@joystack/cli 0.0.0-stage → 0.1.43

package/lib/test-policy.mjs

@@ -0,0 +1,157 @@
+// Extended tests are opt-in declarations; every undeclared test stays ordinary.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, relative, resolve } from 'node:path';
+import { STATE_DIR_NAMES, TEST_POLICY_FILE, testPolicyFile } from './legacy-names.mjs';
+
+// The policy file's name, as the game being read spells it (testPolicyFile);
+// set by readTestPolicy so every error names the file the creator has.
+let POLICY = TEST_POLICY_FILE;
+const posix = (s) => s.replaceAll('\\', '/');
+
+function matcher(pattern) {
+  if (typeof pattern !== 'string' || !pattern || pattern.startsWith('/') || pattern.includes('\\') || pattern.split('/').includes('..') || /[\[\]{}]/.test(pattern)) {
+    throw new Error(`${POLICY}: patterns must be relative paths using /, *, ** or ?`);
+  }
+  let source = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') {
+      i++;
+      if (pattern[i + 1] === '/') { i++; source += '(?:.*/)?'; }
+      else source += '.*';
+    } else if (c === '*') source += '[^/]*';
+    else if (c === '?') source += '[^/]';
+    else source += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(source + '$');
+}
+
+function patterns(value, label, { nonempty = false } = {}) {
+  if (!Array.isArray(value) || (nonempty && !value.length)) throw new Error(`${POLICY}: ${label} must be ${nonempty ? 'a nonempty' : 'an'} array`);
+  return value.map(matcher);
+}
+const matches = (path, rules) => rules.some((rule) => rule.test(path));
+
+export function readTestPolicy(dir, files) {
+  POLICY = testPolicyFile(dir);
+  const path = join(dir, POLICY);
+  if (!existsSync(path)) return null;
+  const raw = JSON.parse(readFileSync(path, 'utf8'));
+  if (raw.version !== 1 || !Array.isArray(raw.extended)) throw new Error(`${POLICY}: expected version 1 and an extended array`);
+  const allowed = ['version', 'extended', 'ordinaryChanges', 'always', 'budgetSeconds'];
+  if (Object.keys(raw).some((k) => !allowed.includes(k))) throw new Error(`${POLICY}: unknown top-level field`);
+  if ('budgetSeconds' in raw && !(typeof raw.budgetSeconds === 'number' && raw.budgetSeconds > 0)) throw new Error(`${POLICY}: budgetSeconds must be a positive number of seconds`);
+  const known = new Set(files.map((f) => posix(relative(dir, f))));
+  const seen = new Set();
+  const extended = raw.extended.map((entry) => {
+    if (!entry || typeof entry.test !== 'string' || !known.has(entry.test) || seen.has(entry.test)) throw new Error(`${POLICY}: extended test is missing or duplicated: ${entry?.test}`);
+    if (Object.keys(entry).some((k) => !['test', 'when', 'reason'].includes(k))) throw new Error(`${POLICY}: unknown field for ${entry.test}`);
+    if (typeof entry.reason !== 'string' || !entry.reason.trim()) throw new Error(`${POLICY}: ${entry.test} needs a reason`);
+    seen.add(entry.test);
+    return { ...entry, rules: patterns(entry.when, `${entry.test}.when`, { nonempty: true }) };
+  });
+  return {
+    extended,
+    ordinary: patterns(raw.ordinaryChanges ?? [], 'ordinaryChanges'),
+    always: patterns(raw.always ?? [], 'always'),
+    budgetSeconds: raw.budgetSeconds,
+  };
+}
+
+// Name-only without rename detection returns both sides of moves. NUL delimiters
+// preserve spaces/newlines, and -- separates paths from command-line options.
+export function changedTestPaths(dir, since) {
+  const git = (args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  if (!since || since.startsWith('-')) throw new Error('test --since needs an integration base, not an option');
+  const root = realpathSync.native(git(['rev-parse', '--show-toplevel']).trim());
+  const projectDir = realpathSync.native(dir);
+  const base = git(['merge-base', 'HEAD', since]).trim();
+  const changed = git(['-C', root, 'diff', '--no-relative', '--name-only', '--no-renames', '-z', base, '--']);
+  const untracked = git(['-C', root, 'ls-files', '--others', '--exclude-standard', '-z']);
+  // The runner's own output under `.joystack/` is never a change to the game. A
+  // game whose .gitignore does not list it would otherwise see this run's log
+  // as an unmapped change and widen every run to the whole suite.
+  return [...new Set((changed + untracked).split('\0').filter(Boolean).map((p) => posix(relative(projectDir, resolve(root, p)))))]
+    .filter((p) => !STATE_DIR_NAMES.some((d) => p.startsWith(`${d}/`)));
+}
+
+export function selectTests({ dir, files, policy, changed, all = false }) {
+  if (!policy || all) return { files, skipped: [], reason: all ? 'explicit --all audit' : 'all tests are ordinary (no policy)' };
+  if (!changed) return { files, skipped: [], reason: 'no integration base; including all extended tests (use --since <base> at submission)' };
+  const extended = new Map(policy.extended.map((entry) => [entry.test, entry]));
+  const testPaths = new Set(files.map((f) => posix(relative(dir, f))));
+  // A changed test file is never an unmapped change, whether or not it still
+  // exists: a deleted or renamed test is absent from `files`, so it is
+  // recognised by name. Nothing imports a test file, so removing one cannot
+  // affect any other test.
+  const isTest = (p) => /\.(test|smoke)\.mjs$/.test(p);
+  const policyFile = testPolicyFile(dir);
+  const broad = changed.find((p) => p === policyFile || matches(p, policy.always) || (!isTest(p) && !matches(p, policy.ordinary) && !policy.extended.some((e) => matches(p, e.rules))));
+  if (broad) return { files, skipped: [], reason: `broad coverage: ${broad} is a foundation, policy, or unmapped change` };
+  const selected = files.filter((file) => {
+    const path = posix(relative(dir, file));
+    const entry = extended.get(path);
+    return !entry || changed.some((p) => p === path || matches(p, entry.rules));
+  });
+  const selectedSet = new Set(selected);
+  return { files: selected, skipped: files.filter((f) => !selectedSet.has(f)), reason: 'ordinary regressions plus extended tests triggered by changes' };
+}
+
+export const TEST_HELP = `joystack test — run this game's checks
+
+Usage:
+  joystack test <aspect> [<aspect>…]  Run the test files whose path contains <aspect> (e.g. \`joystack test boot\`
+                                   runs boot.test.mjs and boot.smoke.mjs). The way to check one thing while
+                                   you work; skips lint.
+  joystack test --since <base>        Submission: ordinary tests plus the extended ones your changes since
+                                   <base> trigger (joystack.tests.json), and lint.
+  joystack test                       Everything not deferred by joystack.tests.json, and lint.
+  joystack test --all                 Every test file, whatever joystack.tests.json says.
+  joystack test … --list              Print what would run, and stop.
+
+Test files:
+  *.test.mjs    node tests (node:test). Run together, reported per file.
+  *.smoke.mjs   browser smokes. Run one at a time against a dev stack this command starts and stops.
+  Both can import the joystack doors (\`import { openWorld } from 'joystack/test'\`). That import only resolves
+  when the file is run by this command — \`node --test x.test.mjs\` fails with "Cannot find package 'joystack'".
+
+Reading the result:
+  The exit code is 0 only when everything passed. The console shows failures in full and passing tests
+  as counts. Every run also writes .joystack/test/last.json (the verdict: what failed, what was skipped,
+  seconds per file) and .joystack/test/last.log (the complete output). Read those instead of piping this
+  command through \`tail\` or \`grep\`: a pipe replaces the exit code with its own and cuts the diagnosis.
+
+A whole-suite run ends with its total against a budget: 300 seconds, or "budgetSeconds" in joystack.tests.json.
+Going over never fails the run; it recommends /compress-tests, the pass over the whole suite.
+
+A test that cannot run on some platform says so at the top of its file, and is reported as skipped there:
+  // skip-on: win32 — WebKit on Windows has no Web Audio
+
+Environment:
+  JOYSTACK_TEST_SMOKE_TIMEOUT=<seconds>  Kill a smoke still running after this long (default 600). A hang
+                                      detector, not a speed limit.
+  JOYSTACK_TEST_UNIT_TIMEOUT=<seconds>   The same for the node tests as a whole (default 1800).
+  JOYSTACK_TEST_NO_GPU=1                 Run smoke browsers on software rendering.
+  JOYSTACK_TEST_ANGLE=<backend>          Graphics backend for smoke browsers (Windows defaults to d3d11;
+                                      \`default\` lets the browser choose).
+`;
+
+export function parseTestArgs(args) {
+  const options = { patterns: [], all: false, list: false };
+  // Asking for help is never an error, whatever else is on the line.
+  if (args.includes('--help') || args.includes('-h')) return { ...options, help: true };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--all') options.all = true;
+    else if (arg === '--list') options.list = true;
+    else if (arg === '--since') {
+      const value = args[++i];
+      if (!value || value.startsWith('-')) throw new Error('test --since requires a git integration base');
+      options.since = value;
+    } else if (arg.startsWith('-')) throw new Error(`Unknown test option: ${arg}`);
+    else options.patterns.push(arg);
+  }
+  if ((options.all && options.since) || (options.patterns.length && (options.all || options.since))) throw new Error('Choose test <pattern>, test --since <base>, or test --all');
+  return options;
+}

