Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

phaser: test the pane's server on a real Vite; fix symlinked workspaces, outside files and % names

dee993b7464c5b3
diff --git a/store/agents/phaser/README.md b/store/agents/phaser/README.md
index 30bfd4373..a056d8692 100644
--- a/store/agents/phaser/README.md
+++ b/store/agents/phaser/README.md
@@ -59,5 +59,6 @@ the wrapper belong here, and a newer Phaser is a bump of `package.json`, `templa
```sh
harness dsh check . # conformance
harness dsh install "$PWD" --link # this checkout as the installed agent
-python3 -m unittest discover -s toolchain # the verdict's judge, without vite
+python3 -m unittest discover -s toolchain # the verdict's judge and the scripts, without vite
+node --test 'test/*.test.mjs' # the pane's server on a real Vite (after setup)
```
diff --git a/store/agents/phaser/package.json b/store/agents/phaser/package.json
index 8bf471fe2..564299079 100644
--- a/store/agents/phaser/package.json
+++ b/store/agents/phaser/package.json
@@ -4,6 +4,9 @@
"description": "Phaser as a Harness agent: one node_modules for every workspace, a Vite dev server as the pane",
"license": "MIT",
"type": "module",
+ "scripts": {
+ "test": "python3 -m unittest discover -s toolchain && node --test 'test/*.test.mjs'"
+ },
"dependencies": {
"phaser": "4.2.1"
},
diff --git a/store/agents/phaser/test/viewer.test.mjs b/store/agents/phaser/test/viewer.test.mjs
new file mode 100644
index 000000000..322d5da48
--- /dev/null
+++ b/store/agents/phaser/test/viewer.test.mjs
@@ -0,0 +1,312 @@
+// node --test test/ — the pane's server (viewer.mjs) on a real Vite, over a tiny workspace.
+//
+// Needs the package's node_modules (toolchain/setup.sh); skips without it. The workspace is reached
+// through a symlink, as a workspace under /tmp or a linked folder is. Its own vite.config.mjs adds a
+// test route that sends payloads through Vite's hot channel the way any plugin can, so every shape
+// the frame is told about is checked, alongside the reloads, updates and errors Vite makes itself.
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import http from 'node:http'
+import { createServer } from 'node:net'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { after, before, describe, test } from 'node:test'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), '..')
+const HAS_VITE = existsSync(join(PKG, 'node_modules', 'vite', 'package.json'))
+
+const CONFIG = `
+export default {
+ cacheDir: '.vite',
+ logLevel: 'silent',
+ optimizeDeps: { noDiscovery: true, include: [] },
+ plugins: [{
+ name: 'test-seam',
+ configureServer(server) {
+ server.middlewares.use((req, res, next) => {
+ const url = new URL(req.url, 'http://127.0.0.1')
+ try {
+ if (url.pathname === '/__test/send') server.environments.client.hot.send(...JSON.parse(url.searchParams.get('args')))
+ else if (url.pathname === '/__test/watch') server.watcher.add(url.searchParams.get('path'))
+ else return next()
+ res.end('ok')
+ } catch (error) { res.statusCode = 500; res.end(String(error)) }
+ })
+ },
+ }],
+}
+`
+
+function freePort() {
+ return new Promise((resolve, reject) => {
+ const probe = createServer()
+ probe.on('error', reject)
+ probe.listen(0, '127.0.0.1', () => { const { port } = probe.address(); probe.close(() => resolve(port)) })
+ })
+}
+
+function get(port, path) {
+ return new Promise((resolve, reject) => {
+ http.get({ host: '127.0.0.1', port, path }, (res) => {
+ const chunks = []
+ res.on('data', (c) => chunks.push(c))
+ res.on('end', () => resolve({ status: res.statusCode, type: res.headers['content-type'], body: Buffer.concat(chunks).toString('utf8') }))
+ }).on('error', reject)
+ })
+}
+
+/** An EventSource, by hand: every `event:` block parsed, every `:` comment kept. */
+function stream(port) {
+ return new Promise((resolve, reject) => {
+ const req = http.get({ host: '127.0.0.1', port, path: '/__harness/events' }, (res) => {
+ const client = { headers: res.headers, events: [], comments: [], close: () => req.destroy() }
+ let buffer = ''
+ res.setEncoding('utf8')
+ res.on('data', (chunk) => {
+ buffer += chunk
+ for (let i = buffer.indexOf('\n\n'); i >= 0; i = buffer.indexOf('\n\n')) {
+ const block = buffer.slice(0, i)
+ buffer = buffer.slice(i + 2)
+ if (block.startsWith(':')) client.comments.push(block)
+ else client.events.push({ event: /^event: (.*)$/m.exec(block)[1], data: JSON.parse(/^data: (.*)$/m.exec(block)[1]) })
+ }
+ })
+ resolve(client)
+ })
+ req.on('error', (error) => { if (error.code !== 'ECONNRESET') reject(error) })
+ })
+}
+
+async function waitFor(check, what, ms = 10_000) {
+ const start = Date.now()
+ for (;;) {
+ const value = check()
+ if (value) return value
+ if (Date.now() - start > ms) throw new Error(`timed out waiting for ${what}`)
+ await sleep(25)
+ }
+}
+
+describe('viewer.mjs', { skip: !HAS_VITE && 'no node_modules — run toolchain/setup.sh' }, () => {
+ let root, real, ws, outside, port, child, output = '', exited, events, pinged
+
+ const send = (...args) => get(port, `/__test/send?args=${encodeURIComponent(JSON.stringify(args))}`)
+ const after_ = (n) => events.events.slice(n)
+ /** Send, then a sentinel reload, and return what the frame was told in between. */
+ async function told(...args) {
+ const mark = events.events.length
+ await send(...args)
+ await send({ type: 'full-reload', path: '/sentinel' })
+ await waitFor(() => after_(mark).some((e) => e.data.path === '/sentinel'), 'the sentinel')
+ return after_(mark).filter((e) => e.data.path !== '/sentinel')
+ }
+
+ before(async () => {
+ root = realpathSync(mkdtempSync(join(tmpdir(), 'phaser-viewer-')))
+ real = join(root, 'game')
+ ws = join(root, 'game-link')
+ outside = join(root, 'shared')
+ const files = {
+ 'index.html': '<!doctype html>\n<html><head><title>game</title></head><body><script type="module" src="/src/main.js"></script></body></html>\n',
+ 'vite.config.mjs': CONFIG,
+ 'src/main.js': 'export const main = 1\n',
+ 'src/hot.js': 'export const hot = 1\nif (import.meta.hot) import.meta.hot.accept()\n',
+ 'src/broken.js': "import missing from 'missing-module'\nexport default missing\n",
+ 'src/100%.js': 'export const percent = 100\n',
+ 'src/data.bin': 'binary',
+ 'src/big.json': `"${'x'.repeat(2_000_001)}"`,
+ '..odd.js': 'export const odd = 1\n',
+ // A stand-in Phaser for the probe to import. Never the package's real node_modules: Vite writes
+ // its bundled config into the workspace's node_modules/.vite-temp, and that install is shared.
+ 'node_modules/phaser/package.json': '{ "name": "phaser", "version": "0.0.0", "type": "module", "main": "index.js" }\n',
+ 'node_modules/phaser/index.js': 'export default { Game: class {} }\n',
+ }
+ for (const [rel, text] of Object.entries(files)) {
+ mkdirSync(dirname(join(real, rel)), { recursive: true })
+ writeFileSync(join(real, rel), text)
+ }
+ mkdirSync(join(real, 'src', 'folder.js'))
+ mkdirSync(outside)
+ writeFileSync(join(outside, 'lib.js'), 'export const shared = 1\n')
+ symlinkSync(real, ws)
+
+ port = await freePort()
+ child = spawn(process.execPath, [join(PKG, 'viewer.mjs')], {
+ env: { ...process.env, HARNESS_VIEWER_PORT: String(port), HARNESS_WORKSPACE: ws },
+ stdio: ['ignore', 'pipe', 'pipe'],
+ })
+ child.stdout.on('data', (c) => { output += c })
+ child.stderr.on('data', (c) => { output += c })
+ exited = new Promise((resolve) => child.on('exit', (code, signal) => resolve({ code, signal })))
+ await waitFor(() => output.includes('listening on'), 'the viewer to listen', 30_000)
+ events = await stream(port)
+ await waitFor(() => events.events.length, 'hello')
+ // The keep-alive comes every 20 s; start waiting now so the suite pays for it once.
+ pinged = waitFor(() => events.comments.length, 'a keep-alive ping', 30_000)
+ })
+
+ after(async () => {
+ events?.close()
+ if (child && child.exitCode === null) { child.kill('SIGTERM'); await exited }
+ rmSync(root, { recursive: true, force: true })
+ })
+
+ test('says where it listens and greets each stream with the workspace name', () => {
+ assert.match(output, new RegExp(`\\[phaser\\] listening on http://127\\.0\\.0\\.1:${port}/ \\(workspace: `))
+ assert.equal(events.headers['content-type'], 'text/event-stream')
+ assert.equal(events.headers['cache-control'], 'no-store')
+ assert.deepEqual(events.events[0].event, 'hello')
+ assert.match(events.events[0].data.workspace, /^game(-link)?$/)
+ })
+
+ test('/ is the frame; /?game is the game page with the guard first and the probe injected', async () => {
+ const frame = await get(port, '/')
+ assert.equal(frame.status, 200)
+ assert.equal(frame.type, 'text/html; charset=utf-8')
+ assert.equal(frame.body, readFileSync(join(PKG, 'viewer', 'frame.html'), 'utf8'))
+
+ const game = await get(port, '/?game')
+ assert.equal(game.status, 200)
+ const guard = readFileSync(join(PKG, 'viewer', 'guard.js'), 'utf8')
+ assert.ok(game.body.includes(guard.trim()), 'the guard is inlined')
+ assert.ok(game.body.indexOf(guard.trim()) < game.body.indexOf('<title>'), 'the guard runs before anything in <head>')
+ assert.match(game.body, /<script type="module" src="\/@harness\/probe\.js"><\/script>/)
+ })
+
+ test('the probe module is served from the frame, never from the workspace', async () => {
+ const probe = await get(port, '/@harness/probe.js')
+ assert.equal(probe.status, 200)
+ assert.match(probe.body, /__harnessPatched/)
+ })
+
+ test('/__harness/<asset> serves the frame\'s own files and nothing else', async () => {
+ const css = await get(port, '/__harness/frame.css')
+ assert.equal(css.status, 200)
+ assert.equal(css.type, 'text/css; charset=utf-8')
+ assert.equal((await get(port, '/__harness/frame.js')).type, 'text/javascript; charset=utf-8')
+ for (const path of ['/__harness/', '/__harness/missing.js', '/__harness/logo.png', '/__harness/..%2Fviewer.mjs']) {
+ assert.equal((await get(port, path)).status, 404, path)
+ }
+ // An encoded `..` is collapsed by the URL parser: the request leaves /__harness/ and Vite answers
+ // with the game page, as it does for any unknown path — never with the server's own files.
+ const escape = await get(port, '/__harness/%2e%2e/viewer.mjs')
+ assert.doesNotMatch(escape.body, /createServer/)
+ assert.match(escape.body, /<title>game<\/title>/)
+ })
+
+ test('/__harness/source reads workspace source files, however the error named them', async () => {
+ const main = 'export const main = 1\n'
+ for (const path of [
+ 'src/main.js',
+ `http://127.0.0.1:${port}/src/main.js?t=123#L1`,
+ `/@fs${real}/src/main.js`,
+ ]) {
+ const res = await get(port, `/__harness/source?path=${encodeURIComponent(path)}`)
+ assert.deepEqual([res.status, res.type, res.body], [200, 'text/plain; charset=utf-8', main], path)
+ }
+ // A name with a percent sign: the query decodes once, and the file is still found.
+ const percent = await get(port, `/__harness/source?path=${encodeURIComponent('src/100%.js')}`)
+ assert.deepEqual([percent.status, percent.body], [200, 'export const percent = 100\n'])
+ })
+
+ test('/__harness/source refuses what is not a workspace source file', async () => {
+ for (const path of [null, '../shared/lib.js', `${outside}/lib.js`, 'src/data.bin', 'src/missing.js', 'src/folder.js', 'src/big.json']) {
+ const query = path === null ? '' : `?path=${encodeURIComponent(path)}`
+ assert.equal((await get(port, `/__harness/source${query}`)).status, 404, String(path))
+ }
+ })
+
+ test('a file saved in the workspace is a change; output, the verdict and files outside are not', async () => {
+ await get(port, `/__test/watch?path=${encodeURIComponent(join(outside, 'lib.js'))}`)
+ await sleep(300)
+ const mark = events.events.length
+ writeFileSync(join(outside, 'lib.js'), 'export const shared = 2\n')
+ mkdirSync(join(ws, 'out'), { recursive: true })
+ writeFileSync(join(ws, 'out', 'bundle.js'), '1')
+ mkdirSync(join(ws, '.harness'), { recursive: true })
+ writeFileSync(join(ws, '.harness', 'verdict.json'), '{}')
+ await sleep(300)
+ writeFileSync(join(ws, 'src', 'added.js'), 'export const added = 1\n')
+ await waitFor(() => after_(mark).some((e) => e.event === 'change' && e.data.file === 'src/added.js'), 'the change')
+ await sleep(500)
+ const changes = after_(mark).filter((e) => e.event === 'change').map((e) => e.data)
+ assert.deepEqual(changes, [{ event: 'add', file: 'src/added.js' }])
+ })
+
+ test('a workspace file whose name starts with two dots is still a workspace file', async () => {
+ const mark = events.events.length
+ writeFileSync(join(ws, '..odd.js'), 'export const odd = 2\n')
+ const change = await waitFor(() => after_(mark).find((e) => e.event === 'change'), 'the change')
+ assert.deepEqual(change.data, { event: 'change', file: '..odd.js' })
+ })
+
+ test('a module with no HMR boundary reloads the page, named by its workspace path', async () => {
+ assert.equal((await get(port, '/src/main.js')).status, 200)
+ const mark = events.events.length
+ writeFileSync(join(ws, 'src', 'main.js'), 'export const main = 2\n')
+ const reload = await waitFor(() => after_(mark).find((e) => e.event === 'reload'), 'the reload')
+ assert.deepEqual(reload.data, { file: 'src/main.js', path: null })
+ })
+
+ test('a self-accepting module is an update', async () => {
+ assert.equal((await get(port, '/src/hot.js')).status, 200)
+ const mark = events.events.length
+ writeFileSync(join(ws, 'src', 'hot.js'), 'export const hot = 2\nif (import.meta.hot) import.meta.hot.accept()\n')
+ const update = await waitFor(() => after_(mark).find((e) => e.event === 'update'), 'the update')
+ assert.deepEqual(update.data, { files: ['src/hot.js'] })
+ })
+
+ test('an import that does not resolve is a build error with its workspace file, line and frame', async () => {
+ const mark = events.events.length
+ assert.equal((await get(port, '/src/broken.js')).status, 500)
+ const error = await waitFor(() => after_(mark).find((e) => e.event === 'build-error'), 'the build error')
+ assert.equal(error.data.file, 'src/broken.js')
+ assert.equal(error.data.line, 1)
+ assert.equal(error.data.plugin, 'vite:import-analysis')
+ assert.match(error.data.message, /missing-module/)
+ assert.match(error.data.frame, /import missing/)
+ assert.doesNotMatch(error.data.message + error.data.frame, /\x1b/)
+ const source = await get(port, `/__harness/source?path=${encodeURIComponent(error.data.file)}`)
+ assert.equal(source.status, 200, 'the frame can show the code around the error')
+ })
+
+ test('payload shapes other plugins send', async () => {
+ assert.deepEqual(await told({ type: 'full-reload' }), [{ event: 'reload', data: { file: null, path: null } }])
+ assert.deepEqual(await told({ type: 'update' }), [{ event: 'update', data: { files: [] } }])
+ assert.deepEqual(await told({ type: 'update', updates: [{ path: '/src/a.js?t=1' }, { path: 'src/a.js' }, {}] }),
+ [{ event: 'update', data: { files: ['src/a.js', null] } }])
+ assert.deepEqual(await told({ type: 'error', err: { message: '\x1b[31mboom\x1b[39m', id: `${real}/src/x.js?import`, frame: '\x1b[33m> 1 |\x1b[39m', plugin: 'p' } }),
+ [{ event: 'build-error', data: { message: 'boom', file: 'src/x.js', line: null, column: null, frame: '> 1 |', plugin: 'p' } }])
+ assert.deepEqual(await told({ type: 'error', err: { message: 'm', loc: { file: join(outside, 'lib.js'), line: 3, column: 4 } } }),
+ [{ event: 'build-error', data: { message: 'm', file: join(outside, 'lib.js'), line: 3, column: 4, frame: '', plugin: null } }])
+ assert.deepEqual(await told({ type: 'error' }),
+ [{ event: 'build-error', data: { message: 'Build error', file: null, line: null, column: null, frame: '', plugin: null } }])
+ // Custom events, junk, and a payload that breaks the reader: the frame hears nothing, Vite still sends.
+ assert.deepEqual(await told('my-plugin:event', { a: 1 }), [])
+ assert.deepEqual(await told({ type: 'connected' }), [])
+ assert.deepEqual(await told({ type: 'update', updates: [null] }), [])
+ assert.deepEqual(await told(null), [])
+ })
+
+ test('a stream that closes is forgotten', async () => {
+ const second = await stream(port)
+ await waitFor(() => second.events.length, 'hello on the second stream')
+ second.close()
+ await sleep(200)
+ assert.deepEqual(await told({ type: 'full-reload', path: '/after-close' }), [{ event: 'reload', data: { file: null, path: '/after-close' } }])
+ })
+
+ test('keeps each stream alive with a comment ping', async () => {
+ await pinged
+ assert.equal(events.comments[0], ': ping')
+ })
+
+ // SIGTERM is Vite's own (it closes and exits 143); Ctrl-C in a terminal is the viewer's.
+ test('stops cleanly on SIGINT', async () => {
+ child.kill('SIGINT')
+ assert.deepEqual(await exited, { code: 0, signal: null })
+ })
+})
diff --git a/store/agents/phaser/viewer.mjs b/store/agents/phaser/viewer.mjs
index 6bda011d5..3a235d260 100644
--- a/store/agents/phaser/viewer.mjs
+++ b/store/agents/phaser/viewer.mjs
@@ -10,14 +10,16 @@
// routes above and injects two small scripts into the game page: a guard (runtime errors, before
// anything else runs) and a probe (finds the Phaser.Game so the frame can pause, debug, restart).
// Nothing is written into the workspace; `vite build` and a standalone `npm run dev` never see it.
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { dirname, extname, join, normalize, relative, resolve, sep } from 'node:path'
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
import { fileURLToPath } from 'node:url'
import { createServer } from 'vite'
const here = dirname(fileURLToPath(import.meta.url))
const port = Number(process.env.HARNESS_VIEWER_PORT)
-const workspace = resolve(process.env.HARNESS_WORKSPACE)
+// The real path: Vite names modules by it, so a workspace reached through a symlink (under /tmp, or
+// a linked folder) would otherwise match none of its own files — no HMR, no code frames.
+const workspace = realpathSync(resolve(process.env.HARNESS_WORKSPACE))
const ASSETS = join(here, 'viewer')
const PROBE_ID = '/@harness/probe.js'
const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml' }
@@ -30,13 +32,15 @@ function broadcast(event, data) {
}
function rel(file) {
- const r = relative(workspace, resolve(workspace, String(file ?? '')))
- return r.startsWith('..') ? String(file ?? '') : r.split(sep).join('/')
+ const r = relative(workspace, resolve(workspace, String(file)))
+ return (r + sep).startsWith(`..${sep}`) ? String(file) : r.split(sep).join('/')
}
/** A workspace path from an error payload or a URL, or null when it leaves the workspace. */
function inWorkspace(raw) {
- const clean = decodeURIComponent(String(raw ?? '').replace(/^https?:\/\/[^/]+/, '').replace(/[?#].*$/, '').replace(/^\/@fs/, ''))
+ const path = String(raw ?? '').replace(/^https?:\/\/[^/]+/, '').replace(/[?#].*$/, '').replace(/^\/@fs/, '')
+ let clean = path
+ try { clean = decodeURIComponent(path) } catch { /* a name with a real `%` in it, already decoded */ }
const full = normalize(clean.startsWith(workspace) ? clean : join(workspace, clean.replace(/^\/+/, '')))
return full.startsWith(workspace + sep) ? full : null
}
@@ -80,19 +84,19 @@ function harness() {
},
},
configureServer(server) {
- const hot = server.environments?.client?.hot ?? server.ws
+ const hot = server.environments.client.hot
const send = hot.send.bind(hot)
hot.send = (...args) => {
try { observe(typeof args[0] === 'string' ? { type: 'custom', event: args[0], data: args[1] } : args[0]) } catch { /* the frame is a spectator */ }
return send(...args)
}
server.watcher.on('all', (event, file) => {
- const r = rel(file)
- if (r.startsWith('..') || /^(out|\.vite|\.harness|node_modules|\.git)(\/|$)/.test(r)) return
+ const r = rel(file) // the watcher's paths are absolute, so one left absolute is outside
+ if (isAbsolute(r) || /^(out|\.vite|\.harness|node_modules|\.git)(\/|$)/.test(r)) return
broadcast('change', { event, file: r })
})
server.middlewares.use((req, res, next) => {
- const url = new URL(req.url ?? '/', 'http://127.0.0.1')
+ const url = new URL(req.url, 'http://127.0.0.1')
const path = url.pathname
if (path === '/' && !url.searchParams.has('game')) return asset(res, 'frame.html')
if (!path.startsWith('/__harness/')) return next()
@@ -121,8 +125,9 @@ function harness() {
function asset(res, name) {
const full = normalize(join(ASSETS, name))
- if (!full.startsWith(ASSETS + sep) || !existsSync(full) || !statSync(full).isFile()) { res.writeHead(404); res.end('not found'); return }
- res.writeHead(200, { 'content-type': TYPES[extname(full)] ?? 'application/octet-stream', 'cache-control': 'no-store' })
+ const type = TYPES[extname(full)]
+ if (!type || !full.startsWith(ASSETS + sep) || !existsSync(full) || !statSync(full).isFile()) { res.writeHead(404); res.end('not found'); return }
+ res.writeHead(200, { 'content-type': type, 'cache-control': 'no-store' })
res.end(readFileSync(full))
}