@looop-games/cli 0.1.27 → 0.1.28

package/CHANGELOG.md

@@ -14,6 +14,17 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.28] - 2026-08-18
+
+### Added
+- `looop update --rc <version>` takes a specific **release candidate** — a
+  pre-release engine (e.g. `0.2.0-rc.1`) you've been handed to test before it
+  becomes an official release. It installs that exact version and re-pins your
+  game to it. Candidates are unlisted: a plain `looop update` never picks one
+  up, and they don't appear in `looop changelog`. A candidate can be re-cut
+  under the same name while it's iterated on, so `--rc` always re-downloads it
+  rather than trusting a cached copy.
+
 ## [0.1.27] - 2026-08-09
 
 ### Added

package/bin/looop.mjs

@@ -33,7 +33,7 @@ Usage:
   looop test                 Run the game's tests (*.test.mjs) and smokes (*.smoke.mjs)
   looop lint [--fix]         Check the game against the Looop rules (runs inside 'looop test')
   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 update [--rc <v>]    Move this game to the latest engine release (--rc <v> takes a specific pre-release)
   looop model bake <glb>     Re-bake a 3D model's server-side hit data now (normally automatic)
   looop publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
   looop feedback             Send reports + replies under notes/feedback/; pull outcomes back in
@@ -104,9 +104,15 @@ try {
         all: rest.includes('--all'),
       });
       break;
