create-ailk 0.27.0 → 0.28.1

package/dist/update.js

@@ -10,10 +10,16 @@
  * version's copy — read from this package's own `templates/` when that is
  * the running version, else re-materialised from the published npm tarball
  * (`lib/fetch-template-snapshot.ts`) — and the running version's copy. A
- * conflict leaves the file untouched and is listed under "Needs review". Every
- * template test that imports a file left under review or skipped is held at
- * the site's version with it, so a run never leaves a test newer than the
- * code it exercises (#8704). A site with no record gets one backfilled from
+ * conflict leaves the file untouched and is listed under "Needs review" — but
+ * a `apps/web/messages/` catalog takes the template's new keys and keeps the
+ * site's values, reviewed only on a key-level conflict (#10173). Every
+ * template file this run would write that imports, transitively, a file left
+ * under review or skipped — or a file the site will not have — is held at the
+ * site's version with it, so a run never writes code newer than what it
+ * imports (#8704 for tests, #10173 for the rest). The env vars the written
+ * files read gain `project.yaml` `env_contract` rows (#10172), and a record
+ * row at a path no longer recorded is dropped, not refused (#10173). A site
+ * with no record gets one backfilled from
  * `.ailk-site-manifest.json`'s `patternVersion` on its first run — one row
  * per in-scope path of that version's snapshot, on disk or not (#9527) —
  * then updates normally. A site scaffolded before `@working-theory/mcp-server`
@@ -27,24 +33,32 @@
  * (#9566): the record retires the copied server files and lands the boot
  * files; the app's rename, its dependencies and delegating scripts, and the
  * bundle-delivered module files are planned here. Every refusal throws
- * before the first write.
+ * before the first write. Last, every mdx-body page in the site's `content/`
+ * with no `# ` heading gets its title and description written into its body
+ * (#7495, `body-heading.ts`); a page with one or more headings is never
+ * touched, and `content/` is never recorded.
  *
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
  */
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve, sep } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
+import { headingViolations, mdxBodyRule, migrateBodyHeadings } from "./body-heading.js";
 import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
+import { EnvContractError, planEnvRows, readEnvContract, readManifestTopology, } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
+import { exportsName, listFilesUnder, namedImportsOf } from "./lib/import-graph.js";
 import { mergeThreeWay } from "./lib/merge-three-way.js";
+import { publicTreeRemoved } from "./lib/site-modules.js";
 import { MODULE_SLICES } from "./module-architecture.js";
 import { MODULE_FLAGS_PATH, PAID_MCP_TOOLS_PATH, writeModuleFlags, writePaidMcpTools, } from "./paid-sections.js";
 import { ParseError } from "./parse-args.js";
 import { SITE_ROSTER_PATH } from "./site-roster.js";
 import { SPOKE_CHECKOUT_TEMPLATE_PATHS } from "./spoke-checkout.js";
-import { excludedRoutePaths } from "./surfaces.js";
+import { excludedRoutePaths, isRemovedPublicRoutePath } from "./surfaces.js";
 import { DATABASE_BOOT_FILES, ROOT_TOOL_FILES, TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
 import { MCP_SEAM_PATH, MCP_SERVER_HUB, TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
 /** A refusal the CLI exits 2 on, thrown before anything is written. */
@@ -165,6 +179,7 @@ function containsKnownPath(prefix, knownPaths) {
 const TEST_FILE = /(^|\/)__tests__\/|\.(test|spec)\.[cm]?[jt]sx?$/;
 /** Module specifiers `import`/`export … from`, `import()`, `require()` and `jest.mock()` name. */
 const IMPORT_SPECIFIER = /\bfrom\s*["']([^"']+)["']|\bimport\s*["']([^"']+)["']|\b(?:import|require|jest\.mock|jest\.requireActual)\s*\(\s*["']([^"']+)["']/g;
+const WEB_ROOT = "apps/web/";
 const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
 /**
  * The record-style paths a relative specifier in `fromPath` can resolve to:
@@ -172,8 +187,10 @@ const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs"
  * swapped for its TypeScript source, and as a directory's `index.*`.
  */
 function relativeImportCandidates(fromPath, specifier) {
-    const parts = fromPath.split("/").slice(0, -1);
-    for (const segment of specifier.split("/")) {
+    // `@/x` is apps/web's `x` — its tsconfig `paths`; no other app declares one.
+    const alias = specifier.startsWith("@/") && fromPath.startsWith(WEB_ROOT);
+    const parts = alias ? ["apps", "web"] : fromPath.split("/").slice(0, -1);
+    for (const segment of (alias ? specifier.slice(2) : specifier).split("/")) {
         if (segment === "" || segment === ".")
             continue;
         if (segment === "..")
@@ -191,13 +208,24 @@ function relativeImportCandidates(fromPath, specifier) {
     out.push(...RESOLVE_EXTENSIONS.map((ext) => `${target}/index${ext}`));
     return out;
 }
-/** The files of `held` that `text`, the source of `fromPath`, imports by relative specifier. */
-function importedHeldFiles(fromPath, text, held) {
+/** Whether `specifier` names a site file: relative, or `@/` from an apps/web file. */
+function isLocal(fromPath, specifier) {
+    return specifier.startsWith(".") || (specifier.startsWith("@/") && fromPath.startsWith(WEB_ROOT));
+}
+/** The local module specifiers `text` names. */
+function localSpecifiers(fromPath, text) {
     const out = new Set();
     for (const match of text.matchAll(IMPORT_SPECIFIER)) {
         const specifier = match[1] ?? match[2] ?? match[3];
-        if (specifier === undefined || !specifier.startsWith("."))
-            continue;
+        if (specifier !== undefined && isLocal(fromPath, specifier))
+            out.add(specifier);
+    }
+    return [...out];
+}
+/** The files of `held` that `text`, the source of `fromPath`, imports by local specifier. */
+function importedHeldFiles(fromPath, text, held) {
+    const out = new Set();
+    for (const specifier of localSpecifiers(fromPath, text)) {
         for (const candidate of relativeImportCandidates(fromPath, specifier)) {
             if (held.has(candidate))
                 out.add(candidate);
@@ -205,6 +233,57 @@ function importedHeldFiles(fromPath, text, held) {
     }
     return [...out];
 }
+/** The `apps/web/messages/` catalogs next-intl loads by locale, never by import. */
+const MESSAGES_JSON = /^apps\/web\/messages\/(?:[^/]+\/)*[^/]+\.json$/;
+const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The site's messages catalog with every key the template's copy has and it
+ * lacks (#10173): the site's values always win, nothing is removed, and the
+ * keys it gains follow its own. A key that is an object on one side and a
+ * value on the other is a conflict, and nothing is merged.
+ */
+export function mergeMessagesAdditively(ours, theirs) {
+    let oursDoc;
+    let theirsDoc;
+    try {
+        oursDoc = JSON.parse(ours);
+        theirsDoc = JSON.parse(theirs);
+    }
+    catch (err) {
+        return { status: "invalid", reason: `not JSON: ${err.message}` };
+    }
+    if (!isPlainObject(oursDoc) || !isPlainObject(theirsDoc)) {
+        return { status: "invalid", reason: "the root is not an object" };
+    }
+    const conflicts = [];
+    let added = 0;
+    const walk = (o, t, at) => {
+        for (const [key, value] of Object.entries(t)) {
+            if (UNSAFE_KEYS.has(key))
+                continue; // never written through, so never a prototype change
+            const path = at === "" ? key : `${at}.${key}`;
+            if (!Object.prototype.hasOwnProperty.call(o, key)) {
+                o[key] = value;
+                added++;
+                continue;
+            }
+            const mine = o[key];
+            if (isPlainObject(mine) && isPlainObject(value))
+                walk(mine, value, path);
+            else if (isPlainObject(mine) || isPlainObject(value))
+                conflicts.push(path);
+        }
+    };
+    walk(oursDoc, theirsDoc, "");
+    if (conflicts.length > 0)
+        return { status: "conflict", keys: conflicts };
+    const indent = /\n(\t| +)"/.exec(ours)?.[1] ?? 2;
+    const text = JSON.stringify(oursDoc, null, indent) + (ours.endsWith("\n") ? "\n" : "");
+    return { status: "merged", text: added === 0 ? ours : text, added };
+}
 // ── The MCP move (#9567): a copied apps/mcp becomes the boot set ──────────
 const MCP_SERVER_PACKAGE = "@working-theory/mcp-server";
 const MCP_PACKAGE_JSON = "apps/mcp/package.json";
@@ -784,9 +863,14 @@ export async function updateSite(opts) {
     const recordPath = join(targetDir, TEMPLATE_RECORD_PATH);
     let record;
     let backfillPatternVersion;
+    // #10173 — a row at a path a later create-ailk no longer records (a
+    // generated file) is dropped and reported, never a refusal of the run.
+    const droppedRows = [];
     if (existsSync(recordPath)) {
         try {
-            record = parseTemplateRecord(readFileSync(recordPath, "utf8"));
+            record = parseTemplateRecord(readFileSync(recordPath, "utf8"), {
+                onUnrecordable: (key) => droppedRows.push(key),
+            });
         }
         catch (err) {
             throw new UpdateRefusedError(err.message);
@@ -1076,6 +1160,26 @@ export async function updateSite(opts) {
             nextFiles[path] = { sha256: newHash, version };
             merged.push(path);
         }
+        else if (mergeResult.status === "conflict" && MESSAGES_JSON.test(path)) {
+            // #10173 — a messages catalog takes the template's new keys and keeps
+            // every value the site has; only a key-level conflict is reviewed.
+            const additive = mergeMessagesAdditively(diskBytes.toString("utf8"), Buffer.from(newBytes).toString("utf8"));
+            if (additive.status === "conflict") {
+                review.push({
+                    path,
+                    reason: `conflicts with the template change ${rec.version} → ${version} at key ${additive.keys.join(", ")}`,
+                });
+            }
+            else if (additive.status === "invalid") {
+                review.push({ path, reason: `the additive pass could not run: ${additive.reason}` });
+            }
+            else {
+                if (additive.added > 0)
+                    writes.push({ path, bytes: Buffer.from(additive.text, "utf8") });
+                nextFiles[path] = { sha256: newHash, version };
+                merged.push(path);
+            }
+        }
         else if (mergeResult.status === "conflict") {
             review.push({
                 path,
@@ -1091,10 +1195,17 @@ export async function updateSite(opts) {
     // module object at a boot-set path goes before the writes below, and the
     // template's re-export lands there as an added file.
     const retired = new Set(apiMove?.deletes ?? []);
+    // #10040 D10 — a site that dropped `marketing` never gains a public route
+    // file from a newer template, tombstone or not.
+    const marketingRemoved = publicTreeRemoved(targetDir);
     const knownPaths = new Set([...Object.keys(record.files), ...(knownSnapshotPaths ?? [])]);
     for (const path of [...newMap.keys()].sort()) {
         if (Object.prototype.hasOwnProperty.call(record.files, path))
             continue;
+        if (marketingRemoved && isRemovedPublicRoutePath(path)) {
+            skipped.push({ path, reason: "marketing removed" });
+            continue;
+        }
         // The guard runs before the disk check, so a full-copy site's boot path
         // reads as guarded, never as "exists, not in the record" (#9569 DD8).
         if (bootFileGuarded(path)) {
@@ -1139,46 +1250,209 @@ export async function updateSite(opts) {
     // exercising the held file is enough. A held test-support file
     // (`__tests__/fixtures.ts`) holds the tests importing it in turn, until no
     // further test is held.
+    //
+    // #10173 — the same holds for every other template file this run would
+    // write: one importing a held file stays at the site's version (or, when
+    // new, is not added), so the written tree never imports an export the held
+    // file lacks. A written file whose relative import names a file the site
+    // will not have once the run lands is held too, under that missing path.
+    // Only the bytes being written are read for a non-test file: the site's
+    // own copy already compiles against what it has.
     const heldFiles = new Set([...review, ...skipped].map((row) => row.path));
+    // The files left alone outright, before any hold-back joins them.
+    const leftAlone = new Set(heldFiles);
+    const writtenBytes = new Map(writes.map((w) => [w.path, w.bytes]));
+    // The moves' removals (#9567, #9566) land too: never code that stays.
+    const deleting = new Set([...deletes, ...(mcpMove?.deletes ?? []), ...(apiMove?.deletes ?? [])]);
+    const adding = new Set(added);
     const heldBackByFile = new Map();
-    const heldTests = new Set();
-    const moving = [...updated, ...merged, ...added, ...removed, ...current]
-        .filter((path) => TEST_FILE.test(path))
+    const heldPaths = new Set();
+    const moving = [...new Set([...updated, ...merged, ...added, ...removed, ...current])].sort();
+    const isFileCache = new Map();
+    const isFileOnDisk = (path) => {
+        let hit = isFileCache.get(path);
+        if (hit === undefined) {
+            try {
+                hit = statSync(join(targetDir, ...path.split("/"))).isFile();
+            }
+            catch {
+                hit = false;
+            }
+            isFileCache.set(path, hit);
+        }
+        return hit;
+    };
+    // What the run rewrites after the record's writes, never from the template.
+    const rewrittenLater = new Set([
+        MODULE_FLAGS_PATH,
+        PAID_MCP_TOOLS_PATH,
+        ...(mcpMove?.seam !== undefined ? [MCP_SEAM_PATH] : []),
+    ]);
+    /** Whether `path` is a file once this run's writes and deletes, less the held ones, land. */
+    const presentAfter = (path) => {
+        if (heldPaths.has(path))
+            return isFileOnDisk(path);
+        if (adding.has(path) || rewrittenLater.has(path))
+            return true;
+        if (deleting.has(path))
+            return false;
+        return isFileOnDisk(path);
+    };
+    const sourcesOf = new Map();
+    for (const path of moving) {
+        const writing = writtenBytes.get(path);
+        const written = writing !== undefined ? writing.toString("utf8") : undefined;
+        const newBytes = newMap.get(path);
+        const newText = newBytes !== undefined ? Buffer.from(newBytes).toString("utf8") : undefined;
+        const all = [];
+        if (TEST_FILE.test(path)) {
+            const abs = join(targetDir, ...path.split("/"));
+            if (existsSync(abs))
+                all.push(readFileSync(abs, "utf8"));
+            if (newText !== undefined)
+                all.push(newText);
+            if (written !== undefined)
+                all.push(written);
+        }
+        else {
+            const text = written ?? newText;
+            if (text !== undefined)
+                all.push(text);
+        }
+        sourcesOf.set(path, { all, written });
+    }
+    const SOURCE_FILE = /\.[cm]?[jt]sx?$/;
+    const hold = (path, file, missing) => {
+        const entry = heldBackByFile.get(file) ?? { tests: [], importers: [], missing };
+        const list = TEST_FILE.test(path) ? entry.tests : entry.importers;
+        if (!list.includes(path))
+            list.push(path);
+        heldBackByFile.set(file, entry);
+    };
+    const importsCache = new Map();
+    const namedImportsAt = (path, text) => {
+        let hit = importsCache.get(path);
+        if (hit === undefined)
+            importsCache.set(path, (hit = namedImportsOf(text)));
+        return hit;
+    };
+    const textCache = new Map();
+    const diskText = (path) => {
+        if (!textCache.has(path)) {
+            textCache.set(path, isFileOnDisk(path) ? readFileSync(join(targetDir, ...path.split("/")), "utf8") : undefined);
+        }
+        return textCache.get(path);
+    };
+    // Every app source file this run does not write: the code that keeps the
+    // site's version and must still find what it imports.
+    const stayingFiles = [...listFilesUnder(targetDir, ["apps/web", "apps/api", "apps/mcp"])]
+        .filter((path) => !writtenBytes.has(path) && !deleting.has(path))
         .sort();
-    for (let grew = heldFiles.size > 0; grew;) {
+    let grew = true;
+    const holdPath = (path) => {
+        heldPaths.add(path);
+        heldFiles.add(path);
+        grew = true;
+    };
+    while (grew) {
         grew = false;
         for (const path of moving) {
-            if (heldTests.has(path))
+            if (heldPaths.has(path))
                 continue;
-            const sources = [];
-            const abs = join(targetDir, ...path.split("/"));
-            if (existsSync(abs))
-                sources.push(readFileSync(abs, "utf8"));
-            const newBytes = newMap.get(path);
-            if (newBytes !== undefined)
-                sources.push(Buffer.from(newBytes).toString("utf8"));
-            const imported = new Set(sources.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
-            if (imported.size === 0)
+            const { all, written } = sourcesOf.get(path);
+            const imported = new Set(all.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
+            const missing = new Set();
+            if (written !== undefined && !TEST_FILE.test(path)) {
+                for (const specifier of localSpecifiers(path, written)) {
+                    const candidates = relativeImportCandidates(path, specifier);
+                    if (candidates.some((c) => heldFiles.has(c) || presentAfter(c)))
+                        continue;
+                    // A dot-directory (`.source/`, `.next/`) is build output the site
+                    // generates, never a file update could have carried.
+                    if (/(^|\/)\.[^./][^/]*\//.test(candidates[0]))
+                        continue;
+                    missing.add(candidates[0]);
+                }
+            }
+            // A named import the file it resolves to — staying at the site's
+            // version — does not export (a regenerated nav-config, say).
+            const lacking = new Set();
+            if (written !== undefined) {
+                for (const { specifier, names } of namedImportsOf(written)) {
+                    if (!isLocal(path, specifier))
+                        continue;
+                    const target = relativeImportCandidates(path, specifier).find(isFileOnDisk);
+                    if (target === undefined || heldFiles.has(target) || rewrittenLater.has(target))
+                        continue;
+                    if (writtenBytes.has(target) && !heldPaths.has(target))
+                        continue;
+                    if (deleting.has(target))
+                        continue; // the missing check above owns it
+                    if (!SOURCE_FILE.test(target))
+                        continue;
+                    const text = diskText(target);
+                    if (text !== undefined && names.some((name) => !exportsName(text, name)))
+                        lacking.add(target);
+                }
+            }
+            if (imported.size === 0 && missing.size === 0 && lacking.size === 0)
+                continue;
+            holdPath(path);
+            for (const file of imported)
+                hold(path, file, false);
+            for (const file of missing)
+                hold(path, file, true);
+            for (const file of lacking)
+                hold(path, file, false);
+        }
+        // The reverse: a file staying at the site's version imports, by name,
+        // something the written copy of its target no longer exports.
+        for (const staying of [...stayingFiles, ...heldPaths]) {
+            const text = diskText(staying);
+            if (text === undefined)
+                continue;
+            // A file left alone keeps the code it was written against: every
+            // template file it imports stays with it, whatever that file exports.
+            if (leftAlone.has(staying)) {
+                for (const specifier of localSpecifiers(staying, text)) {
+                    const target = relativeImportCandidates(staying, specifier).find((c) => writtenBytes.has(c) && !heldPaths.has(c));
+                    if (target === undefined || !SOURCE_FILE.test(target))
+                        continue;
+                    holdPath(target);
+                    hold(target, staying, false);
+                }
                 continue;
-            heldTests.add(path);
-            heldFiles.add(path);
-            grew = true;
-            for (const file of imported) {
-                heldBackByFile.set(file, [...(heldBackByFile.get(file) ?? []), path]);
+            }
+            for (const { specifier, names } of namedImportsAt(staying, text)) {
+                if (!isLocal(staying, specifier))
+                    continue;
+                const target = relativeImportCandidates(staying, specifier).find((c) => writtenBytes.has(c) && !heldPaths.has(c));
+                if (target === undefined || !SOURCE_FILE.test(target))
+                    continue;
+                const next = writtenBytes.get(target).toString("utf8");
+                if (names.every((name) => exportsName(next, name)))
+                    continue;
+                holdPath(target);
+                hold(target, staying, false);
             }
         }
     }
-    for (const path of heldTests) {
+    for (const path of heldPaths) {
         const recorded = record.files[path];
         if (recorded !== undefined)
             nextFiles[path] = recorded;
         else
             delete nextFiles[path];
     }
-    const notHeld = (path) => !heldTests.has(path);
+    const notHeld = (path) => !heldPaths.has(path);
     const heldBack = [...heldBackByFile.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
-        .map(([file, tests]) => ({ file, tests }));
+        .map(([file, { tests, importers, missing }]) => ({
+        file,
+        tests: tests.sort(),
+        ...(importers.length > 0 ? { importers: importers.sort() } : {}),
+        ...(missing ? { missing: true } : {}),
+    }));
     // ── Apply: writes and removals, then the record (D4 Order) ───────────
     // #9566 — the API move's removals first: a retired file at a boot-set
     // path is overwritten by the write that follows, never deleted after it.
@@ -1204,7 +1478,9 @@ export async function updateSite(opts) {
         removed: removed.filter(notHeld),
         current: current.filter(notHeld),
     };
-    const recordChanged = backfilled !== undefined || Object.values(moved).some((paths) => paths.length > 0);
+    const recordChanged = backfilled !== undefined ||
+        droppedRows.length > 0 ||
+        Object.values(moved).some((paths) => paths.length > 0);
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
@@ -1250,6 +1526,50 @@ export async function updateSite(opts) {
         writeFileSync(join(targetDir, ...WEB_PACKAGE_JSON.split("/")), webPackageJson);
         moved.updated.push(WEB_PACKAGE_JSON);
     }
+    // #10172 — the env vars the written files read get an env_contract row
+    // when the site's project.yaml has a block and no row for them, so the
+    // code update brings never fails `env:declared`. Rows are appended, never
+    // edited; a hub with no block is not checked and gains none.
+    const envRowsAdded = [];
+    const projectYamlPath = join(targetDir, "project.yaml");
+    const writtenPaths = new Set(writes.map((w) => w.path).filter(notHeld));
+    if (writtenPaths.size > 0 && existsSync(projectYamlPath)) {
+        const yamlText = readFileSync(projectYamlPath, "utf8");
+        const topology = readManifestTopology(targetDir);
+        if (readEnvContract(yamlText).present && "topology" in topology) {
+            try {
+                const plan = planEnvRows(targetDir, yamlText, {
+                    topology: topology.topology,
+                    catalog: ENV_CATALOG,
+                    onlyFiles: writtenPaths,
+                });
+                if (plan.added.length > 0) {
+                    writeFileSync(projectYamlPath, plan.text);
+                    envRowsAdded.push(...plan.added);
+                }
+            }
+            catch (err) {
+                if (!(err instanceof EnvContractError))
+                    throw err;
+                review.push({ path: "project.yaml", reason: `no env_contract rows added: ${err.message}` });
+            }
+        }
+    }
+    // #7495 D6 — the page body owns its H1: give every heading-less mdx-body
+    // page its title and description, read the rule after the writes so a
+    // route this run added counts. Its rows join `review` after `heldFiles`
+    // was computed, so a content path never holds a template test back.
+    const contentDir = join(targetDir, "content");
+    const rule = mdxBodyRule(targetDir);
+    const sitePath = (abs) => relative(targetDir, abs).split(sep).join("/");
+    const headings = migrateBodyHeadings(contentDir, rule);
+    for (const { path, count } of headingViolations(contentDir, rule)) {
+        if (count > 1)
+            review.push({ path: sitePath(path), reason: `${count} '# ' headings; keep one` });
+    }
+    for (const { path, reason } of headings.refused) {
+        review.push({ path: sitePath(path), reason: `no '# ' heading added: ${reason}` });
+    }
     return {
         targetDir,
         version,
@@ -1257,7 +1577,10 @@ export async function updateSite(opts) {
         review,
         skipped,
         heldBack,
+        headingsAdded: headings.written.map(sitePath),
         ...(backfilled !== undefined ? { backfilled } : {}),
+        ...(envRowsAdded.length > 0 ? { envRowsAdded } : {}),
+        ...(droppedRows.length > 0 ? { droppedRows: droppedRows.sort() } : {}),
     };
 }
 /** The printed report (D9): one section per non-empty list, in order. */
@@ -1272,6 +1595,7 @@ export function formatUpdateReport(result) {
         ["Added", result.added],
         ["Removed", result.removed],
         ["Already current", result.current],
+        ["Page heading added", result.headingsAdded],
     ];
     for (const [label, paths] of sections) {
         if (paths.length === 0)
@@ -1283,9 +1607,18 @@ export function formatUpdateReport(result) {
         lines.push(`Needs review (${result.review.length}):`);
         lines.push(...result.review.map((row) => `  ${row.path} — ${row.reason}`));
     }
-    for (const { file, tests } of result.heldBack) {
-        lines.push(`Held back with ${file} (${tests.length}):`);
-        lines.push(...tests.map((path) => `  ${path}`));
+    for (const { file, tests, importers = [], missing } of result.heldBack) {
+        const held = [...tests, ...importers].sort();
+        lines.push(`Held back with ${file}${missing ? " (not in this site)" : ""} (${held.length}):`);
+        lines.push(...held.map((path) => `  ${path}`));
+    }
+    if (result.envRowsAdded !== undefined) {
+        lines.push(`project.yaml env_contract rows added (${result.envRowsAdded.length}):`);
+        lines.push(...result.envRowsAdded.map((name) => `  ${name}`));
+    }
+    if (result.droppedRows !== undefined) {
+        lines.push(`Dropped from ${TEMPLATE_RECORD_PATH}, no longer recorded (${result.droppedRows.length}):`);
+        lines.push(...result.droppedRows.map((path) => `  ${path}`));
     }
     if (result.skipped.length > 0) {
         lines.push(`Skipped (${result.skipped.length}):`);
@@ -1297,8 +1630,11 @@ export function formatUpdateReport(result) {
         result.added.length === 0 &&
         result.removed.length === 0 &&
         result.current.length === 0 &&
+        result.headingsAdded.length === 0 &&
         result.review.length === 0 &&
-        result.skipped.length === 0;
+        result.skipped.length === 0 &&
+        result.envRowsAdded === undefined &&
+        result.droppedRows === undefined;
     if (nothingHappened) {
         return `[create-ailk] Already up to date (create-ailk ${result.version}).\n`;
     }
@@ -1329,11 +1665,18 @@ untouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the
 app jest configs require, whose template copy changed is overwritten. An
 edited file whose template copy also changed is three-way merged with
 \`git\` (git must be on PATH); a conflict leaves the file alone and is
-listed under "Needs review". Every template test that imports a file
-left under "Needs review" or "Skipped" (by a relative import) is held at the
-site's version with it, its record entry is not advanced, and it is listed
-under "Held back with <file>" — reconcile the file, then run update again to
-bring its tests forward. Every other file in the run still updates.
+listed under "Needs review"; an apps/web/messages catalog instead gains the
+template's new keys and keeps every value it has, and is reviewed only when a
+key is an object on one side and a value on the other. Every template file,
+test or not, that imports a file left under "Needs review" or "Skipped" (by a
+relative or @/ import, transitively) is held at the site's version with it,
+its record entry is not advanced, and it is listed under "Held back with
+<file>" — reconcile the file, then run update again to bring it forward. A
+written file whose import names a file the site will not have is held the
+same way, under "Held back with <file> (not in this site)". Every other file
+in the run still updates. When project.yaml has an env_contract block, each
+env var the written files read that has no row gains one; no row is edited.
+A record row at a path create-ailk no longer records is dropped and listed.
 A site with no record gets one on its first run, from the version its
 .ailk-site-manifest.json already records. A site scaffolded before
 @working-theory/mcp-server has its copied apps/mcp moved to the boot set:
@@ -1344,7 +1687,11 @@ copied apps/api moved to the boot file: the app becomes @working-theory/app-api,
 the package and the six @working-theory/api-<module> packages join
 apps/api/package.json, its bins and build:vercel delegate to the package, and
 the copied server files go. Run \`pnpm install\` after either move, since the
-app's package.json gained dependencies. Commit before running, and review the
+app's package.json gained dependencies. Each mdx-body page in content/ with no
+'# ' heading gets its title and description written into its body as its
+heading and intro, listed under "Page heading added"; a page with one heading
+is left as it is, and one with several, or one whose frontmatter it cannot
+read, is listed under "Needs review". Commit before running, and review the
 diff after.
 `;
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.49.0",
-    "@working-theory/templates": "0.49.0"
+    "@working-theory/schema": "0.50.0",
+    "@working-theory/templates": "0.50.0"
   },
   "repository": {
     "type": "git",

package/release-scope.json

@@ -2,7 +2,8 @@
   "templates": {
     "marketing-site-free": "released",
     "marketing-site": "released",
-    "saas-product": "gated"
+    "saas-product": "gated",
+    "hub": "released"
   },
   "shapes": {
     "organization-product": "released",