@joystack/cli 0.0.0-stage → 0.1.43

package/lib/self-update.mjs

@@ -0,0 +1,162 @@
+// Keep the `joystack` command itself up to date — the third lane.
+//
+// THE BUG THIS EXISTS FOR. A game's skills and its engine ride one artifact, so
+// they can't drift. The `joystack` command does not: it's an npm devDependency
+// pinned in the game's own lockfile, and `npx joystack` runs THAT copy, not npm's
+// latest. `joystack update` used to move only the engine — so a real game (riven)
+// ended up on engine 0.1.14, whose skills tell the agent to run
+// `joystack changelog`, while its CLI was still 0.1.6:
+//
+//     $ npx joystack changelog
+//     Unknown command: changelog
+//
+// The agent surface is shipped BY the engine and can name any `joystack` command it
+// likes. Nothing kept the CLI in step with it. So `joystack update` must mean
+// "update Joystack" — engine, skills, AND the command — or the next skill that
+// mentions a new command breaks the same way.
+//
+// FAIL SOFT, ALWAYS. The engine update is the important half and it has already
+// happened by the time we get here. A CLI bump that cannot be done (offline, npm
+// down, no write access) must warn and step aside — never take the command down
+// with it. Nothing in here throws.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runNpm } from './npm.mjs';
+import { LEGACY_CLI_PACKAGE } from './legacy-names.mjs';
+
+export const CLI_PKG = '@joystack/cli';
+
+// What `npx joystack` will run NEXT TIME — the copy on disk in this game, which is
+// not necessarily the copy running right now (`npx @joystack/cli@x update` in
+// a repo pinned to something older runs the newer one but must still fix the
+// repo).
+export function projectCliVersion(projectDir) {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(projectDir, 'node_modules', ...CLI_PKG.split('/'), 'package.json'), 'utf8'),
+    );
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function isOlder(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) < (pb[i] ?? 0);
+  }
+  return false;
+}
+
+// Whether the game's package.json still names the CLI by its name from before
+// the rename.
+export function dependsOnLegacyCli(projectDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8'));
+    return Boolean(pkg.devDependencies?.[LEGACY_CLI_PACKAGE] ?? pkg.dependencies?.[LEGACY_CLI_PACKAGE]);
+  } catch {
+    return false;
+  }
+}
+
+// A game made with the CLI under its old name: swap that dependency for this
+// CLI. The game's scripts keep working afterwards: this CLI also installs the
+// command name they call. The new CLI is installed at the version npm calls
+// latest, or, when npm cannot say, at the version running now.
+async function switchFromLegacyCli({ projectDir, npm, log }) {
+  let to = runningCliVersion();
+  try {
+    to = JSON.parse(npm(['view', CLI_PKG, 'version', '--json'], { cwd: projectDir }).stdout.toString());
+  } catch { /* keep the running version */ }
+  const spec = `${CLI_PKG}@^${to}`;
+  log('');
+  log(`   This game used ${LEGACY_CLI_PACKAGE}, the CLI's name before Joystack. Moving it to ${spec}…`);
+  try {
+    npm(['uninstall', LEGACY_CLI_PACKAGE], { cwd: projectDir });
+    npm(['install', '--save-dev', spec], { cwd: projectDir });
+  } catch (err) {
+    log(`   The move did not finish (npm failed). Run these two, then \`npx joystack update\` again:`);
+    log(`      npm uninstall ${LEGACY_CLI_PACKAGE}`);
+    log(`      npm install --save-dev ${spec}`);
+    return { from: LEGACY_CLI_PACKAGE, to, updated: false, error: err };
+  }
+  return { from: LEGACY_CLI_PACKAGE, to, updated: true, switched: true };
+}
+
+export async function syncCli({ projectDir, npm = runNpm, log = console.log } = {}) {
+  if (dependsOnLegacyCli(projectDir)) return switchFromLegacyCli({ projectDir, npm, log });
+  const from = projectCliVersion(projectDir);
+
+  // Nothing installed: `create` and `dev` own that. There is nothing to bring up
+  // to date, and force-installing here would be a surprise.
+  if (!from) return { from: null, to: null, updated: false, skipped: 'not-installed' };
+
+  let latest;
+  try {
+    const out = npm(['view', CLI_PKG, 'version', '--json'], { cwd: projectDir });
+    latest = JSON.parse(out.stdout.toString());
+  } catch (err) {
+    log('');
+    log(`   Could not check for a newer joystack command (npm did not answer). Your engine is`);
+    log(`   up to date; the command stayed at ${from}. Try again later, or run:`);
+    log(`      npm update ${CLI_PKG}`);
+    return { from, to: null, updated: false, error: err };
+  }
+
+  // Never downgrade. A local dev build (or a version newer than the registry
+  // knows about) is deliberate — leave it alone.
+  if (!isOlder(from, latest)) return { from, to: latest, updated: false };
+
+  try {
+    // --save-dev so the DECLARED range moves too. Without it the next plain
+    // `npm install` in that repo happily resolves back down to the old pin, and
+    // the update silently un-does itself.
+    npm(['install', '--save-dev', `${CLI_PKG}@${latest}`], { cwd: projectDir });
+  } catch (err) {
+    log('');
+    log(`   The joystack command could not be updated to ${latest} (npm install failed).`);
+    log(`   Your engine is up to date; the command is still ${from}. Run this to retry:`);
+    log(`      npm install --save-dev ${CLI_PKG}@${latest}`);
+    return { from, to: latest, updated: false, error: err };
+  }
+
+  return { from, to: latest, updated: true };
+}
+
+// The version of the CLI EXECUTING right now — which is not always the one the
+// project has installed. `npx joystack` runs the local install (so they match), but
+// `npx @joystack/cli@latest update` runs a newer one against an older repo.
+export function runningCliVersion() {
+  try {
+    return JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// What `update` prints. Separate so the wording is testable.
+//
+// The caveat — "you're still running the old one" — is TRUE only when the process
+// executing is the copy we just replaced. An earlier version asserted it
+// unconditionally and told a `npx @joystack/cli@latest update` run that it was
+// "still running 0.1.6", which it plainly was not. Caught by reading the output of
+// a real run against riven. Say it only when it's true.
+export function reportCli(log, cli, { running = runningCliVersion() } = {}) {
+  if (!cli?.updated) return;
+  log('');
+  if (cli.switched) {
+    log(`✅ This game now uses ${CLI_PKG} ${cli.to} in place of ${cli.from}.`);
+    log('   Your package.json scripts keep working as they are.');
+    return;
+  }
+  log(`✅ The joystack command updated: ${cli.from} → ${cli.to}`);
+  if (running === cli.from) {
+    log(`   You're still running ${cli.from} in this process — any new commands work from`);
+    log(`   your next \`npx joystack\`.`);
+  } else {
+    log(`   New commands are available from your next \`npx joystack\`.`);
+  }
+  log(`   Its own changes are in node_modules/${CLI_PKG}/CHANGELOG.md.`);
+}

package/lib/shadow-resolve.mjs

@@ -0,0 +1,85 @@
+// Shadowing, for the BUNDLER.
+//
+// `overrides/shared/<engine path>` works in the browser because the dev server
+// (and, in production, the import map) resolves each `/shared/...` request
+// against the game's overrides FIRST and the engine SECOND — per file. A game's
+// override sits at the engine's own URL, so its neighbours resolve to the engine's.
+//
+// esbuild has no such notion. It resolves relative imports against the real
+// filesystem, where the game's overrides folder holds only the one or two files
+// the creator actually wrote. So this:
+//
+//   // overrides/shared/ui/room/primitives/player-body.js
+//   import { PlayerBody } from './engine.js';     // ← the escape hatch
+//
+// resolves in the browser (engine.js is right there at /shared/ui/room/primitives/)
+// and dies in the bundler ("Could not resolve ./engine.js") — the game's folder
+// has no engine.js, and never will: it's the engine's.
+//
+// That import is not incidental. It is the ONLY way an override can subclass the
+// primitive it overrides — it cannot import its own path, which is itself — and
+// "change one method" is the most common reason to override anything. So the
+// bundler has to learn the same fall-through the servers already do:
+//
+//   a relative import from inside overrides/shared/…
+//     → the game's file, if it has one
+//     → otherwise the engine's file at the mirrored path
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+const OVERRIDES_ROOT = join('overrides', 'shared');
+
+// esbuild hands us importer paths with symlinks already resolved, while the
+// project dir arrives as the caller spelled it. On macOS that alone is enough to
+// break the comparison below — a temp dir is `/var/…` to us and `/private/var/…`
+// to esbuild — and the fall-through would silently never fire, leaving the
+// creator with "Could not resolve ./engine.js" and no idea why.
+function realOrSelf(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p; // doesn't exist yet — compare as given
+  }
+}
+
+// Is `file` inside the game's overrides/shared/ tree?
+function underOverrides(file, overridesRoot) {
+  const rel = relative(overridesRoot, file);
+  return rel !== '' && !rel.startsWith('..') && !rel.startsWith(sep);
+}
+
+// engineExternal: at PUBLISH the engine is never bundled in — it is marked
+// external and rewritten to the release's pre-bundled `rooms-runtime.js`, so the
+// worker's room code is always ours. Pass the module specifier to rewrite to.
+// In DEV we build the whole room server ourselves, so the engine's real file on
+// disk is exactly what we want.
+export function shadowResolvePlugin({ projectDir, sharedDir, engineExternal = null, onEngineHit = () => {} }) {
+  const overridesRoot = realOrSelf(join(projectDir, OVERRIDES_ROOT));
+
+  return {
+    name: 'joystack-shadow-resolve',
+    setup(build) {
+      build.onResolve({ filter: /^\.{1,2}\// }, (args) => {
+        if (!args.importer) return null;
+        // Everything below is computed in real-path space, so the overrides-root
+        // comparison and the shadow mapping can't disagree about the same file.
+        const importer = realOrSelf(args.importer);
+        if (!underOverrides(importer, overridesRoot)) return null;
+
+        const candidate = resolve(dirname(importer), args.path);
+
+        // The game has this file — its own primitive, its own helper. Use it.
+        if (existsSync(candidate)) return { path: candidate };
+
+        // It doesn't. In the browser this would have fallen through to the
+        // engine, so do the same here: map the path back across the shadow.
+        const rel = relative(overridesRoot, candidate);
+        const engineFile = join(sharedDir, rel);
+        if (!existsSync(engineFile)) return null; // let esbuild report it honestly
+
+        onEngineHit(`/shared/${rel.split(sep).join('/')}`);
+        return engineExternal ? { path: engineExternal, external: true } : { path: engineFile };
+      });
+    },
+  };
+}

package/lib/share.mjs

@@ -0,0 +1,149 @@
+// `joystack dev --share` — a public link to this dev server, for testers.
+//
+// A Cloudflare quick tunnel (`cloudflared tunnel --url`, no account needed)
+// gives a random `https://<words>.trycloudflare.com` name that forwards every
+// request to the dev server's port. A tester opens it on their phone and plays;
+// their recording and their device's performance land in this game's
+// .joystack/replays/ exactly as the creator's own sessions do. The dev server
+// trusts that one hostname (static-server.mjs, trustedHost) and forwards the
+// room's websocket (its upgrade handler), so multiplayer works through the same
+// link.
+//
+// The link lasts as long as `joystack dev` runs. Holding it is the same as being
+// on the creator's wifi: nothing on the dev server is locked away from it.
+import { spawn } from 'node:child_process';
+import { Resolver } from 'node:dns/promises';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { withoutAgentSession } from './agent-session.mjs';
+
+const LINK_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/g;
+// cloudflared's own API, which it names in the error it logs when it cannot get
+// a tunnel. Never a link.
+const API_HOST = 'api.trycloudflare.com';
+
+// Whether the engine a game is pinned to can be shared. The page decides it is
+// a dev page from the flag the dev server writes into it (the engine's
+// dev-host.js, SHARE_FLAG); an engine from before that decides by address
+// alone, so through the link it would record nothing and send a multiplayer
+// page to the production room server.
+export function engineCanShare(sharedDir) {
+  try {
+    return readFileSync(join(sharedDir, 'ui/room/lib/dev-host.js'), 'utf8').includes('JOYSTACK_DEV_SHARE');
+  } catch {
+    return false;
+  }
+}
+
+// How to get cloudflared, per platform, for the error a missing one produces.
+const INSTALL_HINT = [
+  'cloudflared is not installed. It is the free Cloudflare program that opens the link. Install it, then run `joystack dev --share` again:',
+  '  macOS:   brew install cloudflared',
+  '  Windows: winget install --id Cloudflare.cloudflared',
+  '  Linux:   https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/',
+].join('\n');
+
+// A fresh tunnel's name is registered with DNS a few seconds after cloudflared
+// prints it. A device that looks it up in that gap gets "not found" and may
+// keep that answer cached for minutes, so the link is printed only once a
+// public resolver answers for it.
+function publicResolver() {
+  const r = new Resolver();
+  r.setServers(['1.1.1.1', '8.8.8.8']);
+  return (hostname) => r.resolve4(hostname);
+}
+
+/**
+ * Open a quick tunnel to `http://localhost:<port>`.
+ * `exited` settles when cloudflared stops, for whatever reason, after the link
+ * was given; the link is dead from then on.
+ * @returns {Promise<{ url: string, hostname: string, resolved: boolean, close: () => void, exited: Promise<void> }>}
+ */
+export function openTunnel({
+  port,
+  spawnImpl = spawn,
+  resolveHost = publicResolver(),
+  timeoutMs = 45_000,
+  dnsTimeoutMs = 30_000,
+  pollMs = 1_000,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl('cloudflared', ['tunnel', '--url', `http://localhost:${port}`, '--no-autoupdate'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: withoutAgentSession(process.env),
+    });
+    const tail = [];
+    let settled = false;
+    const exited = new Promise((r) => child.on('exit', () => r()));
+    const close = () => {
+      if (child.killed) return;
+      try { child.kill(); } catch { /* already gone */ }
+    };
+    const fail = (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      close();
+      reject(err);
+    };
+    const timer = setTimeout(
+      () => fail(new Error(`cloudflared gave no link within ${Math.round(timeoutMs / 1000)}s.${lastWords()}`)),
+      timeoutMs,
+    );
+    const lastWords = () => (tail.length ? `\ncloudflared said:\n  ${tail.slice(-5).join('\n  ')}` : '');
+
+    child.on('error', (err) => fail(err?.code === 'ENOENT' ? new Error(INSTALL_HINT) : err));
+    child.on('exit', (code, signal) => {
+      if (!settled) fail(new Error(`cloudflared exited before giving a link (${signal ?? `code ${code}`}).${lastWords()}`));
+    });
+
+    const onOutput = (chunk) => {
+      for (const line of String(chunk).split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed) tail.push(trimmed);
+        if (tail.length > 20) tail.shift();
+        for (const [link] of line.matchAll(LINK_RE)) {
+          if (!settled && new URL(link).hostname !== API_HOST) found(link);
+        }
+      }
+    };
+    child.stdout?.on('data', onOutput);
+    child.stderr?.on('data', onOutput);
+
+    async function found(url) {
+      settled = true;
+      clearTimeout(timer);
+      const hostname = new URL(url).hostname;
+      const deadline = Date.now() + dnsTimeoutMs;
+      let resolved = false;
+      while (!resolved && Date.now() < deadline) {
+        try {
+          resolved = (await resolveHost(hostname)).length > 0;
+        } catch { /* not registered yet */ }
+        if (!resolved) await new Promise((r) => setTimeout(r, pollMs));
+      }
+      resolve({ url, hostname, resolved, close, exited });
+    }
+  });
+}
+
+/**
+ * What `joystack dev --share` prints: the link to send, and what sending it gives.
+ */
+export function shareBanner({ url, gamePath, resolved, frozen = false }) {
+  const lines = [
+    `🔗  ${url}${gamePath}   (send this to your testers)`,
+    '',
+    '⚠  Anyone with this link can reach this dev server as if they were on your wifi:',
+    '   play the game, read any of the files your game folder serves, and list, keep or',
+    '   delete your recordings. Send it only to people you trust. The link stops',
+    '   working when you stop `joystack dev`.',
+    '   Every session they play is recorded into .joystack/replays/, with their',
+    '   device\'s performance, as yours are.',
+    ...(frozen
+      ? ['   The game is frozen as it was when you started: nothing you save reaches', '   them until you restart `joystack dev`, which makes a new link.']
+      : ['   Saving a file reloads their page too; start with --no-reload to freeze', '   the game for everyone while you edit.']),
+  ];
+  if (!resolved) lines.splice(1, 0, '   (the link is new: it may take a minute before it opens everywhere)');
+  return lines;
+}

