@joystack/cli 0.0.0-stage → 0.1.43

package/lib/inject.mjs

@@ -0,0 +1,250 @@
+// HTML/JS dev-serving transforms:
+//
+//   * Head injection mirrors the production serve path's entryHeadBlock
+//     (backend/api/src/lib/inject.js): window.GAME_SLUG + window.JOYSTACK_IDENTITY
+//     (classic scripts, so globals exist before any module runs) + the ONE
+//     platform-layer module tag. A global the production path also sets under
+//     its old name (LEGACY_PAGE_GLOBALS) is set under both names here too. New
+//     platform features are added to shared/platform/platform.js FEATURES —
+//     never here.
+//   * ?v=<stamp> rewriting on <script src> and JS imports busts Chrome's
+//     sticky module cache on edit.
+import { readFileSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { LEGACY_PAGE_GLOBALS, withLegacyDoors } from './legacy-names.mjs';
+
+// The identity every `joystack dev` page is signed in as.
+export const DEV_IDENTITY = { userId: 'dev-local-user', name: 'Dev', color: '#38bdf8' };
+
+export const PLATFORM_URL = '/shared/platform/platform.js';
+// The dev toolbox — injected ONLY here, never by the production serve path
+// (backend/api/src/lib/inject.js). That separation is the gate
+// that keeps a dev surface off published pages: the production injector never
+// names this module, so there is nothing to strip and nothing to trust.
+export const TOOLBOX_URL = '/shared/ui/toolbox/toolbox.js';
+
+// JSON safe for an inline <script>: `<` → < so a value containing
+// "</script>" can't terminate the script early.
+function jsJson(value) {
+  return JSON.stringify(value).replaceAll('<', '\\u003c');
+}
+
+// A framework-v2 game imports the bare `joystack[/subpath]` specifiers — the only
+// bare specifiers any browser game uses. The browser needs an import map to
+// resolve them to the framework runtime under the (already-mounted) /shared/
+// tree. This set is the import surface (shared/docs/api.md); keep it in sync
+// with V2_BARE_SPECIFIERS in backend/api/src/lib/inject.js.
+const V2_IMPORTS = {
+  joystack: '/shared/framework/runtime/joystack.js',
+  'joystack/traits': '/shared/framework/runtime/traits.js',
+  'joystack/client': '/shared/framework/runtime/client.js',
+  'joystack/renderers/canvas': '/shared/framework/runtime/renderers/canvas.js',
+  'joystack/renderers/three': '/shared/framework/runtime/renderers/three.js',
+  // The real harness (runtime/test.js) is Node-only. The browser gets a shim that
+  // throws a clear "Node-only" error, so a stray `import 'joystack/test'` in game code
+  // never white-screens on a node:fs load. Node resolves joystack/test via the build
+  // register hook (expand.js), which points at the real test.js regardless.
+  'joystack/test': '/shared/framework/runtime/test-browser.js',
+  // three, mapped to the engine's own vendored same-origin copy so a three-backed
+  // game needs no import map of its own (kept in sync with V2_BARE_SPECIFIERS).
+  three: '/shared/ui/room/vendor/three.js',
+};
+
+// One classic script setting a page global, and its old name when the
+// production serve path sets one too.
+function setGlobal(scope, name, value) {
+  const old = LEGACY_PAGE_GLOBALS[name];
+  return `<script>${scope}.${name} = ${old ? `${scope}.${old} = ` : ''}${jsJson(value)};</script>`;
+}
+
+export function injectHeadTags(html, slug, { identity = DEV_IDENTITY, platformUrl = PLATFORM_URL, toolbox = false, toolboxUrl = TOOLBOX_URL, skeleton = null, shareHost = null } = {}) {
+  const parts = [];
+  // A framework-v2 game resolves `joystack`/`joystack/client` through an import map and
+  // reads its lowered graph from globalThis.__JOYSTACK_SKELETON__. BOTH must precede
+  // any module script (the platform tag AND game.js): a browser ignores an import
+  // map once a module has begun executing, and startGame() reads the skeleton at
+  // module-eval time. So they go FIRST.
+  if (skeleton) {
+    parts.push(`<script type="importmap">${jsJson({ imports: withLegacyDoors(V2_IMPORTS) })}</script>`);
+    parts.push(setGlobal('globalThis', '__JOYSTACK_SKELETON__', skeleton));
+  }
+  // A page served through `joystack dev --share`'s tunnel: the hostname it was
+  // shared on, which the engine's isSharedDevPage compares with the page's own
+  // before treating a public name as a dev page. Ahead of every module script,
+  // like the skeleton, because the room transport reads it as the game boots.
+  if (shareHost) parts.push(`<script>window.JOYSTACK_DEV_SHARE = ${jsJson(shareHost)};</script>`);
+  if (slug) parts.push(`<script>window.GAME_SLUG = ${jsJson(slug)};</script>`);
+  parts.push(setGlobal('window', 'JOYSTACK_IDENTITY', identity));
+  parts.push(
+    `<script type="module">import { installPlatform } from "${platformUrl}"; installPlatform();</script>`,
+  );
+  // Dev-only, opt-in per request: the server sets `toolbox` only when the
+  // resolved engine bundle carries the module (inject-if-present), so an older
+  // pinned engine under a newer CLI never gets a 404ing tag. Behind the
+  // platform tag — the boot gate's error handlers come up first.
+  if (toolbox) {
+    parts.push(
+      `<script type="module">import { ensureToolbox } from "${toolboxUrl}"; ensureToolbox();</script>`,
+    );
+  }
+  const inject = '\n  ' + parts.join('\n  ');
+  const m = /<head[^>]*>/i.exec(html);
+  if (m) return html.slice(0, m.index + m[0].length) + inject + html.slice(m.index + m[0].length);
+  return parts.join('\n') + '\n' + html;
+}
+
+// Match `import ... from "X"`, `import "X"`, `import("X")`, `export ... from "X"`.
+const JS_IMPORT_RE = /(\b(?:from|import)\s*\(?\s*)(['"])([^'"\n]+?)\2/g;
+// Match <script src="X"> in HTML.
+const HTML_SCRIPT_RE = /(<script\b[^>]*?\bsrc\s*=\s*["'])([^"']+?)(["'])/gi;
+
+// A spec that can never name a local file the server would stamp: absolute
+// URLs, data:/blob:, and anything already carrying a query or fragment.
+function isExternalSpec(spec) {
+  return (
+    /^(https?:)?\/\//.test(spec) ||
+    spec.startsWith('data:') ||
+    spec.startsWith('blob:') ||
+    spec.includes('?') ||
+    spec.includes('#')
+  );
+}
+
+// Resolve an import specifier the way the BROWSER does — against the importing
+// module's URL — returning an absolute URL path, or null for bare/external
+// specs. Stamping must live in URL space because that is where module identity
+// lives: an engine file's relative sibling import can be shadowed by the
+// game's overrides mount, so the file the URL serves is not the file that sits
+// next to the importer on disk.
+function resolveSpecToUrl(spec, baseUrl, { allowBareRelative = false } = {}) {
+  if (isExternalSpec(spec)) return null;
+  if (spec.startsWith('/')) return spec;
+  if (!spec.startsWith('.') && !allowBareRelative) return null; // bare module specifier
+  try {
+    return new URL(spec, 'http://x' + baseUrl).pathname;
+  } catch {
+    return null;
+  }
+}
+
+// The version stamp is the max mtime over the module's TRANSITIVE static
+// import closure, not the file's own mtime. Module identity is the full URL,
+// and a browser may reuse a cached body for an unchanged URL across reloads
+// (Chrome's memory cache does not honor no-store for same-URL subresources).
+// A per-target stamp renames only the edited file's URL — its importers' URLs
+// stay put, so a reloading page reassembles the whole pre-edit graph from
+// cache with zero requests and no error anywhere. Stamping the closure renames
+// every URL on the path from the entry (which a navigation always re-fetches),
+// so no URL-keyed cache can serve stale bytes.
+//
+// The parse cache stores RAW specifiers keyed by file path + mtime; resolution
+// happens per walk, because the same file's specs resolve differently through
+// different mount tables (two servers in one process must not contaminate each
+// other). Boundary: only string-literal static/dynamic imports are seen —
+// import(expr) and new URL(...) are runtime-computed and stay unstamped.
+const parseCache = new Map(); // abs fs path -> { mtimeMs, specs: string[] }
+
+function fileInfo(path) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch {
+    return null;
+  }
+  const hit = parseCache.get(path);
+  if (hit && hit.mtimeMs === st.mtimeMs && hit.ctimeMs === st.ctimeMs && hit.size === st.size) return hit;
+  const specs = [];
+  if (/\.(js|mjs)$/.test(path)) {
+    let text = null;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch {
+      /* unreadable: stamp from its own mtime alone */
+    }
+    if (text !== null) {
+      for (const m of text.matchAll(JS_IMPORT_RE)) {
+        if (!isExternalSpec(m[3])) specs.push(m[3]);
+      }
+    }
+  }
+  const info = { mtimeMs: st.mtimeMs, ctimeMs: st.ctimeMs, size: st.size, specs };
+  parseCache.set(path, info);
+  return info;
+}
+
+// A rewrite shares resolved nodes across all import closures. Each URL is
+// resolved/stat'ed once even when several roots reach it. The cache belongs to
+// this synchronous rewrite only: the next request observes edits, deletions and
+// newly-created overrides immediately, without waiting for the reload watcher.
+function rewriteContext(resolveUrl) {
+  const nodes = new Map();
+  return {
+    stamps: new Map(),
+    node(url) {
+      if (!nodes.has(url)) {
+        const path = resolveUrl(url);
+        nodes.set(url, path ? fileInfo(path) : null);
+      }
+      return nodes.get(url);
+    },
+  };
+}
+
+function closureStampUrl(urlPath, context) {
+  if (context.stamps.has(urlPath)) return context.stamps.get(urlPath);
+  let max = 0;
+  const seen = new Set();
+  const stack = [urlPath];
+  while (stack.length) {
+    const url = stack.pop();
+    if (seen.has(url)) continue;
+    seen.add(url);
+    const info = context.node(url);
+    if (!info) continue;
+    max = Math.max(max, info.mtimeMs);
+    for (const spec of info.specs) {
+      const child = resolveSpecToUrl(spec, url);
+      if (child) stack.push(child);
+    }
+  }
+  const stamp = max ? Math.floor(max) : null;
+  context.stamps.set(urlPath, stamp);
+  return stamp;
+}
+
+// Resolve `relPath` and return `<relPath>?v=<closure-stamp>` or null. Stamped
+// extensions include .json: entity/config data is imported by games, and its
+// URL must rename on edit exactly like a module's.
+//
+// `baseUrl` + `resolveUrl` are REQUIRED for stamping: there is deliberately no
+// disk-space fallback. Resolving a relative spec beside the importer on disk
+// stamps the wrong file whenever a mount shadows it (the overrides mechanism),
+// which silently re-opens the staleness hole. No serving context → no stamp.
+function versionedPath(relPath, { baseUrl, resolveUrl, allowBareRelative = false, context }) {
+  if (!/\.(js|mjs|json)$/.test(relPath)) return null;
+  if (baseUrl == null || !resolveUrl) return null;
+  const urlTarget = resolveSpecToUrl(relPath, baseUrl, { allowBareRelative });
+  if (!urlTarget) return null;
+  if (!context.node(urlTarget)) return null;
+  const stamp = closureStampUrl(urlTarget, context);
+  return stamp === null ? null : `${relPath}?v=${stamp}`;
+}
+
+export function rewriteJsImports(text, { baseUrl, resolveUrl }) {
+  const context = rewriteContext(resolveUrl);
+  return text.replace(JS_IMPORT_RE, (whole, prefix, quote, path) => {
+    const v = versionedPath(path, { baseUrl, resolveUrl, context });
+    return `${prefix}${quote}${v ?? path}${quote}`;
+  });
+}
+
+export function rewriteHtmlScripts(html, { baseUrl, resolveUrl }) {
+  const context = rewriteContext(resolveUrl);
+  return html.replace(HTML_SCRIPT_RE, (whole, prefix, path, suffix) => {
+    const v = versionedPath(path, { baseUrl, resolveUrl, allowBareRelative: true, context });
+    return `${prefix}${v ?? path}${suffix}`;
+  });
+}
+
+// For callers that need the base dir of a served file.
+export { dirname };

package/lib/joystack-node-doors.mjs

@@ -0,0 +1,230 @@
+// A `node_modules/joystack` package, written into a game so that running one of
+// its test files with bare `node` says what to run instead.
+//
+// The joystack doors (`joystack`, `joystack/test`, `joystack/traits`, …) are bare
+// specifiers with nothing behind them on disk: the CLI maps them with a Node
+// resolver hook it registers before running a test
+// (shared/framework/build/joystack-test-preload.mjs). Run a test file any other
+// way and Node reports `Cannot find package 'joystack' imported from <file>` —
+// true, and useless: it names no fix, and the nearest thing that looks like one
+// is the engine's own preload, which is a private build file no game should be
+// reaching for.
+//
+// This package is what Node finds instead. It is never consulted under the CLI:
+// the resolver hook short-circuits every door specifier before Node looks in
+// node_modules, so these files are reached only by a process that has no
+// resolver — which is exactly the process that needs telling.
+//
+// THE GENERATED DOORS IMPORT NOTHING. Every name a door exports is emitted as a
+// literal, and the engine module behind it is never named. Two things go wrong
+// the moment a door imports the real one instead:
+//
+//   • Node links a whole static graph before it evaluates any of it, so a door
+//     that re-exported the engine could not register the resolver first however
+//     it was ordered. `joystack/renderers/three` reaches `/shared/…` statically and
+//     died on that, reporting an engine source file the reader has never opened
+//     — further from the fix than the error being replaced.
+//   • esbuild resolves bare specifiers through node_modules. The room-server
+//     build (room-server.mjs) deliberately refuses the browser-only doors so
+//     that server code importing one fails LOUDLY; a door that pulled in the
+//     engine's Node build layer turned that one clear refusal into six
+//     unresolved built-in modules, none of them mentioning joystack.
+//
+// Emitting names as literals means knowing them, so they are read from the real
+// doors once per engine version, in a child process that has the resolver (see
+// readDoorExports). A door then both exports every name and throws on
+// evaluation: the export list is what lets `import { openWorld } from
+// 'joystack/test'` link at all — Node checks imported names before a module body
+// runs, so a door with no exports would report a missing export instead of the
+// message.
+//
+// It REFUSES rather than works, deliberately: `joystack test` is the single way a
+// test runs, because the CLI is also what serves the page a smoke drives, what
+// decides which tests a change needs, and what records the verdict.
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { leaveLegacyEnginePath } from './legacy-names.mjs';
+
+// The doors, as the resolver maps them (the `doors` map in
+// shared/framework/build/expand.js, exported as JOYSTACK_DOORS and compared
+// against this list by joystack-node-doors.test.mjs). A door missing here still
+// fails with `Cannot find package 'joystack'` outside the CLI.
+export const DOORS = [
+  'joystack',
+  'joystack/traits',
+  'joystack/client',
+  'joystack/test',
+  'joystack/smoke',
+  'joystack/renderers/canvas',
+  'joystack/renderers/three',
+];
+
+// `joystack/renderers/canvas` → `renderers-canvas.js`; the root door → `index.js`.
+const fileFor = (door) => (door === 'joystack' ? 'index.js' : `${door.slice('joystack/'.length).replaceAll('/', '-')}.js`);
+const subpathFor = (door) => (door === 'joystack' ? '.' : `./${door.slice('joystack/'.length)}`);
+
+const MESSAGE_LINES = (door) => [
+  `joystack: this file imports \`${door}\`, and the joystack doors only resolve under the CLI —`,
+  'it registers a Node resolver for them before it runs a test file.',
+  '',
+  '  Run this file as:  npx joystack test <name>',
+  '',
+  "<name> matches part of the file's name, so `npx joystack test pickup` runs pickup.test.mjs.",
+  'The CLI is also what serves the page a smoke drives, what decides which tests a change',
+  'needs, and what writes the result to .joystack/test/ — running the file by hand gives up all three.',
+];
+
+/**
+ * The names each door exports, read from the real doors.
+ *
+ * In a child process, because reading them means importing them and importing
+ * them means registering the resolver hook — a process-wide change no command
+ * should carry for the sake of an error message. The child gets the engine's own
+ * preload, which is the same way `joystack test` runs a test file.
+ *
+ * @returns {Record<string, string[]>|null} null when the engine cannot be read
+ *   that way at all, in which case nothing is written and the bare-node error
+ *   stays as it was
+ */
+export function readDoorExports(engineDir, { spawn = spawnSync } = {}) {
+  const preload = pathToFileURL(join(engineDir, 'shared', 'framework', 'build', 'joystack-test-preload.mjs')).href;
+  const script = [
+    `const doors = ${JSON.stringify(DOORS)};`,
+    'const out = {};',
+    'for (const door of doors) {',
+    // A door that cannot be imported gets an empty list rather than failing the
+    // read: six working doors and one bare one beats none at all.
+    '  try { out[door] = Object.keys(await import(door)).filter((n) => n !== "default"); }',
+    '  catch { out[door] = []; }',
+    '}',
+    'process.stdout.write(JSON.stringify(out));',
+  ].join('\n');
+
+  const res = spawn(process.execPath, ['--import', preload, '--input-type=module', '--eval', script], {
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+  if (res.status !== 0 || !res.stdout) return null;
+  try {
+    const parsed = JSON.parse(res.stdout);
+    return DOORS.every((d) => Array.isArray(parsed[d])) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Write only what changed: this runs on every command that resolves the engine,
+// and a rewritten file every time would churn the mtimes a watcher reads.
+function put(path, content) {
+  try {
+    if (readFileSync(path, 'utf8') === content) return;
+  } catch { /* absent or unreadable — write it */ }
+  writeFileSync(path, content);
+}
+
+// The engine version the package was generated from. The export names come out
+// of that engine, so a different one means regenerating — and the same one
+// means the child process above can be skipped entirely, which is what keeps
+// this off the cost of an ordinary command.
+function generatedFor(root) {
+  try {
+    return JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))?.joystack?.generatedFor ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// A valid JS identifier can be exported by name; anything else (a string key in
+// an `export { x as "odd name" }`) cannot, and is dropped rather than emitted as
+// a syntax error that would break the door for every other name too.
+const isIdentifier = (name) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && name !== 'default';
+
+function doorSource(door, names) {
+  return [
+    `// \`${door}\` outside the Joystack CLI. Written by the CLI; edits here are overwritten.`,
+    '//',
+    '// Every name is exported so that an import of this door LINKS — Node checks',
+    '// imported names before a module body runs, and a door with no exports would',
+    '// report a missing export instead of the message below. Nothing is imported',
+    '// here on purpose: see packages/cli/lib/joystack-node-doors.mjs.',
+    '',
+    `const RUN_IT_WITH_THE_CLI = [`,
+    ...MESSAGE_LINES(door).map((l) => `  ${JSON.stringify(l)},`),
+    "].join('\\n');",
+    '',
+    'const refuse = () => { throw new Error(RUN_IT_WITH_THE_CLI); };',
+    '',
+    ...names.filter(isIdentifier).map((n) => `export const ${n} = refuse;`),
+    'export default refuse;',
+    '',
+    'throw new Error(RUN_IT_WITH_THE_CLI);',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Write (or refresh) `<projectDir>/node_modules/joystack`.
+ *
+ * @param {string} projectDir - the game folder
+ * @param {string} engineDir - the resolved engine root, read once for the names
+ *   each door exports
+ * @param {string} engineVersion - what the result is keyed on: the same version
+ *   is left alone, so the read above happens once per engine rather than once
+ *   per command
+ * @returns {boolean} whether the package is present and current afterwards
+ */
+export function writeJoystackNodeDoors(projectDir, engineDir, engineVersion, { readExports = readDoorExports } = {}) {
+  const root = join(projectDir, 'node_modules', 'joystack');
+  if (engineVersion && generatedFor(root) === engineVersion) return true;
+
+  const exportsByDoor = readExports(engineDir);
+  if (!exportsByDoor) return false;
+
+  const doorsDir = join(root, 'doors');
+  mkdirSync(doorsDir, { recursive: true });
+
+  for (const door of DOORS) put(join(doorsDir, fileFor(door)), doorSource(door, exportsByDoor[door]));
+
+  // Written last: it is the key the skip above reads, so a run interrupted
+  // part-way through the doors regenerates rather than declaring itself current.
+  put(join(root, 'package.json'), `${JSON.stringify({
+    name: 'joystack',
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    joystack: { generatedFor: engineVersion ?? null },
+    exports: Object.fromEntries(DOORS.map((door) => [subpathFor(door), `./doors/${fileFor(door)}`])),
+  }, null, 2)}\n`);
+  return true;
+}
+
+/**
+ * `writeJoystackNodeDoors` as a command should call it: only when the engine sits
+ * inside this project, and never loudly.
+ *
+ * An engine served from elsewhere (JOYSTACK_ENGINE_DIR) comes with a promise that
+ * the project is exactly as it was when the process exits, and a package written
+ * into its node_modules would break that promise for the sake of a better error
+ * message. Nor is failing to write one worth failing a command for — it improves
+ * an error and does nothing else.
+ *
+ * The same moment leaves the engine's old folder name linked to it
+ * (leaveLegacyEnginePath), for games that reach engine files by that path.
+ *
+ * @returns {boolean} whether the doors were written
+ */
+export function leaveJoystackNodeDoors(projectDir, engine) {
+  if (!engine?.dir) return false;
+  // Both sides resolved, so a project reached by one path and an engine by
+  // another still compare. Logical paths only: a symlinked project with an
+  // out-of-tree engine is the JOYSTACK_ENGINE_DIR case, which is refused anyway.
+  if (!resolve(engine.dir).startsWith(resolve(projectDir, 'node_modules') + sep)) return false;
+  leaveLegacyEnginePath(projectDir, engine.dir);
+  try {
+    return writeJoystackNodeDoors(projectDir, engine.dir, engine.version);
+  } catch {
+    return false;
+  }
+}

package/lib/lane.mjs

@@ -0,0 +1,141 @@
+// `joystack lane <name>` — open an isolated lane for an experiment.
+//
+// A lane is this game checked out a second time, in its own folder, on its own
+// branch, with its own dev stack. Work in a lane cannot disturb the main
+// checkout: different files, different branch, different servers, different
+// multiplayer room. Win → merge it. Lose → delete the folder; nothing that
+// mattered was ever touched.
+//
+// This exists because the lane used to be a PROCEDURE — a bash block in the
+// build skill: commit-guard, `git worktree add`, `npm install`, and remember a
+// distinct `--port` or you'd kill the main checkout's servers. Four steps,
+// three of them footguns, one of them slow. Agents read that, priced the
+// ceremony, and skipped isolating altogether — repeatedly. The COST was the
+// bug. A procedure a tool can just perform should never be written down and
+// hoped for.
+//
+// What used to be expensive, and isn't any more:
+//
+//   npm install   → node_modules is CLONED from the main checkout. On APFS
+//                   (macOS) and btrfs/xfs (Linux) that's a copy-on-write
+//                   reflink: effectively instant, near-zero extra disk. The
+//                   engine is already sitting one directory up; resolving it
+//                   again over the network was always silly.
+//   --port 8010   → gone. `joystack dev` resolves its own ports now and steps
+//                   around anyone else's stack (ports.mjs). A lane just runs
+//                   `npx joystack dev`, like everywhere else.
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { findProject } from './project.mjs';
+import { runNpm } from './npm.mjs';
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+
+// Is this folder a lane (a linked git worktree) rather than the game itself?
+//
+// Git's own marker, no subprocess: in a linked worktree `.git` is a FILE
+// holding `gitdir: …/.git/worktrees/<name>`; in an ordinary repo it's a
+// directory. A folder with no git at all is not a lane.
+//
+// This matters to `publish`, which is global, permanent and irreversible — see
+// the guard there.
+export function isLane(dir) {
+  try {
+    return statSync(join(dir, '.git')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// The slug of the game a lane was opened from: the project in the main
+// checkout that owns this worktree. `null` when `dir` is not a lane, or the main
+// checkout is not a game folder. A lane folder is named after the lane, so its
+// own slug says nothing about which slug is the live game.
+export function laneParentSlug(dir) {
+  if (!isLane(dir)) return null;
+  try {
+    const common = git(dir, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+    return findProject(dirname(common)).slug;
+  } catch {
+    return null;
+  }
+}
+
+// Clone a directory tree as cheaply as the filesystem allows.
+//
+// `cp -c` (macOS) and `cp --reflink=auto` (Linux) ask for copy-on-write: the
+// new tree shares its blocks with the old one until something writes. For a
+// node_modules of tens of thousands of files that is the difference between
+// "instant" and "go and make a coffee". Neither is guaranteed — a non-APFS
+// volume, a filesystem without reflinks — so both fall back to a real copy,
+// which is still local, and still beats a network resolve.
+export function cloneTree(src, dest) {
+  const args =
+    process.platform === 'darwin'
+      ? ['-c', '-R', src, dest] // APFS clonefile
+      : process.platform === 'linux'
+        ? ['-r', '--reflink=auto', src, dest] // btrfs/xfs, degrades to a copy
+        : null;
+  if (args) {
+    try {
+      execFileSync('cp', args, { stdio: 'ignore' });
+      return 'cloned';
+    } catch {
+      // Not a CoW filesystem (or no `cp` worth the name — Windows). Fall through.
+    }
+  }
+  cpSync(src, dest, { recursive: true });
+  return 'copied';
+}
+
+export async function lane(name, { cwd = process.cwd(), log = console.log } = {}) {
+  const project = findProject(cwd);
+  const slug = project.slug;
+  const branch = `lane/${name}`;
+  const dir = resolve(project.dir, '..', `${slug}-${name}`);
+
+  if (existsSync(dir)) {
+    throw new Error(
+      `A lane called "${name}" already exists at ${dir}.\n` +
+        `Work in it (cd ${basename(dir)} && npx joystack dev), or remove it first ` +
+        `(git worktree remove ${dir}).`,
+    );
+  }
+
+  // `git worktree add` on a repo with NO commits silently produces an empty
+  // orphan lane — the folder exists, the game isn't in it. To a creator that
+  // reads as "the tool deleted my game". Save first, but ONLY in that case:
+  // committing on someone's behalf when they didn't ask is its own betrayal.
+  let savedFirst = false;
+  try {
+    git(project.dir, 'rev-parse', 'HEAD');
+  } catch {
+    log('→ saving your game first (a lane needs at least one save to branch from)');
+    git(project.dir, 'add', '-A');
+    git(project.dir, 'commit', '-m', 'save: initial');
+    savedFirst = true;
+  }
+
+  // Their uncommitted work is deliberately NOT carried across: the lane starts
+  // from the last save. That IS the isolation — the whole point is that what
+  // they're in the middle of stays exactly where it is, untouched.
+  git(project.dir, 'worktree', 'add', '-b', branch, dir);
+  log(`→ lane        ${dir}  (branch ${branch})`);
+
+  // node_modules is gitignored, so the lane arrives empty. Without it, `npx
+  // joystack` falls through to a WRONG public package on npm and dies with an
+  // error that reads like a bug in the creator's game.
+  const src = join(project.dir, 'node_modules');
+  let installed = false;
+  if (existsSync(src)) {
+    const how = cloneTree(src, join(dir, 'node_modules'));
+    log(`→ engine      ${how} from the main checkout (no npm install needed)`);
+  } else {
+    log('→ engine      installing (the main checkout has no node_modules to clone)');
+    runNpm(['install'], { cwd: dir, stdio: 'inherit' });
+    installed = true;
+  }
+
+  return { dir, branch, savedFirst, installed };
+}