@joystack/cli 0.0.0-stage → 0.1.43

package/lib/build-id.mjs

@@ -0,0 +1,130 @@
+// A build id: one short hash naming exactly the files a game build is made of.
+//
+// It is the game's identity for one state of its code, wherever that code
+// runs: a recording made under `joystack dev` carries the id of the files the dev
+// server was serving, and `joystack publish` computes the same id over the same
+// files (`collectGameFiles`, the set a publish uploads). Two builds with the
+// same id ran the same game code; any edit — a constant inside a tick body, a
+// renamed file, a file added — is a different id. That is finer than the code
+// fingerprint a recording also carries, which hashes the simulation's shape
+// (components, fields, ticks) and cannot see a number changed inside a tick.
+//
+// The id covers the game's own files only. The engine is named separately by
+// its version, and a build of the same files on two engines is the same build.
+//
+// Git is an annotation, never the identity: a game need not be in git, and a
+// build with uncommitted changes is not described by any commit. When the game
+// is in git, the build also carries the commit its files were checked out from
+// and whether they differ from it.
+//
+// Format, version 1: SHA-256 over the version line BUILD_ID_FORMAT followed by, for
+// each file in code-point order of its path, `<path>\0<sha256 of its bytes>\n`,
+// with paths relative to the game folder and `/`-separated. The id is the
+// first 12 hex characters. The per-file hash is what keeps a path and the
+// bytes after it from being shifted into each other. Any change to this format
+// changes every id, so it carries its own version in the hashed text.
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { collectGameFiles, isGameFilePath } from './game-files.mjs';
+import { findProject } from './project.mjs';
+import { BUILD_ID_FORMAT } from './legacy-names.mjs';
+
+export const BUILD_ID_RE = /^[0-9a-f]{12}$/;
+const FORMAT = BUILD_ID_FORMAT;
+
+const sha256 = (data) => createHash('sha256').update(data).digest('hex');
+
+/**
+ * The build id of a set of game files.
+ * @param {Map<string, Buffer|string>} files - path relative to the game folder → contents
+ * @returns {string} 12 lowercase hex characters
+ */
+export function buildIdOf(files) {
+  const h = createHash('sha256').update(FORMAT);
+  // Code-point order is UTF-8 byte order; JavaScript's own string comparison
+  // is UTF-16 unit order, which differs for characters past U+FFFF.
+  const paths = [...files.keys()].sort((a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)));
+  for (const path of paths) h.update(`${path}\0${sha256(files.get(path))}\n`);
+  return h.digest('hex').slice(0, 12);
+}
+
+// The commit a game folder is checked out at, and whether any of its build's
+// files differ from that commit — or null when the folder is not in a git
+// repository (or git is not installed). Only the build's files count: an
+// edited note, or another game in the same repository, is not a change to
+// this build.
+function gitStateOf(dir, buildPaths) {
+  const git = (args) => execFileSync('git', args, { cwd: dir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 });
+  let commit;
+  let prefix;
+  try {
+    commit = git(['rev-parse', 'HEAD']).trim();
+    // Only the newline goes: a folder's name can start with a space.
+    prefix = git(['rev-parse', '--show-prefix']).replace(/\n$/, '');
+  } catch {
+    return null;
+  }
+  let status = '';
+  try {
+    status = git(['status', '--porcelain=v1', '-z', '--untracked-files=all', '--', '.']);
+  } catch {
+    // Committed but unreadable status: the commit is still known, and whether
+    // the files differ from it is not.
+    return { commit, dirty: null };
+  }
+  // Porcelain paths are relative to the repository root. A rename entry is
+  // followed by its old path as a second NUL-separated field.
+  const entries = status.split('\0');
+  let dirty = false;
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.length < 4) continue;
+    const code = e.slice(0, 2);
+    // Each path with whether it is gone from the folder: a deletion, or the
+    // old side of a rename. A rename's old path follows it as its own field.
+    const paths = [[e.slice(3), code.includes('D')]];
+    if (code.includes('R')) paths.push([entries[++i] ?? '', true]);
+    else if (code.includes('C')) paths.push([entries[++i] ?? '', false]);
+    for (const [p, gone] of paths) {
+      if (!p.startsWith(prefix)) continue;
+      const rel = p.slice(prefix.length);
+      // A file that exists is judged by the build's own set, which has had the
+      // .gitignore applied; one that is gone no longer exists to be walked, so
+      // it is judged by its name.
+      if (buildPaths.has(rel) || (gone && isGameFilePath(rel))) dirty = true;
+    }
+  }
+  return { commit, dirty };
+}
+
+/**
+ * The build a game folder holds right now.
+ * @param {string} dir - the game folder
+ * @param {object} [opts]
+ * @param {Map<string, Buffer>} [opts.files] - the game's files, when already collected
+ * @param {boolean} [opts.git] - false to leave out the commit (no git processes)
+ * @returns {{ id: string, files: number, git: { commit: string, dirty: boolean|null } | null }}
+ */
+export function gameBuild(dir, { files = collectGameFiles(dir), git = true } = {}) {
+  return { id: buildIdOf(files), files: files.size, git: git ? gitStateOf(dir, new Set(files.keys())) : null };
+}
+
+/**
+ * `joystack build-id` — the build of the game this folder is in, as it is now.
+ * @param {{ cwd?: string, json?: boolean, log?: (m: string) => void }} [opts]
+ */
+export function buildIdCommand({ cwd = process.cwd(), json = false, log = console.log } = {}) {
+  const build = gameBuild(findProject(cwd).dir);
+  if (json) {
+    log(JSON.stringify(build));
+    return build;
+  }
+  log(`build ${build.id}`);
+  log(`${build.files} files`);
+  if (!build.git) log('not in a git repository');
+  else {
+    const state = build.git.dirty === true ? ' + uncommitted changes' : build.git.dirty === null ? ' (could not tell whether the files differ from it)' : '';
+    log(`commit ${build.git.commit}${state}`);
+  }
+  return build;
+}

