@looop-games/cli 0.1.7 → 0.1.9

package/template/.claude/skills/todo/SKILL.md

@@ -1,54 +0,0 @@
----
-name: todo
-description: Capture a bug, idea, or improvement for later without acting on it now. Use when the creator (or you, mid-build) spots something worth remembering — "we should fix that jump later", "idea — a boss level", "note that down" — and when they want to see what's captured or start work on one.
----
-
-# /todo — capture now, decide later
-
-A **todo** is the one lightweight capture type in this repo: bug, idea,
-improvement — all the same thing until someone decides to act. Capturing must
-be nearly free; never derail the current work to file one.
-
-## Capture
-
-Write one small file per todo at `notes/todos/<YYYY-MM-DD-HHMM>-<short-slug>.md`
-(creation datetime first, always — the whole `notes/` tree names files this way
-so they list in order):
-
-```markdown
----
-status: open   # open | done | promoted | abandoned
-created: YYYY-MM-DD
----
-# <One-line summary>
-
-What was seen / imagined, in a couple of sentences. Enough that a future
-session understands it cold. Reference files by path if relevant.
-```
-
-Then get back to what you were doing. If the creator says something mid-build
-that is clearly a "later" item, offer to capture it in one line — don't stop
-the milestone.
-
-## Browse
-
-"What's on the list?" → read `notes/todos/`, summarize the open ones in a few
-lines each. Group bugs vs ideas by content, not by folder — there is
-deliberately only one folder.
-
-## Promote
-
-When the creator decides to actually DO a todo, it becomes a **plan**: start
-`/build`, which creates the plan in `notes/plans/` through its discussion
-phase, seeded from the todo's content. Mark the todo `status: promoted` with a
-line pointing at the plan file. Small fixes don't need promotion — just do
-them and mark the todo `done`.
-
-## Rules
-
-- Never delete a todo — mark it `done` (with a line saying what happened),
-  `promoted`, or — when the creator decides NOT to do it — `abandoned` **with
-  a one-line why**. The why is the value: it saves re-deciding the same thing
-  next month. "Won't do" and "did it" must never collapse into one status.
-- A todo about **Looop itself** (the engine, the CLI, the platform — not this
-  game) is `/feedback`'s job, not a todo.

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

@@ -1,74 +0,0 @@
----
-name: update-looop
-description: Update Looop itself — the engine, and the skills and instructions this repo runs on. Use when the creator asks for the latest Looop ("is there an update?", "update looop", "get the newest version"), when a Looop feature they've heard about is missing, or when something looks like a Looop bug that may already be fixed. Not for updating their GAME — that's just building.
----
-
-# /update-looop — get the latest Looop, and explain what changed
-
-`npx looop update` moves this game to the newest Looop release. It is the **only**
-command that writes to Looop's files inside this repo — `dev` and `publish` never
-do. That is deliberate: an update is something the creator *asks* for.
-
-But it does write into **their** repo. After it runs, `git status` shows changes
-they did not make. **Your job is to make sure that is never a surprise.**
-
-## Before
-
-Tell them what an update touches, in one or two sentences:
-
-- **The engine** — the game code they import from (`/shared/...`). Their game
-  keeps running on the old engine until they publish again, so an update is safe
-  to take at any time.
-- **The skills and instructions** — the files in `.claude/skills/` and the Looop
-  section of `AGENTS.md`. These are Looop's, living in their repo.
-- **Never their game.** Not `index.html`, not `game.js`, not `handbook/`, not
-  `notes/`. And never a skill they wrote, or an edit they made to one of ours —
-  where they've changed something, their version wins and the update says so.
-
-If they have uncommitted work, say so first — the update's changes will land
-alongside it, and a mixed diff is harder to read. Offer to save theirs first.
-
-## Run it
-
-```bash
-npx looop update
-```
-
-It prints exactly what it did: every file updated, every file removed, and every
-file it **kept because the creator had changed it**. Read that output — it is the
-source of truth for the next step, not your assumptions about what a release
-contains.
-
-## After — the part that matters
-
-**Report the change in their terms, not ours.** Don't paste the file list back at
-them; tell them what is now different about what you and they can do:
-
-> *"Looop updated to engine 0.1.8. The `/update-handbook` skill was replaced by a
-> broader `/handbook` — same job, plus it now keeps your game's vision and design
-> pillars. Your own `/my-thing` skill was left alone."*
-
-Then **offer the commit** — never run it unasked:
-
-> *"That changed 3 of Looop's files in your repo. Want me to save them?
-> (`git add -A && git commit -m "update Looop to engine 0.1.8"`)"*
-
-Two things to volunteer without being asked:
-
-- **If they'd edited a Looop file**, the update kept *their* version and did not
-  apply ours. Say which file, and that they may want to re-apply their change on
-  top of the new one — otherwise they'll silently miss the update to that file
-  forever.
-- **If the update mentions a backup folder** (`.looop/backup-<version>/`), that
-  is the pre-update copy of files whose history we couldn't be sure of. Tell them
-  it exists. They can delete it once they're happy.
-
-## Rules
-
-- **Never run `looop update` as a side effect of something else.** It is its own
-  act, with its own consent. If a bug looks like it might already be fixed
-  upstream, *propose* the update — don't just do it mid-build.
-- **Never commit on their behalf** without asking, even when the only changes are
-  Looop's own files. It is their repo and their history.
-- The live game at `play.looop.games` does **not** change until they run
-  `npx looop publish`. Say so — creators reasonably assume an update is live.

package/template/AGENTS.md

@@ -1,93 +0,0 @@
-# {{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 | `/update-looop`. It is the ONLY thing that writes Looop's files into this repo (`.claude/skills/`, the managed block of this file) — `dev` and `publish` never do, so an update is never a surprise in their git. 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 — and it is not the ceiling.** `/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). But read-only means *don't edit it*, **not** *don't exceed
-   it*: a Looop game is a web page, so **anything the browser can do, this game
-   can do.** The library is a bag of conveniences you draw from, not a fence
-   around what the game may be — what it doesn't have, you build, here in the
-   game folder. **Never tell the creator that Looop "can't" do something**
-   (see `/engine` — it is almost always false, and it retires their idea
-   without their consent).
-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 `/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

@@ -1,4 +0,0 @@
-@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

@@ -1,4 +0,0 @@
-@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

@@ -1,21 +0,0 @@
-// 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

@@ -1,53 +0,0 @@
-// 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

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

package/template/handbook/design.md

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

package/template/handbook/feel.md

@@ -1,8 +0,0 @@
-# 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. `/handbook` adds entries.
-
-_Nothing locked yet._

package/template/handbook/qa.md

@@ -1,9 +0,0 @@
-# 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; `/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

@@ -1,26 +0,0 @@
-<!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>