@motujs/cli 0.0.0-stage → 0.1.0

package/src/commands/adopt-root.mjs

@@ -0,0 +1,194 @@
+// `motu archipelago adopt-root <id>` — turn a frame-composed region into a root-composed one.
+//
+// A region composes either from its archipelago's `root` — safe by construction, because the page and
+// the lagoon read the same map — or from a hand-written lagoon frame, which is a second description of
+// the page and is only as safe as the checks comparing it. `region-root` names the difference on every
+// run and does not fail on it, because moving a page is a real refactor of the host's own JSX.
+//
+// This does the half that is DERIVABLE, which is most of the tedium and none of the judgement:
+//   - the host component the frame renders            -> `root`
+//   - each `island('x')` and the prop it sits in      -> `slots`
+// and prints, rather than guesses, the half that is not: the page's own rewrite.
+//
+// It REFUSES rather than approximating. A frame that nests two host components (acme's actions page
+// stacks `ActionsPageStack` around `ActionsLayout`) has an arrangement no single component expresses
+// yet, and the answer is a decision about the application's structure — which is exactly the kind of
+// thing a codemod should hand back.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { SyntaxKind } from 'ts-morph';
+import { color, paths, blankComments } from '../lib/util.mjs';
+import { sourceFileAt } from '../lib/ts-project.mjs';
+import { readRegions } from '../lib/eject.mjs';
+
+/** `received-summary` -> `receivedSummary`. */
+const camel = (kebab) => kebab.split(/[-_]/).map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join('');
+const pascal = (id) => {
+  const c = camel(id);
+  return c[0].toUpperCase() + c.slice(1);
+};
+
+/** The region's frame module, from the lagoon overrides. Mirrors `frameModuleFor` in verify. */
+function frameModuleFor(id) {
+  for (const f of ['src/lagoon.tsx', 'src/lagoon.ts']) {
+    const overrides = paths.lagoonDir ? `${paths.lagoonDir}/${f}` : null;
+    if (!overrides || !existsSync(overrides)) continue;
+    const src = readFileSync(overrides, 'utf8');
+    const named = new RegExp(`(^|[\\s{,])['"\`]?${id}['"\`]?\\s*:\\s*([A-Za-z_$][\\w$]*)?`, 'm');
+    const moduleOf = (ident) => {
+      const spec = src.match(new RegExp(`import\\s*\\{[^}]*\\b${ident}\\b[^}]*\\}\\s*from\\s*['"]([^'"]+)['"]`));
+      if (!spec) return null;
+      const base = new URL(spec[1].replace(/\.js$/, ''), `file://${overrides}`).pathname;
+      return ['.tsx', '.ts', ''].map((e) => base + e).find((c) => existsSync(c)) ?? null;
+    };
+    const record = src.match(/export const regions[^=]*=\s*\{([\s\S]*?)\s*\};/);
+    if (record) {
+      const entry = record[1].match(named);
+      return entry?.[2] ? moduleOf(entry[2]) : null;
+    }
+    const array = src.match(/export const regions[^=]*=\s*\[([\s\S]*?)\s*\];/);
+    for (const ident of array?.[1].match(/[A-Za-z_$][\w$]*/g) ?? []) {
+      const module = moduleOf(ident);
+      if (!module) continue;
+      const body = readFileSync(module, 'utf8');
+      const bound = body.match(/overridesFor\(\s*([A-Za-z_$][\w$]*)/);
+      if (!bound) continue;
+      const from = body.match(new RegExp(`import\\s*\\{[^}]*\\b${bound[1]}\\b[^}]*\\}\\s*from\\s*['"]([^'"]+)['"]`));
+      if (from && new RegExp(`(^|/)${id}\\.archipelago`).test(from[1])) return module;
+    }
+  }
+  return null;
+}
+
+export async function archipelagoAdoptRootCommand(argv) {
+  const id = argv._[0];
+  if (!id) {
+    console.error('usage: motu archipelago adopt-root <id>');
+    process.exit(2);
+  }
+  const archPath = paths.archipelagoFile(id);
+  if (!existsSync(archPath)) {
+    console.error(color.red(`✗ no archipelago '${id}' at ${paths.rel(archPath)}`));
+    process.exit(2);
+  }
+  const archText = readFileSync(archPath, 'utf8');
+  if (/^\s*root\s*:/m.test(blankComments(archText))) {
+    console.log(color.yellow(`! '${id}' already declares a root — nothing to do`));
+    return;
+  }
+  const frame = frameModuleFor(id);
+  if (!frame) {
+    console.error(color.red(`✗ '${id}' has no lagoon frame to read`));
+    console.error(color.dim('  there is nothing to derive from — declare `root` + `slots` by hand'));
+    process.exit(2);
+  }
+
+  const sf = sourceFileAt(frame, { allowJs: true, jsx: 4 });
+  // The frame's returned tree. Its host components are the app's; `island(slot)` calls are motu's.
+  // The frame's OWN components are the frame, not the app's — `<SetupAccountDetailsRegionFrame>` is
+  // the thing being replaced, and counting it made the command report the frame as its own root.
+  const own = new Set(
+    [...sf.getText().matchAll(/(?:export\s+)?(?:function|const)\s+([A-Z][A-Za-z0-9]*)/g)].map((m) => m[1]),
+  );
+  const hosts = [
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+  ].filter((el) => {
+    const tag = el.getTagNameNode().getText();
+    return /^[A-Z]/.test(tag) && !own.has(tag);
+  });
+
+  if (hosts.length === 0) {
+    console.error(color.red(`✗ ${paths.rel(frame)} renders no application component`));
+    console.error(color.dim('  a root IS the app\'s own layout component; this frame has none to point at'));
+    process.exit(2);
+  }
+  if (hosts.length > 1) {
+    console.error(color.red(`✗ ${paths.rel(frame)} nests ${hosts.length} application components:`));
+    for (const el of hosts) console.error(color.dim(`    <${el.getTagNameNode().getText()}>`));
+    console.error(
+      color.dim('  a root is ONE component, so this arrangement is not expressed by any of them yet.\n') +
+        color.dim('  Extract a component that takes the whole region as props, then run this again.\n') +
+        color.dim('  That is a decision about the application\'s structure, which is why it is not guessed here.'),
+    );
+    process.exit(2);
+  }
+
+  const el = hosts[0];
+  const rootName = el.getTagNameNode().getText();
+  const rootFrom = sf
+    .getImportDeclarations()
+    .find((i) => (i.getNamedImports?.() ?? []).some((n) => n.getName() === rootName))
+    ?.getModuleSpecifierValue();
+  if (!rootFrom) {
+    console.error(color.red(`✗ could not find where <${rootName}> is imported from in ${paths.rel(frame)}`));
+    process.exit(2);
+  }
+
+  // prop -> slot, from `prop={island('x')}`; plus the nesting form, `<X>{island('x')}</X>` -> children.
+  //
+  // A prop holding MORE THAN ONE island is the shape `slots` cannot express: acme's sign-in shows
+  // EITHER `auth-error` OR `login-form` in one child, and a region cannot declare that two slots are
+  // exclusive. Taking the first match would have written a map that silently drops the other island —
+  // which this did, on its first run, and produced a plausible wrong answer instead of a refusal.
+  const slots = {};
+  const exclusive = [];
+  const islandsIn = (text) => [...text.matchAll(/\bisland\(\s*['"`]([^'"`]+)['"`]/g)].map((m) => m[1]);
+  for (const attr of el.getAttributes?.() ?? []) {
+    const prop = attr.getNameNode?.().getText?.();
+    const found = islandsIn(attr.getInitializer?.()?.getText?.() ?? '');
+    if (!prop || !found.length) continue;
+    if (found.length > 1) exclusive.push([prop, found]);
+    else slots[prop] = found[0];
+  }
+  const parent = el.getParent?.();
+  if (parent?.getKind?.() === SyntaxKind.JsxElement) {
+    const found = islandsIn(parent.getJsxChildren().map((c) => c.getText()).join(''));
+    if (found.length > 1) exclusive.push(['children', found]);
+    else if (found.length === 1) slots.children = found[0];
+  }
+  if (exclusive.length) {
+    console.error(color.red(`✗ ${paths.rel(frame)} puts more than one island in a single prop:`));
+    for (const [prop, found] of exclusive) console.error(color.dim(`    ${prop}: ${found.join(' | ')}`));
+    console.error(
+      color.dim('  `slots` maps one prop to one island, and a region cannot declare that two of them\n') +
+        color.dim('  are exclusive. Give the root a prop per island (each rendering nothing when it is\n') +
+        color.dim('  not the one), or leave this region on its frame — that is what the frame is for.'),
+    );
+    process.exit(2);
+  }
+
+  if (!Object.keys(slots).length) {
+    console.error(color.red(`✗ ${paths.rel(frame)} passes no island to <${rootName}>`));
+    process.exit(2);
+  }
+
+  // --- write the archipelago ---------------------------------------------------------------------
+  const slotLines = Object.entries(slots).map(([p, s]) => `    ${p}: '${s}',`).join('\n');
+  let out = archText.replace(
+    /(\n\s*id:\s*'[^']+',\n)/,
+    `$1  // THE ARRANGEMENT, DECLARED ONCE: the page renders \`<${pascal(id)}.Root>\` with these prop names and\n` +
+      `  // never writes a slot, and the lagoon renders the same component from this same map.\n` +
+      `  root: ${rootName},\n  slots: {\n${slotLines}\n  },\n`,
+  );
+  const importLine = `import { ${rootName} } from '${rootFrom}';\n`;
+  if (!out.includes(importLine)) {
+    out = out.replace(/(^import [\s\S]*?;\n)/m, `$1${importLine}`);
+  }
+  writeFileSync(archPath, out);
+
+  console.log(color.green(`✓ ${id} now composes from its own root`));
+  console.log('  ' + color.dim(`${paths.rel(archPath)}   root: ${rootName}, slots: ${Object.keys(slots).length}`));
+  console.log('');
+  console.log(color.bold('Still yours to do — this cannot be derived:'));
+  console.log(color.dim(`  1. the page renders <${pascal(id)}.Root …/> instead of <${rootName}> + <${pascal(id)}.Island>:`));
+  for (const [prop, slot] of Object.entries(slots)) {
+    console.log(color.dim(`       ${prop}={…}   (was <${pascal(id)}.Island slot="${slot}">)`));
+  }
+  console.log(color.dim('     pass null for a slot the page decides not to show; a prop it never passes'));
+  console.log(color.dim('     is an island that never renders, and `integrate check` will say so.'));
+  console.log(color.dim(`  2. delete the frame in ${paths.rel(frame)} and its \`layout:\` entry.`));
+  console.log(color.dim('  3. any prop of the root the islands do NOT fill: `hostSlots` if it is a'));
+  console.log(color.dim('     component, a plain prop otherwise — and give the lagoon its value in `hostProps`.'));
+  console.log('');
+  console.log('Then: ' + color.bold(`motu archipelago verify ${id} --runtime`));
+}

package/src/commands/archipelago-init.mjs

@@ -0,0 +1,314 @@
+// `motu archipelago init <id> --page <page.tsx>` — everything a page needs before its FIRST island.
+// `motu archipelago init <id>` (no page) — a NEW region: the archipelago alone, `root` declared first.
+//
+// Two cases, one verb. They used to be `init` and `create`, and the difference is real but it is a
+// difference in INPUT, not in kind: a page that exists has a type, a composition root and a lagoon
+// module to derive; a region whose page does not exist yet has only its declaration, and the safe
+// shape (`root` first) is free there because nothing has to be restructured.
+//
+// The second island on a page is cheap. The first is not: an archipelago, an app-side region type the
+// config is declared against, a composition root that binds the region to this environment, a lagoon
+// module that seeds and arranges it, and two entries in the lagoon overrides. None of it is a
+// decision — every one of those files is derivable from "this id, that page" — but all of it has to
+// exist before anything can be verified, which is what makes adopting motu on a new page feel
+// expensive when adding to an existing one does not.
+//
+// It derives from PRECEDENT, not from a template: the transport and host bridge of a new composition
+// root are copied from the one this project already wrote, because those are environment decisions
+// the project has already made once and must not answer differently by accident.
+//
+// It does NOT scaffold evidence. A file full of `TODO` looks like coverage and rots — the same reason
+// `island create` stopped writing `fixtures.mock.ts`. Evidence appears when there is something real.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { color, paths, HOST_ROOT, APP_ROOT, hostAliasSpecifier } from '../lib/util.mjs';
+import { scaffoldArchipelago } from './archipelago.mjs';
+
+const written = [];
+const skipped = [];
+
+function put(path, contents) {
+  if (existsSync(path)) return skipped.push(path);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, contents);
+  written.push(path);
+}
+
+/** `client-portfolio` -> { pascal: 'ClientPortfolio', camel: 'clientPortfolio' }. */
+function names(id) {
+  const words = id.split(/[-_]/).filter(Boolean);
+  return {
+    pascal: words.map((w) => w[0].toUpperCase() + w.slice(1)).join(''),
+    camel: words.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join(''),
+  };
+}
+
+/**
+ * How this project imports host files: the host's own alias when one covers the file, else relative.
+ *
+ * Resolved through the tsconfig's real alias TARGET, never by assuming `@/*` means the host root.
+ * The assumption held on Next (`"@/*": ["./*"]`) and broke on a Vite app mapping `"@/*": ["./src/*"]`,
+ * where this generated `@/src/pages/…` — a doubled `src/` resolving to nothing, in a file motu had
+ * just written for the adopter to use.
+ */
+function hostSpecifier(fromFile, targetFile) {
+  const aliased = hostAliasSpecifier(targetFile);
+  if (aliased) return aliased;
+  const rel = relative(dirname(fromFile), targetFile).replace(/\.tsx?$/, '');
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+/** An existing composition root, so a new one inherits this project's transport and host bridge. */
+function precedent() {
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = resolve(dir, e.name);
+      if (full.startsWith(APP_ROOT)) continue;
+      if (e.isDirectory()) {
+        if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
+        walk(full);
+      } else if (/\.tsx?$/.test(e.name)) {
+        const text = readFileSync(full, 'utf8');
+        if (/createRegion\(/.test(text)) found.push({ file: full, text });
+      }
+    }
+  };
+  for (const top of ['app', 'components', 'lib', 'src']) walk(resolve(HOST_ROOT, top));
+  return found[0] ?? null;
+}
+
+export async function archipelagoInitCommand(argv) {
+  const id = argv._[0];
+  const page = argv.page ? resolve(process.cwd(), argv.page) : null;
+  if (!id) {
+    console.error('usage: motu archipelago init <id> [--page <path/to/page.tsx>]');
+    process.exit(2);
+  }
+  // NO PAGE YET: the region's declaration alone, `root` first. Everything else derives from a page,
+  // so it is written when there is one — re-run with `--page`, which keeps this archipelago.
+  if (!page) return scaffoldArchipelago(argv);
+  if (!existsSync(page)) {
+    console.error(color.red(`✗ no page at ${page}`));
+    process.exit(2);
+  }
+  const { pascal, camel } = names(id);
+  const archConst = `${camel}Archipelago`;
+
+  // 1 — the APP's region type, beside its page. It belongs to the application: no motu import, and it
+  //     erases at runtime, so the vocabulary survives motu's removal.
+  const typeFile = resolve(dirname(page), `${id}-region.ts`);
+  put(
+    typeFile,
+    `// The ${id} region's shared state, as a type.
+//
+// Belongs to the APPLICATION: no motu import, and it erases at runtime. It is the region's SHARED
+// vocabulary, not everything the page holds — a key earns a place here when more than one part of the
+// region needs it, or when motu binds it.
+//
+// EMPTY until the first key is shared. \`Record<string, never>\` rather than a speculative key: a key
+// with no reader is not a key.
+export type ${pascal}Region = Record<string, never>
+`,
+  );
+
+  // 2 — the archipelago, DECLARED AGAINST that type (the shape `motu check`'s region-type rule wants).
+  const archFile = paths.archipelagoFile(id);
+  if (!existsSync(archFile)) {
+    await scaffoldArchipelago({ _: [id] });
+    written.push(archFile);
+  } else {
+    skipped.push(archFile);
+  }
+  const archText = readFileSync(archFile, 'utf8');
+  if (!/ArchipelagoConfig<|archipelago</.test(archText)) {
+    // UPGRADED TO THE CHECKED CALL, which this step is the first that can do it: the cross-checks are
+    // stated against the app-side region type, and `archipelago init` is what just wrote that type.
+    // The page-less form cannot — there is nothing to check against yet — which is why the plain
+    // config form still exists and why a region scaffolded that way is asserting nothing.
+    //
+    // `as const` is not decoration. The checks are derived from the config's LITERAL type, and `const A`
+    // is best effort: past a certain size TypeScript falls back to the constraint and every check
+    // silently passes without checking. `ConstInferenceLost` turns that into an error, and this is what
+    // stops a new region ever meeting it.
+    writeFileSync(
+      archFile,
+      archText
+        .replace(
+          "import type { ArchipelagoConfig } from '@motujs/core';",
+          `import { archipelago } from '@motujs/core';\n// TYPE-ONLY, from the app: the page's vocabulary is the application's to name.\nimport type { ${pascal}Region } from '${hostSpecifier(archFile, typeFile)}';`,
+        )
+        .replace(`export const ${camel}Archipelago: ArchipelagoConfig = {`, `export const ${camel}Archipelago = archipelago<${pascal}Region>()({`)
+        .replace(
+          /\n\};\n$/,
+          `\n} as const,\n// The region's cross-checks, as the declaration's SECOND ARGUMENT. Each property is the check's\n// own result type, so \`true\` is the only value that compiles and a drift errors on that line naming\n// the offending key. Add \`wiring\` once this region has islands (it needs the generated elements map\n// as the second type argument) and \`produced\` once the app declares its produced-key type.\n{ ownership: true });\n`,
+        ),
+    );
+  }
+
+  // 3 — the lagoon's module for this region: what the page establishes, and where its islands sit.
+  const regionModule = resolve(paths.lagoonDir, 'src/regions', `${id}.tsx`);
+  put(
+    regionModule,
+    `// The ${id} region, for the lagoon: what the page establishes, and where the islands sit.
+import type { ReactNode } from 'react';
+import type { LagoonOverrides } from '@motujs/react';
+
+/** What the PAGE establishes on first paint. Add a key when an island binds one. */
+export const ${camel}Seed: NonNullable<LagoonOverrides['seed']>[string] = {};
+
+/**
+ * The region's arrangement.
+ *
+ * Point this at the APPLICATION's own layout component as soon as the page has one — one description
+ * of the page's shape, rendered by the page with live content and here with islands. Restating the
+ * arrangement in JSX here is the drift the region type exists to prevent, one level up.
+ */
+export const ${pascal}RegionFrame = (island: (slot: string) => ReactNode): ReactNode => {
+  // A FRAGMENT, NOT A STYLED <div>. \`region-root\` allows a frame to hold only the application's own
+  // components, fragments and \`island(slot)\` calls — so the placeholder that shipped here (a
+  // \`<div className="flex flex-col gap-6 …">\`) failed that check the moment it was first run, and the
+  // adopter's first \`motu check\` reported a violation motu had written for them. Arrangement belongs
+  // to the app's own layout component; reach for \`root\` in the archipelago when the page has one.
+  // THE SIGNATURE IS \`layout\`'s OWN, not a component's. This shipped as a component taking
+  // \`{ island }\` as PROPS while \`layout\` is \`(island) => ReactNode\` — so wiring the frame motu had
+  // just written required an adapter the adopter had to guess, and the first guess (the props shape
+  // the scaffold itself suggested) was wrong. Typed from the override so the two cannot drift again.
+  return <>{/* {island('your-slot')} */}</>;
+};
+`,
+  );
+
+  // 4 — the composition root, modelled on the one this project already has.
+  const model = precedent();
+  const bindingDir = model ? dirname(model.file) : dirname(page);
+  // ONE MODULE SPECIFIER, TWO FILES — the collision that only bites the FIRST region in a project,
+  // which is the case this command exists for. With no precedent the binding lands beside the page,
+  // where the region TYPE already lives as `<id>-region.ts`; TypeScript resolves `./<id>-region` to
+  // the `.ts` and the composition root is unreachable, so the screen importing `MotuRegion` fails to
+  // compile with no hint that a second file is involved. A project with a precedent never sees it —
+  // acme's binding sits in `components/motu/` and its type in `app/`.
+  const collides = bindingDir === dirname(typeFile);
+  const bindingFile = resolve(bindingDir, `${id}-${collides ? 'binding' : 'region'}.tsx`);
+  const transportLine = model?.text.match(/^\s*transport:.*$/m)?.[0]?.trim() ?? 'transport: undefined, // TODO(motu): the transport this environment uses';
+  const useHostLine = model?.text.match(/^\s*useHost:.*$/m)?.[0]?.trim() ?? 'useHost: undefined, // TODO(motu): the host bridge for this stack';
+  const modelImports = model
+    ? model.text
+        .split('\n')
+        .filter((l) => /^import /.test(l) && !/Archipelago|ELEMENT_REGISTRY/.test(l))
+        .join('\n')
+    : '';
+  // `createRegion` IS THE ONE IMPORT THIS FILE CANNOT DO WITHOUT, and it was only ever inherited.
+  // `modelImports` copies the precedent's imports, so the FIRST region in a project — the one with no
+  // precedent — got a composition root that calls `createRegion(...)` and never imports it. Measured
+  // on a cold adoption: the adopter's first act after `archipelago init` was hand-adding an import
+  // motu had just made necessary.
+  const createRegionImport = /^import .*\bcreateRegion\b/m.test(modelImports)
+    ? ''
+    : "\nimport { createRegion } from '@motujs/react';";
+
+  // THE BARREL, AS A SPECIFIER THAT RESOLVES. `appPackage` defaults to the app directory's name, which
+  // is a real package name only when the directory and the package agree — on a monorepo app called
+  // `apps/dashboard` publishing `@novu/dashboard`, it generated `from 'dashboard'`, importing a
+  // package that does not exist. The barrel is a FILE motu itself wrote, so prefer the host's own way
+  // of naming that file and keep `appPackage` for when it genuinely is a resolvable package.
+  const barrelSpecifier = (() => {
+    const declared = paths.appPackage;
+    const pkgFile = resolve(APP_ROOT, 'package.json');
+    try {
+      if (existsSync(pkgFile) && JSON.parse(readFileSync(pkgFile, 'utf8')).name === declared) return declared;
+    } catch {}
+    return hostSpecifier(bindingFile, paths.barrel) ?? declared;
+  })();
+
+  // Compared as SPECIFIERS, not as paths: `a-region.ts` and `a-region.tsx` are different paths and
+  // the same module, which is what let the collision above through.
+  const specifierOf = (f) => f.replace(/\.tsx?$/, '');
+  if (specifierOf(bindingFile) !== specifierOf(typeFile)) {
+    put(
+      bindingFile,
+      `'use client';
+// The composition root for the \`${id}\` PAGE archipelago.
+//
+// 100% motu, by design: it is the one file that has to go when motu does, and \`motu removal-check\`
+// deletes it whole and unwraps <${pascal}Region> wherever the page used it.
+//
+// The transport and host bridge are COPIED from this project's existing composition root, not chosen
+// again: they are environment decisions the project already made, and answering them differently by
+// accident is how two regions end up with two securities.
+${modelImports}${createRegionImport}
+import { ELEMENT_REGISTRY, ${archConst} } from '${barrelSpecifier}';
+
+export const ${pascal} = createRegion(${archConst}, {
+  elements: ELEMENT_REGISTRY,
+  ${transportLine}
+  ${useHostLine}
+});
+
+/** The region wrapper, for the page to wrap its content in. */
+export const MotuRegion = ${pascal}.Region;
+`,
+    );
+  }
+
+  // 5 — the lagoon overrides: two entries, added in place when the maps are where we expect them.
+  const overrides = resolve(paths.lagoonDir, 'src/lagoon.tsx');
+  const manual = [];
+  if (existsSync(overrides)) {
+    let text = readFileSync(overrides, 'utf8');
+    const before = text;
+    // ANCHORED, AND NOT INTO A COMMENT. These patterns used to match anywhere, and the scaffold's own
+    // overrides file ships every map COMMENTED OUT as a template — so the first `archipelago init` in a
+    // project spliced its entry into the middle of `// export const seed: … = {`, leaving a bare
+    // `'id': seed, someArchipelago: { … } };` on the next line. A file that cannot parse, written by
+    // the command whose job is to make the region work, and reported as a success.
+    const seedMap = /^export const seed: LagoonOverrides\['seed'\] = \{/m;
+    const layoutMap = /^export const layout: LagoonOverrides\['layout'\] = \{/m;
+    const canSplice = seedMap.test(text) || layoutMap.test(text);
+    const importLine = `import { ${pascal}RegionFrame, ${camel}Seed } from './regions/${id}.js';`;
+    // The import goes in only if something will USE it. Adding it to a file whose maps are all
+    // commented out left a dangling import of a module nothing referenced, and — because the file had
+    // changed — suppressed the instruction telling the user to wire it up by hand.
+    if (canSplice && !text.includes(importLine)) {
+      text = text.replace(/^(import [\s\S]*?;\n)(?!import )/m, `$1${importLine}\n`);
+    }
+    if (seedMap.test(text) && !new RegExp(`\\b${id}:`).test(text)) {
+      text = text.replace(seedMap, `$&\n  '${id}': ${camel}Seed,`);
+    }
+    if (layoutMap.test(text)) {
+      text = text.replace(
+        layoutMap,
+        `$&\n  '${id}': (island) => <${pascal}RegionFrame island={island} />,`,
+      );
+    }
+    if (text !== before) {
+      writeFileSync(overrides, text);
+      written.push(overrides);
+    } else {
+      manual.push(
+        `wire \`${id}\` into ${relative(process.cwd(), overrides)} — its maps are still the scaffold's ` +
+          `commented-out template, so there is nothing to add an entry to. Uncomment \`seed\` and ` +
+          `\`layout\` (or use the \`regions\` array form) and reference \`${camel}Seed\` and ` +
+          `\`${pascal}RegionFrame\` from ./regions/${id}.js`,
+      );
+    }
+  }
+
+  const rel = (f) => relative(process.cwd(), f);
+  console.log(color.bold(`\nmotu archipelago init — ${id}\n`));
+  for (const f of written) console.log('  ' + color.green('+ ') + rel(f));
+  for (const f of skipped) console.log('  ' + color.dim('= ' + rel(f) + ' (exists, untouched)'));
+  console.log('');
+  console.log(color.bold('Next, and these are the parts nobody can generate:'));
+  console.log(`  1. wrap the page's content in ${color.bold('<MotuRegion>')} (${rel(bindingFile)})`);
+  console.log(`  2. add islands: ${color.bold(`motu island integrate <name> --archipelago ${id}`)}`);
+  console.log(`  3. place each one in the page: ${color.bold(`<${pascal}.Island slot="…">`)}`);
+  console.log(`  4. prove the host really uses it: ${color.bold('motu integrate check ' + id)}`);
+  for (const m of manual) console.log('  ' + color.yellow('! ') + m);
+}

package/src/commands/archipelago.mjs

@@ -0,0 +1,138 @@
+// `motu archipelago init <id>` with no `--page` — scaffolds a new (empty) archipelago as its own folder and
+// registers it so the lagoon / CLI can resolve it by id. It:
+//   1. Writes <archipelagos>/<id>/<id>.archipelago.ts with
+//      `export const <id>Archipelago: ArchipelagoConfig = { id, islands: [] }`.
+//   2. Registers it in <archipelagos>/registry.ts (value import + ARCHIPELAGOS map) and
+//      re-exports it from the app barrel.
+// Islands are added later with `motu island integrate <name> --archipelago <id>`.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { Project, QuoteKind, SyntaxKind } from 'ts-morph';
+import { paths, color, FMT } from '../lib/util.mjs';
+
+/** 'client-portfolio' | 'clientPortfolio' -> { id:'client-portfolio', constName:'clientPortfolioArchipelago' }. */
+function archNames(input) {
+  const words = String(input)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.toLowerCase());
+  if (words.length === 0) throw new Error('archipelago id is empty');
+  const id = words.join('-');
+  const camel = words.map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1))).join('');
+  return { id, constName: `${camel}Archipelago` };
+}
+
+function archipelagoSource(id, constName) {
+  // The BINDING's name, PascalCase — a component identifier and a JSX tag, so the archipelago's
+  // camelCase const name cannot stand in for it.
+  const base = constName.replace(/Archipelago$/, '');
+  const Base = base[0].toUpperCase() + base.slice(1);
+  return `// The ${id} region. Add islands with \`motu island integrate <name> --archipelago ${id}\`.
+//
+// DECLARE THE ROOT FIRST. An archipelago is the scope of one root component — usually a page, and it
+// does not have to be. Naming it here is what leaves ONE description of how this region composes:
+// the page renders \`<${Base}.Root prop={…} />\` using its own prop names and never
+// writes a slot, and the lagoon renders the same component from the same map. Skip it and the two
+// sides each compose the region their own way, with nothing comparing them — which is a drift that
+// ships green.
+
+import type { ArchipelagoConfig } from '@motujs/core';
+// import { ${Base}Layout } from '@/app/${id}/${id}-layout';
+
+export const ${constName}: ArchipelagoConfig = {
+  id: '${id}',
+  // The APPLICATION's own layout component, imported — not a copy of it, and not a template.
+  // root: ${Base}Layout,
+  // Which of the root's props an island fills: the app's vocabulary on the left, motu's on the right.
+  // slots: { results: '${id}-results' },
+  // Props the HOST fills, and the app component that fills them — region UI that reads no region key
+  // and writes none. A COMPONENT, never a hole: the lagoon then supplies only its props, as data.
+  // hostSlots: { header: ${Base}Header },
+  islands: [],
+  // layout: \`<div class="gm-arch"></div>\`, // an OCEAN's answer: a legacy page cannot hand React anything
+};
+`;
+}
+
+export async function scaffoldArchipelago(argv) {
+  const raw = argv._[0];
+  if (!raw) {
+    console.error('usage: motu archipelago init <id> [--page <path/to/page.tsx>]');
+    process.exit(2);
+  }
+  const { id, constName } = archNames(raw);
+  const archPath = paths.archipelagoFile(id);
+
+  // "ALREADY EXISTS" IS NOT "ALREADY DONE". Creating a region is three writes — the config, the
+  // registry entry, the barrel re-export — and only the first had a guard. So a run that wrote the
+  // config and then failed (a bad `barrel` path throwing out of ts-morph, say) left the project
+  // half-created, and the RETRY reported "nothing to do" and exited 0 while the registry and barrel
+  // it still owed were never written. Measured on a cold adoption: the region existed, was
+  // unregistered, and the command that should have finished the job said there was nothing to finish.
+  //
+  // So the guard asks whether the region is COMPLETE, not whether one file is present, and when it is
+  // not it carries on and finishes the missing halves.
+  const alreadyRegistered = () => {
+    try {
+      return (
+        readFileSync(paths.archipelagosRegistry, 'utf8').includes(constName) &&
+        readFileSync(paths.barrel, 'utf8').includes(`${id}.archipelago`)
+      );
+    } catch {
+      return false;
+    }
+  };
+  if (existsSync(archPath) && !argv.force) {
+    if (alreadyRegistered()) {
+      console.log(color.yellow(`! ${archPath} already exists — nothing to do`));
+      process.exit(0);
+    }
+    console.log(
+      color.yellow(`! ${paths.rel(archPath)} exists but is not fully registered — finishing what a previous run left`),
+    );
+  }
+
+  mkdirSync(dirname(archPath), { recursive: true });
+  // The existing config is KEPT when it is only the registration that is missing: a half-finished run
+  // must not silently discard edits made to the file it did manage to write.
+  if (!existsSync(archPath) || argv.force) writeFileSync(archPath, archipelagoSource(id, constName));
+
+  const project = new Project({
+    manipulationSettings: { quoteKind: QuoteKind.Single, useTrailingCommas: true },
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+    compilerOptions: { allowJs: true },
+  });
+
+  // 1) registry.ts — value import + ARCHIPELAGOS registry entry.
+  const registrySf = project.addSourceFileAtPath(paths.archipelagosRegistry);
+  const spec = `./${id}/${id}.archipelago`;
+  if (!registrySf.getImportDeclarations().some((d) => d.getModuleSpecifierValue() === spec)) {
+    registrySf.addImportDeclaration({ moduleSpecifier: spec, namedImports: [constName] });
+  }
+  const registry = registrySf.getVariableDeclaration('ARCHIPELAGOS')?.getInitializerIfKind(SyntaxKind.ObjectLiteralExpression);
+  if (registry && !registry.getProperty(`[${constName}.id]`)) {
+    registry.addPropertyAssignment({ name: `[${constName}.id]`, initializer: constName });
+  }
+
+  // 2) barrel (src/index.ts) — re-export the config const (barrel is one level above archipelagos/).
+  const barrelSpec = `./archipelagos/${id}/${id}.archipelago`;
+  const barrelSf = project.addSourceFileAtPath(paths.barrel);
+  if (!barrelSf.getExportDeclarations().some((d) => d.getModuleSpecifierValue() === barrelSpec)) {
+    barrelSf.addExportDeclaration({ moduleSpecifier: barrelSpec, namedExports: [constName] });
+  }
+
+  registrySf.formatText(FMT);
+  barrelSf.formatText(FMT);
+  await project.save();
+
+  console.log(color.green(`✓ created archipelago ${color.bold(id)} (${constName})`));
+  console.log('  ' + color.dim(`${paths.rel(paths.archipelagoFile(id))}   (config const)`));
+  console.log('  ' + color.dim(`${paths.rel(paths.archipelagosRegistry)}   (import + ARCHIPELAGOS)`));
+  console.log('  ' + color.dim(`${paths.rel(paths.barrel)}   (barrel re-export)`));
+  console.log('');
+  console.log('Next: ' + color.bold(`motu island integrate <name> --archipelago ${id}`));
+}