create-ailk 0.15.0 → 0.16.0

package/README.md

@@ -262,6 +262,130 @@ the route-surface registry in the same file.
 `ROUTE_SINCE` entry — `__tests__/sync-routes.test.ts` fails otherwise (and it
 fails on a stale entry for a route the template no longer ships).
 
+### Adopting an existing site
+
+A site that create-ailk did not scaffold, or that was scaffolded before
+`--topology` existed, does not record its topology. Every create-ailk command
+then treats it as a hub — wrong for a site that was trimmed to a spoke by hand.
+`adopt` records it, once:
+
+```bash
+# a site with a .ailk-site-manifest.json (default target: cwd)
+create-ailk adopt ./my-site
+# a site with none: name its template, and its modules when
+# architecture.yaml's "# Modules:" header is missing or out of date
+create-ailk adopt ./my-site --template person-service --modules marketing,docs-blog
+```
+
+It writes two fields into `.ailk-site-manifest.json` (and, on a spoke, the
+`env_contract` rows below):
+
+- `topology` is read from the tree. No `apps/api` and no `database/` is a
+  spoke; both is a hub; one without the other is refused.
+- `patternVersion` is the create-ailk version you ran — the version the site
+  was adopted against.
+
+A site with a manifest keeps every other byte of it. A site with none gets one,
+built the way a scaffold builds it, from `--template` and the module set
+(`--modules`, else the `architecture.yaml` header). `--template` and
+`--modules` are refused on a site that already has a manifest, because the
+manifest already records both. A root `TEMPLATE-MANIFEST.json` (the roster's
+older name) is refused until you rename it to `.ailk-site-manifest.json`.
+
+The report lists each generated seam file (`apps/web/lib/topology.generated.ts`,
+and the `apps/mcp` one when `apps/mcp` exists) as `present`, `differs` or
+`absent` against the render for the site's topology. On a spoke it also warns
+about each recorded module a spoke cannot carry. Neither changes the exit code:
+adopt records the site, it does not admit modules — `add-module` does that.
+
+On a spoke with a `project.yaml`, adopt also appends an `env_contract` row
+for every environment variable the site's code reads that has none, so the
+spoke's `pnpm env:declared` check has a contract to read. It never edits or
+removes a row, and a block it cannot read is refused with exit 2 before
+anything is written. A hub's `project.yaml` is never touched, and adopt does
+not install the check itself.
+
+Beyond that, adopt never writes a seam file, `architecture.yaml` or anything
+under `apps/api`, and never runs another command (`sync-routes --apply`
+included). A second run is refused with exit 2 and the manifest untouched.
+
+### Keeping a spoke current
+
+A spoke's scaffold-written files are few: the generated seams, the
+declared-env check (`tools/declared-env.ts`, `tools/check-declared-env.ts`)
+and the one-line route re-exports; everything else is content, or code that arrives
+through a `@working-theory/*` package bump. create-ailk does not re-scaffold a
+site in place, and there is no re-sync command: `add-module` never overwrites
+an edited file, so a re-sync could only report. Moving a spoke to a new
+create-ailk version is a per-version review instead:
+
+1. **Read the changesets.** A create-ailk changeset that changes what
+   create-ailk writes into a scaffold-written spoke file names each such file
+   on a line beginning `Scaffold-written files:`. Search the CHANGELOG between
+   your site's `patternVersion` and the new version for that line.
+2. **Check the routes.** `create-ailk sync-routes ./my-site` lists missing and
+   locally modified route directories without writing anything.
+3. **Apply each named change by hand**, then set `patternVersion` in
+   `.ailk-site-manifest.json` to the version the changes came from. It is a
+   one-value edit; `adopt` will not do it, because it refuses a second run.
+
+**Maintainer rule:** a create-ailk changeset that changes the content of a file
+create-ailk writes into a spoke scaffold — a seam render, a route re-export, a
+root-file transform — MUST carry a `Scaffold-written files:` line naming each
+such file, site-relative. This is a convention, not a lint.
+
+### Seeding a spoke's flows
+
+A spoke's flows live in its own repo as **declared data**: `flows/<slug>.json`,
+each one flow config exactly as the hub stores it — `slug`, `defaultLocale`,
+`steps`, and optionally `thankYou` and `flags`. The file name is the config's
+`slug` plus `.json`. A spoke carrying `signal-collectors` gets the module's
+`referral` and `fit-check` flows there (a hub gets them under
+`database/flows/`), plus a `flows/README.md`.
+
+`seed-flows` writes them into the spoke's hub workspace, as one rollout step:
+
+```bash
+AILK_SPOKE_KEY=<the spoke's key> create-ailk seed-flows ./my-spoke
+create-ailk seed-flows ./my-spoke --dry-run   # check the files, send nothing
+```
+
+- The key is read from `AILK_SPOKE_KEY` only — never a flag or a file — and
+  never printed.
+- The hub origin is `--hub-url`, else `AILK_API_URL`, else the `AILK_API_URL=`
+  line of `apps/web/.env.local`; it must be `https:` (or `http:` on a loopback
+  host). The first line printed names it and its source, before any request.
+- Each flow is sent to `PUT <hub>/v1/flows/<slug>/definition` and prints
+  `created`, `updated` or `unchanged`, so a re-run is safe. A failure prints
+  only its status and code, and the rest still run.
+- Exit 0 when every flow was accepted, 1 when any failed, 2 on a refusal (a hub
+  site, a bad file, no key, no valid hub origin), which sends nothing.
+
+The hub must have `AILK_SPOKE_FLOW_SEED=true`; until it does and this has run,
+the spoke's `/flows/<slug>` links reach no flow. The repo owns each flow's
+config: the next seed that differs overwrites an Admin edit to it. The hub
+refuses any block it acts on outside the spoke's own pages — emails,
+deliverables, pricing, registers, listings — so a flow that needs one is
+authored in the hub's Admin; once it carries one, the hub refuses a seed of
+that flow (`409 slug_owned`) rather than delete the block.
+
+### A spoke's declared environment
+
+A spoke scaffold's `pnpm preflight` and CI run `pnpm env:declared`: every
+literal `process.env` read in the site's code needs a row in `project.yaml`'s
+`env_contract` block (`name`, a one-line `description`, `secret: true` or
+`false`, and optionally `scope: web | api | mcp`). Platform names (`NODE_ENV`,
+`CI`, `PORT`, `VERCEL` and `VERCEL_*`, `NEXT_RUNTIME`, `NEXT_PHASE`) need
+none. `NEXT_PUBLIC_AILK_API_URL` is refused on a spoke, read or declared: a
+spoke reaches its hub through the server-only `AILK_API_URL`.
+
+create-ailk writes the rows for what it ships — at scaffold time, and again
+whenever `add-module`, `add-route` or `sync-routes --apply` adds code to a
+spoke — and only ever appends: a row you edit is yours. Add a row by hand for
+a variable your own code reads. `env_contract` is its own key; it does not
+change what `required_secrets` means. A hub scaffold carries no block, no
+check and no step.
+
 ## Paid modules require `AILK_LICENSE_KEY`
 
 `src/lib/module-tier.ts` splits a requested module set into its free and paid

