@looop-games/cli 0.1.3 → 0.1.5

package/bin/looop.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// looop — the Looop game-development CLI (project note cuqfzo).
+// looop — the Looop game-development CLI.
 //
 // Runs inside a standalone game folder (its own repo). The agent is the
 // primary user: keep output plain, actionable, and machine-legible.

package/lib/bundle-primitives.mjs

@@ -1,5 +1,5 @@
-// cuqfzo Phase 2 / Option B — Slice 2: bundle a server-backed game's primitives
-// on the CREATOR's machine, with the engine marked external.
+// 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

package/lib/create.mjs

@@ -1,4 +1,4 @@
-// `looop create <name>` — bootstrap a standalone Looop game (cuqfzo Slice 4).
+// `looop create <name>` — bootstrap a standalone Looop game.
 //
 // The create-next-app gesture: one command → a complete folder that is its
 // own repo, where `looop dev` immediately serves a WORKING multiplayer game
@@ -35,7 +35,11 @@ const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/;
 // 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.
-const ALLOW_SCRIPTS = { esbuild: true, workerd: true };
+// 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

package/lib/dev.mjs

@@ -1,5 +1,4 @@
-// `looop dev` — the standalone three-service dev stack (decision Q3 in
-// cuqfzo), same shape the monorepo's dev.sh proved:
+// `looop dev` — the standalone three-service dev stack:
 //
 //   static :8000  game folder at /games/<slug>/, /shared/ → engine bundle,
 //                 head injection + auto-reload
@@ -37,12 +36,11 @@ export function partykitBin() {
   }
 }
 
-// Per-game server parity (cuqfzo Phase 4): a game shipping its own
+// Per-game server parity: a game shipping its own
 // `partykit.json` runs its OWN server in dev — partykit gets the game folder
 // as cwd, resolving the game's `main` entry (which imports the room server
 // from the installed engine). Without one, the bundle's shared room server
