@looop-games/cli 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -14,6 +14,41 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.16] - 2026-07-13
+
+### Added
+- `looop lane <name>` — open an isolated copy of your game to experiment in. It
+  lives in its own folder, on its own branch, with its own dev stack, so an
+  experiment can't disturb the game you're in the middle of. Whatever you have
+  unsaved stays exactly where it is. Like the winner? Merge it. Don't? Delete
+  the folder. The lane borrows the engine from your main folder rather than
+  downloading it again, so opening one is close to instant. Your agent knows
+  when to offer this — ask it for `/worktree`.
+
+### Fixed
+- **`looop publish` no longer guesses a name inside a lane.** Publishing claims
+  a name permanently, and the name defaults to your folder — so publishing from
+  a lane would have claimed `<game>-<lane>` forever for a throwaway experiment
+  (and, if your `package.json` sets `looop.slug`, would have overwritten your
+  live game with it). From a lane, publish now asks you to say the name out
+  loud: `--slug <name>`. Publishing your actual game is unchanged.
+- **`looop dev` no longer kills a dev server that isn't its own.** It used to
+  take over ports 8000/1999/8788 unconditionally, so a second game — or a lane —
+  would shut down the game you already had running and steal its ports. Now it
+  steps around anything else on those ports and picks the next free set, telling
+  you which it took. Run as many games and lanes at once as you like; they no
+  longer fight. It still reclaims *its own* stale server, so you never end up
+  looking at yesterday's code.
+
+## [0.1.15] - 2026-07-13
+
+### Changed
+- When a non-primitive file lands in your primitives folder, the error now sends
+  you to a `lib/` subfolder for the helper, instead of saying it can live
+  "anywhere in your game". It can't: a primitive runs in the browser too (to
+  predict with), so a helper outside the `/shared/` tree resolves on the room
+  server but 404s in the browser. `lib/` is reachable from both sides.
+
 ## [0.1.14] - 2026-07-13
 
 > How to write a room primitive — the folder, the filename-is-type rule, and

package/bin/looop.mjs

@@ -4,6 +4,7 @@
 // Runs inside a standalone game folder (its own repo). The agent is the
 // primary user: keep output plain, actionable, and machine-legible.
 import { dev } from '../lib/dev.mjs';
+import { lane } from '../lib/lane.mjs';
 import { login, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
@@ -26,6 +27,7 @@ const HELP = `looop — build and run Looop games
 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 lane <name>          Open an isolated copy of the game to experiment in, safely
   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)
@@ -38,7 +40,9 @@ Usage:
   looop help                 This message
 
 The dev stack serves your game at http://localhost:8000/games/<name>/index.html
-with local multiplayer on :1999 and the platform services shim on :8788.
+with local multiplayer on :1999 and the platform services shim on :8788. Run
+several at once (a lane, another game) and each picks its own free ports —
+'looop dev' never disturbs a stack that isn't its own.
 `;
 
 try {
@@ -54,6 +58,13 @@ try {
       // Keep the process alive; servers + children hold the loop open.
       break;
     }
+    case 'lane': {
+      const name = rest.find((a) => !a.startsWith('--'));
+      if (!name) throw new Error('Name the lane: looop lane <name>  (e.g. looop lane judder)');
+      const { dir } = await lane(name);
+      console.log(`\nWork in it:\n  cd ${dir} && npx looop dev\n`);
+      break;
+    }
     case 'create':
       await create({ name: rest.find((a) => !a.startsWith('--')) });
       break;

package/lib/dev.mjs

@@ -10,13 +10,13 @@
 import { spawn } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname } from 'node:path';
+import { join, dirname, basename } from 'node:path';
 import { findProject } from './project.mjs';
 import { ensureEngine } from './engine.mjs';
 import { createStaticServer } from './static-server.mjs';
 import { createLlmShim, DEFAULT_API_BASE } from './llm-shim.mjs';
 import { getToken, getApiBase } from './config.mjs';
-import { portsFor, portInUse, killPort, lanIp } from './ports.mjs';
+import { resolvePorts, portInUse, killPort, lanIp } from './ports.mjs';
 import { assertNoInertOverride, scanPrimitives } from './primitives.mjs';
 import { buildDevRoomServer, DEV_OVERRIDES_DIR } from './room-server.mjs';
 
@@ -52,7 +52,21 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   // Q4 revision: the engine is not an npm dependency — install/refresh it from
   // the platform's login-gated registry (no-op when the pinned version is in).
   const engine = await ensureEngine(project.dir, { log });
-  const ports = portsFor(port ?? Number(process.env.LOOOP_DEV_PORT ?? 8000));
+
+  // Which ports, and may we take them? An explicit --port is obeyed as given
+  // (takeover included). With no flag we step around anyone else's stack —
+  // another lane, another game, an unrelated app — and only ever reclaim our
+  // OWN stale server. See ports.mjs; this is what makes a lane collision-free
+  // without the creator having to remember a flag.
+  const explicit = port ?? (process.env.LOOOP_DEV_PORT ? Number(process.env.LOOOP_DEV_PORT) : null);
+  const { ports, tookOver, steppedAside } = await resolvePorts({
+    projectDir: project.dir,
+    requested: explicit,
+  });
+  for (const s of steppedAside) {
+    const who = s.projectDir ? `another Looop game (${basename(s.projectDir)})` : 'another app';
+    log(`→ :${s.port}  (held by ${who} — leaving it alone)`);
+  }
   const children = [];
   const servers = [];
 
@@ -89,8 +103,11 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   };
 
   // ─── static ───
