@motujs/cli 0.0.0-stage → 0.1.1

package/src/commands/coverage.mjs

@@ -0,0 +1,358 @@
+// `motu coverage init | doctor | pull` — production coverage that reaches the host, on any stack.
+//
+// WHY THIS EXISTS. Coverage is the one part of motu that runs in production, and on the first project
+// that switched it on the host never stored a single corpus. Nothing said so: setup took four values
+// in a production environment, a token minted by hand on the host, two route files and two meta tags,
+// and any one of them missing gave silence. These three verbs are the setup, the proof, and the way
+// round a production server that cannot reach the host at all.
+//
+//   init    write the route for this host stack, mint the ingest token over the host's admin API, and
+//           print the ONE remaining step in that platform's terms
+//   doctor  send a synthetic report through the DEPLOYED route and name the hop that fails
+//   pull    fold `motu-coverage {…}` lines from a log (the route's `log` mode) and upload them with
+//           this machine's credentials — for a server with no outbound network
+//
+// An agent runs all three: `init` during integration, `doctor` after every deploy, `pull` from CI.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, resolve } from 'node:path';
+import { mergeCorpora, keysHash } from '@motujs/coverage';
+import { color, paths, REPO_ROOT } from '../lib/util.mjs';
+import { loadMotuConfig } from '../lib/config.mjs';
+import { readRegions } from '../lib/eject.mjs';
+import { gitIdentity, loadHostConfig } from '../lib/remote.mjs';
+
+/** The full config: the curated `paths` export carries neither the host stack nor its root. */
+const full = loadMotuConfig();
+
+const DEFAULT_ENDPOINT = '/api/motu/coverage';
+/** Where the Java servlet in `dev.motu:endpoint` answers, relative to the application's context. */
+const JAVA_ENDPOINT = '/motu/coverage';
+
+export async function coverageCommand(sub, argv) {
+  if (sub === 'doctor') return doctor(argv);
+  if (sub === 'pull') return pull(argv);
+  if (sub === 'init') return init(argv);
+  console.error(color.red(`unknown: motu coverage ${sub ?? ''}`) + color.dim(' — init | doctor | pull'));
+  return 2;
+}
+
+function hostTarget(argv) {
+  const cfg = loadHostConfig();
+  const url = (typeof argv.host === 'string' ? argv.host : process.env.MOTU_HOST_URL || cfg.url || '').replace(/\/+$/, '');
+  const token = (typeof argv.token === 'string' ? argv.token : process.env.MOTU_HOST_TOKEN || cfg.token) || null;
+  return { url, token };
+}
+
+function repoName() {
+  return paths.publishAs?.repo ?? gitIdentity(REPO_ROOT).repo;
+}
+
+function regionIds() {
+  return readRegions(paths.archipelagosDir).map((r) => r.id);
+}
+
+// ── doctor ──────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Send one synthetic report through the deployed route, and say which hop failed.
+ *
+ * The report is marked (`x-motu-doctor: 1`): the route forwards it as a DRY RUN, which the host
+ * checks (token, repo) and does not store, or logs it under a different prefix, which `pull` skips.
+ * So running this against production changes nothing a person will later read.
+ *
+ * EXIT CODES carry the usual meaning: 1 is a finding about the deployment (repair it), 2 is that the
+ * application could not be reached from here at all (retry, or run it from somewhere that can).
+ */
+async function doctor(argv) {
+  const json = argv.json === true;
+  const base = typeof argv.url === 'string' ? argv.url.replace(/\/+$/, '') : '';
+  if (!/^https?:\/\//.test(base)) {
+    console.error(color.red('✗ --url <the application’s origin> is required, e.g. --url https://app.example.com'));
+    return 2;
+  }
+  const endpoint = typeof argv.endpoint === 'string' ? argv.endpoint : full.host === 'angularjs' ? JAVA_ENDPOINT : DEFAULT_ENDPOINT;
+  const region = typeof argv.region === 'string' ? argv.region : regionIds()[0];
+  if (!region) {
+    console.error(color.red('✗ this project declares no region to name in the report — pass --region <id>'));
+    return 2;
+  }
+  const target = `${base}${endpoint}`;
+  const report = { v: 1, regionId: region, keys: [], entries: [] };
+  const say = (ok, hop, detail, code) => {
+    if (json) console.log(JSON.stringify({ ok, hop, detail, target, region }, null, 2));
+    else {
+      console.log(`${ok ? color.green('✓') : color.red('✗')} ${color.bold(hop)} ${color.dim('·')} ${detail}`);
+      console.log(color.dim(`  ${target} (region ${region})`));
+    }
+    return code;
+  };
+
+  let res;
+  try {
+    res = await fetch(target, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-motu-doctor': '1' },
+      body: JSON.stringify(report),
+    });
+  } catch (err) {
+    return say(false, 'application unreachable', `could not reach ${base} from this machine (${err?.cause?.code ?? err?.message ?? err})`, 2);
+  }
+  const took = res.headers.get('x-motu-coverage');
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  const error = body?.error ?? '';
+  if (res.status === 404) return say(false, 'route missing', `nothing answers at ${endpoint} — \`motu coverage init\` writes the route`, 1);
+  if (res.status === 405) return say(false, 'route refuses POST', `${endpoint} exists but answers 405 to a POST — is it the coverage route?`, 1);
+  if (res.status === 503) return say(false, 'route not configured', error || 'the route answered 503', 1);
+  if (res.status === 400) return say(false, 'report refused by the route', error || 'the route answered 400', 1);
+  if (res.status === 502) {
+    const hop = /401|token/.test(error) ? 'host refused the token' : /unreachable/.test(error) ? 'host unreachable from the application' : 'host answered an error';
+    return say(false, hop, error || 'the route answered 502', 1);
+  }
+  if (res.ok && took === 'forwarded') return say(true, 'forwarded', 'the route reached the motu host, which accepted the token (dry run — nothing stored)', 0);
+  if (res.ok && took === 'logged') {
+    return say(true, 'logged', 'the route is in log mode: look for one `motu-coverage-doctor {…}` line in that server’s log, then collect real lines with `motu coverage pull`', 0);
+  }
+  if (res.ok) {
+    return say(false, 'route too old to say', `the route answered ${res.status} without \`x-motu-coverage\` — update @motujs/coverage (or the Java endpoint) so this can tell forwarded from dropped`, 1);
+  }
+  return say(false, 'unexpected answer', `the route answered ${res.status}${error ? `: ${error}` : ''}`, 1);
+}
+
+// ── pull ────────────────────────────────────────────────────────────────────────────────────────
+
+const LINE = /(?:^|\s)motu-coverage (\{.*\})\s*$/;
+
+/**
+ * Fold `motu-coverage {…}` lines out of a log and upload them to the host.
+ *
+ * For a server in `log` mode: it cannot reach the host (a JBoss behind a datacentre's egress
+ * firewall) or should not hold a secret. Its log is collected somewhere already — a file, a CI
+ * artifact, an ELK or Splunk export — and this runs wherever that is, with this machine's own host
+ * credentials.
+ *
+ * PULLED LINES ARE REMEMBERED (by hash, in `.motu/cache/coverage-pulled.json`) so pulling the same log
+ * twice does not count its states twice. Pulling it from two machines would; pull from one place.
+ */
+async function pull(argv) {
+  const json = argv.json === true;
+  const from = typeof argv.from === 'string' ? argv.from : null;
+  if (!from) {
+    console.error(color.red('✗ --from <log file> is required (`-` reads stdin: `kubectl logs … | motu coverage pull --from -`)'));
+    return 2;
+  }
+  let text;
+  try {
+    text = from === '-' ? readFileSync(0, 'utf8') : readFileSync(resolve(process.cwd(), from), 'utf8');
+  } catch (err) {
+    console.error(color.red(`✗ could not read ${from}: ${err.message}`));
+    return 2;
+  }
+
+  const seenFile = process.env.MOTU_COVERAGE_PULL_STATE || resolve(full.cacheDir ?? resolve(REPO_ROOT, '.motu/cache'), 'coverage-pulled.json');
+  let seen = new Set();
+  try {
+    seen = new Set(JSON.parse(readFileSync(seenFile, 'utf8')));
+  } catch {
+    /* first pull */
+  }
+
+  const groups = new Map();
+  let lines = 0;
+  let malformed = 0;
+  let already = 0;
+  const fresh = [];
+  for (const raw of text.split('\n')) {
+    const m = LINE.exec(raw);
+    if (!m) continue;
+    lines++;
+    const h = createHash('sha256').update(m[1]).digest('hex').slice(0, 32);
+    if (seen.has(h)) {
+      already++;
+      continue;
+    }
+    let corpus;
+    try {
+      corpus = JSON.parse(m[1]);
+    } catch {
+      malformed++;
+      continue;
+    }
+    if (!corpus || typeof corpus.regionId !== 'string' || !Array.isArray(corpus.keys) || !Array.isArray(corpus.entries)) {
+      malformed++;
+      continue;
+    }
+    // Grouped by DECLARATION, not just region: two key sets are not comparable, and `mergeCorpora`
+    // refuses to fold them rather than produce nonsense.
+    const k = `${corpus.regionId}\u0000${corpus.keysHash ?? keysHash(corpus.keys)}`;
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(corpus);
+    fresh.push(h);
+  }
+
+  if (!lines) {
+    // A PULL THAT FOUND NOTHING is almost always the wrong file, or a route not in log mode — never a
+    // success to report quietly.
+    const msg = `no \`motu-coverage {…}\` lines in ${from} — is the route in log mode, and is this that server’s log?`;
+    if (json) console.log(JSON.stringify({ ok: false, error: msg, lines: 0 }, null, 2));
+    else console.error(color.red(`✗ ${msg}`));
+    return 1;
+  }
+
+  const host = hostTarget(argv);
+  const repo = repoName();
+  const dry = argv['dry-run'] === true;
+  if (!dry && (!host.url || !host.token)) {
+    console.error(color.red('✗ no lagoon host to upload to — set MOTU_HOST_URL / MOTU_HOST_TOKEN or ~/.config/motu/host.json (or pass --dry-run)'));
+    return 2;
+  }
+
+  const results = [];
+  for (const list of groups.values()) {
+    const merged = mergeCorpora(list);
+    const entry = { region: merged.regionId, reports: list.length, states: merged.entries.length };
+    if (!dry) {
+      const res = await fetch(`${host.url}/api/coverage?repo=${encodeURIComponent(repo)}&region=${encodeURIComponent(merged.regionId)}`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${host.token}`, 'content-type': 'application/json' },
+        body: JSON.stringify(merged),
+      }).catch((err) => ({ ok: false, status: 0, statusText: String(err?.cause?.code ?? err?.message ?? err) }));
+      entry.uploaded = !!res.ok;
+      if (!res.ok) entry.error = `host answered ${res.status || res.statusText}`;
+    }
+    results.push(entry);
+  }
+
+  const failed = results.filter((r) => r.uploaded === false);
+  if (!dry && !failed.length) {
+    mkdirSync(dirname(seenFile), { recursive: true });
+    // Bounded: the newest 50 000 line hashes are plenty to stop a re-pull of last week's logs.
+    writeFileSync(seenFile, JSON.stringify([...seen, ...fresh].slice(-50_000)));
+  }
+  if (json) {
+    console.log(JSON.stringify({ ok: !failed.length, repo, lines, already, malformed, regions: results, dryRun: dry }, null, 2));
+  } else {
+    for (const r of results) {
+      const mark = r.uploaded === false ? color.red('✗') : color.green('✓');
+      console.log(`${mark} ${r.region}  ${r.states} state(s) from ${r.reports} report(s)${r.error ? color.red(` — ${r.error}`) : dry ? color.dim(' (dry run)') : ''}`);
+    }
+    console.log(color.dim(`  ${lines} line(s) read · ${already} already pulled · ${malformed} malformed · repo ${repo}`));
+  }
+  return failed.length ? 1 : 0;
+}
+
+// ── init ────────────────────────────────────────────────────────────────────────────────────────
+
+const NEXT_ROUTE = (host, mode) => `// Where a motu coverage beacon lands. Written by \`motu coverage init\`; see @motujs/coverage/server.
+//
+// ${mode === 'log' ? 'LOG MODE: each report becomes one `motu-coverage {…}` line in this server\'s log, and\n// `motu coverage pull --from <log>` uploads them. No secret, no outbound network.' : 'FORWARD MODE: each report goes to the motu host with MOTU_COVERAGE_TOKEN, the one secret this\n// needs. The host URL is not a secret, so it is written here; the repo is read from the token.'}
+import { createCoverageRoute } from '@motujs/coverage/server/next';
+
+export const dynamic = 'force-dynamic';
+
+export const POST = createCoverageRoute({ ${mode === 'log' ? "mode: 'log'" : `host: ${JSON.stringify(host)}`} });
+`;
+
+const NEXT_KNOWN = (host) => `// The states somebody accepted, served back so the beacon stays quiet about them. Written by
+// \`motu coverage init\`. The ingest token reads this set of its own repo; nothing else is needed.
+import { createKnownRoute } from '@motujs/coverage/server/next/known';
+
+export const dynamic = 'force-dynamic';
+
+export const GET = createKnownRoute({ host: ${JSON.stringify(host)} });
+`;
+
+/**
+ * Wire coverage for this project's host stack, as far as files in this repository can.
+ *
+ * What it writes is code (the route). What it cannot write is the production environment, so for
+ * that it prints exactly one step in the platform's own terms — a Vercel variable, a JBoss system
+ * property — and stops. `doctor` is how that step is proved afterwards.
+ */
+async function init(argv) {
+  const json = argv.json === true;
+  const mode = argv.mode === 'log' ? 'log' : 'forward';
+  const host = hostTarget(argv);
+  const repo = repoName();
+  const cfg = full;
+  const steps = [];
+  const wrote = [];
+
+  if (!cfg.coverage?.enabled) steps.push('switch the fold on: `"coverage": { "enabled": true }` in motu.config.json, then `motu sync`');
+
+  // 1. THE ROUTE, for the stacks motu knows.
+  let endpoint = DEFAULT_ENDPOINT;
+  if (full.host === 'next') {
+    const appDir = ['app', 'src/app'].map((d) => resolve(full.hostRoot, d)).find((d) => existsSync(d));
+    if (!appDir) {
+      steps.push(`no Next app router found under ${paths.rel(full.hostRoot)} — add a POST route at ${DEFAULT_ENDPOINT} exporting createCoverageRoute from @motujs/coverage/server/next`);
+    } else {
+      const routeFile = resolve(appDir, 'api/motu/coverage/route.ts');
+      const knownFile = resolve(appDir, 'api/motu/coverage/known/route.ts');
+      for (const [file, body] of [
+        [routeFile, NEXT_ROUTE(host.url, mode)],
+        ...(mode === 'forward' ? [[knownFile, NEXT_KNOWN(host.url)]] : []),
+      ]) {
+        if (existsSync(file) && argv.force !== true) {
+          steps.push(`${paths.rel(file)} already exists — kept. \`--force\` rewrites it to the one-secret form`);
+          continue;
+        }
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, body);
+        wrote.push(paths.rel(file));
+      }
+    }
+    steps.push(`the root layout renders <meta name="motu-coverage-endpoint" content="${DEFAULT_ENDPOINT}" />${mode === 'forward' ? ` and <meta name="motu-coverage-known" content="${DEFAULT_ENDPOINT}/known" />` : ''} (skip if present)`);
+  } else if (full.host === 'angularjs') {
+    endpoint = JAVA_ENDPOINT;
+    steps.push('depend on dev.motu:endpoint in the WAR: its servlet registers itself at /motu/coverage through web-fragment.xml (no web.xml edit)');
+    steps.push(`the page renders <meta name="motu-coverage-endpoint" content="<context>${JAVA_ENDPOINT}" />`);
+    steps.push(mode === 'log' ? 'set the system property -Dmotu.coverage.mode=log (or MOTU_COVERAGE_MODE=log)' : `set -Dmotu.coverage.host=${host.url || '<host url>'} (not a secret)`);
+  } else {
+    steps.push(`this host (${full.host}) has no server motu writes for: deploy a POST route at ${DEFAULT_ENDPOINT} with @motujs/coverage/server's handleCoverage (Web-standard Request/Response — any JS runtime), or the Java servlet`);
+  }
+
+  // 2. THE ONE SECRET, minted over the admin API.
+  let token = null;
+  if (mode === 'forward') {
+    if (!host.url || !host.token) {
+      steps.push('mint an ingest token: no admin credentials here (~/.config/motu/host.json) — on the host, `motu-host access --repo ' + repo + ' --ingest`');
+    } else {
+      const res = await fetch(`${host.url}/api/access/ingest?repo=${encodeURIComponent(repo)}`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${host.token}` },
+      }).catch((err) => ({ ok: false, status: 0, json: async () => ({ error: String(err?.cause?.code ?? err) }) }));
+      const body = await res.json().catch(() => ({}));
+      if (!res.ok || !body.token) {
+        steps.push(`could not mint an ingest token (${res.status || 'unreachable'}: ${body.error ?? 'no detail'}) — on the host, \`motu-host access --repo ${repo} --ingest\``);
+      } else token = body.token;
+    }
+    const where = existsSync(resolve(full.hostRoot, 'vercel.json'))
+      ? 'vercel env add MOTU_COVERAGE_TOKEN production   (paste the token)'
+      : full.host === 'angularjs'
+        ? '-Dmotu.coverage.token=<token> in the server’s JVM options (or MOTU_COVERAGE_TOKEN in its environment)'
+        : 'MOTU_COVERAGE_TOKEN=<token> in the production environment';
+    steps.push(`the ONE production step: ${where}`);
+  }
+  steps.push(`then prove it: motu coverage doctor --url <production origin>${endpoint !== DEFAULT_ENDPOINT ? ` --endpoint <context>${endpoint}` : ''}`);
+
+  if (json) {
+    console.log(JSON.stringify({ ok: true, mode, repo, host: host.url || null, wrote, token, steps }, null, 2));
+    return 0;
+  }
+  console.log(`${color.green('✓')} coverage for ${color.bold(repo)} — ${mode} mode${host.url && mode === 'forward' ? color.dim(` → ${host.url}`) : ''}`);
+  for (const f of wrote) console.log(color.dim(`  wrote ${f}`));
+  if (token) {
+    console.log('');
+    console.log(`  ${color.bold('MOTU_COVERAGE_TOKEN')}=${token}`);
+    console.log(color.dim('  shown once; it can only WRITE coverage for this repo (and read back its accepted states).'));
+  }
+  console.log('');
+  steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
+  return 0;
+}

