create-ailk 0.14.0 → 0.16.0

package/dist/derive-architecture.d.ts

@@ -1,3 +1,33 @@
+/**
+ * Derive a scaffolded site's `architecture.yaml` from its selected module set.
+ *
+ * `deriveArchitecture(modules)` composes the module-independent BASE
+ * (module-architecture.ts `ARCHITECTURE_BASE`) with the selected module slices
+ * into ONE deterministic `architecture.yaml` document string. The module set is
+ * the single source of truth for the result — same set → byte-identical output
+ * (no timestamps, stable key/array ordering), so the derivation doubles as the
+ * re-runnable sync path (add a module, re-derive, the file updates; re-deriving
+ * an unchanged set is a no-op).
+ *
+ * Zero runtime dependencies (create-ailk is a published, standalone CLI): the
+ * YAML is emitted by a small, purpose-built deterministic serializer over the
+ * fixed document shape this module produces — no `yaml`/`js-yaml` dependency.
+ */
+import { type ForbiddenPattern } from "./module-architecture.js";
+import type { Topology } from "./topology.js";
+/** The topology a document is derived for (#7426 D8). */
+export interface DeriveArchitectureOptions {
+    /** `"hub"` (the default) or `"spoke"`. */
+    topology?: Topology;
+    /** Spoke only: whether the spoke keeps `apps/mcp` (default true). */
+    mcp?: boolean;
+}
+/** The only spoke files that may import @working-theory/spoke-checkout (#7873). */
+export declare const SPOKE_CHECKOUT_ROUTE_FILES: readonly string[];
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+export declare const SPOKE_WEB_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
+/** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
+export declare const SPOKE_MCP_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
 /**
  * Derive the `architecture.yaml` document for a module set.
  *
@@ -6,8 +36,13 @@
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export declare function deriveArchitecture(modules?: string[], surfaces?: string[]): string;
+export declare function deriveArchitecture(modules?: string[], surfaces?: string[], options?: DeriveArchitectureOptions): string;

package/dist/derive-architecture.js

@@ -15,6 +15,66 @@
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
 import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+/** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
+const SPOKE_TIERS = {
+    data: "none — the hub's database",
+    api: "the hub at AILK_API_URL (apps/mcp is a stateless front)",
+    presentation: "apps/web",
+};
+// ── The spoke checkout boundary (#7873, brief Part 2 §2) ───────────────────
+//
+// A scaffold's lint (template-overlay/tools/lint-architecture.ts) resolves an
+// import only to a workspace on disk, so the one way to ban an npm package is
+// a line-level forbidden pattern. These go under the spoke's own `apps.web`
+// and `apps.mcp` only — never top level, and never on a hub derivation.
+/** The only spoke files that may import @working-theory/spoke-checkout (#7873). */
+export const SPOKE_CHECKOUT_ROUTE_FILES = Object.freeze([
+    "apps/web/app/api/checkout/[offering]/route.ts",
+    "apps/web/app/api/webhooks/stripe/route.ts",
+]);
+/**
+ * A line-level regex for an import of `specifier` or one of its subpaths, in
+ * every form the line can take: `from "…"` (a static or re-export, including
+ * the closing line of a multi-line import), `import "…"`, `import("…")` and
+ * `require("…")`. The leading `\b` keeps `myrequire(…)` / `datafrom(…)` out;
+ * the quote set takes a backtick so `import(\`…\`)` is not a way round it.
+ * A plain string (`"stripe"`) and a lookalike name (`…-extra`) do not match.
+ */
+function specifierForm(specifier) {
+    const q = "['\"`]";
+    const literal = specifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return `\\b(?:from|import|require)\\s*\\(?\\s*${q}${literal}(?:/[^'"\`]*)?${q}`;
+}
+/** P1 with no exclusions — a kept apps/mcp's form; apps/web adds the two routes. */
+const SPOKE_CHECKOUT_PATTERN = Object.freeze({
+    pattern: specifierForm("@working-theory/spoke-checkout"),
+    reason: "Spoke checkout: only the buy route and the webhook route may import @working-theory/spoke-checkout (brief Part 2 §2, #7873)",
+});
+const STRIPE_CLIENT_PATTERN = Object.freeze({
+    pattern: specifierForm("@working-theory/stripe-client"),
+    reason: "A spoke never imports stripe-client directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
+});
+const STRIPE_SDK_PATTERN = Object.freeze({
+    pattern: specifierForm("stripe"),
+    reason: "A spoke never imports the stripe SDK directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
+});
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2). */
+export const SPOKE_WEB_FORBIDDEN_PATTERNS = Object.freeze([
+    Object.freeze({ ...SPOKE_CHECKOUT_PATTERN, paths_excluded: [...SPOKE_CHECKOUT_ROUTE_FILES] }),
+    STRIPE_CLIENT_PATTERN,
+    STRIPE_SDK_PATTERN,
+]);
+/** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
+export const SPOKE_MCP_FORBIDDEN_PATTERNS = Object.freeze([
+    SPOKE_CHECKOUT_PATTERN,
+    STRIPE_CLIENT_PATTERN,
+    STRIPE_SDK_PATTERN,
+]);
+/** Per-app extra patterns on the spoke branch only, keyed by the app's key. */
+const SPOKE_APP_FORBIDDEN = {
+    web: SPOKE_WEB_FORBIDDEN_PATTERNS,
+    mcp: SPOKE_MCP_FORBIDDEN_PATTERNS,
+};
 function isScalar(v) {
     return typeof v === "string" || typeof v === "number";
 }