package/lib/test-reporter.mjs

@@ -0,0 +1,177 @@
+// The node:test reporter `joystack test` runs its unit half with.
+//
+// It prints failures in full and everything else as counts, so the output of a
+// two-thousand-test suite fits on a screen and nobody needs to pipe it through
+// `tail` to read it. The complete per-test listing still exists: the runner
+// attaches node's own `spec` reporter to a file alongside this one.
+//
+// It also records what the default reporters do not: which FILE each result
+// belongs to and how long each file took. The record is written as JSON to the
+// path in JOYSTACK_TEST_UNIT_REPORT when the run ends; the runner folds it into
+// the verdict file.
+import { writeFileSync, realpathSync } from 'node:fs';
+import { relative, isAbsolute } from 'node:path';
+import { readEnv } from './legacy-names.mjs';
+
+const MAX_ERROR_LINES = 24;
+const SLOWEST_SHOWN = 5;
+
+// Events for one file can name it through different spellings of the same
+// path (macOS reports /var/… in one event and /private/var/… in another), so
+// both sides are resolved before the relative path is taken.
+const real = (path) => { try { return realpathSync.native(path); } catch { return path; } };
+
+// node names a whole-file result after the path the file was given by on the
+// command line, which may be relative or absolute.
+const isWholeFile = (data) => Boolean(data.file) && data.nesting === 0
+  && (data.name === data.file || real(data.name) === real(data.file) || data.file.endsWith(`/${data.name}`) || data.file.endsWith(`\\${data.name}`));
+
+function rel(file, root) {
+  if (!file) return '(unknown file)';
+  const path = isAbsolute(file) ? relative(real(root), real(file)) : file;
+  return path.split('\\').join('/');
+}
+
+// node wraps an assertion thrown inside a test in an ERR_TEST_FAILURE error
+// whose `cause` is the original; the original carries the message a reader wants.
+function describeError(error) {
+  const cause = error?.cause ?? error;
+  const message = String(cause?.message ?? cause ?? 'test failed');
+  const stack = typeof cause?.stack === 'string' ? cause.stack : '';
+  // Frames inside node itself say nothing about the game and push the frames
+  // that do off the screen; the full log keeps them.
+  const lines = (stack.includes(message) ? stack : `${message}\n${stack}`).split('\n')
+    .filter((line) => !/^\s*at .*\(?node:/.test(line));
+  const shown = lines.slice(0, MAX_ERROR_LINES);
+  if (lines.length > shown.length) shown.push(`… ${lines.length - shown.length} more line(s) in the full log`);
+  return { message, text: shown.join('\n') };
+}
+
+export function createCollector(root = process.cwd()) {
+  const files = new Map();
+  const failed = [];
+  const skipped = [];
+  const todos = [];
+  // Counts are singular (`fail`, `skip`); the lists of what failed and what was
+  // skipped take the past participle, so the two never share a key.
+  const totals = { tests: 0, pass: 0, fail: 0, skip: 0, todo: 0 };
+
+  const fileEntry = (file) => {
+    const key = rel(file, root);
+    if (!files.has(key)) files.set(key, { file: key, ms: 0, tests: 0, fail: 0, measured: false });
+    return files.get(key);
+  };
+
+  function record(type, data) {
+    // A `describe` block reports as an event of its own; counting it would
+    // count its tests twice.
+    if (data.details?.type === 'suite') return null;
+    const entry = fileEntry(data.file);
+    const duration = Number(data.details?.duration_ms) || 0;
+    // Top-level durations already include their subtests. A file's time is the
+    // sum of its top-level tests unless node reports a per-file figure (below).
+    if (data.nesting === 0 && !entry.measured) entry.ms += duration;
+    totals.tests += 1;
+    entry.tests += 1;
+    if (data.skip !== undefined && data.skip !== false) {
+      totals.skip += 1;
+      const item = { file: entry.file, name: data.name, reason: typeof data.skip === 'string' ? data.skip : '' };
+      skipped.push(item);
+      return { kind: 'skip', item };
+    }
+    if (data.todo !== undefined && data.todo !== false) {
+      totals.todo += 1;
+      const item = { file: entry.file, name: data.name, reason: typeof data.todo === 'string' ? data.todo : '' };
+      todos.push(item);
+      return { kind: 'todo', item };
+    }
+    // node reports a FILE as one passing test named after its own path only
+    // when the process ended cleanly without reporting any test of its own —
+    // which is what `process.exit(0)` at module level, or a helper that exits
+    // on import, produces. The tests in that file never ran, so it is a failure.
+    if (type === 'test:pass' && isWholeFile(data)) {
+      totals.fail += 1;
+      entry.fail += 1;
+      const message = 'this file exited before reporting any test — a `process.exit()` at module level (its own, or in something it imports) ended it, so none of its tests ran';
+      const item = { file: entry.file, name: '(the whole file)', message };
+      failed.push(item);
+      return { kind: 'fail', item, text: message };
+    }
+    if (type === 'test:pass') { totals.pass += 1; return null; }
+    totals.fail += 1;
+    entry.fail += 1;
+    let { message, text } = describeError(data.details?.error);
+    // A file that could not be loaded fails as a whole, and node's error for it
+    // says only "test failed"; what went wrong was written to the file's stderr.
+    const output = (stderrByFile.get(data.file) ?? '').trim();
+    if (isWholeFile(data) && output) {
+      const lines = output.split('\n').filter((line) => !/^\s*at .*\(?node:/.test(line));
+      message = lines.find((line) => /\w*Error\b/.test(line)) ?? lines[0];
+      text = lines.slice(0, MAX_ERROR_LINES).join('\n');
+    }
+    const item = { file: entry.file, name: isWholeFile(data) ? '(the whole file)' : data.name, message };
+    failed.push(item);
+    return { kind: 'fail', item, text };
+  }
+
+  // node ≥ 22.12 emits a summary per file with its wall time, which includes
+  // module load and top-level awaits that per-test durations leave out.
+  function summary(data) {
+    if (!data?.file || typeof data.duration_ms !== 'number') return;
+    const entry = fileEntry(data.file);
+    entry.ms = data.duration_ms;
+    entry.measured = true;
+  }
+
+  // What each test file wrote to stderr, kept only to explain a file-level failure.
+  const stderrByFile = new Map();
+  function stderr(data) {
+    if (!data?.file || typeof data.message !== 'string') return;
+    const so_far = stderrByFile.get(data.file) ?? '';
+    if (so_far.length < 16384) stderrByFile.set(data.file, so_far + data.message);
+  }
+
+  function result() {
+    const list = [...files.values()].map(({ measured, ...f }) => ({ ...f, ms: Math.round(f.ms) }));
+    list.sort((a, b) => b.ms - a.ms);
+    return { ...totals, failed, skipped, todos, files: list };
+  }
+
+  return { record, summary, stderr, result };
+}
+
+export function summaryLines(result, { seconds } = {}) {
+  const lines = [];
+  const took = seconds === undefined ? '' : ` in ${seconds.toFixed(1)}s`;
+  lines.push(`  node tests: ${result.tests} tests — ${result.pass} passed, ${result.fail} failed, ${result.skip} skipped${result.todo ? `, ${result.todo} todo` : ''}${took}`);
+  if (result.files.length > SLOWEST_SHOWN) {
+    lines.push(`  slowest node files: ${result.files.slice(0, SLOWEST_SHOWN).map((f) => `${f.file} ${(f.ms / 1000).toFixed(1)}s`).join(', ')}`);
+  } else if (result.files.length > 1) {
+    lines.push(`  node files: ${result.files.map((f) => `${f.file} ${(f.ms / 1000).toFixed(1)}s`).join(', ')}`);
+  }
+  return lines;
+}
+
+export default async function* joystackReporter(source) {
+  const collector = createCollector(process.cwd());
+  const started = Date.now();
+  for await (const event of source) {
+    if (event.type === 'test:pass' || event.type === 'test:fail') {
+      const outcome = collector.record(event.type, event.data);
+      if (outcome?.kind === 'fail') yield `  ✖ ${outcome.item.file} › ${outcome.item.name}\n${outcome.text.split('\n').map((l) => `      ${l}`).join('\n')}\n`;
+      if (outcome?.kind === 'skip') yield `  ⏭ ${outcome.item.file} › ${outcome.item.name} — skipped: ${outcome.item.reason || '(no reason given)'}\n`;
+      if (outcome?.kind === 'todo') yield `  ☐ ${outcome.item.file} › ${outcome.item.name} — todo, does not run${outcome.item.reason ? `: ${outcome.item.reason}` : ''}\n`;
+    } else if (event.type === 'test:summary') {
+      collector.summary(event.data);
+    } else if (event.type === 'test:stderr') {
+      collector.stderr(event.data);
+    }
+  }
+  const result = collector.result();
+  const seconds = (Date.now() - started) / 1000;
+  if (readEnv('JOYSTACK_TEST_UNIT_REPORT')) {
+    writeFileSync(readEnv('JOYSTACK_TEST_UNIT_REPORT'), JSON.stringify({ ...result, seconds }));
+  }
+  // No summary from here: the runner prints it once at the end of the whole
+  // run, with a wall time that includes node's start-up and module loading.
+}

package/lib/test-selection-cli.mjs

@@ -0,0 +1,18 @@
+// Adapter for runners with their own discovery rules. Stdout is NUL-delimited
+// selected paths; explanations go to stderr so filenames remain lossless.
+import { readTestPolicy, changedTestPaths, selectTests } from './test-policy.mjs';
+const [dir, since, ...files] = process.argv.slice(2);
+try {
+  const policy = readTestPolicy(dir, files);
+  let changed;
+  if (since !== '--all') {
+    try { changed = changedTestPaths(dir, since); }
+    catch (error) { console.error(`Cannot compare with ${since}: ${error.message}. Including all tests.`); }
+  }
+  const selection = selectTests({ dir, files, policy, changed, all: since === '--all' });
+  console.error(`Test selection: ${selection.reason}; ${selection.files.length} selected, ${selection.skipped.length} deferred.`);
+  process.stdout.write(selection.files.map((file) => file + '\0').join(''));
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/lib/update.mjs

@@ -0,0 +1,299 @@
+// `joystack update` — move this game to the latest Joystack: the engine bundle AND
+// the agent surface (skills + the Layer-0 managed block) that rides it.
+//
+// This is the ONLY command that writes to `.claude/skills/` or `AGENTS.md`.
+// `dev` and `publish` never touch them: an update is something a creator asks
+// for, not something that happens to them while they were doing something else.
+//
+// Because it writes into files the creator has in git, it OWES them a full
+// account of what it changed — every path, and whose it was. The `/update-joystack`
+// skill wraps this to walk them through the diff and offer the commit.
+import { findProject, resolveEngine } from './project.mjs';
+import { ensureEngine, readEnginePin, writeEnginePin } from './engine.mjs';
+import { reconcileAgentSurface } from './agent-surface.mjs';
+import { DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+import { login } from './login.mjs';
+import { compareVersions, renderReleases } from './changelog.mjs';
+import { syncCli, reportCli } from './self-update.mjs';
+import { fetchStatus, landedIn } from './feedback-sync.mjs';
+
+// The report is the point. A creator reading this must be able to answer, with
+// no further digging: what changed, was any of it mine, and what do I do now.
+function report(log, engineVersion, surface) {
+  const { placed = [], removed = [], lossy = [], backups = [], backupDir, adopted } = surface;
+  if (!placed.length && !removed.length && !lossy.length) {
+    log('   Your skills and instructions were already current.');
+    return;
+  }
+
+  log('');
+  log(`Joystack also updated this game's skills and instructions to match engine ${engineVersion}:`);
+  for (const f of placed) {
+    if (lossy.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+    else log(`   updated     ${f}`);
+  }
+  for (const f of removed) {
+    if (lossy.includes(f)) log(`   removed     ${f}   (retired by Joystack — it had local changes, see below)`);
+    else log(`   removed     ${f}   (retired by Joystack)`);
+  }
+  for (const f of lossy) {
+    if (!placed.includes(f) && !removed.includes(f)) log(`   OVERWROTE   ${f}   (it had local changes — see below)`);
+  }
+
+  if (lossy.length) {
+    // The overwrite is the contract (Joystack's files always land — keeping a
+    // local edit would freeze the file out of every future update), but the content is
+    // never gone: name both recovery routes and the one place local guidance
+    // is safe from updates.
+    log('');
+    log('   Files marked OVERWROTE had local changes that Joystack replaced. Nothing is');
+    log(`   lost: recover them with \`git diff\`${backupDir ? `, or from ${backupDir}` : ''}.`);
+    log('   Guidance you want to keep belongs in AGENTS.md, below the managed block —');
+    log('   updates never touch anything there.');
+  }
+
+  if (adopted && backups.length) {
+    // On adoption we cannot tell an untouched old platform file from one the
+    // creator edited — there is no ownership record to compare against, which
+    // is precisely why we're adopting. Most of these are just the previous
+    // version's files. Claiming "you edited these" would be a lie that alarms;
+    // saying nothing would risk a silent overwrite. State only what is true.
+    log('');
+    log(`   This game predates Joystack's skill updates, so those files had no`);
+    log(`   ownership record. Their previous contents are saved in ${backupDir}`);
+    log(`   — if you had edited any of them, your version is in there.`);
+  }
+
+  log('');
+  log("   These are Joystack's files inside your repo, so they show up in git as");
+  log("   changes you didn't make. Review them and save them with your next commit.");
+}
+
+export async function update({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  fetchImpl = fetch,
+  loginFn = login,
+  ensure = ensureEngine,
+  reconcile = reconcileAgentSurface,
+  syncCliFn = syncCli,
+  // `joystack update --rc <version>` — take an EXACT release candidate by reference.
+  target = null,
+} = {}) {
+  const project = findProject(cwd);
+  const from = readEnginePin(project.dir);
+
+  // Same login gate as every /api/creator endpoint.
+  if (!getToken()) {
+    log('Checking for engine updates needs your Joystack account.');
+    await loginFn({ apiBase, log });
+    if (!getToken()) throw new Error('login did not produce a token — run `joystack login` and retry.');
+  }
+
+  // ── Release-candidate lane ────────────────────────────────────────────────
+  // A candidate (`--rc 0.2.0-rc.1`) is UNLISTED: it never appears in `latest` or
+  // `joystack changelog`, so this lane bypasses the newest-stable comparison and
+  // installs the named version directly. Its changelog and any migration notes
+  // ship INSIDE the engine tarball (the docs the agent reads), not through the
+  // version-crossing callout the stable lane prints. syncCli runs FIRST for the
+  // same reason it does below — its npm install would prune the engine if it ran
+  // after the engine landed.
+  if (target) {
+    // Validate the version shape BEFORE anything mutates the repo. syncCli's npm
+    // install below prunes the engine, so a typo caught only after that point
+    // would leave the game engine-less on a bad pin. This mirrors the platform's
+    // ENGINE_VERSION_WITH_PRERELEASE_OK; a well-formed but unknown/removed
+    // candidate is still caught below by restoring the pin on a failed download.
+    if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$/.test(target)) {
+      throw new Error(`\`--rc\` needs a valid engine version like 0.2.0-rc.1 — got "${target}".`);
+    }
+    let cli;
+    try {
+      cli = await syncCliFn({ projectDir: project.dir, log });
+    } catch (err) {
+      cli = { updated: false, error: err };
+    }
+    writeEnginePin(project.dir, target);
+    let engine;
+    try {
+      engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+    } catch (err) {
+      // The candidate didn't download (a typo that still parsed, or one that was
+      // since removed). Restore the previous pin so the game isn't left pointing
+      // at a version that doesn't exist — the engine may have been pruned by the
+      // CLI install above, but is recoverable by a normal `joystack dev`/`update` on
+      // the restored pin. A game with no prior pin keeps none.
+      if (from) writeEnginePin(project.dir, from);
+      throw err;
+    }
+    const engineDir = engine.dir ?? null;
+    log('');
+    log(`✅ Engine candidate installed: ${from ?? '(none)'} → ${engine.version}`);
+
+    const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
+    if (!surface.skipped) report(log, surface.engineVersion ?? target, surface);
+
+    if (cli?.error) {
+      log('');
+      log(`   The joystack command could not be updated (${cli.error.message}).`);
+      log('   Retry with: npm update @joystack/cli');
+    } else {
+      reportCli(log, cli);
+    }
+
+    log('');
+    log('   This is a pre-release candidate — its changelog and any migration');
+    log('   notes ship inside the engine (read the handbook / engine docs), not');
+    log('   via `joystack changelog`. Republish (`npx joystack publish`) when ready.');
+    return { from, to: engine.version, updated: from !== engine.version, surface, crossed: null, cli, candidate: true };
+  }
+
+  const res = await fetchImpl(`${apiBase}/api/creator/engine`, {
+    headers: { Authorization: `Bearer ${getToken()}` },
+  });
+  if (res.status === 401) throw new Error('the platform rejected this machine’s token — run `joystack login` again.');
+  if (!res.ok) throw new Error(`could not list engine releases (HTTP ${res.status})`);
+  const { latest, releases } = await res.json();
+  if (!latest) throw new Error('the platform has no downloadable engine releases yet.');
+
+  // What the update is about to change UNDER the game.
+  // Reporting the skill files we rewrote and nothing about the engine was the
+  // whole gap: an agent crossed two versions of the shared library blind.
+  //
+  // A platform too old to serve `releases` must NOT block the update — it just
+  // has to be honest that it cannot say what changed. (`joystack changelog`, whose
+  // only job is to answer that question, refuses outright instead.)
+  // Newest first, to match `joystack changelog` and — more importantly — to match
+  // what renderReleases' own header SAYS. The endpoint returns them ascending;
+  // passing that straight through would print 0.1.13 above 0.1.14 under a
+  // heading that reads "newest first".
+  const crossed = Array.isArray(releases)
+    ? releases
+        .filter(
+          (r) => compareVersions(r.version, latest) <= 0 && (!from || compareVersions(r.version, from) > 0),
+        )
+        .sort((a, b) => compareVersions(b.version, a.version))
+    : null;
+
+  // ── The `joystack` command FIRST, before the engine lands ─────────────────────
+  //
+  // Order is load-bearing, and getting it wrong deleted the engine. The engine is
+  // not an npm package — it installs with `npm install --no-save`, so npm has no
+  // record of it and treats it as extraneous. ANY later `npm install` in the game
+  // prunes it. syncCli runs exactly such an install (`--save-dev` the new CLI), so
+  // running it AFTER the engine install wiped the engine every single time: the
+  // update reported success and left node_modules/@joystack/engine gone. The
+  // next `joystack lint` then found no engine at all (caught on a real game).
+  //
+  // So: do every npm install that this command is going to do BEFORE the engine
+  // is put on disk, and let the engine be the last thing to land.
+  //
+  // Wrapped: syncCli is already fail-soft, and a bug in it must not stop the
+  // engine update that is the point of this command.
+  let cli;
+  try {
+    cli = await syncCliFn({ projectDir: project.dir, log });
+  } catch (err) {
+    cli = { updated: false, error: err };
+  }
+
+  let engineDir = null;
+  let updated = false;
+
+  // Forward-only: `joystack update` moves a game to `latest` only when `latest` is
+  // actually NEWER than the pin. It never moves a game that is already on latest
+  // OR ahead of it — the latter is real now that release candidates exist: a
+  // testbed pinned to `0.2.0-rc.3` while the newest stable is `0.1.10` must not
+  // be silently DOWNGRADED to 0.1.10 (which would break every 0.2.0 API it uses)
+  // just because the plain `update` was run out of habit. `--rc` is the lane that
+  // moves onto a candidate; the stable lane only ever moves forward.
+  const cmp = from ? compareVersions(from, latest) : -1;
+  if (cmp >= 0) {
+    // On latest, or ahead of it on a pre-release. Reconcile the surface anyway —
+    // a repo can sit on the right engine with a STILL out-of-date surface (one
+    // scaffolded before this mechanism existed never had its skills adopted) —
+    // but never rewrite the pin.
+    const label = from ?? latest;
+    const ahead = cmp > 0;
+    try {
+      engineDir = resolveEngine(project.dir).dir;
+      log(
+        ahead
+          ? `✅ Engine ${label} — a pre-release ahead of the latest release (${latest}); not downgrading.`
+          : `✅ Engine ${label} — already up to date.`,
+      );
+    } catch {
+      // Pinned to this version, but NOT on disk. The pin is a claim about what
+      // this game runs; node_modules is the truth, and they disagree — because a
+      // plain `npm install` (the creator's own, or ours above) prunes the engine,
+      // which npm never recorded. "Already up to date" while the engine is missing
+      // is a lie that leaves every engine-reading command broken, and re-running
+      // update could never fix it. Put it back — from the local cache, so this is
+      // fast and works offline.
+      log(`Engine ${label} is pinned but missing from node_modules — reinstalling it.`);
+      const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+      engineDir = engine.dir ?? null;
+      log('');
+      log(`✅ Engine ${label} — restored.`);
+    }
+  } else {
+    // Rewrite the pin first; ensureEngine honors it (download → install → pin).
+    writeEnginePin(project.dir, latest);
+    const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+    engineDir = engine.dir ?? null;
+    updated = true;
+    log('');
+    log(`✅ Engine updated: ${from ?? '(none)'} → ${engine.version}`);
+  }
+
+  const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
+  if (!surface.skipped) report(log, surface.engineVersion ?? latest, surface);
+
+  // The third lane: the `joystack` command itself (see self-update.mjs). The skills
+  // we reconciled ship WITH the engine and can name any command they like — a real
+  // game ended up on an engine whose skills say `joystack changelog` while its CLI was
+  // four versions too old to have it. So update moves this too.
+  //
+  // It already RAN, at the top: its npm install has to happen before the engine
+  // lands or it prunes it. This is only the report.
+  if (cli?.error) {
+    log('');
+    log(`   The joystack command could not be updated (${cli.error.message}).`);
+    log('   Your engine and skills are up to date. Retry with: npm update @joystack/cli');
+  } else {
+    reportCli(log, cli);
+  }
+
+  // Feedback this repo filed that a crossed release resolved. Best-effort on
+  // purpose: the back-channel must never block or fail an engine update, so
+  // any error here (an older platform without the endpoint, offline after the
+  // download, a bad response) reduces to "no landings to report".
+  let landed = [];
+  if (updated) {
+    try {
+      landed = landedIn(await fetchStatus({ apiBase, fetchImpl }), { from, to: latest });
+    } catch {
+      landed = [];
+    }
+  }
+
+  if (updated) {
+    log('');
+    if (crossed === null) {
+      log('   This Joystack platform could not tell us what changed in the engine — no changelog');
+      log('   is available for the versions you just crossed.');
+    } else if (crossed.length) {
+      log(renderReleases(crossed, { pinned: from, latest }));
+    }
+    if (landed.length) {
+      log('');
+      log('   Feedback you filed landed in this update:');
+      for (const r of landed) log(`   • "${r.title}" — resolved in ${r.resolved_in}`);
+      log('   Run `npx joystack feedback` to pull the details into notes/feedback/.');
+    }
+    log('');
+    log('   Republish (`npx joystack publish`) when you want the live game on it.');
+  }
+  return { from, to: latest, updated, surface, crossed, cli, landed };
+}