@joystack/cli 0.0.0-stage → 0.1.43

package/lib/legacy-names.mjs

@@ -0,0 +1,246 @@
+// The names the CLI still accepts from games written for the Looop engine
+// (engine 0.2.35, CLI 0.1.43 and earlier). Joystack is the same engine under a
+// new name; a game written against the old one keeps working unchanged, so
+// every old name the CLI reads is mapped onto its new one here, and nowhere
+// else. New code and new games use only the joystack names.
+//
+//   imports        `looop`, `looop/<sub>`        → `joystack`, `joystack/<sub>`
+//                  `@looop-games/engine/<path>`  → `@joystack/engine/<path>`
+//                  `@looop-games/cli/<path>`     → `@joystack/cli/<path>`
+//   environment    LOOOP_<NAME> is read when JOYSTACK_<NAME> is unset, and a
+//                  variable the CLI hands a game's tests is set under both names
+//   page globals   the dev server sets `LOOOP_IDENTITY` and the other globals
+//                  the production serve path sets under both names
+//   package.json   the `"looop": { … }` block, when there is no `"joystack"` block
+//   test policy    looop.tests.json, when there is no joystack.tests.json
+//   state folder   a game's `.looop/`, when it has no `.joystack/`
+//   dev routes     `/__looop/<route>`                → `/__joystack/<route>`
+//   data formats   recordings tagged `looop-…/1`     are read as `joystack-…/1`
+//   AGENTS.md      the `looop:managed` markers       are read as `joystack:managed`
+//   build ids      hashed from the version line the old engine used (BUILD_ID_FORMAT)
+import { existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+const OLD = 'looop';
+const NEW = 'joystack';
+
+// ── hash inputs ──────────────────────────────────────────────────────────────
+
+/**
+ * The version line a build id's hash starts from. A hash input keeps its exact
+ * bytes: a different line would give every game a new build id, and every
+ * recording made before would read as made on another build.
+ */
+export const BUILD_ID_FORMAT = 'looop-build/1\n';
+
+// ── imports ──────────────────────────────────────────────────────────────────
+
+// Engine releases up to 0.2.35 install under this package name. This CLI does
+// not run them; it names the problem instead of failing on a missing folder.
+export const LEGACY_ENGINE_PACKAGE = '@looop-games/engine';
+
+/**
+ * Make `node_modules/@looop-games/engine` a link to the installed engine.
+ *
+ * A game written for engine 0.2.35 or earlier can name files inside the engine
+ * package by path rather than through a door: a relative import such as
+ * `../../node_modules/@looop-games/engine/shared/ui/room/entity/frac.js`, its
+ * eslint.config.js importing `@looop-games/engine/eslint/index.js`, or a path in
+ * its handbook. Every one of those files is still in the engine under the same
+ * path, so the old folder name only has to lead to it. Whatever sits at the old
+ * path is replaced: it is an engine npm installed without saving, and the game
+ * now runs on the one at `engineDir`.
+ *
+ * @returns {boolean} whether the link is in place afterwards
+ */
+export function leaveLegacyEnginePath(projectDir, engineDir) {
+  const at = join(projectDir, 'node_modules', ...LEGACY_ENGINE_PACKAGE.split('/'));
+  const target = relative(dirname(at), engineDir);
+  try {
+    let stat = null;
+    try { stat = lstatSync(at); } catch { /* nothing there yet */ }
+    if (stat?.isSymbolicLink() && readlinkSync(at) === target) return true;
+    if (stat) rmSync(at, { recursive: true, force: true });
+    mkdirSync(dirname(at), { recursive: true });
+    symlinkSync(target, at, process.platform === 'win32' ? 'junction' : 'dir');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// The CLI's package name before the rename. A game that still depends on it is
+// moved onto @joystack/cli by `joystack update` (self-update.mjs).
+export const LEGACY_CLI_PACKAGE = '@looop-games/cli';
+
+const PACKAGE_PREFIXES = [
+  ['@looop-games/engine', '@joystack/engine'],
+  ['@looop-games/cli', '@joystack/cli'],
+];
+
+/**
+ * The specifier a game's import means: an old door or package path mapped onto
+ * its joystack name by prefix, so a door added later is covered with no edit
+ * here. Anything else comes back unchanged.
+ */
+export function canonicalSpecifier(specifier) {
+  if (typeof specifier !== 'string') return specifier;
+  if (specifier === OLD) return NEW;
+  if (specifier.startsWith(`${OLD}/`)) return NEW + specifier.slice(OLD.length);
+  for (const [from, to] of PACKAGE_PREFIXES) {
+    if (specifier === from || specifier.startsWith(`${from}/`)) return to + specifier.slice(from.length);
+  }
+  return specifier;
+}
+
+/** A browser import map extended with the old name of every joystack door it maps. */
+export function withLegacyDoors(imports) {
+  const out = { ...imports };
+  for (const [key, url] of Object.entries(imports)) {
+    if (key === NEW || key.startsWith(`${NEW}/`)) out[OLD + key.slice(NEW.length)] = url;
+  }
+  return out;
+}
+
+const IMPORT_MAP_RE = /(<script type="importmap">)([\s\S]*?)(<\/script>)/;
+
+/**
+ * An HTML page with its own import map (the Assets page carries one) and the
+ * old name of every door that map names added to it, so a game module the page
+ * imports resolves an old door too.
+ */
+export function withLegacyImportMap(html) {
+  const m = IMPORT_MAP_RE.exec(html);
+  if (!m) return html;
+  let map;
+  try { map = JSON.parse(m[2]); } catch { return html; }
+  if (!map || typeof map.imports !== 'object') return html;
+  const extended = JSON.stringify({ ...map, imports: withLegacyDoors(map.imports) }, null, 2);
+  return html.slice(0, m.index) + m[1] + '\n' + extended + '\n' + m[3] + html.slice(m.index + m[0].length);
+}
+
+/** The esbuild `onResolve` filter matching a door specifier under either name. */
+export const DOOR_FILTER = new RegExp(`^(?:${NEW}|${OLD})(\\/.*)?$`);
+
+/** The esbuild `onResolve` filter matching the engine package under either name. */
+export const ENGINE_PACKAGE_FILTER = /^@(?:joystack|looop-games)\/engine(\/|$)/;
+
+// ── environment ──────────────────────────────────────────────────────────────
+
+const legacyEnvName = (name) => (name.startsWith(`${NEW.toUpperCase()}_`)
+  ? `${OLD.toUpperCase()}_${name.slice(NEW.length + 1)}`
+  : null);
+
+/** `JOYSTACK_<NAME>` from `env`, or `LOOOP_<NAME>` when the joystack one is unset. */
+export function readEnv(name, env = process.env) {
+  if (env[name] !== undefined) return env[name];
+  const old = legacyEnvName(name);
+  return old ? env[old] : undefined;
+}
+
+/**
+ * Variables the CLI hands to a game's own processes (its tests and smokes), set
+ * under both names: a test written for the old engine reads `LOOOP_<NAME>`.
+ */
+export function withLegacyEnv(vars) {
+  const out = { ...vars };
+  for (const [name, value] of Object.entries(vars)) {
+    const old = legacyEnvName(name);
+    if (old && !(old in vars)) out[old] = value;
+  }
+  return out;
+}
+
+// ── page globals ─────────────────────────────────────────────────────────────
+
+/**
+ * The page globals a served game page carries under both names, keyed by the
+ * joystack name. The production serve path (backend/api/src/lib/inject.js) sets
+ * the same list, so game code reading an old name finds it in `joystack dev`
+ * exactly as it does on its published page.
+ */
+export const LEGACY_PAGE_GLOBALS = Object.freeze({
+  __JOYSTACK_SKELETON__: '__LOOOP_SKELETON__',
+  JOYSTACK_ROOM_PARTY: 'LOOOP_ROOM_PARTY',
+  JOYSTACK_IDENTITY: 'LOOOP_IDENTITY',
+  JOYSTACK_REVIEW_BUILD: 'LOOOP_REVIEW_BUILD',
+});
+
+// ── a game's package.json block ──────────────────────────────────────────────
+
+/** Which key of package.json holds the game's settings: `joystack`, or `looop` when only that exists. */
+export function gameConfigKey(pkg) {
+  if (pkg && typeof pkg[NEW] === 'object' && pkg[NEW] !== null) return NEW;
+  if (pkg && typeof pkg[OLD] === 'object' && pkg[OLD] !== null) return OLD;
+  return NEW;
+}
+
+/** The game's settings block from package.json (`{}` when it has none). */
+export function gameConfig(pkg) {
+  return pkg?.[gameConfigKey(pkg)] ?? {};
+}
+
+// ── test policy file ─────────────────────────────────────────────────────────
+
+export const TEST_POLICY_FILE = `${NEW}.tests.json`;
+const LEGACY_TEST_POLICY_FILE = `${OLD}.tests.json`;
+
+/** The test policy file name a game uses: joystack.tests.json, or looop.tests.json when only that exists. */
+export function testPolicyFile(projectDir) {
+  if (!existsSync(join(projectDir, TEST_POLICY_FILE)) && existsSync(join(projectDir, LEGACY_TEST_POLICY_FILE))) {
+    return LEGACY_TEST_POLICY_FILE;
+  }
+  return TEST_POLICY_FILE;
+}
+
+// ── the game's state folder ──────────────────────────────────────────────────
+
+/**
+ * Every name a game's private state folder can have. Each one is kept out of
+ * publishing, serving, linting and test triggers, whichever the game uses.
+ */
+export const STATE_DIR_NAMES = Object.freeze([`.${NEW}`, `.${OLD}`]);
+
+/** The state folder's name in this game: `.joystack`, or `.looop` when only that exists. */
+export function stateDirName(projectDir) {
+  if (projectDir && !existsSync(join(projectDir, `.${NEW}`)) && existsSync(join(projectDir, `.${OLD}`))) return `.${OLD}`;
+  return `.${NEW}`;
+}
+
+/** The absolute path of the game's state folder (see stateDirName). */
+export function stateDir(projectDir) {
+  return join(projectDir, stateDirName(projectDir));
+}
+
+// ── dev-server routes ────────────────────────────────────────────────────────
+
+const OLD_ROUTE = `/__${OLD}/`;
+const NEW_ROUTE = `/__${NEW}/`;
+
+/** A dev-server request path with an old `/__looop/` route mapped onto `/__joystack/`. */
+export function canonicalDevPath(urlPath) {
+  if (typeof urlPath === 'string' && (urlPath.startsWith(OLD_ROUTE) || urlPath === `/__${OLD}`)) {
+    return `/__${NEW}` + urlPath.slice(OLD_ROUTE.length - 1);
+  }
+  return urlPath;
+}
+
+// ── persisted data formats ───────────────────────────────────────────────────
+
+const LEGACY_FORMATS = new Map([
+  [`${OLD}-replay/1`, `${NEW}-replay/1`],
+  [`${OLD}-replay-seg/1`, `${NEW}-replay-seg/1`],
+  [`${OLD}-track-seg/1`, `${NEW}-track-seg/1`],
+]);
+
+/** A recording's format tag, with an old tag mapped onto the one written today. */
+export function canonicalFormat(tag) {
+  return LEGACY_FORMATS.get(tag) ?? tag;
+}
+
+// ── AGENTS.md managed markers ────────────────────────────────────────────────
+
+export const LEGACY_MANAGED_MARKERS = Object.freeze({
+  start: `<!-- ${OLD}:managed:start -->`,
+  end: `<!-- ${OLD}:managed:end -->`,
+});

package/lib/lint.mjs

@@ -0,0 +1,292 @@
+// `joystack lint` — the hard rules, made executable.
+//
+// A "Never" that lives only in prose is a suggestion. The rules that have
+// actually shipped broken games are enforced here: in the editor as you type
+// (via the game's eslint.config.js) and in the gate (`joystack test` runs this
+// first).
+//
+// The rules themselves live in the ENGINE (`<engine>/eslint/`), not in this
+// package — they are something the creator receives, so they have one authoring
+// home and one release lane, and `joystack update` brings a game the new ones. This
+// command resolves them out of the game's installed engine, which is the very
+// same file its eslint.config.js imports. One copy: the gate and the editor
+// cannot disagree.
+//
+// Escape hatch: `// eslint-disable-next-line joystack/<rule>` — the one every
+// developer already knows. This is mandatory, not a nicety: creators are not
+// developers, and a false positive must never wall someone out of their own
+// test command with no way through.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isFrameworkV2 } from './primitives.mjs';
+import { findProject, resolveEngine } from './project.mjs';
+
+const CONFIG_NAMES = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'];
+
+// Resolve ESLint from the GAME's node_modules — same preflight shape as
+// playwright in test-cmd.mjs. Games scaffolded before lint existed simply don't
+// have it; they skip rather than break.
+async function loadFromProject(projectDir) {
+  try {
+    const req = createRequire(join(projectDir, 'package.json'));
+    const mod = await import(pathToFileURL(req.resolve('eslint')).href);
+    return mod.ESLint ?? mod.default?.ESLint ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The shareable config, out of the installed engine artifact.
+//
+// The two ways this can come up empty are DIFFERENT problems with different
+// fixes, and conflating them sends people in a circle: the first version of this
+// said "engine ships no rules — run joystack update" when the engine was not
+// installed at all, so `joystack update` was the one command that could never help.
+// Say which it is.
+async function loadRulesFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return { configs: null, why: 'no-engine' };
+  }
+  const entry = join(engineDir, 'eslint', 'index.js');
+  if (!existsSync(entry)) return { configs: null, why: 'engine-too-old' };
+  const mod = await import(pathToFileURL(entry).href);
+  return { configs: mod.configs ?? mod.default?.configs ?? null, why: 'ok' };
+}
+
+// The entity graph lint — the SECOND shared step, alongside the eslint rules.
+// Like the rules, the implementation lives in the ENGINE (shared/ui/room/
+// entity/lint-run.mjs), so every gate that checks a game runs the identical
+// pass — there is no second copy to drift. An engine too old to carry it
+// skips — same degradation contract as the rules.
+async function loadEntityLintFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return null;
+  }
+  const entry = join(engineDir, 'shared', 'ui', 'room', 'entity', 'lint-run.mjs');
+  if (!existsSync(entry)) return null;
+  const mod = await import(pathToFileURL(entry).href);
+  return mod.runEntityLint ?? null;
+}
+
+// The framework-v2 build gate — the THIRD shared step, and engine-resident for
+// the same reason as the other two: the gate that refuses to build a game and
+// the gate that lints it must be the same code, or lint would bless a game the
+// build then rejects.
+//
+// It runs only for a v2 game (package.json `joystack.framework === 'v2'`); a
+// classic game has no world to expand. An engine too old to carry it skips —
+// same degradation contract as the rules and the entity lint.
+async function loadBuildGateFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return null;
+  }
+  const entry = join(engineDir, 'shared', 'framework', 'build', 'gate.js');
+  if (!existsSync(entry)) return null;
+  const mod = await import(pathToFileURL(entry).href);
+  return mod.runGate ?? null;
+}
+
+// The handbook path check — the FOURTH shared step. Every file the game's
+// `handbook/` names in backticks must exist. It lives in the engine next to the
+// rules (eslint/handbook-paths.js) because the rules for what a handbook says
+// ship with the engine's `/handbook` skill, and the check and the skill have to
+// move together. An engine too old to carry it skips.
+async function loadHandbookCheckFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return null;
+  }
+  const entry = join(engineDir, 'eslint', 'handbook-paths.js');
+  if (!existsSync(entry)) return null;
+  const mod = await import(pathToFileURL(entry).href);
+  if (!mod.runHandbookPathCheck) return null;
+  return (dir, opts) => mod.runHandbookPathCheck(dir, { engineDir, ...opts });
+}
+
+// Gate errors, printed the way lint prints everything else: the location first,
+// so an agent or an editor can jump to it, then the rule that was broken, then
+// the gate's own prescriptive text.
+//
+// The heading has a job beyond decoration. These errors are in GAME code, and a
+// creator's agent used to meet them first as a node test that could not open its
+// world — which reads as a broken test and sends the agent to debug the test.
+// Say what they are.
+async function runBuildGateStep(runGate, dir, log) {
+  let report;
+  try {
+    // `write: false` — lint reads, it does not leave `.joystack/diagnostics.json`
+    // behind. The build path writes that file when it actually builds.
+    ({ report } = await runGate(dir, { write: false }));
+  } catch (e) {
+    // The gate import()s the game, so a module that throws at load arrives
+    // here. A diagnosis beats a stack trace out of the engine's insides.
+    log('');
+    log('❌ joystack lint: the build gate could not read your game.');
+    log(`   ${e?.message ?? e}`);
+    return { ok: false, errors: [] };
+  }
+
+  const errors = report?.errors ?? [];
+  if (!errors.length) return { ok: true, errors: [] };
+
+  log('');
+  log(`❌ joystack lint: ${errors.length} build gate error(s) — your game cannot be built, so it cannot run.`);
+  log('   These are errors in your game\'s code, not a broken test.');
+  log('');
+  for (const e of errors) {
+    const where = [e.file, e.line, e.col].filter((p) => p != null && p !== '').join(':');
+    log(`  ${where || '(location unknown)'}  ${e.code}`);
+    for (const line of String(e.message ?? '').split('\n')) log(`    ${line}`);
+  }
+  return { ok: false, errors };
+}
+
+export async function lintCmd({
+  cwd = process.cwd(),
+  fix = false,
+  log = console.log,
+  loadEslint = loadFromProject,
+  loadRules = loadRulesFromEngine,
+  loadEntityLint = loadEntityLintFromEngine,
+  loadBuildGate = loadBuildGateFromEngine,
+  loadHandbookCheck = loadHandbookCheckFromEngine,
+} = {}) {
+  const project = findProject(cwd);
+
+  // The entity graph check runs regardless of the eslint tooling below — a
+  // missing dev tool must never switch off a structural guarantee. It skips
+  // itself silently for games with no entity folders.
+  const runEntity = await loadEntityLint(project.dir);
+  const entity = runEntity ? await runEntity(project.dir, { log }) : { ok: true, skipped: true };
+
+  // Same contract for the build gate, and for the same reason.
+  // An engine with no gate file is an older engine and skips. A gate file that
+  // is there and cannot be imported is a broken install, and that fails: a
+  // skipped gate would pass a game that nothing checked.
+  let runGate = null;
+  let gate = null;
+  if (isFrameworkV2(project.dir)) {
+    try {
+      runGate = await loadBuildGate(project.dir);
+    } catch (e) {
+      log('');
+      log('❌ joystack lint: the build gate could not be loaded, so your game was not checked.');
+      log(`   ${e?.message ?? e}`);
+      log('   This is the installed engine, not your game: `npx joystack update` reinstalls it.');
+      gate = { ok: false };
+    }
+  }
+  gate ??= runGate ? await runBuildGateStep(runGate, project.dir, log) : { ok: true, skipped: true };
+
+  // Runs whether or not eslint is installed; an engine without the check skips.
+  // A check that is present and throws fails the step rather than the command,
+  // so the entity and gate results above still reach the caller.
+  let handbook;
+  try {
+    const runHandbook = await loadHandbookCheck(project.dir);
+    handbook = runHandbook ? runHandbook(project.dir, { log }) : { ok: true, skipped: true };
+  } catch (e) {
+    log('');
+    log('❌ joystack lint: the handbook path check could not run.');
+    log(`   ${e?.message ?? e}`);
+    handbook = { ok: false, error: String(e?.message ?? e) };
+  }
+
+  const ESLint = await loadEslint(project.dir);
+  if (!ESLint) {
+    log('⚠️  joystack lint: eslint is not installed in this game — skipping the rule checks.');
+    log('   To turn them on (recommended — they catch bugs that silently pass your tests):');
+    log('     npm i -D eslint');
+    return { ok: entity.ok && gate.ok && handbook.ok, skipped: true, errorCount: 0, warningCount: 0, entity, gate, handbook };
+  }
+
+  const { configs, why } = await loadRules(project.dir);
+  if (!configs) {
+    if (why === 'no-engine') {
+      // The engine is not on disk. Usually it was PRUNED: it installs with
+      // `npm install --no-save`, so npm has no record of it and any later
+      // `npm install` in this game deletes it. It is not lost — it is cached.
+      log('⚠️  joystack lint: the Joystack engine is not installed in this game — skipping.');
+      log('   (A plain `npm install` removes it; it is cached, so putting it back is instant.)');
+      log('   Restore it with:  joystack update');
+    } else {
+      log('⚠️  joystack lint: your engine is older than the Joystack rules — skipping.');
+      log('   Get an engine that carries them:  joystack update');
+    }
+    return { ok: entity.ok && gate.ok && handbook.ok, skipped: true, errorCount: 0, warningCount: 0, entity, gate, handbook };
+  }
+
+  // A game that ships its own eslint.config.js owns its rules — we do not
+  // override it (and the scaffold's config already spreads ours in). Otherwise
+  // lint with the engine's recommended set, so a repo created before lint
+  // existed still gets the checks with zero setup.
+  const hasOwnConfig = CONFIG_NAMES.some((n) => existsSync(join(project.dir, n)));
+  const eslint = new ESLint({
+    cwd: project.dir,
+    fix,
+    ...(hasOwnConfig ? {} : { overrideConfigFile: true, baseConfig: configs.recommended }),
+  });
+
+  const results = await eslint.lintFiles(['.']);
+  if (fix) await ESLint.outputFixes(results);
+
+  let errorCount = 0;
+  let warningCount = 0;
+  for (const r of results) {
+    errorCount += r.errorCount;
+    warningCount += r.warningCount;
+  }
+
+  if (errorCount || warningCount) {
+    // ESLint's own stylish formatter: the creator's agent (and their editor)
+    // already know how to read it.
+    const formatter = await eslint.loadFormatter('stylish');
+    const text = await formatter.format(results);
+    if (text.trim()) log(text.trim());
+  }
+
+  // The closing line speaks for every step: a green line under a failed
+  // build gate would be the last thing read.
+  const failedSteps = [
+    !entity.ok && 'the entity check',
+    !gate.ok && 'the build gate',
+    !handbook.ok && 'the handbook path check',
+  ].filter(Boolean);
+  if (errorCount === 0 && failedSteps.length) {
+    const named = failedSteps.length > 1 ? `${failedSteps.slice(0, -1).join(', ')} and ${failedSteps.at(-1)}` : failedSteps[0];
+    log(`❌ joystack lint: ${named} failed (above); the ${results.length} file(s) have no rule errors`);
+  } else if (errorCount === 0) {
+    log(`✅ joystack lint: clean (${results.length} file(s))${fix ? ' — fixes applied' : ''}`);
+  } else {
+    log('');
+    log(`❌ joystack lint: ${errorCount} error(s) in ${results.filter((r) => r.errorCount).length} file(s)`);
+    if (results.some((r) => r.messages.some((m) => m.fix))) {
+      log('   Some of these are auto-fixable: `joystack lint --fix`');
+    }
+    log('   A rule is wrong about your code? `// eslint-disable-next-line <rule>` above the line.');
+  }
+
+  return {
+    ok: errorCount === 0 && entity.ok && gate.ok && handbook.ok,
+    skipped: false,
+    errorCount,
+    warningCount,
+    entity,
+    gate,
+    handbook,
+    files: results.map((r) => relative(project.dir, r.filePath)),
+  };
+}