@@ -150,11 +210,18 @@ function namespacesToYaml(ns) {
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export function deriveArchitecture(modules = ["marketing"], surfaces) {
+export function deriveArchitecture(modules = ["marketing"], surfaces, options = {}) {
+    const spoke = options.topology === "spoke";
+    const keepMcp = options.mcp !== false;
     const selected = normalizeModules(modules);
     const slices = selected.map((m) => MODULE_SLICES[m]);
     // The declared route surface (#4154). A scaffold's live-route set is a
@@ -180,12 +247,20 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     };
     for (const s of slices)
         Object.assign(declared, s.apps ?? {});
+    // A spoke carries only its own apps (#7426 D8): web, and mcp unless
+    // `--without-mcp` — never api, never a module's admin.
+    if (spoke) {
+        for (const key of Object.keys(declared)) {
+            if (key !== "web" && !(key === "mcp" && keepMcp))
+                delete declared[key];
+        }
+    }
     // A scaffold carries no `packages/` tree — `@working-theory/*` install from
     // npm — so an entry naming a monorepo folder is dropped rather than shipped
     // as a rule the linter can never apply (#6940). What survives names a path
     // the scaffold has: a declared app, or `database/`.
     const roots = [
-        "database",
+        ...(spoke ? [] : ["database"]),
         ...Object.values(declared).map((a) => a.path),
     ];
     const inScaffold = (p) => {
@@ -202,15 +277,21 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
         const a = declared[key];
         if (!a)
             continue;
+        // The checkout boundary is keyed on the topology the caller passed, never
+        // a module or a path glob alone, so a hub derivation is unchanged (#7873).
+        const extra = spoke ? (SPOKE_APP_FORBIDDEN[key] ?? []) : [];
         apps[key] = appToYaml({
             ...a,
             may_import_from: a.may_import_from.filter(inScaffold),
             may_not_import_from: a.may_not_import_from.filter(inScaffold),
-            forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], a.forbidden_patterns ?? []).map(scoped),
+            forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], [...(a.forbidden_patterns ?? []), ...extra]).map(scoped),
         });
     }
