@joystack/cli 0.0.0-stage → 0.1.43

package/lib/test-cmd.mjs

@@ -0,0 +1,697 @@
+// `joystack test` — run the game's own verification gate.
+//
+// Discovers the game's test files — `*.test.mjs` (unit, run under
+// `node --test`) and `*.smoke.mjs` (integration, run against a REAL dev
+// stack) — and selects ordinary plus triggered extended checks. The files ARE the executable QA list: `/qa`
+// merges this gate with handbook/qa.md and the engine's master qa.md.
+//
+// The smoke stack boots on a free shifted port triple so it never seizes a
+// dev server the creator has running on :8000.
+import { selectTests, readTestPolicy, changedTestPaths } from './test-policy.mjs';
+import { spawn } from 'node:child_process';
+import {
+  existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync, appendFileSync, copyFileSync, rmSync, statSync,
+  openSync, readSync, closeSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import nodePath, { join, relative, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import os from 'node:os';
+import { StringDecoder } from 'node:string_decoder';
+import { findProject, resolveEngine } from './project.mjs';
+import { dev } from './dev.mjs';
+import { lintCmd } from './lint.mjs';
+import { portsFor, portInUse } from './ports.mjs';
+import { terminateChildTree } from './process-tree.mjs';
+import { summaryLines } from './test-reporter.mjs';
+import { leaveJoystackNodeDoors } from './joystack-node-doors.mjs';
+import { withoutAgentSession } from './agent-session.mjs';
+import { readEnv, stateDir, withLegacyEnv } from './legacy-names.mjs';
+
+const SKIP_DIRS = new Set(['node_modules', 'overrides']);
+
+// Whether a game-relative path lies under a directory discovery must ignore:
+// dependencies (the engine ships its own scaffold smokes under node_modules),
+// engine-override copies, and dot-directories. `path.relative()` returns
+// backslash-separated paths on Windows, so the split accepts both separators —
+// splitting on '/' alone yields one giant segment there and skips nothing.
+export function isSkippedPath(rel) {
+  return rel.split(/[\\/]/).some((p) => SKIP_DIRS.has(p) || p.startsWith('.'));
+}
+
+// The game-relative path with forward slashes on every platform, so a filter
+// the creator types as `sub/depth` matches on Windows too. The path module is
+// injectable so the Windows form can be produced on any host.
+export const posixRelative = (dir, file, p = nodePath) => p.relative(dir, file).split('\\').join('/');
+
+// 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 } = {}) {
+  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);
+  }
+  unit.sort();
+  smokes.sort();
+  return { unit, smokes };
+}
+
+// Children run via async spawn, never spawnSync: the smoke dev stack's
+// static server lives in THIS process, and a blocked event loop can't
+// answer a child's requests — spawnSync deadlocks every smoke until its
+// fetches time out.
+//
+// A child's output is forwarded through `onOutput` rather than inherited, so
+// the runner can write the same bytes to the run's log file. `timeoutMs` is a
+// hang detector: a child still alive after it is killed with its descendants
+// and the run resolves to HUNG.
+//
+// Reaching the descendants is why the child leads its own process group
+// (`detached`) everywhere but Windows, where `terminateChildTree` walks the
+// tree with taskkill instead: a signal sent to a negative pid only lands when
+// that pid is a group leader, and a hung smoke is exactly the one that left a
+// browser or a helper server running. The price of a separate group is that
+// Ctrl-C in the terminal no longer reaches the child by itself, so the live
+// children are tracked and taken down when this process is told to stop.
+//
+// The run resolves when the child EXITS, not when its output pipes close: a
+// process the child started can inherit those pipes and outlive it, and
+// `close` waits for every holder. Output still in flight gets a short grace
+// period, then the pipes are dropped. Each stream is decoded as a stream, so a
+// character whose bytes arrive in two chunks is not turned into two
+// replacement characters.
+const OUTPUT_GRACE_MS = 250;
+export const HUNG = -2;
+
+const liveChildren = new Set();
+let stopHandlersInstalled = false;
+function installStopHandlers() {
+  if (stopHandlersInstalled) return;
+  stopHandlersInstalled = true;
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, () => {
+      for (const child of liveChildren) { try { terminateChildTree(child, 'SIGKILL'); } catch { /* already gone */ } }
+      process.exit(signal === 'SIGINT' ? 130 : 143);
+    });
+  }
+}
+
+function run(args, { onOutput, timeoutMs, ...opts } = {}) {
+  installStopHandlers();
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32', ...opts });
+    liveChildren.add(child);
+    let hung = false;
+    const timer = timeoutMs
+      ? setTimeout(() => {
+        hung = true;
+        try { terminateChildTree(child, 'SIGKILL'); } catch { child.kill('SIGKILL'); }
+      }, timeoutMs)
+      : null;
+    for (const stream of [child.stdout, child.stderr]) {
+      if (!stream) continue;
+      const decoder = new StringDecoder('utf8');
+      stream.on('data', (chunk) => {
+        const text = decoder.write(chunk);
+        if (text) (onOutput ?? ((t) => process.stdout.write(t)))(text);
+      });
+    }
+    let settled = false;
+    const settle = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      liveChildren.delete(child);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve(code);
+    };
+    child.on('exit', (code) => {
+      const result = hung ? HUNG : code ?? 1;
+      child.on('close', () => settle(result));
+      setTimeout(() => settle(result), OUTPUT_GRACE_MS);
+    });
+    child.on('error', () => settle(1));
+  });
+}
+
+// A smoke's normal run is seconds to a few minutes even on a slow machine
+// without a GPU, so ten minutes only ever ends a smoke that would not have
+// ended by itself. It is not a performance budget: a tighter value fails
+// different smokes on different machines.
+const DEFAULT_SMOKE_TIMEOUT_MS = 10 * 60 * 1000;
+// What a whole-suite run is measured against when `joystack.tests.json` names no
+// `budgetSeconds`: long enough for a real suite, short enough that a developer
+// still waits for it rather than working around it.
+const DEFAULT_BUDGET_SECONDS = 300;
+
+// The node half runs as one process, so its guard covers the whole half: long
+// enough for a large suite on a slow machine, and still an end to a test whose
+// promise never settles.
+const DEFAULT_UNIT_TIMEOUT_MS = 30 * 60 * 1000;
+
+// A timeout from the environment, in seconds. A value that is not a positive
+// number falls back to the default AND says so: a knob that silently ignores
+// `30s` leaves its user waiting ten minutes believing they asked for thirty
+// seconds.
+export function timeoutFromEnv(name, fallbackMs, { warn = (line) => console.error(line) } = {}) {
+  const raw = readEnv(name);
+  if (raw === undefined || raw === '') return fallbackMs;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds) && seconds > 0) return seconds * 1000;
+  warn(`joystack test: ${name}=${JSON.stringify(raw)} is not a positive number of seconds — using ${fallbackMs / 1000}.`);
+  return fallbackMs;
+}
+
+function smokeTimeoutFromEnv() {
+  return timeoutFromEnv('JOYSTACK_TEST_SMOKE_TIMEOUT', DEFAULT_SMOKE_TIMEOUT_MS);
+}
+
+// A test file may declare, in a comment near its top, the platforms it cannot
+// run on and why:
+//
+//   // skip-on: win32 — WebKit on Windows has no Web Audio
+//
+// Platforms are node's `process.platform` values, comma-separated. The file is
+// then reported as skipped there instead of failing. Returns null when the
+// file declares nothing; an empty `reason` is the caller's to reject.
+//
+// The line counts only inside the comment block that opens the file (`//`
+// lines and blank lines, after an optional `#!` line). The same text further
+// down — inside a template literal, or in a fixture a test writes — is not a
+// declaration. The reason is split off at a dash; a hyphen only counts with
+// whitespace on both sides, so `win32-only` stays one (unknown) platform name
+// instead of reading as platform `win32`, reason `only`.
+const SKIP_LINE = /^\s*\/\/\s*skip-on:\s*(.*)$/;
+const REASON_SPLIT = /\s*[—–]\s*|\s+-\s+/;
+const HEAD_BYTES = 2048;
+
+// The values `process.platform` can take. A declaration naming anything else
+// (`windows`, `macos`, `Win32`) can never match, so the file would run
+// everywhere while its author believes it is skipped; that is refused.
+const PLATFORMS = ['aix', 'android', 'darwin', 'freebsd', 'haiku', 'linux', 'openbsd', 'sunos', 'win32', 'cygwin', 'netbsd'];
+
+// The `//` lines of the comment block that opens a file: everything before the
+// first line of code, past an optional `#!` line, blank lines and `/* … */`
+// blocks (whose contents are not yielded). Declarations are read from here
+// and nowhere else, so text further down is never mistaken for one.
+export function* openingCommentLines(source) {
+  let inBlock = false;
+  for (const [index, raw] of source.split(/\r?\n/).entries()) {
+    let line = raw.trim();
+    if (index === 0 && line.startsWith('#!')) continue;
+    if (inBlock) {
+      if (!line.includes('*/')) continue;
+      inBlock = false;
+      line = line.slice(line.indexOf('*/') + 2).trim();
+    }
+    while (line.startsWith('/*')) {
+      const end = line.indexOf('*/', 2);
+      if (end === -1) { inBlock = true; line = ''; break; }
+      line = line.slice(end + 2).trim();
+    }
+    if (line === '') continue;
+    if (!line.startsWith('//')) return;
+    yield line;
+  }
+}
+
+export function skipDeclaration(source) {
+  let declared = null;
+  for (const line of openingCommentLines(source.slice(0, HEAD_BYTES))) {
+    const match = SKIP_LINE.exec(line);
+    if (match) { declared = match[1].trim(); break; }
+  }
+  if (declared === null) return null;
+  const [names, ...rest] = declared.split(REASON_SPLIT);
+  const platforms = names.split(',').map((p) => p.trim()).filter(Boolean);
+  const unknown = platforms.filter((p) => !PLATFORMS.includes(p));
+  if (unknown.length) {
+    throw new Error(`\`skip-on: ${names.trim()}\` — "${unknown.join('", "')}" is not a platform. Use node's names: win32 (Windows), darwin (macOS), linux.`);
+  }
+  return { platforms, reason: rest.join(' — ').trim() };
+}
+
+// Why a smoke needs a browser at all, declared at the head of the file:
+//
+//   // browser-need: layout
+//
+// The five words are the only things a node test cannot check: `layout` (real
+// CSS and viewport geometry), `input` (real pointer, touch and key events),
+// `boot` (the page loads and its modules resolve), `audio` (what the device's
+// audio graph is doing) and `pixels` (what was actually drawn). `joystack lint`
+// rejects a smoke that declares none or another word; the runner only counts
+// them, so a growing number of browser smokes is visible on the run that added one.
+export const BROWSER_NEEDS = ['layout', 'input', 'boot', 'audio', 'pixels'];
+const BROWSER_NEED = /^\/\/\s*browser-need:\s*(.*?)\s*$/;
+
+// Read from the comment block that opens the file, however long it is — the
+// same place `joystack lint` requires it. A word outside the five is no
+// declaration at all: counting `layouts` as a kind of its own would hide the
+// typo on a scoped run, where lint does not run.
+export function browserNeed(source) {
+  for (const line of openingCommentLines(source)) {
+    const word = BROWSER_NEED.exec(line)?.[1];
+    if (word !== undefined) return BROWSER_NEEDS.includes(word) ? word : null;
+  }
+  return null;
+}
+
+// "layout 2 3.4s, audio 1 40.1s, undeclared 1 2.0s" — the five kinds in their
+// fixed order, then the files that declare none of them. Each kind carries its
+// time as well as its count, because the numerous kind is rarely the costly one.
+function needCounts(smokes) {
+  const kinds = new Map();
+  for (const s of smokes) {
+    const kind = kinds.get(s.need ?? 'undeclared') ?? { count: 0, seconds: 0 };
+    kinds.set(s.need ?? 'undeclared', { count: kind.count + 1, seconds: kind.seconds + s.seconds });
+  }
+  return [...BROWSER_NEEDS, 'undeclared'].filter((k) => kinds.has(k))
+    .map((k) => `${k} ${kinds.get(k).count} ${kinds.get(k).seconds.toFixed(1)}s`).join(', ');
+}
+
+function readHead(file) {
+  const fd = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(HEAD_BYTES);
+    return buffer.toString('utf8', 0, readSync(fd, buffer, 0, HEAD_BYTES, 0));
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// Everything a terminal interprets rather than prints: colour and cursor
+// sequences (including the private `?25l` forms a spinner hides the cursor
+// with) and window-title sequences. A carriage return with no line feed is a
+// progress line redrawing itself; in a file each redraw becomes its own line.
+const ANSI = /\u001b(?:\[[0-?]*[ -/]*[@-~]|\][^\u0007\u001b]*(?:\u0007|\u001b\\))/g;
+const plain = (text) => text.replace(ANSI, '').replace(/\r(?!\n)/g, '\n');
+const KEPT_RUNS = 20;
+const SCRATCH_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+// Each run gets its own pair of files under .joystack/test/ (named by start time
+// and pid, so a background run and a foreground run in one folder never
+// overwrite each other), and `last.json` / `last.log` are copies of the most
+// recently finished one.
+function openRunFiles(projectDir, startedAt) {
+  const dir = join(stateDir(projectDir), 'test');
+  mkdirSync(dir, { recursive: true });
+  const stamp = `${startedAt.toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+  const logPath = join(dir, `${stamp}.log`);
+  const verdictPath = join(dir, `${stamp}.json`);
+  writeFileSync(logPath, '');
+  const names = readdirSync(dir);
+  const old = names.filter((f) => /^\d{4}-[^.]*\.(log|json)$/.test(f)).sort();
+  for (const name of old.slice(0, Math.max(0, old.length - KEPT_RUNS * 2))) rmSync(join(dir, name), { force: true });
+  // A run that was interrupted leaves its `.unit.` scratch pair behind. Only
+  // old ones are removed: a recent pair may belong to a run still in progress.
+  for (const name of names.filter((f) => /^\d{4}-[^.]*\.unit\.(log|json)$/.test(f))) {
+    try { if (Date.now() - statSync(join(dir, name)).mtimeMs > SCRATCH_MAX_AGE_MS) rmSync(join(dir, name), { force: true }); } catch { /* gone already */ }
+  }
+  return { dir, logPath, verdictPath, unitLogPath: join(dir, `${stamp}.unit.log`), unitReportPath: join(dir, `${stamp}.unit.json`) };
+}
+
+async function freeTestPort(base = 8100) {
+  for (let port = base; port < base + 500; port += 10) {
+    const triple = portsFor(port);
+    const used = await Promise.all(Object.values(triple).map(portInUse));
+    if (!used.some(Boolean)) return port;
+  }
+  throw new Error('no free port triple found for the test dev stack');
+}
+
+// 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;
+
+// The compact node:test reporter (see test-reporter.mjs), as a file URL for the
+// same reason.
+const REPORTER = new URL('./test-reporter.mjs', import.meta.url).href;
+
+// The joystack resolver preload the installed engine ships
+// (shared/framework/build/joystack-test-preload.mjs): registering it lets a unit
+// test or smoke import the joystack doors (`import { openWorld } from
+// 'joystack/test'`) at top level, with no per-file bootstrap. Null when the
+// 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) {
+  try {
+    const preload = join(resolveEngine(projectDir).dir, 'shared', 'framework', 'build', 'joystack-test-preload.mjs');
+    return existsSync(preload) ? pathToFileURL(preload).href : null;
+  } catch {
+    return null;
+  }
+}
+
+// How loaded the machine is at the moment a run starts: the share of processor
+// time spent busy over a short window, from the operating system's own counters
+// (`os.loadavg()` is always zero on Windows, so it cannot be used). A suite that
+// takes four times as long on a saturated machine has not become slower, and
+// without this number in the verdict the two cases cannot be told apart later.
+export async function sampleMachine(windowMs = 250) {
+  const read = () => os.cpus().reduce((acc, cpu) => {
+    const total = Object.values(cpu.times).reduce((a, b) => a + b, 0);
+    return { idle: acc.idle + cpu.times.idle, total: acc.total + total };
+  }, { idle: 0, total: 0 });
+  const before = read();
+  await new Promise((resolve) => setTimeout(resolve, windowMs));
+  const after = read();
+  const total = after.total - before.total;
+  const cpuBusy = total > 0 ? Number((1 - (after.idle - before.idle) / total).toFixed(2)) : 0;
+  return { cpus: os.cpus().length, cpuBusy, freeMemMB: Math.round(os.freemem() / 1048576) };
+}
+
+// Above this share of busy processor time when the run starts, the run says so.
+const BUSY_MACHINE = 0.5;
+
+export async function testCmd({
+  cwd = process.cwd(), log: logLine = console.log, write: writeOut = (text) => process.stdout.write(text),
+  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),
+} = {}) {
+  const project = findProject(cwd);
+  const startedAt = new Date();
+  let runFiles = null;
+  const toLogFile = (text) => { if (runFiles) appendFileSync(runFiles.logPath, plain(text)); };
+  const log = (line = '') => { logLine(line); toLogFile(`${line}\n`); };
+  const forwardOutput = (text) => { writeOut(text); toLogFile(text); };
+
+  if ((since && runAll) || (patterns.length && (since || runAll))) throw new Error('Choose patterns, --since, or --all');
+  const scoped = patterns.length > 0;
+  const posix = (file) => posixRelative(project.dir, file);
+
+  // `--list` runs nothing, so it leaves no run files. Every other run opens
+  // them before its first line, so the log holds the run from the top.
+  if (!list) runFiles = openRunFiles(project.dir, startedAt);
+
+  const verdict = {
+    ok: false, startedAt: startedAt.toISOString(), seconds: 0, platform,
+    // How the run was launched and on what, so that two verdicts can be compared
+    // as two runs of the same thing rather than guessed at.
+    command: ['joystack test', ...patterns, ...(since ? ['--since', since] : []), ...(runAll ? ['--all'] : [])].join(' '),
+    node: process.version, machine: null, selection: null, lint: null,
+    skipped: [], unit: null, smokes: [],
+  };
+  let lint = { ok: true, skipped: true };
+  let selection = null;
+  let all, files, policy, unit, smokes;
+
+  // Every exit of a real run goes through `finish`, so a run always leaves a
+  // verdict behind — including the runs that end early. Refreshing `last.*` is
+  // best effort: a copy that fails (the file held open by an editor on Windows)
+  // must not replace the result of the run with an exception.
+  const finish = (result) => {
+    verdict.ok = result.ok;
+    verdict.seconds = Number(((Date.now() - startedAt.getTime()) / 1000).toFixed(1));
+    writeFileSync(runFiles.verdictPath, `${JSON.stringify(verdict, null, 2)}\n`);
+    for (const scratch of [runFiles.unitLogPath, runFiles.unitReportPath]) rmSync(scratch, { force: true });
+    try {
+      copyFileSync(runFiles.verdictPath, join(runFiles.dir, 'last.json'));
+      copyFileSync(runFiles.logPath, join(runFiles.dir, 'last.log'));
+    } catch (e) {
+      logLine(`⚠ could not refresh .joystack/test/last.json and last.log (${e?.message ?? e}) — this run's own files are ${relative(project.dir, runFiles.verdictPath)} and ${relative(project.dir, runFiles.logPath)}`);
+    }
+    return { ...result, lint, selection, verdictPath: runFiles.verdictPath, logPath: runFiles.logPath };
+  };
+
+  // Anything that throws once the run files exist — an unreadable
+  // `joystack.tests.json`, a dev stack that will not boot, no free port — is a
+  // failed run with a verdict, not an exception that leaves `last.json`
+  // describing the previous run.
+  try {
+    const listed = await prepare();
+    return listed ?? await execute();
+  } catch (e) {
+    if (!runFiles) throw e;
+    const message = String(e?.message ?? e);
+    log(`❌ joystack test could not finish: ${message}`);
+    verdict.error = message;
+    return finish({ ok: false, ran: 0 });
+  }
+
+  async function prepare() {
+    all = discoverTestFiles(project.dir);
+    files = [...all.unit, ...all.smokes];
+    policy = readTestPolicy(project.dir, files);
+    let changed;
+    if (since) {
+      try { changed = changedTestPaths(project.dir, since); }
+      catch (error) { log(`⚠ Cannot compare with ${since}: ${error.message}. Including every extended test.`); }
+    }
+    selection = scoped
+      ? { files: files.filter((f) => patterns.some((p) => posix(f).includes(p))), skipped: [], reason: 'targeted step checks' }
+      : selectTests({ dir: project.dir, files, policy, changed, all: runAll });
+    const selected = new Set(selection.files);
+    unit = all.unit.filter((f) => selected.has(f));
+    smokes = all.smokes.filter((f) => selected.has(f));
+    verdict.selection = { reason: selection.reason, selected: selected.size, of: files.length };
+    log(`▶ ${selection.reason}: ${selected.size} of ${files.length} test files`);
+    // A scoped run names its files outright, so which extended tests a broad
+    // run would defer is noise there. `--list` is the mode that explains
+    // selection, so it gives each extended test its reason; a real run says the
+    // same in one line.
+    const extended = (scoped ? [] : policy?.extended ?? []).map((entry) => ({
+      ...entry, included: selection.files.some((f) => posix(f) === entry.test),
+    }));
+    if (list) {
+      for (const entry of extended) log(`  ${entry.included ? 'include' : 'defer'} extended ${entry.test} — ${entry.reason}`);
+      for (const file of selection.files) log(`  ${posix(file)}`);
+      return { ok: !scoped || selected.size > 0, ran: 0, selection };
+    }
+    if (extended.length) {
+      const names = (wanted) => extended.filter((e) => e.included === wanted).map((e) => e.test);
+      const part = (label, tests) => (tests.length ? `${tests.length} ${label} (${tests.join(', ')})` : `0 ${label}`);
+      log(`  extended tests: ${part('included', names(true))}, ${part('deferred', names(false))} — \`--list\` gives the reason for each`);
+    }
+
+    // Sampled before lint and model baking, which load the machine themselves.
+    verdict.machine = await machineFn();
+    if (verdict.machine.cpuBusy >= BUSY_MACHINE) {
+      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.`);
+    }
+
+    const { ensureBaked } = await import('./model-bake.mjs');
+    await ensureBaked({ dir: project.dir, log });
+
+    // Lint FIRST — it needs no servers and no browser, and the defects it catches
+    // (a hardcoded multiplayer host, a smoke pointed at the wrong port) are
+    // exactly the ones that make the suite below pass while testing nothing.
+    // Failing here does not skip the tests: the creator should see everything
+    // that is wrong in one run, not peel it one gate at a time.
+    //
+    // A SCOPED run skips it: lint runs at the submission gate — a `joystack test <pattern>` is a focused per-step
+    // re-run, not the gate.
+    // A lint step that throws is a failed step, not the end of the run: the tests
+    // below still run and the verdict is still written.
+    if (!scoped) {
+      try {
+        lint = await lintFn({ cwd: project.dir, log });
+      } catch (e) {
+        log(`❌ joystack lint could not run: ${e?.message ?? e}`);
+        lint = { ok: false, error: String(e?.message ?? e) };
+      }
+    }
+    verdict.lint = { ok: lint.ok, skipped: Boolean(lint.skipped), ...(lint.error ? { error: lint.error } : {}) };
+    return null;
+  }
+
+  async function execute() {
+  // A pattern that matches nothing FAILS LOUD. "0 tests, all green" is the exact
+  // false-pass this whole gate exists to prevent — a mistyped scope must never
+  // read as "everything's fine." (A game with genuinely no tests and no pattern
+  // is the legitimately-green fresh-game case below.)
+  if (patterns.length && unit.length + smokes.length === 0) {
+    log(`No tests matched ${patterns.map((p) => `"${p}"`).join(', ')} in ${project.dir}.`);
+    log(`(${all.unit.length + all.smokes.length} test file(s) exist; none contain that pattern. Check the spelling, or run \`joystack test\` with no pattern to run the whole suite.)`);
+    return finish({ ok: false, ran: 0 });
+  }
+
+  if (unit.length + smokes.length === 0) {
+    log(`No tests yet in ${project.dir} — nothing to run.`);
+    log('(Unit tests are *.test.mjs; browser smokes are *.smoke.mjs.)');
+    return finish({ ok: lint.ok, ran: 0 });
+  }
+
+  if (patterns.length) {
+    log(`▶ scoped to ${patterns.map((p) => `"${p}"`).join(', ')}: ${unit.length + smokes.length} of ${all.unit.length + all.smokes.length} file(s) — broader coverage runs at submission.`);
+  }
+
+  let ok = lint.ok;
+
+  // Platform skips, declared in the files themselves. A declaration with no
+  // reason fails the run: an unexplained skip is indistinguishable from a
+  // test somebody switched off because it was red.
+  const runsHere = (file) => {
+    let declared;
+    try {
+      declared = skipDeclaration(readHead(file));
+    } catch (e) {
+      log(`  ❌ ${posix(file)} — ${e.message}`);
+      ok = false;
+      return false;
+    }
+    if (!declared || !declared.platforms.includes(platform)) return true;
+    if (!declared.reason) {
+      log(`  ❌ ${posix(file)} — its \`// skip-on:\` line gives no reason. Write why it cannot run on ${platform}: \`// skip-on: ${platform} — <reason>\``);
+      ok = false;
+      return false;
+    }
+    log(`  ⏭ ${posix(file)} — skipped on ${platform}: ${declared.reason}`);
+    verdict.skipped.push({ file: posix(file), reason: declared.reason });
+    return false;
+  };
+  const unitHere = unit.filter(runsHere);
+  const smokesHere = smokes.filter(runsHere);
+
+  // The joystack resolver preload, if the installed engine ships it (see above).
+  const joystackPreload = joystackTestPreload(project.dir);
+  const joystackImport = joystackPreload ? ['--import', joystackPreload] : [];
+
+  // The other half of the same problem: the preload above is what makes `joystack
+  // test` able to run these files, and its absence is what makes running one by
+  // hand fail with `Cannot find package 'joystack'`. Leave the package that answers
+  // that (joystack-node-doors.mjs) while the engine is known — `test` is the
+  // command whose files get run by hand, and it does not go through
+  // ensureEngine.
+  try { leaveJoystackNodeDoors(project.dir, resolveEngine(project.dir)); } catch { /* no engine resolved; nothing to point at */ }
+
+  // If joystack test itself runs under a node --test parent, the inherited
+  // NODE_TEST_CONTEXT makes a nested `node --test` exit 0 even on failure —
+  // silently green. Strip it for every child. The agent session's address is
+  // stripped too: a test that starts its own `joystack dev` must never post
+  // into the conversation of the agent running the tests.
+  const env = withoutAgentSession(process.env);
+  delete env.NODE_TEST_CONTEXT;
+
+  if (unitHere.length) {
+    log(`▶ node tests: ${unitHere.length} file(s)`);
+    // Two reporters on one run: the compact one to the console, node's full
+    // `spec` listing to a file that is appended to the run's log afterwards.
+    const reporters = [
+      '--test-reporter', REPORTER, '--test-reporter-destination', 'stdout',
+      '--test-reporter', 'spec', '--test-reporter-destination', runFiles.unitLogPath,
+    ];
+    const unitStarted = performance.now();
+    const code = await unitRunFn([...joystackImport, '--test', ...reporters, ...unitHere], {
+      cwd: project.dir, env: { ...env, ...withLegacyEnv({ JOYSTACK_TEST_UNIT_REPORT: runFiles.unitReportPath }) }, onOutput: forwardOutput,
+      timeoutMs: unitTimeoutMs,
+    });
+    if (code !== 0) ok = false;
+    const unitHung = code === HUNG;
+    if (unitHung) log(`  ❌ node tests — HUNG: still running after ${Math.round(unitTimeoutMs / 1000)}s, killed. Some test never ends: a promise that never settles, a timer or a server left open. The full log lists the tests that did finish; the one after them is where to look.`);
+    if (existsSync(runFiles.unitLogPath)) toLogFile(`\n── node tests, full listing ──\n${readFileSync(runFiles.unitLogPath, 'utf8')}\n`);
+    // Wall time is taken here, around the whole child: the reporter only sees
+    // the span between its first and last event, which leaves out node's own
+    // start-up and the loading of every test file.
+    const unitSeconds = Number(((performance.now() - unitStarted) / 1000).toFixed(1));
+    if (existsSync(runFiles.unitReportPath)) verdict.unit = { ...JSON.parse(readFileSync(runFiles.unitReportPath, 'utf8')), seconds: unitSeconds };
+    // The child died before its reporter could write (a crash in a preload,
+    // an out-of-memory kill): the exit code is all that is known.
+    else verdict.unit = { tests: 0, pass: 0, fail: 0, skip: 0, todo: 0, failed: [], skipped: [], todos: [], files: [], crashed: !unitHung, exitCode: code, seconds: unitSeconds };
+    if (unitHung) verdict.unit.hung = true;
+    // node exits 0 for a file that ended itself before reporting a test; the
+    // reporter counts that as a failure, and the count is what decides.
+    if (verdict.unit.fail > 0) ok = false;
+  }
+
+  if (smokesHere.length) {
+    // Browser preflight — only when a smoke actually imports playwright (a
+    // plain fetch-probe smoke needs none, and test fixtures must stay
+    // hermetic). The scaffold ships playwright and `joystack create` pre-fetches
+    // Chromium; this self-heals older repos and pruned caches so a smoke
+    // never dies into a cryptic mid-run download.
+    if (smokesHere.some((f) => /['"]playwright/.test(readFileSync(f, 'utf8')))) {
+      let playwrightCli;
+      try {
+        playwrightCli = join(
+          dirname(createRequire(join(project.dir, 'package.json')).resolve('playwright/package.json')),
+          'cli.js',
+        );
+      } catch {
+        log('❌ a smoke imports playwright, which is not installed in this game —');
+        log('   run: npm i -D playwright   (then re-run `joystack test`)');
+        return finish({ ok: false, ran: unitHere.length });
+      }
+      // Instant no-op when the browser is already cached; downloads otherwise.
+      if ((await run([playwrightCli, 'install', 'chromium'], { cwd: project.dir, env, onOutput: forwardOutput })) !== 0) {
+        log('❌ could not fetch the Chromium test browser (offline?) — smokes need it.');
+        return finish({ ok: false, ran: unitHere.length });
+      }
+    }
+
+    const handle = await devFn({ cwd: project.dir, port: await freeTestPort(), watch: false, log: () => {} });
+    log(`▶ smokes against ${handle.url}`);
+    try {
+      for (const file of smokesHere) {
+        const rel = posix(file);
+        const started = performance.now();
+        log(`  ▶ ${rel}`);
+        const code = await runFn(['--import', SMOKE_PRELOAD, ...joystackImport, file], {
+          cwd: project.dir,
+          onOutput: forwardOutput,
+          timeoutMs: smokeTimeoutMs,
+          env: {
+            ...env,
+            ...withLegacyEnv({ JOYSTACK_TEST_GAME_URL: handle.url }),
+            // A legacy alias for the same URL, exported so smokes written
+            // against the older convention keep running unedited.
+            GAMEDEV_TEST_GAME_URL: handle.url,
+            URL: handle.url,
+          },
+        });
+        const seconds = Number(((performance.now() - started) / 1000).toFixed(2));
+        const hung = code === HUNG;
+        if (hung) log(`  ❌ ${rel} — HUNG: still running after ${Math.round(smokeTimeoutMs / 1000)}s, killed. A smoke must end by itself; look for a wait loop whose condition can never become true. (${seconds.toFixed(2)}s)`);
+        else log(`  ${code === 0 ? '✅' : '❌'} ${rel} (${seconds.toFixed(2)}s)`);
+        verdict.smokes.push({ file: rel, ok: code === 0, seconds, need: browserNeed(readFileSync(file, 'utf8')), ...(hung ? { hung: true } : {}) });
+        if (code !== 0) ok = false;
+      }
+    } finally {
+      // The smokes have their results by now; a stack that fails to stop is
+      // reported, and does not replace them.
+      try { await handle.stop(); } catch (e) { log(`⚠ the test dev stack did not stop cleanly: ${e?.message ?? e}`); }
+    }
+  }
+
+  log('');
+  const smokeSeconds = verdict.smokes.reduce((sum, s) => sum + s.seconds, 0);
+  const failedSmokes = verdict.smokes.filter((s) => !s.ok);
+  if (verdict.unit && !verdict.unit.crashed) for (const line of summaryLines(verdict.unit, { seconds: verdict.unit.seconds })) log(line);
+  if (verdict.smokes.length) log(`  smokes: ${verdict.smokes.length} run — ${verdict.smokes.length - failedSmokes.length} passed, ${failedSmokes.length} failed in ${smokeSeconds.toFixed(1)}s (${needCounts(verdict.smokes)})`);
+  if (verdict.skipped.length) log(`  skipped on ${platform}: ${verdict.skipped.map((s) => s.file).join(', ')}`);
+  // The total is measured against a budget on every run that is not scoped to
+  // a pattern. Going over never fails the run: the budget exists so that the
+  // cost of the suite is in front of whoever is about to add another file to it.
+  if (!scoped) {
+    const budgetSeconds = policy?.budgetSeconds ?? DEFAULT_BUDGET_SECONDS;
+    const total = (Date.now() - startedAt.getTime()) / 1000;
+    verdict.budgetSeconds = budgetSeconds;
+    verdict.overBudget = total > budgetSeconds;
+    log(verdict.overBudget
+      ? `  total: ${total.toFixed(1)}s of a ${budgetSeconds}s budget — over by ${(total - budgetSeconds).toFixed(0)}s. Before adding a test file: put the check in an existing file, move a smoke's check into a node test, or delete a test that no longer guards anything. To bring the whole suite back down, run /compress-tests — the costs that belong to no single test are only visible from there.`
+      : `  total: ${total.toFixed(1)}s of a ${budgetSeconds}s budget`);
+  }
+  if (!ok) {
+    if (verdict.unit?.crashed) log(`  ✖ node tests: the test process ended (exit ${verdict.unit.exitCode}) before reporting a single result — the full log has whatever it printed`);
+    if (verdict.unit?.hung) log('  ✖ node tests (hung)');
+    for (const f of verdict.unit?.failed ?? []) log(`  ✖ ${f.file} › ${f.name}`);
+    for (const s of failedSmokes) log(`  ✖ ${s.file}${s.hung ? ' (hung)' : ''}`);
+    if (!lint.ok) log('  ✖ lint');
+  }
+  log(ok
+    ? `✅ joystack test: all green (${unitHere.length} node test file(s), ${smokesHere.length} smoke(s))`
+    : '❌ joystack test: failed — the list above is complete');
+  log(`   full log: ${relative(project.dir, runFiles.logPath)}   verdict: ${relative(project.dir, runFiles.verdictPath)}`);
+  return finish({ ok, ran: unitHere.length + smokesHere.length });
+  }
+}