create-ailk 0.15.0 → 0.17.0

package/dist/programmatic.js

@@ -29,22 +29,26 @@ import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shipped
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
 import { resolveDesign, spliceThemeBlock, } from "./design-scaffold.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { extractModuleBundle, installBundleTree, } from "./lib/extract-module-bundle.js";
 import { fetchTemplate } from "./lib/fetch-template.js";
 import { assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
 import { assertDesignAllowed, assertReleased, deriveDesignLevel, deriveLevel, resolveModuleSet, resolvePaidModules, } from "./lib/module-license-gate.js";
-import { classifyModules } from "./lib/module-tier.js";
+import { classifyModules, isAddition } from "./lib/module-tier.js";
 import { normalizeModules } from "./module-architecture.js";
 import { writePaidSections } from "./paid-sections.js";
 import { RECOGNIZED_SHAPES, RESERVED_SHAPES, } from "./parse-args.js";
+import { writeSpokeFlowsReadme } from "./seed-flows.js";
 import { SITE_CHROME_PATH, renderSiteChrome, resolveSiteChrome, } from "./site-chrome.js";
 import { SITE_FONTS_PATH, renderSiteFonts } from "./site-fonts.js";
 import { planSiteManifest } from "./site-manifest.js";
 import { SITE_ROSTER_PATH, planHomeRecord, planSiteManifestDesign, readSiteRoster, withMeetPlaceholderSeeds, } from "./site-roster.js";
+import { spokeCheckoutSite, spokeEnvRowOptions, writeSpokeCheckoutSlice, } from "./spoke-checkout.js";
 import { GATEABLE_SURFACES, MODULE_SURFACES, NAV_CONFIG_PATH, excludedRoutePaths, renderNavConfig, resolveSurfaces, } from "./surfaces.js";
 import { syncRoutes } from "./sync-routes.js";
 import { BASE_LAYER_DIR, SHAPE_STARTERS, TEMPLATE_MANIFESTS, TemplateError, mergeRoster, resolveTemplate, resolveTemplateLineage, rosterDeclares, templateDelivery, templateTreeDir, } from "./template-manifest.js";
-import { TopologyError, applySpokeTransforms, isSpokeExcluded, normalizeHubUrl, readSiteTopology, spokeExclusions, spokeModuleRefusal, spokeModules, writeHubOriginEnv, } from "./topology.js";
+import { SPOKE_ONLY_FILES, TopologyError, applySpokeTransforms, isSpokeExcluded, normalizeHubSignInUrl, normalizeHubUrl, readSiteTopology, spokeExclusions, spokeDestination, spokeModuleRefusal, spokeModules, writeHubOriginEnv, writeHubSignInEnv, } from "./topology.js";
 import { validateTarget } from "./validate.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const TEMPLATES_DIR = resolve(PKG_ROOT, "templates");
@@ -154,7 +158,12 @@ export function scaffoldSync(opts) {
     const enabledSurfaces = resolveSurfaces(opts.modules ?? ["marketing"], opts.surfaces ?? []);
     // #7426 D4 — a spoke is this same copy with the spoke's exclusions added:
     // one registry over the one template tree, never a second tree.
-    const spoke = opts.topology === "spoke" ? { mcp: opts.mcp !== false } : undefined;
+    const spoke = opts.topology === "spoke"
+        ? {
+            mcp: opts.mcp !== false,
+            ...(opts.hubSignInUrl !== undefined ? { signIn: "hub" } : {}),
+        }
+        : undefined;
     const versions = readVersionMap();
     copyTemplate({
         templatesDir: TEMPLATES_DIR,
@@ -162,7 +171,10 @@ export function scaffoldSync(opts) {
         versions,
         excludePaths: [
             ...excludedRoutePaths(enabledSurfaces),
-            ...(spoke !== undefined ? spokeExclusions(TEMPLATES_DIR, spoke) : []),
+            // #7874 D11 — the declared-env check is a spoke's alone.
+            ...(spoke !== undefined
+                ? spokeExclusions(TEMPLATES_DIR, spoke)
+                : SPOKE_ONLY_FILES),
         ],
         markers: buildScaffoldMarkers(projectName),
     });
@@ -197,6 +209,11 @@ export function scaffoldSync(opts) {
     // scaffold with `withCatalog` unset touches exactly the files it did before.
     if (opts.withCatalog === true)
         writeComponentCatalog(targetAbs);
+    // #7874 D9 — a spoke's env_contract rows, as its last write, so every file
+    // above is in the scan. A hub's project.yaml is never touched.
+    if (spoke !== undefined) {
+        appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+    }
     const filesCreated = countFiles(targetAbs);
     return {
         targetDir: targetAbs,
@@ -376,8 +393,12 @@ export async function scaffold(opts) {
         bundles = chosen.bundles;
         level = chosen.level;
         // #7426 D7 — a key-derived default set keeps only what a spoke admits;
-        // the run names what it dropped (`droppedModules`).
-        if (spoke !== undefined && opts.modules === undefined) {
+        // the run names what it dropped (`droppedModules`). Naming only
+        // additions (`--modules commerce`) keeps the level default too, so it is
+        // filtered the same way (#7838 D12); a named keep set is never touched.
+        if (spoke !== undefined &&
+            (opts.modules === undefined ||
+                opts.modules.every(isAddition))) {
             const admitted = new Set(spokeModules());
             dropped = chosen.modules.filter((m) => !admitted.has(m));
             chosen.modules = chosen.modules.filter((m) => admitted.has(m));
@@ -501,7 +522,8 @@ export async function scaffold(opts) {
     // it a `{{MARKER}}` authored in a base-layer or site-template file would
     // survive into the scaffold verbatim — the state before this card, and the
     // reason a template file could not carry the version stamp.
-    const markers = buildScaffoldMarkers(opts.projectName ?? basename(result.targetDir));
+    const projectName = opts.projectName ?? basename(result.targetDir);
+    const markers = buildScaffoldMarkers(projectName);
     // #5618 D4 — the file-grain ownership registry for THIS scaffold: which
     // layer wrote which destination. Call-scoped (a fresh Map per scaffold(),
     // never module-level), threaded through every layer install below in the
@@ -513,10 +535,12 @@ export async function scaffold(opts) {
     const ownership = new Map();
     // #7426 D4 — every layer below lands through the spoke filter: a module
     // bundle's or the template's destination a spoke does not carry is dropped.
+    // #7876 D10 — and a module flow file lands in `flows/` as declared data.
     const exclusions = spoke !== undefined ? spokeExclusions(TEMPLATES_DIR, spoke) : [];
     const spokeSkip = spoke !== undefined
         ? {
-            skip: (destination) => isSpokeExcluded(destination, { mcp: spoke.mcp, exclusions }),
+            skip: (destination) => isSpokeExcluded(destination, { ...spoke, exclusions }),
+            remapDestination: spokeDestination,
         }
         : {};
     // The BASE LAYER lands first (#5618 D1) — the seed files every template
@@ -719,6 +743,17 @@ export async function scaffold(opts) {
                 writeFileSync(rosterPath, nextManifest);
         }
     }
+    // #7838 D8 — a commerce spoke's own checkout: two routes, its config and
+    // two return pages, once every layer has landed (so the spoke filter has
+    // already dropped the hub-checkout files) and before the manifest, whose
+    // code-route rows then record /checkout/thank-you and /checkout/unavailable.
+    const spokeCommerce = spoke !== undefined && result.modules.includes("commerce");
+    if (spokeCommerce) {
+        writeSpokeCheckoutSlice(result.targetDir, {
+            site: spokeCheckoutSite(projectName),
+            versions,
+        });
+    }
     // #6944 — the manifest records what this scaffold IS, once every layer has
     // landed: the effective module set, a row for every route on disk, and the
     // level only when the key path above derived one — `resolveModuleSet`, or
@@ -734,6 +769,7 @@ export async function scaffold(opts) {
                 modules: result.modules,
                 level,
                 topology: spoke !== undefined ? "spoke" : "hub",
+                ...(spoke?.signIn === "hub" ? { signIn: "hub" } : {}),
                 patternVersion: markers["CREATE_AILK_VERSION"] ?? "",
                 siteTemplatesDir: SITE_TEMPLATES_DIR,
                 templatesDir: TEMPLATES_DIR,
@@ -744,14 +780,33 @@ export async function scaffold(opts) {
     // #7536 D3 — the registry follows `apps/web/package.json`, which a module
     // bundle's `patches` (and the template layer) just finished editing.
     writePaidSections(result.targetDir);
+    // #7874 D9 — a spoke's rows again, now the module bundles and the template
+    // layer are in the scan; it appends only what those layers added. A
+    // commerce spoke also declares what the checkout package reads (#7838 D9).
+    if (spoke !== undefined) {
+        appendEnvRows(result.targetDir, {
+            topology: "spoke",
+            ...spokeEnvRowOptions(spokeCommerce),
+        });
+    }
     // #6107 D2 — after every layer landed, so nothing later overwrites it: a
     // served scaffold needs BETTER_AUTH_SECRET (#6044), and this is its value.
     // A spoke has no sign-in (#7426 D4), so it gets its hub's origin instead
     // (D2) — never the spoke key, which the hub issues.
+    // #7894 D11 — a spoke signing in through its hub also gets the hub's web
+    // origin and its own session secret; never the client secret.
     if (spoke !== undefined)
         writeHubOriginEnv(result.targetDir, spoke.hubOrigin);
     else
         writeAuthSecretFile(result.targetDir);
+    if (spoke?.hubSignInOrigin !== undefined) {
+        writeHubSignInEnv(result.targetDir, spoke.hubSignInOrigin);
+    }
+    // #7876 D9 — a spoke carrying the flow stepper says what its `flows/` is
+    // and how its rollout seeds it. A hub, and a spoke without flows, get none.
+    if (spoke !== undefined && modules.includes("signal-collectors")) {
+        writeSpokeFlowsReadme(result.targetDir);
+    }
     // #6683 D9 — persisted only after every layer landed, and only when the
     // caller passed `license`: a scaffold without it writes nothing new. A
     // spoke has no apps/api, so it keeps the key in ailk.key alone (#7426 D6).
@@ -765,6 +820,9 @@ export async function scaffold(opts) {
         ...result,
         ...(dropped.length > 0 ? { droppedModules: dropped } : {}),
         ...(spoke !== undefined ? { hubOrigin: spoke.hubOrigin } : {}),
+        ...(spoke?.hubSignInOrigin !== undefined
+            ? { hubSignInOrigin: spoke.hubSignInOrigin }
+            : {}),
     };
     if (template !== undefined && resolvedDesign !== undefined) {
         return {
@@ -783,6 +841,7 @@ function resolveSpoke(opts, template) {
         const spokeOnly = [
             opts.hubUrl !== undefined ? "hubUrl" : undefined,
             opts.mcp !== undefined ? "mcp" : undefined,
+            opts.hubSignInUrl !== undefined ? "hubSignInUrl" : undefined,
         ].filter((f) => f !== undefined);
         if (spokeOnly.length > 0) {
             throw new TemplateError(`${spokeOnly.join(" and ")} only apply to a spoke — pass topology: "spoke"`);
@@ -793,8 +852,12 @@ function resolveSpoke(opts, template) {
         throw new TemplateError("a spoke needs a starter — pass --shape <shape> or --template <name>: the site manifest is where the topology is recorded");
     }
     let hubOrigin;
+    let hubSignInOrigin;
     try {
         hubOrigin = normalizeHubUrl(opts.hubUrl ?? process.env["AILK_API_URL"]);
+        if (opts.hubSignInUrl !== undefined) {
+            hubSignInOrigin = normalizeHubSignInUrl(opts.hubSignInUrl);
+        }
     }
     catch (err) {
         if (err instanceof TopologyError)
@@ -809,7 +872,13 @@ function resolveSpoke(opts, template) {
                 : refusal);
         }
     }
-    return { mcp: opts.mcp !== false, hubOrigin };
+    return {
+        mcp: opts.mcp !== false,
+        hubOrigin,
+        ...(hubSignInOrigin !== undefined
+            ? { signIn: "hub", hubSignInOrigin }
+            : {}),
+    };
 }
 /**
  * The per-row install of the two SHARED seed layers (#6646 D1, disposition

package/dist/seed-flows.d.ts

@@ -0,0 +1,65 @@
+/** The environment variable the spoke key is read from — and nowhere else. */
+export declare const SPOKE_KEY_ENV_VAR = "AILK_SPOKE_KEY";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export declare class SeedFlowsRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface SeedFlowsOptions {
+    /** The spoke site. */
+    targetDir: string;
+    /** `--hub-url`. */
+    hubUrl?: string | undefined;
+    /** `--dry-run` — read and check the files, send nothing, read no key. */
+    dryRun?: boolean;
+    /** Injectable for tests; defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Each report line as it happens; defaults to nothing. */
+    onLine?: (line: string) => void;
+}
+/** Where the hub origin came from. */
+export type HubSource = "--hub-url" | "AILK_API_URL" | "apps/web/.env.local";
+export type SeedFlowOutcome = {
+    slug: string;
+    ok: true;
+    result: string;
+    status: string;
+} | {
+    slug: string;
+    ok: false;
+    failure: string;
+} | {
+    slug: string;
+    ok: "dry-run";
+};
+export interface SeedFlowsResult {
+    /** The hub origin, when one resolved (a dry run may have none). */
+    hub?: {
+        origin: string;
+        source: HubSource;
+    };
+    /** Set when there were no declared flows to send. */
+    empty?: string;
+    flows: SeedFlowOutcome[];
+    /** 0 every flow answered 200 (or a dry run); 1 any failed. */
+    exitCode: 0 | 1;
+}
+/** The whole report, one line per row — what `seedFlows` printed as it went. */
+export declare function formatSeedFlowsReport(result: SeedFlowsResult): string;
+export declare function seedFlows(opts: SeedFlowsOptions): Promise<SeedFlowsResult>;
+export declare const SPOKE_FLOWS_README = "# flows/\n\nEach file here is one **declared flow**: `flows/<slug>.json` holds one flow\nconfig, exactly as the hub stores it. This repo owns these configs \u2014 the hub\nruns them for this site.\n\n## What a spoke may declare\n\nA spoke key may seed only what this site's own flow pages show:\n`slug`, `defaultLocale`, `steps`, `thankYou` and `flags`. Anything the\nhub acts on outside these pages \u2014 emails, deliverables, pricing, registers,\nlistings \u2014 is refused (`field_not_seedable`). A flow that needs one of those\nis authored in the hub's Admin instead.\n\nThe file name must be the config's `slug` plus `.json`.\n\n## Seeding them into the hub\n\nRun this as part of each rollout, from the site's root, with the spoke key\nyour hub issued set as `AILK_SPOKE_KEY` in the environment (a shell or CI\nsecret \u2014 never a file in this repo):\n\n    npx create-ailk seed-flows .\n\nThe hub origin comes from `--hub-url`, else `AILK_API_URL`, else the\n`AILK_API_URL=` line of `apps/web/.env.local`. The key is read from the\nenvironment only. Each flow answers `created`, `updated` or `unchanged`,\nso running it again is safe. `--dry-run` checks the files and sends nothing.\n\nThe hub's operator must first turn seeding on (`AILK_SPOKE_FLOW_SEED=true`\non the hub). Until it is on and this command has run, links to these flows\n(`/flows/<slug>`) reach no flow.\n\n## Who owns what\n\nThe next seed that differs overwrites the hub's copy of a flow's config, so\nedit flows here, not in the Admin. A flow's status (live or draft) is the\nhub's: switching a seeded flow to draft in the Admin keeps it draft through\nevery later seed. Removing a file here does not delete the hub's flow. If\nthe Admin adds a block only it can author (an email, a deliverable, an\noffer), the hub refuses the next seed of that flow (`slug_owned`) rather\nthan delete the block.\n";
+/**
+ * Write `SPOKE_FLOWS_README` to `<targetDir>/flows/README.md` unless that
+ * file exists. Returns whether it wrote.
+ */
+export declare function writeSpokeFlowsReadme(targetDir: string): boolean;
+export interface SeedFlowsArgs {
+    target: string | undefined;
+    hubUrl: string | undefined;
+    dryRun: boolean;
+    help: boolean;
+}
+export declare const SEED_FLOWS_HELP = "create-ailk seed-flows \u2014 send a spoke's declared flows to its hub.\n\nUsage:\n  AILK_SPOKE_KEY=<key> create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]\n\nArguments:\n  <dir>                The spoke site. Defaults to the current dir.\n\nOptions:\n  --hub-url <origin>   The hub's origin. Else AILK_API_URL, else the\n                       AILK_API_URL= line of apps/web/.env.local. https:\n                       only (http: on localhost or 127.0.0.1).\n  --dry-run            Check every flows/*.json and print what would be sent.\n                       Sends nothing and reads no key.\n  -h, --help           Show this help.\n\nEach flows/<slug>.json is sent to PUT <hub>/v1/flows/<slug>/definition with\nthe spoke key, which is read from AILK_SPOKE_KEY only. The hub must have\nAILK_SPOKE_FLOW_SEED=true. Exit 0 when every flow was accepted, 1 when any\nfailed, 2 on a refusal (nothing is sent).\n";
+export declare function parseSeedFlowsArgs(argv: string[]): SeedFlowsArgs;

package/dist/seed-flows.js

@@ -0,0 +1,350 @@
+/**
+ * `create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]` — send a
+ * spoke's declared flows to its hub (#7876).
+ *
+ * A spoke's flows live in its own repo as `flows/<slug>.json`, each one flow
+ * config exactly as the hub stores it (D6). This command is the rollout step
+ * that writes them into the spoke's hub workspace: one
+ * `PUT <hub>/v1/flows/<slug>/definition` per file, carrying the spoke key, and
+ * the hub answers `created`, `updated` or `unchanged` (D4) — so a second run
+ * writes nothing.
+ *
+ * In order (D7): the site must be a spoke; every `flows/*.json` must parse
+ * and carry a `slug` equal to its file name; `--dry-run` stops there; the hub
+ * origin comes from `--hub-url`, else the `AILK_API_URL` environment
+ * variable, else the `AILK_API_URL=` line of `apps/web/.env.local`, and must
+ * be `https:` (or `http:` on a loopback host); the key comes from the
+ * `AILK_SPOKE_KEY` environment variable and nowhere else. Every refusal is
+ * thrown before the first request. The hub origin and its source are printed
+ * before any request, so where the key goes is visible before it is sent.
+ *
+ * The key is sent only as `x-ailk-spoke-key`, never followed across a
+ * redirect (`redirect: "error"`), and never printed. Of a hub's answer only a
+ * status and a `[a-z0-9_]` error code are printed — no other hub-supplied
+ * text reaches the terminal (SEC-7876-S1).
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly. `fetch`
+ * and `env` are injectable. Spec: docs/specs/7876-flows-as-declared-data-spec.md.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { ParseError } from "./parse-args.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+/** The environment variable the spoke key is read from — and nowhere else. */
+export const SPOKE_KEY_ENV_VAR = "AILK_SPOKE_KEY";
+/** The header the key travels in (`packages/api-client`'s spoke header). */
+const SPOKE_KEY_HEADER = "x-ailk-spoke-key";
+/** `flowSlugSchema`'s rule (`@working-theory/validation`), restated: no runtime dep. */
+const FLOW_SLUG = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const FLOW_SLUG_MAX = 59;
+/** The only hub-supplied text printed: a code of this shape, else `unknown`. */
+const SAFE_CODE = /^[a-z0-9_]{1,64}$/;
+const REQUEST_TIMEOUT_MS = 15_000;
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export class SeedFlowsRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "SeedFlowsRefusedError";
+    }
+}
+function readDeclaredFlows(flowsDir) {
+    if (!existsSync(flowsDir))
+        return [];
+    const files = readdirSync(flowsDir)
+        .filter((name) => name.endsWith(".json"))
+        .sort();
+    return files.map((file) => {
+        let config;
+        try {
+            config = JSON.parse(readFileSync(join(flowsDir, file), "utf8"));
+        }
+        catch {
+            throw new SeedFlowsRefusedError(`seed-flows: flows/${file} is not JSON. Nothing was sent.`);
+        }
+        if (config === null ||
+            typeof config !== "object" ||
+            Array.isArray(config)) {
+            throw new SeedFlowsRefusedError(`seed-flows: flows/${file} is not a flow config object. Nothing was sent.`);
+        }
+        const slug = config["slug"];
+        const expected = file.slice(0, -".json".length);
+        if (typeof slug !== "string" ||
+            !FLOW_SLUG.test(slug) ||
+            slug.length > FLOW_SLUG_MAX) {
+            throw new SeedFlowsRefusedError(`seed-flows: flows/${file} has no valid "slug" (lowercase letters, digits and single hyphens, at most ${FLOW_SLUG_MAX} characters). Nothing was sent.`);
+        }
+        if (slug !== expected) {
+            throw new SeedFlowsRefusedError(`seed-flows: flows/${file} declares slug "${slug}"; a declared flow's file is named <slug>.json. Nothing was sent.`);
+        }
+        return { slug, file, config: config };
+    });
+}
+// ── The hub origin ──────────────────────────────────────────────────────────
+/** The `AILK_API_URL=` value in `apps/web/.env.local`, if one is assigned. */
+function readEnvLocalHubUrl(targetDir) {
+    const path = join(targetDir, "apps", "web", ".env.local");
+    if (!existsSync(path))
+        return undefined;
+    const line = readFileSync(path, "utf8")
+        .split(/\r?\n/)
+        .map((l) => /^\s*(?:export\s+)?AILK_API_URL\s*=\s*(.*)$/.exec(l))
+        .filter((m) => m !== null)
+        .pop(); // dotenv: the last assignment wins
+    const value = line?.[1]?.trim().replace(/^(["'])(.*)\1$/, "$2");
+    return value !== undefined && value !== "" ? value : undefined;
+}
+const HUB_SOURCES_HINT = `The hub origin comes from --hub-url, else the ${HUB_ORIGIN_ENV_VAR} environment variable, else the ${HUB_ORIGIN_ENV_VAR}= line of apps/web/.env.local.`;
+function resolveHub(targetDir, hubUrl, env) {
+    const fromEnv = env[HUB_ORIGIN_ENV_VAR];
+    const candidates = [
+        ["--hub-url", hubUrl],
+        [HUB_ORIGIN_ENV_VAR, fromEnv],
+        ["apps/web/.env.local", readEnvLocalHubUrl(targetDir)],
+    ];
+    const picked = candidates.find(([, value]) => value !== undefined && value.trim() !== "");
+    if (picked === undefined) {
+        throw new SeedFlowsRefusedError(`seed-flows: no hub origin was given. ${HUB_SOURCES_HINT} Nothing was sent.`);
+    }
+    const [source, raw] = picked;
+    try {
+        return { origin: normalizeHubUrl(raw), source };
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        throw new SeedFlowsRefusedError(`seed-flows: ${err.message} (from ${source}). ${HUB_SOURCES_HINT} Nothing was sent.`);
+    }
+}
+// ── Sending ─────────────────────────────────────────────────────────────────
+function safeCode(value) {
+    return typeof value === "string" && SAFE_CODE.test(value) ? value : "unknown";
+}
+async function sendFlow(fetchImpl, origin, key, flow) {
+    let response;
+    try {
+        response = await fetchImpl(`${origin}/v1/flows/${flow.slug}/definition`, {
+            method: "PUT",
+            headers: {
+                "content-type": "application/json",
+                [SPOKE_KEY_HEADER]: key,
+            },
+            body: JSON.stringify(flow.config),
+            // A redirect would re-send the key and the body to another URL.
+            redirect: "error",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        const name = err instanceof Error ? err.name.toLowerCase() : undefined;
+        return { slug: flow.slug, ok: false, failure: `network ${safeCode(name)}` };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    const envelope = (body ?? {});
+    if (response.status === 200) {
+        const result = envelope.data?.result;
+        if (result === "created" ||
+            result === "updated" ||
+            result === "unchanged") {
+            return {
+                slug: flow.slug,
+                ok: true,
+                result,
+                status: safeCode(envelope.data?.status),
+            };
+        }
+        return { slug: flow.slug, ok: false, failure: "200 unknown" };
+    }
+    return {
+        slug: flow.slug,
+        ok: false,
+        failure: `${response.status} ${safeCode(envelope.error?.code)}`,
+    };
+}
+// ── The report ──────────────────────────────────────────────────────────────
+function hubLine(hub) {
+    return hub === undefined
+        ? "hub: none resolved"
+        : `hub: ${hub.origin} (from ${hub.source})`;
+}
+function flowLine(outcome) {
+    if (outcome.ok === "dry-run")
+        return `${outcome.slug}: would send`;
+    if (outcome.ok === false)
+        return `${outcome.slug}: failed — ${outcome.failure}`;
+    const draft = outcome.status === "draft" ? " (status draft — not shown to visitors)" : "";
+    return `${outcome.slug}: ${outcome.result}${draft}`;
+}
+/** The whole report, one line per row — what `seedFlows` printed as it went. */
+export function formatSeedFlowsReport(result) {
+    if (result.empty !== undefined)
+        return `${result.empty}\n`;
+    return `${[hubLine(result.hub), ...result.flows.map(flowLine)].join("\n")}\n`;
+}
+// ── The command ─────────────────────────────────────────────────────────────
+export async function seedFlows(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    let topology;
+    try {
+        topology = readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        throw new SeedFlowsRefusedError(`seed-flows: ${err.message}`);
+    }
+    if (topology !== "spoke") {
+        throw new SeedFlowsRefusedError(`seed-flows: ${opts.targetDir} is a hub; a hub's flows are authored in its Admin or seeded with seed-presets.`);
+    }
+    const flows = readDeclaredFlows(join(targetDir, "flows"));
+    if (flows.length === 0) {
+        const empty = `no declared flows in ${opts.targetDir}/flows`;
+        onLine(empty);
+        return { empty, flows: [], exitCode: 0 };
+    }
+    if (opts.dryRun === true) {
+        let hub;
+        try {
+            hub = resolveHub(targetDir, opts.hubUrl, env);
+        }
+        catch (err) {
+            if (!(err instanceof SeedFlowsRefusedError))
+                throw err;
+            hub = undefined;
+        }
+        const outcomes = flows.map((flow) => ({
+            slug: flow.slug,
+            ok: "dry-run",
+        }));
+        onLine(hubLine(hub));
+        outcomes.forEach((outcome) => onLine(flowLine(outcome)));
+        return { ...(hub !== undefined && { hub }), flows: outcomes, exitCode: 0 };
+    }
+    const hub = resolveHub(targetDir, opts.hubUrl, env);
+    const key = env[SPOKE_KEY_ENV_VAR]?.trim() ?? "";
+    if (key === "") {
+        throw new SeedFlowsRefusedError(`seed-flows: set ${SPOKE_KEY_ENV_VAR} to the spoke key your hub issued. It is read from the environment only — never a flag or a file. Nothing was sent.`);
+    }
+    onLine(hubLine(hub));
+    const fetchImpl = opts.fetch ?? globalThis.fetch;
+    const outcomes = [];
+    for (const flow of flows) {
+        const outcome = await sendFlow(fetchImpl, hub.origin, key, flow);
+        onLine(flowLine(outcome));
+        outcomes.push(outcome);
+    }
+    return {
+        hub,
+        flows: outcomes,
+        exitCode: outcomes.every((o) => o.ok === true) ? 0 : 1,
+    };
+}
+// ── The spoke's flows/README.md (D9) ────────────────────────────────────────
+export const SPOKE_FLOWS_README = `# flows/
+
+Each file here is one **declared flow**: \`flows/<slug>.json\` holds one flow
+config, exactly as the hub stores it. This repo owns these configs — the hub
+runs them for this site.
+
+## What a spoke may declare
+
+A spoke key may seed only what this site's own flow pages show:
+\`slug\`, \`defaultLocale\`, \`steps\`, \`thankYou\` and \`flags\`. Anything the
+hub acts on outside these pages — emails, deliverables, pricing, registers,
+listings — is refused (\`field_not_seedable\`). A flow that needs one of those
+is authored in the hub's Admin instead.
+
+The file name must be the config's \`slug\` plus \`.json\`.
+
+## Seeding them into the hub
+
+Run this as part of each rollout, from the site's root, with the spoke key
+your hub issued set as \`AILK_SPOKE_KEY\` in the environment (a shell or CI
+secret — never a file in this repo):
+
+    npx create-ailk seed-flows .
+
+The hub origin comes from \`--hub-url\`, else \`AILK_API_URL\`, else the
+\`AILK_API_URL=\` line of \`apps/web/.env.local\`. The key is read from the
+environment only. Each flow answers \`created\`, \`updated\` or \`unchanged\`,
+so running it again is safe. \`--dry-run\` checks the files and sends nothing.
+
+The hub's operator must first turn seeding on (\`AILK_SPOKE_FLOW_SEED=true\`
+on the hub). Until it is on and this command has run, links to these flows
+(\`/flows/<slug>\`) reach no flow.
+
+## Who owns what
+
+The next seed that differs overwrites the hub's copy of a flow's config, so
+edit flows here, not in the Admin. A flow's status (live or draft) is the
+hub's: switching a seeded flow to draft in the Admin keeps it draft through
+every later seed. Removing a file here does not delete the hub's flow. If
+the Admin adds a block only it can author (an email, a deliverable, an
+offer), the hub refuses the next seed of that flow (\`slug_owned\`) rather
+than delete the block.
+`;
+/**
+ * Write `SPOKE_FLOWS_README` to `<targetDir>/flows/README.md` unless that
+ * file exists. Returns whether it wrote.
+ */
+export function writeSpokeFlowsReadme(targetDir) {
+    const dir = join(targetDir, "flows");
+    const path = join(dir, "README.md");
+    if (existsSync(path))
+        return false;
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, SPOKE_FLOWS_README);
+    return true;
+}
+export const SEED_FLOWS_HELP = `create-ailk seed-flows — send a spoke's declared flows to its hub.
+
+Usage:
+  AILK_SPOKE_KEY=<key> create-ailk seed-flows [<dir>] [--hub-url <origin>] [--dry-run]
+
+Arguments:
+  <dir>                The spoke site. Defaults to the current dir.
+
+Options:
+  --hub-url <origin>   The hub's origin. Else AILK_API_URL, else the
+                       AILK_API_URL= line of apps/web/.env.local. https:
+                       only (http: on localhost or 127.0.0.1).
+  --dry-run            Check every flows/*.json and print what would be sent.
+                       Sends nothing and reads no key.
+  -h, --help           Show this help.
+
+Each flows/<slug>.json is sent to PUT <hub>/v1/flows/<slug>/definition with
+the spoke key, which is read from AILK_SPOKE_KEY only. The hub must have
+AILK_SPOKE_FLOW_SEED=true. Exit 0 when every flow was accepted, 1 when any
+failed, 2 on a refusal (nothing is sent).
+`;
+export function parseSeedFlowsArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            "hub-url": { type: "string" },
+            "dry-run": { type: "boolean", default: false },
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`seed-flows takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        hubUrl: parsed.values["hub-url"],
+        dryRun: parsed.values["dry-run"] === true,
+        help: parsed.values.help === true,
+    };
+}