-    // namespaces — present only if a data-tier module contributes one.
-    const nsSlice = slices.find((s) => s.namespaces)?.namespaces;
+    // namespaces — present only if a data-tier module contributes one, and
+    // never on a spoke, which has no database/ of its own.
+    const nsSlice = spoke
+        ? undefined
+        : slices.find((s) => s.namespaces)?.namespaces;
     // forbidden_patterns — base floor first, then the selected modules' patterns.
     const extraForbidden = [];
     for (const s of slices)
@@ -218,8 +299,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
     const doc = {
         version: ARCHITECTURE_BASE.version,
+        ...(spoke ? { topology: "spoke" } : {}),
         composition_model: {
-            tiers: { ...ARCHITECTURE_BASE.composition_model.tiers },
+            tiers: spoke
+                ? { ...SPOKE_TIERS }
+                : { ...ARCHITECTURE_BASE.composition_model.tiers },
         },
         surfaces: {
             core: [...CORE_SURFACE_PATHS],
@@ -240,6 +324,7 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
         "#",
         `# Modules: ${selected.join(", ")}`,
         `# Surfaces: ${enabledSurfaces.length > 0 ? enabledSurfaces.join(", ") : "core only"}`,
+        ...(spoke ? ["# Topology: spoke"] : []),
         "",
     ].join("\n");
     return header + emitDocument(doc);

package/dist/design-package.js

@@ -207,7 +207,7 @@ function parseScalar(raw, lineNo, file) {
  * The one dotted key path whose value may be a block sequence (#7719 D2) —
  * the deck's ordered ground list. Every other `- ` line is refused as before.
  */
-const SEQUENCE_PATHS = new Set(["layout.deckGrounds"]);
+const SEQUENCE_PATHS = new Set(["layout.deckGrounds", "layout.closingFooterPaths"]);
 /**
  * Parse a block sequence of scalars whose `- ` items sit at `pos.i`'s indent
  * (#7719 D2). Each item's text is read by `parseScalar`, with every refusal it
@@ -487,7 +487,7 @@ function validateStringMap(raw, file, field) {
 const LAYOUT_KEYS = ["nav", "footer", "announcementBanner", "home"];
 /** Every key a package's `layout` may carry — #7719 D3 adds the optional `deckGrounds` (a deck home only),
  *  #7721 D1 the optional `innerPages`, #7740 D1 the optional `deckPresentation` (a deck home only),
- *  #7742 D1 the optional `colorMode` and `chromeStyle`. */
+ *  #7742 D1 the optional `colorMode` and `chromeStyle`, #7797 D1 the optional `closingFooterPaths`. */
 const ALLOWED_LAYOUT_KEYS = new Set([
     ...LAYOUT_KEYS,
     "deckGrounds",
@@ -495,6 +495,7 @@ const ALLOWED_LAYOUT_KEYS = new Set([
     "deckPresentation",
     "colorMode",
     "chromeStyle",
+    "closingFooterPaths",
 ]);
 function validateLayout(raw, file) {
     const obj = requireObject(raw, file, "layout");

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { CATALOG_TARGET_PATH, FREE_MODULES, addModule, LicenseRequiredError, PAI
 export { DEFAULT_AILK_MODULE_REGISTRY_URL, FetchModuleError, fetchModule, type FetchModuleOptions, } from "./lib/fetch-module.js";
 export { extractModuleBundle, type ExistingFilePolicy, type ExtractModuleBundleOptions, type InstallReportRow, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, type AddModuleReportRow, type AddModuleResult, type ApplyModuleOptions, } from "./add-module.js";
-export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
+export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, type ApplyDesignArgs, type ApplyDesignChange, type ApplyDesignOptions, type ApplyDesignResult, } from "./apply-design.js";
 export type { HomeSeedOutcome } from "./design-home.js";
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 export { SYNC_ROUTES_HELP, formatSyncRoutesReport, listTemplateRouteDirs, parseSyncRoutesArgs, syncRoutes, type RouteReport, type SyncRoutesOptions, type SyncRoutesResult, } from "./sync-routes.js";

package/dist/index.js

@@ -16,7 +16,7 @@ export { extractModuleBundle, } from "./lib/extract-module-bundle.js";
 export { ADD_MODULE_HELP, AddModuleRefusedError, applyModuleToScaffold, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
 // `create-ailk apply-design` (#6819) — make an existing site wear a design,
 // changing only its look. The pure core, beside `add-module`'s.
-export { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
+export { APPLY_DESIGN_HELP, UnreadChromeError, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 // The site's page roster of record and its install-diff check (#6682).
 export { SITE_ROSTER_PATH, readSiteRoster, siteRosterProblems, } from "./site-roster.js";
 // `create-ailk sync-routes` (#4986) — the template-route drift check + copy.

package/dist/lib/chrome-readers.d.ts

@@ -0,0 +1,21 @@
+import { type ResolvedSiteChrome } from "../site-chrome.js";
+/** One knob a design sets that one of the site's reader files does not read. */
+export interface UnreadChromeKnob {
+    knob: string;
+    /** Overlay-relative path of the reader file, with `/` separators. */
+    file: string;
+}
+/** The pattern that means "this text reads `knob`". */
+export declare function chromeReadPattern(knob: string): RegExp;
+/**
+ * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
+ * fails closed (throws, naming the directory) when it is absent or unreadable,
+ * so a broken overlay can never read as "nothing reads any knob".
+ */
+export declare function chromeKnobReaders(templatesDir: string): Map<string, string[]>;
+/**
+ * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
+ * the shipped overlay's `file` reads it, the site has its own `file`, and the
+ * site's `file` does not read it. A reader file the site lacks is skipped.
+ */
+export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly string[]>, siteDir: string): UnreadChromeKnob[];

package/dist/lib/chrome-readers.js

@@ -0,0 +1,100 @@
+/**
+ * Which generated app files read which chrome knob (#7781, spec
+ * docs/specs/apply-design-unread-chrome-spec.md).
+ *
+ * `apply-design` writes a design's chrome knobs into the site's generated
+ * `apps/web/lib/site-chrome.ts`; other generated files read them. A site
+ * scaffolded before a knob existed has a reader file that ignores it, so the
+ * design is half-applied. These pure functions find that gap:
+ *
+ * - `chromeKnobReaders` derives, from the shipped overlay, the files that read
+ *   each knob — nothing is hard-coded, so a new reader file is picked up.
+ * - `unreadChromeKnobs` compares the site's own copy of each reader file.
+ *
+ * "Reads `knob`" means the file's text matches `(?:siteChrome|chrome)\.<knob>\b`.
+ * A file that reads a knob under another name (a destructured alias) is not
+ * recognised — accepted (spec § Clarifications, detection).
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_SITE_CHROME, } from "../site-chrome.js";
+/** The overlay tree the generated app files live under. */
+const OVERLAY_WEB_DIR = ["apps", "web"];
+/** What precedes a knob name in a read: `siteChrome.` or `chrome.` — the one definition both the overlay scan and the per-site check use. */
+const READ_HEAD = "(?:siteChrome|chrome)\\.";
+/** The pattern that means "this text reads `knob`". */
+export function chromeReadPattern(knob) {
+    return new RegExp(`${READ_HEAD}${knob.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+}
+/** Every `.ts`/`.tsx` file under `dir` outside a `__tests__` segment, as `/`-joined paths relative to `root`. */
+function listSources(root, dir, out) {
+    for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) {
+        const rel = `${dir}/${entry.name}`;
+        if (entry.isDirectory()) {
+            if (entry.name !== "__tests__")
+                listSources(root, rel, out);
+        }
+        else if (/\.tsx?$/.test(entry.name)) {
+            out.push(rel);
+        }
+    }
+}
+/**
+ * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
+ * fails closed (throws, naming the directory) when it is absent or unreadable,
+ * so a broken overlay can never read as "nothing reads any knob".
+ */
+export function chromeKnobReaders(templatesDir) {
+    const webDir = join(templatesDir, ...OVERLAY_WEB_DIR);
+    const readers = new Map();
+    try {
+        if (!existsSync(webDir))
+            throw new Error("missing");
+        const files = [];
+        listSources(templatesDir, OVERLAY_WEB_DIR.join("/"), files);
+        for (const file of files.sort()) {
+            const text = readFileSync(join(templatesDir, file), "utf8");
+            for (const match of text.matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
+                const knob = match[1];
+                const list = readers.get(knob) ?? [];
+                if (!list.includes(file))
+                    list.push(file);
+                readers.set(knob, list);
+            }
+        }
+    }
+    catch {
+        throw new Error(`cannot check chrome knobs: the overlay has no readable apps/web at ${webDir}. Reinstall create-ailk.`);
+    }
+    return readers;
+}
+/** A knob is set when it differs from its default; an optional knob (no default) when present. */
+function isSet(resolved, knob) {
+    const value = resolved[knob];
+    if (value === undefined)
+        return false;
+    if (!(knob in DEFAULT_SITE_CHROME))
+        return true;
+    return (value !== DEFAULT_SITE_CHROME[knob]);
+}
+/**
+ * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
+ * the shipped overlay's `file` reads it, the site has its own `file`, and the
+ * site's `file` does not read it. A reader file the site lacks is skipped.
+ */
+export function unreadChromeKnobs(resolved, readers, siteDir) {
+    const out = [];
+    for (const knob of Object.keys(resolved).sort()) {
+        if (!isSet(resolved, knob))
+            continue;
+        const pattern = chromeReadPattern(knob);
+        for (const file of readers.get(knob) ?? []) {
+            const abs = join(siteDir, file);
+            if (!existsSync(abs))
+                continue;
+            if (!pattern.test(readFileSync(abs, "utf8")))
+                out.push({ knob, file });
+        }
+    }
+    return out;
+}

package/dist/lib/declared-env.d.ts

@@ -0,0 +1,142 @@
+/** Names the platform sets, which need no row (D4). Fixed: a site cannot extend it. */
+export declare const PLATFORM_ENV_NAMES: readonly string[];
+/** Every name with one of these prefixes is a platform name too (D4). */
+export declare const PLATFORM_ENV_PREFIXES: readonly string[];
+/** Names a spoke may neither read nor declare (D5): its hub origin is server-only. */
+export declare const SPOKE_REFUSED_ENV: readonly string[];
+/** Whether `name` is set by the platform and so needs no row. */
+export declare function isPlatformEnvName(name: string): boolean;
+/** A site's topology. Restated from `topology.ts`: the scaffold copy cannot import it. */
+export type SiteTopology = "hub" | "spoke";
+/** One literal env read: the variable name and its 1-based line. */
+export interface EnvRead {
+    name: string;
+    line: number;
+}
+/**
+ * Every literal env read in `source` (D3): `process.env.NAME`,
+ * `process.env["NAME"]` / `['NAME']`, either with `?.` in place of a `.`,
+ * and each key of an object pattern destructured from `process.env`. A
+ * computed `process.env[expr]` is skipped. In source order.
+ */
+export declare function findEnvReads(source: string): EnvRead[];
+/**
+ * The site-relative (`/`-separated) source files under `root` whose reads
+ * the check collects, sorted. Symbolic links are not followed.
+ */
+export declare function listScannedFiles(root: string): string[];
+/** A read located in the site: the file it sits in and its line. */
+export interface SiteEnvRead extends EnvRead {
+    file: string;
+}
+/** Every read in the site at `root`, and every file that could not be read. */
+export declare function collectSiteReads(root: string): {
+    reads: SiteEnvRead[];
+    unreadable: Array<{
+        file: string;
+        reason: string;
+    }>;
+};
+/** One `env_contract` row as written. */
+export interface EnvContractRow {
+    name: string;
+    description: string;
+    secret: boolean;
+    scope?: EnvScope;
+    /** The 1-based `project.yaml` line the row's item starts on. */
+    line: number;
+}
+/** A fault in the block: the 1-based `project.yaml` line and what is wrong. */
+export interface EnvContractFault {
+    line: number;
+    message: string;
+}
+export type EnvContract = {
+    present: false;
+} | {
+    present: true;
+    rows: EnvContractRow[];
+    faults: EnvContractFault[];
+};
+export declare const ENV_SCOPES: readonly ["web", "api", "mcp"];
+export type EnvScope = (typeof ENV_SCOPES)[number];
+/**
+ * The top-level `env_contract:` block of `projectYamlText` (D2): absent, or
+ * its rows and every fault in it. A row whose name is valid is in `rows`
+ * even when another of its keys is at fault, so its name still counts as
+ * declared; the fault is reported either way.
+ */
+export declare function readEnvContract(projectYamlText: string): EnvContract;
+/**
+ * The topology `.ailk-site-manifest.json` records under `root` (D8): a
+ * missing file or key reads `"hub"`; an unknown value or a file that is not
+ * JSON is a fault. The `readSiteTopology` rule in create-ailk's `topology.ts`.
+ */
+export declare function readManifestTopology(root: string): {
+    topology: SiteTopology;
+} | {
+    fault: string;
+};
+/** The check's result: one line per finding, and the line to print on a pass. */
+export interface DeclaredEnvResult {
+    findings: string[];
+    summary: string;
+}
+/**
+ * Check the site at `root` (D5): every literal env read has an
+ * `env_contract` row, every row is well-formed, and on a spoke
+ * `NEXT_PUBLIC_AILK_API_URL` is neither read nor declared. A hub with no
+ * block has nothing to check; a spoke with no block is a finding.
+ */
+export declare function checkDeclaredEnv(root: string): DeclaredEnvResult;
+/** A block the writer cannot read, so it never appends to it (D7). */
+export declare class EnvContractError extends Error {
+    constructor(message: string);
+}
+/** What a row says about a name the writer knows (create-ailk's catalog). */
+export interface EnvCatalogEntry {
+    description: string;
+    secret: boolean;
+}
+export interface PlanEnvRowsOptions {
+    /** The site's topology — passed by the caller, never read from the manifest. */
+    topology: SiteTopology;
+    /** Described rows for known names; any other name gets a placeholder row. */
+    catalog: Readonly<Record<string, EnvCatalogEntry>>;
+    /**
+     * Names the site depends on that an installed package reads on its behalf,
+     * so the scan never sees them (#7838). Each gets a row when it has none,
+     * with no reader and so no `scope`; a platform or refused name is skipped.
+     */
+    declare?: readonly string[];
+}
+/**
+ * `projectYamlText` with a row appended for every name the site at `root`
+ * reads that has none (D7), sorted by name, after the existing rows. Platform
+ * names, and on a spoke `SPOKE_REFUSED_ENV`, get no row. Pure: it reads the
+ * tree, never writes. `added` names the rows it wrote.
+ *
+ * @throws EnvContractError when the existing block has a fault — the writer
+ *   never appends to a block it cannot read.
+ */
+export declare function planEnvRows(root: string, projectYamlText: string, opts: PlanEnvRowsOptions): {
+    text: string;
+    added: string[];
+};
+/** What `appendEnvRows` did to `<root>/project.yaml`. */
+export type AppendEnvRowsResult = {
+    state: "written";
+    added: string[];
+} | {
+    state: "unchanged";
+} | {
+    state: "no-project-yaml";
+};
+/**
+ * Plan and write `<root>/project.yaml`'s new rows (D7). Writes only when the
+ * text changed, so a second run changes nothing; never edits or removes a
+ * row. A site with no `project.yaml` is left alone.
+ *
+ * @throws EnvContractError on a block it cannot read (nothing is written).
+ */
+export declare function appendEnvRows(root: string, opts: PlanEnvRowsOptions): AppendEnvRowsResult;