create-ailk 0.15.0 → 0.16.0

package/dist/lib/declared-env.js

@@ -0,0 +1,985 @@
+/**
+ * The declared-env check (#7874) — every environment variable this site's
+ * code reads has a row in `project.yaml` `env_contract`, and a spoke reads
+ * no `NEXT_PUBLIC_AILK_API_URL` (a spoke's hub origin is server-only).
+ *
+ * ONE file, run in two places (spec D6): create-ailk imports it to write a
+ * spoke's rows, and a spoke scaffold carries a byte-identical copy as
+ * `tools/declared-env.ts`, which `tools/check-declared-env.ts` runs as
+ * `pnpm env:declared`. So it imports only Node built-ins, and nothing in it
+ * may contain a double open brace (the scaffold copy substitutes markers in
+ * `.ts` files).
+ *
+ *   - `findEnvReads` — the literal `process.env` reads in one source file
+ *     (D3), from a line-bounded tokenizer, never a regex over raw text;
+ *   - `listScannedFiles` — the files a site's reads are collected from (D4);
+ *   - `readEnvContract` — the `env_contract:` block, read without a YAML
+ *     dependency (D1/D2);
+ *   - `readManifestTopology` — the site's topology from its manifest (D8);
+ *   - `checkDeclaredEnv` — the check itself (D5);
+ *   - `planEnvRows` / `appendEnvRows` — the writer: appends a row for every
+ *     undeclared read, never edits or removes one (D7).
+ *
+ * Spec: docs/specs/7874-declared-env-check-spec.md. Edit this file, never the
+ * scaffold copy: `scripts/build-templates.mjs` rewrites
+ * `template-overlay/tools/declared-env.ts` from it.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** Names the platform sets, which need no row (D4). Fixed: a site cannot extend it. */
+export const PLATFORM_ENV_NAMES = [
+    "NODE_ENV",
+    "NEXT_RUNTIME",
+    "NEXT_PHASE",
+    "CI",
+    "PORT",
+    "VERCEL",
+];
+/** Every name with one of these prefixes is a platform name too (D4). */
+export const PLATFORM_ENV_PREFIXES = ["VERCEL_"];
+/** Names a spoke may neither read nor declare (D5): its hub origin is server-only. */
+export const SPOKE_REFUSED_ENV = [
+    "NEXT_PUBLIC_AILK_API_URL",
+];
+/** The server-only name a spoke reaches its hub through. */
+const SPOKE_HUB_ORIGIN_ENV = "AILK_API_URL";
+/** Whether `name` is set by the platform and so needs no row. */
+export function isPlatformEnvName(name) {
+    return (PLATFORM_ENV_NAMES.includes(name) ||
+        PLATFORM_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)));
+}
+/** Keywords after which a `/` starts a regex literal, not a division. */
+const REGEX_AFTER_KEYWORDS = new Set([
+    "return",
+    "typeof",
+    "instanceof",
+    "case",
+    "in",
+    "of",
+    "new",
+    "delete",
+    "void",
+    "throw",
+    "yield",
+    "await",
+    "else",
+    "do",
+]);
+const IDENT_START = /[A-Za-z_$]/;
+const IDENT_PART = /[A-Za-z0-9_$]/;
+/**
+ * The code tokens of `source`. Comments, string text (its decoded value is
+ * kept as one `string` token), template-literal text and regex literals are
+ * never tokenized as code; a template's `${…}` expressions are. A string or
+ * regex literal ends at a newline, so a mis-read apostrophe (JSX text) costs
+ * at most the rest of its own line.
+ */
+function tokenize(source) {
+    const tokens = [];
+    /** One entry per open template literal: the brace depth its `${` opened at. */
+    const templates = [];
+    let depth = 0;
+    let line = 1;
+    let i = 0;
+    const n = source.length;
+    const push = (kind, value, at) => {
+        tokens.push({ kind, value, line: at });
+    };
+    const prevAllowsDivision = () => {
+        const prev = tokens[tokens.length - 1];
+        if (prev === undefined)
+            return false;
+        if (prev.kind === "ident")
+            return !REGEX_AFTER_KEYWORDS.has(prev.value);
+        if (prev.kind === "string" || prev.kind === "other")
+            return true;
+        // `<` before `/` is a JSX closing tag (`</a>`), never a regex.
+        return (prev.value === ")" ||
+            prev.value === "]" ||
+            prev.value === "}" ||
+            prev.value === "<");
+    };
+    /** Skip template text from `i` to the closing backtick or a `${`. */
+    const templateText = () => {
+        while (i < n) {
+            const c = source[i];
+            if (c === "\\") {
+                if (source[i + 1] === "\n")
+                    line++;
+                i += 2;
+                continue;
+            }
+            if (c === "`") {
+                i++;
+                return;
+            }
+            if (c === "$" && source[i + 1] === "{") {
+                i += 2;
+                templates.push(depth);
+                depth++;
+                return;
+            }
+            if (c === "\n")
+                line++;
+            i++;
+        }
+    };
+    while (i < n) {
+        const c = source[i] ?? "";
+        const next = source[i + 1] ?? "";
+        if (c === "\n") {
+            line++;
+            i++;
+            continue;
+        }
+        if (c === " " || c === "\t" || c === "\r" || c === "\f" || c === "\v") {
+            i++;
+            continue;
+        }
+        // Comments.
+        if (c === "/" && next === "/") {
+            while (i < n && source[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && next === "*") {
+            i += 2;
+            while (i < n && !(source[i] === "*" && source[i + 1] === "/")) {
+                if (source[i] === "\n")
+                    line++;
+                i++;
+            }
+            i += 2;
+            continue;
+        }
+        // String literals — decoded, ending at a newline.
+        if (c === '"' || c === "'") {
+            const start = line;
+            let value = "";
+            i++;
+            while (i < n && source[i] !== c && source[i] !== "\n") {
+                if (source[i] === "\\" && i + 1 < n && source[i + 1] !== "\n") {
+                    value += source[i + 1];
+                    i += 2;
+                    continue;
+                }
+                value += source[i];
+                i++;
+            }
+            if (source[i] === c)
+                i++;
+            push("string", value, start);
+            continue;
+        }
+        // Template literals — the text is skipped, `${…}` is code.
+        if (c === "`") {
+            i++;
+            templateText();
+            push("other", "`", line);
+            continue;
+        }
+        // Regex literals — ending at a newline.
+        if (c === "/" && !prevAllowsDivision()) {
+            i++;
+            let inClass = false;
+            while (i < n && source[i] !== "\n") {
+                const r = source[i];
+                if (r === "\\") {
+                    i += 2;
+                    continue;
+                }
+                if (r === "[")
+                    inClass = true;
+                else if (r === "]")
+                    inClass = false;
+                else if (r === "/" && !inClass) {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            while (i < n && IDENT_PART.test(source[i] ?? ""))
+                i++;
+            push("other", "/re/", line);
+            continue;
+        }
+        // Identifiers.
+        if (IDENT_START.test(c)) {
+            let j = i + 1;
+            while (j < n && IDENT_PART.test(source[j] ?? ""))
+                j++;
+            push("ident", source.slice(i, j), line);
+            i = j;
+            continue;
+        }
+        // Numbers.
+        if (/[0-9]/.test(c) || (c === "." && /[0-9]/.test(next))) {
+            let j = i + 1;
+            while (j < n && /[0-9A-Za-z_.]/.test(source[j] ?? ""))
+                j++;
+            push("other", source.slice(i, j), line);
+            i = j;
+            continue;
+        }
+        // Punctuators.
+        if (c === "?" && next === "." && !/[0-9]/.test(source[i + 2] ?? "")) {
+            push("punct", "?.", line);
+            i += 2;
+            continue;
+        }
+        if (c === "." && next === "." && source[i + 2] === ".") {
+            push("punct", "...", line);
+            i += 3;
+            continue;
+        }
+        if (c === "{") {
+            depth++;
+            push("punct", c, line);
+            i++;
+            continue;
+        }
+        if (c === "}") {
+            depth--;
+            if (templates.length > 0 && templates[templates.length - 1] === depth) {
+                templates.pop();
+                i++;
+                templateText();
+                continue;
+            }
+            push("punct", c, line);
+            i++;
+            continue;
+        }
+        if (c === "=" && next === "=") {
+            // `==` / `===` are not the destructuring `=`.
+            let j = i;
+            while (source[j] === "=")
+                j++;
+            push("punct", source.slice(i, j), line);
+            i = j;
+            continue;
+        }
+        if (c === "=" && next === ">") {
+            push("punct", "=>", line);
+            i += 2;
+            continue;
+        }
+        push("punct", c, line);
+        i++;
+    }
+    return tokens;
+}
+/** `process.env` / `process?.env` starting at `tokens[i]`: the index after `env`. */
+function processEnvAt(tokens, i) {
+    const a = tokens[i];
+    const dot = tokens[i + 1];
+    const env = tokens[i + 2];
+    if (a?.kind !== "ident" || a.value !== "process")
+        return undefined;
+    if (dot?.kind !== "punct" || (dot.value !== "." && dot.value !== "?.")) {
+        return undefined;
+    }
+    if (env?.kind !== "ident" || env.value !== "env")
+        return undefined;
+    // `x.process.env` is some other object's `process` property.
+    const before = tokens[i - 1];
+    if (before?.kind === "punct" &&
+        (before.value === "." || before.value === "?.")) {
+        return undefined;
+    }
+    return i + 3;
+}
+/** The keys of the object pattern whose closing `}` is `tokens[close]`. */
+function patternKeys(tokens, close) {
+    let depth = 0;
+    let open = -1;
+    for (let k = close; k >= 0; k--) {
+        const t = tokens[k];
+        if (t?.kind !== "punct")
+            continue;
+        if (t.value === "}" || t.value === "]" || t.value === ")")
+            depth++;
+        else if (t.value === "{" || t.value === "[" || t.value === "(") {
+            depth--;
+            if (depth === 0) {
+                open = k;
+                break;
+            }
+        }
+    }
+    if (open === -1 || tokens[open]?.value !== "{")
+        return [];
+    const keys = [];
+    let level = 0;
+    let expectKey = true;
+    for (let k = open + 1; k < close; k++) {
+        const t = tokens[k];
+        if (t === undefined)
+            break;
+        if (t.kind === "punct") {
+            if (t.value === "{" || t.value === "[" || t.value === "(")
+                level++;
+            else if (t.value === "}" || t.value === "]" || t.value === ")")
+                level--;
+            else if (t.value === "," && level === 0) {
+                expectKey = true;
+                continue;
+            }
+            else if (t.value === "..." && level === 0) {
+                expectKey = false;
+                continue;
+            }
+        }
+        if (level === 0 &&
+            expectKey &&
+            (t.kind === "ident" || t.kind === "string")) {
+            keys.push({ name: t.value, line: t.line });
+        }
+        expectKey = false;
+    }
+    return keys;
+}
+/**
+ * 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 function findEnvReads(source) {
+    const tokens = tokenize(source);
+    const reads = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const after = processEnvAt(tokens, i);
+        if (after === undefined)
+            continue;
+        const t = tokens[after];
+        const u = tokens[after + 1];
+        const v = tokens[after + 2];
+        const w = tokens[after + 3];
+        if (t?.kind === "punct" && (t.value === "." || t.value === "?.")) {
+            if (u?.kind === "ident") {
+                reads.push({ name: u.value, line: u.line });
+                continue;
+            }
+            if (t.value === "?." &&
+                u?.value === "[" &&
+                v?.kind === "string" &&
+                w?.value === "]") {
+                reads.push({ name: v.value, line: v.line });
+                continue;
+            }
+        }
+        if (t?.kind === "punct" &&
+            t.value === "[" &&
+            u?.kind === "string" &&
+            v?.value === "]") {
+            reads.push({ name: u.value, line: u.line });
+            continue;
+        }
+        // `{ A, B: b } = process.env` — the pattern ends just before the `=`.
+        const eq = tokens[i - 1];
+        const close = tokens[i - 2];
+        if (eq?.kind === "punct" && eq.value === "=" && close?.value === "}") {
+            reads.push(...patternKeys(tokens, i - 2));
+        }
+    }
+    return reads;
+}
+// ── D4 — what is scanned ────────────────────────────────────────────────────
+const SCANNED_EXTENSIONS = /\.(?:ts|tsx|mts|cts|js|jsx|mjs|cjs)$/;
+const DECLARATION_FILE = /\.d\.[mc]?ts$/;
+const SKIPPED_FILES = [
+    /\.test\.[^/]+$/,
+    /\.spec\.[^/]+$/,
+    /\.stories\.[^/]+$/,
+    /^jest\.config\.[^/]+$/,
+    /^jest\.setup\.[^/]+$/,
+    /^playwright\.config\.[^/]+$/,
+];
+/** Directories never scanned, at any depth (D4). */
+const SKIPPED_DIRECTORIES = [
+    "node_modules",
+    ".next",
+    ".turbo",
+    ".git",
+    ".claude",
+    "dist",
+    "build",
+    "out",
+    "coverage",
+    "__tests__",
+    "__mocks__",
+    "e2e",
+];
+/** The root-level directory never scanned: the checks themselves. */
+const SKIPPED_ROOT_DIRECTORY = "tools";
+/**
+ * The site-relative (`/`-separated) source files under `root` whose reads
+ * the check collects, sorted. Symbolic links are not followed.
+ */
+export function listScannedFiles(root) {
+    const out = [];
+    const walk = (dir, rel) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const childRel = rel === "" ? entry.name : `${rel}/${entry.name}`;
+            if (entry.isDirectory()) {
+                if (SKIPPED_DIRECTORIES.includes(entry.name))
+                    continue;
+                if (rel === "" && entry.name === SKIPPED_ROOT_DIRECTORY)
+                    continue;
+                walk(join(dir, entry.name), childRel);
+            }
+            else if (entry.isFile()) {
+                if (!SCANNED_EXTENSIONS.test(entry.name))
+                    continue;
+                if (DECLARATION_FILE.test(entry.name))
+                    continue;
+                if (SKIPPED_FILES.some((re) => re.test(entry.name)))
+                    continue;
+                out.push(childRel);
+            }
+        }
+    };
+    walk(root, "");
+    return out.sort();
+}
+/** Every read in the site at `root`, and every file that could not be read. */
+export function collectSiteReads(root) {
+    const reads = [];
+    const unreadable = [];
+    for (const file of listScannedFiles(root)) {
+        let source;
+        try {
+            source = readFileSync(join(root, file), "utf8");
+        }
+        catch (err) {
+            unreadable.push({ file, reason: err.message });
+            continue;
+        }
+        for (const read of findEnvReads(source))
+            reads.push({ ...read, file });
+    }
+    return { reads, unreadable };
+}
+export const ENV_SCOPES = ["web", "api", "mcp"];
+const ROW_KEYS = ["name", "description", "secret", "scope"];
+const NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+const KEY_LINE = /^env_contract:(.*)$/;
+/** Strip a trailing ` # comment` from a plain scalar. */
+function stripComment(text) {
+    const m = /(^|\s)#/.exec(text);
+    return (m === null ? text : text.slice(0, m.index)).trim();
+}
+/** Decode a scalar value; `undefined` is a fault named by `fault`. */
+function decodeScalar(raw, fault) {
+    const text = raw.trim();
+    if (text.startsWith('"')) {
+        const end = text.lastIndexOf('"');
+        const rest = text.slice(end + 1).trim();
+        if (end === 0 || (rest !== "" && !rest.startsWith("#"))) {
+            fault("an unterminated double-quoted value");
+            return undefined;
+        }
+        try {
+            return {
+                text: JSON.parse(text.slice(0, end + 1)),
+                plain: false,
+            };
+        }
+        catch {
+            fault("a double-quoted value that is not a valid string");
+            return undefined;
+        }
+    }
+    if (text.startsWith("'")) {
+        let value = "";
+        let k = 1;
+        for (;;) {
+            if (k >= text.length) {
+                fault("an unterminated single-quoted value");
+                return undefined;
+            }
+            if (text[k] === "'") {
+                if (text[k + 1] === "'") {
+                    value += "'";
+                    k += 2;
+                    continue;
+                }
+                break;
+            }
+            value += text[k];
+            k++;
+        }
+        const rest = text.slice(k + 1).trim();
+        if (rest !== "" && !rest.startsWith("#")) {
+            fault("text after a single-quoted value");
+            return undefined;
+        }
+        return { text: value, plain: false };
+    }
+    return { text: stripComment(text), plain: true };
+}
+function parseContract(text) {
+    const lines = text.split("\n").map((l) => l.replace(/\r$/, ""));
+    const keyIndexes = lines.flatMap((l, idx) => (KEY_LINE.test(l) ? [idx] : []));
+    const keyIndex = keyIndexes[0];
+    if (keyIndex === undefined)
+        return undefined;
+    const faults = [];
+    const rows = [];
+    for (const dup of keyIndexes.slice(1)) {
+        faults.push({ line: dup + 1, message: "a second env_contract key" });
+    }
+    const inline = stripComment(KEY_LINE.exec(lines[keyIndex] ?? "")?.[1] ?? "");
+    const parsed = {
+        keyIndex,
+        flowEmpty: inline === "[]",
+        itemIndent: undefined,
+        lastItemIndex: undefined,
+        rows,
+        faults,
+    };
+    if (inline !== "" && inline !== "[]") {
+        faults.push({
+            line: keyIndex + 1,
+            message: "env_contract must be a block list of rows (or [] when empty)",
+        });
+        return parsed;
+    }
+    let item;
+    const items = [];
+    const setKey = (it, idx, body) => {
+        const m = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:(?:\s+(.*)|\s*)$/.exec(body);
+        if (m === null) {
+            faults.push({
+                line: idx + 1,
+                message: `"${body.trim()}" is not a key: value pair`,
+            });
+            return;
+        }
+        const key = m[1] ?? "";
+        const rawValue = m[2] ?? "";
+        if (it.values.has(key)) {
+            faults.push({
+                line: idx + 1,
+                message: `the row repeats the key "${key}"`,
+            });
+            return;
+        }
+        const indicator = /^([|>])[+-]?\s*(#.*)?$/.exec(rawValue.trim());
+        if (indicator !== null) {
+            it.values.set(key, { text: "", plain: false });
+            it.scalar = {
+                key,
+                col: undefined,
+                parts: [],
+                fold: indicator[1] === ">",
+            };
+            return;
+        }
+        const value = decodeScalar(rawValue, (message) => faults.push({ line: idx + 1, message: `${key} has ${message}` }));
+        if (value !== undefined)
+            it.values.set(key, value);
+    };
+    const finishScalar = (it) => {
+        if (it.scalar === undefined)
+            return;
+        const joined = it.scalar.parts.join(it.scalar.fold ? " " : "\n").trim();
+        it.values.set(it.scalar.key, { text: joined, plain: false });
+        it.scalar = undefined;
+    };
+    for (let idx = keyIndex + 1; idx < lines.length; idx++) {
+        const line = lines[idx] ?? "";
+        const trimmed = line.trim();
+        const indent = line.length - line.trimStart().length;
+        if (indent === 0 && trimmed !== "" && !trimmed.startsWith("#")) {
+            if (trimmed.startsWith("-") && !parsed.flowEmpty) {
+                faults.push({
+                    line: idx + 1,
+                    message: "env_contract rows must be indented under the key",
+                });
+            }
+            break;
+        }
+        // A block scalar takes every more-indented line, blank ones included.
+        if (item?.scalar !== undefined) {
+            if (trimmed === "") {
+                item.scalar.parts.push("");
+                continue;
+            }
+            if (indent > item.keyCol) {
+                item.scalar.col ??= indent;
+                item.scalar.parts.push(line.slice(Math.min(indent, item.scalar.col)));
+                parsed.lastItemIndex = idx;
+                continue;
+            }
+            finishScalar(item);
+        }
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        if (parsed.flowEmpty) {
+            faults.push({
+                line: idx + 1,
+                message: "env_contract: [] cannot also have rows",
+            });
+            continue;
+        }
+        const dash = /^(\s*)-(?:(\s+)(.*))?$/.exec(line);
+        if (dash !== null &&
+            (parsed.itemIndent === undefined || indent === parsed.itemIndent)) {
+            parsed.itemIndent ??= indent;
+            const gap = dash[2] ?? " ";
+            item = {
+                line: idx + 1,
+                keyCol: indent + 1 + gap.length,
+                values: new Map(),
+                scalar: undefined,
+            };
+            items.push(item);
+            parsed.lastItemIndex = idx;
+            const body = dash[3] ?? "";
+            if (body.trim() !== "" && !body.trim().startsWith("#"))
+                setKey(item, idx, body);
+            continue;
+        }
+        if (item !== undefined && indent === item.keyCol) {
+            setKey(item, idx, line.slice(indent));
+            parsed.lastItemIndex = idx;
+            continue;
+        }
+        faults.push({
+            line: idx + 1,
+            message: `unexpected line "${trimmed}" — each row is "- name: …" with its keys aligned under it`,
+        });
+    }
+    if (item !== undefined)
+        finishScalar(item);
+    const seen = new Map();
+    for (const it of items) {
+        const fault = (message) => {
+            faults.push({ line: it.line, message });
+        };
+        for (const key of it.values.keys()) {
+            if (!ROW_KEYS.includes(key)) {
+                fault(`the row has an unknown key "${key}" (allowed: ${ROW_KEYS.join(", ")})`);
+            }
+        }
+        const name = it.values.get("name")?.text;
+        const description = it.values.get("description");
+        const secret = it.values.get("secret");
+        const scope = it.values.get("scope");
+        let valid = true;
+        if (name === undefined || name === "") {
+            fault("the row has no name");
+            valid = false;
+        }
+        else if (!NAME_RE.test(name)) {
+            fault(`the row's name "${name}" is not an env var name (A-Z, 0-9, _)`);
+            valid = false;
+        }
+        else if (seen.has(name)) {
+            fault(`${name} already has a row at project.yaml:${seen.get(name)}`);
+            valid = false;
+        }
+        if (description === undefined) {
+            fault(`the row${name !== undefined ? ` for ${name}` : ""} has no description`);
+        }
+        else if (description.text.trim() === "") {
+            fault(`the row${name !== undefined ? ` for ${name}` : ""} has an empty description`);
+        }
+        let secretValue = false;
+        if (secret === undefined) {
+            fault(`the row${name !== undefined ? ` for ${name}` : ""} has no secret: true or false`);
+        }
+        else if (!secret.plain ||
+            (secret.text !== "true" && secret.text !== "false")) {
+            fault(`secret must be true or false, got ${JSON.stringify(secret.text)}`);
+        }
+        else {
+            secretValue = secret.text === "true";
+        }
+        if (secretValue && name?.startsWith("NEXT_PUBLIC_") === true) {
+            fault(`${name} is browser-exposed, so it is never a secret: set secret: false`);
+        }
+        if (scope !== undefined &&
+            !ENV_SCOPES.includes(scope.text)) {
+            fault(`scope must be one of ${ENV_SCOPES.join(", ")}, got ${JSON.stringify(scope.text)}`);
+        }
+        if (valid && name !== undefined) {
+            seen.set(name, it.line);
+            const row = {
+                name,
+                description: description?.text ?? "",
+                secret: secretValue,
+                line: it.line,
+            };
+            if (scope !== undefined &&
+                ENV_SCOPES.includes(scope.text)) {
+                row.scope = scope.text;
+            }
+            rows.push(row);
+        }
+    }
+    faults.sort((a, b) => a.line - b.line);
+    return parsed;
+}
+/**
+ * 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 function readEnvContract(projectYamlText) {
+    const parsed = parseContract(projectYamlText);
+    if (parsed === undefined)
+        return { present: false };
+    return { present: true, rows: parsed.rows, faults: parsed.faults };
+}
+// ── D8 — the site's topology ────────────────────────────────────────────────
+/** The site manifest a templated scaffold writes. */
+const SITE_MANIFEST_FILE = ".ailk-site-manifest.json";
+/**
+ * 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 function readManifestTopology(root) {
+    const path = join(root, SITE_MANIFEST_FILE);
+    if (!existsSync(path))
+        return { topology: "hub" };
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        return {
+            fault: `${SITE_MANIFEST_FILE} is not JSON: ${err.message}`,
+        };
+    }
+    const value = typeof doc === "object" && doc !== null
+        ? doc["topology"]
+        : undefined;
+    if (value === undefined)
+        return { topology: "hub" };
+    if (value === "hub" || value === "spoke")
+        return { topology: value };
+    return {
+        fault: `${SITE_MANIFEST_FILE} records an unknown topology ${JSON.stringify(value)} (expected hub or spoke)`,
+    };
+}
+const PROJECT_YAML = "project.yaml";
+/**
+ * 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 function checkDeclaredEnv(root) {
+    const findings = [];
+    const yamlPath = join(root, PROJECT_YAML);
+    if (!existsSync(yamlPath)) {
+        return { findings: [`env: ${PROJECT_YAML}: missing`], summary: "" };
+    }
+    let yamlText;
+    try {
+        yamlText = readFileSync(yamlPath, "utf8");
+    }
+    catch (err) {
+        return {
+            findings: [`env: ${PROJECT_YAML}: ${err.message}`],
+            summary: "",
+        };
+    }
+    const manifest = readManifestTopology(root);
+    if ("fault" in manifest) {
+        return {
+            findings: [`env: ${SITE_MANIFEST_FILE}: ${manifest.fault}`],
+            summary: "",
+        };
+    }
+    const contract = readEnvContract(yamlText);
+    if (!contract.present) {
+        if (manifest.topology === "hub") {
+            return {
+                findings: [],
+                summary: `env: no env_contract block in ${PROJECT_YAML} — nothing to check`,
+            };
+        }
+        return {
+            findings: [
+                `env: ${PROJECT_YAML} has no env_contract block; a spoke must declare the variables its code reads`,
+            ],
+            summary: "",
+        };
+    }
+    for (const fault of contract.faults) {
+        findings.push(`env: ${PROJECT_YAML}:${fault.line}: ${fault.message}`);
+    }
+    const { reads, unreadable } = collectSiteReads(root);
+    for (const { file, reason } of unreadable)
+        findings.push(`env: ${file}: ${reason}`);
+    const declared = new Map(contract.rows.map((row) => [row.name, row]));
+    const refused = new Set(manifest.topology === "spoke" ? SPOKE_REFUSED_ENV : []);
+    const readFindings = [];
+    for (const name of refused) {
+        const row = declared.get(name);
+        if (row !== undefined) {
+            readFindings.push({
+                name,
+                file: PROJECT_YAML,
+                line: row.line,
+                text: refusal(name, `declared in ${PROJECT_YAML}:${row.line}`),
+            });
+        }
+    }
+    const names = new Set();
+    for (const read of reads) {
+        if (isPlatformEnvName(read.name))
+            continue;
+        names.add(read.name);
+        if (refused.has(read.name)) {
+            readFindings.push({
+                ...read,
+                text: refusal(read.name, `read at ${read.file}:${read.line}`),
+            });
+        }
+        else if (!declared.has(read.name)) {
+            readFindings.push({
+                ...read,
+                text: `env: ${read.name} is read at ${read.file}:${read.line} but ${PROJECT_YAML} has no env_contract row for it`,
+            });
+        }
+    }
+    readFindings.sort((a, b) => compare(a.name, b.name) ||
+        compare(a.file === PROJECT_YAML ? "" : a.file, b.file === PROJECT_YAML ? "" : b.file) ||
+        a.line - b.line);
+    findings.push(...readFindings.map((f) => f.text));
+    return {
+        findings,
+        summary: `env: OK — ${names.size} names read, all declared`,
+    };
+}
+function refusal(name, where) {
+    return `env: ${name} is refused on a spoke (${where}) — a spoke's hub origin is server-only; use ${SPOKE_HUB_ORIGIN_ENV}`;
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+// ── D7 — the writer ─────────────────────────────────────────────────────────
+/** A block the writer cannot read, so it never appends to it (D7). */
+export class EnvContractError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "EnvContractError";
+    }
+}
+/** The header the writer puts above a block it creates. */
+const ENV_CONTRACT_HEADER = [
+    "# The environment variables this site's code reads. `pnpm env:declared`",
+    "# checks every literal process.env read against these rows; create-ailk",
+    "# appends rows and never edits one.",
+];
+/** The site-root app directories a row's `scope` names. */
+const SCOPE_DIRS = [
+    ["web", "apps/web/"],
+    ["api", "apps/api/"],
+    ["mcp", "apps/mcp/"],
+];
+/**
+ * `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 function planEnvRows(root, projectYamlText, opts) {
+    const parsed = parseContract(projectYamlText);
+    if (parsed !== undefined && parsed.faults.length > 0) {
+        const first = parsed.faults[0];
+        throw new EnvContractError(`project.yaml:${first?.line ?? 0}: ${first?.message ?? "a fault"} — fix the env_contract block, then re-run`);
+    }
+    const declared = new Set(parsed?.rows.map((row) => row.name) ?? []);
+    const refused = new Set(opts.topology === "spoke" ? SPOKE_REFUSED_ENV : []);
+    const files = new Map();
+    for (const read of collectSiteReads(root).reads) {
+        if (isPlatformEnvName(read.name) || refused.has(read.name))
+            continue;
+        if (declared.has(read.name))
+            continue;
+        const list = files.get(read.name) ?? [];
+        list.push(read.file);
+        files.set(read.name, list);
+    }
+    for (const name of opts.declare ?? []) {
+        if (isPlatformEnvName(name) || refused.has(name))
+            continue;
+        if (declared.has(name) || files.has(name))
+            continue;
+        files.set(name, []);
+    }
+    const added = [...files.keys()].sort(compare);
+    if (parsed !== undefined && added.length === 0) {
+        return { text: projectYamlText, added };
+    }
+    const itemIndent = parsed?.itemIndent ?? 2;
+    const pad = " ".repeat(itemIndent);
+    const rowLines = added.flatMap((name) => {
+        const readers = [...new Set(files.get(name) ?? [])].sort(compare);
+        const entry = Object.prototype.hasOwnProperty.call(opts.catalog, name)
+            ? opts.catalog[name]
+            : undefined;
+        const description = entry?.description ??
+            `Read by ${readers[0] ?? "this site"}. Describe what it sets.`;
+        const secret = entry?.secret ?? !name.startsWith("NEXT_PUBLIC_");
+        const scopes = new Set(readers.map((file) => SCOPE_DIRS.find(([, dir]) => file.startsWith(dir))?.[0]));
+        const scope = scopes.size === 1 ? [...scopes][0] : undefined;
+        return [
+            `${pad}- name: ${name}`,
+            `${pad}  description: ${JSON.stringify(description)}`,
+            `${pad}  secret: ${secret ? "true" : "false"}`,
+            ...(scope !== undefined ? [`${pad}  scope: ${scope}`] : []),
+        ];
+    });
+    const lines = projectYamlText.split("\n");
+    if (parsed === undefined) {
+        const body = lines.length > 0 && lines[lines.length - 1] === ""
+            ? lines.slice(0, -1)
+            : lines;
+        const block = rowLines.length > 0
+            ? ["env_contract:", ...rowLines]
+            : ["env_contract: []"];
+        return {
+            text: [...body, "", ...ENV_CONTRACT_HEADER, ...block, ""].join("\n"),
+            added,
+        };
+    }
+    if (parsed.flowEmpty) {
+        const keyLine = lines[parsed.keyIndex] ?? "";
+        lines[parsed.keyIndex] = keyLine.replace(/^env_contract:\s*\[\s*\]/, "env_contract:");
+        lines.splice(parsed.keyIndex + 1, 0, ...rowLines);
+        return { text: lines.join("\n"), added };
+    }
+    const at = (parsed.lastItemIndex ?? parsed.keyIndex) + 1;
+    lines.splice(at, 0, ...rowLines);
+    return { text: lines.join("\n"), added };
+}
+/**
+ * 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 function appendEnvRows(root, opts) {
+    const path = join(root, PROJECT_YAML);
+    if (!existsSync(path))
+        return { state: "no-project-yaml" };
+    const text = readFileSync(path, "utf8");
+    const plan = planEnvRows(root, text, opts);
+    if (plan.text === text)
+        return { state: "unchanged" };
+    writeFileSync(path, plan.text);
+    return { state: "written", added: plan.added };
+}