@looop-games/cli 0.1.2 → 0.1.4

package/bin/looop.mjs

@@ -7,6 +7,9 @@ import { dev } from '../lib/dev.mjs';
 import { login, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
+import { testCmd } from '../lib/test-cmd.mjs';
+import { update } from '../lib/update.mjs';
+import { sendFeedback } from '../lib/feedback.mjs';
 import { clearToken } from '../lib/config.mjs';
 
 const [, , cmd, ...rest] = process.argv;
@@ -21,7 +24,10 @@ const HELP = `looop — build and run Looop games
 Usage:
   looop create <name>        Bootstrap a new game folder (multiplayer works out of the box)
   looop dev [--port <n>]     Run the full dev stack (game + multiplayer + services)
+  looop test                 Run the game's tests (*.test.mjs) and smokes (*.smoke.mjs)
+  looop update               Move this game to the latest engine release (re-pins looop.engine)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
+  looop feedback             Send the unsent reports under notes/feedback/ to the Looop team
   looop login                Authenticate this machine as your Looop player account
   looop logout               Forget the stored token
   looop whoami               Show who this machine publishes as
@@ -47,9 +53,19 @@ try {
     case 'create':
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;
+    case 'test': {
+      const { ok } = await testCmd();
+      process.exit(ok ? 0 : 1);
+    }
+    case 'update':
+      await update();
+      break;
     case 'publish':
       await publish({ slug: flag('slug') });
       break;
+    case 'feedback':
+      await sendFeedback();
+      break;
     case 'login':
       await login();
       break;

package/lib/bundle-primitives.mjs

@@ -0,0 +1,77 @@
+// cuqfzo Phase 2 / Option B — Slice 2: 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 `@looop-games/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 { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+// The primitives barrel — same path the endpoint detects a server-backed game
+// by (SERVER_PRIMITIVES_PATH in game-server-deploy.ts).
+export const PRIMITIVES_ENTRY = '_local/primitives/index.js';
+
+// 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 } = {}) {
+  const entry = join(projectDir, PRIMITIVES_ENTRY);
+  if (!existsSync(entry)) {
+    throw new Error(
+      `no server primitives to bundle — ${PRIMITIVES_ENTRY} not found (this is not a server-backed game)`,
+    );
+  }
+  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: 'looop-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: /^@looop-games\/engine(\/|$)/ }, toArtifact);
+      // Workers-runtime builtins are provided at execution — never bundled.
+      build.onResolve({ filter: /^cloudflare:/ }, (args) => ({ path: args.path, external: true }));
+    },
+  };
+
+  const result = await esbuild.build({
+    entryPoints: [entry],
+    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: [enginePlugin],
+  });
+
+  return { source: result.outputFiles[0].text, externals };
+}

package/lib/bundle-primitives.test.mjs

