@looop-games/cli 0.1.17 → 0.1.18

package/CHANGELOG.md

@@ -14,6 +14,21 @@ Versions: [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.18] - 2026-07-15
+
+### Added
+
+- **`looop dev`, `looop test`, and `looop publish` understand entity
+  components.** A game that declares behavior in `components/` folders (the
+  entity system — see `shared/practices/entities.md` in your installed engine)
+  now works across the whole command surface: `dev` bundles your components
+  into the local room server, `test` runs the entity graph lint out of the
+  installed engine before anything else (it runs even when eslint isn't
+  installed in the game), and `publish` bundles them into your game's own
+  multiplayer server — a component game is server-backed automatically,
+  exactly like a primitives game. Requires engine 0.1.27 or newer; run
+  `looop update` if your game pins an older one.
+
 ## [0.1.17] - 2026-07-14
 
 ### Added

package/lib/bundle-primitives.mjs

@@ -17,6 +17,7 @@
 // class past the setInterval/park cost boundary. Keeping it external means the
 // worker's room code is always ours.
 import { assertNoOverrideCycle, PRIMITIVES_DIR, SERVER_BARREL, renderBarrel, scanPrimitives } from './primitives.mjs';
+import { scanEntityComponents, renderEntityComponents } from './room-server.mjs';
 import { shadowResolvePlugin } from './shadow-resolve.mjs';
 import { join } from 'node:path';
 
@@ -29,17 +30,19 @@ export const PRIMITIVES_ENTRY = SERVER_BARREL;
 // engine import in the primitives bundle is rewritten to this.
 export const ENGINE_ARTIFACT_MODULE = './rooms-runtime.js';
 
