@motujs/cli 0.0.0-stage → 0.1.1

package/src/run.mjs

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+// motu — the agentic CLI for the island / archipelago workflow.
+//
+//   motu island create <name>    scaffold a new island (component + registry row + fixtures)
+//   motu island verify <name>    run the deterministic island rules + lagoon mount (the moat)
+//                                `--all` sweeps every island; one line each, findings only where there are any
+//
+// Kept dependency-light and plain-ESM (like @motujs/codegen) so it runs with a bare `node`.
+import { createCommand } from './commands/create.mjs';
+import { verifyCommand, archipelagoVerifyCommand } from './commands/verify.mjs';
+import { checkCommand } from './commands/check.mjs';
+import { snapshotCommand, archipelagoSnapshotCommand } from './commands/snapshot.mjs';
+import { integrateCommand } from './commands/integrate.mjs';
+import { integrateCheckCommand } from './commands/integration.mjs';
+import { archipelagoInitCommand } from './commands/archipelago-init.mjs';
+import { regionCoverageCommand } from './commands/region-coverage.mjs';
+import { coverageCommand } from './commands/coverage.mjs';
+import { diffCommand, flowsTraceCommand } from './commands/diff.mjs';
+import { assuranceCommand } from './commands/assurance.mjs';
+import { screenVerifyCommand } from './commands/verify/screens-runtime.mjs';
+import { closeLagoonPool } from './playwright-lagoon.mjs';
+import { archipelagoAdoptRootCommand } from './commands/adopt-root.mjs';
+import { codegenCommand } from './commands/codegen.mjs';
+import { fixturesRecordCommand } from './commands/fixtures.mjs';
+import { islandDefaultsCommand } from './commands/defaults.mjs';
+import { syncCommand } from './commands/sync.mjs';
+import { removalCheckCommand } from './commands/removal-check.mjs';
+import { lagoonPublishCommand, lagoonServeCommand, lagoonEjectCommand, lagoonStatesCommand } from './commands/lagoon.mjs';
+import { lagoonTryCommand } from './commands/lagoon-try.mjs';
+import { loadMotuConfig, assertProject } from './lib/config.mjs';
+import { initCommand } from './commands/init.mjs';
+import { skillsInstallCommand, skillsListCommand } from './commands/skills.mjs';
+import { color, ensureNoInstallLinks, REPO_ROOT, MOTU_CHECKOUT } from './lib/util.mjs';
+
+/** Minimal argv parser: positionals in `_`, `--flag`/`--no-flag`/`--key value` in the rest. */
+function parse(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--no-')) out[a.slice(5)] = false;
+    else if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith('--')) {
+        out[key] = next;
+        i++;
+      } else out[key] = true;
+    } else out._.push(a);
+  }
+  return out;
+}
+
+const USAGE = `${color.bold('motu')} — island / archipelago CLI
+
+${color.bold('Usage:')}
+  motu init [dir] --host next|angularjs|none        scaffold config + registries + a WORKING lagoon root
+  motu link [--check]                               record @motujs/* in package.json (npm deletes bare links)
+  motu island create <name>                         scaffold a new island (component, registry, fixtures)
+  motu island create <name> --from <specifier>      ...over a component the app ALREADY owns (React hosts)
+  motu check                                        every island + every region + removal, one verdict
+  motu island verify <name|--all>                   the island rules (static; --runtime adds the browser)
+  motu island snapshot <name|--all> [--update]      visual baselines, per scenario × viewport
+  motu island snapshot --all --remote               ...stored on the lagoon host instead of in git
+  motu island snapshot --all --remote --changed     ...only what this branch touched
+  motu island snapshot --accept <name>              move the accepted baseline — a decision, not a write
+  motu island defaults [name]                       classify declared defaults: component default, or evidence?
+  motu sync                                         regenerate every derived file (registry, contracts, region module)
+  motu island integrate <name> --archipelago <id>   make the island a member of an archipelago
+  motu integrate check [region]                     does the HOST compose, place and read the region?
+  motu archipelago init <id> --page <file>          scaffold everything a page needs before its 1st island
+  motu archipelago init <id>                        ...a NEW region with no page yet: the archipelago, root first
+  motu archipelago verify <id|--all>                boot the whole region in the lagoon + config checks
+  motu archipelago snapshot <id|--all> --remote      picture the COMPOSED page — catches arrangement
+  motu archipelago coverage <id> [--corpus <f>]     states production reached that no flow previews
+  motu diff --base <ref> [--explain <file>] [--json] what the change did to the flows: keys, renders, calls, declarations — each to explain or fix
+  motu assurance [id] [--json]                    one row per declared thing (slot, write, key, calls) and the strongest evidence holding it
+  motu screen verify [id] [--json]                  open each declared screen (or one), hold its calls to declarations, replay screen flows
+  motu coverage init [--mode forward|log]           wire production coverage: the route, the ingest token, the one step left
+  motu coverage doctor --url <origin>               prove the deployed route reaches the host; names the hop that fails
+  motu coverage pull --from <log|->                 upload \`motu-coverage\` lines from a log-mode server's log
+    --json --ids --accept <id> --fail-above <n>     machine-readable · print ids · accept one · gate
+    --forget <id> | --forget-all                    remove a state the instrument recorded wrongly
+  motu fixtures record <island>                     capture backend responses into request-keyed fixtures
+  motu lagoon states [island|region]                every state the lagoon can be OPENED in, as a URL
+  motu lagoon try <region> [step…]                  "what happens if…?" — each step's keys, slots and calls
+  motu lagoon eject                                 write the framework's lagoon entries into the project
+  motu lagoon publish [island]                      build the lagoon as one self-contained page to publish
+  motu lagoon publish --remote <url>                ...or upload it to a lagoon host as chunks (see motu-host)
+  motu lagoon serve [island]                        build that same page and serve it (preview it in a browser)
+  motu lagoon serve --watch [--host]                ...and keep it current: rebuild on save, reload viewers (the loop)
+  motu lagoon serve --watch --detach | --stop       ...left running after the shell exits, and stopped
+  motu removal-check [--force]                      prove motu is removable from the host app (C2)
+  motu codegen [manifest] [outDir]                  regenerate @motujs/contract from motu-manifest.json
+  motu skills install [dir]                         install the motu agent skills into a repo (Copilot + Claude Code)
+  motu skills list                                  list the skills this motu checkout ships
+
+${color.bold('snapshot flags:')}
+  --update        record the baselines instead of checking them (a deliberate, separate act)
+  --all           every island
+  --json          machine-readable report
+  ${color.dim('baselines live in <islands>/<kebab>.snapshots/, one per scenario × viewport; commit them.')}
+
+${color.bold('removal-check flags:')}
+  --force         re-prove it even when nothing it depends on has changed
+  ${color.dim('the proof is cached against the files it touches + the islands/archipelagos it generates from;')}
+  ${color.dim('an unchanged repo skips the application typecheck, which is nearly all of the cost.')}
+
+${color.bold('check flags:')}
+  --runtime       also drive the lagoon in a browser (mount, data-flow, viewports, axe, live wiring)
+  --verbose       name each runtime step as it runs, with what it cost
+  --json          machine-readable verdict: islands, regions, removal
+  ${color.dim('motu check runs MOTU\'s gates only. Your typecheck/linter are yours: `<host build> && motu check`.')}
+
+${color.bold('verify flags:')}
+  --all           every island / every region, one after another; one line each, findings where there are any
+  --runtime       add the lagoon checks: mount, data-flow, viewports, axe, live wiring
+                  ${color.dim('opt-in: it drives a real browser per scenario × viewport. Static verify answers drift, which is the common question.')}
+  --verbose       name each runtime step as it runs, with what it cost
+  --fast          use the in-process happy-dom lagoon mount instead of the real browser (Playwright)
+  --standalone    the island is intentionally not in an archipelago (no membership warning)
+  --json          machine-readable report
+
+${color.bold('lagoon states:')}
+  ${color.dim('an island scenario and a region flow are ADDRESSES — open the lagoon directly on one:')}
+  ${color.dim('  /?target=island:x-week-actions&scenario=a%20week%20to%20answer')}
+  ${color.dim('  /?flow=marking%20a%20mission%20done&step=2')}
+  ${color.dim('  both against the gallery — the entry `serve` and `publish` build, and the one a person opens')}
+  --base <url>    print absolute URLs against a running lagoon instead of paths
+  --json          machine-readable catalogue
+  ${color.dim('a name that resolves to nothing REFUSES to render — it never falls back to the default state.')}
+
+${color.bold('lagoon try:')}
+  ${color.dim('explore a region before you know what to assert — the same verbs a flow has, nothing else:')}
+  ${color.dim("  motu lagoon try review 'click Accept' 'emit shot-list:shot-selected {\"island\":\"x\",\"shot\":\"a@desktop\"}'")}
+  in <world> · seed <key>=<json> · look · click <name> · emit <slot>:<event> [json] · provide <key>=<json>
+  shows <slot>: <text> · hides <slot>: <text> · holds <key>=<json>   ${color.dim('assertions — yours, never copied from the output')}
+  --world <id>    run in a declared world        --shot <dir>   a PNG per step
+  --keep <name>   append it to <id>.evidence.ts — only with assertions, only if they all held
+  --json          machine-readable
+
+${color.bold('lagoon serve flags:')}
+  --port <n>      port to listen on (default 8817)
+  --host          also serve on your LAN, to open it on a phone on the same wifi
+  --no-build      serve the last published artifact instead of rebuilding
+  --watch         rebuild on every source change and live-reload open viewers (phones included)
+  --live-url <url>  the address the HOST should fetch this from, when it is not on this machine
+  --live-push     send the built page to the host after every save, instead of being fetched
+  --single        build one self-contained page instead of chunks (rebuilds and pushes send it whole)
+  ${color.dim('takes the same target/--fit flags as publish. Ctrl-C to stop.')}
+  ${color.dim('--live-url needs --host, and the host must ALLOW the name (MOTU_LIVE_ALLOW there):')}
+  ${color.dim('  motu lagoon serve --watch --host --live-url http://192.168.1.20:8901')}
+  ${color.dim('the address is whatever the HOST can reach: a LAN IP, a tailnet peer, a tunnel. An')}
+  ${color.dim('ingress/funnel name usually is NOT — those publish one port, and not this one.')}
+  ${color.dim('--live-push needs nothing to reach you at all: each save uploads the chunks it changed')}
+  ${color.dim('and the manifest, and the host serves them. Use it when there is no route back to you.')}
+
+${color.bold('lagoon publish flags:')}
+  --archipelago <id>   publish one archipelago instead of an island
+  --fit <native|legacy>  legacy-fit strategy for a single-island target
+  --out <path>         write somewhere other than .motu/publish/ (keep it stable to keep one URL)
+  --title <text>       name this lagoon in the host's listing (default: derived from the target)
+  --remote [url]       upload it to a lagoon host (or $MOTU_HOST_URL) as chunks, and print the URLs —
+                       only the chunks the host does not already have are sent
+  --single             with --remote: upload one self-contained page instead (a host without chunks)
+  --token <secret>     the host's upload token (or $MOTU_HOST_TOKEN)
+  --json          machine-readable report
+  ${color.dim('no target => every archipelago, with the switcher. Always mock-backed: an artifact has no backend.')}
+
+${color.bold('island create flags:')}
+  --from <specifier>   wrap a component the application already owns instead of scaffolding one under
+                       ui/ — the React-host case, where copying it would fork it. Use the specifier
+                       the app itself uses (an alias like @/components/foo, or a relative path).
+  --export <name>      the component's name INSIDE that module, when it is not the island's Pascal name
+  --force              overwrite an existing scaffolded component
+
+${color.bold('island snapshot flags:')}
+  --update             record baselines as FILES beside the evidence (the in-repo model)
+  --remote [url]       compare against the host's ACCEPTED baseline; nothing is written to git
+  --accept [name]      move the accepted pointer to what was last rendered
+  --changed [base]     only islands/regions this branch touched — widens back to everything, loudly,
+                       when a changed file belongs to no single one
+  ${color.dim('a page, a screen, an app-side source, the lagoon map or a shared evidence module belongs to no')}
+  ${color.dim('island, so a real session usually widens. To check ONE region while you work, name it:')}
+  ${color.dim('  motu archipelago verify <id> --runtime   ·   motu island verify <name> --runtime')}
+  --json          machine-readable report
+
+${color.bold('integrate flags:')}
+  --archipelago <id>   (required) target archipelago id
+  --slot <slot>        marker slot name (defaults to the island's kebab name)
+
+${color.bold('skills install flags:')}
+  --only <both|claude|copilot>   which agent format(s) to write (default: both)
+  --force         overwrite files that already exist with different contents
+  --json          machine-readable report
+
+${color.bold('create flags:')}
+  --force         overwrite existing files
+`;
+
+async function main() {
+  // RESTORE THE NO-INSTALL LINKS FIRST, on every run.
+  //
+  // `motu init` symlinks node_modules/@motujs/* into the checkout, which is what lets a project depend
+  // on nothing. `npm install` then deletes them as extraneous — measured on an Angular app, where the
+  // next build failed with `Cannot find module '@motujs/react'`, an error pointing nowhere near the
+  // cause. (bun and pnpm left them alone, so this is invisible on the machines motu grew up on.)
+  // Re-linking is a handful of existsSync calls and makes the mechanism survive the host's package
+  // manager instead of losing to it.
+  try {
+    ensureNoInstallLinks(REPO_ROOT, MOTU_CHECKOUT);
+  } catch {
+    // Not a motu project, or a read-only checkout — the commands that need the links say so themselves.
+  }
+  const [, , group, sub, ...rest] = process.argv;
+  const argv = parse(rest);
+
+  if (!group || group === '--help' || group === '-h' || group === 'help') {
+    console.log(USAGE);
+    process.exit(group ? 0 : 1);
+  }
+
+  // `--help` ON A SUBCOMMAND. It used to be parsed as an ordinary flag, so `motu island create --help`
+  // reached the command with no positional, printed its usage line, and exited 2 — the code that means
+  // "a check could not run, retry, do NOT repair". Asking for help is neither a failure nor an
+  // environment problem, and this was the FIRST command two cold-start agents typed for each verb.
+  // Handled once, here, so every subcommand answers the same way instead of each remembering to.
+  // `sub` IS CHECKED TOO, and leaving it out was worse than the bug it was fixing. On a top-level verb
+  // (`motu init --help`) the flag lands in `sub`, not in `rest`, so `argv.help` was false, dispatch
+  // fell through, and `init` treated the missing positional as "." — `motu init --help` SCAFFOLDED
+  // MOTU INTO THE CURRENT DIRECTORY and exited 0. Found by a cold-start agent typing it in its repo,
+  // where the existing config refused the overwrite and only an exit 1 showed; reproduced in an empty
+  // directory, where it silently created a project.
+  const askedForHelp = ['--help', '-h', 'help'].includes(sub) || argv.help || rest.includes('-h');
+  if (askedForHelp) {
+    console.log(USAGE);
+    console.log(color.dim(`\n(\`motu ${group}${sub ? ' ' + sub : ''}\` — see the usage block above; each command also prints its own usage when required arguments are missing.)`));
+    process.exit(0);
+  }
+
+  if (group === 'init') {
+    // Top-level verb: sub is an optional target dir positional.
+    return initCommand(parse([sub, ...rest].filter((x) => x !== undefined)));
+  }
+
+  // AM I EVEN IN A PROJECT? Asked once, here, after the verbs that legitimately run outside one:
+  // `init` creates the config, `skills install` copies agent skills into a repo motu has not touched,
+  // and `link` repairs a package.json the package manager stripped. Every other verb reads a layout,
+  // and reading the WRONG layout is silent — an empty islands glob is not an error, it is a check
+  // that examined nothing and passed. See `assertProject`.
+  if (!['skills', 'link'].includes(group)) assertProject(loadMotuConfig(), { color });
+
+  // `motu link` — record @motujs/* in package.json so the package manager stops deleting them.
+  // `--check` asserts instead of writing, which is the CI half of the same question.
+  if (group === 'sync') return syncCommand(parse([sub, ...rest].filter((x) => x !== undefined)));
+
+  if (group === 'link') {
+    const { linkCommand } = await import('./commands/link.mjs');
+    return linkCommand(parse([sub, ...rest].filter((x) => x !== undefined)));
+  }
+
+  // The last mile, and its own verb because it asks about the HOST, not about motu's files:
+  // `motu integrate check [region]`.
+  if (group === 'integrate') {
+    // `rest` is already everything after the sub-verb, so the region positional is argv._[0].
+    if (sub === 'check') return integrateCheckCommand(argv);
+    console.error(color.red(`unknown: motu integrate ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'island') {
+    if (sub === 'create') return createCommand(argv);
+    if (sub === 'verify') return verifyCommand(argv);
+    if (sub === 'snapshot') return snapshotCommand(argv);
+    if (sub === 'defaults') return islandDefaultsCommand(argv);
+    // The two halves of what is now `motu sync`. Kept answering, because every generated file in an
+    // adopting repo carried "run `motu island sync`" in its header until it was regenerated.
+    if (sub === 'sync') return syncCommand(argv);
+    if (sub === 'integrate') return integrateCommand(argv);
+    console.error(color.red(`unknown: motu island ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'archipelago') {
+    // `snapshot` takes an id positional, so re-parse with `rest` shifted.
+    if (sub === 'snapshot') return archipelagoSnapshotCommand(parse(rest));
+    if (sub === 'create') {
+      console.error(color.red('`motu archipelago create` is now `motu archipelago init <id>`') + color.dim(' — add --page <file> when the region has a page'));
+      process.exit(1);
+    }
+    // Everything a page needs before its FIRST island — the step that makes adoption feel expensive.
+    if (sub === 'init') return archipelagoInitCommand(argv);
+    // What the region DOES, against what it previews. The only check here that compares motu to
+    // reality rather than to a declaration — see the command's own header.
+    if (sub === 'coverage') return regionCoverageCommand(argv);
+    // The migration `region-root` points at: derive `root` + `slots` from the frame, hand back the rest.
+    if (sub === 'adopt-root') return archipelagoAdoptRootCommand(parse(rest));
+    if (sub === 'verify') return archipelagoVerifyCommand(argv);
+    if (sub === 'sync') return syncCommand(argv);
+    console.error(color.red(`unknown: motu archipelago ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'fixtures') {
+    if (sub === 'record') return fixturesRecordCommand(argv);
+    console.error(color.red(`unknown: motu fixtures ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'skills') {
+    // `install` takes an optional target-dir positional, so re-parse with `rest` shifted.
+    if (sub === 'install') return skillsInstallCommand(parse(rest));
+    if (sub === 'list') return skillsListCommand(argv);
+    console.error(color.red(`unknown: motu skills ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'lagoon') {
+    // REMOVED, and said so with the replacement rather than as an unknown verb: two servers for one
+    // loop was one too many, and `serve --watch` is the one that builds what `publish` ships.
+    if (sub === 'dev') {
+      console.error(color.red('`motu lagoon dev` is gone — use `motu lagoon serve --watch`') + color.dim(' (--detach / --stop / --no-live / --as carry over)'));
+      process.exit(1);
+    }
+    if (sub === 'states') return lagoonStatesCommand(argv);
+    if (sub === 'try') return lagoonTryCommand(argv);
+    if (sub === 'eject') return lagoonEjectCommand(argv);
+    if (sub === 'publish') return lagoonPublishCommand(argv);
+    if (sub === 'serve') return lagoonServeCommand(argv);
+    console.error(color.red(`unknown: motu lagoon ${sub ?? ''}`));
+    console.log(USAGE);
+    process.exit(2);
+  }
+
+  if (group === 'assurance') {
+    process.exit(assuranceCommand(parse([sub, ...rest].filter(Boolean))) ?? 0);
+  }
+  if (group === 'diff') {
+    const code = await diffCommand(parse([sub, ...rest].filter(Boolean)));
+    process.exit(code ?? 0);
+  }
+  // INTERNAL: one side of `motu diff` (it runs this in a base worktree, then here).
+  if (group === 'flows' && sub === 'trace') {
+    const code = await flowsTraceCommand(argv);
+    process.exit(code ?? 0);
+  }
+
+  if (group === 'screen') {
+    if (sub === 'verify') {
+      const code = await screenVerifyCommand(parse(rest));
+      await closeLagoonPool().catch(() => {});
+      process.exit(code ?? 0);
+    }
+    console.error(color.red(`unknown: motu screen ${sub ?? ''}`) + color.dim(' — verify [id]'));
+    process.exit(2);
+  }
+
+  if (group === 'coverage') {
+    const code = await coverageCommand(sub, argv);
+    process.exit(code ?? 0);
+  }
+
+  // Single-word verbs: their flags land in `sub`, since `argv` is parsed from what follows it.
+  if (group === 'removal-check') return removalCheckCommand(parse([sub, ...rest].filter(Boolean)));
+
+  if (group === 'check') return checkCommand(parse([sub, ...rest].filter(Boolean)));
+
+  if (group === 'codegen') {
+    // Top-level verb: sub + rest are positional args ([manifest, outDir]).
+    return codegenCommand(parse([sub, ...rest].filter((x) => x !== undefined)));
+  }
+
+  console.error(color.red(`unknown command: motu ${group}`));
+  console.log(USAGE);
+  process.exit(2);
+}
+
+main().catch((err) => {
+  console.error(color.red(err?.stack || String(err)));
+  process.exit(1);
+});

package/src/runtime-harness.mjs

@@ -0,0 +1,225 @@
+// Runtime lagoon check, run in-process under happy-dom (no browser download, no vite). It mounts ONE
+// island by tag against MockTransport fixtures and reports whether it produced a non-empty shadow DOM.
+// Run via `node --import tsx runtime-harness.mjs <tag> <fixturesPath> <fit> [mode]`; prints a single
+// JSON line. mode 'mount' (default) = the render/remount check; mode 'differentiate' = mount once per
+// declared `scenario` seed and report whether distinct inputs produced distinct output (data-flow).
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+import * as React from 'react';
+import { stringifyEvidence } from './lib/evidence-json.mjs';
+import { installIslandRender } from './lib/island-render.mjs';
+import { judgeRenders } from './lib/data-flow.mjs';
+
+/**
+ * GENERATED IDS ARE MEANT TO DIFFER between mounts. React's `useId` counter is module state and Radix
+ * builds `aria-controls` from it, so comparing raw HTML across two mounts compares a counter: the
+ * browser reloads and the counter resets (pass), node reuses the registry (fail). Neither was testing
+ * what `remount-stable` claims, and the failure it printed — "likely accidental module-level state" —
+ * named the one thing that was not the cause.
+ */
+function withoutGeneratedIds(html) {
+  return String(html)
+    .replace(/(_r_|:r|«r)[0-9a-z]+(_|:|»)/gi, '<id>')
+    .replace(/\bradix-[\w:-]+/gi, 'radix-<id>');
+}
+
+async function main() {
+  const [, , tag, fixturesPath, fit = 'native', mode = 'mount'] = process.argv;
+
+  // 'scenarios' mode: print the fixtures' declared scenarios as JSON and exit BEFORE importing the DOM
+  // or the element registry (which may pull in vite-only `?raw` imports). Lets the plain-node verify
+  // CLI read scenarios without a happy-dom mount.
+  if (mode === 'scenarios') {
+    let scenarios = [];
+    if (fixturesPath) {
+      try {
+        const mod = await import(fixturesPath);
+        scenarios = mod.scenarios ?? [];
+      } catch (err) {
+        process.stderr.write(`harness: could not load scenarios ${fixturesPath}: ${err?.message}\n`);
+      }
+    }
+    // stringifyEvidence, not JSON.stringify: a Date in a seed has to reach the CLI as a Date.
+    // See lib/evidence-json.mjs — this hop silently flattened them for as long as it existed.
+    process.stdout.write(stringifyEvidence({ scenarios }) + '\n');
+    process.exit(0);
+  }
+
+  // 'catalogue' mode: resolve a catalogue region's declared members against the app's own capture.
+  // Runs here rather than in the CLI for one reason: `@motujs/core` is TS source, so `checkCatalogue`
+  // is importable under tsx and nowhere else — and a second copy of that set arithmetic in the CLI
+  // would drift from the one the framework actually ships.
+  if (mode === 'catalogue') {
+    const declared = JSON.parse(process.env.MOTU_CATALOGUE_DECLARED ?? '[]');
+    try {
+      const { capture } = await import(fixturesPath);
+      if (!capture) {
+        process.stdout.write(JSON.stringify({ error: 'no `capture` export' }) + '\n');
+        process.exit(0);
+      }
+      const { checkCatalogue } = await import('@motujs/core');
+      const present = (typeof capture.present === 'function' ? capture.present() : capture.present) ?? [];
+      const universe = typeof capture.universe === 'function' ? capture.universe() : capture.universe;
+      process.stdout.write(JSON.stringify({ report: checkCatalogue({ declared, universe, present }), present: present.length }) + '\n');
+    } catch (err) {
+      process.stdout.write(JSON.stringify({ error: err?.message ?? String(err) }) + '\n');
+    }
+    process.exit(0);
+  }
+
+  GlobalRegistrator.register();
+  // The islands rely on the JSX transform and never `import React`. tsx/esbuild compiles the classic
+  // runtime (React.createElement) here, so expose React as a free global for the island modules.
+  globalThis.React = React;
+
+  // Diagnostics: any console.error the island emits (incl. React warnings) or unhandled rejection.
+  const diagnostics = [];
+  const realConsoleError = console.error.bind(console);
+  console.error = (...args) => {
+    diagnostics.push('console.error: ' + args.map((a) => (a instanceof Error ? a.message : String(a))).join(' '));
+  };
+  process.on('unhandledRejection', (reason) => {
+    diagnostics.push('unhandledrejection: ' + String(reason instanceof Error ? reason.stack || reason.message : reason));
+  });
+
+  // Imported AFTER the DOM globals exist so custom elements / shadow roots / constructable stylesheets
+  // resolve against happy-dom.
+  const { configure } = await import('@motujs/runtime');
+  const { MockTransport } = await import('@motujs/runtime/mock');
+  const { defineLagoon } = await import('@motujs/react');
+  // Import the app barrel by resolved path (from motu.config.json), not by a hardcoded package name,
+  // so the harness works for any project layout.
+  const { pathToFileURL } = await import('node:url');
+  const { paths } = await import('./lib/util.mjs');
+  const { ELEMENT_REGISTRY } = await import(pathToFileURL(paths.barrel).href);
+
+  let fixtures = [];
+  let roles = [];
+  let scenarios = [];
+  if (fixturesPath) {
+    try {
+      const mod = await import(fixturesPath);
+      fixtures = mod.fixtures ?? [];
+      roles = mod.roles ?? [];
+      scenarios = mod.scenarios ?? [];
+    } catch (err) {
+      // Missing/broken fixtures shouldn't crash the mount; the default render doesn't need them.
+      process.stderr.write(`harness: could not load fixtures ${fixturesPath}: ${err?.message}\n`);
+    }
+  }
+
+  configure(new MockTransport(fixtures, roles));
+
+  const mountOne = (seed = { criteria: {} }) => {
+    const node = defineLagoon({ kind: 'island', tag, fit }, { elements: ELEMENT_REGISTRY, seed });
+    document.body.appendChild(node);
+    return node;
+  };
+
+  // The lagoon wraps every island target in a one-island <motu-archipelago> that owns the shadow
+  // boundary; the island renders LIGHT inside it, so pierce the archipelago shadow to find the tag and
+  // read its light DOM (a standalone island would instead have its own shadowRoot).
+  const findIsland = () => {
+    let node = document.querySelector(tag);
+    if (!node) {
+      for (const arch of document.querySelectorAll('motu-archipelago')) {
+        const hit = arch.shadowRoot && arch.shadowRoot.querySelector(tag);
+        if (hit) {
+          node = hit;
+          break;
+        }
+      }
+    }
+    return node;
+  };
+  // The same reading of "what the island rendered" as the browser lane: its own DOM plus what its own
+  // mount portaled to <body> (lib/island-render.mjs) — so `--fast` and the browser agree on a dialog.
+  installIslandRender(window);
+  const rendered = (node) => window.__motuRendered(node);
+
+  // DIFFERENTIATION mode: mount once per declared scenario seed and diff the rendered output. Distinct
+  // inputs producing distinct output prove data flows criteria -> contract -> render (not just wiring).
+  if (mode === 'differentiate') {
+    const result = { differentiates: null, scenarioCount: scenarios.length, diagnostics };
+    if (scenarios.length >= 2) {
+      const outputs = [];
+      const portals = [];
+      for (const scenario of scenarios) {
+        document.body.innerHTML = '';
+        const mounted = mountOne(scenario.seed ?? {});
+        await new Promise((r) => setTimeout(r, 80));
+        // `afterMount`: provided once the island is up, as the browser lane does.
+        if (scenario.afterMount && typeof mounted?.provide === 'function') {
+          for (const [k, v] of Object.entries(scenario.afterMount)) mounted.provide(k, v);
+          await new Promise((r) => setTimeout(r, 80));
+        }
+        const island = findIsland();
+        outputs.push(rendered(island));
+        portals.push(island ? window.__motuPortals(island).length : 0);
+      }
+      result.portals = portals;
+      // The same judgement as the browser lane (lib/data-flow.mjs): every scenario rendered something
+      // or DECLARED it would not (`blank`), and not every output is identical.
+      Object.assign(result, judgeRenders(outputs, scenarios));
+      // WHICH scenarios collide, not just whether any two do. `size > 1` passes a set where two of
+      // three render identically, while the report says "distinct inputs produce distinct output" —
+      // claiming more than it tested, and leaving one scenario that is fake evidence by the project's
+      // own definition. Named here so the caller can say so.
+      result.distinctOutputs = new Set(outputs).size;
+    }
+    console.error = realConsoleError;
+    process.stdout.write(JSON.stringify(result) + '\n');
+    process.exit(0);
+  }
+
+  const el = mountOne();
+
+  // Let the custom-element upgrade + React render flush.
+  await new Promise((r) => setTimeout(r, 60));
+
+  const island = findIsland();
+  const renderedHtml = rendered(island);
+  const ok = Boolean(island) && renderedHtml.trim().length > 0;
+
+  // Re-mount identical: dispose this element and mount a fresh one, diff the rendered output.
+  //
+  // BOTH RENDERS MUST BE SETTLED, or this compares a finished render against a half-finished one. The
+  // first mount had 60ms plus whatever the module graph took; the second got a flat 60ms, so any
+  // island that loads asynchronously "changed on remount" — reported as accidental module-level state,
+  // which is a specific and alarming accusation to make on a timing artefact.
+  let remountIdentical = null;
+  if (ok) {
+    document.body.removeChild(el); // disconnectedCallback -> __motuDispose
+    mountOne();
+    let previous = null;
+    let stable = 0;
+    const deadline = Date.now() + 2000;
+    for (;;) {
+      await new Promise((r) => setTimeout(r, 60));
+      const now = rendered(findIsland());
+      stable = now === previous ? stable + 1 : 0;
+      previous = now;
+      if (stable >= 2 || Date.now() > deadline) break;
+    }
+    remountIdentical = withoutGeneratedIds(previous) === withoutGeneratedIds(renderedHtml);
+  }
+
+  console.error = realConsoleError;
+
+  process.stdout.write(
+    JSON.stringify({
+      ok,
+      fit,
+      mounted: Boolean(island),
+      shadowLength: renderedHtml.length,
+      diagnostics,
+      remountIdentical,
+      portals: island ? window.__motuPortals(island).length : 0,
+    }) + '\n',
+  );
+  process.exit(0);
+}
+
+main().catch((err) => {
+  process.stderr.write(`harness-fatal: ${err?.stack || err}\n`);
+  process.exit(3);
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.