package/lib/bundle-primitives.mjs

@@ -0,0 +1,123 @@
+// Bundle a server-backed game's primitives on the CREATOR's machine, with the
+// engine marked external.
+//
+// The publish endpoint is a Pages Function — a Worker with no filesystem and no
+// npm — so it cannot run a bundler. But real server primitives import npm
+// packages, WASM, and sibling game files that only a bundler with node_modules
+// on disk can resolve. So the CLI bundles `_local/primitives/index.js` into ONE
+// self-contained ESM module here (npm + WASM + local files inlined), and the
+// endpoint assembles the worker from it + our generated entry + the release's
+// pre-bundled engine runtime.
+//
+// The ENGINE seam (the dev convention): a primitive imports engine server-side
+// helpers via `/shared/ui/room/...` (or the `@joystack/engine` package). We
+// mark those EXTERNAL and rewrite them to `./rooms-runtime.js` — the engine
+// artifact the endpoint uploads alongside. Bundling the engine IN would
+// duplicate the room runtime and, worse, let a primitive smuggle its own room
+// class past the setInterval/park cost boundary. Keeping it external means the
+// worker's room code is always ours.
+import { DOOR_FILTER, ENGINE_PACKAGE_FILTER, canonicalSpecifier } from './legacy-names.mjs';
+import { assertNoOverrideCycle, PRIMITIVES_DIR, SERVER_BARREL, renderBarrel, scanPrimitives } from './primitives.mjs';
+import { scanEntityComponents, renderEntityComponents } from './room-server.mjs';
+import { shadowResolvePlugin } from './shadow-resolve.mjs';
+import { join } from 'node:path';
+
+// The bundled barrel's path in the upload — the same path the endpoint detects a
+// server-backed game by (SERVER_PRIMITIVES_PATH in game-server-deploy.ts).
+// The creator never writes it; the CLI generates it from the directory scan.
+export const PRIMITIVES_ENTRY = SERVER_BARREL;
+
+// The module name the generated worker entry imports the runtime from; every
+// engine import in the primitives bundle is rewritten to this.
+export const ENGINE_ARTIFACT_MODULE = './rooms-runtime.js';
+
+export async function bundlePrimitives(projectDir, { esbuildImpl, engineSharedDir } = {}) {
+  // The barrel is GENERATED, not authored. A creator adds a primitive by adding
+  // a file to `overrides/shared/ui/room/primitives/` — and an entity component
+  // by adding a folder under components/ — there is no list to keep in sync,
+  // and therefore no way for the list and the folder to disagree.
+  const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
+  const engineShared = engineSharedDir ?? join(projectDir, 'node_modules/@joystack/engine/shared');
+  const entityComponents = await scanEntityComponents(projectDir, engineShared); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
+    throw new Error(
+      `nothing to bundle — ${PRIMITIVES_DIR}/ and components/ are both empty (this is not a server-backed game)`,
+    );
+  }
+  assertNoOverrideCycle(primitives, projectDir, engineShared);
+
+  const esbuild = esbuildImpl ?? (await import('esbuild'));
+
+  // Every engine specifier the primitives import, captured for reporting.
+  const externals = [];
+  const toArtifact = (args) => {
+    externals.push(args.path);
+    return { path: ENGINE_ARTIFACT_MODULE, external: true };
+  };
+
+  const enginePlugin = {
+    name: 'joystack-engine-external',
+    setup(build) {
+      // `/shared/ui/room/...` — the dev alias the room server + primitives use.
+      build.onResolve({ filter: /^\/shared\// }, toArtifact);
+      // The engine package specifier, if a primitive imports it by name.
+      build.onResolve({ filter: ENGINE_PACKAGE_FILTER }, (args) => toArtifact({ ...args, path: canonicalSpecifier(args.path) }));
+      // Workers-runtime builtins are provided at execution — never bundled.
+      build.onResolve({ filter: /^cloudflare:/ }, (args) => ({ path: args.path, external: true }));
+      // A bare joystack door has never resolved in this build, and the failure used
+      // to be esbuild's. It cannot be any more: a game now carries a real
+      // node_modules/joystack (joystack-node-doors.mjs), so the specifier resolves to
+      // a file that refuses at runtime, and a bundle that got that far would
+      // take the refusal into the worker instead of failing here. Refused by
+      // name so the message says which door and where it belongs.
+      build.onResolve({ filter: DOOR_FILTER }, (args) => ({
+        errors: [{
+          text: `\`${args.path}\` cannot be used here — the primitives bundle runs on the server, and `
+            + 'the joystack doors are the page\'s. Import what this file needs from the engine directly '
+            + '(`@joystack/engine/...` or a `/shared/...` path). See shared/docs/api.md.',
+        }],
+      }));
+    },
+  };
+
+  const result = await esbuild.build({
+    // No entry file on disk: the generated barrel is fed straight in, resolved
+    // against the game root so `./overrides/...` means what it says. Same shape
+    // the dev room server uses (lib/room-server.mjs) — one contract, two builds.
+    stdin: {
+      contents: `${renderBarrel(primitives)}\n${renderEntityComponents(entityComponents)}\n`,
+      resolveDir: projectDir,
+      sourcefile: 'joystack-primitives.js',
+      loader: 'js',
+    },
+    absWorkingDir: projectDir,
+    bundle: true,
+    write: false,
+    format: 'esm',
+    // workerd is browser-shaped; the engine artifact is built the same way.
+    platform: 'browser',
+    target: 'esnext',
+    legalComments: 'none',
+    // Prefer worker builds of packages that ship a `workerd`/`worker` export
+    // condition (e.g. the quickjs WASM variant wordsmith uses).
+    conditions: ['workerd', 'worker'],
+    // Inline WASM as bytes so the bundle stays ONE self-contained module — no
+    // extra CompiledWasm part to thread through the 3-module upload.
+    loader: { '.wasm': 'binary' },
+    plugins: [
+      // An override's relative imports fall through to the engine, as they do in
+      // the browser — and here the engine is EXTERNAL, so they land on the
+      // release's pre-bundled runtime rather than being inlined. That is what
+      // makes `import { PlayerBody } from './engine.js'` work inside an override.
+      shadowResolvePlugin({
+        projectDir,
+        sharedDir: engineShared,
+        engineExternal: ENGINE_ARTIFACT_MODULE,
+        onEngineHit: (spec) => externals.push(spec),
+      }),
+      enginePlugin,
+    ],
+  });
+
+  return { source: result.outputFiles[0].text, externals };
+}

package/lib/changelog.mjs

@@ -0,0 +1,193 @@
+// `joystack changelog` — what changed in the engine.
+//
+// Why it exists: an update that reports only a version bump and the SKILL FILES
+// it rewrote says nothing about what changed in the engine itself, so the agent
+// crosses versions of the shared library blind — it cannot know a call it makes
+// is now wrong, or that the thing it was about to hand-roll now exists.
+//
+// Two moments matter, and they are different:
+//   BEFORE an update — "what am I about to take?"   → the default, vs your pin
+//   AFTER  an update — "what do I have to change?"  → the BREAKING callout
+//
+// This command sends no token: a version number is not a secret, and requiring
+// a login to read what an update would do to you would be backwards. Only the
+// DOWNLOAD carries a token. The backend's listing route
+// (backend/api/src/routes/engine.js, listEngines) does require a creator token,
+// so against that backend this command is refused until one side changes.
+import { findProject } from './project.mjs';
+import { readEnginePin } from './engine.mjs';
+import { DEFAULT_API_BASE, getApiBase, getToken } from './config.mjs';
+
+const RULE = '─'.repeat(64);
+
+// Semver by NUMBER. String order would put 0.1.9 after 0.1.10 and quietly show
+// the wrong set — the kind of bug nobody notices until a release is missing
+// from someone's update.
+//
+// Release candidates carry a pre-release suffix (`0.2.0-rc.1`); a game pinned to
+// one still asks this to compare versions (e.g. `joystack changelog` filters by the
+// pin). Standard semver precedence: a pre-release ranks just BELOW its release
+// (`0.2.0-rc.1` < `0.2.0`), and two pre-releases of the same core order by their
+// suffix. Without this the raw `split('.').map(Number)` produced NaN and silently
+// mis-ranked every suffixed version.
+export function compareVersions(a, b) {
+  const parse = (v) => {
+    const s = String(v);
+    const dash = s.indexOf('-');
+    const core = dash < 0 ? s : s.slice(0, dash);
+    const pre = dash < 0 ? '' : s.slice(dash + 1);
+    return { nums: core.split('.').map(Number), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    if ((A.nums[i] ?? 0) !== (B.nums[i] ?? 0)) return (A.nums[i] ?? 0) > (B.nums[i] ?? 0) ? 1 : -1;
+  }
+  // Same numeric core: a release outranks its pre-releases; two pre-releases
+  // order lexically by suffix (a stable, total order — the label is opaque).
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
+}
+
+export function selectReleases(releases, { pinned, version, all } = {}) {
+  const newestFirst = [...releases].sort((a, b) => compareVersions(b.version, a.version));
+
+  if (version) {
+    const one = newestFirst.find((r) => r.version === version);
+    if (!one) {
+      throw new Error(
+        `no engine release ${version}. Known: ${newestFirst.map((r) => r.version).join(', ')}`,
+      );
+    }
+    return [one];
+  }
+  if (all) return newestFirst;
+  // No pin means the game has never installed an engine (no `dev` yet). There is
+  // no "since" to work from, so show what it would get: the newest.
+  if (!pinned) return newestFirst.slice(0, 1);
+  return newestFirst.filter((r) => compareVersions(r.version, pinned) > 0);
+}
+
+// The actionable half. Everything else in a changelog is informative; a BREAKING
+// entry means code in THIS game has to change, so it gets hoisted out of the
+// prose and repeated on its own — with its migration line, which is the part the
+// reader actually needs.
+//
+// The marker is POSITIONAL: a breaking change is a bullet that STARTS with it.
+// Two false positives got here by loosening that, and both were found by reading
+// real output rather than by any test:
+//
+//   1. matching the bare word case-insensitively flagged the ordinary sentence
+//      "when your game turns out to be breaking a Joystack rule";
+//   2. matching `**BREAKING**` anywhere on a line flagged a changelog entry that
+//      merely DESCRIBED the feature ("...calls out **BREAKING** entries
+//      separately...") — prose about breaking changes is not a breaking change.
+//
+// A callout that cries wolf is worse than no callout: it gets ignored, and the
+// next real one is ignored with it.
+// Bold form is case-insensitive (`**BREAKING**`, `**Breaking**` — the markup is
+// the deliberate part). The bare-word form must be ALL CAPS with punctuation, so
+// a bullet that merely opens with the ordinary word ("- breaking the sound
+// barrier: …") can't pass as a marker.
+const BREAKING_BOLD = /^\s*[-*]\s+\*\*breaking\*\*/i;
+const BREAKING_CAPS = /^\s*[-*]\s+BREAKING\b\s*[:—–-]/;
+const BREAKING_BULLET = { test: (l) => BREAKING_BOLD.test(l) || BREAKING_CAPS.test(l) };
+
+// True for a line that continues the bullet above it: indented, non-blank, and
+// not itself a new bullet or heading. That's how the migration line rides along.
+const CONTINUATION = /^\s+\S/;
+const NEW_BULLET_OR_HEADING = /^\s*(?:[-*]\s|#)/;
+
+export function breakingLines(notes) {
+  const lines = (notes ?? '').split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!BREAKING_BULLET.test(lines[i])) continue;
+    const block = [lines[i].trim()];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (!CONTINUATION.test(l) || NEW_BULLET_OR_HEADING.test(l)) break;
+      block.push(l.trim());
+      i = j;
+    }
+    out.push(block.join(' '));
+  }
+  return out;
+}
+
+export function renderReleases(selected, { pinned, latest } = {}) {
+  const out = [];
+  if (!selected.length) {
+    out.push(`Engine ${pinned ?? '(unpinned)'} — nothing new. This game is up to date with ${latest}.`);
+    return out.join('\n');
+  }
+
+  const head =
+    selected.length === 1
+      ? `Engine ${selected[0].version}`
+      : `${selected.length} engine releases newer than ${pinned}, newest first (latest is ${latest})`;
+  out.push(head, '');
+
+  for (const r of selected) {
+    out.push(RULE);
+    out.push(`## ${r.version}`);
+    out.push('');
+    out.push(r.notes?.trim() ? r.notes.trim() : '  (no notes recorded — this release predates the changelog)');
+    out.push('');
+  }
+
+  const breaking = selected.flatMap((r) => breakingLines(r.notes).map((l) => `   ${r.version}  ${l}`));
+  if (breaking.length) {
+    out.push(RULE);
+    out.push('');
+    out.push(
+      `⚠  ${breaking.length} BREAKING change${breaking.length === 1 ? '' : 's'} in this range.`,
+      '   These are the entries that mean code in THIS game has to change — check each one',
+      '   against the game before you call the update done.',
+      '',
+      ...breaking,
+      '',
+    );
+  }
+  return out.join('\n');
+}
+
+// The release list is behind the same sign-in as every /api/creator route, so
+// the machine's token is sent when it has one, and a refusal says to sign in.
+export async function fetchReleases({ apiBase, fetchImpl = fetch, token = getToken() }) {
+  const res = await fetchImpl(`${apiBase}/api/creator/engine`, token ? { headers: { Authorization: `Bearer ${token}` } } : {});
+  if (res.status === 401) throw new Error('reading the engine changelog needs a signed-in machine — run `joystack login` and retry.');
+  if (!res.ok) throw new Error(`could not read the engine changelog (HTTP ${res.status})`);
+  const body = await res.json();
+  // An older platform has no `releases` key. Printing "nothing new" there would
+  // be a lie in the most dangerous direction — it reads as "safe to update".
+  //
+  // Do NOT tell them to upgrade the CLI: the missing half is the PLATFORM's, and
+  // a creator cannot deploy it. Advice they can't act on is worse than none.
+  if (!Array.isArray(body.releases)) {
+    throw new Error(
+      'this Joystack platform is not serving the engine changelog yet. Nothing is wrong with your ' +
+        'game — try again later, and `npx joystack update` still works in the meantime.',
+    );
+  }
+  return body;
+}
+
+export async function changelog({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  fetchImpl = fetch,
+  token = getToken(),
+  readPin,
+  version,
+  all = false,
+} = {}) {
+  const pinned = readPin ? readPin() : readEnginePin(findProject(cwd).dir);
+  const { releases, latest } = await fetchReleases({ apiBase, fetchImpl, token });
+  const selected = selectReleases(releases, { pinned, version, all });
+  log(renderReleases(selected, { pinned, latest }));
+  return { pinned, latest, selected };
+}

