@joystack/cli 0.0.0-stage → 0.1.44

package/lib/create.mjs

@@ -0,0 +1,243 @@
+// `joystack create <name>` — bootstrap a standalone Joystack game.
+//
+// The create-next-app gesture: one command → a complete folder that is its
+// own repo, where `joystack dev` immediately serves a WORKING multiplayer game
+// (the platform is not optional — the scaffold joins a room on line one, no
+// "add multiplayer later" tier). The folder name is the slug.
+//
+// ── Where the creator's files come from ─────────────────────────────────────
+//
+// EVERYTHING a creator receives comes from the versioned engine artifact: the
+// starter game (`scaffold/`) and the agent surface (`agent-surface/` — skills
+// plus the Layer-0 managed block). This npm package ships CODE ONLY.
+//
+// Shipping a second copy of the surface (a `template/` folder) inside this
+// package would be a bug with a long fuse. npm and the engine registry are two
+// independent, immutable release lanes, so two copies drift the moment one ships
+// without the other — and seeding from the CLI while stamping the ownership
+// record with the ENGINE's version makes that record false from the start. The
+// creator would pay for it on their first `joystack update`: skills they never
+// touched would change under them, and a skill the CLI shipped but the engine
+// didn't would be silently DELETED (agent-surface.mjs prunes files it owns that
+// the artifact no longer lists), on a repo minutes old.
+//
+// One authored copy, one release lane. A skill or scaffold change ships with an
+// engine release alone; the CLI is released only when the CLI's own code
+// changes.
+//
+// The consequence, and it is deliberate: `create` needs the engine, and the
+// engine download is login-gated — so CREATE SIGNS YOU IN. That gate existed
+// anyway, one command later, at first `dev`. This moves it to where the creator
+// is already waiting and leaves `dev` instant.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, rmSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative, dirname } from 'node:path';
+import { DEFAULT_API_BASE, getApiBase } from './config.mjs';
+import { runNpm } from './npm.mjs';
+import { ensureEngine } from './engine.mjs';
+import { reconcileAgentSurface } from './agent-surface.mjs';
+import { readEnv } from './legacy-names.mjs';
+
+// The starter game, inside the installed engine artifact.
+export const SCAFFOLD_DIR = 'scaffold';
+
+const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
+
+// npm is making install scripts opt-in: npm 11 warns that a package's
+// postinstall is "not covered by allowScripts", npm 12 SKIPS it by default.
+// esbuild and workerd (both under partykit) fetch their native binaries in a
+// postinstall — skipped, `joystack dev` cannot start and nothing says why. The
+// scaffold therefore ships its own approval, so a stranger's first install is
+// clean on a strict npm without them ever running `npm approve-scripts`.
+//
+// Deliberately UNPINNED (name-only, not `esbuild@0.21.5`): partykit moves its
+// esbuild/workerd pins between releases, and a version-pinned approval would
+// quietly stop covering them on the next bump — the same silent breakage,
+// later.
+// fsevents is macOS-only (an optional dep of the file watchers) — it never
+// installs on Windows, so the entry is simply unused there. Approving it
+// keeps a Mac creator's first install warning-free, and under npm 12 keeps
+// the watcher on native FSEvents instead of silently degrading to polling.
+const ALLOW_SCRIPTS = { esbuild: true, workerd: true, fsevents: true };
+
+// Smokes drive a real browser, so playwright ships in every scaffold's
+// devDependencies and the Chromium binary is fetched at create time — a
+// surprise "npm i -D playwright" + browser download mid-build is exactly
+// what create-time provisioning exists to prevent.
+const PLAYWRIGHT_SPEC = '^1.61.1';
+
+// The Joystack rules ship as an ESLint config (the scaffold's eslint.config.js,
+// importing the rules from the installed engine), so they squiggle in the
+// creator's editor as the code is written — a far tighter loop than a failing
+// gate, and the whole reason this is ESLint and not a bespoke scanner. That
+// only works if eslint is actually installed, so it is a scaffold
+// devDependency, exactly like playwright. `joystack test` also runs it.
+const ESLINT_SPEC = '^10.7.0';
+
+// Copy the starter game out of the artifact. One rename: `gitignore` →
+// `.gitignore` (npm pack silently strips .gitignore files from a package, so
+// the artifact stores it dot-less).
+function copyScaffold(engineDir, dir, name, version) {
+  const root = join(engineDir, SCAFFOLD_DIR);
+  if (!existsSync(root)) {
+    // RELEASE ORDER: the engine must ship the scaffold BEFORE a CLI that expects
+    // it. If this CLI ever reaches a creator ahead of that engine, `create`
+    // resolves the latest engine, finds no starter game, and every create on
+    // earth fails — so say exactly what is wrong, and never blame the creator's
+    // setup for our release ordering.
+    throw new Error(
+      `Joystack engine ${version} ships no starter game — it predates engine-owned scaffolding. ` +
+        'This is a platform-side issue, not something you did: please report it (`npx joystack feedback`) or retry shortly.',
+    );
+  }
+  for (const entry of readdirSync(root, { withFileTypes: true, recursive: true })) {
+    if (!entry.isFile()) continue;
+    const rel = relative(root, join(entry.parentPath, entry.name));
+    const dest = join(dir, rel === 'gitignore' ? '.gitignore' : rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(join(root, rel), 'utf8').replaceAll('{{name}}', name));
+  }
+}
+
+async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile }) {
+  // Written FIRST, and without the engine pin: npm needs a package.json to
+  // install into, and `ensureEngine` writes the pin itself once it knows which
+  // version it actually installed. ONE writer for the pin — the old code had
+  // `create` resolve it and `ensureEngine` resolve it again, which is precisely
+  // how they came to disagree.
+  writeFileSync(
+    join(dir, 'package.json'),
+    JSON.stringify(
+      {
+        name,
+        private: true,
+        // Every file a game is made of is an ES module.
+        type: 'module',
+        description: `A Joystack game. Play at https://${name}.joystack.games/`,
+        // The scaffold is a framework-v2 game (entities + traits + a world root,
+        // lowered to the engine runtime on this machine). This flag is what makes
+        // the room server build the v2 room and the serve path inject the v2
+        // import map + skeleton.
+        joystack: { framework: 'v2' },
+        scripts: { dev: 'joystack dev', publish: 'joystack publish', test: 'joystack test', lint: 'joystack lint' },
+        devDependencies: { '@joystack/cli': cliSpec, playwright: PLAYWRIGHT_SPEC, eslint: ESLINT_SPEC },
+        allowScripts: ALLOW_SCRIPTS,
+      },
+      null,
+      2,
+    ) + '\n',
+  );
+
+  if (install) {
+    log(`Installing the CLI (npm install in ${name}/)…`);
+    runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
+  }
+
+  // The engine — and with it the starter game and the agent skills. Signs the
+  // creator in via the device flow if this machine has no token yet, and writes
+  // the `joystack.engine` pin.
+  const engine = await ensure(dir, { apiBase, log });
+
+  copyScaffold(engine.dir, dir, name, engine.version);
+
+  // The agent surface is PLATFORM-owned and reconciled on every `joystack update`,
+  // so it is placed here by the very code that will later update it — reading
+  // the artifact, recording the real hash of what landed. That identity is the
+  // whole point: a fresh repo's first `update` is now a genuine no-op, because
+  // the bytes on disk and the bytes in the ownership record came from the same
+  // artifact.
+  reconcile(dir, engine.dir, { log });
+
+  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
+  // discover project skills at .agents/skills/ — alias it to the same files.
+  // After reconcile, so the link is never dangling.
+  try {
+    mkdirSync(join(dir, '.agents'), { recursive: true });
+    symlinkSync(join('..', '.claude', 'skills'), join(dir, '.agents', 'skills'), 'dir');
+  } catch {
+    // e.g. Windows without symlink rights — Claude Code (and any tool that
+    // reads .claude/skills/ directly) still works.
+  }
+
+  if (install) {
+    // Fetch the smoke-test browser NOW (cached machine-wide per version) so
+    // the first `joystack test` never stalls on a surprise download mid-build.
+    // Resolved + run via node directly — NEVER a nested `npx`: when create
+    // itself runs under `npm exec --package=<tarball>` (the stranger gesture),
+    // the inherited npm_config_* env makes an inner npx try to re-install the
+    // tarball and cancel.
+    try {
+      log('Fetching the test browser (Chromium — one-time download, cached for every game)…');
+      const req = createRequire(join(dir, 'package.json'));
+      const playwrightCli = join(dirname(req.resolve('playwright/package.json')), 'cli.js');
+      execFileSync(process.execPath, [playwrightCli, 'install', 'chromium'], { cwd: dir, stdio: 'inherit' });
+    } catch {
+      log('⚠️  Could not fetch Chromium (offline?) — `joystack test` will fetch it when first needed.');
+    }
+  }
+
+  try {
+    execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'pipe' });
+    // The initial commit is the first revert baseline (rejecting milestone 1
+    // resets to it) and what lets `git worktree add` work — on a never-committed
+    // repo it silently creates an empty orphan lane instead. It carries the
+    // engine pin AND the true agent surface, so a reset to baseline cannot
+    // silently change either.
+    execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
+    const msg = ['commit', '-q', '-m', 'initial scaffold (joystack create)'];
+    try {
+      execFileSync('git', msg, { cwd: dir, stdio: 'pipe' });
+    } catch {
+      // Non-dev machines often have no git identity configured — commit as
+      // the scaffold rather than leaving the repo without a baseline.
+      execFileSync('git', ['-c', 'user.name=Joystack', '-c', 'user.email=create@joystack.ai', ...msg], {
+        cwd: dir,
+        stdio: 'pipe',
+      });
+    }
+  } catch {
+    // git not installed — fine, the folder still works.
+  }
+
+  log('');
+  log(`✅ ${name} is ready (Joystack engine ${engine.version}).`);
+  log(`   cd ${name} && npx joystack dev`);
+  return { dir, engineVersion: engine.version };
+}
+
+export async function create({
+  name,
+  cwd = process.cwd(),
+  install = true,
+  cliSpec = readEnv('JOYSTACK_CREATE_CLI_SPEC') || '^0.1.0',
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  // Seams, mirroring `joystack update` — the tests drive a real artifact on disk
+  // through the real reconciler, with no network and no account.
+  ensure = ensureEngine,
+  reconcile = reconcileAgentSurface,
+} = {}) {
+  if (!name || !NAME_OK.test(name)) {
+    throw new Error(
+      `"${name ?? ''}" won't work as a game name — use lowercase letters, digits, and dashes (it becomes the URL: <name>.joystack.games).`,
+    );
+  }
+  const dir = join(cwd, name);
+  if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
+
+  mkdirSync(dir, { recursive: true });
+  try {
+    return await scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, reconcile });
+  } catch (err) {
+    // ATOMIC. Everything a creator receives now arrives over the network behind
+    // a login, so a failure anywhere leaves a folder with no game, no skills and
+    // no initial commit — one that `joystack dev` cannot run, and that `create`
+    // would refuse to retry into ("already exists"). A folder that looks like a
+    // game and isn't one is worse than no folder at all: it fails later,
+    // somewhere more confusing. Take it back, and say so.
+    rmSync(dir, { recursive: true, force: true });
+    log(`\n⚠️  Could not finish creating ${name} — removed the incomplete folder so you can retry cleanly.`);
+    throw err;
+  }
+}