package/dist/add-module.js

@@ -32,14 +32,17 @@ import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-cor
 import { deriveArchitecture } from "./derive-architecture.js";
 import { LEGACY_NAV_RENDERERS } from "./legacy-nav-renderers.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
+import { appendEnvRows } from "./lib/declared-env.js";
 import { diffTwoStrings, extractModuleBundle, } from "./lib/extract-module-bundle.js";
 import { normalizeModules } from "./module-architecture.js";
 import { PAID_SECTIONS_PATH, writePaidSections } from "./paid-sections.js";
 import { ParseError, parseModules } from "./parse-args.js";
+import { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_ROSTER_PATH, moduleRosterRows, planRosterAppend, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
+import { spokeCheckoutSite, spokeEnvRowOptions, writeSpokeCheckoutSlice, } from "./spoke-checkout.js";
 import { MODULE_SURFACES, NAV_CONFIG_PATH, readNavConfigStamp, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
-import { TopologyError, isSpokeExcluded, readSiteTopology, spokeModuleRefusal, } from "./topology.js";
+import { TopologyError, isSpokeExcluded, readSiteTopology, readSpokeShape, spokeDestination, spokeModuleRefusal, } from "./topology.js";
 /**
  * The site's topology for add-module (#7426 D13): an unreadable manifest is a
  * refusal this command names (exit 2), before the first write — the same
@@ -55,6 +58,20 @@ export function addModuleSiteTopology(targetDir) {
         throw err;
     }
 }
+/**
+ * The site's spoke options for add-module (#7894 D1) — `readSpokeShape`, with
+ * an unreadable manifest refused the way `addModuleSiteTopology` refuses it.
+ */
+function addModuleSpokeShape(targetDir) {
+    try {
+        return readSpokeShape(targetDir);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new AddModuleRefusedError(err.message);
+        throw err;
+    }
+}
 export { AddModuleRefusedError, readArchitectureHeader };
 /** `package.json` paths a `json` patch may write under the plus-config policy. */
 const PACKAGE_JSON_PATCH_KEYS = new Set([
@@ -104,10 +121,9 @@ export async function applyModuleToScaffold(opts) {
     const archPath = join(targetAbs, "architecture.yaml");
     // #7426 D13 — a spoke stays a spoke: a module it does not admit is refused
     // before the first write, and an admitted one lands through the spoke
-    // filter. `mcp` follows whether the spoke still carries apps/mcp.
-    const spoke = addModuleSiteTopology(targetAbs) === "spoke"
-        ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
-        : undefined;
+    // filter. `mcp` follows whether the spoke still carries apps/mcp, and the
+    // sign-in mode is the manifest's (#7894 D1).
+    const spoke = addModuleSpokeShape(targetAbs);
     if (spoke !== undefined) {
         const refusal = spokeModuleRefusal(opts.moduleName);
         if (refusal !== undefined)
@@ -140,9 +156,28 @@ export async function applyModuleToScaffold(opts) {
         existingFilePolicy: "skip-existing",
         checkPatches: checkPlusConfigPatches,
         ...(spoke !== undefined
-            ? { skip: (destination) => isSpokeExcluded(destination, spoke) }
+            ? {
+                skip: (destination) => isSpokeExcluded(destination, spoke),
+                // #7876 D10 — a module flow file lands in flows/ as declared data.
+                remapDestination: spokeDestination,
+            }
             : {}),
     });
+    // #7838 D8 — commerce on a spoke brings the spoke's own checkout, stamped
+    // from the site directory's name (the `projectName` scaffold() defaults to).
+    // A file the site already has is left as it is.
+    const spokeCommerce = spoke !== undefined && opts.moduleName === "commerce";
+    const checkoutRows = spokeCommerce
+        ? writeSpokeCheckoutSlice(targetAbs, {
+            site: spokeCheckoutSite(basename(targetAbs)),
+            versions: opts.versions,
+        })
+        : [];
+    // #7876 D9 — a spoke that just gained the flow stepper says what its
+    // flows/ is and how its rollout seeds it; an edited README is kept.
+    if (spoke !== undefined && opts.moduleName === "signal-collectors") {
+        writeSpokeFlowsReadme(targetAbs);
+    }
     const routes = syncRoutes({
         targetDir: targetAbs,
         templatesDir: opts.templatesDir,
@@ -169,7 +204,7 @@ export async function applyModuleToScaffold(opts) {
     writePaidSections(targetAbs);
     const registryChanged = existsSync(registryPath) &&
         readFileSync(registryPath, "utf8") !== registryBefore;
-    const rows = [...report];
+    const rows = [...report, ...checkoutRows];
     if (registryChanged)
         rows.push({ path: PAID_SECTIONS_PATH, action: "written" });
     const navRow = syncNavConfig(targetAbs, current.surfaces, surfaces);
@@ -223,6 +258,16 @@ export async function applyModuleToScaffold(opts) {
             templatesDir: opts.templatesDir,
         });
     }
+    // #7874 D9 — a spoke declares what the bundle reads, as the last write. A
+    // malformed env_contract block throws EnvContractError naming its line;
+    // the files written above stay, and `pnpm env:declared` names the same fault.
+    // A commerce spoke also declares what the checkout package reads (#7838 D9).
+    if (spoke !== undefined) {
+        appendEnvRows(targetAbs, {
+            topology: "spoke",
+            ...spokeEnvRowOptions(spokeCommerce),
+        });
+    }
     return { targetDir: targetAbs, modules, report: rows, routes, roster };
 }
 /**

package/dist/add-route.js

@@ -33,6 +33,8 @@ import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader, syncNavConfig, } from "./add-module.js";
 import { isTextFile } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
 import { ParseError } from "./parse-args.js";
 import { substituteMarkers } from "./substitute.js";
@@ -124,6 +126,12 @@ export function addRouteToScaffold(opts) {
     // written only once every other step has landed. A spoke's `syncRoutes`
     // call above already skipped what it lacks (#7426 D13).
     writeFileSync(archPath, deriveArchitecture(current.modules, surfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
+    // #7874 D9 — a spoke declares what the route reads. A malformed
+    // env_contract block throws EnvContractError naming its line; the files
+    // written above stay, and `pnpm env:declared` names the same fault.
+    if (spoke !== undefined) {
+        appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+    }
     return { targetDir: targetAbs, route, surfaces, report, routes };
 }
 /** The canonical id for one route argument, refusing an unknown one. */

package/dist/adopt.d.ts

@@ -0,0 +1,74 @@
+import { type Topology } from "./topology.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export declare class AdoptRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface AdoptOptions {
+    /** The existing site. */
+    targetDir: string;
+    /** The package's `templates/` dir, for the manifest writer. */
+    templatesDir: string;
+    /** The package's `site-templates/` dir, for the manifest writer. */
+    siteTemplatesDir: string;
+    /** `--template` — required, and only allowed, when the site has no manifest. */
+    template?: string | undefined;
+    /** `--modules`, comma-separated — only allowed when the site has no manifest. */
+    modules?: string | undefined;
+}
+/** A generated seam file's state against the render for the derived topology. */
+export interface AdoptSeam {
+    path: string;
+    state: "present" | "differs" | "absent";
+}
+export interface AdoptResult {
+    /** Resolved absolute path to the site. */
+    targetDir: string;
+    /** The site-relative manifest written. */
+    path: string;
+    topology: Topology;
+    patternVersion: string;
+    /** Whether the manifest was created (no manifest before) or gained the two fields. */
+    created: boolean;
+    /** One per seam file whose app directory exists (D8) — information only. */
+    seams: AdoptSeam[];
+    /** One per recorded module a spoke cannot carry (D6) — never a refusal. */
+    warnings: string[];
+    /** What adopt did to a spoke's `project.yaml` `env_contract` (#7874 D9). */
+    env: AdoptEnvResult;
+}
+/** What adopt did to `project.yaml` (#7874 D9): only a spoke's is written. */
+export type AdoptEnvResult = {
+    state: "written";
+    added: string[];
+} | {
+    state: "unchanged";
+} | {
+    state: "no-project-yaml";
+} | {
+    state: "hub";
+};
+/**
+ * Adopt the site at `opts.targetDir`: write the manifest recording its
+ * topology and pattern version. Every refusal throws before the one write.
+ *
+ * @throws AdoptRefusedError (exit 2) on a refusal this command names, and
+ *   the `AddModuleRefusedError` (exit 2) the roster readers and manifest
+ *   writer throw on a manifest they cannot read or extend.
+ */
+export declare function adoptSite(opts: AdoptOptions): AdoptResult;
+/** The printed report: the path written, the record, the seams, the warnings. */
+export declare function formatAdoptReport(result: AdoptResult): string;
+export interface AdoptArgs {
+    /** Positional target directory; undefined = the caller's cwd. */
+    target: string | undefined;
+    template: string | undefined;
+    modules: string | undefined;
+    help: boolean;
+}
+export declare const ADOPT_HELP = "create-ailk adopt \u2014 record what an existing site is, once.\n\nUsage:\n  create-ailk adopt [<target-dir>] [--template <name>] [--modules <a,b>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --template <name>        The template the site was built from. Required\n                           when the site has no .ailk-site-manifest.json;\n                           refused when it has one.\n  --modules <a,b>          The site's module set, when it has no manifest.\n                           Overrides architecture.yaml's \"# Modules:\" header.\n  --help, -h               Print this message.\n\nWrites \"topology\" and \"patternVersion\" into .ailk-site-manifest.json. On a\nspoke it also appends an env_contract row to project.yaml for every\nenvironment variable the site's code reads that has none, so pnpm\nenv:declared has a contract to check; it never edits or removes a row, and\nit never touches a hub's project.yaml. Nothing else is written. The\ntopology is read from the tree: no apps/api and no database/ is a spoke,\nboth is a hub, one without the other is refused.\npatternVersion is this create-ailk's version. A site with no manifest gets\none, built the way a scaffold builds it. A manifest that already records\neither field is refused: adopt runs once. A recorded module a spoke cannot\ncarry is a warning, not a refusal.\n";
+/**
+ * Parse the argv AFTER the `adopt` word. Strict `node:util` parseArgs, like
+ * `parseAddRouteArgs`; the values themselves are validated by `adoptSite`.
+ */
+export declare function parseAdoptArgs(argv: string[]): AdoptArgs;

package/dist/adopt.js

@@ -0,0 +1,314 @@
+/**
+ * `create-ailk adopt [<target-dir>]` — record, once, what an existing site
+ * is (#7875).
+ *
+ * A site scaffolded before #7426, or not scaffolded by create-ailk at all,
+ * has no `topology` in its `.ailk-site-manifest.json`, so every create-ailk
+ * command that asks `readSiteTopology` treats it as a hub — wrong for a site
+ * trimmed to a spoke by hand. Adopt writes the two fields the keystone added
+ * (D10 of spec 7426), and nothing else:
+ *
+ *   - `topology` is derived from the tree against `SPOKE_REMOVED_ROOTS`
+ *     (D1) — all removed roots absent is a spoke, all present a hub, a mix
+ *     is refused. Never a flag: the tree is the evidence;
+ *   - `patternVersion` is the running create-ailk version, the value a
+ *     scaffold records (D8 — on an adopted site, the version it was adopted
+ *     against);
+ *   - an existing manifest gains the two fields, every other byte kept
+ *     (`planTopologyRecord`, D3); a site with none gets one built by the
+ *     scaffold's own writer from `--template` and the module set
+ *     (`planAdoptedSiteManifest`, D4/D5);
+ *   - a manifest already recording either field is refused (D2): adopt runs
+ *     once. A recorded module a spoke cannot carry is a warning, never a
+ *     refusal (D6) — `add-module` is the admission gate, not adopt.
+ *
+ * It writes the manifest — never a seam file, `architecture.yaml`, anything
+ * under `apps/api`, and never another subcommand (`sync-routes --apply`
+ * included). The one exception is a spoke's `project.yaml` (#7874 D9): on a
+ * site it derives as a spoke, adopt also appends an `env_contract` row for
+ * every env var the site's code reads that has none, so its `pnpm
+ * env:declared` check has a contract to read. A hub's `project.yaml` is never
+ * touched. Every refusal throws before any write.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly — the
+ * package-rooted directories are supplied by the CLI, the `add-route.ts`
+ * split. Spec: docs/specs/7875-create-ailk-adopt-spec.md.
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { readArchitectureHeader } from "./add-module-core.js";
+import { buildScaffoldMarkers } from "./copy.js";
+import { EnvContractError, planEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
+import { normalizeModules } from "./module-architecture.js";
+import { ParseError, RECOGNIZED_MODULES, } from "./parse-args.js";
+import { planAdoptedSiteManifest, planTopologyRecord, } from "./site-manifest.js";
+import { LEGACY_SITE_ROSTER_PATH, SITE_ROSTER_PATH, readSiteRoster, resolveRosterTemplate, } from "./site-roster.js";
+import { SHAPE_STARTERS } from "./template-manifest.js";
+import { MCP_SEAM_PATH, SPOKE_REMOVED_ROOTS, WEB_SEAM_PATH, renderMcpSeam, renderWebSeam, spokeModuleRefusal, } from "./topology.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export class AdoptRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "AdoptRefusedError";
+    }
+}
+/** The generated seam files, by the app directory each lives in, with their renders. */
+const SEAMS = [
+    { app: "apps/web", path: WEB_SEAM_PATH, render: renderWebSeam },
+    { app: "apps/mcp", path: MCP_SEAM_PATH, render: renderMcpSeam },
+];
+function isDirectory(path) {
+    return existsSync(path) && statSync(path).isDirectory();
+}
+/**
+ * D1 — the topology the tree shows: every `SPOKE_REMOVED_ROOTS` entry absent
+ * is a spoke, every one present a hub. Anything else is refused.
+ */
+function deriveTopology(targetDir) {
+    const present = SPOKE_REMOVED_ROOTS.filter((root) => isDirectory(join(targetDir, root)));
+    if (present.length === 0)
+        return "spoke";
+    if (present.length === SPOKE_REMOVED_ROOTS.length)
+        return "hub";
+    const absent = SPOKE_REMOVED_ROOTS.filter((root) => !present.includes(root));
+    throw new AdoptRefusedError(`adopt: ${targetDir} has ${present.join(", ")} but not ${absent.join(", ")}, so it is neither a hub nor a spoke`);
+}
+/** D5 — the module set for a site with no manifest: `--modules`, else the header. */
+function moduleSet(targetDir, flag) {
+    if (flag !== undefined) {
+        try {
+            return normalizeModules(flag.split(","));
+        }
+        catch (err) {
+            throw new AdoptRefusedError(`--modules is not a module list: ${err.message}`);
+        }
+    }
+    const archPath = join(targetDir, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new AdoptRefusedError(`${targetDir} has no architecture.yaml to read its module set from; name it with --modules <a,b>`);
+    }
+    try {
+        return readArchitectureHeader(readFileSync(archPath, "utf8")).modules;
+    }
+    catch (err) {
+        throw new AdoptRefusedError(`${err.message.replace(/\.$/, "")}. Name the module set with --modules <a,b> instead.`);
+    }
+}
+/** The recorded module names this package recognizes; anything else is ignored. */
+function recordedModules(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((m) => RECOGNIZED_MODULES.includes(m));
+}
+/**
+ * Adopt the site at `opts.targetDir`: write the manifest recording its
+ * topology and pattern version. Every refusal throws before the one write.
+ *
+ * @throws AdoptRefusedError (exit 2) on a refusal this command names, and
+ *   the `AddModuleRefusedError` (exit 2) the roster readers and manifest
+ *   writer throw on a manifest they cannot read or extend.
+ */
+export function adoptSite(opts) {
+    const targetDir = resolve(opts.targetDir);
+    if (!isDirectory(targetDir)) {
+        throw new Error(`adopt target is not a directory: ${targetDir}. Point adopt at an existing site.`);
+    }
+    const topology = deriveTopology(targetDir);
+    const markers = buildScaffoldMarkers(basename(targetDir));
+    const patternVersion = markers["CREATE_AILK_VERSION"];
+    if (patternVersion === undefined || patternVersion === "") {
+        // A once-only field: never record an empty version a second run cannot fix.
+        throw new Error("adopt: this create-ailk has no version to record");
+    }
+    const record = { topology, patternVersion };
+    const roster = readSiteRoster(targetDir);
+    let text;
+    let modules;
+    if (roster !== undefined) {
+        if (roster.path === LEGACY_SITE_ROSTER_PATH) {
+            throw new AdoptRefusedError(`${LEGACY_SITE_ROSTER_PATH} is the pre-#6658 roster name; rename it to ${SITE_ROSTER_PATH}, then re-run adopt.`);
+        }
+        for (const key of ["topology", "patternVersion"]) {
+            if (key in roster.doc) {
+                throw new AdoptRefusedError(`${roster.path} already records "${key}", so this site is already adopted. To move it to a new create-ailk version, see the README § Keeping a spoke current.`);
+            }
+        }
+        for (const [flag, value] of [
+            ["--template", opts.template],
+            ["--modules", opts.modules],
+        ]) {
+            if (value !== undefined) {
+                throw new AdoptRefusedError(`${roster.path} already records the site's template and modules; ${flag} would contradict it. Re-run adopt without ${flag}.`);
+            }
+        }
+        text = planTopologyRecord(roster.text, record, roster.path);
+        modules = recordedModules(roster.doc["modules"]);
+    }
+    else {
+        if (opts.template === undefined) {
+            throw new AdoptRefusedError(`${targetDir} has no ${SITE_ROSTER_PATH}; name the template it was built from with --template <name> (one of: ${Object.keys(SHAPE_STARTERS).join(", ")}).`);
+        }
+        try {
+            resolveRosterTemplate(opts.template);
+        }
+        catch (err) {
+            throw new AdoptRefusedError(`--template "${opts.template}" names no declared template: ${err.message}`);
+        }
+        modules = moduleSet(targetDir, opts.modules);
+        text = planAdoptedSiteManifest({
+            targetDir,
+            template: opts.template,
+            modules,
+            ...record,
+            siteTemplatesDir: opts.siteTemplatesDir,
+            templatesDir: opts.templatesDir,
+            markers,
+        });
+    }
+    const warnings = topology === "spoke"
+        ? modules.flatMap((m) => spokeModuleRefusal(m) ?? [])
+        : [];
+    const seams = SEAMS.filter(({ app }) => isDirectory(join(targetDir, app))).map(({ path, render }) => {
+        const abs = join(targetDir, path);
+        if (!existsSync(abs))
+            return { path, state: "absent" };
+        return {
+            path,
+            state: readFileSync(abs, "utf8") === render(topology) ? "present" : "differs",
+        };
+    });
+    // #7874 D9 — a spoke's env_contract rows, planned before any write: a
+    // block adopt cannot read is a refusal, and nothing is written.
+    const yamlPath = join(targetDir, "project.yaml");
+    let env = { state: "hub" };
+    let yamlNext;
+    if (topology === "spoke") {
+        if (!existsSync(yamlPath)) {
+            env = { state: "no-project-yaml" };
+        }
+        else {
+            const yamlText = readFileSync(yamlPath, "utf8");
+            try {
+                const plan = planEnvRows(targetDir, yamlText, {
+                    topology,
+                    catalog: ENV_CATALOG,
+                });
+                if (plan.text === yamlText) {
+                    env = { state: "unchanged" };
+                }
+                else {
+                    env = { state: "written", added: plan.added };
+                    yamlNext = plan.text;
+                }
+            }
+            catch (err) {
+                if (err instanceof EnvContractError) {
+                    throw new AdoptRefusedError(`adopt: ${err.message}`);
+                }
+                throw err;
+            }
+        }
+    }
+    writeFileSync(join(targetDir, SITE_ROSTER_PATH), text);
+    if (yamlNext !== undefined)
+        writeFileSync(yamlPath, yamlNext);
+    return {
+        targetDir,
+        path: SITE_ROSTER_PATH,
+        topology,
+        patternVersion,
+        created: roster === undefined,
+        seams,
+        warnings,
+        env,
+    };
+}
+/** The printed report: the path written, the record, the seams, the warnings. */
+export function formatAdoptReport(result) {
+    const lines = [
+        `[create-ailk] adopt → ${result.targetDir}`,
+        `${result.created ? "Wrote" : "Updated"} ${result.path}`,
+        `  topology: ${result.topology}`,
+        `  patternVersion: ${result.patternVersion}`,
+    ];
+    if (result.seams.length > 0) {
+        lines.push(`Seam files (against the ${result.topology} render):`);
+        const width = Math.max(...result.seams.map((s) => s.path.length));
+        lines.push(...result.seams.map((s) => `  ${s.path.padEnd(width)}  ${s.state}`));
+    }
+    const env = formatAdoptEnv(result.env);
+    if (env !== undefined)
+        lines.push(env);
+    lines.push(...result.warnings.map((w) => `warning: ${w}`));
+    return lines.join("\n") + "\n";
+}
+/** The report's one env_contract line (#7874 D9); none on a hub. */
+function formatAdoptEnv(env) {
+    switch (env.state) {
+        case "written":
+            return `env_contract: ${env.added.length} rows added (${env.added.join(", ")})`;
+        case "unchanged":
+            return "env_contract: every read already declared";
+        case "no-project-yaml":
+            return "env_contract: no project.yaml, nothing written";
+        case "hub":
+            return undefined;
+    }
+}
+export const ADOPT_HELP = `create-ailk adopt — record what an existing site is, once.
+
+Usage:
+  create-ailk adopt [<target-dir>] [--template <name>] [--modules <a,b>]
+
+Arguments:
+  <target-dir>             The existing site. Defaults to the current dir.
+
+Options:
+  --template <name>        The template the site was built from. Required
+                           when the site has no .ailk-site-manifest.json;
+                           refused when it has one.
+  --modules <a,b>          The site's module set, when it has no manifest.
+                           Overrides architecture.yaml's "# Modules:" header.
+  --help, -h               Print this message.
+
+Writes "topology" and "patternVersion" into .ailk-site-manifest.json. On a
+spoke it also appends an env_contract row to project.yaml for every
+environment variable the site's code reads that has none, so pnpm
+env:declared has a contract to check; it never edits or removes a row, and
+it never touches a hub's project.yaml. Nothing else is written. The
+topology is read from the tree: no apps/api and no database/ is a spoke,
+both is a hub, one without the other is refused.
+patternVersion is this create-ailk's version. A site with no manifest gets
+one, built the way a scaffold builds it. A manifest that already records
+either field is refused: adopt runs once. A recorded module a spoke cannot
+carry is a warning, not a refusal.
+`;
+/**
+ * Parse the argv AFTER the `adopt` word. Strict `node:util` parseArgs, like
+ * `parseAddRouteArgs`; the values themselves are validated by `adoptSite`.
+ */
+export function parseAdoptArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            template: { type: "string" },
+            modules: { type: "string" },
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`adopt takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        template: parsed.values.template,
+        modules: parsed.values.modules,
+        help: parsed.values.help === true,
+    };
+}