@joystack/cli 0.1.54 → 0.1.56

package/lib/static-server.mjs

@@ -5,6 +5,7 @@
 //   /shared/…         → the engine bundle's shared/ tree
 //   /__reload         → SSE; tells open tabs the version they run on is replaced
 //   /__joystack/dev   → the versions' state; reload, and auto-reload on or off
+//   /__joystack/warm/<slug>/ → a page that downloads the game's start ahead of it
 //
 // Mounts are ORDERED — first prefix match wins. That ordering is how
 // overrides/shared/… will shadow the engine bundle (Slice 2): the game's
@@ -17,8 +18,11 @@ import { readFileSync, readdirSync, statSync, existsSync, realpathSync } from 'n
 import { extname, join, normalize, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
-import { injectHeadTags, injectNoteTag, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL, DEVTOOLS_URL, ENGINE_TOOLS_URL, POINT_URL } from './inject.mjs';
+import { injectHeadTags, injectNoteTag, stampedKinds, rewriteHtmlScripts, rewriteJsImports, NOTE_URL, PLATFORM_URL, TOOLBOX_URL, DEVTOOLS_URL, ENGINE_TOOLS_URL, POINT_URL } from './inject.mjs';
+import { cacheHeaders, closureStamps, declaredAssets, freshOfRequest, freshToken, notModified, splitStamp, stampValue, startFiles, WARM_PAGE, WARM_PATH } from './fingerprint/fingerprint.mjs';
 import { createRelay, RELAY_PATH } from './relay/relay.mjs';
+import { createStartFailed, START_FAILED_PATH } from './start-failed.mjs';
+import { MIME } from './mime.mjs';
 import { WHOAMI_PATH } from './ports.mjs';
 import {
   writeSegment, stitchStream, streamDir, listRecordings, latestRecording, deleteRecording, setKept,
@@ -27,6 +31,7 @@ import {
 import { gameBuild } from './build-id.mjs';
 import { createHistory, checkPath, HISTORY_PATH, HistoryError } from './history.mjs';
 import { STATE_DIR_NAMES, canonicalDevPath, stateDir, stateDirName, withLegacyImportMap } from './legacy-names.mjs';
+import { reloadClient } from './reload-client.mjs';
 
 // `?replay=<id>` resolves to `.joystack/replays/<id>.json` (replaySourceUrl in the
 // engine's replay transport). Nothing writes that FILE — the room writes the
@@ -50,48 +55,6 @@ const REPLAY_URL_RE = new RegExp(`^/games/[^/]+/(?:${STATE_DIRS_RE})/replays/([a
 // one of them carries a dash and none of them is a word.
 const LATEST_ALIAS = 'last';
 
-// The page's half of /__reload, under `joystack dev` (live-versions.mjs). Every
-// page the server serves belongs to one version of the game, and leaves when
-// that version stops being the one served:
-//
-//   game    a game page. It reloads as soon as an update starts, so no game
-//           runs while files are replaced; the server answers it with the
-//           "Updating…" page, then the game.
-//   status  the "Updating…" or error page. It reloads when a version is ready.
-//   other   any other page (the Assets page). It reloads once the new version
-//           is served.
-//
-// The stream sends `reload` after every switch, and the status (JSON) on
-// connecting and whenever it changes. A page whose version is not the one in
-// the status reloads at once: it was served just before a switch.
-const reloadClient = (kind, version, token) => `<script>
-(() => {
-  const kind = ${JSON.stringify(kind)};
-  const version = ${JSON.stringify(version)};
-  let alive = false;
-  let leaving = false;
-  const leave = () => { if (!leaving) { leaving = true; location.reload(); } };
-  function connect() {
-    const es = new EventSource('/__reload?page=' + kind + '&token=${token}');
-    es.onopen = () => { alive = true; };
-    es.onmessage = (e) => {
-      if (e.data === 'reload') return leave();
-      let s;
-      try { s = JSON.parse(e.data); } catch { return; }
-      if (kind === 'game' && (s.state !== 'ready' || s.version !== version)) return leave();
-      if (kind === 'status' && s.state === 'ready') return leave();
-      if (kind === 'status') window.dispatchEvent(new CustomEvent('joystack-status', { detail: s }));
-    };
-    es.onerror = () => {
-      es.close();
-      setTimeout(connect, alive ? 200 : 1000);
-      alive = false;
-    };
-  }
-  connect();
-})();
-</script>`;
-
 // The one line of a failed build a person needs: the first error it reports,
 // with the game's paths written from the game folder and the build's own
 // location left off. The whole error stays in the terminal and in
@@ -100,8 +63,13 @@ export function errorSummary(text, gameDir = null) {
   const lines = String(text ?? '').split('\n').map((l) => l.trim()).filter(Boolean)
     // Node's own warnings ride along on the build's output.
     .filter((l) => !/^\(node:\d+\)|^\(Use `node --trace-warnings|^Reparsing as ES module|^To eliminate this warning|package\.json\.$/.test(l));
-  const first = lines.find((l) => l.startsWith('✘')) ?? lines.find((l) => /error|cannot|not defined|unexpected/i.test(l)) ?? lines[0] ?? '';
-  let line = first.replace(/^✘\s*/, '').replace(/^\S+:\d+(?::\d+)?\s+—\s+/, '').replace(/^Expansion threw:\s*/, '');
+  // A gate refusal first; then the error a build that threw printed (Node
+  // prints the line of code that threw above it, which says "Error" too);
+  // then any line that reads like one.
+  const first = lines.find((l) => l.startsWith('✘'))
+    ?? lines.find((l) => /^(?:[A-Z]\w*)?Error:\s/.test(l))
+    ?? lines.find((l) => /error|cannot|not defined|unexpected/i.test(l)) ?? lines[0] ?? '';
+  let line = first.replace(/^✘\s*/, '').replace(/^\S+:\d+(?::\d+)?\s+—\s+/, '').replace(/^Expansion threw:\s*/, '').replace(/^Error:\s+/, '');
   if (gameDir) {
     // Any absolute path into the game folder, however it is spelled: with
     // either separator, a drive letter, /private on macOS, or a Windows short
@@ -210,8 +178,9 @@ function trustedHost(header, shareHost = null) {
 // gives an attacker both halves at once (see trustedHost).
 //
 // `requireOrigin` turns the absent-header case from pass into fail, and is what
-// separates "a page this server served" from "any program that can reach this
-// port". A browser attaches Origin to every request whose method is not GET or
+// separates "a page this server served" from a program that sends no Origin.
+// It does not stop a program on this machine, which can write any Origin and
+// Host it likes; only a browser is bound by them. A browser attaches Origin to every request whose method is not GET or
 // HEAD, same-origin ones included — so on the MUTATING verbs the header is free
 // to demand and refuses every non-browser caller. A GET cannot demand it: a
 // same-origin GET carries no Origin either, so the game page fetching its own
@@ -242,6 +211,12 @@ function devtoolsRide({ shared, shareIsOwner, carried }) {
   return carried && (!shared || shareIsOwner);
 }
 
+// The pages that may frame one of this server's: its own, under either
+// loopback name, on its own port alone.
+export function frameAncestors(port) {
+  return port ? `frame-ancestors 'self' http://localhost:${port} http://127.0.0.1:${port}` : "frame-ancestors 'self'";
+}
+
 // Whether a Host header names the shared tunnel hostname (with or without a port).
 function isShareHost(header, shareHost) {
   return !!shareHost && String(header ?? '').replace(/:\d+$/, '').toLowerCase() === shareHost;
@@ -255,34 +230,6 @@ function shareGuestIdentity() {
   return { userId: `dev-share-${id}`, name: `guest-${id.slice(0, 4)}`, color: '#a3e635' };
 }
 
-const MIME = {
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.wasm': 'application/wasm',
-  '.mp3': 'audio/mpeg',
-  '.ogg': 'audio/ogg',
-  '.wav': 'audio/wav',
-  '.m4a': 'audio/mp4',
-  '.flac': 'audio/flac',
-  '.txt': 'text/plain; charset=utf-8',
-  '.md': 'text/markdown; charset=utf-8',
-  '.woff': 'font/woff',
-  '.woff2': 'font/woff2',
-  '.glb': 'model/gltf-binary',
-  '.gltf': 'model/gltf+json',
-  '.bin': 'application/octet-stream',
-};
-
 export function createStaticServer({
   slug,
   mounts,
@@ -314,8 +261,10 @@ export function createStaticServer({
   // this machine wakes that session, and the note rides on every page.
   agentSession = null,
   // Whether a request through the share link is the creator's own (startDev's
-  // `shareIsOwner`): its relay events then count as from this machine.
+  // `shareIsOwner`): its relay requests then count as from this machine.
   shareIsOwner = false,
+  // The relay's feed for Claude Code (relay/relay.mjs); off in the maker.
+  agentFeed = true,
 }) {
   // The tunnel hostname `joystack dev --share` opened to this server, once it is
   // up (setShareHost). See trustedHost.
@@ -327,13 +276,12 @@ export function createStaticServer({
   // The creator's own browser: on this machine, or through a share link that
   // only the creator can reach the dev tools by.
   const fromCreator = (req) => fromThisMachine(req) || (shareIsOwner && isShareHost(req.headers.host, shareHost));
-  // The relay's hub (relay/relay.mjs): events between the pages this server
-  // serves and the agent. Without a projectDir there is no game to relay for
-  // and the routes do not exist.
+  // The relay's dev server end (relay/relay.mjs), run from the engine's own
+  // relay. Without a projectDir there is no game to relay for and the
+  // routes do not exist.
   const relay = projectDir ? createRelay({
-    projectDir, agentSession, log, cliBin: CLI_BIN,
-    sameOrigin: (req) => sameOrigin(req, { shareHost }),
-    fromCreator,
+    projectDir, agentSession, log, cliBin: CLI_BIN, sharedDir: () => engineSharedDir, feed: agentFeed,
+    sameOrigin: (req, opts) => sameOrigin(req, { ...opts, shareHost }), fromCreator,
   }) : null;
   // The laptop note (NOTE_URL) rides on every page the creator opens, when
   // the coding-agent session that started this server is there to be woken.
@@ -363,7 +311,7 @@ export function createStaticServer({
     }
     // The state folder (`.joystack/`) is the game's private working directory, not part of the site.
     // It holds the relay's files (the notes the creator sent the agent, with
-    // their pictures, and the hub's bearer token) and the recorded sessions (which carry every player's entity seed, every
+    // their pictures, and the relay's bearer token for the agent) and the recorded sessions (which carry every player's entity seed, every
     // non-replicated field, and every participant's account id — strictly more
     // than any single live client is ever sent). This server binds every
     // interface and stamps `Access-Control-Allow-Origin: *`, so serving that
@@ -452,14 +400,53 @@ export function createStaticServer({
 
   const gameEntry = `/games/${slug}/index.html`;
 
+  // The page in place of the game while it updates or after its build failed.
+  // A failed build answers as an error, so a check that fetches the page (an
+  // agent's curl, a test) sees it failed; a browser still shows it. The
+  // header says why, so a proxy that passes the page on (the maker's live
+  // links) can answer it as the page it is rather than its own 5xx.
+  function sendStatus(res, status) {
+    const failed = status.state === 'failed';
+    return sendBody(res, failed ? 500 : 200, statusPage(status, projectDir) + reloadClient('status', currentVersion, 0), MIME['.html'], failed ? { 'x-joystack-build': 'failed' } : {});
+  }
+
   function serveHtml(req, res, fsPath, urlPath, query) {
     const gamePage = /^\/games\/[^/]+\//.test(urlPath);
     const status = versions?.status();
-    if (gamePage && status && status.state !== 'ready') {
-      return sendBody(res, 200, statusPage(status, projectDir) + reloadClient('status', currentVersion, 0), MIME['.html']);
+    if (gamePage && status && status.state !== 'ready') return sendStatus(res, status);
+    let html = pageHtml(req, fsPath, urlPath, query);
+    const note = wantsNote(req);
+    // Under its stamp: the overlay imports the note by that URL, and a module
+    // loaded under two URLs runs twice.
+    if (note) html = injectNoteTag(html, stamper(freshToken(query?.get('fresh')))(NOTE_URL));
+    // The reload client also carries the relay's announcements (an agent is
+    // there, a note's reply), so a page with the note gets it even from a
+    // server with no versions, which never tells it to reload.
+    if (versions || note) {
+      let token = 0;
+      if (versions && gamePage) {
+        token = nextToken++;
+        gamePages.set(token, { version: currentVersion, connected: false, servedAt: Date.now() });
+      }
+      const client = reloadClient(gamePage ? 'game' : 'other', currentVersion, token);
+      html = html.includes('</body>') ? html.replace('</body>', client + '</body>') : html + client;
     }
+    sendBody(res, 200, html, MIME['.html']);
+  }
+
+  // A page as this server serves it, before the note and the reload client.
+  // `?fresh=<n>` names every stamp `?v=<stamp>.<n>` (fingerprint/, freshToken).
+  // A URL under the shared folders named with its current stamp, and the
+  // page's fresh token; a URL the engine does not carry stays as it is.
+  function stamper(fresh) {
+    const stamps = closureStamps(resolveUrl);
+    return (url) => { const v = stamps.stamp(url); return v ? `${url}?v=${stampValue(v, fresh)}` : url; };
+  }
+
+  function pageHtml(req, fsPath, urlPath, query) {
+    const fresh = freshToken(query?.get('fresh'));
     let html = readFileSync(fsPath, 'utf8');
-    html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl });
+    html = rewriteHtmlScripts(html, { baseUrl: urlPath, resolveUrl, fresh });
     html = withLegacyImportMap(html);
     // Mirror the production /g/<slug> entry injection — only when the resolved
     // engine actually ships the platform layer (transition shim, same as
@@ -490,41 +477,90 @@ export function createStaticServer({
       // and earlier); a newer engine has the dev tools runtime instead.
       // Per-request, so a bundle swap mid-session is honoured.
       const toolbox = !shared && !!resolveUrl(TOOLBOX_URL);
+      const stamp = stamper(fresh);
       html = injectHeadTags(html, m[1], {
+        stamp,
         ...(tabIdentity ? { identity: tabIdentity } : {}),
         toolbox,
         ...devtoolsFor(shared, m[1]),
-        skeleton: currentSkeleton,
+        skeleton: currentSkeleton && stampedKinds(currentSkeleton, urlPath, stamp),
+        fresh,
+        report: START_FAILED_PATH,
         ...(shared ? { shareHost, replay: shareIsOwner } : {}),
       });
     }
-    if (wantsNote(req)) html = injectNoteTag(html);
-    if (versions) {
-      let token = 0;
-      if (gamePage) {
-        token = nextToken++;
-        gamePages.set(token, { version: currentVersion, connected: false, servedAt: Date.now() });
-      }
-      const client = reloadClient(gamePage ? 'game' : 'other', currentVersion, token);
-      html = html.includes('</body>') ? html.replace('</body>', client + '</body>') : html + client;
+    return html;
+  }
+
+  // GET /__joystack/warm/<slug>/            the warm page (WARM_PAGE)
+  // GET /__joystack/warm/<slug>/files.json  { files: [url…] }
+  //
+  // The files the game's start downloads: its page's stamped closure as this
+  // request's page would name it (fingerprint/, startFiles), then the assets
+  // its assets.js declares, which it asks for under their plain URLs. The
+  // page is not a game page: it carries no platform layer, no dev tools, no
+  // recording and no room, and a version switch does not wait for it. While
+  // no version is ready the list is empty.
+  async function serveWarm(req, res, urlPath) {
+    const m = /^\/__joystack\/warm\/([^/]+)\/(files\.json)?$/.exec(urlPath);
+    if (!m || decodeURIComponent(m[1]) !== slug) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      return res.end('404');
     }
-    sendBody(res, 200, html, MIME['.html']);
+    if (!m[2]) return sendBody(res, 200, WARM_PAGE, MIME['.html']);
+    const status = versions?.status();
+    const fsPath = resolveUrl(gameEntry);
+    let files = [];
+    if (fsPath && (!status || status.state === 'ready')) {
+      const html = pageHtml(req, fsPath, gameEntry, new URLSearchParams());
+      const { engineTools = [], gameTools = [] } = devtoolsFor(isShareHost(req.headers.host, shareHost), slug);
+      const plain = [...engineTools, ...gameTools];
+      files = [...startFiles({ html, pageUrl: gameEntry, resolveUrl, plain }), ...(await declaredAssets({ slug, resolveUrl }))];
+    }
+    return sendBody(res, 200, JSON.stringify({ files }), 'application/json');
   }
 
-  function serveJs(res, fsPath, urlPath) {
+  // A module asked for under a fresh address, or by its plain URL from a
+  // fresh page, names its imports with the same token (fingerprint/).
+  function serveJs(req, res, fsPath, urlPath, query) {
     const raw = readFileSync(fsPath);
+    const fresh = splitStamp(query?.get('v')).fresh ?? (query?.has('v') ? null : freshOfRequest(req, query));
     let body;
     try {
-      body = rewriteJsImports(raw.toString('utf8'), { baseUrl: urlPath, resolveUrl });
+      body = rewriteJsImports(raw.toString('utf8'), { baseUrl: urlPath, resolveUrl, fresh });
     } catch {
       body = raw;
     }
-    sendBody(res, 200, body, MIME['.js']);
+    sendFile(req, res, body, MIME['.js'], urlPath, query);
+  }
+
+  // A file of the game or the engine (never a page): kept by the browser for
+  // good under a URL whose stamp is current, otherwise checked with this
+  // server by its tag (fingerprint/).
+  function sendFile(req, res, body, type, urlPath, query) {
+    const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
+    const requested = splitStamp(query?.get('v') ?? null).stamp;
+    const headers = cacheHeaders({ requested, current: requested ? closureStamps(resolveUrl).stamp(urlPath) : null, body: buf });
+    if (headers.ETag && notModified(req, headers.ETag)) {
+      // Closed after: the maker's container proxy (workerd) fails the next
+      // request on a connection that has carried a bodiless 304 ("Container
+      // port connection closed unexpectedly").
+      res.writeHead(304, { ...headers, 'Access-Control-Allow-Origin': '*', Connection: 'close' });
+      return res.end();
+    }
+    res.writeHead(200, {
+      ...headers,
+      'Content-Type': type,
+      'Content-Length': buf.length,
+      'Access-Control-Allow-Origin': '*',
+    });
+    res.end(req.method === 'HEAD' ? undefined : buf);
   }
 
-  function sendBody(res, status, body, type) {
+  function sendBody(res, status, body, type, headers = {}) {
     const buf = Buffer.isBuffer(body) ? body : Buffer.from(body);
     res.writeHead(status, {
+      ...headers,
       'Content-Type': type,
       'Content-Length': buf.length,
       'Cache-Control': 'no-store, must-revalidate',
@@ -532,10 +568,12 @@ export function createStaticServer({
       // Only a page of this server's own may frame one of its pages. The dev
       // tools runtime (shared/ui/devtools/runtime.js) takes the page that
       // frames it as its host: a page on another site that framed it could
-      // write into the game's world and receive every pick. The maker frames
-      // live links from its own origin, which its Worker names in place of
-      // this on every page it passes on.
-      ...(type === MIME['.html'] ? { 'Content-Security-Policy': "frame-ancestors 'self'" } : {}),
+      // write into the game's world and receive every pick. This server
+      // under its other loopback name is listed too: the same files, and the
+      // testbed's relay check frames the game across the two. The maker
+      // frames live links from its own origin, which its Worker names in
+      // place of this on every page it passes on.
+      ...(type === MIME['.html'] ? { 'Content-Security-Policy': frameAncestors(server.address()?.port) } : {}),
     });
     res.end(buf);
   }
@@ -810,7 +848,17 @@ export function createStaticServer({
     return json(200, { stream, deleted: true });
   }
 
-  function handleSse(res, query) {
+  // Whether a reload stream was opened by the creator's own page, served by
+  // this server: only such a stream hears the relay's announcements (an
+  // agent is there, a note's reply). A browser names where a request came
+  // from; a page from another site is refused even where it could not read
+  // the stream.
+  function creatorStream(req) {
+    const site = req.headers['sec-fetch-site'];
+    return fromCreator(req) && sameOrigin(req, { shareHost }) && (site === undefined || site === 'same-origin' || site === 'none');
+  }
+
+  function handleSse(req, res, query) {
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',
@@ -826,8 +874,12 @@ export function createStaticServer({
     keepalive.unref();
     reload.on('reload', push);
     reload.on('status', pushStatus);
+    const stopRelay = relay && creatorStream(req)
+      ? relay.listen((name, data) => res.write(`event: relay\ndata: ${JSON.stringify({ name, data })}\n\n`))
+      : () => {};
     res.on('close', () => {
       clearInterval(keepalive);
+      stopRelay();
       reload.off('reload', push);
       reload.off('status', pushStatus);
       if (page) {
@@ -883,6 +935,21 @@ export function createStaticServer({
     return json(404, { error: 'not found' });
   }
 
+  // A start that failed in a browser, written to the log (start-failed.mjs).
+  const handleStartFailed = createStartFailed({
+    log,
+    // The block reaches the creator's agent: a tester on the share link never
+    // writes one, the creator on their own link (the maker's) does.
+    allowed: (req) => sameOrigin(req, { requireOrigin: true, shareHost }) && (shareIsOwner || !isShareHost(req.headers.host, shareHost)),
+    from: (req) => (isShareHost(req.headers.host, shareHost) ? 'the share link'
+      : fromThisMachine(req) ? 'this machine'
+        : `${String(req.socket.remoteAddress ?? 'another device').replace(/^::ffff:/, '')} on your network`),
+    ownHost: (host) => trustedHost(host, shareHost),
+    slug,
+    projectDir,
+    resolveUrl: (urlPath) => resolveUrl(urlPath),
+  });
+
   // ── model history: the game's files at an earlier commit ────────────────
   //
   //   GET /__joystack/history?path=<p>&path=<p>…   the commits that touched those
@@ -984,7 +1051,13 @@ export function createStaticServer({
   const server = http.createServer((req, res) => {
     const reqUrl = new URL(req.url, 'http://x');
     const urlPath = canonicalDevPath(reqUrl.pathname);
-    if (urlPath === '/__reload') return handleSse(res, reqUrl.searchParams);
+    if (urlPath === '/__reload') return handleSse(req, res, reqUrl.searchParams);
+    if (urlPath.startsWith(`${WARM_PATH}/`)) {
+      return serveWarm(req, res, urlPath).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
+    }
+    if (urlPath === START_FAILED_PATH) {
+      return handleStartFailed(req, res).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
+    }
     if (versions && (urlPath === DEV_CONTROL_PATH || urlPath.startsWith(`${DEV_CONTROL_PATH}/`))) {
       return handleDevControl(req, res, urlPath).catch(() => res.headersSent ? res.end() : (res.writeHead(500), res.end('500')));
     }
@@ -1058,7 +1131,8 @@ export function createStaticServer({
     }
 
     if (urlPath === '/' || urlPath === '/index.html') {
-      res.writeHead(302, { Location: gameEntry });
+      // The query goes along: `?fresh=` is for the game's page.
+      res.writeHead(302, { Location: gameEntry + reqUrl.search });
       return res.end();
     }
     let fsPath = resolveUrl(urlPath);
@@ -1073,8 +1147,8 @@ export function createStaticServer({
     const ext = extname(fsPath).toLowerCase();
     try {
       if (ext === '.html') return serveHtml(req, res, fsPath, urlPath, reqUrl.searchParams);
-      if (ext === '.js' || ext === '.mjs') return serveJs(res, fsPath, urlPath);
-      sendBody(res, 200, readFileSync(fsPath), MIME[ext] ?? 'application/octet-stream');
+      if (ext === '.js' || ext === '.mjs') return serveJs(req, res, fsPath, urlPath, reqUrl.searchParams);
+      sendFile(req, res, readFileSync(fsPath), MIME[ext] ?? 'application/octet-stream', urlPath, reqUrl.searchParams);
     } catch {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
       res.end('500');

package/lib/test-cmd.mjs

@@ -21,6 +21,7 @@ import { StringDecoder } from 'node:string_decoder';
 import { findProject, resolveEngine } from './project.mjs';
 import { dev } from './dev.mjs';
 import { lintCmd } from './lint.mjs';
+import { ensureEngine, ensureNamedEngine, namedEngineFailure } from './engine.mjs';
 import { portsFor, portInUse } from './ports.mjs';
 import { terminateChildTree } from './process-tree.mjs';
 import { summaryLines } from './test-reporter.mjs';
@@ -47,18 +48,35 @@ export const posixRelative = (dir, file, p = nodePath) => p.relative(dir, file).
 // The path module is injectable for the same reason: with `path.win32` the
 // real readdir → join → relative → skip chain runs with Windows semantics
 // against real files, on any host.
-export function discoverTestFiles(dir, { path: p = nodePath } = {}) {
+//
+// The walk never opens a folder it skips: the dev server keeps changing what
+// is under .joystack/ (frozen copies come and go) and node_modules/ is large,
+// and listing everything to filter after fails the whole run on a file that
+// vanished mid-listing. A folder that vanishes while the walk looks at it is
+// simply not there. `readdir` is injectable to check both.
+export function discoverTestFiles(dir, { path: p = nodePath, readdir = readdirSync } = {}) {
   const unit = [];
   const smokes = [];
-  const entries = readdirSync(dir, { withFileTypes: true, recursive: true });
-  for (const entry of entries) {
-    if (!entry.isFile()) continue;
-    // `parentPath` exists from node 20.12; the 20.11 floor names the same value `path`.
-    const path = p.join(entry.parentPath ?? entry.path, entry.name);
-    if (isSkippedPath(p.relative(dir, path))) continue;
-    if (entry.name.endsWith('.test.mjs')) unit.push(path);
-    else if (entry.name.endsWith('.smoke.mjs')) smokes.push(path);
-  }
+  // `real` is the folder as this host's file system names it; `shown`, as the
+  // injected path module does (the two differ only under path.win32).
+  const walk = (real, shown) => {
+    let entries;
+    try {
+      entries = readdir(real, { withFileTypes: true });
+    } catch (err) {
+      if (err?.code === 'ENOENT' && real !== dir) return;
+      throw err;
+    }
+    for (const entry of entries) {
+      const path = p.join(shown, entry.name);
+      if (isSkippedPath(p.relative(dir, path))) continue;
+      if (entry.isDirectory()) walk(nodePath.join(real, entry.name), path);
+      else if (!entry.isFile()) continue;
+      else if (entry.name.endsWith('.test.mjs')) unit.push(path);
+      else if (entry.name.endsWith('.smoke.mjs')) smokes.push(path);
+    }
+  };
+  walk(dir, dir);
   unit.sort();
   smokes.sort();
   return { unit, smokes };
@@ -330,7 +348,7 @@ async function freeTestPort(base = 8100) {
 
 // Preload that GPU-offloads each smoke's browser (see smoke-gpu-preload.mjs).
 // A file URL so `node --import` resolves it regardless of the smoke's cwd.
-const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
+export const SMOKE_PRELOAD = new URL('./smoke-gpu-preload.mjs', import.meta.url).href;
 
 // The compact node:test reporter (see test-reporter.mjs), as a file URL for the
 // same reason.
@@ -343,7 +361,7 @@ const REPORTER = new URL('./test-reporter.mjs', import.meta.url).href;
 // engine is absent (pruned by an npm install — the next dev/publish self-heals
 // it) or too old to ship the preload — the spawn then runs without it, as
 // before.
-function joystackTestPreload(projectDir) {
+export function joystackTestPreload(projectDir) {
   try {
     const preload = join(resolveEngine(projectDir).dir, 'shared', 'framework', 'build', 'joystack-test-preload.mjs');
     return existsSync(preload) ? pathToFileURL(preload).href : null;
@@ -378,6 +396,7 @@ export async function testCmd({
   devFn = dev, lintFn = lintCmd, runFn = run, unitRunFn = run, patterns = [], since, all: runAll = false, list = false,
   platform = process.platform, smokeTimeoutMs = smokeTimeoutFromEnv(), machineFn = sampleMachine,
   unitTimeoutMs = timeoutFromEnv('JOYSTACK_TEST_UNIT_TIMEOUT', DEFAULT_UNIT_TIMEOUT_MS),
+  ensure = ensureEngine,
 } = {}) {
   const project = findProject(cwd);
   const startedAt = new Date();
@@ -480,6 +499,16 @@ export async function testCmd({
       log(`▶ this machine was ${Math.round(verdict.machine.cpuBusy * 100)}% busy when this run started (another test run, a build, a game left open?). The result is still valid; the timings are not comparable with a run on an idle machine.`);
     }
 
+    // The tests, the preload that lets them import the joystack doors, and lint
+    // all load the engine, so it has to be the one the game names
+    // (engine.mjs, ensureNamedEngine). A run that cannot install it fails here,
+    // with a verdict, rather than testing the game on another engine.
+    try {
+      await ensureNamedEngine(project.dir, { ensure, log });
+    } catch (e) {
+      throw new Error(namedEngineFailure(project.dir, e));
+    }
+
     const { ensureBaked } = await import('./model-bake.mjs');
     await ensureBaked({ dir: project.dir, log });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joystack/cli",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "description": "Joystack game development CLI \u2014 dev server, login, and publishing for standalone Joystack games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -12,7 +12,8 @@
     "CHANGELOG.md",
     "bin",
     "lib",
-    "!lib/**/*.test.mjs"
+    "!lib/**/*.test.mjs",
+    "!lib/**/*-kit.mjs"
   ],
   "engines": {
     "node": ">=20.11"