@looop-games/cli 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog — @looop-games/cli
+
+The `looop` command itself. This is the one piece of Looop you install from npm;
+everything else (the component library, the room primitives, your game's skills)
+lives in the engine and has [its own changelog](https://docs.looop.games), which
+you can read with `looop changelog`.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> Entries for 0.1.9 and earlier were reconstructed from the release history after
+> the fact, so they are short and may miss detail. Everything from 0.1.10 on is
+> written as the change is made.
+
+## [Unreleased]
+
+## [0.1.11] - 2026-07-12
+
+### Fixed
+- `looop update` now updates the **`looop` command itself**, not just the engine.
+  It used to leave the command at whatever version your game had pinned — so an
+  update could hand you an engine whose skills tell you to run a command your
+  `looop` was too old to have (`Unknown command: changelog`). It now moves both,
+  and says which versions it moved you between.
+
+  If you are seeing `Unknown command` today, you are on a `looop` from before
+  this fix and it cannot update itself. Run this once, and it will keep itself
+  current from then on:
+
+  ```bash
+  npm update @looop-games/cli
+  ```
+
+## [0.1.10] - 2026-07-12
+
+### Added
+- `looop changelog` — what changed in the engine. With no arguments it shows
+  every release newer than the version your game is pinned to; `looop changelog
+  <version>` shows one release, `--all` shows the whole history.
+- `looop update` now prints the changelog for every version it crosses, with
+  **BREAKING** entries called out separately, so you find out what has to change
+  in your game at the moment you take the update — not when something breaks.
+
+## [0.1.9] - 2026-07-12
+
+### Changed
+- `looop create` now signs you in and downloads the engine, which carries the
+  starter game and your game's skills. The login used to happen at your first
+  `looop dev`, one command later.
+- The published package is now just the command itself. Everything you receive as
+  a creator — the starter game, the skills, the shared libraries — comes from the
+  engine, so the two can no longer drift apart.
+
+## [0.1.8] - 2026-07-12
+
+### Added
+- `looop feedback` sends the files a report attaches, so whoever reads it can see
+  the code you are talking about.
+
+## [0.1.7] - 2026-07-11
+
+### Changed
+- `looop update` refreshes your game's skills and `AGENTS.md`, and reports every
+  file it touched. A file you edited yourself is kept, not overwritten.
+
+## [0.1.6] - 2026-07-11
+
+### Added
+- `looop update` — move a game onto the latest engine release and re-pin it.
+
+## [0.1.5] - 2026-07-11
+
+### Added
+- `looop feedback` — send the reports under `notes/feedback/` to the Looop team.
+
+## [0.1.4] - 2026-07-11
+
+### Fixed
+- `looop create` installs cleanly on macOS (`fsevents` is pre-approved along with
+  the other install scripts).
+
+## [0.1.3] - 2026-07-11
+
+### Fixed
+- `looop create` works on Windows.
+
+## [0.1.2] - 2026-07-10
+
+### Added
+- First public release. `looop create` scaffolds a game, `looop dev` runs it with
+  multiplayer, `looop publish` puts it on play.looop.games, `looop login`
+  authenticates the machine.

package/bin/looop.mjs

@@ -9,6 +9,7 @@ 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 { changelog } from '../lib/changelog.mjs';
 import { sendFeedback } from '../lib/feedback.mjs';
 import { clearToken } from '../lib/config.mjs';
 
@@ -25,6 +26,7 @@ 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 changelog [<v>]      What changed in the engine (default: everything newer than your pin)
   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
@@ -57,6 +59,12 @@ try {
       const { ok } = await testCmd();
       process.exit(ok ? 0 : 1);
     }
+    case 'changelog':
+      await changelog({
+        version: rest.find((a) => !a.startsWith('--')),
+        all: rest.includes('--all'),
+      });
+      break;
     case 'update':
       await update();
       break;

package/lib/changelog.mjs

@@ -0,0 +1,171 @@
+// `looop changelog` — what changed in the engine (project note azlqm2).
+//
+// The gap this closes: `looop update` used to say "Engine updated: 0.1.10 →
+// 0.1.12" and then list the SKILL FILES it rewrote. It said nothing about what
+// changed in the engine itself, so the agent crossed two versions of the shared
+// library blind — it could not know a call it makes is now wrong, or that the
+// thing it was about to hand-roll now exists.
+//
+// Two moments matter, and they are different:
+//   BEFORE an update — "what am I about to take?"   → the default, vs your pin
+//   AFTER  an update — "what do I have to change?"  → the BREAKING callout
+//
+// Reading is NOT login-gated. The version list is public by design (a version
+// number is not a secret — see builder/functions/api/creator/engine/index.ts);
+// only the DOWNLOAD carries a token. Requiring a login to read what an update
+// would do to you would be exactly backwards.
+import { findProject } from './project.mjs';
+import { readEnginePin } from './engine.mjs';
+import { getApiBase } from './config.mjs';
+import { DEFAULT_API_BASE } from './llm-shim.mjs';
+
+const RULE = '─'.repeat(64);
+
+// Semver by NUMBER. String order would put 0.1.9 after 0.1.10 and quietly show
+// the wrong set — the kind of bug nobody notices until a release is missing
+// from someone's update.
+export function compareVersions(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0) ? 1 : -1;
+  }
+  return 0;
+}
+
+export function selectReleases(releases, { pinned, version, all } = {}) {
+  const newestFirst = [...releases].sort((a, b) => compareVersions(b.version, a.version));
+
+  if (version) {
+    const one = newestFirst.find((r) => r.version === version);
+    if (!one) {
+      throw new Error(
+        `no engine release ${version}. Known: ${newestFirst.map((r) => r.version).join(', ')}`,
+      );
+    }
+    return [one];
+  }
+  if (all) return newestFirst;
+  // No pin means the game has never installed an engine (no `dev` yet). There is
+  // no "since" to work from, so show what it would get: the newest.
+  if (!pinned) return newestFirst.slice(0, 1);
+  return newestFirst.filter((r) => compareVersions(r.version, pinned) > 0);
+}
+
+// The actionable half. Everything else in a changelog is informative; a BREAKING
+// entry means code in THIS game has to change, so it gets hoisted out of the
+// prose and repeated on its own — with its migration line, which is the part the
+// reader actually needs.
+//
+// The marker is POSITIONAL: a breaking change is a bullet that STARTS with it.
+// Two false positives got here by loosening that, and both were found by reading
+// real output rather than by any test:
+//
+//   1. matching the bare word case-insensitively flagged the ordinary sentence
+//      "when your game turns out to be breaking a Looop rule";
+//   2. matching `**BREAKING**` anywhere on a line flagged a changelog entry that
+//      merely DESCRIBED the feature ("...calls out **BREAKING** entries
+//      separately...") — prose about breaking changes is not a breaking change.
+//
+// A callout that cries wolf is worse than no callout: it gets ignored, and the
+// next real one is ignored with it.
+// Bold form is case-insensitive (`**BREAKING**`, `**Breaking**` — the markup is
+// the deliberate part). The bare-word form must be ALL CAPS with punctuation, so
+// a bullet that merely opens with the ordinary word ("- breaking the sound
+// barrier: …") can't pass as a marker.
+const BREAKING_BOLD = /^\s*[-*]\s+\*\*breaking\*\*/i;
+const BREAKING_CAPS = /^\s*[-*]\s+BREAKING\b\s*[:—–-]/;
+const BREAKING_BULLET = { test: (l) => BREAKING_BOLD.test(l) || BREAKING_CAPS.test(l) };
+
+// True for a line that continues the bullet above it: indented, non-blank, and
+// not itself a new bullet or heading. That's how the migration line rides along.
+const CONTINUATION = /^\s+\S/;
+const NEW_BULLET_OR_HEADING = /^\s*(?:[-*]\s|#)/;
+
+export function breakingLines(notes) {
+  const lines = (notes ?? '').split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!BREAKING_BULLET.test(lines[i])) continue;
+    const block = [lines[i].trim()];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (!CONTINUATION.test(l) || NEW_BULLET_OR_HEADING.test(l)) break;
+      block.push(l.trim());
+      i = j;
+    }
+    out.push(block.join(' '));
+  }
+  return out;
+}
+
+export function renderReleases(selected, { pinned, latest } = {}) {
+  const out = [];
+  if (!selected.length) {
+    out.push(`Engine ${pinned ?? '(unpinned)'} — nothing new. This game is up to date with ${latest}.`);
+    return out.join('\n');
+  }
+
+  const head =
+    selected.length === 1
+      ? `Engine ${selected[0].version}`
+      : `${selected.length} engine releases newer than ${pinned}, newest first (latest is ${latest})`;
+  out.push(head, '');
+
+  for (const r of selected) {
+    out.push(RULE);
+    out.push(`## ${r.version}`);
+    out.push('');
+    out.push(r.notes?.trim() ? r.notes.trim() : '  (no notes recorded — this release predates the changelog)');
+    out.push('');
+  }
+
+  const breaking = selected.flatMap((r) => breakingLines(r.notes).map((l) => `   ${r.version}  ${l}`));
+  if (breaking.length) {
+    out.push(RULE);
+    out.push('');
+    out.push(
+      `⚠  ${breaking.length} BREAKING change${breaking.length === 1 ? '' : 's'} in this range.`,
+      '   These are the entries that mean code in THIS game has to change — check each one',
+      '   against the game before you call the update done.',
+      '',
+      ...breaking,
+      '',
+    );
+  }
+  return out.join('\n');
+}
+
+export async function fetchReleases({ apiBase, fetchImpl = fetch }) {
+  const res = await fetchImpl(`${apiBase}/api/creator/engine`);
+  if (!res.ok) throw new Error(`could not read the engine changelog (HTTP ${res.status})`);
+  const body = await res.json();
+  // An older platform has no `releases` key. Printing "nothing new" there would
+  // be a lie in the most dangerous direction — it reads as "safe to update".
+  //
+  // Do NOT tell them to upgrade the CLI: the missing half is the PLATFORM's, and
+  // a creator cannot deploy it. Advice they can't act on is worse than none.
+  if (!Array.isArray(body.releases)) {
+    throw new Error(
+      'this Looop platform is not serving the engine changelog yet. Nothing is wrong with your ' +
+        'game — try again later, and `npx looop update` still works in the meantime.',
+    );
+  }
+  return body;
+}
+
+export async function changelog({
+  cwd = process.cwd(),
+  apiBase = getApiBase(DEFAULT_API_BASE),
+  log = console.log,
+  fetchImpl = fetch,
+  readPin,
+  version,
+  all = false,
+} = {}) {
+  const pinned = readPin ? readPin() : readEnginePin(findProject(cwd).dir);
+  const { releases, latest } = await fetchReleases({ apiBase, fetchImpl });
+  const selected = selectReleases(releases, { pinned, version, all });
+  log(renderReleases(selected, { pinned, latest }));
+  return { pinned, latest, selected };
+}

