@motujs/cli 0.0.0-stage → 0.1.0

package/src/commands/fixtures.mjs

@@ -0,0 +1,153 @@
+// `motu fixtures record <island>` — capture real (or mock) backend responses into request-keyed
+// fixtures. It boots the focused lagoon, drives the island's declared `scenarios` through the
+// archipelago boundary, and records each contract call's request + response at the `call()` seam.
+// With `--transport http` it records the REAL backend (the point of it); default records the mock
+// (a self-consistency check of the pipeline). This closes the "fixtures are hand-written / can't
+// capture semantic fidelity" gap — the recorder replays real truth, keyed by request, without
+// reimplementing any backend logic.
+import { parseEvidence } from '../lib/evidence-json.mjs';
+import { existsSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { paths, names, color } from '../lib/util.mjs';
+import { recordLagoon } from '../playwright-lagoon.mjs';
+import { scenarioInputs } from '../lib/data-flow.mjs';
+import { CHROMIUM_INSTALL } from '../lib/framework.mjs';
+
+const HARNESS = resolve(dirname(fileURLToPath(import.meta.url)), '../runtime-harness.mjs');
+const CLI_PKG = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** Read the island's declared `scenarios` via the harness (loads only the fixtures file). */
+function readScenarios(fixturesPath) {
+  if (!fixturesPath || !existsSync(fixturesPath)) return [];
+  const args = ['--import', 'tsx', HARNESS, '', fixturesPath, 'native', 'scenarios'];
+  const res = spawnSync(process.execPath, args, { encoding: 'utf8', cwd: CLI_PKG });
+  if (res.status !== 0) return [];
+  const line = (res.stdout || '').trim().split('\n').filter(Boolean).pop();
+  // See lib/evidence-json.mjs — the harness marks Dates so they survive this hop.
+  return parseEvidence(line)?.scenarios ?? [];
+}
+
+/** Stable JSON (sorted object keys) for dedup keys. */
+function stable(v) {
+  return JSON.stringify(v, (_k, val) =>
+    val && typeof val === 'object' && !Array.isArray(val)
+      ? Object.fromEntries(Object.keys(val).sort().map((k) => [k, val[k]]))
+      : val,
+  );
+}
+
+export async function fixturesRecordCommand(argv) {
+  const name = argv._[0];
+  if (!name) {
+    console.error('usage: motu fixtures record <island> [--transport http|mock] [--out <path>]');
+    process.exit(2);
+  }
+  const { kebab, tag } = names(name);
+  const fixturesPath = paths.fixturesFile(kebab);
+  const scenarios = readScenarios(fixturesPath);
+  if (scenarios.length === 0) {
+    console.error(color.red(`✗ ${kebab} declares no \`scenarios\` in fixtures.mock.ts — add at least one { seed } to record against.`));
+    process.exit(1);
+  }
+
+  const transport = argv.transport === 'http' ? 'http' : undefined; // default: mock
+  console.log(color.dim(`recording ${tag} against the ${transport ?? 'mock'} transport over ${scenarios.length} scenario(s)…`));
+  const port = 5400 + Math.floor(Math.random() * 300);
+
+  let result;
+  try {
+    result = await recordLagoon({ tag, port, scenarios, transport });
+  } catch (err) {
+    const msg = String(err?.message || err).split('\n')[0];
+    if (/Executable doesn't exist|playwright install/i.test(msg)) {
+      console.error(color.red(`✗ Chromium not installed — run ${CHROMIUM_INSTALL}`));
+    } else {
+      console.error(color.red(`✗ recording failed: ${msg}`));
+    }
+    process.exit(1);
+  }
+  if (!result.mounted) {
+    console.error(color.red('✗ island did not mount — nothing recorded'));
+    process.exit(1);
+  }
+
+  // Dedupe captured calls by (service, method, args).
+  const seen = new Set();
+  const unique = [];
+  for (const c of result.calls) {
+    const key = `${c.service}.${c.method}(${stable(c.args)})`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(c);
+  }
+
+  // Reduce host-fed store writes (channels + provide) to a last-wins seed, MINUS the keys the
+  // scenarios themselves drove (those are inputs, not host config).
+  const scenarioKeys = new Set(scenarios.flatMap((s) => Object.keys(scenarioInputs(s))));
+  const seed = {};
+  for (const w of result.seedWrites ?? []) {
+    if (scenarioKeys.has(w.key)) continue;
+    seed[w.key] = w.value;
+  }
+  const seedKeys = Object.keys(seed);
+
+  if (unique.length === 0 && seedKeys.length === 0) {
+    console.error(color.red('✗ nothing captured — no contract calls and no host-fed store writes'));
+    process.exit(1);
+  }
+
+  const outPath = argv.out ? resolve(process.cwd(), argv.out) : resolve(paths.islandDir(kebab), 'fixtures.recorded.ts');
+  writeFileSync(outPath, renderFixtures(kebab, unique, seed, transport));
+  console.log(color.green(`✓ wrote ${unique.length} fixture(s)${seedKeys.length ? ` + ${seedKeys.length} seed key(s)` : ''}`) + color.dim(` -> ${outPath}`));
+  for (const c of unique) {
+    console.log('  ' + color.dim(`${c.service}.${c.method}  match=${stable(c.args)}${c.status ? `  (status ${c.status})` : ''}`));
+  }
+  for (const k of seedKeys) console.log('  ' + color.dim(`seed.${k} = ${preview(seed[k])}`));
+  console.log(color.dim('\nReview, then merge into fixtures.mock.ts (fixtures) and the lagoon seed (seed) to replay this session offline.'));
+}
+
+/** A short one-line preview of a captured value. */
+function preview(v) {
+  try {
+    const s = JSON.stringify(v);
+    return s && s.length > 60 ? s.slice(0, 57) + '…' : String(s);
+  } catch {
+    return String(v);
+  }
+}
+
+function renderFixtures(kebab, calls, seed, transport) {
+  const rows = calls.map((c) => {
+    const match = JSON.stringify(c.args);
+    // A CAPTURED FAILURE IS A FIXTURE NOW. This emitted the status as a commented line with
+    // `response: null`, because `Fixture` could not express a failing call — so recording a real 500
+    // through `--transport http` produced something nobody could run. `FixtureFailure` is the form it
+    // was reaching for.
+    if (c.status) {
+      return `  { service: ${JSON.stringify(c.service)}, method: ${JSON.stringify(c.method)}, match: ${match}, status: ${c.status} },`;
+    }
+    const response = indent(JSON.stringify(c.response, null, 2), 4);
+    return `  { service: ${JSON.stringify(c.service)}, method: ${JSON.stringify(c.method)}, match: ${match}, response: ${response} },`;
+  });
+  const seedBlock =
+    Object.keys(seed).length > 0
+      ? `\n// Host-fed store values (channels + provide) captured this session — pass as the lagoon seed so\n// the island receives REAL host config offline, not a hand-written stub.\nexport const seed: Record<string, unknown> = ${indent(JSON.stringify(seed, null, 2), 0)};\n`
+      : '';
+  return `// RECORDED fixtures for x-${kebab} — captured from the ${transport ?? 'mock'} transport by \`motu fixtures record\`.
+// Request-keyed (\`match\` = the exact call args). Merge the ones you want into fixtures.mock.ts.
+import type { Fixture } from '@motujs/runtime/mock';
+
+export const fixtures: Fixture[] = [
+${rows.join('\n')}
+];
+${seedBlock}`;
+}
+
+/** Re-indent a multi-line JSON blob so nested lines align under the fixture row. */
+function indent(json, spaces) {
+  if (json == null) return 'null';
+  const pad = ' '.repeat(spaces);
+  return json.split('\n').map((l, i) => (i === 0 ? l : pad + l)).join('\n');
+}

package/src/commands/init.mjs

@@ -0,0 +1,473 @@
+// `motu init [dir]` — bootstrap a project so `motu island create` / `verify` work immediately.
+//
+// It writes motu.config.json (the layout declaration the rest of the CLI reads), the semantic roots +
+// registries + barrel that islands slot into, AND the lagoon root. That last part is the point: the
+// lagoon is where `motu island verify` closes the loop, so a project scaffolded without one gets the
+// static checks and none of the verification. Init used to stop before it, on the grounds that a
+// composition root is "a project concern" — but the result was a documented happy path (init ->
+// island create -> island verify) that could not reach green without hand-porting the demo app.
+//
+// `--host` picks the stack the islands embed INTO, which decides what the lagoon has to speak:
+//   angularjs  the reference ocean — legacy fit gates apply, AngularJS adapter available
+//   next       a Next.js app — the lagoon inherits the host's '@/…' alias + Tailwind, stubs next/*
+//   none       plain React — nothing host-specific
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative, resolve } from 'node:path';
+import { color } from '../lib/util.mjs';
+import { applyHostRules } from '../lib/host-rules.mjs';
+import { installSkills } from './skills.mjs';
+import { CLI_VERSION, INSTALLED } from '../lib/framework.mjs';
+import {
+  render,
+  ISLANDS_REGISTRY,
+  ARCHIPELAGOS_REGISTRY,
+  BARREL,
+  APP_PACKAGE_JSON,
+  SHARED_STYLES,
+  GITIGNORE,
+  LAGOON_PACKAGE_JSON,
+  LAGOON_INDEX_HTML,
+  LAGOON_FOCUS_HTML,
+  LAGOON_FIXTURES,
+  LAGOON_FOCUS_ENTRY,
+  LAGOON_GALLERY_ENTRY,
+  LAGOON_CONFIG,
+  LAGOON_CHROME_SHADCN,
+  LAGOON_OVERRIDES,
+  NEXT_STUBS,
+  ENV_SHIM,
+  NEXT_VITE_IMPORTS,
+  NEXT_VITE_ALIASES,
+  NEXT_VITE_CSS,
+  NEXT_TAILWIND_CONFIG,
+} from '../lib/scaffold.mjs';
+
+/** What a host's Tailwind config can be called. Mirrors @motujs/adapter-next's own list. */
+const TAILWIND_CONFIGS = ['tailwind.config.ts', 'tailwind.config.js', 'tailwind.config.mjs', 'tailwind.config.cjs'];
+
+/** Framework entry points, mapped by module specifier — @motujs/* are raw TS with no build step. */
+const MOTU_ENTRIES = {
+  // The ONE motu module application code may import — types only, so it erases at compile time and
+  // the app still ships byte-identical output without motu.
+  '@motujs/types': 'packages/types/src/index.ts',
+  '@motujs/core': 'packages/core/src/index.ts',
+  '@motujs/react': 'packages/react/src/index.ts',
+  '@motujs/react/define': 'packages/react/src/defineReactElement.ts',
+  '@motujs/runtime/mock': 'packages/runtime/src/mock.ts',
+  '@motujs/runtime': 'packages/runtime/src/index.ts',
+  '@motujs/debug-overlay': 'packages/debug-overlay/src/index.ts',
+};
+
+const HOST_ADAPTER_ENTRY = {
+  angularjs: ['@motujs/adapter-angularjs', 'packages/adapters/angularjs/src/index.ts'],
+  next: ['@motujs/adapter-next', 'packages/adapters/next/src/index.ts'],
+};
+
+/**
+ * Vite aliases resolving the framework straight to THIS checkout's sources.
+ *
+ * The @motujs/* packages are unpublished workspace packages whose entry point is raw TypeScript, so an
+ * existing project cannot simply depend on them — that is the single thing that blocks adopting motu
+ * outside its own repo. The lagoon is a Vite app and transpiles TS anyway, so pointing it at the
+ * sources removes the package-manager problem entirely: `motu init` produces a lagoon that boots with
+ * no install step. Longest specifier first, so '@motujs/runtime/mock' is not eaten by '@motujs/runtime'.
+ */
+/** Escape a module specifier for use inside a RegExp literal. */
+function reEscape(spec) {
+  return spec.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+}
+
+/** An anchored, exact-match alias pattern for one module specifier. */
+function exact(spec) {
+  return `/^${reEscape(spec)}$/`;
+}
+
+function motuAliases(lagoonDir, appRoot, appPackage, host) {
+  const entries = Object.entries(MOTU_ENTRIES);
+  const adapter = HOST_ADAPTER_ENTRY[host];
+  if (adapter) entries.push([adapter[0], adapter[1]]);
+  const lines = entries.map(([spec, rel]) => `      { find: ${exact(spec)}, replacement: motu('${rel}') },`);
+  // The project's own barrel + stylesheet, imported by name so generated code never carries a
+  // relative path into the app. The stylesheet pattern is intentionally NOT end-anchored: it is
+  // imported as '<pkg>/styles.css?inline', and the query has to survive the rewrite.
+  lines.push(
+    `      { find: /^${reEscape(appPackage)}\\/styles\\.css/, replacement: resolve(__dirname, '${relPosix(lagoonDir, resolve(appRoot, 'src/shared/styles.css'))}') },`,
+  );
+  lines.push(
+    `      { find: ${exact(appPackage)}, replacement: resolve(__dirname, '${relPosix(lagoonDir, resolve(appRoot, 'src/index.ts'))}') },`,
+  );
+  return lines.join('\n') + '\n';
+}
+
+/** Where a Next/React app conventionally keeps the global stylesheet Tailwind is pulled in through. */
+const HOST_GLOBAL_CSS = ['app/globals.css', 'src/app/globals.css', 'styles/globals.css', 'src/styles/globals.css'];
+
+/** `import '<host globals.css>';` for the lagoon entries, or '' when the host has no such file. */
+function hostGlobalCssImport(lagoonDir, hostRoot) {
+  for (const rel of HOST_GLOBAL_CSS) {
+    const abs = resolve(hostRoot, rel);
+    if (existsSync(abs)) return `import '${relPosix(resolve(lagoonDir, 'src'), abs)}';\n`;
+  }
+  return '';
+}
+
+// 'vite' was supported everywhere EXCEPT here: the adapter exists (packages/adapters/vite/vite.mjs),
+// `hostContribution` resolves it, `loadMotuConfig` accepts it, and Twenty runs on it — but the one
+// command that starts a project rejected it, so the only way onto a vite host was to hand-write
+// motu.config.json. Found on the first greenfield init after adoption stopped needing a checkout path.
+const HOSTS = new Set(['angularjs', 'next', 'none', 'vite']);
+
+/** Hosts with a legacy skin an island must be proven to survive (mirrors lib/config.mjs). */
+const LEGACY_FIT_HOSTS = new Set(['angularjs']);
+
+/** POSIX-style relative path for generated code (never a Windows backslash in a module specifier). */
+function relPosix(from, to) {
+  const r = relative(from, to).split('\\').join('/');
+  return r === '' ? '.' : r.startsWith('.') ? r : './' + r;
+}
+
+/**
+ * Say when the app's OWN package.json was kept and the `@motujs/*` block therefore never landed.
+ *
+ * `writeNew` is non-destructive per file, which is right — but it made the one file EVERY real
+ * adoption already has, `package.json`, silently skip the dependency block with it. The scaffold is
+ * written for a greenfield project; an existing app is the normal case, and there the block is not
+ * "kept", it is ABSENT. Measured on a cold adoption of a Next monorepo: no `@motujs/adapter-next`
+ * anywhere, `nextHostBridge` unresolvable, and `init` printed a green success line.
+ *
+ * A notice rather than a merge: editing an application's package.json is the host's call, and a
+ * printed block a human can paste is honest about which side owns the file.
+ */
+function keptPackageJsonNotice(appRoot, skipped, motuDependencies) {
+  // NO WORKSPACE TO SATISFY `@motujs/*` — say what DOES resolve them, because nothing else will.
+  //
+  // On a single-package project the dependency block is deliberately not written (a `workspace:*`
+  // range nothing can resolve breaks the next `npm install` outright). The consequence, measured on a
+  // cold adoption of an npm project: `motu init` changed ZERO lines of package.json, so the only
+  // record of motu's presence was raw symlinks in `node_modules/@motujs/*` — which a fresh
+  // `npm install` deletes, leaving nothing to say what was needed or why the build then fails.
+  // The CLI re-creates them on every invocation, so this is legibility, not breakage.
+  if (!motuDependencies) {
+    // THERE IS A FIX NOW, so this stops describing the hazard and names it.
+    //
+    // This used to end with "after `npm install` wipes them, any motu command puts them back", which
+    // is true and is not a fix: the person who runs `npm install` is usually not the person who runs
+    // a motu command next. Measured on shlink — `npm install` printed `removed 9 packages` and the
+    // host build then failed with `Cannot find module '@motujs/react'`, an error pointing nowhere near
+    // the cause. CI and a fresh clone hit it every time.
+    console.log(color.yellow('  ! nothing in package.json records @motujs/*, and `npm install` deletes them as extraneous.'));
+    console.log(color.dim('    Record them as `file:` paths, which npm creates itself and never prunes:'));
+    console.log('');
+    console.log('      motu link');
+    console.log('');
+    console.log(color.dim('    (`motu link --check` asserts it, for CI. A workspace project needs neither.)'));
+    console.log('');
+    return;
+  }
+  const pkgPath = resolve(appRoot, 'package.json');
+  if (!skipped.includes(pkgPath)) return;
+  let already = false;
+  try {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    already = Object.keys(pkg.dependencies ?? {}).some((d) => d.startsWith('@motujs/'));
+  } catch {}
+  if (already) return;
+  console.log(color.yellow('  ! package.json was kept, so the @motujs/* dependencies were NOT added.'));
+  console.log(color.dim('    The lagoon and tsconfig resolve @motujs/* without them, and the CLI links'));
+  console.log(color.dim("    node_modules/@motujs/* on every run — so this is not fatal. It matters when the"));
+  console.log(color.dim('    HOST bundler resolves them (a host adapter import). Add to its "dependencies":'));
+  console.log('');
+  for (const line of motuDependencies.split('\n').slice(1, -2)) console.log(color.dim('    ' + line.trim()));
+  console.log('');
+}
+
+/**
+ * Add the `@motujs/*` an installed project needs to its package.json, never touching one it already
+ * declares. Returns `"<field>: <name>@<range>"` for each line added.
+ *
+ * Runtime packages go in `dependencies` — islands ship in the app's bundle. `@motujs/debug-overlay` is
+ * only ever imported by the lagoon, so it is a devDependency, beside @motujs/cli itself.
+ */
+function recordInstalledDeps(pkgPath, range, host) {
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  } catch {
+    return [];
+  }
+  const adapter = host === 'angularjs' ? '@motujs/adapter-angularjs' : host === 'next' ? '@motujs/adapter-next' : null;
+  const wanted = {
+    dependencies: ['@motujs/core', '@motujs/react', '@motujs/runtime', ...(adapter ? [adapter] : [])],
+    devDependencies: ['@motujs/debug-overlay'],
+  };
+  const added = [];
+  for (const [field, names] of Object.entries(wanted)) {
+    for (const name of names) {
+      if (pkg.dependencies?.[name] || pkg.devDependencies?.[name] || pkg.peerDependencies?.[name]) continue;
+      (pkg[field] ??= {})[name] = range;
+      added.push(`${field}: ${name}@${range}`);
+    }
+  }
+  if (added.length) writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  return added;
+}
+
+function writeNew(path, contents, created, skipped) {
+  if (existsSync(path)) {
+    skipped.push(path);
+    return false;
+  }
+  mkdirSync(resolve(path, '..'), { recursive: true });
+  writeFileSync(path, contents);
+  created.push(path);
+  return true;
+}
+
+export async function initCommand(argv) {
+  const root = resolve(process.cwd(), argv._[0] ?? '.');
+  const host = argv.host === true || argv.host === undefined ? 'none' : String(argv.host);
+  if (!HOSTS.has(host)) {
+    console.error(color.red(`✗ unknown --host '${host}' — expected one of: ${[...HOSTS].join(', ')}`));
+    process.exit(2);
+  }
+
+  const configPath = resolve(root, 'motu.config.json');
+  if (existsSync(configPath) && !argv.force) {
+    console.error(color.red(`✗ ${basename(root)}/motu.config.json already exists — use --force to overwrite`));
+    process.exit(1);
+  }
+
+  // Layout. `app` is the sub-package holding islands/ui/archipelagos; `hostRoot` is where the host
+  // application lives (for `next`, the Next app whose aliases/Tailwind the lagoon borrows).
+  const appRel = argv.app ? String(argv.app) : '.';
+  const hostRel = argv.hostRoot ? String(argv.hostRoot) : appRel;
+  const appRoot = resolve(root, appRel);
+  const hostRoot = resolve(root, hostRel);
+  const lagoonRel = 'roots/lagoon';
+  const lagoonDir = resolve(appRoot, lagoonRel);
+  const appPackage = argv.appPackage ? String(argv.appPackage) : basename(appRoot) === '.' ? 'motu-app' : basename(appRoot);
+
+  // Islands mount directly in a React host — shadow DOM would cut them off from the host's own
+  // stylesheet (Tailwind included), which is the opposite of what a Next island wants.
+  const isolation = argv.isolation ? String(argv.isolation) : host === 'angularjs' ? 'shadow' : 'light';
+
+  const created = [];
+  const skipped = [];
+  mkdirSync(root, { recursive: true });
+
+  const config = {
+    app: appRel,
+    host,
+    hostRoot: hostRel,
+    islands: 'src/islands',
+    ui: 'src/ui',
+    archipelagos: 'src/archipelagos',
+    shared: 'src/shared',
+    contract: 'contract/src',
+    lagoon: lagoonRel,
+    ...(host === 'angularjs' ? { bridge: 'roots/bridge' } : {}),
+    appPackage,
+    tagPrefix: 'x-',
+    isolation,
+    // NO `motuRoot`, EVER. It used to be written here as "the only machine-specific path in the
+    // project" — a committed relative path to somebody's checkout, which is exactly what breaks on the
+    // second machine and in CI. The CLI derives it from the binary that is running (see
+    // FRAMEWORK_ROOT in lib/config.mjs), so the correct value is never worth committing.
+    //
+    // It used to still be written when $MOTU_ROOT was set for this init, on the reasoning that a
+    // deliberate arrangement is worth recording. That was backwards: it took an override that was
+    // correct for ONE machine and froze it into the file every other machine reads. $MOTU_ROOT stays
+    // in the environment, where whoever needs it sets it.
+  };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  created.push(configPath);
+
+  // --- the app package: registries, barrel, the shared island sheet ---------------------------
+  // INSTALLED FROM NPM, the range is the CLI's own version: the set is released in lockstep, so the
+  // CLI that is running is the statement of which `@motujs/*` it was built against.
+  const motuDep = argv.motuDep ? String(argv.motuDep) : INSTALLED ? `^${CLI_VERSION}` : 'workspace:*';
+  // `workspace:*` IS A LIE IN A STANDALONE PROJECT, and an expensive one: the generated package.json
+  // listed three @motujs packages that no workspace resolves, so `bun install` — and therefore
+  // `bun add react` — failed outright in a freshly-initialised project. A greenfield adopter could
+  // not install their first dependency.
+  //
+  // The packages do not belong there anyway. Nothing resolves @motujs/* through node: the lagoon aliases
+  // them and tsconfig `paths` maps them, which is the whole "no install step" posture. So they are
+  // declared only when a workspace above the project can actually satisfy them.
+  const inWorkspace = (() => {
+    let dir = appRoot;
+    for (let up = 0; up < 6; up++) {
+      const parent = dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+      if (existsSync(resolve(dir, 'pnpm-workspace.yaml'))) return true;
+      try {
+        const pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8'));
+        if (pkg.workspaces) return true;
+      } catch {}
+    }
+    return false;
+  })();
+  const motuDependencies =
+    inWorkspace || argv.motuDep || INSTALLED
+      ? `  "dependencies": {\n    "@motujs/core": "${motuDep}",\n    "@motujs/react": "${motuDep}",` +
+        `\n    "@motujs/runtime": "${motuDep}"${adapterDepFor(motuDep, host)}\n  },\n`
+      : '';
+  // 'vite' contributes at BUILD time (packages/adapters/vite/vite.mjs), not as a runtime package,
+  // so it needs no adapter dependency — the same as 'none'.
+  const adapterPkg = host === 'angularjs' ? '@motujs/adapter-angularjs' : host === 'next' ? '@motujs/adapter-next' : '';
+  const adapterDep = adapterPkg ? `,\n    "${adapterPkg}": "${motuDep}"` : '';
+  function adapterDepFor(dep, h) {
+    const pkg = h === 'angularjs' ? '@motujs/adapter-angularjs' : h === 'next' ? '@motujs/adapter-next' : '';
+    return pkg ? `,\n    "${pkg}": "${dep}"` : '';
+  }
+
+  writeNew(
+    resolve(appRoot, 'package.json'),
+    render(APP_PACKAGE_JSON, { appPackage, motuDep, adapterDep, motuDependencies }),
+    created,
+    skipped,
+  );
+  // INSTALLED, AN EXISTING package.json IS EDITED, not just reported on. In checkout mode the block
+  // could only ever be a `workspace:*` or a path into somebody's clone, so a printed notice was the
+  // honest move (see keptPackageJsonNotice). Installed, it is `^<version>` of packages that are on the
+  // registry — exactly what `npm i` would have written — and the adopter has just run
+  // `npm i -D @motujs/cli`, which already said yes to motu in this manifest. Leaving them out is what
+  // would break: the islands import `@motujs/react` from the app's own code, and under pnpm (or after
+  // npm stops hoisting a transitive) nothing the app declares would provide it.
+  const recorded = INSTALLED ? recordInstalledDeps(resolve(appRoot, 'package.json'), motuDep, host) : null;
+  writeNew(resolve(appRoot, 'src/islands/registry.ts'), ISLANDS_REGISTRY, created, skipped);
+  writeNew(resolve(appRoot, 'src/archipelagos/registry.ts'), ARCHIPELAGOS_REGISTRY, created, skipped);
+  writeNew(resolve(appRoot, 'src/index.ts'), BARREL, created, skipped);
+  writeNew(resolve(appRoot, 'src/shared/styles.css'), SHARED_STYLES, created, skipped);
+  writeNew(resolve(appRoot, 'src/ui/.gitkeep'), '', created, skipped);
+  writeNew(resolve(root, '.gitignore'), GITIGNORE, created, skipped);
+
+  // --- the lagoon root: where `motu island verify` closes the loop ------------------------------
+  if (argv.lagoon !== false) {
+    const vars = {
+      appPackage,
+      motuDep,
+      adapterDep,
+      appDep: argv.motuDep ? relPosix(lagoonDir, appRoot) : 'workspace:*',
+      tagPrefix: 'x-',
+      // Baked at scaffold time: a glob cannot go through a tsconfig alias reliably.
+      fixturesGlob: `['${relPosix(resolve(lagoonDir, 'src'), resolve(appRoot, 'src/islands'))}/*.evidence.ts', '${relPosix(resolve(lagoonDir, 'src'), resolve(appRoot, 'src/islands'))}/*/fixtures.mock.ts']`,
+      configFromLagoon: relPosix(lagoonDir, configPath),
+      hostRootFromLagoon: relPosix(lagoonDir, hostRoot),
+      // Tailwind/autoprefixer are the host's toolchain, but the lagoon runs its own postcss pass.
+      lagoonExtraDevDeps: host === 'next' ? ',\n    "autoprefixer": "^10.4.20",\n    "tailwindcss": "^3.4.0"' : '',
+      viteHostImports: host === 'next' ? NEXT_VITE_IMPORTS : '',
+      // The app's own global stylesheet. Without it the lagoon has no Tailwind base/utilities and no
+      // theme tokens, so islands render unstyled — a preview that lies about how they look in the app.
+      hostGlobalCss: hostGlobalCssImport(lagoonDir, hostRoot),
+      // FIRST import in both entries: host modules read process.env while being imported.
+      // Only where there IS a shim to import: `src/env.ts` is written for the Next host alone, so
+      // every other host got an entry file importing a module that was never created.
+      envShim: host === 'next' ? "import '{{envImport}}';\n" : '',
+      // A Next/shadcn app exposes --primary / --primary-foreground; borrow them so motu's chrome
+      // wears the application's colour rather than motu's own.
+      lagoonChrome: host === 'next' ? LAGOON_CHROME_SHADCN : '',
+      // A React host renders islands in its own tree; the lagoon must do the same or it verifies a
+      // mount path the project never ships. An ocean keeps the custom elements.
+      lagoonMount: host === 'angularjs' ? '' : '  "mount": "react",\n',
+      motuAliases: motuAliases(lagoonDir, appRoot, appPackage, host),
+      hostAliases: host === 'next' ? render(NEXT_VITE_ALIASES, { hostRootFromLagoon: relPosix(lagoonDir, hostRoot) }) : '',
+      viteCss: host === 'next' ? render(NEXT_VITE_CSS, { hostRootFromLagoon: relPosix(lagoonDir, hostRoot) }) : '',
+      // The AngularJS ocean needs a host present for islands that read host scope; the React hosts
+      // need nothing — the store is the only seam.
+      hostImport: host === 'angularjs' ? "import { angularHostScopeChannel } from '@motujs/adapter-angularjs';\n" : '',
+      // Paths the entries import by. `init` writes into the lagoon root, so these are the plain
+      // relative forms; `motu lagoon dev|build` renders the SAME templates into .motu/cache and
+      // overrides them with paths computed from there (see lib/lagoon-materialize.mjs).
+      lagoonConfigImport: '../lagoon.config.json',
+      overridesImport: './lagoon.js',
+      fixturesImport: './fixtures.js',
+      framesGlob: './frames/*.css',
+      galleryEntrySrc: '/src/main.tsx',
+      focusEntrySrc: '/src/lagoon.tsx',
+      envImport: './env.js',
+      hostOption: '',
+      hostOptionInline: '',
+    };
+
+    // ENTRIES ARE NOT SCAFFOLDED, and the reason is a name collision the old layout could not survive.
+    //
+    // It wrote the focus ENTRY to `src/lagoon.tsx` and the OVERRIDES stub to `src/lagoon.ts`, and
+    // writing `index.html` made the project "own" its lagoon — which turns off materialization, so
+    // those two files became the ones Vite actually serves. But a region's `layout` override returns
+    // JSX, so overrides must live in a `.tsx`, which is the entry's name. Following the scaffold
+    // produced a lagoon that served the overrides file as its entry and rendered an empty div.
+    //
+    // acme never hit it because acme has no index.html: it materializes, and its `src/lagoon.tsx` is
+    // the overrides. That is the working shape, so it is now the shape `init` creates — entries,
+    // index.html and the vite config are rendered into `.motu/cache` by `motu lagoon dev|build`,
+    // which is where generated code belongs anyway.
+    // NEITHER IS `src/fixtures.ts`, for the same reason, and it used to be written here anyway.
+    // The materializer renders it — with `fixturesGlob` AND `flowsGlob`, which only it computes — so
+    // init's copy was a duplicate that also could not parse: `vars` here has no `flowsGlob`, so the
+    // file went out carrying a literal `{{flowsGlob}}` and any project that typechecked its lagoon
+    // directory failed on it. Neither acme nor the review console has the file at all, which is why
+    // nothing noticed. `motu lagoon eject` materializes into the project's own lagoon dir, so the
+    // rendered version is what a project gets the moment it wants one on disk.
+    // Declared, not coded: what the lagoon IS lives here; what it DOES lives in @motujs/react.
+    writeNew(resolve(lagoonDir, 'lagoon.config.json'), render(LAGOON_CONFIG, vars), created, skipped);
+    writeNew(resolve(lagoonDir, 'src/lagoon.tsx'), LAGOON_OVERRIDES, created, skipped);
+    if (host === 'next') {
+      writeNew(resolve(lagoonDir, 'src/next-stubs.tsx'), NEXT_STUBS, created, skipped);
+      // RENDERED, like every other template here. This one was written RAW, so the scaffolded
+      // `env.ts` kept its `{{lagoonConfigImport}}` placeholder verbatim and the file could not
+      // compile — invisible until something typechecked `roots/`, which nothing did.
+      writeNew(
+        resolve(lagoonDir, 'src/env.ts'),
+        render(ENV_SHIM, { lagoonConfigImport: '../lagoon.config.json' }),
+        created,
+        skipped,
+      );
+      // ONLY IF THE HOST HAS TAILWIND. This file's whole body is `import hostConfig from
+      // '../../../tailwind.config'`, so writing it for a Next app that styles itself any other way
+      // scaffolds a module that cannot resolve. @motujs/adapter-next makes the same check before it
+      // installs the postcss plugin; a Next host is not a Tailwind host.
+      if (TAILWIND_CONFIGS.some((f) => existsSync(resolve(hostRoot, f))))
+        writeNew(resolve(lagoonDir, 'tailwind.config.ts'), render(NEXT_TAILWIND_CONFIG, vars), created, skipped);
+    }
+  }
+
+  // The rules the HOST's agent has to follow — shipped with motu so they cannot drift from what the
+  // CLI enforces, written into the instruction files the repo already keeps.
+  //
+  // BEFORE the `--json` branch, not after. It used to sit below it, so `motu init --json` scaffolded
+  // the project and silently skipped the rules — and `--json` is exactly the invocation a script or a
+  // CI image uses, which is the one place nobody reads the output to notice they are missing.
+  const rules = applyHostRules(hostRoot);
+  // AND THE SKILLS THEY POINT AT. The rules block is short on purpose — the invariants, and which skill
+  // holds the detail (motu-regions, motu-evidence, motu-checks). A project that got the block without
+  // the skills would be told to load something it does not have. Same root as the rules: the host's,
+  // where its agent reads both. Never over a skill the project changed (reported, not overwritten).
+  const { out: skillsOut } = installSkills(hostRoot);
+
+  if (argv.json) {
+    console.log(JSON.stringify({ root, host, appPackage, created, skipped, rules, skills: skillsOut }, null, 2));
+    return;
+  }
+
+  console.log(color.green(`✓ initialized motu project in ${basename(root)}/`) + color.dim(`  (host: ${host})`));
+  for (const p of created) console.log('  ' + color.dim(relPosix(root, p).replace(/^\.\//, '')));
+  for (const p of skipped) console.log('  ' + color.dim(relPosix(root, p).replace(/^\.\//, '')) + color.yellow(' (kept)'));
+  for (const p of rules) console.log('  ' + color.dim(p) + color.dim(' (motu rules block)'));
+  const skillFiles = skillsOut.created.length + skillsOut.updated.length;
+  if (skillFiles) console.log('  ' + color.dim(`${skillFiles} skill file(s) — the detail the rules block points at (.claude/skills, .github/agents)`));
+  for (const p of skillsOut.skipped) console.log('  ' + color.dim(p) + color.yellow(' (kept — differs from motu\'s; `motu skills install --force` to update)'));
+  console.log('');
+  if (recorded?.length) {
+    console.log(color.yellow(`  ! recorded ${recorded.length} @motujs/* package(s) in package.json — run your package manager once:`));
+    for (const r of recorded) console.log(color.dim(`      ${r}`));
+    console.log('');
+    console.log('      npm install');
+    console.log('');
+  } else if (!INSTALLED) keptPackageJsonNotice(appRoot, skipped, motuDependencies);
+  if (!LEGACY_FIT_HOSTS.has(host)) {
+    console.log(color.dim('  legacy fit is off for this host — islands mount directly, there is no legacy skin to fit.'));
+  }
+  console.log('Next: ' + color.bold('motu archipelago init <id> --page <file>') + color.dim(' then ') + color.bold('motu island create <name>'));
+}