create-ailk 0.14.0 → 0.16.0

package/dist/site-manifest.js

@@ -15,6 +15,13 @@
  *     (`resolveModuleSet` / `deriveLevel`). Never inferred from `modules`:
  *     the level comes only from the key. An alias or `--modules` keep run
  *     derives none and records none;
+ *   - `topology` and `patternVersion` (#7426 D10) — `"hub"` or `"spoke"`,
+ *     and the create-ailk version that wrote the files, on every scaffold.
+ *     A site with no `topology` predates the option and reads as a hub
+ *     (`topology.ts` `readSiteTopology`);
+ *   - `signIn` (#7894 D1) — `"hub"` on a spoke that signs in through its
+ *     hub, written after `topology` on such a spoke only; absent reads as
+ *     `"off"` (`topology.ts` `readSpokeShape`);
  *   - a row for every route present on disk — each module's contributed rows
  *     through `planRosterAppend` (add-module's own append), the sample pages
  *     a module's bundle installs (`sampleRows`), and a code-route row for any
@@ -31,7 +38,7 @@ import { join, relative, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { AddModuleRefusedError } from "./add-module-core.js";
 import { MODULE_SLICES, normalizeModules } from "./module-architecture.js";
-import { moduleRosterRows, planRosterAppend, } from "./site-roster.js";
+import { SITE_ROSTER_PATH, moduleRosterRows, parseSiteRoster, planRosterAppend, resolveRosterTemplate, } from "./site-roster.js";
 import { TEMPLATE_MANIFESTS, rosterDeclares, templateTreeDir, } from "./template-manifest.js";
 /** Prettier's default print width — the generator formats the manifest with it. */
 const PRINT_WIDTH = 80;
@@ -51,16 +58,24 @@ const CODE_ROUTE_ROW = {
     sections: [],
 };
 /**
- * The manifest's next text: `modules` (and `level`, when derived) after
- * `requires`, and a row for every route present on disk.
+ * The manifest's next text: `modules` (and `level`, when derived), then
+ * `topology` and `patternVersion`, after `requires`, and a row for every
+ * route present on disk.
  *
- * @throws AddModuleRefusedError when the file already records `modules` or
- *   `level`, or its layout is not the generator's (`rows` last, `requires`
- *   at the top level) — guessing would silently mis-record the site.
+ * @throws AddModuleRefusedError when the file already records `modules`,
+ *   `level`, `topology` or `patternVersion`, or its layout is not the
+ *   generator's (`rows` last, `requires` at the top level) — guessing would
+ *   silently mis-record the site.
  */
 export function planSiteManifest(opts) {
     const { roster } = opts;
-    for (const key of ["modules", "level"]) {
+    for (const key of [
+        "modules",
+        "level",
+        "topology",
+        "signIn",
+        "patternVersion",
+    ]) {
         if (key in roster.doc) {
             throw new AddModuleRefusedError(`${roster.path} already records "${key}"`);
         }
@@ -81,7 +96,91 @@ export function planSiteManifest(opts) {
         ...codeRouteRows(opts.targetDir, declared),
     ];
     const withRows = appendRows(appended, extra, roster);
-    return insertRecord(withRows, opts.modules, opts.level, roster.path);
+    return insertRecord(withRows, opts, roster.path);
+}
+/** The top-level keys `planSiteManifest` writes before the topology record, in order. */
+const RECORD_ANCHORS = ["requires", "modules", "level"];
+/**
+ * `text` with `topology` and `patternVersion` inserted directly after the
+ * last of `requires`, `modules`, `level` the file records — the position
+ * `planSiteManifest` gives them (#7875 D3). Every other byte is the input's.
+ *
+ * @throws AddModuleRefusedError when the file already records either field,
+ *   records none of the anchor keys, records one more than once at the top
+ *   level, or the result does not read back the two values exactly.
+ */
+export function planTopologyRecord(text, record, label) {
+    const doc = JSON.parse(text);
+    for (const key of ["topology", "patternVersion"]) {
+        if (key in doc) {
+            throw new AddModuleRefusedError(`${label} already records "${key}"`);
+        }
+    }
+    let end = -1;
+    for (const key of RECORD_ANCHORS) {
+        if (!(key in doc))
+            continue;
+        const anchor = `\n  ${JSON.stringify(key)}: `;
+        const at = text.indexOf(anchor);
+        if (at === -1 || text.indexOf(anchor, at + 1) !== -1) {
+            throw new AddModuleRefusedError(`${label} has no single top-level "${key}" key to record the topology beside`);
+        }
+        const start = at + anchor.length;
+        const close = text[start] === "[" ? "]" : '"';
+        end = Math.max(end, text.indexOf(close, start + 1) + 1);
+    }
+    if (end === -1) {
+        throw new AddModuleRefusedError(`${label} has no top-level "requires" key to record the topology beside`);
+    }
+    const next = text.slice(0, end) +
+        `,\n  "topology": ${JSON.stringify(record.topology)}` +
+        `,\n  "patternVersion": ${JSON.stringify(record.patternVersion)}` +
+        text.slice(end);
+    let after;
+    try {
+        after = JSON.parse(next);
+    }
+    catch {
+        after = {};
+    }
+    if (after["topology"] !== record.topology ||
+        after["patternVersion"] !== record.patternVersion) {
+        throw new AddModuleRefusedError(`${label}: the topology could not be recorded after its last top-level key`);
+    }
+    return next;
+}
+/**
+ * The manifest for a site that has none (#7875 D4): a seed naming the
+ * template, its `requires` and no rows, parsed the way `readSiteRoster`
+ * reads a manifest, then `planSiteManifest` over it — so module rows, sample
+ * rows and a code-route row per page route on disk arrive exactly as a
+ * scaffold's would. No `level` (it comes only from a licence key), and none
+ * of the template's `shape`, `design`, `categories`, `layout` or `theme`:
+ * they would claim a look the site may not wear.
+ *
+ * @throws AddModuleRefusedError when the template is undeclared, or as
+ *   `planSiteManifest` does.
+ */
+export function planAdoptedSiteManifest(opts) {
+    let requires;
+    try {
+        requires = resolveRosterTemplate(opts.template).requires;
+    }
+    catch (err) {
+        throw new AddModuleRefusedError(`"${opts.template}" names no declared template (${err.message})`);
+    }
+    const seed = `${renderJson({ template: opts.template, requires: [...requires], rows: [] }, 0)}\n`;
+    return planSiteManifest({
+        targetDir: opts.targetDir,
+        roster: parseSiteRoster(seed, SITE_ROSTER_PATH),
+        modules: opts.modules,
+        level: undefined,
+        topology: opts.topology,
+        patternVersion: opts.patternVersion,
+        siteTemplatesDir: opts.siteTemplatesDir,
+        templatesDir: opts.templatesDir,
+        markers: opts.markers,
+    });
 }
 /**
  * The rows for the sample pages a module's bundle installs through its
@@ -233,8 +332,12 @@ function appendRows(text, rows, roster) {
         ? text.slice(0, end) + rendered + roster.trail + text.slice(close)
         : text.slice(0, end) + "," + rendered + text.slice(end);
 }
-/** `text` with `modules` (and `level`, when derived) inserted after the top-level `requires`. */
-function insertRecord(text, modules, level, label) {
+/**
+ * `text` with `modules` (and `level`, when derived), `topology` and
+ * `patternVersion` inserted after the top-level `requires`.
+ */
+function insertRecord(text, opts, label) {
+    const { modules, level, topology, signIn, patternVersion } = opts;
     const anchor = '\n  "requires": ';
     const at = text.indexOf(anchor);
     if (at === -1 || text.indexOf(anchor, at + 1) !== -1) {
@@ -243,11 +346,17 @@ function insertRecord(text, modules, level, label) {
     const end = text.indexOf("]", at) + 1;
     const name = '"modules": ';
     const record = `,\n  ${name}${renderJson([...modules], 2, name.length, 1)}` +
-        (level !== undefined ? `,\n  "level": ${JSON.stringify(level)}` : "");
+        (level !== undefined ? `,\n  "level": ${JSON.stringify(level)}` : "") +
+        `,\n  "topology": ${JSON.stringify(topology)}` +
+        (signIn !== undefined ? `,\n  "signIn": ${JSON.stringify(signIn)}` : "") +
+        `,\n  "patternVersion": ${JSON.stringify(patternVersion)}`;
     const next = text.slice(0, end) + record + text.slice(end);
     const doc = JSON.parse(next);
     if (!isDeepStrictEqual(doc["modules"], [...modules]) ||
-        doc["level"] !== level) {
+        doc["level"] !== level ||
+        doc["topology"] !== topology ||
+        doc["signIn"] !== signIn ||
+        doc["patternVersion"] !== patternVersion) {
         throw new AddModuleRefusedError(`${label}: the module set could not be recorded beside "requires"`);
     }
     return next;

package/dist/site-roster.d.ts

@@ -58,6 +58,19 @@ export interface ModuleRosterRow {
  * not declare is refused: guessing would silently mis-roster the site.
  */
 export declare function readSiteRoster(targetDir: string): SiteRoster | undefined;
+/**
+ * The roster `text` holds, read as `readSiteRoster` reads the file at the
+ * site-relative `path` (#7875 D10) — the one parse, so a manifest `adopt`
+ * builds goes through the same template resolution a read one does.
+ */
+export declare function parseSiteRoster(text: string, path: string): SiteRoster;
+/**
+ * The registry entry a manifest's `template` names. #6757 D6 — a bare-shape
+ * starter's name (the shape itself) resolves through SHAPE_STARTERS first;
+ * `resolveTemplate` alone never sees one (NFR-3).
+ * @throws Error from `resolveTemplate` when the name is undeclared.
+ */
+export declare function resolveRosterTemplate(name: string): TemplateManifest;
 /** What `planSiteManifestDesign` writes when it rewrites the manifest. */
 export interface SiteManifestDesignNext {
     design: string;

package/dist/site-roster.js

@@ -11,6 +11,7 @@
  * does (#6646). This module owns every read and write of that file:
  *
  *   - `readSiteRoster` — the file, or `undefined` for a template-less site;
+ *     `parseSiteRoster` is its parse of given text (#7875 D10);
  *   - `moduleRosterRows` — a module's rows, read from the generator's own
  *     output in the shipped template manifests (never re-derived: the
  *     derivation needs a YAML parser the package does not ship, and would be
@@ -167,22 +168,35 @@ export function readSiteRoster(targetDir) {
     const path = [SITE_ROSTER_PATH, LEGACY_SITE_ROSTER_PATH].find((name) => existsSync(join(targetDir, name)));
     if (path === undefined)
         return undefined;
-    const file = parseRosterFile(readFileSync(join(targetDir, path), "utf8"), path);
-    const name = String(file.doc["template"]);
+    return parseSiteRoster(readFileSync(join(targetDir, path), "utf8"), path);
+}
+/**
+ * The roster `text` holds, read as `readSiteRoster` reads the file at the
+ * site-relative `path` (#7875 D10) — the one parse, so a manifest `adopt`
+ * builds goes through the same template resolution a read one does.
+ */
+export function parseSiteRoster(text, path) {
+    const file = parseRosterFile(text, path);
     let template;
     try {
-        // #6757 D6 — a bare-shape starter's name (the shape itself) resolves
-        // through SHAPE_STARTERS first; `resolveTemplate` alone never sees one
-        // (NFR-3).
-        template = Object.prototype.hasOwnProperty.call(SHAPE_STARTERS, name)
-            ? SHAPE_STARTERS[name]
-            : resolveTemplate(name);
+        template = resolveRosterTemplate(String(file.doc["template"]));
     }
     catch (err) {
         throw new AddModuleRefusedError(`${path} names no declared template (${err.message}), so the page roster is unknown`);
     }
     return { ...file, template, path };
 }
+/**
+ * The registry entry a manifest's `template` names. #6757 D6 — a bare-shape
+ * starter's name (the shape itself) resolves through SHAPE_STARTERS first;
+ * `resolveTemplate` alone never sees one (NFR-3).
+ * @throws Error from `resolveTemplate` when the name is undeclared.
+ */
+export function resolveRosterTemplate(name) {
+    return Object.prototype.hasOwnProperty.call(SHAPE_STARTERS, name)
+        ? SHAPE_STARTERS[name]
+        : resolveTemplate(name);
+}
 /** `value`, rendered the way prettier prints an object-only JSON value nested one level under the manifest's root object. */
 function renderManifestValue(value) {
     return JSON.stringify(value, null, 2)

package/dist/spoke-checkout.d.ts

@@ -0,0 +1,42 @@
+import type { EnvCatalogEntry, PlanEnvRowsOptions } from "./lib/declared-env.js";
+import { type InstallReportRow } from "./lib/extract-module-bundle.js";
+import { type WorkspaceVersionMap } from "./substitute.js";
+/** The checkout package a spoke's two route files import. */
+export declare const SPOKE_CHECKOUT_PACKAGE = "@working-theory/spoke-checkout";
+/** The site's checkout data — written once, the site's from then on. */
+export declare const SPOKE_CHECKOUT_CONFIG_PATH = "apps/web/lib/checkout-config.ts";
+/** The two return pages: Stripe's success URL and every refused buy's target. */
+export declare const SPOKE_CHECKOUT_PAGE_FILES: readonly string[];
+/** The variables a commerce spoke depends on (D9). The package reads three of them. */
+export declare const SPOKE_CHECKOUT_ENV_CATALOG: Readonly<Record<string, EnvCatalogEntry>>;
+/** The names a commerce spoke declares although only the package reads them (D9). */
+export declare const SPOKE_CHECKOUT_DECLARED_ENV: readonly string[];
+/**
+ * The catalog (and declared names) a spoke's `appendEnvRows` call passes: a
+ * commerce spoke adds the checkout's four rows (D9). `ENV_CATALOG` itself is
+ * unchanged — its test fails on an entry the monorepo's apps never read.
+ */
+export declare function spokeEnvRowOptions(commerce: boolean): Pick<PlanEnvRowsOptions, "catalog" | "declare">;
+/**
+ * The site stamp for a project name (D6): lower-cased, every run outside
+ * `a-z0-9` collapsed to `-`, trimmed, cut to 40. A name that leaves nothing
+ * usable — or `default`, which is also an unset hub's own stamp — gets
+ * `site-` and the first 8 hex characters of its SHA-256. Never `AILK_SITE_ID`.
+ */
+export declare function spokeCheckoutSite(projectName: string): string;
+/**
+ * The slice for `site`, in order: the two route files, the config, the two
+ * pages (D3). Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ */
+export declare function renderSpokeCheckoutFiles(site: string): [string, string][];
+/**
+ * Write the slice into `targetDir` (D3). A file that already exists is left
+ * byte-for-byte and reported `skipped` — the config is the site's once
+ * written. Adds the package to `apps/web/package.json` only when absent.
+ * Every refusal (an invalid stamp, a version map without the package, a
+ * missing or malformed `apps/web/package.json`) throws before the first write.
+ */
+export declare function writeSpokeCheckoutSlice(targetDir: string, opts: {
+    site: string;
+    versions: WorkspaceVersionMap;
+}): InstallReportRow[];

package/dist/spoke-checkout.js

@@ -0,0 +1,359 @@
+/**
+ * The spoke checkout slice (#7838) — what a spoke carrying `commerce` gets in
+ * `apps/web`: the buy route and the Stripe webhook route (the only two files
+ * allowed to import the checkout package, #7873), the site's own
+ * `lib/checkout-config.ts`, and the thank-you and unavailable return pages.
+ *
+ * Every guarantee lives in `@working-theory/spoke-checkout` and arrives by a
+ * package bump; these files are thin and, apart from the config's one stamp
+ * line, byte-identical across spokes at one create-ailk version (roadmap D3,
+ * AC-SPOKE-02). A hub never gets them: its checkout is `apps/api`'s.
+ *
+ * Spec: docs/specs/7838-spoke-web-checkout-slice-spec.md (D3–D7, D9).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly. Every
+ * package specifier in a rendered file is interpolated from a constant, so the
+ * monorepo's own architecture lint never reads a rendered line as an import
+ * create-ailk makes (the `CONTENT_ADAPTERS_PACKAGE` idiom in topology.ts).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SPOKE_CHECKOUT_ROUTE_FILES } from "./derive-architecture.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
+import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
+import { substituteWorkspaceVersions, } from "./substitute.js";
+import { TopologyError } from "./topology.js";
+/** The checkout package a spoke's two route files import. */
+export const SPOKE_CHECKOUT_PACKAGE = "@working-theory/spoke-checkout";
+const API_CLIENT_PACKAGE = "@working-theory/api-client";
+const UI_SECTIONS_PACKAGE = "@working-theory/ui/sections";
+const VALIDATION_PACKAGE = "@working-theory/validation";
+/** The site's checkout data — written once, the site's from then on. */
+export const SPOKE_CHECKOUT_CONFIG_PATH = "apps/web/lib/checkout-config.ts";
+/** The two return pages: Stripe's success URL and every refused buy's target. */
+export const SPOKE_CHECKOUT_PAGE_FILES = Object.freeze([
+    "apps/web/app/[locale]/checkout/thank-you/page.tsx",
+    "apps/web/app/[locale]/checkout/unavailable/page.tsx",
+]);
+/** The variables a commerce spoke depends on (D9). The package reads three of them. */
+export const SPOKE_CHECKOUT_ENV_CATALOG = Object.freeze({
+    STRIPE_SECRET_KEY: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: a test key (sk_test_ or rk_test_), or a restricted live key the operator sets with STRIPE_MODE=live.`,
+        secret: true,
+    },
+    STRIPE_WEBHOOK_SECRET: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: the signing secret of this site's Stripe webhook endpoint.`,
+        secret: true,
+    },
+    STRIPE_MODE: {
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: test (the default) or live. Live is the operator's switch, per site.`,
+        secret: false,
+    },
+    AILK_SPOKE_KEY: {
+        description: "The hub-issued key this site sends as x-ailk-spoke-key; the checkout fulfilment refuses to run without it. Never committed.",
+        secret: true,
+    },
+});
+/** The names a commerce spoke declares although only the package reads them (D9). */
+export const SPOKE_CHECKOUT_DECLARED_ENV = Object.freeze([
+    "STRIPE_SECRET_KEY",
+    "STRIPE_WEBHOOK_SECRET",
+    "STRIPE_MODE",
+]);
+/**
+ * The catalog (and declared names) a spoke's `appendEnvRows` call passes: a
+ * commerce spoke adds the checkout's four rows (D9). `ENV_CATALOG` itself is
+ * unchanged — its test fails on an entry the monorepo's apps never read.
+ */
+export function spokeEnvRowOptions(commerce) {
+    return commerce
+        ? {
+            catalog: { ...ENV_CATALOG, ...SPOKE_CHECKOUT_ENV_CATALOG },
+            declare: SPOKE_CHECKOUT_DECLARED_ENV,
+        }
+        : { catalog: ENV_CATALOG };
+}
+/** `metadata.site` / an offering slug — the package's own pattern. */
+const SITE_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
+/** A stamp a renderer may interpolate: the package's pattern, never `default` (D6). */
+function isValidSite(site) {
+    return SITE_PATTERN.test(site) && site !== "default";
+}
+function assertSite(site) {
+    if (!isValidSite(site)) {
+        throw new TopologyError(`spoke checkout: site stamp ${JSON.stringify(site)} must match ^[a-z0-9][a-z0-9-]{0,39}$ and must not be "default"`);
+    }
+}
+/**
+ * The site stamp for a project name (D6): lower-cased, every run outside
+ * `a-z0-9` collapsed to `-`, trimmed, cut to 40. A name that leaves nothing
+ * usable — or `default`, which is also an unset hub's own stamp — gets
+ * `site-` and the first 8 hex characters of its SHA-256. Never `AILK_SITE_ID`.
+ */
+export function spokeCheckoutSite(projectName) {
+    const slug = projectName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    if (isValidSite(slug))
+        return slug;
+    const digest = createHash("sha256").update(projectName).digest("hex");
+    return `site-${digest.slice(0, 8)}`;
+}
+/** One route file (D4): three lines of wiring, every guarantee in the package. */
+function renderRoute(opts) {
+    return [
+        `// ${opts.title} — GENERATED by create-ailk (#7838). Do not edit: every`,
+        "// guarantee lives in the spoke-checkout package and arrives by a package",
+        "// bump. This site's data is lib/checkout-config.ts.",
+        `import { createSpokeCheckout } from "${SPOKE_CHECKOUT_PACKAGE}";`,
+        "",
+        `import { checkoutConfig } from "../../../../lib/checkout-config";`,
+        "",
+        `export const runtime = "nodejs";`,
+        `export const dynamic = "force-dynamic";`,
+        "",
+        `// platform-decisions-waiver: api-versioning — ${opts.waiver} (spec 7838 §7)`,
+        opts.exportLine,
+        "",
+    ].join("\n");
+}
+const BUY_ROUTE = renderRoute({
+    title: "The buy route",
+    waiver: "a browser buy link that redirects to Stripe Checkout, not a versioned API contract",
+    exportLine: "export const { GET, POST } = createSpokeCheckout(checkoutConfig).buy;",
+});
+const WEBHOOK_ROUTE = renderRoute({
+    title: "The Stripe webhook route",
+    waiver: "the endpoint URL registered in Stripe, not a versioned API contract",
+    exportLine: "export const { POST } = createSpokeCheckout(checkoutConfig).webhook;",
+});
+/** The site's checkout data (D5). Only the `const SITE` line varies by site. */
+function renderConfig(site) {
+    return [
+        "// checkout-config.ts — this spoke's checkout, as data (#7838).",
+        "//",
+        "// Written once by create-ailk and yours from then on: create-ailk never",
+        "// rewrites it. The buy route and the Stripe webhook route build their",
+        "// handlers from it. Those two are the only files allowed to import the",
+        "// checkout package (architecture.yaml), so this file never imports it,",
+        "// stripe-client or the stripe SDK. Keep it to data and the fulfil callback.",
+        "//",
+        "// site       Stamped on every Checkout Session as metadata.site. This site's",
+        "//            webhook acts only on its own stamp, and the hub ignores any stamp",
+        "//            that is not its own, so the stamp must be unique on the Stripe",
+        '//            account this site shares. Never "default". Change it only before',
+        "//            any price exists: every lookup key starts with it.",
+        "// offerings  slug -> Stripe lookup_key. The buy link is /api/checkout/<slug>.",
+        "//            scaffold-commerce replaces the placeholder below.",
+        "// fulfil     Runs for each paid session, at least once. It posts one lead to",
+        "//            the hub with the session id as its Idempotency-Key, so a repeat",
+        "//            writes nothing new. The hub dedupes only an identical body: change",
+        "//            the payload's shape only when no webhook is failing.",
+        `import { leads } from "${API_CLIENT_PACKAGE}";`,
+        "",
+        `import { resolveBaseUrl } from "../src/lib/routes";`,
+        "",
+        `const SITE = "${site}";`,
+        "",
+        "/** What this site's fulfil callback reads from a completed checkout. */",
+        "interface CompletedCheckout {",
+        "  idempotencyKey: string;",
+        "  sessionId: string;",
+        "  offering: string;",
+        '  kind: "fixed" | "quoted";',
+        '  mode: "test" | "live";',
+        "  amountTotal: number | null;",
+        "  currency: string | null;",
+        "  email: string | null;",
+        "  customerId: string | null;",
+        "}",
+        "",
+        "export const checkoutConfig = {",
+        "  site: SITE,",
+        "  siteBaseUrl: resolveBaseUrl(),",
+        "  offerings: {",
+        "    // A placeholder until scaffold-commerce creates this site's prices.",
+        '    example: { kind: "fixed", lookupKey: `${SITE}_example`, cancelPath: "/" },',
+        "  },",
+        "  async fulfil(checkout: CompletedCheckout): Promise<void> {",
+        "    if (checkout.email === null) return;",
+        "    // No spoke key: the hub cannot place the lead in this site's workspace.",
+        "    // Fail, so Stripe retries and the dashboard shows a failed webhook.",
+        "    if (!process.env.AILK_SPOKE_KEY)",
+        '      throw new Error("AILK_SPOKE_KEY is not set");',
+        "    const result = await leads.submit(",
+        "      {",
+        "        siteId: SITE,",
+        '        source: "web",',
+        "        email: checkout.email,",
+        "        payload: {",
+        "          site: SITE,",
+        '          page: "checkout",',
+        "          offering: checkout.offering,",
+        "          checkoutKind: checkout.kind,",
+        "          mode: checkout.mode,",
+        "          amountTotal: checkout.amountTotal,",
+        "          currency: checkout.currency,",
+        "          stripeCustomerId: checkout.customerId,",
+        "          checkoutSession: checkout.sessionId,",
+        "        },",
+        "      },",
+        '      { headers: { "Idempotency-Key": checkout.idempotencyKey } },',
+        "    );",
+        "    // A replay under the same key answers 201 with the first lead; any",
+        "    // failure (422 idempotency_key_reused included) makes Stripe retry.",
+        "    if (!result.ok) throw new Error(`hub lead write answered ${result.status}`);",
+        "  },",
+        "};",
+        "",
+    ].join("\n");
+}
+/** One return page (D7): a server component that reads nothing but its copy. */
+function renderPage(opts) {
+    return [
+        `// ${opts.title} — GENERATED by create-ailk (#7838).`,
+        ...opts.about.map((line) => `// ${line}`),
+        `import { SectionRenderer } from "${UI_SECTIONS_PACKAGE}";`,
+        `import type { PageSection } from "${VALIDATION_PACKAGE}";`,
+        `import type { Metadata } from "next";`,
+        `import { getTranslations } from "next-intl/server";`,
+        `import type { ReactElement } from "react";`,
+        "",
+        "interface Props {",
+        "  params: Promise<{ locale: string }>;",
+        "}",
+        "",
+        "export async function generateMetadata({ params }: Props): Promise<Metadata> {",
+        "  const { locale } = await params;",
+        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
+        `  return { title: t("title"), robots: { index: false, follow: false } };`,
+        "}",
+        "",
+        "export default async function Page({ params }: Props): Promise<ReactElement> {",
+        "  const { locale } = await params;",
+        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
+        "  const sections: PageSection[] = [",
+        ...opts.sections.map((line) => `    ${line}`),
+        "  ];",
+        "  return (",
+        '    <main id="main">',
+        "      <SectionRenderer sections={sections} locale={locale} leadingSectionOwnsTitle />",
+        "    </main>",
+        "  );",
+        "}",
+        "",
+    ].join("\n");
+}
+const THANK_YOU_PAGE = renderPage({
+    title: "The checkout thank-you page",
+    about: [
+        "Stripe returns a buyer here after paying. It reads no search parameter and",
+        "calls neither Stripe nor the hub: the webhook is what fulfils the order.",
+    ],
+    namespace: "checkoutThankYou",
+    sections: [
+        "{",
+        '  id: "checkout-thank-you",',
+        '  type: "content-block",',
+        '  data: { headline: t("title"), body: t("body") },',
+        "},",
+    ],
+});
+const UNAVAILABLE_PAGE = renderPage({
+    title: "The checkout unavailable page",
+    about: [
+        "Every refused buy lands here. It never says why: a reason is a probe's",
+        "answer, and the buyer needs only that nothing was charged.",
+    ],
+    namespace: "checkoutUnavailable",
+    sections: [
+        "{",
+        '  id: "checkout-unavailable",',
+        '  type: "content-block",',
+        '  data: { headline: t("title"), body: t("body") },',
+        "},",
+        "{",
+        '  id: "checkout-unavailable-cta",',
+        '  type: "cta",',
+        "  data: {",
+        '    headline: t("ctaHeadline"),',
+        '    primaryCta: { label: t("ctaLabel"), href: "/contact" },',
+        "  },",
+        "},",
+    ],
+});
+/**
+ * The slice for `site`, in order: the two route files, the config, the two
+ * pages (D3). Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ */
+export function renderSpokeCheckoutFiles(site) {
+    assertSite(site);
+    const [buyPath, webhookPath] = SPOKE_CHECKOUT_ROUTE_FILES;
+    const [thankYouPath, unavailablePath] = SPOKE_CHECKOUT_PAGE_FILES;
+    return [
+        [buyPath, BUY_ROUTE],
+        [webhookPath, WEBHOOK_ROUTE],
+        [SPOKE_CHECKOUT_CONFIG_PATH, renderConfig(site)],
+        [thankYouPath, THANK_YOU_PAGE],
+        [unavailablePath, UNAVAILABLE_PAGE],
+    ];
+}
+const WEB_PACKAGE_JSON = "apps/web/package.json";
+/** `deps` with `name: version` added in sorted position, every other key kept in place. */
+function withDependency(deps, name, version) {
+    const out = {};
+    let placed = false;
+    for (const [key, value] of Object.entries(deps)) {
+        // Code-unit order, as package managers sort — never the host's locale.
+        if (!placed && key > name) {
+            out[name] = version;
+            placed = true;
+        }
+        out[key] = value;
+    }
+    if (!placed)
+        out[name] = version;
+    return out;
+}
+/**
+ * Write the slice into `targetDir` (D3). A file that already exists is left
+ * byte-for-byte and reported `skipped` — the config is the site's once
+ * written. Adds the package to `apps/web/package.json` only when absent.
+ * Every refusal (an invalid stamp, a version map without the package, a
+ * missing or malformed `apps/web/package.json`) throws before the first write.
+ */
+export function writeSpokeCheckoutSlice(targetDir, opts) {
+    const files = renderSpokeCheckoutFiles(opts.site);
+    const range = JSON.parse(substituteWorkspaceVersions(`{"${SPOKE_CHECKOUT_PACKAGE}": "workspace:*"}`, opts.versions));
+    const version = range[SPOKE_CHECKOUT_PACKAGE];
+    const pkgPath = join(targetDir, WEB_PACKAGE_JSON);
+    const before = readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(before);
+    const rows = [];
+    for (const [path, text] of files) {
+        const abs = join(targetDir, path);
+        if (existsSync(abs)) {
+            rows.push({ path, action: "skipped", wanted: text });
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, text);
+        rows.push({ path, action: "written" });
+    }
+    const deps = pkg.dependencies ?? {};
+    if (!Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)) {
+        pkg.dependencies = withDependency(deps, SPOKE_CHECKOUT_PACKAGE, version);
+        const after = `${JSON.stringify(pkg, null, 2)}${before.endsWith("\n") ? "\n" : ""}`;
+        writeFileSync(pkgPath, after);
+        rows.push({
+            path: WEB_PACKAGE_JSON,
+            action: "patched",
+            change: diffTwoStrings(WEB_PACKAGE_JSON, before, after, true),
+        });
+    }
+    return rows;
+}