package/lib/smoke-gpu-preload.mjs

@@ -0,0 +1,91 @@
+// Preloaded before every browser smoke via `node --import`. Its whole job is to
+// make headless Chromium render on the real GPU instead of SwiftShader.
+//
+// Why it matters: a headless browser has no GPU, so WebGL falls back to
+// SwiftShader — software rasterization spread across a thread pool sized to the
+// machine's core count. A single 3D-game smoke can pin 8+ cores that way, which
+// on a modest laptop means a frozen machine, not just a slow test. Rendering on
+// the actual GPU (Metal on macOS, D3D11 on Windows, GL or Vulkan on Linux — see
+// `angleBackend` below for which of these is named outright) moves that work
+// off the CPU entirely: measured ~8.5 cores → ~0.1, with pixel-identical output.
+//
+// It runs as a preload so an UNMODIFIED smoke needs no change: it patches the
+// `chromium.launch` of the GAME's own playwright (resolved from cwd, the same
+// instance the smoke imports) to append the flags. Fetch-only smokes that never
+// import playwright, and machines with no usable GPU, both fall through
+// untouched — ANGLE simply falls back to software, so this is never worse than
+// before. Opt out with JOYSTACK_TEST_NO_GPU=1.
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { readEnv } from './legacy-names.mjs';
+
+// The ANGLE backend to name, or null to let Chromium choose. Windows is named
+// explicitly: headless Chromium there does not reach the GPU through its
+// default backend even with the two GPU flags set, and renders slower than
+// software; naming D3D11 is what engages the GPU (measured on one scene:
+// 5.8 fps → 57 fps). macOS (Metal) and Linux pick a working backend unaided.
+// JOYSTACK_TEST_ANGLE=<backend> overrides on any platform; `default` removes the
+// flag, for a Windows machine whose driver misbehaves under D3D11.
+function angleBackend(platform) {
+  const override = readEnv('JOYSTACK_TEST_ANGLE');
+  if (override) return override === 'default' ? null : override;
+  return platform === 'win32' ? 'd3d11' : null;
+}
+
+export function gpuArgs(platform = process.platform) {
+  if (readEnv('JOYSTACK_TEST_NO_GPU') === '1') return [];
+  const angle = angleBackend(platform);
+  return ['--enable-gpu', '--ignore-gpu-blocklist', ...(angle ? [`--use-angle=${angle}`] : [])];
+}
+
+// Append `extra` to whatever args a caller already passed to chromium.launch(),
+// preserving theirs. Idempotent enough for our use: called once per smoke process.
+export function patchLaunch(chromium, extra = gpuArgs()) {
+  if (!chromium || typeof chromium.launch !== 'function' || extra.length === 0) return false;
+  const orig = chromium.launch.bind(chromium);
+  chromium.launch = (opts = {}) => orig({ ...opts, args: [...(opts.args || []), ...extra] });
+  return true;
+}
+
+// Resolve the SAME playwright module object a smoke's `import 'playwright'` gets.
+// The catch: a bare ESM import resolves via the package's "import" export
+// (index.mjs), while createRequire().resolve() returns the "require" main
+// (index.js) — a DIFFERENT module instance. Patching that one would miss, and the
+// smoke would silently fall back to software with no error. So resolve the
+// package dir, then import its ESM entry explicitly.
+//
+// Resolve from the SMOKE FILE's directory first (process.argv[1] under
+// `node --import <preload> <smoke>`), then cwd. A smoke normally runs from its
+// own game folder (cwd == the smoke's dir), but a runner may invoke it from a
+// different working directory — resolving off the smoke's own location makes the
+// same playwright install resolve either way.
+async function loadGamePlaywright() {
+  const bases = [];
+  const smoke = process.argv[1];
+  if (smoke) bases.push(join(dirname(smoke), 'package.json'));
+  bases.push(join(process.cwd(), 'package.json'));
+  let lastErr;
+  for (const base of bases) {
+    try {
+      const require = createRequire(base);
+      const pkgDir = dirname(require.resolve('playwright')); // .../node_modules/playwright
+      const pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8'));
+      const entry = pkg.exports?.['.']?.import ?? pkg.module ?? pkg.main ?? 'index.js';
+      return import(pathToFileURL(join(pkgDir, entry)).href);
+    } catch (e) { lastErr = e; }
+  }
+  throw lastErr;
+}
+
+// Self-execute on preload. Kept in try/catch so a smoke without playwright (a
+// fetch-only boot smoke) or a missing install never turns a preload into a crash.
+if (gpuArgs().length > 0) {
+  try {
+    const pw = await loadGamePlaywright();
+    patchLaunch(pw.chromium ?? pw.default?.chromium);
+  } catch {
+    // No playwright here, or it couldn't be patched — leave the smoke unchanged.
+  }
+}

