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.

7.2 KB
Raw Blame
// The Phaser pane: Vite's dev server on the workspace, wrapped in a game frame.
//
//   GET /                      the frame — toolbar, device presets, debug, errors — around an iframe
//   GET /index.html            the game itself, served and hot-reloaded by Vite as always
//   GET /__harness/<asset>     the frame's own files (viewer/), never the workspace's
//   GET /__harness/events      server-sent events: file changes, Vite's reloads, updates and errors
//   GET /__harness/source      ?path= a workspace source file as text, for an error's code frame
//
// Vite runs in-process with the workspace's own vite.config.mjs, plus one plugin that adds the
// 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, 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)
// 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' }
const SOURCE = new Set(['.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx', '.json', '.html', '.css', '.glsl', '.frag', '.vert'])
const clients = new Set()

function broadcast(event, data) {
  const line = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
  for (const client of clients) client.write(line)
}

function rel(file) {
  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 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
}

/** What the frame needs from a Vite payload: reloads, updates and errors, with workspace paths. */
function observe(payload) {
  if (!payload || typeof payload !== 'object') return
  if (payload.type === 'full-reload') {
    broadcast('reload', { file: payload.triggeredBy ? rel(payload.triggeredBy) : null, path: payload.path ?? null })
  } else if (payload.type === 'update') {
    broadcast('update', { files: [...new Set((payload.updates ?? []).map((u) => u.path?.replace(/^\/+/, '').replace(/\?.*$/, '')))] })
  } else if (payload.type === 'error') {
    const err = payload.err ?? {}
    const file = err.loc?.file ?? err.id ?? null
    broadcast('build-error', {
      message: String(err.message ?? 'Build error').replace(/\x1b\[[0-9;]*m/g, ''),
      file: file ? rel(String(file).replace(/\?.*$/, '')) : null,
      line: err.loc?.line ?? null,
      column: err.loc?.column ?? null,
      frame: String(err.frame ?? '').replace(/\x1b\[[0-9;]*m/g, ''),
      plugin: err.plugin ?? null,
    })
  }
}

const GUARD = readFileSync(join(ASSETS, 'guard.js'), 'utf8')

function harness() {
  return {
    name: 'harness-frame',
    apply: 'serve',
    resolveId(id) { return id === PROBE_ID ? '\0harness-probe' : null },
    load(id) { return id === '\0harness-probe' ? readFileSync(join(ASSETS, 'probe.js'), 'utf8') : null },
    transformIndexHtml: {
      order: 'pre',
      handler() {
        return [
          { tag: 'script', children: GUARD, injectTo: 'head-prepend' },
          { tag: 'script', attrs: { type: 'module', src: PROBE_ID }, injectTo: 'head' },
        ]
      },
    },
    configureServer(server) {
      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) // 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 path = url.pathname
        if (path === '/' && !url.searchParams.has('game')) return asset(res, 'frame.html')
        if (!path.startsWith('/__harness/')) return next()
        const name = path.slice('/__harness/'.length)
        if (name === 'events') {
          res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' })
          res.write(`event: hello\ndata: ${JSON.stringify({ workspace: workspace.split(sep).pop() })}\n\n`)
          clients.add(res)
          req.on('close', () => clients.delete(res))
          return
        }
        if (name === 'source') {
          const full = inWorkspace(url.searchParams.get('path'))
          if (!full || !SOURCE.has(extname(full).toLowerCase()) || !existsSync(full) || !statSync(full).isFile() || statSync(full).size > 2_000_000) {
            res.writeHead(404); res.end('not found'); return
          }
          res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' })
          res.end(readFileSync(full))
          return
        }
        return asset(res, name)
      })
    },
  }
}

function asset(res, name) {
  const full = normalize(join(ASSETS, name))
  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))
}

const server = await createServer({
  root: workspace,
  clearScreen: false,
  plugins: [harness()],
  // The frame shows build errors itself, readably and outside the game; Vite's overlay would sit
  // inside the scaled game and cover it.
  server: { host: '127.0.0.1', port, strictPort: true, hmr: { overlay: false } },
})
await server.listen()
console.log(`[phaser] listening on http://127.0.0.1:${port}/ (workspace: ${workspace})`)
setInterval(() => { for (const c of clients) c.write(': ping\n\n') }, 20_000).unref()
for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => { server.close().finally(() => process.exit(0)) })