create-ailk 0.14.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/component-catalog.json

@@ -5235,8 +5235,7 @@
                 }
               },
               "required": [
-                "title",
-                "description"
+                "title"
               ]
             }
           },
@@ -7378,7 +7377,8 @@
             "type": "string",
             "enum": [
               "default",
-              "sm"
+              "sm",
+              "lg"
             ]
           },
           "surface": {

package/dist/add-module.d.ts

@@ -4,6 +4,13 @@ import { type ModulePatch } from "./module-architecture.js";
 import { type ModuleName } from "./parse-args.js";
 import type { MarkerMap, WorkspaceVersionMap } from "./substitute.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
+import { type Topology } 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
+ * posture as its unreadable-roster refusal.
+ */
+export declare function addModuleSiteTopology(targetDir: string): Topology;
 export { AddModuleRefusedError, readArchitectureHeader };
 /**
  * One report row: a bundle file written, patched or skipped, or a seed the

package/dist/add-module.js

@@ -32,13 +32,46 @@ 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, 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
+ * posture as its unreadable-roster refusal.
+ */
+export function addModuleSiteTopology(targetDir) {
+    try {
+        return readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new AddModuleRefusedError(err.message);
+        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([
@@ -86,6 +119,16 @@ export function checkPlusConfigPatches(patches) {
 export async function applyModuleToScaffold(opts) {
     const targetAbs = resolve(opts.targetDir);
     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, 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)
+            throw new AddModuleRefusedError(refusal);
+    }
     const current = readArchitectureHeader(readFileSync(archPath, "utf8"));
     const modules = normalizeModules([...current.modules, opts.moduleName]);
     // Resolved before the first write: a header surface that is unknown, or
@@ -112,7 +155,29 @@ export async function applyModuleToScaffold(opts) {
         markers: opts.markers,
         existingFilePolicy: "skip-existing",
         checkPatches: checkPlusConfigPatches,
+        ...(spoke !== undefined
+            ? {
+                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,
@@ -123,10 +188,12 @@ export async function applyModuleToScaffold(opts) {
     // #6107 D8 — a module that brings `apps/admin` brings its auth hard-fail;
     // the Admin app gets the web app's effective secret, and a secret already
     // held in any Next-loaded env file is never shadowed.
-    writeAuthSecretFile(targetAbs);
+    // A spoke has no sign-in (#7426 D13), so it gets no secret.
+    if (spoke === undefined)
+        writeAuthSecretFile(targetAbs);
     // The same composition `syncArchitectureSync` writes — a pure function of
     // the module set, so an unchanged set rewrites identical bytes.
-    writeFileSync(archPath, deriveArchitecture(modules, surfaces));
+    writeFileSync(archPath, deriveArchitecture(modules, surfaces, spoke !== undefined ? { topology: "spoke", mcp: spoke.mcp } : {}));
     // #7536 D3 — the paid-sections registry follows `apps/web/package.json`,
     // which the bundle's `patches` just edited. Generated and always
     // overwritten, like `architecture.yaml` above.
@@ -137,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);
@@ -191,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,12 +33,15 @@ 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";
 import { GATEABLE_SURFACES, MODULE_SURFACES, parseSurfaces, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR } from "./template-manifest.js";
+import { TopologyError, readSiteTopology } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
 export class AddRouteRefusedError extends Error {
     exitCode = 2;
@@ -64,6 +67,20 @@ export function addRouteToScaffold(opts) {
     if (!existsSync(archPath)) {
         throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
     }
+    // #7426 D13 — a spoke stays a spoke. Read before the first write: an
+    // unreadable manifest is a refusal this command names (exit 2).
+    let spoke;
+    try {
+        spoke =
+            readSiteTopology(targetAbs) === "spoke"
+                ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+                : undefined;
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new AddRouteRefusedError(err.message);
+        throw err;
+    }
     const route = canonicalRoute(opts.route);
     const owner = Object.entries(MODULE_SURFACES).find(([, surfaces]) => surfaces.includes(route))?.[0];
     let current;
@@ -106,8 +123,15 @@ export function addRouteToScaffold(opts) {
     if (navRow !== undefined)
         report.push(navRow);
     // Last: the declared header is what makes a rerun a no-op, so it is
-    // written only once every other step has landed.
-    writeFileSync(archPath, deriveArchitecture(current.modules, surfaces));
+    // 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;