@looop-games/cli 0.1.2 → 0.1.4

package/template/.claude/skills/update-handbook/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: update-handbook
+description: Record something durable this game just taught us — convert a playtest catch into an automated check, lock in a blessed feel value, or write down a design pillar. Use right after a creator playtest catches a defect the automated checks missed, when a feel value gets approved ("that jump is perfect — keep it"), or when a design principle emerges.
+---
+
+# /update-handbook — keep what the game taught us
+
+`handbook/` is this game's durable truth — the layer that AUGMENTS the
+engine's read-only practices with what THIS game has learned. This skill is
+how it grows.
+
+**Every handbook write needs the creator's approval first.** The handbook is
+*their* game's truth — propose the exact entry ("I'd like to record: …"),
+and write it only after they say yes. Never slip an entry in as a side effect
+of other work. (Smoke/test FILES don't need this gate — they're regression
+tests, not blessed truth; only `handbook/` writes do.)
+
+Three kinds of lesson, three destinations:
+
+## 1. A playtest caught a defect → an automated check
+
+The premise (from the engine's `shared/practices/qa.md`): **a human catching a
+defect means an automated check was missing.** Convert the *class* of defect,
+not the instance:
+
+1. Name the miss precisely — not "the door was broken" but "doors can lose
+   their collision when the room resets, and nothing checks collision after a
+   reset."
+2. Prefer an **executable check**: write a `<aspect>.smoke.mjs` (or
+   `*.test.mjs`) that reproduces the defect — confirm it fails RED on the
+   broken state, then goes green on the fix. `npx looop test` discovers it
+   forever after; a guard you never saw fail is a guard you can't trust.
+3. **If the check needs to SEE the game's internals** (collision boxes, depth
+   order, hit areas) and the game has no debug overlay yet, **build one as
+   part of the conversion** — a keyboard-toggled draw of the real boxes/order.
+   It's a small one-time cost, and every later screenshot-verify reuses it
+   (master list row R2).
+4. Only if it truly can't be executed (needs human perception), add it as a
+   procedural step in **`handbook/qa.md`** — `/qa` runs those by hand each
+   time.
+
+## 2. A feel value got blessed → `handbook/feel.md`
+
+When the creator locks a feel call ("that speed is exactly right"), record the
+value, where it lives, and WHY it's right — so no future session "improves" it
+away. If it's worth defending, pin it with a smoke too.
+
+## 3. A design principle emerged → `handbook/design.md`
+
+When a decision reveals what this game IS ("never text tutorials — the world
+teaches", "death must always be the player's fault"), write the pillar down.
+Future builds check new ideas against these.
+
+## The upstream half
+
+Before writing, ask: **is this lesson specific to this game, or would every
+Looop game want it?** A generic hole (an engine component that breaks a
+universal expectation, a check every game should run) belongs in the engine's
+master list, not just this repo — offer `/feedback` so it lands upstream for
+everyone. Do both when in doubt: the handbook entry protects this game now;
+the feedback fixes it everywhere later.
+
+## Rules
+
+- One lesson per invocation, converted fully — an entry someone can act on
+  cold, not a vague reminder.
+- Handbook entries are durable truth: date them, keep them short, and when a
+  later decision supersedes one, update it in place rather than stacking
+  contradictions.

package/template/AGENTS.md

@@ -0,0 +1,86 @@
+# {{name}} — a Looop game
+
+<!-- looop:managed:start -->
+<!-- Everything between the looop:managed markers belongs to the Looop
+     platform and is REWRITTEN when the engine updates. Add your own
+     instructions BELOW the end marker — updates never touch them. -->
+
+This folder is a standalone Looop game. You (the agent) build it for a person
+who is probably **not a developer** — the "creator". They describe the game in
+plain language and make the judgment calls; you own everything else: process,
+code, and verification. They should never need to learn git, npm, or servers.
+
+## Where things go
+
+The workflows live as **skills** in `.claude/skills/` (aliased at
+`.agents/skills/` — same files); each skill's `description` says when it
+applies. This table routes only what has no skill:
+
+| The creator wants… | Do this |
+|---|---|
+| To "save my work" | `git add -A && git commit` (and push, if the repo has a remote). Saving is local; it is **not** publishing. |
+| To update Looop / the engine | `npx looop update` — moves the game to the latest engine release and re-pins `looop.engine` in `package.json`. The live game changes only on the next publish. |
+| Better game feel (tuning speeds, jumps, timings) | The engine's **tweaks** library (`node_modules/@looop-games/engine/shared/ui/tweaks/`) + `shared/practices/feel.md`. |
+| To change how an engine file behaves | Copy it to `overrides/shared/<same path>` and edit the copy — dev and publish serve your override instead of the official module. Imports stay `/shared/...`; never rewrite them. An override is a fork: that file stops receiving engine updates until you re-port it. |
+
+## Commands (run from this folder)
+
+- `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}}.
+  **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)
+
+1. **Multiplayer-first.** Any state other players can see (positions, physics,
+   scores, world objects) rides the room's authority — `room.update(...)`,
+   `room.send('input', ...)` — never local mutation only one client sees.
+   Verify multiplayer behaviour with TWO browser contexts, not one.
+2. **The engine is read-only.** `/shared/...` imports come from the installed
+   engine at `node_modules/@looop-games/engine` (not an npm dependency —
+   `looop dev` downloads the version pinned in `package.json`'s `looop.engine`
+   and reinstalls it if an `npm install` prunes it). Never edit files in
+   `node_modules` — use `overrides/shared/` (see the table above).
+3. **Never hand-roll a server.** Only `looop dev` (or `looop test`) serves
+   this game: they alias `/shared/...` and inject the platform layer. A plain
+   static server 404s every engine import and the game silently never boots.
+4. **Never handle tokens or keys.** Login is a browser device flow; platform
+   services (LLM etc.) are already wired through the local shim. If something
+   seems to need an API key, you're on the wrong path.
+5. **Read what's already known before writing game code.** First this game's
+   own **`handbook/`** (its locked truths — qa.md, feel.md, design.md), then
+   the engine craft docs at
+   `node_modules/@looop-games/engine/shared/practices/` — `feel.md`,
+   `architecture.md`, `multiplayer.md`, `qa.md` (and `eval.md` when anything
+   is LLM-generated), which apply to every game.
+   The handbook augments the generic docs; where they touch the same topic,
+   the handbook is this game's answer.
+6. **Anything with an assertion is a regression test.** Playwright checks live
+   in `<aspect>.smoke.mjs` files (excluded from publish, discovered by
+   `looop test`). Keep them; delete only assertion-free scratch.
+
+## This repo's own knowledge
+
+- **`handbook/`** — durable truth about THIS game: `qa.md` (its checks),
+  `feel.md` (locked feel values), `design.md` (its pillars). Consult it before
+  working; grow it with `/update-handbook`.
+- **`notes/`** — work tracking: `notes/plans/` (what's being built — `/build`
+  runs from these), `notes/todos/` (captured bugs/ideas), and
+  `notes/feedback/` (reports for the Looop team, written by `/feedback`).
+  Nothing under `notes/` is ever published.
+
+<!-- looop:managed:end -->
+
+<!-- Your own instructions go below this line. -->

package/template/CLAUDE.md

@@ -0,0 +1,4 @@
+@AGENTS.md
+
+(If your tool didn't inline the line above: read AGENTS.md — it is this
+project's agent instructions.)

package/template/GEMINI.md

@@ -0,0 +1,4 @@
+@AGENTS.md
+
+(If your tool didn't inline the line above: read AGENTS.md — it is this
+project's agent instructions.)

package/template/boot.smoke.mjs

@@ -0,0 +1,21 @@
+// Boot smoke — the game's first regression test, shipped with the scaffold.
+// Proves the dev stack serves the game page AND the engine alias (a plain
+// static server would 404 every /shared/... import and the game would
+// silently never boot). Runs under `npx looop test`, which boots a real dev
+// stack and exports its URL. Grow your own checks as `<aspect>.smoke.mjs`
+// files next to this one.
+const url = process.env.LOOOP_TEST_GAME_URL || process.env.URL;
+if (!url) {
+  console.error('boot smoke: no game URL — run this via `npx looop test`.');
+  process.exit(1);
+}
+
+const page = await fetch(url);
+if (!page.ok) throw new Error(`game page: ${page.status} for ${url}`);
+if (!(await page.text()).includes('<canvas')) throw new Error('game page served, but no canvas in it');
+
+const engineModule = new URL('/shared/ui/room/client.js', url);
+const engine = await fetch(engineModule);
+if (!engine.ok) throw new Error(`engine alias broken: ${engineModule.pathname} → ${engine.status}`);
+
+console.log('boot smoke: game page + engine alias OK');

package/template/game.js

@@ -0,0 +1,53 @@
+// 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';
+
+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 });
+
+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;
+
+const keys = new Set();
+addEventListener('keydown', (e) => keys.add(e.key.toLowerCase()));
+addEventListener('keyup', (e) => keys.delete(e.key.toLowerCase()));
+
+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 });
+  }
+
+  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);
+}
+requestAnimationFrame(tick);

package/template/gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.looop/

package/template/handbook/design.md

@@ -0,0 +1,7 @@
+# Design — the pillars
+
+What this game IS: the principles new ideas get checked against. Written as
+they emerge from real decisions (via `/update-handbook`), not invented up
+front — an empty file is honest; a speculative pillar is a trap.
+
+_No pillars yet._

package/template/handbook/feel.md

@@ -0,0 +1,8 @@
+# Feel — locked values
+
+Feel calls the creator has blessed: the value, where it lives, and why it's
+right — so no future session "improves" them away. General feel craft lives in
+the engine's `shared/practices/feel.md`; this file is only what THIS game has
+locked. `/update-handbook` adds entries.
+
+_Nothing locked yet._

package/template/handbook/qa.md

@@ -0,0 +1,9 @@
+# QA — this game's own checks
+
+Checks THIS game has earned, on top of the engine's master list
+(`node_modules/@looop-games/engine/shared/practices/qa.md`) and the executable
+tests `npx looop test` discovers. `/qa` runs all three sources; `/update-handbook`
+adds entries here when a playtest catches something no automated check saw —
+but prefer writing a `*.smoke.mjs` when the check can be executed.
+
+_No game-specific checks yet. The first playtest catch starts this list._

package/template/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <!-- Mobile baseline (engine practices, architecture.md): locked viewport,
+       no double-tap/pinch zoom, no text selection on game UI. Required on
+       every Looop game — keep all four pieces when reshaping this file. -->
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover">
+  <title>{{name}}</title>
+  <style>
+    html, body { margin: 0; height: 100%; background: #0f1220; overflow: hidden; touch-action: manipulation; }
+    * { -webkit-user-select: none; user-select: none; -webkit-touch-callout: none; -webkit-tap-highlight-color: transparent; }
+    input, textarea, [contenteditable] { -webkit-user-select: text; user-select: text; }
+    canvas { display: block; width: 100vw; height: 100vh; }
+  </style>
+  <script>
+    // Safari ignores user-scalable=no — block iOS gesture-zoom too.
+    for (const ev of ['gesturestart', 'gesturechange', 'gestureend'])
+      document.addEventListener(ev, (e) => e.preventDefault());
+  </script>
+</head>
+<body>
+  <canvas id="game"></canvas>
+  <script type="module" src="game.js"></script>
+</body>
+</html>

package/lib/agent-files.mjs

@@ -1,151 +0,0 @@
-// The agent-facing surface `looop create` writes into every game folder
-// (cuqfzo Q4 addendum: no plugin — per-project files are what every agent CLI
-// actually reads).
-//
-// Layout: AGENTS.md is CANONICAL (the emerging cross-vendor standard, read by
-// Codex and friends). CLAUDE.md and GEMINI.md are thin pointers that @import
-// it, with a plain-text fallback for tools without import support. The looop
-// skill lands at .claude/skills/looop/SKILL.md (Claude Code loads project
-// skills from there). Because these ship inside @looop-games/cli, the
-// instructions always match the CLI/engine version that scaffolded the game —
-// the skills-vs-CLI drift a marketplace plugin would reintroduce.
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-
-export const agentsMd = (name) => `# ${name} — a Looop game
-
-This folder is a standalone Looop game. You (the agent) build it for a person
-who is not a developer — they describe the game in plain language, you make it
-real. The game is multiplayer-first: every behaviour must work with other
-players in the room (shared state rides the room's authority, never local
-mutation).
-
-## Commands (run from this folder)
-
-- \`npx looop dev\` — full local stack: the game at
-  http://localhost:8000/games/${name}/index.html, multiplayer on :1999, and
-  platform services (LLM etc.) on :8788. Leave it running; edits hot-reload.
-- \`npx looop login\` — connect this machine to the person's Looop account
-  (needed once per machine; the first \`looop dev\` runs it automatically —
-  the engine downloads from the platform and every download needs the account).
-- \`npx looop publish\` — ship to https://play.looop.games/g/${name}.
-  \`--slug <alt>\` publishes an A/B copy without touching the live game.
-
-## The engine
-
-\`/shared/...\` imports come from the installed engine at
-\`node_modules/@looop-games/engine\` (not an npm dependency — \`looop dev\`
-downloads the version pinned in package.json's \`looop.engine\` from the
-platform, and reinstalls it automatically if an \`npm install\` prunes it) —
-browse \`node_modules/@looop-games/engine/shared/ui/\` for the component library.
-**Read \`node_modules/@looop-games/engine/shared/practices/\` (feel.md,
-architecture.md, multiplayer.md, qa.md) before writing game code** — that's
-the studio's craft knowledge and it applies here.
-
-The engine is read-only. To modify an engine file for THIS game, copy it to
-\`overrides/shared/<same path>\` and edit the copy — dev and publish both
-serve your override instead of the official module (imports stay
-\`/shared/...\`; never rewrite them). The override is a fork: engine updates
-to that file stop arriving until you re-port it.
-
-## Verification
-
-Playwright-style checks belong in \`<aspect>.smoke.mjs\` files (excluded from
-publish). Anything with an assertion is a regression test — keep it.
-`;
-
-// CLAUDE.md / GEMINI.md: inline AGENTS.md via @import (both tools support
-// it); the second line is the graceful fallback where imports aren't a thing.
-const pointerMd = `@AGENTS.md
-
-(If your tool didn't inline the line above: read AGENTS.md — it is this
-project's agent instructions.)
-`;
-
-export const skillMd = () => `---
-name: looop
-description: Build, run, and publish a multiplayer game on Looop (play.looop.games). Use whenever the user wants to make a game, change their Looop game, preview it, log in, or publish it.
----
-
-# Looop — build multiplayer games for play.looop.games
-
-You are building a game for a person who is probably **not a developer**. They
-describe what they want in plain language; you make it real, run it, and show
-them. They should never need to learn git, npm, or servers — those are yours.
-
-Looop games are **multiplayer-first**: the full stack (game + room server +
-platform services) runs locally from minute one, and every behaviour must work
-with other players in the room. There is no "add multiplayer later."
-
-## The commands (run inside the game folder)
-
-\`\`\`bash
-npx @looop-games/cli create <name>   # new game folder — multiplayer works out of the box
-npx looop dev                  # local stack: game on :8000, rooms :1999, services :8788
-npx looop login                # device-flow login — browser opens, user clicks Approve
-npx looop publish              # live at https://play.looop.games/g/<name>
-npx looop publish --slug <alt> # A/B copy at /g/<alt> — never touches the live game
-npx looop whoami               # which account this machine publishes as
-\`\`\`
-
-- \`<name>\` becomes the URL: lowercase letters, digits, dashes.
-- \`looop dev\` hot-reloads on every edit; leave it running in a dedicated
-  terminal and give the user the URL to open.
-- \`login\` is needed once per machine — the first \`looop dev\` triggers it
-  automatically (the engine downloads from the platform, and every download
-  needs the user's account). Tell the user: "your browser will open — sign in
-  and click Approve." The code is shown in the terminal; never handle any
-  token yourself.
-
-## The engine (\`/shared/...\`)
-
-Game code imports the engine by absolute path, e.g.
-\`import { createRoom } from '/shared/ui/room/client.js'\`. Those files come
-from the installed engine at \`node_modules/@looop-games/engine\` — downloaded
-from the platform by \`looop dev\` (the version is pinned in package.json's
-\`looop.engine\`; it is deliberately not an npm dependency):
-
-- **Browse the library** at \`node_modules/@looop-games/engine/shared/ui/\` —
-  components for rooms, physics primitives, audio, joysticks, leaderboards,
-  LLM-driven NPCs, and more. Read a component's README before using it.
-- **Read the craft docs** at \`node_modules/@looop-games/engine/shared/practices/\`
-  (\`feel.md\`, \`architecture.md\`, \`multiplayer.md\`, \`qa.md\`) before writing
-  game code — they are the studio's accumulated knowledge and they apply to
-  every game.
-
-**The engine is read-only.** To change engine behaviour for this game, copy
-the file to \`overrides/shared/<same path>\` and edit the copy — both dev and
-publish serve your override instead of the official module. Keep the game's
-imports as \`/shared/...\`; never rewrite them. An override is a fork: that file
-stops receiving engine updates until you re-port it, so prefer game-local code
-when possible.
-
-## Multiplayer rules (non-negotiable)
-
-- Any state other players can see (positions, physics, scores, world objects)
-  rides the room's authority — \`room.update(...)\`, \`room.send('input', ...)\`,
-  world specs — never local mutation that only one client sees.
-- Verify multiplayer with two browser contexts (Playwright), not one.
-
-## Verification
-
-- Write Playwright checks as \`<aspect>.smoke.mjs\` in the game folder; they are
-  excluded from publish. Anything with an assertion is a regression test — keep it.
-- Before saying something works: run it. Boot the game, drive the behaviour,
-  screenshot visuals and look at them.
-
-## Services (LLM etc.)
-
-Platform services are already wired: in dev, calls to \`/api/llm\` ride the
-local shim on :8788 with the user's login; published games call same-origin.
-The user never needs an API key — if something asks for one, you're on the
-wrong path.
-`;
-
-export function writeAgentFiles(dir, name) {
-  writeFileSync(join(dir, 'AGENTS.md'), agentsMd(name));
-  writeFileSync(join(dir, 'CLAUDE.md'), pointerMd);
-  writeFileSync(join(dir, 'GEMINI.md'), pointerMd);
-  mkdirSync(join(dir, '.claude', 'skills', 'looop'), { recursive: true });
-  writeFileSync(join(dir, '.claude', 'skills', 'looop', 'SKILL.md'), skillMd());
-}