@joystack/cli 0.0.0-stage → 0.1.43

package/lib/dev.mjs

@@ -0,0 +1,435 @@
+// `joystack dev` — the standalone two-service dev stack:
+//
+//   static :8000  game folder at /games/<slug>/, /shared/ → engine bundle,
+//                 head injection + auto-reload
+//   mp     :1999  local partykit running the BUNDLE's room-server code
+//
+// Multiplayer runs from minute one — the platform is not optional (the Next
+// analogy deliberately breaks there). NO_MP=1 opts out for purely-SP work.
+import { spawn } from 'node:child_process';
+import { terminateChildTree } from './process-tree.mjs';
+import { withoutAgentSession } from './agent-session.mjs';
+import { existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { findProject } from './project.mjs';
+import { ensureEngine } from './engine.mjs';
+import { createStaticServer } from './static-server.mjs';
+import { pruneOnStart } from './replay-store.mjs';
+import { resolvePorts, portInUse, killPort, lanIp, isRestricted, nextBrowserSafe } from './ports.mjs';
+import { assertNoInertOverride, isFrameworkV2, isSinglePlayerV2, scanPrimitives } from './primitives.mjs';
+import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
+import { createFileWatcher, createRoomReloader } from './room-reload.mjs';
+import { hasDeclaredAssets, assetsPageUrl } from './assets-page.mjs';
+import { openTunnel, shareBanner, engineCanShare } from './share.mjs';
+import { freezeGame } from './freeze.mjs';
+import { readEnv, stateDir } from './legacy-names.mjs';
+
+// Resolve the partykit CLI entry from OUR dependencies (the game never
+// declares partykit; it rides @joystack/cli). partykit's `exports` map hides
+// package.json from require.resolve, so walk node_modules dirs by hand.
+export function partykitBin() {
+  let dir = import.meta.dirname;
+  for (;;) {
+    const candidate = join(dir, 'node_modules', 'partykit', 'package.json');
+    if (existsSync(candidate)) {
+      const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+      const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin.partykit;
+      return join(dirname(candidate), bin);
+    }
+    const parent = dirname(dir);
+    if (parent === dir) throw new Error('partykit is not installed alongside @joystack/cli — reinstall the CLI.');
+    dir = parent;
+  }
+}
+
+// Resolves 'up' once the local room server answers an HTTP request, 'exited'
+// as soon as `alive()` says its process ended, and 'timeout' if it has not
+// answered within `timeoutMs`.
+// Any HTTP status counts: partykit answers `GET /` with a 404 as soon as it is
+// serving. An open port is not enough, because the port can accept a
+// connection and then drop it while the server finishes starting.
+export async function waitForRoomServer(port, { timeoutMs = 30_000, intervalMs = 50, alive = () => true, fetchFn = fetch } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!alive()) return 'exited';
+    try {
+      const res = await fetchFn(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(1000) });
+      // Releases the connection now instead of when the response is collected.
+      await res?.body?.cancel();
+      return 'up';
+    } catch {
+      /* not serving yet */
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return alive() ? 'timeout' : 'exited';
+}
+
+// Per-game server parity: a game with primitives of its own
+// (overrides/shared/ui/room/primitives/) runs its OWN room server in dev, built
+// from those classes. Without them, the engine's stock room server runs.
+//
+// The predicate is `isServerBacked` — the SAME one publish uses. If dev asked a
+// different question (e.g. "does a partykit.json exist", which nothing in this
+// CLI ever creates), dev and publish would disagree and a creator's primitive
+// would run in production but not on their own machine. One question, one
+// answer, both commands.
+
+// `share` opens a public link to the stack for testers (share.mjs); `openShare`
+// replaces the tunnel for tests.
+export async function dev(opts = {}) {
+  // Whatever startup has made so far, undone if a later step throws: a room
+  // build that fails on the creator's code, a port already taken, a tunnel
+  // that never opens. A frozen copy of the game is among it.
+  const undo = [];
+  try {
+    return await startDev(opts, (fn) => undo.push(fn));
+  } catch (err) {
+    for (const fn of undo.reverse()) {
+      try { fn(); } catch { /* the original error is the one to report */ }
+    }
+    throw err;
+  }
+}
+
+// `agentSession` is the coding-agent session to wake with agent-inbox reports
+// (agent-session.mjs). Only the interactive `joystack dev` and `joystack assets`
+// commands pass one; a stack started by `joystack test` or any other caller has
+// none, so no test run can wake the agent that started it.
+async function startDev({ cwd = process.cwd(), port, noMp = process.env.NO_MP === '1', watch = true, reload = true, share = false, openShare = openTunnel, log = console.log, agentSession = null } = {}, onFailure) {
+  const project = findProject(cwd);
+  // Q4 revision: the engine is not an npm dependency — install/refresh it from
+  // the platform's login-gated registry (no-op when the pinned version is in).
+  const engine = await ensureEngine(project.dir, { log });
+  if (share && !engineCanShare(engine.sharedDir)) {
+    throw new Error(
+      `joystack dev --share needs a newer engine than ${engine.version ?? 'the one this game is pinned to'}: ` +
+      'its pages cannot tell they were opened through the link, so they would record nothing. Run `npx joystack update`, then try again.',
+    );
+  }
+
+  // Any 3D model the entity definitions reference re-bakes when its GLB (or
+  // bake config) changed — the server must hit the surface the player sees. A
+  // bake failure stops the stack with the model named rather than serving a
+  // room that shoots at yesterday's shape.
+  const { ensureBaked } = await import('./model-bake.mjs');
+  await ensureBaked({ dir: project.dir, log });
+
+  // Recordings accumulate on the creator's own disk — every session played
+  // under `joystack dev` writes one — so the oldest go here, before anything can
+  // be watching one. The caps and the keep marker live in replay-store.mjs.
+  pruneOnStart({ projectDir: project.dir, log });
+
+  // `reload: false` (`joystack dev --no-reload`) freezes the game as it is now:
+  // pages are served, and the room is built, from a copy taken here, after the
+  // bake so baked models come with it, and nothing is watched. Recordings still
+  // land in the real folder. See freeze.mjs for why a copy is needed.
+  const frozen = reload ? null : freezeGame(project.dir);
+  if (frozen) onFailure(frozen.remove);
+  if (frozen) watch = false;
+  const codeDir = frozen?.dir ?? project.dir;
+
+  // Which ports, and may we take them? An explicit --port is obeyed as given
+  // (takeover included). With no flag we step around anyone else's stack —
+  // another lane, another game, an unrelated app — and only ever reclaim our
+  // OWN stale server. See ports.mjs; this is what makes a lane collision-free
+  // without the creator having to remember a flag.
+  const explicit = port ?? (readEnv('JOYSTACK_DEV_PORT') ? Number(readEnv('JOYSTACK_DEV_PORT')) : null);
+  const { ports, tookOver, steppedAside } = await resolvePorts({
+    projectDir: project.dir,
+    requested: explicit,
+  });
+  for (const s of steppedAside) {
+    const who = s.reason === 'browser-restricted'
+      ? 'browser-restricted (its multiplayer port would be blocked) — stepping past'
+      : `held by ${s.projectDir ? `another Joystack game (${basename(s.projectDir)})` : 'another app'} — leaving it alone`;
+    log(`→ :${s.port}  (${who})`);
+  }
+  // An EXPLICIT --port is obeyed as given, but if it derives a browser-blocked
+  // port (e.g. --port 8050 → mp 2049/NFS) the game would look broken with no
+  // clue, so say so loudly rather than silently binding it.
+  for (const [name, p] of [['multiplayer', ports.mp], ['static', ports.static]]) {
+    if (isRestricted(p)) {
+      log(`⚠ ${name} port :${p} is browser-restricted (ERR_UNSAFE_PORT) — browsers will refuse it. Re-run with a --port whose ${name} port is reachable (e.g. --port ${nextBrowserSafe(ports.static)}).`);
+    }
+  }
+  const children = [];
+  const servers = [];
+
+  // The game's own server code, if any. Built BEFORE any server binds a port —
+  // both because a malformed primitives folder should fail before we start
+  // taking over ports, and because this generates the merged browser registry
+  // the static server is about to mount. Building it after would leave a window
+  // where the page loads and predicts with the engine's classes instead.
+  //
+  // The inert-override check runs FIRST, before the scan. An override of, say,
+  // `primitives/effects.js` is a room-runtime file that merely happens to live in
+  // the primitives folder — scanned first, it would be reported as "a primitive
+  // with no default export", which is true and useless. Checked first, the
+  // creator is told the actual problem: the server cannot take this file.
+  assertNoInertOverride({ projectDir: codeDir, engine });
+  const serverPrimitives = scanPrimitives(codeDir);
+  const { cwd: roomServerCwd, inputs: roomInputs, skeleton: roomSkeleton = null } = await buildDevRoomServer({ projectDir: codeDir, engine });
+  const ownServer = roomServerCwd !== engine.roomServerDir;
+  // A single-player framework-v2 game (no config({ multiplayer: true })) runs its
+  // authoritative sim in-process via LocalRoom, so no room server is started.
+  const singlePlayer = isSinglePlayerV2({ projectDir: codeDir, skeleton: roomSkeleton });
+  const runsRoom = !(noMp || singlePlayer);
+  let tunnel = null;
+
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+    tunnel?.close();
+    for (const s of servers) s.close();
+    for (const c of children) terminateChildTree(c);
+    frozen?.remove();
+  };
+  onFailure(stop);
+
+  // ─── static ───
+  // `tookOver` is the ONLY licence to kill: an explicit --port, or our own
+  // stale server on this block. resolvePorts already walked away from
+  // everyone else's, so anything still here is fair game.
+  if (tookOver && (await portInUse(ports.static))) {
+    log(`→ static      :${ports.static}  (our stale server — reclaiming)`);
+    await killPort(ports.static);
+  }
+  // overrides/shared/… : the game's engine modifications mount ahead of the
+  // bundle and shadow it per-file — the same shadowing the publish resolve step
+  // applies in production.
+  //
+  // Two override layers, in precedence order:
+  //   1. GENERATED (.joystack/overrides/shared) — the merged primitive registry the
+  //      CLI writes for a game with server primitives, so the client predicts
+  //      with the game's classes. It goes first because it shadows a file
+  //      (primitives/index.js) the creator is not allowed to write themselves.
+  //   2. THE CREATOR'S (overrides/shared) — everything they wrote.
+  // Then the engine. First mount that HAS the file wins (static-server.mjs).
+  const generatedOverridesDir = join(stateDir(codeDir), 'overrides', 'shared');
+  const overridesDir = join(codeDir, 'overrides', 'shared');
+  const staticServer = createStaticServer({
+    slug: project.slug,
+    projectDir: project.dir, // answers /__joystack/whoami — see ports.mjs
+    log, // agent-inbox report lines ride the dev logger
+    engineVersion: engine.version ?? null, // stamped on agent-inbox reports
+    agentSession, // woken by agent-inbox reports sent from this machine
+    mounts: [
+      { url: `/games/${project.slug}/`, dir: codeDir },
+      { url: '/shared/', dir: generatedOverridesDir },
+      { url: '/shared/', dir: overridesDir },
+      { url: '/shared/', dir: engine.sharedDir },
+    ],
+    watchDirs: watch ? [codeDir, engine.sharedDir] : [],
+    injectReload: watch,
+    ...(frozen ? { fixedBuild: frozen.build } : {}),
+    // Present only for a framework-v2 game — injects the joystack import map + the
+    // lowered skeleton into the entry HTML so startGame() boots in the browser.
+    skeleton: roomSkeleton,
+    // Where the room's websocket is forwarded (the upgrade handler), so a page
+    // reached through the share link joins it on the static port alone.
+    roomPort: runsRoom ? ports.mp : null,
+  });
+  await staticServer.listen(ports.static);
+  servers.push(staticServer);
+  log(`→ static      :${ports.static}  (serving ${frozen ? `a copy of ${project.dir} as it is now` : project.dir}, engine ${engine.version}, auto-reload ${watch ? 'on' : 'off'})`);
+
+  // ─── multiplayer (partykit on the bundle's room code) ───
+  // A single-player game's client never opens a socket, so standing up partykit
+  // here just burns a port and a workerd process. Skip it, mirroring publish,
+  // which deploys no per-game room worker for the same game.
+  if (!runsRoom) {
+    log(
+      singlePlayer && !noMp
+        ? `→ multiplayer :${ports.mp}  (skipped — single-player; add config({ multiplayer: true }) to enable)`
+        : `→ multiplayer :${ports.mp}  (skipped — NO_MP=1)`,
+    );
+    // No room worker, but the client still assembles its graph against the injected
+    // skeleton — so a STRUCTURAL edit (new entity/trait) must rebuild the skeleton
+    // and push it to the static server, or the page reloads onto a stale skeleton
+    // and assembleGraph throws ("re-ran N ticks but the skeleton has M"). The full
+    // partykit reloader below does this as a side effect; single-player needs a
+    // stripped-down version with no child to respawn. (NO_MP on a real multiplayer
+    // game has no client to serve a skeleton to, so it needs none.)
+    if (singlePlayer && watch) {
+      const skelWatcher = createFileWatcher({
+        files: roomInputs,
+        dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(codeDir, d)),
+        onChange: async () => {
+          try {
+            const built = await buildDevRoomServer({ projectDir: codeDir, engine });
+            staticServer.setSkeleton(built.skeleton ?? null);
+            skelWatcher.setFiles(built.inputs);
+          } catch (err) {
+            log(`[skeleton] rebuild failed — fix the error and save again: ${err.message}`);
+          }
+        },
+      });
+      servers.push({ close: () => skelWatcher.close() });
+    }
+  } else {
+    if (tookOver && (await portInUse(ports.mp))) {
+      log(`→ multiplayer :${ports.mp}  (our stale server — reclaiming)`);
+      await killPort(ports.mp);
+    }
+    const spawnMp = (cwd) => {
+      const pk = spawn(
+        process.execPath,
+        [partykitBin(), 'dev', '--port', String(ports.mp), '--persist', join(tmpdir(), `joystack-partykit-${ports.mp}`)],
+        { cwd, stdio: ['ignore', 'pipe', 'pipe'], detached: true, env: withoutAgentSession(process.env) },
+      );
+      pk.stdout.on('data', () => {});
+      pk.stderr.on('data', (d) => {
+        const s = String(d);
+        if (/error/i.test(s)) log(`[partykit] ${s.trim()}`);
+      });
+      // A spawn that fails (ENOENT, EMFILE) emits 'error' and never 'exit';
+      // without a listener the event throws and takes the stack down.
+      pk.on('error', (err) => log(`[partykit] failed to start: ${err.message}`));
+      children.push(pk);
+      return pk;
+    };
+    const killMp = async (pk) => {
+      if (pk.pid == null) return;
+      // Keep ownership when termination fails so stop() can retry the tree.
+      // Child exit callbacks cannot run between these synchronous statements.
+      terminateChildTree(pk);
+      const idx = children.indexOf(pk);
+      if (idx !== -1) children.splice(idx, 1);
+      const exited = new Promise((resolveExit) => {
+        if (pk.exitCode !== null || pk.signalCode !== null) return resolveExit();
+        const onExit = () => {
+          pk.removeListener('exit', onExit);
+          pk.removeListener('error', onExit);
+          resolveExit();
+        };
+        pk.once('exit', onExit);
+        pk.once('error', onExit);
+      });
+      // partykit is a node wrapper forking workerd; if the tree ignores TERM,
+      // escalate — the port must be free before the replacement binds it.
+      const hardKill = setTimeout(() => {
+        try {
+          terminateChildTree(pk, 'SIGKILL');
+        } catch {
+          /* gone */
+        }
+      }, 2000);
+      hardKill.unref();
+      await exited;
+      clearTimeout(hardKill);
+      // The parent's exit is not the port's release: workerd is a separate
+      // process in the group and can hold the listening socket a beat longer.
+      // A replacement that binds too early dies on EADDRINUSE — killing a
+      // working room and leaving nothing. Wait until the port is actually free.
+      const deadline = Date.now() + 5000;
+      while ((await portInUse(ports.mp)) && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+    };
+    const pk = spawnMp(roomServerCwd);
+    // A game's own room carries one of three kinds of server code — creator
+    // primitives (named), a framework-v2 lowered bundle, or v1 entity
+    // components — and only the first has a list to print. Naming the kind
+    // keeps a v2 or component-backed game from logging a dangling "— ".
+    const ownServerDesc = serverPrimitives.length
+      ? `this game's OWN server — ${serverPrimitives.map((p) => p.type).join(', ')}`
+      : `this game's OWN server — ${isFrameworkV2(codeDir) ? 'framework v2' : 'entity components'}`;
+    log(
+      `→ multiplayer :${ports.mp}  (partykit on ${ownServer ? ownServerDesc : "the engine's room server"}, pid ${pk.pid})`,
+    );
+    // The stack is reported ready, and `joystack test` starts its smokes, only
+    // once the room server answers. On a game's first run partykit can take
+    // several seconds to start; a page opened before then logs a refused
+    // WebSocket connection, which fails any smoke that treats console errors
+    // as failures, even though the client reconnects moments later.
+    // A room server that exits during startup fails the stack here, naming the
+    // cause, rather than leaving every page to fail on a refused connection.
+    const room = await waitForRoomServer(ports.mp, { alive: () => pk.pid != null && pk.exitCode === null && pk.signalCode === null });
+    if (room === 'exited') throw new Error(`the multiplayer server (partykit on :${ports.mp}) stopped while starting — its errors are printed above with a [partykit] prefix`);
+    if (room === 'timeout') log(`[partykit] not answering on :${ports.mp} after 30s — the game will keep trying to connect`);
+
+    // The room bundle is frozen at build time, so the static watcher's page
+    // reload is only half the contract: an edit to anything the room runs on
+    // (entity data, a room override, a server sim) must also rebuild the room
+    // and restart its child, or the creator playtests against pre-edit
+    // adjudication with everything looking live — a failure `joystack test` is
+    // structurally blind to, because it boots fresh stacks.
+    //
+    // The watch set is the bundle's own input list (covers every file the room
+    // actually imports, wherever it lives) plus the room-shaped game trees for
+    // files that don't exist yet — a first primitive, a new entity, a new room
+    // override. overrides/ is deliberately scoped to its room subtree: editing
+    // a purely client-side override must not restart the room and reset its
+    // state mid-playtest.
+    let roomWatcher = null;
+    let roomCwd = roomServerCwd;
+    const reloader = createRoomReloader({
+      build: () => buildDevRoomServer({ projectDir: codeDir, engine }),
+      spawnChild: spawnMp,
+      killChild: killMp,
+      log,
+      onRebuilt: (built) => {
+        roomWatcher?.setFiles(built.inputs);
+        // Push the rebuilt skeleton to the static server so the client injects
+        // the SAME lowered graph the room now embeds — otherwise a v2 hot-reload
+        // leaves the page on the startup skeleton and assembleGraph throws on the
+        // next load (client "re-ran N ticks but the skeleton has M").
+        staticServer.setSkeleton(built.skeleton ?? null);
+        staticServer.roomRestarted();
+        // A rebuild can flip which server the game runs on (first primitive
+        // added, last one removed) — say so, or the startup line misleads for
+        // the rest of the session.
+        if (built.cwd !== roomCwd) {
+          roomCwd = built.cwd;
+          log(
+            `→ multiplayer :${ports.mp}  (now on ${roomCwd === engine.roomServerDir ? "the engine's room server" : "this game's OWN server"})`,
+          );
+        }
+      },
+    });
+    reloader.attach(roomServerCwd, pk);
+    roomWatcher = watch ? createFileWatcher({
+      files: roomInputs,
+      dirs: ['entities', 'components', 'overrides/shared/ui/room'].map((d) => join(codeDir, d)),
+      onChange: reloader.onChange,
+    }) : null;
+    // stop() (e.g. `joystack test` tearing down its stack) must also stop the
+    // reloader: a rebuild in flight would otherwise spawn a replacement room
+    // child AFTER the children list was killed — a leaked detached process.
+    servers.push({
+      close: () => {
+        reloader.stop();
+        roomWatcher?.close();
+      },
+    });
+  }
+
+  const url = `http://localhost:${ports.static}/games/${project.slug}/index.html`;
+  const ip = lanIp();
+  log('');
+  log('────────────────────────────────────────────────────────────');
+  log(`✅ ${project.slug} ready. Open:`);
+  log(`   ${url}`);
+  if (ip) log(`   📱  http://${ip}:${ports.static}/games/${project.slug}/index.html   (phone / LAN)`);
+  // Only when this game declares assets (inspect.mjs). A line printed on every
+  // single boot is a line nobody reads by the third one, and the tool it points
+  // at is then invisible exactly when it would have helped.
+  if (hasDeclaredAssets(project.dir)) {
+    log(`   🔍  ${assetsPageUrl(url)}   (your models, sounds and assets, one at a time)`);
+  }
+  if (share) {
+    log('');
+    log('→ share       opening a public link (cloudflared)…');
+    tunnel = await openShare({ port: ports.static }); // a failure stops the stack (see dev)
+    staticServer.setShareHost(tunnel.hostname);
+    for (const line of shareBanner({ url: tunnel.url, gamePath: `/games/${project.slug}/index.html`, resolved: tunnel.resolved, frozen: !!frozen })) log(line);
+    tunnel.exited.then(() => {
+      if (!stopped) log('⚠ the share link stopped working (cloudflared exited). Restart `joystack dev --share` for a new one.');
+    });
+  }
+  log('────────────────────────────────────────────────────────────');
+
+  return { project, engine, ports, url, shareUrl: tunnel ? `${tunnel.url}/games/${project.slug}/index.html` : null, frozenDir: frozen?.dir ?? null, stop };
+}