package/lib/self-update.mjs

@@ -0,0 +1,120 @@
+// Keep the `looop` command itself up to date — the third lane.
+//
+// THE BUG THIS EXISTS FOR. A game's skills and its engine ride one artifact, so
+// they can't drift. The `looop` command does not: it's an npm devDependency
+// pinned in the game's own lockfile, and `npx looop` runs THAT copy, not npm's
+// latest. `looop update` used to move only the engine — so a real game (riven)
+// ended up on engine 0.1.14, whose skills tell the agent to run
+// `looop changelog`, while its CLI was still 0.1.6:
+//
+//     $ npx looop changelog
+//     Unknown command: changelog
+//
+// The agent surface is shipped BY the engine and can name any `looop` command it
+// likes. Nothing kept the CLI in step with it. So `looop update` must mean
+// "update Looop" — engine, skills, AND the command — or the next skill that
+// mentions a new command breaks the same way.
+//
+// FAIL SOFT, ALWAYS. The engine update is the important half and it has already
+// happened by the time we get here. A CLI bump that cannot be done (offline, npm
+// down, no write access) must warn and step aside — never take the command down
+// with it. Nothing in here throws.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runNpm } from './npm.mjs';
+
+export const CLI_PKG = '@looop-games/cli';
+
+// What `npx looop` will run NEXT TIME — the copy on disk in this game, which is
+// not necessarily the copy running right now (`npx @looop-games/cli@x update` in
+// a repo pinned to something older runs the newer one but must still fix the
+// repo).
+export function projectCliVersion(projectDir) {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(join(projectDir, 'node_modules', ...CLI_PKG.split('/'), 'package.json'), 'utf8'),
+    );
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+function isOlder(a, b) {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) < (pb[i] ?? 0);
+  }
+  return false;
+}
+
+export async function syncCli({ projectDir, npm = runNpm, log = console.log } = {}) {
+  const from = projectCliVersion(projectDir);
+
+  // Nothing installed: `create` and `dev` own that. There is nothing to bring up
+  // to date, and force-installing here would be a surprise.
+  if (!from) return { from: null, to: null, updated: false, skipped: 'not-installed' };
+
+  let latest;
+  try {
+    const out = npm(['view', CLI_PKG, 'version', '--json'], { cwd: projectDir });
+    latest = JSON.parse(out.stdout.toString());
+  } catch (err) {
+    log('');
+    log(`   Could not check for a newer looop command (npm did not answer). Your engine is`);
+    log(`   up to date; the command stayed at ${from}. Try again later, or run:`);
+    log(`      npm update ${CLI_PKG}`);
+    return { from, to: null, updated: false, error: err };
+  }
+
+  // Never downgrade. A local dev build (or a version newer than the registry
+  // knows about) is deliberate — leave it alone.
+  if (!isOlder(from, latest)) return { from, to: latest, updated: false };
+
+  try {
+    // --save-dev so the DECLARED range moves too. Without it the next plain
+    // `npm install` in that repo happily resolves back down to the old pin, and
+    // the update silently un-does itself.
+    npm(['install', '--save-dev', `${CLI_PKG}@${latest}`], { cwd: projectDir });
+  } catch (err) {
+    log('');
+    log(`   The looop command could not be updated to ${latest} (npm install failed).`);
+    log(`   Your engine is up to date; the command is still ${from}. Run this to retry:`);
+    log(`      npm install --save-dev ${CLI_PKG}@${latest}`);
+    return { from, to: latest, updated: false, error: err };
+  }
+
+  return { from, to: latest, updated: true };
+}
+
+// The version of the CLI EXECUTING right now — which is not always the one the
+// project has installed. `npx looop` runs the local install (so they match), but
+// `npx @looop-games/cli@latest update` runs a newer one against an older repo.
+export function runningCliVersion() {
+  try {
+    return JSON.parse(readFileSync(join(import.meta.dirname, '..', 'package.json'), 'utf8')).version ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// What `update` prints. Separate so the wording is testable.
+//
+// The caveat — "you're still running the old one" — is TRUE only when the process
+// executing is the copy we just replaced. An earlier version asserted it
+// unconditionally and told a `npx @looop-games/cli@latest update` run that it was
+// "still running 0.1.6", which it plainly was not. Caught by reading the output of
+// a real run against riven. Say it only when it's true.
+export function reportCli(log, cli, { running = runningCliVersion() } = {}) {
+  if (!cli?.updated) return;
+  log('');
+  log(`✅ The looop command updated: ${cli.from} → ${cli.to}`);
+  if (running === cli.from) {
+    log(`   You're still running ${cli.from} in this process — any new commands work from`);
+    log(`   your next \`npx looop\`.`);
+  } else {
+    log(`   New commands are available from your next \`npx looop\`.`);
+  }
+  log(`   Its own changes are in node_modules/${CLI_PKG}/CHANGELOG.md.`);
+}

package/lib/update.mjs

@@ -15,6 +15,8 @@ import { reconcileAgentSurface } from './agent-surface.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { login } from './login.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
+import { compareVersions, renderReleases } from './changelog.mjs';
+import { syncCli, reportCli } from './self-update.mjs';
 
 // The report is the point. A creator reading this must be able to answer, with
 // no further digging: what changed, was any of it mine, and what do I do now.
@@ -56,6 +58,7 @@ export async function update({
   loginFn = login,
   ensure = ensureEngine,
   reconcile = reconcileAgentSurface,
+  syncCliFn = syncCli,
 } = {}) {
   const project = findProject(cwd);
   const from = readEnginePin(project.dir);
@@ -72,9 +75,28 @@ export async function update({
   });
   if (res.status === 401) throw new Error('the platform rejected this machine’s token — run `looop login` again.');
   if (!res.ok) throw new Error(`could not list engine releases (HTTP ${res.status})`);
-  const { latest } = await res.json();
+  const { latest, releases } = await res.json();
   if (!latest) throw new Error('the platform has no downloadable engine releases yet.');
 
+  // What the update is about to change UNDER the game (project note azlqm2).
+  // Reporting the skill files we rewrote and nothing about the engine was the
+  // whole gap: an agent crossed two versions of the shared library blind.
+  //
+  // A platform too old to serve `releases` must NOT block the update — it just
+  // has to be honest that it cannot say what changed. (`looop changelog`, whose
+  // only job is to answer that question, refuses outright instead.)
+  // Newest first, to match `looop changelog` and — more importantly — to match
+  // what renderReleases' own header SAYS. The endpoint returns them ascending;
+  // passing that straight through printed 0.1.13 above 0.1.14 under a heading
+  // that read "newest first". Caught by reading a real production run.
+  const crossed = Array.isArray(releases)
+    ? releases
+        .filter(
+          (r) => compareVersions(r.version, latest) <= 0 && (!from || compareVersions(r.version, from) > 0),
+        )
+        .sort((a, b) => compareVersions(b.version, a.version))
+    : null;
+
   let engineDir = null;
   let updated = false;
 
@@ -102,9 +124,34 @@ export async function update({
   const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
   if (!surface.skipped) report(log, surface.engineVersion ?? latest, surface);
 
+  // The third lane: the `looop` command itself (see self-update.mjs). The skills
+  // we just reconciled ship WITH the engine and can name any command they like —
+  // riven ended up on an engine whose skills say `looop changelog` while its CLI
+  // was four versions too old to have it. So update moves this too.
+  //
+  // Wrapped: syncCli is already fail-soft, but a bug in it must not undo an
+  // engine update that has already landed on disk.
+  let cli;
+  try {
+    cli = await syncCliFn({ projectDir: project.dir, log });
+    reportCli(log, cli);
+  } catch (err) {
+    cli = { updated: false, error: err };
+    log('');
+    log(`   The looop command could not be updated (${err.message}).`);
+    log('   Your engine and skills are up to date. Retry with: npm update @looop-games/cli');
+  }
+
   if (updated) {
+    log('');
+    if (crossed === null) {
+      log('   This Looop platform could not tell us what changed in the engine — no changelog');
+      log('   is available for the versions you just crossed.');
+    } else if (crossed.length) {
+      log(renderReleases(crossed, { pinned: from, latest }));
+    }
     log('');
     log('   Republish (`npx looop publish`) when you want the live game on it.');
   }
-  return { from, to: latest, updated, surface };
+  return { from, to: latest, updated, surface, crossed, cli };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",
@@ -8,6 +8,7 @@
     "looop": "bin/looop.mjs"
   },
   "files": [
+    "CHANGELOG.md",
     "bin",
     "lib",
     "!lib/**/*.test.mjs"