create-ailk 0.14.0 → 0.16.0

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,
+    };
+}

package/dist/site-chrome.d.ts

@@ -76,6 +76,8 @@ export interface TemplateLayout {
     colorMode?: SiteChromeColorMode;
     /** #7742 D1 — `minimal`: the minimal closing slide, consent bar and themed 404. */
     chromeStyle?: SiteChromeChromeStyle;
+    /** #7797 D1 — route paths whose page ends on the closing footer (wordmark, contact lines, legal line). */
+    closingFooterPaths?: readonly string[];
 }
 /** `TemplateLayout` with every field resolved — what `site-chrome.ts` exports. */
 export interface ResolvedSiteChrome {
@@ -93,6 +95,8 @@ export interface ResolvedSiteChrome {
     colorMode?: "light";
     /** Present only when it resolves to "minimal" — never "default" (#7742 D1). */
     chromeStyle?: "minimal";
+    /** Present only when a non-empty list resolves — never `[]` (#7797 D1). */
+    closingFooterPaths?: readonly string[];
 }
 /** Defaults (#5612 D1; banner off since #6469). */
 export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;

package/dist/site-chrome.js

@@ -66,6 +66,14 @@ const HOME_VALUES = ["default", "deck"];
 const INNER_PAGES_VALUES = ["default", "bare"];
 const COLOR_MODE_VALUES = ["user", "light"];
 const CHROME_STYLE_VALUES = ["default", "minimal"];
+/**
+ * A `closingFooterPaths` member (#7797): a route path as the site writes it —
+ * a leading "/" and no query, fragment, whitespace or control character. The
+ * layout normalizes the visitor's pathname (locale prefix, trailing slash)
+ * before comparing, so "/about" and "/about/" name the same page.
+ */
+// eslint-disable-next-line no-control-regex -- the class deliberately refuses control characters
+const CLOSING_FOOTER_PATH = /^\/[^\s?#\u0000-\u001f]*$/;
 /**
  * Validate an UNTRUSTED `layout` value (a bundle's `ailk-template.json`
  * `layout` field — arbitrary JSON, never compile-time checked the way the
@@ -144,6 +152,16 @@ export function validateTemplateLayout(value, subject) {
         }
         result.chromeStyle = raw.chromeStyle;
     }
+    if ("closingFooterPaths" in raw && raw.closingFooterPaths !== undefined) {
+        const paths = raw.closingFooterPaths;
+        const badIndex = Array.isArray(paths)
+            ? paths.findIndex((p) => typeof p !== "string" || !CLOSING_FOOTER_PATH.test(p))
+            : -1;
+        if (!Array.isArray(paths) || paths.length === 0 || badIndex !== -1) {
+            throw new TemplateLayoutError(`${subject}: layout.closingFooterPaths must be a non-empty list of route paths ("/about") with no query or fragment — got ${JSON.stringify(badIndex !== -1 ? paths[badIndex] : paths)}`);
+        }
+        result.closingFooterPaths = paths;
+    }
     return result;
 }
 /**
@@ -195,6 +213,12 @@ export function resolveSiteChrome(layout, designLayout) {
     if ((layout?.chromeStyle ?? fromDesign.chromeStyle) === "minimal") {
         resolved.chromeStyle = "minimal";
     }
+    // #7797 D1 — the list resolves as a whole (an explicit layout wins over the
+    // design's), and only a non-empty list is ever a key.
+    const closingFooterPaths = layout?.closingFooterPaths ?? fromDesign.closingFooterPaths;
+    if (closingFooterPaths !== undefined && closingFooterPaths.length > 0) {
+        resolved.closingFooterPaths = closingFooterPaths;
+    }
     return resolved;
 }
 /**
@@ -225,6 +249,10 @@ export function renderSiteChrome(resolved) {
     // only for the opt-in values.
     const colorModeValue = resolved.colorMode === "light" ? '\n  colorMode: "light",' : "";
     const chromeStyleValue = resolved.chromeStyle === "minimal" ? '\n  chromeStyle: "minimal",' : "";
+    // #7797 D1 — the same form: member and bullet always, the value line only for a non-empty list.
+    const closingFooterPathsValue = resolved.closingFooterPaths === undefined
+        ? ""
+        : `\n  closingFooterPaths: [${resolved.closingFooterPaths.map((p) => JSON.stringify(p)).join(", ")}],`;
     return `// site-chrome.ts — resolved template layout knobs.
 //
 // GENERATED by create-ailk from the declared template's \`layout\` block
@@ -247,7 +275,9 @@ export function renderSiteChrome(resolved) {
 //     switch; dark appears only as a deck ground.
 //   - chromeStyle: "minimal" → the deck's closing slide is the wordmark,
 //     contact lines and one legal line; the consent bar is a hairline bar on
-//     the page ground; the 404 renders in the site's theme.${groundsComment}
+//     the page ground; the 404 renders in the site's theme.
+//   - closingFooterPaths → each listed inner page ends on the closing footer
+//     (the wordmark, contact lines and legal line) instead of its usual footer.${groundsComment}
 
 export interface SiteChrome {
   nav: "full" | "mark-only";
@@ -257,14 +287,15 @@ export interface SiteChrome {
   innerPages?: "bare";
   deckPresentation?: true;
   colorMode?: "light";
-  chromeStyle?: "minimal";${groundsMember}
+  chromeStyle?: "minimal";
+  closingFooterPaths?: readonly string[];${groundsMember}
 }
 
 export const siteChrome: SiteChrome = {
   nav: ${JSON.stringify(resolved.nav)},
   footer: ${JSON.stringify(resolved.footer)},
   announcementBanner: ${JSON.stringify(resolved.announcementBanner)},
-  home: ${JSON.stringify(resolved.home)},${groundsValue}${innerPagesValue}${presentationValue}${colorModeValue}${chromeStyleValue}
+  home: ${JSON.stringify(resolved.home)},${groundsValue}${innerPagesValue}${presentationValue}${colorModeValue}${chromeStyleValue}${closingFooterPathsValue}
 };
 `;
 }

package/dist/site-manifest.d.ts

@@ -2,6 +2,7 @@ import type { Level } from "./lib/module-tier.js";
 import type { ModuleName } from "./parse-args.js";
 import { type SiteRoster } from "./site-roster.js";
 import type { MarkerMap } from "./substitute.js";
+import type { Topology } from "./topology.js";
 export interface PlanSiteManifestOptions {
     targetDir: string;
     /** The installed manifest, read after every layer landed. */
@@ -10,16 +11,65 @@ export interface PlanSiteManifestOptions {
     modules: readonly ModuleName[];
     /** The level the key path derived, or undefined when it derived none. */
     level: Level | undefined;
+    /** The scaffold's topology (#7426 D10). */
+    topology: Topology;
+    /**
+     * `"hub"` on a spoke that signs in through its hub (#7894 D1); absent
+     * otherwise, so every other manifest is byte-identical to before.
+     */
+    signIn?: "hub";
+    /** The create-ailk version that wrote the scaffold (`CREATE_AILK_VERSION`). */
+    patternVersion: string;
     siteTemplatesDir: string;
     templatesDir: string;
     markers: MarkerMap;
 }
 /**
- * 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 declare function planSiteManifest(opts: PlanSiteManifestOptions): string;
+/** The two fields `create-ailk adopt` records (#7875). */
+export interface TopologyRecord {
+    topology: Topology;
+    patternVersion: string;
+}
+/**
+ * `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 declare function planTopologyRecord(text: string, record: TopologyRecord, label: string): string;
+export interface PlanAdoptedSiteManifestOptions extends TopologyRecord {
+    targetDir: string;
+    /** The template the site was built from — a `SHAPE_STARTERS` or `resolveTemplate` name. */
+    template: string;
+    /** The site's module set. */
+    modules: readonly ModuleName[];
+    siteTemplatesDir: string;
+    templatesDir: string;
+    markers: MarkerMap;
+}
+/**
+ * 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 declare function planAdoptedSiteManifest(opts: PlanAdoptedSiteManifestOptions): string;