@looop-games/cli 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -14,6 +14,39 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.13] - 2026-07-12
+
+### Fixed
+- **`looop update` deleted your engine.** The engine is not an npm package — it
+  installs without a record in `package.json`, so *any* `npm install` in your game
+  treats it as junk and removes it. `looop update` then updated the `looop` command
+  itself with an npm install — **after** putting the engine in place — and wiped it
+  out every time. The update said it succeeded; `node_modules/@looop-games/engine`
+  was gone. Everything that reads the engine then failed, and re-running
+  `looop update` cheerfully said "already up to date" and fixed nothing.
+
+  The engine is now the last thing installed, and an update that finds it missing
+  puts it back (from the local cache — instant, no download). If you hit this, one
+  `npx looop update` repairs it.
+- `looop lint` said "this engine ships no rules yet" when the real problem was that
+  the engine was not installed at all — sending you to `looop update`, the one
+  command that could not help. It now tells you which of the two it is.
+
+## [0.1.12] - 2026-07-12
+
+### Added
+- `looop lint` — check your game against the Looop rules: the mistakes that ship
+  a broken game while every test stays green. `looop lint --fix` applies the ones
+  that can be fixed mechanically.
+- `looop test` now runs the lint first, before it starts a browser. A hardcoded
+  multiplayer host is reported in a second, instead of after a full smoke run
+  that passed for the wrong reason.
+
+  The rules themselves live in the engine (so `looop update` brings you new ones)
+  and your game's `eslint.config.js` imports the same file the gate runs — the
+  editor and the test can't disagree. Nothing changes for an existing game until
+  you install eslint (`npm i -D eslint`); new games get it out of the box.
+
 ## [0.1.11] - 2026-07-12
 
 ### Fixed

package/bin/looop.mjs

@@ -8,6 +8,7 @@ import { login, whoami } from '../lib/login.mjs';
 import { publish } from '../lib/publish.mjs';
 import { create } from '../lib/create.mjs';
 import { testCmd } from '../lib/test-cmd.mjs';
+import { lintCmd } from '../lib/lint.mjs';
 import { update } from '../lib/update.mjs';
 import { changelog } from '../lib/changelog.mjs';
 import { sendFeedback } from '../lib/feedback.mjs';
@@ -26,6 +27,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 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 publish [--slug <s>]  Publish this game to play.looop.games (--slug for an A/B copy)
@@ -59,6 +61,10 @@ try {
       const { ok } = await testCmd();
       process.exit(ok ? 0 : 1);
     }