package/src/commands/create.mjs

@@ -0,0 +1,277 @@
+// `motu island create <name>` — scaffolds an island as ONE file, plus its ui component if motu owns it:
+//   ui/<kebab>/<Pascal>.tsx   — the plain, mode-agnostic component (only when not wrapping the app's)
+//   islands/<kebab>.island.ts — the island: tag, component, and its declared boundary
+// then regenerates the registry from what is on disk.
+//
+// It does NOT scaffold an evidence file. A `fixtures.mock.ts` full of `TODO(motu:fixtures)` is worse
+// than no file: it looks like coverage, invites a hand-written response shape, and rots — six of them
+// sat empty in the reference adopter for months. Evidence appears when `motu fixtures record` produces
+// it, or when you write a scenario because you need one.
+//
+// The component lives OUTSIDE islands/ so mount points can never import each other. TODO(motu:*)
+// markers are left for the extraction skill.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { Project, QuoteKind, SyntaxKind } from 'ts-morph';
+import { paths, names, color, FMT, resolveModuleSpecifier, LEGACY_FIT, islandComponentPath, islandComponentExport } from '../lib/util.mjs';
+import { syncRegistry } from '../lib/islands.mjs';
+import { syncContracts } from '../lib/contracts.mjs';
+import { readComponentContract } from '../lib/component-props.mjs';
+
+function componentSource(pascal, kebab) {
+  return `export interface ${pascal}Props {
+  /** TODO(motu:props): declare inputs. Every prop MUST have a default so the island renders in the
+   * lagoon from its defaults alone (verified by \`motu island verify\`). */
+  title?: string;
+}
+
+/**
+ * ${pascal} — TODO(motu:body): implement this island.
+ *
+ * Rules enforced by \`motu island verify\` (see README "The rules that make islands verifiable"):
+ *  - Mode-agnostic: no bare fetch, no history/pushState, no document reach-out into the host.
+ *  - All server I/O goes through the generated @motujs/contract, never a raw transport.
+ *  - Renders correctly from default props alone (the lagoon mounts it with none).
+ */
+export function ${pascal}({ title = '${pascal}' }: ${pascal}Props = {}) {
+  return (
+    <section className="motu-${kebab}">
+      <h2>{title}</h2>
+      <p className="motu-note">TODO(motu:body): build the ${kebab} island.</p>
+    </section>
+  );
+}
+`;
+}
+
+function elementSource(pascal, camel, tag, kebab, from, exportName, contract) {
+  // Only where the host HAS a legacy skin. Under a modern host it is not optional but absent —
+  // declaring it would be a field nothing reads (see `motu island verify`'s legacy-strategy rule).
+  const legacy = LEGACY_FIT ? "\n    legacy: 'fill'," : '';
+  // `from` = wrapping a component the app already owns; otherwise the scaffolded ui/ component.
+  // One directory shallower than the old folder layout: the island file sits IN islands/.
+  const spec = from ?? `../ui/${kebab}/${pascal}.js`;
+  const header = from
+    ? `// Mount point for ${pascal}: it wraps the application's OWN component rather than a copy, so the
+// island cannot drift from what the app already ships. The component stays where it is and keeps
+// being used directly elsewhere; this file only declares how it is mounted as an island.
+`
+    : '';
+
+  // READ from the component when there is one to read. Every line below is a fact already in its
+  // source — transcribing it by hand is how an island's contract drifts from the component on its
+  // first day. What is left for a human is the part that is a decision: the event NAMES (renamed here
+  // to the region's vocabulary if it has a better word) and, in the archipelago, what they bind to.
+  const lines = [];
+  if (contract?.effects?.length) {
+    lines.push('      // AMBIENT — host capabilities this island reaches for without being handed them.');
+    lines.push('      effects: [');
+    for (const a of contract.effects) lines.push(`        '${a}',`);
+    lines.push('      ],');
+  }
+  if (contract?.input?.length) {
+    lines.push('      input: [');
+    for (const i of contract.input) lines.push(`        '${i}',`);
+    lines.push('      ],');
+  } else if (from) {
+    lines.push("      // TODO(motu:contract): this component's props could not be read — list them here.");
+    lines.push('      input: [],');
+  } else {
+    lines.push("      input: ['title'],");
+  }
+  if (contract?.output?.length) {
+    lines.push('      // Event names are the REGION\'s vocabulary — rename them if it has a better word.');
+    lines.push('      output: {');
+    for (const o of contract.output) lines.push(`        ${o.prop}: '${o.event}',`);
+    lines.push('      },');
+  }
+
+  const imported = exportName && exportName !== pascal ? `${exportName} as ${pascal}` : pascal;
+  return `${header}import { islandElement } from '@motujs/react';
+import { ${imported} } from '${spec}';
+
+export const element = islandElement({
+  tag: '${tag}',
+  component: ${pascal},
+  options: {
+    // The island's boundary in one place — input (props), output (events), effects (what it reaches).
+    contract: {
+${lines.join('\n')}
+    },${legacy}
+  },
+});
+`;
+}
+
+function indexSource(camel) {
+  return `export { ${camel}Element } from './element';\n`;
+}
+
+function fixturesSource(kebab, contractHint) {
+  return `// Lagoon fixtures for x-${kebab}: replayed by MockTransport so the island renders offline (no backend,
+// no login). Fill these in with the shapes the island's @motujs/contract calls return.
+//
+// Contract methods available to mock (from @motujs/contract):
+${contractHint}
+import type { Fixture, Scenario } from '@motujs/runtime/mock';
+
+export const fixtures: Fixture[] = [
+  // TODO(motu:fixtures): e.g.
+  // { service: 'SomeService', method: 'search', roles: ['CAN_...'], response: { /* ... */ } },
+  // Request-keyed (return different data per input) — 'match' deep-equals the call args, with
+  // 'undefined' as a wildcard slot and a plain object matched as a subset:
+  // { service: 'SomeService', method: 'search', match: [undefined, { login: 'brice' }], response: { /* ... */ } },
+];
+
+/** Roles the mock caller holds — must satisfy the fixtures' role gates. */
+export const roles: string[] = [];
+
+/** Optional data-flow cases: two+ seeds whose DISTINCT output proves inputs reach the render
+ *  (\`motu island verify\` mounts each and asserts they differ). Pair with request-keyed fixtures. */
+export const scenarios: Scenario[] = [
+  // { name: 'empty', seed: { criteria: {} } },
+  // { name: 'filtered', seed: { criteria: { login: 'brice' } } },
+];
+`;
+}
+
+/** A comment block listing contract services/methods so the fixtures author knows what to mock. */
+function readContractHint() {
+  try {
+    const text = readFileSync(paths.contract, 'utf8');
+    const services = [...text.matchAll(/export const (\w+) = \{([\s\S]*?)\n\};/g)];
+    const lines = [];
+    for (const [, name, body] of services) {
+      for (const [, method] of body.matchAll(/^\s{2}(\w+):/gm)) {
+        lines.push(`//   - ${name}.${method}`);
+      }
+    }
+    return lines.length ? lines.join('\n') : '//   (none found — regenerate @motujs/contract)';
+  } catch {
+    return '//   (@motujs/contract not found)';
+  }
+}
+
+/** Add the import + ELEMENT_REGISTRY entry to the islands registry via AST. */
+function addRegistryEntry(project, camel, kebab) {
+  const sf = project.addSourceFileAtPath(paths.islandsRegistry);
+  const spec = `./${kebab}/element`;
+  const constName = `${camel}Element`;
+
+  if (!sf.getImportDeclarations().some((d) => d.getModuleSpecifierValue() === spec)) {
+    sf.addImportDeclaration({ moduleSpecifier: spec, namedImports: [constName] });
+  }
+
+  const registry = sf.getVariableDeclarationOrThrow('ELEMENT_REGISTRY');
+  const arr = registry.getInitializerIfKindOrThrow(SyntaxKind.ArrayLiteralExpression);
+  if (!arr.getElements().some((e) => e.getText().trim() === constName)) {
+    arr.addElement(constName);
+  }
+  return sf;
+}
+
+export async function createCommand(argv) {
+  const name = argv._[0];
+  if (!name) {
+    console.error('usage: motu island create <name>');
+    process.exit(2);
+  }
+  const { pascal, camel, kebab, tag } = names(name);
+  // `--from <specifier>` wraps a component the application already owns (the React-host case: there is
+  // nothing to write, only something to mount). Without it, scaffold a new component under ui/ — the
+  // extraction case, where the original is not React and a component has to be authored.
+  let from = typeof argv.from === 'string' ? argv.from : null;
+  // `--export` names the component INSIDE the module, when it is not the island's Pascal name.
+  let exportName = typeof argv.export === 'string' ? argv.export : null;
+
+  // `--from <module>:<Export>` IS ACCEPTED, because it is what people actually type.
+  //
+  // Measured on three cold-start adoptions: two independent agents, on two different applications,
+  // invented exactly this form, spent three invocations each on it, and only recovered via the docs
+  // or `--help`. When two strangers independently guess the same syntax, the syntax is not the
+  // problem — refusing it is. `--export` remains the canonical spelling and still wins if both are
+  // given; this only stops the guess from being a dead end.
+  //
+  // Split on the LAST colon, and only when the tail looks like an export name, so a Windows drive
+  // letter or a `node:`/`virtual:` style specifier is untouched.
+  if (from && !exportName) {
+    const m = from.match(/^(.*[^:]):([A-Za-z_$][\w$]*)$/);
+    if (m && !/^[a-z]+:$/.test(m[1] + ':')) {
+      from = m[1];
+      exportName = m[2];
+    }
+  }
+  const componentPath = paths.componentFile(kebab, pascal);
+  const fixturesPath = paths.fixturesFile(kebab);
+
+  if (!from && existsSync(componentPath) && !argv.force) {
+    console.error(color.red(`✗ ${componentPath} already exists (use --force to overwrite)`));
+    process.exit(1);
+  }
+  // RESOLVE FROM WHERE THE ISLAND FILE WILL ACTUALLY SIT.
+  //
+  // This resolved against `islandDir(kebab)` — the FOLDER layout, `src/islands/<kebab>/` — while
+  // create always writes the FLAT one, `src/islands/<kebab>.island.ts`, one level up. So a relative
+  // `--from` was broken in both directions: the specifier that is correct for the emitted file
+  // (`../ui/x`) was rejected, and the one that satisfied this check (`../../ui/x`) was written
+  // verbatim into a file where it resolves one level too high — a broken import that passed the
+  // CLI's own validation. Only the alias form worked, because aliases resolve from the host root,
+  // which is why the React hosts never hit it.
+  const islandDir = paths.islandsDir;
+  if (from && !resolveModuleSpecifier(from, islandDir)) {
+    // SHOW A CORRECT CALL. The old message said what was wrong and never what to type, so an agent
+    // that had guessed the syntax had nothing to correct toward — it guessed twice more, then read
+    // the docs. A message that ends in an example is the difference between three invocations and one.
+    const guessedExt = /\.(tsx?|jsx?)$/.test(from);
+    console.error(
+      color.red(`✗ --from '${from}' does not resolve to a file from ${paths.rel(islandDir)}`) +
+        (guessedExt ? color.dim('\n  Drop the file extension — this is a module specifier, not a path.') : '') +
+        color.dim('\n  Use the specifier the APP itself uses, and name the export with --export:') +
+        color.dim(`\n      motu island create ${kebab} --from @/components/${kebab} --export ${pascal}`) +
+        color.dim(`\n      motu island create ${kebab} --from ../components/${kebab} --export ${pascal}   (relative to ${paths.rel(islandDir)})`) +
+        color.dim('\n  `--from <module>:<Export>` is also accepted.'),
+    );
+    process.exit(1);
+  }
+
+  if (!from) mkdirSync(dirname(componentPath), { recursive: true }); // ui/<kebab>/
+  mkdirSync(paths.islandsDir, { recursive: true });
+
+  // Component in ui/ (unless wrapping one the app owns), then the island itself — one file.
+  if (!from) writeFileSync(componentPath, componentSource(pascal, kebab));
+  const islandFile = resolve(paths.islandsDir, `${kebab}.island.ts`);
+  // The component's own source answers most of the contract; read it rather than asking for it again.
+  const contract = from ? readComponentContract(resolveModuleSpecifier(from, islandDir), exportName ?? pascal) : null;
+  writeFileSync(islandFile, elementSource(pascal, camel, tag, kebab, from, exportName, contract));
+
+  // The registry is GENERATED from what is on disk, not edited: adding an island is a file operation,
+  // and reconciling is what keeps a deleted or renamed one from lingering in it.
+  syncRegistry(paths.islandsDir, paths.isolation);
+  // AND THE CONTRACTS, in the same breath. Creating an island left `contracts.generated.ts` missing,
+  // so the very first `motu check` a new project runs — straight after the next-step this command
+  // prints — opened with `✗ generated  contracts.generated.ts is missing`. The scaffolder failing its
+  // own check is the first thing a stranger sees, and the fix was a command they had not been told
+  // about yet.
+  syncContracts(paths.islandsDir, { islandComponentPath, islandComponentExport, names });
+  console.log(color.green(`✓ created island ${color.bold(kebab)}  (component ${pascal}, tag ${tag})`));
+  if (contract) {
+    console.log(
+      '  ' +
+        color.dim(
+          `read from the component: ${contract.input.length} input(s), ${contract.output.length} output(s)` +
+            `${contract.effects.length ? `, ${contract.effects.length} effect(s)` : ''}`,
+        ),
+    );
+  }
+  if (from) console.log('  ' + color.dim(`wraps ${from}   (the app's own component — not copied)`));
+  else console.log('  ' + color.dim(`${paths.rel(paths.componentFile(kebab, pascal))}   (component)`));
+  console.log('  ' + color.dim(`${paths.rel(islandFile)}   (the island)`));
+  console.log('  ' + color.dim(`${paths.rel(paths.islandsRegistry)}   (regenerated)`));
+  console.log('');
+  console.log('Next: fill the TODO(motu:*) markers, then ' + color.bold(`motu island verify ${kebab}`));
+  console.log(
+    color.dim('  Evidence (fixtures/scenarios) goes in ') +
+      color.dim(color.bold(`${kebab}.evidence.ts`)) +
+      color.dim(' — write one when you need it, or record it with `motu fixtures record`.'),
+  );
+}