-// runs, exactly as before. Mirrors the monorepo dev.sh detection so a
-// vendor-flipped game behaves identically standalone. A config whose `main`
+// runs, exactly as before. A config whose `main`
 // doesn't exist is ignored LOUDLY — a dead file must not take dev's
 // multiplayer down with it.
 export function partykitCwdFor(project, engine, warn = console.warn) {

package/lib/feedback.mjs

@@ -1,5 +1,5 @@
 // `looop feedback` — send the reports under notes/feedback/ to the Looop team
-// (cuqfzo; the transport behind the template's /feedback skill).
+// (the transport behind the template's /feedback skill).
 //
 // Target: /api/creator/feedback — the token-authenticated intake beside
 // creator/publish. Each unsent notes/feedback/*.md ships VERBATIM as the

package/lib/inject.mjs

@@ -1,5 +1,4 @@
-// HTML/JS dev-serving transforms — a Node port of the proven logic in
-// looop-core tools/game/dev_server.py, kept behaviour-identical:
+// HTML/JS dev-serving transforms:
 //
 //   * Head injection mirrors the production /g/<slug> serve path
 //     (builder/functions/g/[[path]].ts): window.GAME_SLUG + window.LOOOP_IDENTITY

package/lib/llm-shim.mjs

@@ -1,4 +1,4 @@
-// Local platform-services shim (:8788) — decision Q3b in cuqfzo.
+// Local platform-services shim (:8788).
 //
 // Thin auth/CORS plumbing between a game running on localhost and the
 // platform's services API (LLM today; whatever comes next). It forwards

package/lib/login.mjs

@@ -1,5 +1,4 @@
-// `looop login` — device-flow authentication (cuqfzo Slice 1, decisions
-// Q2/Q6, the `gh auth login` shape):
+// `looop 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),

package/lib/ports.mjs

@@ -1,4 +1,4 @@
-// Port conventions + takeover, mirroring looop-core tools/game/dev.sh.
+// Port conventions + takeover.
 //
 // Canonical ports: static :8000, partykit :1999, services shim :8788. The
 // engine's browser clients derive the other two from location.port

package/lib/publish.mjs

@@ -1,9 +1,9 @@
-// `looop publish` — ship the game to play.looop.games (cuqfzo Slice 2, Q1).
+// `looop publish` — ship the game to play.looop.games.
 //
 // Server-resolved: we send ONLY the game's own files plus the engine version
 // the installed bundle declares; the platform resolves /shared/... from its
-// release registry. Compare catalog_publish.py, which staged the whole shared
-// library client-side — that trust hole is what this replaces.
+// release registry. The client never stages the shared library itself — that
+// trust hole is what this design replaces.
 //
 // Target: /api/creator/publish — the token-authenticated creator lane, the
 // one publish route reachable on the public play host (the legacy
@@ -21,9 +21,8 @@ import { bundlePrimitives, PRIMITIVES_ENTRY } from './bundle-primitives.mjs';
 export const PLAY_BASE = 'https://play.looop.games';
 
 // Never shipped: tooling, VCS, agent workspace, notes + handbook + agent
-// instructions (repo knowledge travels with the repo, not the catalog — same
-// rule as the monorepo publisher; a published game must not expose it on a
-// public URL), tests/smokes.
+// instructions (repo knowledge travels with the repo, not the catalog — a
+// published game must not expose it on a public URL), tests/smokes.
 const SKIP_DIRS = new Set(['node_modules', 'notes', 'handbook', '.git', '.looop', '.claude', '__pycache__']);
 const SKIP_FILES = [
   /^package(-lock)?\.json$/,
@@ -69,7 +68,7 @@ export async function publish({
     throw new Error('this game has no index.html at its root — publish needs an entry page.');
   }
 
-  // Server-backed game (cuqfzo Phase 2 / Option B, Slice 2): its primitives can
+  // Server-backed game: its primitives can
   // import npm packages + WASM the platform's bundler-less endpoint can't
   // resolve, so we bundle them HERE (engine marked external) and send the
   // single self-contained module in place of the raw barrel. The endpoint

package/lib/static-server.mjs

@@ -1,6 +1,5 @@
-// The standalone dev static server — Node port of looop-core
-// tools/game/dev_server.py, serving a single game + the installed engine
-// bundle behind the same URL shape production uses:
+// The standalone dev static server — serves a single game + the installed
+// engine bundle behind the same URL shape production uses:
 //
 //   /games/<slug>/…   → the game folder
 //   /shared/…         → the engine bundle's shared/ tree

package/lib/test-cmd.mjs

@@ -1,5 +1,4 @@
-// `looop test` — run the game's own verification gate (cuqfzo creator-harness
-// Slice 1; the successor to the monorepo's `gamedev <name> test`).
+// `looop test` — run the game's own verification gate.
 //
 // Discovers the game's test files — `*.test.mjs` (unit, run under
 // `node --test`) and `*.smoke.mjs` (integration, run against a REAL dev
@@ -115,8 +114,8 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
           env: {
             ...env,
             LOOOP_TEST_GAME_URL: handle.url,
-            // The monorepo's smoke convention — exported too, so a game (and
-            // its smokes) moving out of looop-games ports without edits.
+            // A legacy alias for the same URL, exported so smokes written
+            // against the older convention keep running unedited.
             GAMEDEV_TEST_GAME_URL: handle.url,
             URL: handle.url,
           },

package/lib/update.mjs

@@ -1,5 +1,5 @@
-// `looop update` — move this game to the latest engine release (the CLI verb
-// the demoted /update skill became, cuqfzo Q6). Asks the platform registry
+// `looop update` — move this game to the latest engine release.
+// Asks the platform registry
 // for the latest downloadable release, rewrites the `looop.engine` pin, and
 // lets ensureEngine do what it already does on every dev/publish: download
 // (cached), install, re-pin. Slice 2 extends this with the skills/agent-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -10,7 +10,8 @@
   "files": [
     "bin",
     "lib",
-    "template"
+    "template",
+    "!lib/**/*.test.mjs"
   ],
   "engines": {
     "node": ">=20.11"

package/template/AGENTS.md

@@ -28,13 +28,19 @@ applies. This table routes only what has no skill:
 - `npx looop dev` — the full local stack: the game at
   http://localhost:8000/games/{{name}}/index.html, multiplayer on :1999,
   platform services (LLM etc.) on :8788. Leave it running; edits hot-reload.
+  **On a new machine the first `dev` signs the creator in: a browser window
+  opens, they log in and click Approve (~30 seconds, once per machine). Tell
+  them it's coming BEFORE you run it** — an unexplained browser popup mid-build
+  reads as something going wrong.
 - `npx looop test` — the per-change gate: runs every `*.test.mjs` (unit, under
   node) and every `*.smoke.mjs` (against a real dev stack it boots itself on
   free ports) in this folder.
 - `npx looop login` — connect this machine to the creator's Looop account
   (once per machine; the first `looop dev` runs it automatically).
 - `npx looop publish` — ship to https://play.looop.games/g/{{name}}.
-  `--slug <alt>` publishes an A/B copy without touching the live game.
+  **The first publish permanently claims the name `{{name}}` for the creator's
+  account** — from then on only they can update it. `--slug <alt>` publishes an
+  A/B copy without touching the live game.
 
 ## The rules that are physics (not preference)
 

package/lib/bundle-primitives.test.mjs

@@ -1,95 +0,0 @@
-// 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/config.test.mjs

@@ -1,37 +0,0 @@
-// CLI config lives in ~/.looop/config.json (LOOOP_HOME overrides for tests).
-// It stores the creator token minted by `looop login` — the secret never
-// passes through the human's hands (device flow, decision Q2/Q6 in cuqfzo).
-import { test } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync, readFileSync, statSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { readConfig, writeConfig, getToken, setToken, clearToken, configPath } from './config.mjs';
-
-const home = mkdtempSync(join(tmpdir(), 'looop-home-'));
-process.env.LOOOP_HOME = home;
-
-test('empty config reads as {}', () => {
-  assert.deepEqual(readConfig(), {});
-  assert.equal(getToken(), null);
-});
-
-test('setToken persists and getToken reads it back', () => {
-  setToken('looop_abc123', { apiBase: 'https://play.looop.games' });
-  assert.equal(getToken(), 'looop_abc123');
-  const onDisk = JSON.parse(readFileSync(configPath(), 'utf8'));
-  assert.equal(onDisk.token, 'looop_abc123');
-});
-
-test('token file is not world-readable', () => {
-  const mode = statSync(configPath()).mode & 0o777;
-  assert.equal(mode & 0o077, 0, `mode ${mode.toString(8)} leaks to group/other`);
-});
-
-test('clearToken removes the token but keeps other config', () => {
-  writeConfig({ ...readConfig(), custom: 'x' });
-  clearToken();
-  assert.equal(getToken(), null);
-  assert.equal(readConfig().custom, 'x');
-  rmSync(home, { recursive: true, force: true });
-});