+    case 'lint': {
+      const { ok } = await lintCmd({ fix: rest.includes('--fix') });
+      process.exit(ok ? 0 : 1);
+    }
     case 'changelog':
       await changelog({
         version: rest.find((a) => !a.startsWith('--')),

package/lib/create.mjs

@@ -67,6 +67,14 @@ const ALLOW_SCRIPTS = { esbuild: true, workerd: true, fsevents: true };
 // what create-time provisioning exists to prevent.
 const PLAYWRIGHT_SPEC = '^1.61.1';
 
+// The Looop rules ship as an ESLint config (the scaffold's eslint.config.js,
+// importing the rules from the installed engine), so they squiggle in the
+// creator's editor as the code is written — a far tighter loop than a failing
+// gate, and the whole reason this is ESLint and not a bespoke scanner. That
+// only works if eslint is actually installed, so it is a scaffold
+// devDependency, exactly like playwright. `looop test` also runs it.
+const ESLINT_SPEC = '^10.7.0';
+
 // Copy the starter game out of the artifact. One rename: `gitignore` →
 // `.gitignore` (npm pack silently strips .gitignore files from a package, so
 // the artifact stores it dot-less).
@@ -105,8 +113,8 @@ async function scaffold({ dir, name, install, cliSpec, apiBase, log, ensure, rec
         name,
         private: true,
         description: `A Looop game. Play at https://play.looop.games/g/${name}`,
-        scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test' },
-        devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC },
+        scripts: { dev: 'looop dev', publish: 'looop publish', test: 'looop test', lint: 'looop lint' },
+        devDependencies: { '@looop-games/cli': cliSpec, playwright: PLAYWRIGHT_SPEC, eslint: ESLINT_SPEC },
         allowScripts: ALLOW_SCRIPTS,
       },
       null,

package/lib/lint.mjs

@@ -0,0 +1,140 @@
+// `looop lint` — the hard rules, made executable.
+//
+// A "Never" that lives only in prose is a suggestion. The rules that have
+// actually shipped broken games are enforced here: in the editor as you type
+// (via the game's eslint.config.js) and in the gate (`looop test` runs this
+// first).
+//
+// The rules themselves live in the ENGINE (`<engine>/eslint/`), not in this
+// package — they are something the creator receives, so they have one authoring
+// home and one release lane, and `looop update` brings a game the new ones. This
+// command resolves them out of the game's installed engine, which is the very
+// same file its eslint.config.js imports. One copy: the gate and the editor
+// cannot disagree.
+//
+// Escape hatch: `// eslint-disable-next-line looop/<rule>` — the one every
+// developer already knows. This is mandatory, not a nicety: creators are not
+// developers, and a false positive must never wall someone out of their own
+// test command with no way through.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { findProject, resolveEngine } from './project.mjs';
+
+const CONFIG_NAMES = ['eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs'];
+
+// Resolve ESLint from the GAME's node_modules — same preflight shape as
+// playwright in test-cmd.mjs. Games scaffolded before lint existed simply don't
+// have it; they skip rather than break.
+async function loadFromProject(projectDir) {
+  try {
+    const req = createRequire(join(projectDir, 'package.json'));
+    const mod = await import(pathToFileURL(req.resolve('eslint')).href);
+    return mod.ESLint ?? mod.default?.ESLint ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The shareable config, out of the installed engine artifact.
+//
+// The two ways this can come up empty are DIFFERENT problems with different
+// fixes, and conflating them sends people in a circle: the first version of this
+// said "engine ships no rules — run looop update" when the engine was not
+// installed at all, so `looop update` was the one command that could never help.
+// Say which it is.
+async function loadRulesFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return { configs: null, why: 'no-engine' };
+  }
+  const entry = join(engineDir, 'eslint', 'index.js');
+  if (!existsSync(entry)) return { configs: null, why: 'engine-too-old' };
+  const mod = await import(pathToFileURL(entry).href);
+  return { configs: mod.configs ?? mod.default?.configs ?? null, why: 'ok' };
+}
+
+export async function lintCmd({
+  cwd = process.cwd(),
+  fix = false,
+  log = console.log,
+  loadEslint = loadFromProject,
+  loadRules = loadRulesFromEngine,
+} = {}) {
+  const project = findProject(cwd);
+
+  const ESLint = await loadEslint(project.dir);
+  if (!ESLint) {
+    log('⚠️  looop lint: eslint is not installed in this game — skipping the rule checks.');
+    log('   To turn them on (recommended — they catch bugs that silently pass your tests):');
+    log('     npm i -D eslint');
+    return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
+  }
+
+  const { configs, why } = await loadRules(project.dir);
+  if (!configs) {
+    if (why === 'no-engine') {
+      // The engine is not on disk. Usually it was PRUNED: it installs with
+      // `npm install --no-save`, so npm has no record of it and any later
+      // `npm install` in this game deletes it. It is not lost — it is cached.
+      log('⚠️  looop lint: the Looop engine is not installed in this game — skipping.');
+      log('   (A plain `npm install` removes it; it is cached, so putting it back is instant.)');
+      log('   Restore it with:  looop update');
+    } else {
+      log('⚠️  looop lint: your engine is older than the Looop rules — skipping.');
+      log('   Get an engine that carries them:  looop update');
+    }
+    return { ok: true, skipped: true, errorCount: 0, warningCount: 0 };
+  }
+
+  // A game that ships its own eslint.config.js owns its rules — we do not
+  // override it (and the scaffold's config already spreads ours in). Otherwise
+  // lint with the engine's recommended set, so a repo created before lint
+  // existed still gets the checks with zero setup.
+  const hasOwnConfig = CONFIG_NAMES.some((n) => existsSync(join(project.dir, n)));
+  const eslint = new ESLint({
+    cwd: project.dir,
+    fix,
+    ...(hasOwnConfig ? {} : { overrideConfigFile: true, baseConfig: configs.recommended }),
+  });
+
+  const results = await eslint.lintFiles(['.']);
+  if (fix) await ESLint.outputFixes(results);
+
+  let errorCount = 0;
+  let warningCount = 0;
+  for (const r of results) {
+    errorCount += r.errorCount;
+    warningCount += r.warningCount;
+  }
+
+  if (errorCount || warningCount) {
+    // ESLint's own stylish formatter: the creator's agent (and their editor)
+    // already know how to read it.
+    const formatter = await eslint.loadFormatter('stylish');
+    const text = await formatter.format(results);
+    if (text.trim()) log(text.trim());
+  }
+
+  if (errorCount === 0) {
+    log(`✅ looop lint: clean (${results.length} file(s))${fix ? ' — fixes applied' : ''}`);
+  } else {
+    log('');
+    log(`❌ looop lint: ${errorCount} error(s) in ${results.filter((r) => r.errorCount).length} file(s)`);
+    if (results.some((r) => r.messages.some((m) => m.fix))) {
+      log('   Some of these are auto-fixable: `looop lint --fix`');
+    }
+    log('   A rule is wrong about your code? `// eslint-disable-next-line <rule>` above the line.');
+  }
+
+  return {
+    ok: errorCount === 0,
+    skipped: false,
+    errorCount,
+    warningCount,
+    files: results.map((r) => relative(project.dir, r.filePath)),
+  };
+}

package/lib/test-cmd.mjs

@@ -13,6 +13,7 @@ import { createRequire } from 'node:module';
 import { join, relative, dirname } from 'node:path';
 import { findProject } from './project.mjs';
 import { dev } from './dev.mjs';
+import { lintCmd } from './lint.mjs';
 import { portsFor, portInUse } from './ports.mjs';
 
 const SKIP_DIRS = new Set(['node_modules', 'overrides']);
@@ -56,17 +57,24 @@ async function freeTestPort(base = 8100) {
   throw new Error('no free port triple found for the test dev stack');
 }
 
-export async function testCmd({ cwd = process.cwd(), log = console.log, devFn = dev } = {}) {
+export async function testCmd({ cwd = process.cwd(), log = console.log, devFn = dev, lintFn = lintCmd } = {}) {
   const project = findProject(cwd);
   const { unit, smokes } = discoverTestFiles(project.dir);
 
+  // Lint FIRST — it needs no servers and no browser, and the defects it catches
+  // (a hardcoded multiplayer host, a smoke pointed at the wrong port) are
+  // exactly the ones that make the suite below pass while testing nothing.
+  // Failing here does not skip the tests: the creator should see everything
+  // that is wrong in one run, not peel it one gate at a time.
+  const lint = await lintFn({ cwd: project.dir, log });
+
   if (unit.length + smokes.length === 0) {
     log(`No tests yet in ${project.dir} — nothing to run.`);
     log('(Unit tests are *.test.mjs; browser smokes are *.smoke.mjs. Anything with an assertion is a regression test — keep it.)');
-    return { ok: true, ran: 0 };
+    return { ok: lint.ok, ran: 0 };
   }
 
-  let ok = true;
+  let ok = lint.ok;
 
   // If looop test itself runs under a node --test parent, the inherited
   // NODE_TEST_CONTEXT makes a nested `node --test` exit 0 even on failure —
@@ -130,5 +138,5 @@ export async function testCmd({ cwd = process.cwd(), log = console.log, devFn =
 
   log('');
   log(ok ? `✅ looop test: all green (${unit.length} unit file(s), ${smokes.length} smoke(s))` : '❌ looop test: failures above');
-  return { ok, ran: unit.length + smokes.length };
+  return { ok, ran: unit.length + smokes.length, lint };
 }

package/lib/update.mjs

@@ -97,19 +97,52 @@ export async function update({
         .sort((a, b) => compareVersions(b.version, a.version))
     : null;
 
+  // ── The `looop` command FIRST, before the engine lands ─────────────────────
+  //
+  // Order is load-bearing, and getting it wrong deleted the engine. The engine is
+  // not an npm package — it installs with `npm install --no-save`, so npm has no
+  // record of it and treats it as extraneous. ANY later `npm install` in the game
+  // prunes it. syncCli runs exactly such an install (`--save-dev` the new CLI), so
+  // running it AFTER the engine install wiped the engine every single time: the
+  // update reported success and left node_modules/@looop-games/engine gone. The
+  // next `looop lint` then found no engine at all (caught on a real game).
+  //
+  // So: do every npm install that this command is going to do BEFORE the engine
+  // is put on disk, and let the engine be the last thing to land.
+  //
+  // Wrapped: syncCli is already fail-soft, and a bug in it must not stop the
+  // engine update that is the point of this command.
+  let cli;
+  try {
+    cli = await syncCliFn({ projectDir: project.dir, log });
+  } catch (err) {
+    cli = { updated: false, error: err };
+  }
+
   let engineDir = null;
   let updated = false;
 
   if (from === latest) {
-    log(`✅ Engine ${latest} — already up to date.`);
     // 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.
     try {
       engineDir = resolveEngine(project.dir).dir;
+      log(`✅ Engine ${latest} — already up to date.`);
     } catch {
-      engineDir = null; // engine not installed yet — the next `dev` fetches it
+      // 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.`);
+      const engine = await ensure(project.dir, { apiBase, log, fetchImpl });
+      engineDir = engine.dir ?? null;
+      log('');
+      log(`✅ Engine ${latest} — restored.`);
     }
   } else {
     // Rewrite the pin first; ensureEngine honors it (download → install → pin).
@@ -125,21 +158,18 @@ export async function update({
   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.
+  // we reconciled ship WITH the engine and can name any command they like — a real
+  // game 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 };
+  // It already RAN, at the top: its npm install has to happen before the engine
+  // lands or it prunes it. This is only the report.
+  if (cli?.error) {
     log('');
-    log(`   The looop command could not be updated (${err.message}).`);
+    log(`   The looop command could not be updated (${cli.error.message}).`);
     log('   Your engine and skills are up to date. Retry with: npm update @looop-games/cli');
+  } else {
+    reportCli(log, cli);
   }
 
   if (updated) {

package/package.json

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