package/lib/login.mjs

@@ -0,0 +1,134 @@
+// `joystack login` — device-flow authentication (the `gh auth login` shape):
+//
+//   1. ask the platform for a pairing (device_code for us, user_code for the
+//      human),
+//   2. show the human the short code and open /activate in their browser,
+//   3. poll until they approve,
+//   4. store the minted creator token in ~/.joystack/config.json.
+//
+// The secret never passes through the human's hands or the chat — non-dev
+// creators can't fumble a 40-char paste (why web-paste was rejected).
+import { spawn } from 'node:child_process';
+import { clearToken, setToken, getToken, getApiBase, DEFAULT_API_BASE } from './config.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function defaultOpenBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch {
+    // No browser available (headless) — the printed URL is the fallback.
+  }
+}
+
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body ?? {}),
+  });
+  return { status: res.status, body: await res.json().catch(() => ({})) };
+}
+
+export async function login({
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  openBrowser = defaultOpenBrowser,
+  pollIntervalMsOverride,
+} = {}) {
+  const { status, body: grant } = await postJson(`${apiBase}/api/device/code`);
+  if (status !== 200 || !grant.device_code) {
+    throw new Error(`could not start login against ${apiBase} (HTTP ${status})`);
+  }
+
+  log('');
+  log('  To connect this computer to your Joystack account:');
+  log('');
+  log(`  1. Open   ${grant.verification_uri}`);
+  log(`  2. Enter  ${grant.user_code}`);
+  log('');
+  log('  (opening your browser…)');
+  openBrowser(grant.verification_uri_complete ?? grant.verification_uri);
+
+  const intervalMs = pollIntervalMsOverride ?? (grant.interval ?? 5) * 1000;
+  const deadline = Date.now() + (grant.expires_in ?? 900) * 1000;
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+    const poll = await postJson(`${apiBase}/api/device/token`, { device_code: grant.device_code });
+    if (poll.status === 200 && poll.body.token) {
+      setToken(poll.body.token, { apiBase, userId: poll.body.user_id });
+      log('');
+      log(`  ✅ Logged in. This machine now builds and publishes as your account (${poll.body.user_id}).`);
+      return { userId: poll.body.user_id };
+    }
+    if (poll.body.error === 'authorization_pending') continue;
+    if (poll.body.error === 'expired_token') {
+      throw new Error('that login code expired before it was approved — run `joystack login` again for a fresh one.');
+    }
+    throw new Error(`login failed: ${poll.body.error ?? `HTTP ${poll.status}`}`);
+  }
+  throw new Error('login timed out — run `joystack login` again.');
+}
+
+export async function whoami({ apiBase = getApiBase(DEFAULT_API_BASE), log = console.log } = {}) {
+  const token = getToken();
+  if (!token) throw new Error('not logged in — run `joystack login` first.');
+  const res = await fetch(`${apiBase}/api/me`, { headers: { Authorization: `Bearer ${token}` } });
+  if (res.status === 401) throw new Error('stored token was rejected (unauthenticated) — run `joystack login` again.');
+  if (!res.ok) throw new Error(`whoami failed: HTTP ${res.status}`);
+  const me = await res.json();
+  log(`${me.name ?? me.userId}  (${me.userId})  via ${apiBase}`);
+  return me;
+}
+
+// `joystack logout [--all]`: revokes the stored token on the platform, or with
+// `all` every token of the account (every machine it is signed in on), then
+// forgets it here. The local copy is forgotten even when the platform cannot be
+// reached, and the output says what may still be valid in that case.
+export async function logout({ all = false, apiBase = getApiBase(DEFAULT_API_BASE), log = console.log, timeoutMs = 15_000 } = {}) {
+  const token = getToken();
+  if (!token) {
+    log('Not logged in on this machine.');
+    return { revoked: 0 };
+  }
+  let revoked = null;
+  let rejected = false;
+  let problem = null;
+  try {
+    const res = await fetch(`${apiBase}/api/creator/logout`, {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ all }),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (res.ok) {
+      const body = await res.json().catch(() => null);
+      revoked = typeof body?.revoked === 'number' ? body.revoked : null;
+    } else if (res.status === 401) {
+      rejected = true;
+    } else {
+      problem = `HTTP ${res.status}`;
+    }
+  } catch (err) {
+    problem = err?.message ?? String(err);
+  }
+  clearToken();
+  if (problem) {
+    log(`Logged out on this machine, but ${apiBase} could not revoke the token (${problem}); it stays valid until it expires.`);
+  } else if (rejected && all) {
+    log('Logged out on this machine. Its token had already expired or been revoked, so other machines were not signed out: run `joystack login`, then `joystack logout --all`.');
+  } else if (rejected) {
+    log('Logged out: the token had already expired or been revoked, and is removed from this machine.');
+  } else if (all) {
+    log(revoked === null ? 'Logged out everywhere.' : `Logged out everywhere: ${revoked} token${revoked === 1 ? '' : 's'} revoked.`);
+  } else {
+    log('Logged out: the token is revoked and removed from this machine.');
+  }
+  return { revoked, rejected, problem };
+}