package/lib/config.mjs

@@ -0,0 +1,56 @@
+// CLI config at ~/.joystack/config.json (JOYSTACK_HOME overrides the directory —
+// used by tests and by anyone running isolated profiles). Holds the creator
+// token minted by `joystack login`; written 0600 because it's a credential.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readEnv } from './legacy-names.mjs';
+
+// The platform API the CLI talks to when neither JOYSTACK_API_BASE nor the
+// config file names another.
+export const DEFAULT_API_BASE = 'https://api.joystack.ai';
+
+function configDir() {
+  return readEnv('JOYSTACK_HOME') || join(homedir(), '.joystack');
+}
+
+export function configPath() {
+  return join(configDir(), 'config.json');
+}
+
+// Machine-wide artifact cache (engine tarballs). Lives beside the config so
+// JOYSTACK_HOME isolates it too.
+export function cacheDir() {
+  return join(configDir(), 'cache');
+}
+
+export function readConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  const dir = configDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function getToken() {
+  return readConfig().token ?? null;
+}
+
+export function setToken(token, extra = {}) {
+  writeConfig({ ...readConfig(), ...extra, token });
+}
+
+export function clearToken() {
+  const { token, ...rest } = readConfig();
+  writeConfig(rest);
+}
+
+export function getApiBase(fallback) {
+  return readEnv('JOYSTACK_API_BASE') || readConfig().apiBase || fallback;
+}