package/lib/engine.mjs

@@ -0,0 +1,198 @@
+// ensureEngine — make the engine present before dev/publish (Q4 revision:
+// the engine is NOT an npm package; npm ships only this CLI).
+//
+// The engine installs from the platform's release registry via the
+// LOGIN-GATED /api/creator/engine lane — every download maps to a creator
+// account (attribution, revocation, and the /activate approval as the terms
+// gate). The flow, Playwright-style (npm tool + vendor-served artifact):
+//
+//   1. honor the game's `joystack.engine` pin in package.json (written on first
+//      install, so repeat runs are reproducible and offline-friendly)
+//   2. if the installed node_modules/@joystack/engine already matches → done
+//   3. otherwise: auto-run the device-flow login when the machine has no
+//      token, download the release tarball (cached in ~/.joystack/cache — a
+//      later `npm install` may prune the engine from node_modules; the cache
+//      makes the self-heal local), `npm install --no-save` it, write the pin.
+//
+// JOYSTACK_ENGINE_TARBALL=<path> short-circuits the network — the offline/smoke
+// lane (packed-install smoke, air-gapped work against a local build).
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { runNpm } from './npm.mjs';
+import { resolveEngine } from './project.mjs';
+import { cacheDir, DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+import { login } from './login.mjs';
+import { leaveJoystackNodeDoors } from './joystack-node-doors.mjs';
+import { LEGACY_ENGINE_PACKAGE, gameConfig, gameConfigKey, readEnv } from './legacy-names.mjs';
+
+// An engine package that installed under the name releases before 0.2.36 use.
+function olderEngineError(projectDir, version) {
+  if (!existsSync(join(projectDir, 'node_modules', ...LEGACY_ENGINE_PACKAGE.split('/'), 'package.json'))) return null;
+  return new Error(
+    `engine ${version} predates this CLI, which runs engine 0.2.36 and later: pin a newer engine in package.json and retry.`,
+  );
+}
+
+export function readEnginePin(projectDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+    const pin = gameConfig(pkg).engine;
+    return typeof pin === 'string' ? pin : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeEnginePin(projectDir, version) {
+  const pkgPath = join(projectDir, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  const key = gameConfigKey(pkg);
+  pkg[key] = { ...pkg[key], engine: version };
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+}
+
+function installedEngine(projectDir) {
+  try {
+    return resolveEngine(projectDir);
+  } catch {
+    return null;
+  }
+}
+
+// `npm install --no-save <tgz>` — npm extracts the package into
+// node_modules/@joystack/engine AND installs its runtime dependencies
+// (the room server's bare imports), without touching package.json.
+function npmInstallTarball(projectDir, tgzPath) {
+  runNpm(['install', '--no-save', '--no-audit', '--no-fund', resolve(tgzPath)], {
+    cwd: projectDir,
+    stdio: 'pipe',
+  });
+}
+
+/**
+ * The engine, present — plus the `node_modules/joystack` package that tells anyone
+ * running a test file with bare `node` to use `joystack test` instead
+ * (joystack-node-doors.mjs).
+ *
+ * The moment those doors are wanted is the moment somebody runs a test file by
+ * hand, which is not a moment any CLI command is watching — so they are left
+ * behind in advance, by whatever ran last. `create` and `dev` come through
+ * here; `joystack test` does not, and writes them itself (test-cmd.mjs).
+ */
+export async function ensureEngine(projectDir, opts = {}) {
+  const engine = await installEngine(projectDir, opts);
+  leaveJoystackNodeDoors(projectDir, engine);
+  return engine;
+}
+
+async function installEngine(
+  projectDir,
+  {
+    apiBase = getApiBase(DEFAULT_API_BASE),
+    log = console.log,
+    fetchImpl = fetch,
+    loginFn = login,
+    installTarball = npmInstallTarball,
+    tarballOverride = readEnv('JOYSTACK_ENGINE_TARBALL'),
+    dirOverride = readEnv('JOYSTACK_ENGINE_DIR'),
+  } = {},
+) {
+  // Before the pin, before the installed copy, before the network: an explicit
+  // checkout is the most specific thing anyone can ask for.
+  if (dirOverride) {
+    // resolveEngine owns the override for EVERY tool (project.mjs) — this only
+    // announces it, so the banner and the lint can never disagree about which
+    // engine is in play.
+    const e = resolveEngine(projectDir);
+    log(`→ engine      ${e.version} from JOYSTACK_ENGINE_DIR (${e.dir}) — nothing installed`);
+    return e;
+  }
+
+  let pin = readEnginePin(projectDir);
+
+  const installed = installedEngine(projectDir);
+  if (installed && (!pin || installed.version === pin)) {
+    // Adopt a pre-existing install (e.g. the npm-distribution era) as the pin.
+    if (!pin) writeEnginePin(projectDir, installed.version);
+    return installed;
+  }
+
+  // Offline/smoke lane: a local tarball wins over everything network.
+  if (tarballOverride) {
+    log(`Installing the engine from ${tarballOverride}…`);
+    installTarball(projectDir, tarballOverride);
+    const engine = installedEngine(projectDir);
+    if (!engine) throw olderEngineError(projectDir, tarballOverride) ?? new Error(`installing ${tarballOverride} did not produce node_modules/@joystack/engine`);
+    if (pin && engine.version !== pin) {
+      log(`  (note: this tarball is ${engine.version}; the game pinned ${pin} — pin updated)`);
+    }
+    writeEnginePin(projectDir, engine.version);
+    return engine;
+  }
+
+  // The download lane is login-gated: no token → run the device flow now.
+  if (!getToken()) {
+    log('The Joystack engine is downloaded from the platform and needs your account.');
+    await loginFn({ apiBase, log });
+    if (!getToken()) throw new Error('login did not produce a token — run `joystack login` and retry.');
+  }
+  const auth = { Authorization: `Bearer ${getToken()}` };
+
+  if (!pin) {
+    const res = await fetchImpl(`${apiBase}/api/creator/engine`, { headers: auth });
+    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 } = await res.json();
+    if (!latest) throw new Error('the platform has no downloadable engine releases yet.');
+    pin = latest;
+  }
+
+  const cache = cacheDir();
+  const cached = join(cache, `engine-${pin}.tgz`);
+  // A release candidate (a `-suffix` pin) is MUTABLE — the same label can be
+  // re-cut with new bytes — so its cache entry can be stale. Always re-download
+  // a candidate; the content-addressed stable releases are safe to cache forever.
+  const isCandidate = pin.includes('-');
+  if (!existsSync(cached) || isCandidate) {
+    log(`Downloading engine ${pin} from ${apiBase}…`);
+    const dlUrl = `${apiBase}/api/creator/engine/${pin}`;
+    let res = await fetchImpl(dlUrl, { headers: auth });
+    // 403 = the token is fine but the platform refuses with a reason the
+    // human must act on — today, an updated Engine License that needs
+    // re-accepting. The acceptance IS the browser approval step of the device
+    // flow, so run the flow right here instead of asking the human to type
+    // `joystack login` themselves (the click in the browser is still theirs to
+    // make), then retry once with the fresh token. If the platform still says
+    // no, surface its words — never loop.
+    if (res.status === 403) {
+      const reason = (await res.json().catch(() => null))?.error;
+      log(reason || 'The platform refused the engine download — your sign-in needs a refresh.');
+      log('Opening the sign-in flow to sort that out…');
+      await loginFn({ apiBase, log });
+      res = await fetchImpl(dlUrl, { headers: { Authorization: `Bearer ${getToken()}` } });
+      if (res.status === 403) {
+        const still = (await res.json().catch(() => null))?.error;
+        throw new Error(still || reason || 'the platform refused the engine download (HTTP 403).');
+      }
+    }
+    if (res.status === 401) throw new Error('the platform rejected this machine’s token — run `joystack login` again.');
+    if (res.status === 404) throw new Error(`engine ${pin} is not downloadable — check the \`joystack.engine\` pin in package.json.`);
+    if (!res.ok) throw new Error(`engine download failed (HTTP ${res.status})`);
+    mkdirSync(cache, { recursive: true });
+    // Write-then-rename so a killed download never leaves a truncated .tgz
+    // behind as a valid-looking cache entry.
+    const partial = `${cached}.partial`;
+    writeFileSync(partial, Buffer.from(await res.arrayBuffer()));
+    renameSync(partial, cached);
+  }
+
+  log(`Installing engine ${pin}…`);
+  installTarball(projectDir, cached);
+  const engine = installedEngine(projectDir);
+  if (!engine) throw olderEngineError(projectDir, pin) ?? new Error('engine install did not produce node_modules/@joystack/engine');
+  if (engine.version !== pin) {
+    throw new Error(`installed engine reports ${engine.version} but ${pin} was requested — corrupt cache? Delete ${cached} and retry.`);
+  }
+  writeEnginePin(projectDir, pin);
+  return engine;
+}