-    case 'update':
-      await update();
+    case 'update': {
+      // `--rc <version>` takes an exact release candidate by reference (a
+      // pre-release you were handed); no flag → the normal newest-stable update.
+      const rcIdx = rest.indexOf('--rc');
+      const target = rcIdx >= 0 ? rest[rcIdx + 1] : null;
+      if (rcIdx >= 0 && !target) throw new Error('`--rc` needs a version, e.g. `looop update --rc 0.2.0-rc.1`');
+      await update({ target });
       break;
+    }
     case 'model': {
       // `model` is the accessor for 3D-model tooling; `bake` is its first verb.
       // Baking is normally automatic (dev/test/publish re-bake changed models);

package/lib/changelog.mjs

@@ -24,13 +24,32 @@ 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.
+//
+// Release candidates carry a pre-release suffix (`0.2.0-rc.1`); a game pinned to
+// one still asks this to compare versions (e.g. `looop changelog` filters by the
+// pin). Standard semver precedence: a pre-release ranks just BELOW its release
+// (`0.2.0-rc.1` < `0.2.0`), and two pre-releases of the same core order by their
+// suffix. Without this the raw `split('.').map(Number)` produced NaN and silently
+// mis-ranked every suffixed version.
 export function compareVersions(a, b) {
-  const pa = a.split('.').map(Number);
-  const pb = b.split('.').map(Number);
+  const parse = (v) => {
+    const s = String(v);
+    const dash = s.indexOf('-');
+    const core = dash < 0 ? s : s.slice(0, dash);
+    const pre = dash < 0 ? '' : s.slice(dash + 1);
+    return { nums: core.split('.').map(Number), pre };
+  };
+  const A = parse(a);
+  const B = parse(b);
   for (let i = 0; i < 3; i++) {
-    if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) > (pb[i] ?? 0) ? 1 : -1;
+    if ((A.nums[i] ?? 0) !== (B.nums[i] ?? 0)) return (A.nums[i] ?? 0) > (B.nums[i] ?? 0) ? 1 : -1;
   }
-  return 0;
+  // Same numeric core: a release outranks its pre-releases; two pre-releases
+  // order lexically by suffix (a stable, total order — the label is opaque).
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;
+  if (!B.pre) return -1;
+  return A.pre < B.pre ? -1 : 1;
 }
 
 export function selectReleases(releases, { pinned, version, all } = {}) {

package/lib/engine.mjs

@@ -122,7 +122,11 @@ export async function ensureEngine(
 
   const cache = cacheDir();
   const cached = join(cache, `engine-${pin}.tgz`);
-  if (!existsSync(cached)) {
+  // A release candidate (a `-suffix` pin) is MUTABLE — the same label can be
+  // re-cut with new bytes — so its cache entry can be stale. Always re-download
+  // a candidate; the content-addressed stable releases are safe to cache forever.
+  const isCandidate = pin.includes('-');
+  if (!existsSync(cached) || isCandidate) {
     log(`Downloading engine ${pin} from ${apiBase}…`);
     const dlUrl = `${apiBase}/api/creator/engine/${pin}`;
     let res = await fetchImpl(dlUrl, { headers: auth });

package/lib/update.mjs

@@ -80,6 +80,8 @@ export async function update({
   ensure = ensureEngine,
   reconcile = reconcileAgentSurface,
   syncCliFn = syncCli,
+  // `looop update --rc <version>` — take an EXACT release candidate by reference.
+  target = null,
 } = {}) {
   const project = findProject(cwd);
   const from = readEnginePin(project.dir);
@@ -91,6 +93,64 @@ export async function update({
     if (!getToken()) throw new Error('login did not produce a token — run `looop login` and retry.');
   }
 
+  // ── Release-candidate lane ────────────────────────────────────────────────
+  // A candidate (`--rc 0.2.0-rc.1`) is UNLISTED: it never appears in `latest` or
+  // `looop changelog`, so this lane bypasses the newest-stable comparison and
+  // installs the named version directly. Its changelog and any migration notes
+  // ship INSIDE the engine tarball (the docs the agent reads), not through the
+  // version-crossing callout the stable lane prints. syncCli runs FIRST for the
+  // same reason it does below — its npm install would prune the engine if it ran
+  // after the engine landed.
+  if (target) {
+    // Validate the version shape BEFORE anything mutates the repo. syncCli's npm
+    // install below prunes the engine, so a typo caught only after that point
+    // would leave the game engine-less on a bad pin. This mirrors the platform's
+    // ENGINE_VERSION_WITH_PRERELEASE_OK; a well-formed but unknown/removed
+    // candidate is still caught below by restoring the pin on a failed download.
+    if (!/^\d+\.\d+\.\d+(-[0-9A-Za-z][0-9A-Za-z.-]*)?$/.test(target)) {
+      throw new Error(`\`--rc\` needs a valid engine version like 0.2.0-rc.1 — got "${target}".`);
+    }
+    let cli;
+    try {
+      cli = await syncCliFn({ projectDir: project.dir, log });
+    } catch (err) {
+      cli = { updated: false, error: err };
+    }
+    writeEnginePin(project.dir, target);
+    let engine;
+    try {
+      engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+    } catch (err) {
+      // The candidate didn't download (a typo that still parsed, or one that was
+      // since removed). Restore the previous pin so the game isn't left pointing
+      // at a version that doesn't exist — the engine may have been pruned by the
+      // CLI install above, but is recoverable by a normal `looop dev`/`update` on
+      // the restored pin. A game with no prior pin keeps none.
+      if (from) writeEnginePin(project.dir, from);
+      throw err;
+    }
+    const engineDir = engine.dir ?? null;
+    log('');
+    log(`✅ Engine candidate installed: ${from ?? '(none)'} → ${engine.version}`);
+
+    const surface = engineDir ? reconcile(project.dir, engineDir, { log }) : { skipped: true };
+    if (!surface.skipped) report(log, surface.engineVersion ?? target, surface);
+
+    if (cli?.error) {
+      log('');
+      log(`   The looop command could not be updated (${cli.error.message}).`);
+      log('   Retry with: npm update @looop-games/cli');
+    } else {
+      reportCli(log, cli);
+    }
+
+    log('');
+    log('   This is a pre-release candidate — its changelog and any migration');
+    log('   notes ship inside the engine (read the handbook / engine docs), not');
+    log('   via `looop changelog`. Republish (`npx looop publish`) when ready.');
+    return { from, to: engine.version, updated: from !== engine.version, surface, crossed: null, cli, candidate: true };
+  }
+
   const res = await fetchImpl(`${apiBase}/api/creator/engine`, {
     headers: { Authorization: `Bearer ${getToken()}` },
   });
@@ -143,27 +203,41 @@ export async function update({
   let engineDir = null;
   let updated = false;
 
-  if (from === latest) {
-    // Reconcile anyway. A repo can sit on the latest engine and STILL have an
-    // out-of-date surface: one scaffolded before this mechanism existed has
-    // never had its skills adopted, and would otherwise wait forever for a
-    // release it already has.
+  // Forward-only: `looop update` moves a game to `latest` only when `latest` is
+  // actually NEWER than the pin. It never moves a game that is already on latest
+  // OR ahead of it — the latter is real now that release candidates exist: a
+  // testbed pinned to `0.2.0-rc.3` while the newest stable is `0.1.10` must not
+  // be silently DOWNGRADED to 0.1.10 (which would break every 0.2.0 API it uses)
+  // just because the plain `update` was run out of habit. `--rc` is the lane that
+  // moves onto a candidate; the stable lane only ever moves forward.
+  const cmp = from ? compareVersions(from, latest) : -1;
+  if (cmp >= 0) {
+    // On latest, or ahead of it on a pre-release. Reconcile the surface anyway —
+    // a repo can sit on the right engine with a STILL out-of-date surface (one
+    // scaffolded before this mechanism existed never had its skills adopted) —
+    // but never rewrite the pin.
+    const label = from ?? latest;
+    const ahead = cmp > 0;
     try {
       engineDir = resolveEngine(project.dir).dir;
-      log(`✅ Engine ${latest} — already up to date.`);
+      log(
+        ahead
+          ? `✅ Engine ${label} — a pre-release ahead of the latest release (${latest}); not downgrading.`
+          : `✅ Engine ${label} — already up to date.`,
+      );
     } catch {
-      // Pinned to the latest, but NOT on disk. The pin is a claim about what this
-      // game runs; node_modules is the truth, and they disagree — because a plain
-      // `npm install` (the creator's own, or ours above) prunes the engine, which
-      // npm never recorded. "Already up to date" while the engine is missing is a
-      // lie that leaves every engine-reading command broken, and re-running update
-      // could never fix it. Put it back — from the local cache, so this is fast and
-      // works offline.
-      log(`Engine ${latest} is pinned but missing from node_modules — reinstalling it.`);
+      // Pinned to this version, but NOT on disk. The pin is a claim about what
+      // this game runs; node_modules is the truth, and they disagree — because a
+      // plain `npm install` (the creator's own, or ours above) prunes the engine,
+      // which npm never recorded. "Already up to date" while the engine is missing
+      // is a lie that leaves every engine-reading command broken, and re-running
+      // update could never fix it. Put it back — from the local cache, so this is
+      // fast and works offline.
+      log(`Engine ${label} is pinned but missing from node_modules — reinstalling it.`);
       const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
       engineDir = engine.dir ?? null;
       log('');
-      log(`✅ Engine ${latest} — restored.`);
+      log(`✅ Engine ${label} — restored.`);
     }
   } else {
     // Rewrite the pin first; ensureEngine honors it (download → install → pin).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",