package/lib/source-path.mjs

@@ -0,0 +1,33 @@
+// Where a piece of code lives, named the way a creator would look for it:
+// relative to the game folder, or inside the engine's package as
+// `@joystack/engine/shared/…`, which is the same in every install.
+//
+// Paths are compared as the disk sees them, through any link: an engine
+// reached through a symlinked folder (a linked install, `JOYSTACK_ENGINE_DIR`)
+// is still the engine.
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+
+// `path` relative to `root` with `/` separators, or null when it is not inside.
+function within(root, path) {
+  const rel = relative(root, path);
+  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? rel.split(sep).join('/') : null;
+}
+
+/**
+ * A file's name for people: `@joystack/engine/shared/<path>` inside the
+ * engine, `<path>` inside the game, or null when it is in neither.
+ *
+ * @param {string} path - absolute, or relative to `dir`
+ * @param {{ dir?: string|null, sharedDir?: string|null }} where - the game
+ *   folder, and the engine's shared/ tree
+ */
+export function sourcePath(path, { dir = null, sharedDir = null } = {}) {
+  if (typeof path !== 'string' || !path) return null;
+  const abs = real(dir ? resolve(dir, path) : resolve(path));
+  const inEngine = sharedDir ? within(real(sharedDir), abs) : null;
+  if (inEngine) return `@joystack/engine/shared/${inEngine}`;
+  return dir ? within(real(dir), abs) : null;
+}