-  if (await portInUse(ports.static)) {
-    log(`→ static      :${ports.static}  (in use — killing to take over)`);
+  // `tookOver` is the ONLY licence to kill: an explicit --port, or our own
+  // stale server on this block. resolvePorts already walked away from
+  // everyone else's, so anything still here is fair game.
+  if (tookOver && (await portInUse(ports.static))) {
+    log(`→ static      :${ports.static}  (our stale server — reclaiming)`);
     await killPort(ports.static);
   }
   // overrides/shared/… : the game's engine modifications mount ahead of the
@@ -108,6 +125,7 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   const overridesDir = join(project.dir, 'overrides', 'shared');
   const staticServer = createStaticServer({
     slug: project.slug,
+    projectDir: project.dir, // answers /__looop/whoami — see ports.mjs
     mounts: [
       { url: `/games/${project.slug}/`, dir: project.dir },
       { url: '/shared/', dir: generatedOverridesDir },
@@ -124,8 +142,8 @@ export async function dev({ cwd = process.cwd(), port, noMp = process.env.NO_MP
   if (noMp) {
     log(`→ multiplayer :${ports.mp}  (skipped — NO_MP=1)`);
   } else {
-    if (await portInUse(ports.mp)) {
-      log(`→ multiplayer :${ports.mp}  (in use — killing to take over)`);
+    if (tookOver && (await portInUse(ports.mp))) {
+      log(`→ multiplayer :${ports.mp}  (our stale server — reclaiming)`);
       await killPort(ports.mp);
     }
     const pk = spawn(

package/lib/lane.mjs

@@ -0,0 +1,127 @@
+// `looop lane <name>` — open an isolated lane for an experiment.
+//
+// A lane is this game checked out a second time, in its own folder, on its own
+// branch, with its own dev stack. Work in a lane cannot disturb the main
+// checkout: different files, different branch, different servers, different
+// multiplayer room. Win → merge it. Lose → delete the folder; nothing that
+// mattered was ever touched.
+//
+// This exists because the lane used to be a PROCEDURE — a bash block in the
+// build skill: commit-guard, `git worktree add`, `npm install`, and remember a
+// distinct `--port` or you'd kill the main checkout's servers. Four steps,
+// three of them footguns, one of them slow. Agents read that, priced the
+// ceremony, and skipped isolating altogether — repeatedly. The COST was the
+// bug. A procedure a tool can just perform should never be written down and
+// hoped for.
+//
+// What used to be expensive, and isn't any more:
+//
+//   npm install   → node_modules is CLONED from the main checkout. On APFS
+//                   (macOS) and btrfs/xfs (Linux) that's a copy-on-write
+//                   reflink: effectively instant, near-zero extra disk. The
+//                   engine is already sitting one directory up; resolving it
+//                   again over the network was always silly.
+//   --port 8010   → gone. `looop dev` resolves its own ports now and steps
+//                   around anyone else's stack (ports.mjs). A lane just runs
+//                   `npx looop dev`, like everywhere else.
+import { execFileSync } from 'node:child_process';
+import { cpSync, existsSync, statSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { findProject } from './project.mjs';
+import { runNpm } from './npm.mjs';
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+
+// Is this folder a lane (a linked git worktree) rather than the game itself?
+//
+// Git's own marker, no subprocess: in a linked worktree `.git` is a FILE
+// holding `gitdir: …/.git/worktrees/<name>`; in an ordinary repo it's a
+// directory. A folder with no git at all is not a lane.
+//
+// This matters to `publish`, which is global, permanent and irreversible — see
+// the guard there.
+export function isLane(dir) {
+  try {
+    return statSync(join(dir, '.git')).isFile();
+  } catch {
+    return false;
+  }
+}
+
+// Clone a directory tree as cheaply as the filesystem allows.
+//
+// `cp -c` (macOS) and `cp --reflink=auto` (Linux) ask for copy-on-write: the
+// new tree shares its blocks with the old one until something writes. For a
+// node_modules of tens of thousands of files that is the difference between
+// "instant" and "go and make a coffee". Neither is guaranteed — a non-APFS
+// volume, a filesystem without reflinks — so both fall back to a real copy,
+// which is still local, and still beats a network resolve.
+export function cloneTree(src, dest) {
+  const args =
+    process.platform === 'darwin'
+      ? ['-c', '-R', src, dest] // APFS clonefile
+      : process.platform === 'linux'
+        ? ['-r', '--reflink=auto', src, dest] // btrfs/xfs, degrades to a copy
+        : null;
+  if (args) {
+    try {
+      execFileSync('cp', args, { stdio: 'ignore' });
+      return 'cloned';
+    } catch {
+      // Not a CoW filesystem (or no `cp` worth the name — Windows). Fall through.
+    }
+  }
+  cpSync(src, dest, { recursive: true });
+  return 'copied';
+}
+
+export async function lane(name, { cwd = process.cwd(), log = console.log } = {}) {
+  const project = findProject(cwd);
+  const slug = project.slug;
+  const branch = `lane/${name}`;
+  const dir = resolve(project.dir, '..', `${slug}-${name}`);
+
+  if (existsSync(dir)) {
+    throw new Error(
+      `A lane called "${name}" already exists at ${dir}.\n` +
+        `Work in it (cd ${basename(dir)} && npx looop dev), or remove it first ` +
+        `(git worktree remove ${dir}).`,
+    );
+  }
+
+  // `git worktree add` on a repo with NO commits silently produces an empty
+  // orphan lane — the folder exists, the game isn't in it. To a creator that
+  // reads as "the tool deleted my game". Save first, but ONLY in that case:
+  // committing on someone's behalf when they didn't ask is its own betrayal.
+  let savedFirst = false;
+  try {
+    git(project.dir, 'rev-parse', 'HEAD');
+  } catch {
+    log('→ saving your game first (a lane needs at least one save to branch from)');
+    git(project.dir, 'add', '-A');
+    git(project.dir, 'commit', '-m', 'save: initial');
+    savedFirst = true;
+  }
+
+  // Their uncommitted work is deliberately NOT carried across: the lane starts
+  // from the last save. That IS the isolation — the whole point is that what
+  // they're in the middle of stays exactly where it is, untouched.
+  git(project.dir, 'worktree', 'add', '-b', branch, dir);
+  log(`→ lane        ${dir}  (branch ${branch})`);
+
+  // node_modules is gitignored, so the lane arrives empty. Without it, `npx
+  // looop` falls through to a WRONG public package on npm and dies with an
+  // error that reads like a bug in the creator's game.
+  const src = join(project.dir, 'node_modules');
+  let installed = false;
+  if (existsSync(src)) {
+    const how = cloneTree(src, join(dir, 'node_modules'));
+    log(`→ engine      ${how} from the main checkout (no npm install needed)`);
+  } else {
+    log('→ engine      installing (the main checkout has no node_modules to clone)');
+    runNpm(['install'], { cwd: dir, stdio: 'inherit' });
+    installed = true;
+  }
+
+  return { dir, branch, savedFirst, installed };
+}

package/lib/ports.mjs

@@ -8,6 +8,25 @@
 // Takeover: `looop dev` must "just work" — a stale dev session or orphaned
 // workerd holding a port means the user gets stale code with no recourse, so
 // we TERM (then KILL) the listener instead of skipping, exactly like dev.sh.
+//
+// …but ONLY our own. Takeover used to be unconditional: `portInUse()` is a bare
+// TCP connect, so dev killed whatever answered without asking whose it was. In
+// a worktree lane that meant a plain `npx looop dev` SIGKILLed the MAIN
+// checkout's whole stack (game + multiplayer + services) and stole its ports —
+// the tool manufacturing the exact collision a lane exists to prevent, with a
+// remembered `--port 8010` as the only defence. Isolation you have to remember
+// isn't isolation.
+//
+// So a port now has an OWNER, and the answer decides:
+//
+//   free                        → take it
+//   our own dev server          → take it OVER (the stale-code case above)
+//   another project's, or a
+//   foreign app's               → LEAVE IT and step to the next block
+//
+// Ownership is asked, not inferred: the static server answers `/__looop/whoami`
+// with its project dir (static-server.mjs). No registry file to go stale, and
+// nothing to clean up after a crash — if it answers, it's alive.
 import { execFileSync } from 'node:child_process';
 import net from 'node:net';
 import { networkInterfaces } from 'node:os';
@@ -16,11 +35,90 @@ export const STATIC_PORT_BASE = 8000;
 export const MP_PORT_BASE = 1999;
 export const SHIM_PORT_BASE = 8788;
 
+// Ports move in BLOCKS: the browser derives mp/shim from location.port, so the
+// whole stack shifts together. 8000/1999/8788 → 8010/2009/8798 → …
+export const BLOCK_STRIDE = 10;
+export const WHOAMI_PATH = '/__looop/whoami';
+
 export function portsFor(staticPort = STATIC_PORT_BASE) {
   const offset = staticPort - STATIC_PORT_BASE;
   return { static: staticPort, mp: MP_PORT_BASE + offset, shim: SHIM_PORT_BASE + offset };
 }
 
+// Who is on this port? → { projectDir, pid } if one of our dev servers answers,
+// null if the port is silent, or if something that isn't us holds it (a foreign
+// app owes us no answer — and either way the verdict is "not mine, don't touch").
+export function whoIsOn(port, timeoutMs = 400) {
+  return new Promise((resolve) => {
+    const req = net.connect({ port, host: '127.0.0.1' });
+    let body = '';
+    const done = (v) => {
+      req.destroy();
+      resolve(v);
+    };
+    req.setTimeout(timeoutMs, () => done(null));
+    req.on('error', () => done(null)); // nothing listening
+    req.on('connect', () => {
+      req.write(`GET ${WHOAMI_PATH} HTTP/1.0\r\nHost: 127.0.0.1\r\n\r\n`);
+    });
+    req.on('data', (chunk) => {
+      body += chunk;
+      const i = body.indexOf('\r\n\r\n');
+      if (i === -1) return; // headers still arriving
+      if (!/^HTTP\/1\.[01] 200/.test(body)) return done(null); // answered, but not ours
+      try {
+        const parsed = JSON.parse(body.slice(i + 4));
+        done(parsed.projectDir ? parsed : null);
+      } catch {
+        /* body may still be arriving; wait for more, or for the timeout */
+      }
+    });
+    req.on('end', () => done(null));
+  });
+}
+
+// Pick the port block this dev stack should bind.
+//
+// `requested` (an explicit --port) is obeyed as given, takeover included: you
+// named the port, you get the port. Explicit beats clever — it's the AUTO path
+// that has to be safe, because that's the one nobody thought about.
+// `base` exists so the tests can run in a private port range: a suite that
+// probes :8000 for real would fight (and report on) whatever dev servers the
+// developer has running — which is how this file's own tests first "failed".
+export async function resolvePorts({
+  projectDir,
+  requested = null,
+  blocks = 24,
+  base = STATIC_PORT_BASE,
+} = {}) {
+  if (requested != null) {
+    return { ports: portsFor(requested), tookOver: true, steppedAside: [] };
+  }
+  const steppedAside = [];
+  for (let i = 0; i < blocks; i++) {
+    const ports = portsFor(base + i * BLOCK_STRIDE);
+    const owner = (await portInUse(ports.static)) ? await whoIsOn(ports.static) : undefined;
+
+    if (owner === undefined) {
+      // The game port is free — but a block only isolates if the WHOLE stack
+      // fits in it. Half a stack here and half somewhere else is worse than
+      // moving on, so a contaminated block is skipped entire.
+      if ((await portInUse(ports.mp)) || (await portInUse(ports.shim))) {
+        steppedAside.push({ port: ports.static, projectDir: null });
+        continue;
+      }
+      return { ports, tookOver: false, steppedAside };
+    }
+    if (owner && owner.projectDir === projectDir) {
+      return { ports, tookOver: true, steppedAside }; // our own stale server
+    }
+    steppedAside.push({ port: ports.static, projectDir: owner?.projectDir ?? null });
+  }
+  throw new Error(
+    `No free port block after trying ${blocks}. Close a dev server, or pass --port explicitly.`,
+  );
+}
+
 export function portInUse(port) {
   return new Promise((resolve) => {
     const sock = net.connect({ port, host: '127.0.0.1' });

package/lib/primitives.mjs

@@ -106,8 +106,12 @@ export function scanPrimitives(projectDir) {
         throw new Error(
           `${PRIMITIVES_DIR}/${name} has no default export, so it cannot be a primitive.\n` +
             'A primitive is `export default class { ... }`, and its filename is its type name.\n' +
-            `If ${name} is a HELPER your primitive imports, move it out of this folder — anywhere else in\n` +
-            `your game works, or a subfolder here (e.g. ${PRIMITIVES_DIR}/lib/${name}), which is not scanned.`,
+            `If ${name} is a HELPER your primitive imports, put it in a lib/ subfolder here —\n` +
+            `  ${PRIMITIVES_DIR}/lib/${name}\n` +
+            `and import it as './lib/${name}'. The scanner skips lib/, and a primitive runs on BOTH\n` +
+            'sides — bundled into the room AND served to the browser to predict with — so its helper\n' +
+            'has to sit under this /shared/ tree to be reachable from both. Anywhere else in your game\n' +
+            'resolves for the room but 404s in the browser.',
         );
       }
       found.push({ type: name.slice(0, -3), module: `${PRIMITIVES_DIR}/${name}` });

package/lib/publish.mjs

@@ -13,6 +13,7 @@ import { createHash } from 'node:crypto';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { findProject } from './project.mjs';
+import { isLane } from './lane.mjs';
 import { ensureEngine } from './engine.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
@@ -65,6 +66,26 @@ export async function publish({
   log = console.log,
 } = {}) {
   const project = findProject(cwd);
+
+  // A publish is GLOBAL, PERMANENT and IRREVERSIBLE — the first one claims the
+  // name for this account forever. A lane is a throwaway experiment in a folder
+  // named after it, and the slug defaults to the folder name, so a bare publish
+  // from one would claim "riven-judder" for all time (or 403 against whoever
+  // owns it). And when a game overrides `looop.slug`, the lane inherits it and
+  // would silently overwrite the LIVE game with the experiment.
+  //
+  // A name this permanent is never guessed inside a lane. The guard is on
+  // GUESSING, not on publishing: name it with --slug and it goes through.
+  if (!slug && isLane(project.dir)) {
+    throw new Error(
+      `This is a lane, not your game. Publishing from here would claim the name ` +
+        `"${project.slug}" permanently.\n\n` +
+        `  npx looop publish --slug ${project.slug}-test   # publish an A/B copy to compare\n` +
+        `  npx looop publish --slug <your-game>            # ship this lane AS the real game\n\n` +
+        `Or merge the lane into your game and publish from there.`,
+    );
+  }
+
   // The declared engineVersion must be a version the platform can resolve —
   // ensureEngine keeps the local install synced to the game's pin.
   const engine = await ensureEngine(project.dir, { apiBase, log });

package/lib/static-server.mjs

@@ -13,6 +13,7 @@ import { EventEmitter } from 'node:events';
 import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
 import { extname, join, normalize, sep } from 'node:path';
 import { injectHeadTags, rewriteHtmlScripts, rewriteJsImports, PLATFORM_URL } from './inject.mjs';
+import { WHOAMI_PATH } from './ports.mjs';
 
 const RELOAD_CLIENT = `<script>
 (() => {
@@ -96,6 +97,7 @@ function mtimesChanged(a, b) {
 export function createStaticServer({
   slug,
   mounts,
+  projectDir = null,
   watchDirs = [],
   injectReload = true,
   watchIntervalMs = 400,
@@ -214,6 +216,18 @@ export function createStaticServer({
     const reqUrl = new URL(req.url, 'http://x');
     const urlPath = reqUrl.pathname;
     if (urlPath === '/__reload') return handleSse(res);
+    // Ownership probe (ports.mjs): "whose dev server is this?". It is what lets
+    // another `looop dev` — a lane, another game — tell OUR stale server (kill
+    // and reclaim) from a live one that belongs to somebody else (step around,
+    // never touch). Answering honestly here is what keeps lanes from colliding.
+    if (urlPath === WHOAMI_PATH) {
+      return sendBody(
+        res,
+        200,
+        JSON.stringify({ projectDir, slug, pid: process.pid }),
+        'application/json',
+      );
+    }
     if (urlPath === '/' || urlPath === '/index.html') {
       res.writeHead(302, { Location: gameEntry });
       return res.end();

package/package.json

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