@@ -0,0 +1,95 @@
+// cuqfzo Phase 2 / Option B — Slice 2: the CLI "bundle primitives, engine
+// external" step. A creator's server primitives can import npm packages, WASM,
+// and sibling game files; the publish endpoint (a Pages Function) has no
+// bundler, so the CLI bundles them into ONE self-contained module here. The
+// engine surface a primitive imports (`/shared/ui/room/...`, or the engine
+// package) is marked EXTERNAL and rewritten to `./rooms-runtime.js` — the
+// pre-bundled engine artifact the endpoint uploads alongside; bundling it in
+// would duplicate the room runtime and bypass the cost boundary.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { bundlePrimitives } from './bundle-primitives.mjs';
+
+// A fixture game whose primitives exercise all three seams: an npm dep, a WASM
+// module, and an engine import. Returns the project dir (caller cleans up).
+function fixture() {
+  const dir = mkdtempSync(join(tmpdir(), 'looop-bundle-'));
+  // A fake installed npm package (proves node_modules resolution + inlining).
+  mkdirSync(join(dir, 'node_modules/tiny-dep'), { recursive: true });
+  writeFileSync(join(dir, 'node_modules/tiny-dep/package.json'), JSON.stringify({ name: 'tiny-dep', version: '1.0.0', main: 'index.js', type: 'module' }));
+  writeFileSync(join(dir, 'node_modules/tiny-dep/index.js'), 'export const DEP_MARKER = 41;\n');
+  // A tiny WASM blob (bytes only — the bundler embeds it; validity is the
+  // smoke's job). The magic header makes it a recognizable, real .wasm file.
+  mkdirSync(join(dir, '_local/primitives'), { recursive: true });
+  writeFileSync(join(dir, '_local/primitives/mod.wasm'), Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]));
+  // The primitives barrel: engine import (external), npm import (inline),
+  // sibling wasm import (inline).
+  writeFileSync(
+    join(dir, '_local/primitives/index.js'),
+    [
+      "import { runEffect } from '/shared/ui/room/primitives/effects.js';",
+      "import { DEP_MARKER } from 'tiny-dep';",
+      "import wasmBytes from './mod.wasm';",
+      'export const extraPrimitives = {',
+      "  demo: class { constructor() { this.v = DEP_MARKER; this.w = wasmBytes; this.e = runEffect; } },",
+      '};',
+    ].join('\n'),
+  );
+  return dir;
+}
+
+test('bundles npm deps and WASM INLINE, and leaves the engine import external as ./rooms-runtime.js', async () => {
+  const dir = fixture();
+  try {
+    const { source } = await bundlePrimitives(dir);
+    assert.equal(typeof source, 'string');
+
+    // npm dep inlined — its value is present, its bare specifier is gone.
+    assert.match(source, /41/, 'the npm dep value should be inlined');
+    assert.doesNotMatch(source, /from\s*["']tiny-dep["']/, 'the npm dep must not remain an external import');
+
+    // WASM inlined — no leftover ".wasm" import; the magic bytes appear (base64
+    // "AGFzbQ" is the standard encoding of \0asm\1\0\0\0).
+    assert.doesNotMatch(source, /\.wasm["']/, 'the wasm import must be inlined, not external');
+    assert.match(source, /AGFzbQ/, 'the wasm bytes should be embedded (base64)');
+
+    // Engine import is EXTERNAL and rewritten to the artifact module.
+    assert.match(source, /from\s*["']\.\/rooms-runtime\.js["']/, 'engine imports must be external → ./rooms-runtime.js');
+    assert.match(source, /runEffect/, 'the imported engine symbol is preserved');
+    // The original /shared/... specifier is gone (rewritten).
+    assert.doesNotMatch(source, /\/shared\/ui\/room/, 'the /shared/... specifier must be rewritten away');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('the ONLY external import in the bundle is the engine artifact (everything else is self-contained)', async () => {
+  const dir = fixture();
+  try {
+    const { source, externals } = await bundlePrimitives(dir);
+    // Every `from "..."` in the output must point at the artifact (or a
+    // cloudflare: builtin) — nothing else may be left unresolved.
+    const froms = [...source.matchAll(/\bfrom\s*["']([^"']+)["']/g)].map((m) => m[1]);
+    for (const spec of froms) {
+      assert.ok(
+        spec === './rooms-runtime.js' || spec.startsWith('cloudflare:'),
+        `unexpected external in the primitives bundle: ${spec}`,
+      );
+    }
+    assert.deepEqual([...new Set(externals)].sort(), ['/shared/ui/room/primitives/effects.js']);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('throws a clear error when the primitives barrel is missing (not a server-backed game)', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'looop-bundle-empty-'));
+  try {
+    await assert.rejects(() => bundlePrimitives(dir), /primitives/i);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/lib/create.mjs

@@ -4,91 +4,85 @@
 // own repo, where `looop dev` immediately serves a WORKING multiplayer game
 // (the platform is not optional — the template joins a room on line one, no
 // "add multiplayer later" tier). The folder name is the slug.
+//
+// The scaffold lives as REAL FILES in ../template/ (creator-harness Slice 1)
+// — edit the template there, not string literals here. `create` copies it
+// with a {{name}} substitution pass. One rename on copy, an npm-pack
+// artifact: `gitignore` → `.gitignore` (npm silently strips .gitignore
+// files from packages). package.json is generated below instead of shipped
+// in the template (nested package.json files confuse npm's packer, and it
+// carries the dynamic cliSpec anyway).
 import { execFileSync } from 'node:child_process';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { writeAgentFiles } from './agent-files.mjs';
-
-const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
-
-const html = (name) => `<!doctype html>
-<html>
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>${name}</title>
-  <style>
-    html, body { margin: 0; height: 100%; background: #0f1220; overflow: hidden; }
-    canvas { display: block; width: 100vw; height: 100vh; }
-  </style>
-</head>
-<body>
-  <canvas id="game"></canvas>
-  <script type="module" src="game.js"></script>
-</body>
-</html>
-`;
+import { existsSync, mkdirSync, writeFileSync, readdirSync, readFileSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative, dirname } from 'node:path';
+import { getApiBase } from './config.mjs';
+import { DEFAULT_API_BASE } from './llm-shim.mjs';
+import { runNpm } from './npm.mjs';
 
-const gameJs = () => `// A tiny multiplayer plaza — walk around, see everyone else.
-// This is a REAL Looop game: it already syncs across browsers and works
-// published. Reshape it into your game; the room + identity plumbing stays.
-import { createRoom, getIdentity } from '/shared/ui/room/client.js';
+export const TEMPLATE_DIR = join(import.meta.dirname, '..', 'template');
 
-const me = getIdentity(); // injected by the platform (fails closed if absent)
-const canvas = document.getElementById('game');
-const ctx = canvas.getContext('2d');
-const size = () => { canvas.width = innerWidth; canvas.height = innerHeight; };
-addEventListener('resize', size); size();
-
-const self = { name: me.name, color: me.color, x: Math.random() * 400 - 200, y: Math.random() * 400 - 200 };
-// One room per game: the slug (injected by the serve path) is the room id.
-const room = createRoom({ room: window.GAME_SLUG ?? 'dev', self });
+const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
 
-let others = new Map();
-room.onPlayers = (players) => { others = new Map(players); };
-// Handy for smokes: how many players does this client see (self included)?
-window.__looopPlayers = () => others.size + 1;
+// 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, `looop 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. Caught by our first Windows creator, 2026-07-11.
+// 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 };
 
-const keys = new Set();
-addEventListener('keydown', (e) => keys.add(e.key.toLowerCase()));
-addEventListener('keyup', (e) => keys.delete(e.key.toLowerCase()));
+// 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';
 
-const SPEED = 220; // px/s — tune the feel!
-let last = performance.now();
-function tick(now) {
-  const dt = Math.min((now - last) / 1000, 0.05); last = now;
-  const dx = (keys.has('d') || keys.has('arrowright')) - (keys.has('a') || keys.has('arrowleft'));
-  const dy = (keys.has('s') || keys.has('arrowdown')) - (keys.has('w') || keys.has('arrowup'));
-  if (dx || dy) {
-    const n = Math.hypot(dx, dy);
-    self.x += (dx / n) * SPEED * dt;
-    self.y += (dy / n) * SPEED * dt;
-    room.update({ x: self.x, y: self.y });
+// Resolve the engine pin AT CREATE TIME so the initial commit — the
+// milestone-1 revert baseline — already carries `looop.engine`. Without
+// this, first `looop dev` writes the pin AFTER the baseline: the fresh repo
+// starts dirty, and a milestone-1 reject (`git reset --hard`) deletes the
+// pin, so the next dev re-resolves "latest" and can silently change engine
+// versions under a revert. The version LIST endpoint is public (a version
+// number is not a secret); the engine BYTES stay login-gated at first dev.
+async function resolveEnginePin(apiBase, log) {
+  try {
+    const res = await fetch(`${apiBase}/api/creator/engine`);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const { latest } = await res.json();
+    if (!latest) throw new Error('no downloadable releases');
+    return latest;
+  } catch (err) {
+    log(`⚠️  Could not resolve the engine version (${err.message}) — the first \`looop dev\` will pin it instead.`);
+    return null;
   }
+}
 
-  ctx.fillStyle = '#0f1220';
-  ctx.fillRect(0, 0, canvas.width, canvas.height);
-  const cx = canvas.width / 2, cy = canvas.height / 2;
-  const drawAvatar = (p) => {
-    ctx.fillStyle = p.color ?? '#888';
-    ctx.fillRect(cx + (p.x ?? 0) - self.x - 14, cy + (p.y ?? 0) - self.y - 14, 28, 28);
-    ctx.fillStyle = '#e7e9f4';
-    ctx.font = '12px system-ui';
-    ctx.textAlign = 'center';
-    ctx.fillText(p.name ?? '?', cx + (p.x ?? 0) - self.x, cy + (p.y ?? 0) - self.y - 22);
-  };
-  for (const p of others.values()) drawAvatar(p);
-  drawAvatar(self);
-  requestAnimationFrame(tick);
+function copyTemplate(dir, name) {
+  const entries = readdirSync(TEMPLATE_DIR, { withFileTypes: true, recursive: true }).filter((e) => e.isFile());
+  for (const entry of entries) {
+    const rel = relative(TEMPLATE_DIR, join(entry.parentPath, entry.name));
+    const dest = join(dir, rel === 'gitignore' ? '.gitignore' : rel);
+    mkdirSync(dirname(dest), { recursive: true });
+    writeFileSync(dest, readFileSync(join(TEMPLATE_DIR, rel), 'utf8').replaceAll('{{name}}', name));
+  }
 }
-requestAnimationFrame(tick);
-`;
 
 export async function create({
   name,
   cwd = process.cwd(),
   install = true,
   cliSpec = process.env.LOOOP_CREATE_CLI_SPEC || '^0.1.0',
+  apiBase = getApiBase(DEFAULT_API_BASE),
   log = console.log,
 } = {}) {
   if (!name || !NAME_OK.test(name)) {
@@ -100,15 +94,22 @@ export async function create({
   if (existsSync(dir)) throw new Error(`${dir} already exists — pick another name or remove it first.`);
 
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, 'index.html'), html(name));
-  writeFileSync(join(dir, 'game.js'), gameJs());
-  // The agent surface for every vendor (AGENTS.md canonical, CLAUDE.md /
-  // GEMINI.md pointers, the looop skill) — see agent-files.mjs.
-  writeAgentFiles(dir, name);
-  writeFileSync(join(dir, '.gitignore'), 'node_modules/\n.looop/\n');
+  copyTemplate(dir, name);
+  // Non-Claude agent CLIs (Codex, Gemini/Antigravity, Cursor, opencode)
+  // discover project skills at .agents/skills/ — alias it to the same files.
+  // Created here, not shipped in the template: npm pack can't carry symlinks.
+  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.
+  }
   // The engine is deliberately NOT a dependency (Q4 revision): it installs
-  // from the platform's login-gated registry on first `looop dev`, which then
-  // writes the `looop.engine` version pin here.
+  // from the platform's login-gated registry on first `looop dev`. The
+  // VERSION is pinned here at create time (public lookup, warn-fallback) so
+  // the initial commit already carries it — see resolveEnginePin above.
+  const enginePin = await resolveEnginePin(apiBase, log);
   writeFileSync(
     join(dir, 'package.json'),
     JSON.stringify(
@@ -116,8 +117,10 @@ export async function create({
         name,
         private: true,
         description: `A Looop game. Play at https://play.looop.games/g/${name}`,
-        scripts: { dev: 'looop dev', publish: 'looop publish' },
-        devDependencies: { '@looop-games/cli': cliSpec },
+        scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test' },
+        devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC },
+        allowScripts: ALLOW_SCRIPTS,
+        ...(enginePin ? { looop: { engine: enginePin } } : {}),
       },
       null,
       2,
@@ -126,10 +129,40 @@ export async function create({
 
   if (install) {
     log(`Installing the CLI (npm install in ${name}/)…`);
-    execFileSync('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
+    runNpm(['install', '--no-audit', '--no-fund'], { cwd: dir, stdio: 'pipe' });
+    // Fetch the smoke-test browser NOW (cached machine-wide per version) so
+    // the first `looop 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 (caught live, 2026-07-10).
+    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?) — `looop test` will fetch it when first needed.');
+    }
   }
   try {
     execFileSync('git', ['init', '-q'], { cwd: dir, stdio: 'pipe' });
+    // Commit the scaffold: 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.
+    execFileSync('git', ['add', '-A'], { cwd: dir, stdio: 'pipe' });
+    const msg = ['commit', '-q', '-m', 'initial scaffold (looop 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=Looop', '-c', 'user.email=create@looop.games', ...msg], {
+        cwd: dir,
+        stdio: 'pipe',
+      });
+    }
   } catch {
     // git not installed — fine, the folder still works.
   }