-export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
+export async function bundlePrimitives(projectDir, { esbuildImpl, engineSharedDir } = {}) {
   // The barrel is GENERATED, not authored. A creator adds a primitive by adding
-  // a file to `overrides/shared/ui/room/primitives/` — there is no list to keep
-  // in sync, and therefore no way for the list and the folder to disagree.
+  // a file to `overrides/shared/ui/room/primitives/` — and an entity component
+  // by adding a folder under components/ — there is no list to keep in sync,
+  // and therefore no way for the list and the folder to disagree.
   const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
-  if (!primitives.length) {
+  const engineShared = engineSharedDir ?? join(projectDir, 'node_modules/@looop-games/engine/shared');
+  const entityComponents = await scanEntityComponents(projectDir, engineShared); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
     throw new Error(
-      `no server primitives to bundle — ${PRIMITIVES_DIR}/ is empty (this is not a server-backed game)`,
+      `nothing to bundle — ${PRIMITIVES_DIR}/ and components/ are both empty (this is not a server-backed game)`,
     );
   }
-  const engineShared = join(projectDir, 'node_modules/@looop-games/engine/shared');
   assertNoOverrideCycle(primitives, projectDir, engineShared);
 
   const esbuild = esbuildImpl ?? (await import('esbuild'));
@@ -68,7 +71,7 @@ export async function bundlePrimitives(projectDir, { esbuildImpl } = {}) {
     // against the game root so `./overrides/...` means what it says. Same shape
     // the dev room server uses (lib/room-server.mjs) — one contract, two builds.
     stdin: {
-      contents: renderBarrel(primitives),
+      contents: `${renderBarrel(primitives)}\n${renderEntityComponents(entityComponents)}\n`,
       resolveDir: projectDir,
       sourcefile: 'looop-primitives.js',
       loader: 'js',

package/lib/lint.mjs

@@ -57,21 +57,46 @@ async function loadRulesFromEngine(projectDir) {
   return { configs: mod.configs ?? mod.default?.configs ?? null, why: 'ok' };
 }
 
+// The entity graph lint — the SECOND shared step, alongside the eslint rules.
+// Like the rules, the implementation lives in the ENGINE (shared/ui/room/
+// entity/lint-run.mjs), so every gate that checks a game runs the identical
+// pass — there is no second copy to drift. An engine too old to carry it
+// skips — same degradation contract as the rules.
+async function loadEntityLintFromEngine(projectDir) {
+  let engineDir;
+  try {
+    ({ dir: engineDir } = resolveEngine(projectDir));
+  } catch {
+    return null;
+  }
+  const entry = join(engineDir, 'shared', 'ui', 'room', 'entity', 'lint-run.mjs');
+  if (!existsSync(entry)) return null;
+  const mod = await import(pathToFileURL(entry).href);
+  return mod.runEntityLint ?? null;
+}
+
 export async function lintCmd({
   cwd = process.cwd(),
   fix = false,
   log = console.log,
   loadEslint = loadFromProject,
   loadRules = loadRulesFromEngine,
+  loadEntityLint = loadEntityLintFromEngine,
 } = {}) {
   const project = findProject(cwd);
 
+  // The entity graph check runs regardless of the eslint tooling below — a
+  // missing dev tool must never switch off a structural guarantee. It skips
+  // itself silently for games with no entity folders.
+  const runEntity = await loadEntityLint(project.dir);
+  const entity = runEntity ? await runEntity(project.dir, { log }) : { ok: true, skipped: true };
+
   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 };
+    return { ok: entity.ok, skipped: true, errorCount: 0, warningCount: 0, entity };
   }
 
   const { configs, why } = await loadRules(project.dir);
@@ -87,7 +112,7 @@ export async function lintCmd({
       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 };
+    return { ok: entity.ok, skipped: true, errorCount: 0, warningCount: 0, entity };
   }
 
   // A game that ships its own eslint.config.js owns its rules — we do not
@@ -131,10 +156,11 @@ export async function lintCmd({
   }
 
   return {
-    ok: errorCount === 0,
+    ok: errorCount === 0 && entity.ok,
     skipped: false,
     errorCount,
     warningCount,
+    entity,
     files: results.map((r) => relative(project.dir, r.filePath)),
   };
 }

package/lib/primitives.mjs

@@ -127,8 +127,19 @@ export function scanPrimitives(projectDir) {
 // other. (They used to disagree: publish looked for `_local/primitives/index.js`
 // while dev looked for a `partykit.json` that nothing ever created, so a
 // creator's primitive ran in production and silently did not run in dev.)
+//
+// TWO trees make a game server-backed: vendored primitives (overrides/) and
+// entity components (components/, or entity-local ones under entities/). The
+// entity half is a cheap folder check, not a scan — a malformed component
+// still makes the game server-backed; the build is where it fails loudly.
 export function isServerBacked(projectDir) {
-  return scanPrimitives(projectDir).length > 0;
+  if (scanPrimitives(projectDir).length > 0) return true;
+  if (existsSync(join(projectDir, 'components'))) return true;
+  const entitiesDir = join(projectDir, 'entities');
+  if (!existsSync(entitiesDir)) return false;
+  return readdirSync(entitiesDir).some((name) => {
+    try { return existsSync(join(entitiesDir, name, 'components')); } catch { return false; }
+  });
 }
 
 // The one cycle shadowing makes possible, caught in the creator's own words.

package/lib/publish.mjs

@@ -18,6 +18,7 @@ import { ensureEngine } from './engine.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 import { bundlePrimitives } from './bundle-primitives.mjs';
+import { scanEntityComponents } from './room-server.mjs';
 import {
   BROWSER_REGISTRY,
   SERVER_BARREL,
@@ -119,13 +120,22 @@ export async function publish({
   // are killing is an override that uploads, serves, and silently never runs.
   assertNoInertOverride({ projectDir: project.dir, engine });
   const serverPrimitives = scanPrimitives(project.dir); // throws on a reserved index.js
-  if (serverPrimitives.length) {
-    const { source, externals } = await bundlePrimitives(project.dir);
+  const entityComponents = await scanEntityComponents(project.dir, engine.sharedDir); // throws on a malformed component
+  if (serverPrimitives.length || entityComponents.length) {
+    const { source, externals } = await bundlePrimitives(project.dir, { engineSharedDir: engine.sharedDir });
     files.set(SERVER_BARREL, Buffer.from(source, 'utf8'));
-    files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
-    const names = serverPrimitives.map((p) => p.type).join(', ');
+    // The browser prediction registry exists for PRIMITIVES only — entity
+    // components' client/shared files ship as ordinary game files, and the
+    // client imports its own manifests directly.
+    if (serverPrimitives.length) {
+      files.set(BROWSER_REGISTRY, Buffer.from(renderBrowserRegistry(serverPrimitives), 'utf8'));
+    }
+    const names = [
+      ...serverPrimitives.map((p) => p.type),
+      ...entityComponents.map((c) => `${c.name} (component)`),
+    ].join(', ');
     log(
-      `Bundled server primitives — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
+      `Bundled server code — ${names} (${(source.length / 1024).toFixed(0)} KB, engine external${externals.length ? `: ${[...new Set(externals)].length} module(s)` : ''}).`,
     );
   }
 

package/lib/room-server.mjs

@@ -23,8 +23,9 @@
 // imports EXTERNAL and rewrites them to the release's pre-bundled
 // `rooms-runtime.js`, because the publish endpoint is a Worker with no bundler.
 // Same seam, two deliveries.)
-import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import {
   assertNoOverrideCycle,
   isServerBacked,
@@ -65,17 +66,76 @@ function engineAliasPlugin(sharedDir) {
   };
 }
 
+// Entity components take the same trip as vendored primitives: scanned from
+// the game tree, bundled, handed to the host — through the sibling
+// `extraEntityComponents()` seam. The room bundle carries each component's
+// MANIFEST (so channel gates are trusted — a world spec arrives from a
+// client and may not define them) and its SIM entry: `server/sim.js` when
+// the component has one, else `shared/sim.js` (predicted sims live in
+// shared/ so the browser can run them too; server/ is for genuinely
+// server-only adjudication and may import shared/ itself).
+//
+// The scan implementation lives in the ENGINE (shared/ui/room/entity/) at
+// the same relative path in the repo and the built artifact. An engine too
+// old to carry it means no entity components exist for that game — skip.
+export async function scanEntityComponents(projectDir, sharedDir) {
+  const scanPath = join(sharedDir, 'ui', 'room', 'entity', 'scan.js');
+  if (!existsSync(scanPath)) return [];
+  const { scanGame } = await import(pathToFileURL(scanPath).href);
+  const { components, errors } = scanGame(projectDir);
+  if (errors.length) {
+    throw new Error(`this game's entity components cannot build a room server:\n  - ${errors.join('\n  - ')}`);
+  }
+  const posix = (p) => relative(projectDir, p).split('\\').join('/');
+  return [...components.values()].map((c) => {
+    const serverSim = join(c.dir, 'server', 'sim.js');
+    const sharedSim = join(c.dir, 'shared', 'sim.js');
+    const code = existsSync(serverSim) ? serverSim : existsSync(sharedSim) ? sharedSim : null;
+    return {
+      name: c.name,
+      manifestRel: posix(c.manifestPath),
+      codeRel: code ? posix(code) : null,
+    };
+  });
+}
+
+export function renderEntityComponents(components) {
+  if (!components.length) return 'export const extraEntityComponents = null;';
+  const lines = [];
+  const manifests = [];
+  const code = [];
+  components.forEach((c, i) => {
+    lines.push(`import entityManifest${i} from './${c.manifestRel}';`);
+    manifests.push(`entityManifest${i}`);
+    if (c.codeRel) {
+      lines.push(`import * as entityCode${i} from './${c.codeRel}';`);
+      code.push(`    '${c.name}': entityCode${i},`);
+    }
+  });
+  return [
+    ...lines,
+    'export const extraEntityComponents = {',
+    `  manifests: [${manifests.join(', ')}],`,
+    '  code: {',
+    ...code,
+    '  },',
+    '};',
+  ].join('\n');
+}
+
 // The room the game actually gets: the engine's room class, subclassed to hand
 // the host the creator's primitives through the `extraPrimitives()` seam the
 // engine already reads (server.js). Identical in shape to what the publish
 // endpoint generates for the per-game Worker — one contract, two builders.
-function renderEntry(primitives) {
+function renderEntry(primitives, entityComponents) {
   return [
     renderBarrel(primitives),
+    renderEntityComponents(entityComponents),
     "import LooopRoom from '/shared/ui/room/server.js';",
     '',
     'export default class GameRoom extends LooopRoom {',
     '  extraPrimitives() { return extraPrimitives; }',
+    '  extraEntityComponents() { return extraEntityComponents; }',
     '}',
     '',
   ].join('\n');
@@ -88,7 +148,8 @@ function renderEntry(primitives) {
 // dev must not quietly serve a room that is missing the creator's code.
 export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
   const primitives = scanPrimitives(projectDir); // throws on a reserved index.js
-  if (!primitives.length) {
+  const entityComponents = await scanEntityComponents(projectDir, engine.sharedDir); // throws on a malformed component
+  if (!primitives.length && !entityComponents.length) {
     // Not server-backed (any more). A PREVIOUS run may have generated a room
     // server and a registry shadow; both must go, or dev keeps mounting a stale
     // `.looop/overrides/shared/.../index.js` that imports a primitive the creator
@@ -109,7 +170,7 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
     // against the game root, so `./overrides/...` means what it says and no
     // machine-specific absolute path can leak into the output.
     stdin: {
-      contents: renderEntry(primitives),
+      contents: renderEntry(primitives, entityComponents),
       resolveDir: projectDir,
       sourcefile: 'looop-room-server.js',
       loader: 'js',
@@ -156,9 +217,15 @@ export async function buildDevRoomServer({ projectDir, engine, esbuildImpl }) {
   // same in dev (static mount fall-through) and in production (the import map):
   //   /shared/ui/room/primitives/engine.js  → not shadowed → the engine's list
   //   /shared/ui/room/primitives/beacon.js  → shadowed     → the game's primitive
-  const registryDir = join(projectDir, DEV_OVERRIDES_DIR, 'ui/room/primitives');
-  mkdirSync(registryDir, { recursive: true });
-  writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+  if (primitives.length) {
+    const registryDir = join(projectDir, DEV_OVERRIDES_DIR, 'ui/room/primitives');
+    mkdirSync(registryDir, { recursive: true });
+    writeFileSync(join(registryDir, 'index.js'), renderBrowserRegistry(primitives));
+  } else {
+    // Entity components alone need no primitive-registry shadow — and a stale
+    // one from a removed primitive must not stay mounted.
+    rmSync(join(projectDir, DEV_OVERRIDES_DIR), { recursive: true, force: true });
+  }
 
   return outDir;
 }

package/package.json

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