create-ailk 0.15.0 → 0.16.0

package/templates/tools/declared-env.ts

@@ -0,0 +1,1163 @@
+/**
+ * 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: readonly string[] = [
+  "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: readonly string[] = ["VERCEL_"];
+
+/** Names a spoke may neither read nor declare (D5): its hub origin is server-only. */
+export const SPOKE_REFUSED_ENV: readonly string[] = [
+  "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: string): boolean {
+  return (
+    PLATFORM_ENV_NAMES.includes(name) ||
+    PLATFORM_ENV_PREFIXES.some((prefix) => name.startsWith(prefix))
+  );
+}
+
+/** A site's topology. Restated from `topology.ts`: the scaffold copy cannot import it. */
+export type SiteTopology = "hub" | "spoke";
+
+// ── D3 — what counts as a read ──────────────────────────────────────────────
+
+/** One literal env read: the variable name and its 1-based line. */
+export interface EnvRead {
+  name: string;
+  line: number;
+}
+
+type TokenKind = "ident" | "string" | "punct" | "other";
+
+interface Token {
+  kind: TokenKind;
+  /** The identifier, the punctuator, or a string literal's decoded value. */
+  value: string;
+  line: number;
+}
+
+/** 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: string): Token[] {
+  const tokens: Token[] = [];
+  /** One entry per open template literal: the brace depth its `${` opened at. */
+  const templates: number[] = [];
+  let depth = 0;
+  let line = 1;
+  let i = 0;
+  const n = source.length;
+
+  const push = (kind: TokenKind, value: string, at: number): void => {
+    tokens.push({ kind, value, line: at });
+  };
+  const prevAllowsDivision = (): boolean => {
+    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 = (): void => {
+    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: Token[], i: number): number | undefined {
+  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: Token[], close: number): EnvRead[] {
+  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: EnvRead[] = [];
+  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: string): EnvRead[] {
+  const tokens = tokenize(source);
+  const reads: EnvRead[] = [];
+  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: readonly string[] = [
+  "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: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string, rel: string): void => {
+    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();
+}
+
+/** 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 function collectSiteReads(root: string): {
+  reads: SiteEnvRead[];
+  unreadable: Array<{ file: string; reason: string }>;
+} {
+  const reads: SiteEnvRead[] = [];
+  const unreadable: Array<{ file: string; reason: string }> = [];
+  for (const file of listScannedFiles(root)) {
+    let source: string;
+    try {
+      source = readFileSync(join(root, file), "utf8");
+    } catch (err) {
+      unreadable.push({ file, reason: (err as Error).message });
+      continue;
+    }
+    for (const read of findEnvReads(source)) reads.push({ ...read, file });
+  }
+  return { reads, unreadable };
+}
+
+// ── D1/D2 — the env_contract block ──────────────────────────────────────────
+
+/** 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 const ENV_SCOPES = ["web", "api", "mcp"] as const;
+export type EnvScope = (typeof ENV_SCOPES)[number];
+
+const ROW_KEYS = ["name", "description", "secret", "scope"] as const;
+const NAME_RE = /^[A-Z_][A-Z0-9_]*$/;
+const KEY_LINE = /^env_contract:(.*)$/;
+
+/** A raw value: its text, and whether it was quoted or a block scalar. */
+interface RawValue {
+  text: string;
+  plain: boolean;
+}
+
+/** The parsed block, with the layout the writer needs. */
+interface ParsedContract {
+  /** 0-based index of the `env_contract:` line. */
+  keyIndex: number;
+  /** Whether the key's value is the flow `[]`. */
+  flowEmpty: boolean;
+  /** Column items start at, when the block has one. */
+  itemIndent: number | undefined;
+  /** 0-based index of the block's last item-content line, when it has one. */
+  lastItemIndex: number | undefined;
+  rows: EnvContractRow[];
+  faults: EnvContractFault[];
+}
+
+/** Strip a trailing ` # comment` from a plain scalar. */
+function stripComment(text: string): string {
+  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: string,
+  fault: (message: string) => void,
+): RawValue | undefined {
+  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)) as string,
+        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: string): ParsedContract | undefined {
+  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: EnvContractFault[] = [];
+  const rows: EnvContractRow[] = [];
+  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: ParsedContract = {
+    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;
+  }
+
+  interface Item {
+    line: number;
+    keyCol: number;
+    values: Map<string, RawValue>;
+    /** The key whose block scalar is being read, and its indicator. */
+    scalar:
+      | { key: string; col: number | undefined; parts: string[]; fold: boolean }
+      | undefined;
+  }
+  let item: Item | undefined;
+  const items: Item[] = [];
+
+  const setKey = (it: Item, idx: number, body: string): void => {
+    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: Item): void => {
+    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<string, number>();
+  for (const it of items) {
+    const fault = (message: string): void => {
+      faults.push({ line: it.line, message });
+    };
+    for (const key of it.values.keys()) {
+      if (!(ROW_KEYS as readonly string[]).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 as readonly string[]).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: EnvContractRow = {
+        name,
+        description: description?.text ?? "",
+        secret: secretValue,
+        line: it.line,
+      };
+      if (
+        scope !== undefined &&
+        (ENV_SCOPES as readonly string[]).includes(scope.text)
+      ) {
+        row.scope = scope.text as EnvScope;
+      }
+      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: string): EnvContract {
+  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: string,
+): { topology: SiteTopology } | { fault: string } {
+  const path = join(root, SITE_MANIFEST_FILE);
+  if (!existsSync(path)) return { topology: "hub" };
+  let doc: unknown;
+  try {
+    doc = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    return {
+      fault: `${SITE_MANIFEST_FILE} is not JSON: ${(err as Error).message}`,
+    };
+  }
+  const value =
+    typeof doc === "object" && doc !== null
+      ? (doc as Record<string, unknown>)["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)`,
+  };
+}
+
+// ── D5 — the check ──────────────────────────────────────────────────────────
+
+/** The check's result: one line per finding, and the line to print on a pass. */
+export interface DeclaredEnvResult {
+  findings: string[];
+  summary: string;
+}
+
+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: string): DeclaredEnvResult {
+  const findings: string[] = [];
+  const yamlPath = join(root, PROJECT_YAML);
+  if (!existsSync(yamlPath)) {
+    return { findings: [`env: ${PROJECT_YAML}: missing`], summary: "" };
+  }
+  let yamlText: string;
+  try {
+    yamlText = readFileSync(yamlPath, "utf8");
+  } catch (err) {
+    return {
+      findings: [`env: ${PROJECT_YAML}: ${(err as Error).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: Array<{
+    name: string;
+    file: string;
+    line: number;
+    text: string;
+  }> = [];
+  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<string>();
+  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: string, where: string): string {
+  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: string, b: string): number {
+  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: string) {
+    super(message);
+    this.name = "EnvContractError";
+  }
+}
+
+/** 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[];
+}
+
+/** The header the writer puts above a block it creates. */
+const ENV_CONTRACT_HEADER: readonly string[] = [
+  "# 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: ReadonlyArray<[EnvScope, string]> = [
+  ["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: string,
+  projectYamlText: string,
+  opts: PlanEnvRowsOptions,
+): { text: string; added: string[] } {
+  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<string, string[]>();
+  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 };
+}
+
+/** 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 function appendEnvRows(
+  root: string,
+  opts: PlanEnvRowsOptions,
+): AppendEnvRowsResult {
+  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 };
+}