create-ailk 0.28.0 → 0.28.1

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

@@ -5,17 +5,33 @@ export interface UnreadChromeKnob {
     /** Overlay-relative path of the reader file, with `/` separators. */
     file: string;
 }
+/** One overlay file that reads a knob. */
+export interface ChromeReader {
+    /** Overlay-relative path, with `/` separators. */
+    file: string;
+    /** Present when `file` reads the knob only through its imports: the files it reaches that read it directly. */
+    via?: string[];
+}
 /** The pattern that means "this text reads `knob`". */
 export declare function chromeReadPattern(knob: string): RegExp;
 /**
- * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
- * fails closed (throws, naming the directory) when it is absent or unreadable,
- * so a broken overlay can never read as "nothing reads any knob".
+ * knob → the overlay files that read it, sorted by file; one that reads it
+ * only through relative imports carries `via`. Scans `<templatesDir>/apps/web`; fails closed (throws, naming the directory)
+ * when it is absent or unreadable, so a broken overlay can never read as
+ * "nothing reads any knob".
  */
-export declare function chromeKnobReaders(templatesDir: string): Map<string, string[]>;
+export declare function chromeKnobReaders(templatesDir: string): Map<string, ChromeReader[]>;
 /**
  * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
  * the shipped overlay's `file` reads it, the site has its own `file`, and the
  * site's `file` does not read it. A reader file the site lacks is skipped.
+ *
+ * A pair the overlay credits only through an import is also satisfied when
+ * some site file outside its `via` reads the knob directly: a site from before
+ * the read moved into the helper renders it in its own place (#10156). So the
+ * import credit adds a pair only for a knob the site reads nowhere but its
+ * helpers. It is per file, not per export: a site whose home page drops the
+ * helper import is named for every knob that helper reads — a refusal the
+ * operator passes with `--allow-unread-chrome`, never a silent miss.
  */
-export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly string[]>, siteDir: string): UnreadChromeKnob[];
+export declare function unreadChromeKnobs(resolved: ResolvedSiteChrome, readers: ReadonlyMap<string, readonly ChromeReader[]>, siteDir: string): UnreadChromeKnob[];

package/dist/lib/chrome-readers.js

@@ -11,12 +11,16 @@
  *   each knob — nothing is hard-coded, so a new reader file is picked up.
  * - `unreadChromeKnobs` compares the site's own copy of each reader file.
  *
- * "Reads `knob`" means the file's text matches `(?:siteChrome|chrome)\.<knob>\b`.
- * A file that reads a knob under another name (a destructured alias) is not
- * recognised — accepted (spec § Clarifications, detection).
+ * A file "reads `knob` directly" when its text matches
+ * `(?:siteChrome|chrome)\.<knob>\b`, and "reads" it when it or a file it
+ * imports by a relative path, at any depth, reads it directly — so the layout
+ * stays a reader of `innerPages` after #10106 moved that read into
+ * `lib/page-chrome.ts` (#10156). A file that reads a knob under another name
+ * (a destructured alias) is not recognised — accepted (spec § Clarifications,
+ * detection).
  */
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, posix } from "node:path";
 import { DEFAULT_SITE_CHROME, } from "../site-chrome.js";
 /** The overlay tree the generated app files live under. */
 const OVERLAY_WEB_DIR = ["apps", "web"];
@@ -31,41 +35,126 @@ function listSources(root, dir, out) {
     for (const entry of readdirSync(join(root, dir), { withFileTypes: true })) {
         const rel = `${dir}/${entry.name}`;
         if (entry.isDirectory()) {
-            if (entry.name !== "__tests__")
+            if (entry.name !== "__tests__" &&
+                entry.name !== "node_modules" &&
+                !entry.name.startsWith(".")) {
                 listSources(root, rel, out);
+            }
         }
         else if (/\.tsx?$/.test(entry.name)) {
             out.push(rel);
         }
     }
 }
+/** A relative module specifier in an import, export-from or dynamic import. */
+const RELATIVE_IMPORT = /(?:\bfrom|\bimport)\s*\(?\s*["'](\.{1,2}\/[^"']+)["']/g;
+function sourceTree(root) {
+    const texts = new Map();
+    const closures = new Map();
+    const importLists = new Map();
+    const text = (file) => {
+        if (!texts.has(file)) {
+            const abs = join(root, file);
+            texts.set(file, existsSync(abs) ? readFileSync(abs, "utf8") : null);
+        }
+        return texts.get(file);
+    };
+    /** The files `file` imports by a relative path that exist under the root; `./x.js` may name `x.ts`. */
+    const imports = (file) => {
+        const cached = importLists.get(file);
+        if (cached !== undefined)
+            return cached;
+        const out = [];
+        for (const match of (text(file) ?? "").matchAll(RELATIVE_IMPORT)) {
+            const base = posix
+                .normalize(posix.join(posix.dirname(file), match[1]))
+                .replace(/\/$/, "");
+            if (base.startsWith(".."))
+                continue;
+            const stem = base.replace(/\.(?:js|jsx)$/, "");
+            const hit = [
+                base,
+                `${stem}.ts`,
+                `${stem}.tsx`,
+                `${stem}/index.ts`,
+                `${stem}/index.tsx`,
+            ].find((candidate) => /\.tsx?$/.test(candidate) && text(candidate) !== null);
+            if (hit !== undefined)
+                out.push(hit);
+        }
+        importLists.set(file, out);
+        return out;
+    };
+    const reached = (file) => {
+        let closure = closures.get(file);
+        if (closure === undefined) {
+            closure = new Set();
+            const stack = [...imports(file)];
+            while (stack.length > 0) {
+                const next = stack.pop();
+                if (next === file || closure.has(next))
+                    continue;
+                closure.add(next);
+                stack.push(...imports(next));
+            }
+            closures.set(file, closure);
+        }
+        return closure;
+    };
+    const readsDirectly = (file, pattern) => pattern.test(text(file) ?? "");
+    return {
+        text,
+        reached,
+        readsDirectly,
+        reads: (file, pattern) => readsDirectly(file, pattern) ||
+            [...reached(file)].some((dep) => readsDirectly(dep, pattern)),
+    };
+}
 /**
- * knob → the overlay files that read it, sorted. Scans `<templatesDir>/apps/web`;
- * fails closed (throws, naming the directory) when it is absent or unreadable,
- * so a broken overlay can never read as "nothing reads any knob".
+ * knob → the overlay files that read it, sorted by file; one that reads it
+ * only through relative imports carries `via`. Scans `<templatesDir>/apps/web`; fails closed (throws, naming the directory)
+ * when it is absent or unreadable, so a broken overlay can never read as
+ * "nothing reads any knob".
  */
 export function chromeKnobReaders(templatesDir) {
     const webDir = join(templatesDir, ...OVERLAY_WEB_DIR);
-    const readers = new Map();
+    const direct = new Map();
+    const files = [];
+    const tree = sourceTree(templatesDir);
     try {
         if (!existsSync(webDir))
             throw new Error("missing");
-        const files = [];
         listSources(templatesDir, OVERLAY_WEB_DIR.join("/"), files);
-        for (const file of files.sort()) {
-            const text = readFileSync(join(templatesDir, file), "utf8");
-            for (const match of text.matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
+        files.sort();
+        for (const file of files) {
+            for (const match of tree
+                .text(file)
+                .matchAll(new RegExp(`${READ_HEAD}([A-Za-z_$][\\w$]*)\\b`, "g"))) {
                 const knob = match[1];
-                const list = readers.get(knob) ?? [];
+                const list = direct.get(knob) ?? [];
                 if (!list.includes(file))
                     list.push(file);
-                readers.set(knob, list);
+                direct.set(knob, list);
             }
         }
     }
     catch {
         throw new Error(`cannot check chrome knobs: the overlay has no readable apps/web at ${webDir}. Reinstall create-ailk.`);
     }
+    const readers = new Map();
+    for (const [knob, directFiles] of direct) {
+        const list = [];
+        for (const file of files) {
+            if (directFiles.includes(file)) {
+                list.push({ file });
+                continue;
+            }
+            const via = directFiles.filter((reader) => tree.reached(file).has(reader));
+            if (via.length > 0)
+                list.push({ file, via });
+        }
+        readers.set(knob, list);
+    }
     return readers;
 }
 /** A knob is set when it differs from its default; an optional knob (no default) when present. */
@@ -81,19 +170,38 @@ function isSet(resolved, knob) {
  * The `(knob, file)` pairs where the resolved chrome sets a non-default `knob`,
  * the shipped overlay's `file` reads it, the site has its own `file`, and the
  * site's `file` does not read it. A reader file the site lacks is skipped.
+ *
+ * A pair the overlay credits only through an import is also satisfied when
+ * some site file outside its `via` reads the knob directly: a site from before
+ * the read moved into the helper renders it in its own place (#10156). So the
+ * import credit adds a pair only for a knob the site reads nowhere but its
+ * helpers. It is per file, not per export: a site whose home page drops the
+ * helper import is named for every knob that helper reads — a refusal the
+ * operator passes with `--allow-unread-chrome`, never a silent miss.
  */
 export function unreadChromeKnobs(resolved, readers, siteDir) {
     const out = [];
+    const site = sourceTree(siteDir);
+    let siteFiles;
     for (const knob of Object.keys(resolved).sort()) {
         if (!isSet(resolved, knob))
             continue;
         const pattern = chromeReadPattern(knob);
-        for (const file of readers.get(knob) ?? []) {
-            const abs = join(siteDir, file);
-            if (!existsSync(abs))
+        for (const { file, via } of readers.get(knob) ?? []) {
+            if (site.text(file) === null || site.reads(file, pattern))
                 continue;
-            if (!pattern.test(readFileSync(abs, "utf8")))
-                out.push({ knob, file });
+            if (via !== undefined) {
+                if (siteFiles === undefined) {
+                    siteFiles = [];
+                    if (existsSync(join(siteDir, ...OVERLAY_WEB_DIR))) {
+                        listSources(siteDir, OVERLAY_WEB_DIR.join("/"), siteFiles);
+                    }
+                }
+                const elsewhere = siteFiles.some((other) => !via.includes(other) && site.readsDirectly(other, pattern));
+                if (elsewhere)
+                    continue;
+            }
+            out.push({ knob, file });
         }
     }
     return out;

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

@@ -109,6 +109,12 @@ export interface PlanEnvRowsOptions {
      * with no reader and so no `scope`; a platform or refused name is skipped.
      */
     declare?: readonly string[];
+    /**
+     * When set, only reads in these site-relative files get a row (#10173):
+     * `update` declares what the files it wrote read, never a name only the
+     * site's own code reads.
+     */
+    onlyFiles?: ReadonlySet<string>;
 }
 /**
  * `projectYamlText` with a row appended for every name the site at `root`

package/dist/lib/declared-env.js

@@ -904,6 +904,8 @@ export function planEnvRows(root, projectYamlText, opts) {
     const refused = new Set(opts.topology === "spoke" ? SPOKE_REFUSED_ENV : []);
     const files = new Map();
     for (const read of collectSiteReads(root).reads) {
+        if (opts.onlyFiles !== undefined && !opts.onlyFiles.has(read.file))
+            continue;
         if (isPlatformEnvName(read.name) || refused.has(read.name))
             continue;
         if (declared.has(read.name))

package/dist/lib/import-graph.d.ts

@@ -27,3 +27,19 @@ export declare function resolveRelativeImport(fromFile: string, spec: string, ca
  * @param seeds repo-relative, "/"-separated files the closure starts from.
  */
 export declare function importClosure(repoRoot: string, roots: readonly string[], seeds: Iterable<string>): Set<string>;
+/**
+ * The names a module imports from each specifier, textually (#10173): the
+ * members of a `{ … }` list (an `a as b` member names `a`, a `type a` member
+ * `a`) and `default` for a default import. A namespace import (`* as x`) and
+ * a side-effect import name nothing.
+ */
+export declare function namedImportsOf(text: string): Array<{
+    specifier: string;
+    names: string[];
+}>;
+/**
+ * Whether module `text` exports `name`, textually. Fails toward `true` — an
+ * `export *`, or a destructuring export, could export anything — so a caller
+ * that holds a file back on `false` never holds one that does export it.
+ */
+export declare function exportsName(text: string, name: string): boolean;

package/dist/lib/import-graph.js

@@ -138,3 +138,56 @@ export function importClosure(repoRoot, roots, seeds) {
     }
     return closed;
 }
+const IDENT = "[A-Za-z_$][\\w$]*";
+/** `import { a, b as c }` / `export { a } from` / `import X from` — the bound names per specifier. */
+const NAMED_IMPORT = new RegExp(`\\b(?:import|export)\\s+(?:type\\s+)?(?:(${IDENT})\\s*,\\s*)?\\{([^}]*)\\}\\s*from\\s*["']([^"']+)["']` +
+    `|\\bimport\\s+(?:type\\s+)?(${IDENT})\\s+from\\s*["']([^"']+)["']`, "g");
+/**
+ * The names a module imports from each specifier, textually (#10173): the
+ * members of a `{ … }` list (an `a as b` member names `a`, a `type a` member
+ * `a`) and `default` for a default import. A namespace import (`* as x`) and
+ * a side-effect import name nothing.
+ */
+export function namedImportsOf(text) {
+    const out = [];
+    for (const m of text.matchAll(NAMED_IMPORT)) {
+        if (m[3] !== undefined) {
+            const names = (m[2] ?? "")
+                .split(",")
+                .map((member) => member.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim())
+                .filter((name) => new RegExp(`^${IDENT}$`).test(name));
+            if (m[1] !== undefined)
+                names.push("default");
+            out.push({ specifier: m[3], names });
+        }
+        else if (m[5] !== undefined) {
+            out.push({ specifier: m[5], names: ["default"] });
+        }
+    }
+    return out;
+}
+/**
+ * Whether module `text` exports `name`, textually. Fails toward `true` — an
+ * `export *`, or a destructuring export, could export anything — so a caller
+ * that holds a file back on `false` never holds one that does export it.
+ */
+export function exportsName(text, name) {
+    if (/\bexport\s*\*/.test(text))
+        return true;
+    if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(text))
+        return true;
+    if (name === "default" && /\bexport\s+default\b/.test(text))
+        return true;
+    const declared = new RegExp(`\\bexport\\s+(?:declare\\s+)?(?:async\\s+)?(?:abstract\\s+)?` +
+        `(?:const\\s+enum|const|let|var|function\\s*\\*?|class|type|interface|enum|namespace)\\s*${name.replace(/\$/g, "\\$")}\\b`);
+    if (declared.test(text))
+        return true;
+    for (const m of text.matchAll(/\bexport\s*(?:type\s*)?\{([^}]*)\}/g)) {
+        for (const member of (m[1] ?? "").split(",")) {
+            const parts = member.trim().replace(/^type\s+/, "").split(/\s+as\s+/);
+            if ((parts[1] ?? parts[0])?.trim() === name)
+                return true;
+        }
+    }
+    return false;
+}

package/dist/template-record.d.ts

@@ -49,14 +49,23 @@ export interface TemplateRecord {
 export declare class TemplateRecordError extends Error {
     constructor(message: string);
 }
+export interface ParseTemplateRecordOptions {
+    /**
+     * Called with each traversal-safe `files` key that is not a recordable path
+     * — a path a later create-ailk stopped recording, such as a generated file
+     * (#10173) — instead of refusing the record. The row is left out of the
+     * result. An unsafe key still refuses.
+     */
+    onUnrecordable?: (key: string) => void;
+}
 /**
  * Parse `.ailk-template-files.json` text, refusing — naming the field — on:
  * JSON that does not parse; `schema !== 1`; an unknown top-level key; an
- * empty `projectName`; a `files` key that is not a recordable path; a
- * `sha256` that is not 64 lowercase hex; a `version` that is not a semver
- * string (#8522 D1).
+ * empty `projectName`; a `files` key that is not a recordable path (unless
+ * `onUnrecordable` takes it); a `sha256` that is not 64 lowercase hex; a
+ * `version` that is not a semver string (#8522 D1).
  */
-export declare function parseTemplateRecord(text: string): TemplateRecord;
+export declare function parseTemplateRecord(text: string, opts?: ParseTemplateRecordOptions): TemplateRecord;
 /** `record` as `scaffold()` and `update` write it: sorted keys, trailing newline. */
 export declare function serializeTemplateRecord(record: TemplateRecord): string;
 export interface PlanTemplateRecordOptions {

package/dist/template-record.js

@@ -128,11 +128,11 @@ function isSafeRecordKey(key) {
 /**
  * Parse `.ailk-template-files.json` text, refusing — naming the field — on:
  * JSON that does not parse; `schema !== 1`; an unknown top-level key; an
- * empty `projectName`; a `files` key that is not a recordable path; a
- * `sha256` that is not 64 lowercase hex; a `version` that is not a semver
- * string (#8522 D1).
+ * empty `projectName`; a `files` key that is not a recordable path (unless
+ * `onUnrecordable` takes it); a `sha256` that is not 64 lowercase hex; a
+ * `version` that is not a semver string (#8522 D1).
  */
-export function parseTemplateRecord(text) {
+export function parseTemplateRecord(text, opts = {}) {
     let doc;
     try {
         doc = JSON.parse(text);
@@ -167,6 +167,10 @@ export function parseTemplateRecord(text) {
             throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has an unsafe key "${key}"`);
         }
         if (!isRecordable(key)) {
+            if (opts.onUnrecordable !== undefined) {
+                opts.onUnrecordable(key);
+                continue;
+            }
             throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has a key "${key}" that is not a recordable path`);
         }
         if (typeof value !== "object" || value === null) {

package/dist/update.d.ts

@@ -40,11 +40,24 @@ export interface UpdateResult {
         path: string;
         reason: string;
     }>;
-    /** Per file left under review or skipped, the template tests importing it that stay at the site's version (#8704). */
+    /**
+     * Per file left under review or skipped — or a relative import the written
+     * code names that the site will not have (`missing`) — the template tests
+     * (#8704) and the other template files (`importers`, #10173) held with it
+     * — the files that import it, or, when it is a file staying at the site's
+     * version, the written files it imports — which keep the site's version so
+     * the tree never imports what it lacks.
+     */
     heldBack: Array<{
         file: string;
         tests: string[];
+        importers?: string[];
+        missing?: true;
     }>;
+    /** The `project.yaml` `env_contract` rows added for env vars the written files read (#10172). */
+    envRowsAdded?: string[];
+    /** Record rows dropped because the path is no longer recordable (#10173). */
+    droppedRows?: string[];
     /** The mdx-body pages under `content/` given a `# ` heading this run (#7495). */
     headingsAdded: string[];
     backfilled?: {
@@ -52,6 +65,23 @@ export interface UpdateResult {
         files: number;
     };
 }
+/**
+ * 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 declare function mergeMessagesAdditively(ours: string, theirs: string): {
+    status: "merged";
+    text: string;
+    added: number;
+} | {
+    status: "conflict";
+    keys: string[];
+} | {
+    status: "invalid";
+    reason: string;
+};
 export declare function updateSite(opts: UpdateSiteOptions): Promise<UpdateResult>;
 /** The printed report (D9): one section per non-empty list, in order. */
 export declare function formatUpdateReport(result: UpdateResult): string;
@@ -59,6 +89,6 @@ export interface UpdateArgs {
     target: string | undefined;
     help: boolean;
 }
-export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\". Every template test that imports a file\nleft under \"Needs review\" or \"Skipped\" (by a relative import) is held at the\nsite's version with it, its record entry is not advanced, and it is listed\nunder \"Held back with <file>\" \u2014 reconcile the file, then run update again to\nbring its tests forward. Every other file in the run still updates.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
+export declare const UPDATE_HELP = "create-ailk update \u2014 bring template fixes into a site's copied app code.\n\nUsage:\n  create-ailk update [<target-dir>]\n\nArguments:\n  <target-dir>             The existing site. Defaults to the current dir.\n\nOptions:\n  --help, -h               Print this message.\n\nReads .ailk-template-files.json (written beside .ailk-site-manifest.json by\nevery template scaffold) to tell an untouched copy from an edit. An\nuntouched apps/web, apps/api or apps/mcp file, or a root tools/jest file the\napp jest configs require, whose template copy changed is overwritten. An\nedited file whose template copy also changed is three-way merged with\n`git` (git must be on PATH); a conflict leaves the file alone and is\nlisted under \"Needs review\"; an apps/web/messages catalog instead gains the\ntemplate's new keys and keeps every value it has, and is reviewed only when a\nkey is an object on one side and a value on the other. Every template file,\ntest or not, that imports a file left under \"Needs review\" or \"Skipped\" (by a\nrelative or @/ import, transitively) is held at the site's version with it,\nits record entry is not advanced, and it is listed under \"Held back with\n<file>\" \u2014 reconcile the file, then run update again to bring it forward. A\nwritten file whose import names a file the site will not have is held the\nsame way, under \"Held back with <file> (not in this site)\". Every other file\nin the run still updates. When project.yaml has an env_contract block, each\nenv var the written files read that has no row gains one; no row is edited.\nA record row at a path create-ailk no longer records is dropped and listed.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. A site scaffolded before\n@working-theory/mcp-server has its copied apps/mcp moved to the boot set:\nthe server and each module's paid MCP pack join apps/mcp/package.json, the\ncopied server files go, and apps/mcp/src/lib/paid-tools.generated.ts is\nrewritten on every run. A site scaffolded before @working-theory/api has its\ncopied apps/api moved to the boot file: the app becomes @working-theory/app-api,\nthe package and the six @working-theory/api-<module> packages join\napps/api/package.json, its bins and build:vercel delegate to the package, and\nthe copied server files go. Run `pnpm install` after either move, since the\napp's package.json gained dependencies. Each mdx-body page in content/ with no\n'# ' heading gets its title and description written into its body as its\nheading and intro, listed under \"Page heading added\"; a page with one heading\nis left as it is, and one with several, or one whose frontmatter it cannot\nread, is listed under \"Needs review\". Commit before running, and review the\ndiff after.\n";
 /** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
 export declare function parseUpdateArgs(argv: string[]): UpdateArgs;

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`
@@ -35,13 +41,16 @@
  * 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 { 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";
@@ -170,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:
@@ -177,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 === "..")
@@ -196,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);
@@ -210,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";
@@ -789,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);
@@ -1081,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,
@@ -1151,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.
@@ -1216,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 }));
     }
@@ -1262,6 +1526,35 @@ 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`
@@ -1286,6 +1579,8 @@ export async function updateSite(opts) {
         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. */
@@ -1312,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}):`);
@@ -1328,7 +1632,9 @@ export function formatUpdateReport(result) {
         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`;
     }
@@ -1359,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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.28.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",

package/templates/apps/web/app/[locale]/services/__tests__/service-detail-sections.test.tsx

@@ -25,6 +25,7 @@ jest.mock("@working-theory/page-renderer", () => ({
   getMdxSource: jest.fn(),
 }));
 
+// eslint-disable-next-line no-restricted-syntax -- #507: the route passes no `listSlugs`, so `listDetailPages` would list the real content tree; the category's child list is this test's fixture.
 jest.mock("../../../../lib/route-family", () => ({
   __esModule: true,
   listDetailPages: (...args: unknown[]) => mockListDetailPages(...args),

package/templates/apps/web/app/[locale]/templates/__tests__/page.test.tsx

@@ -222,6 +222,7 @@ describe("TemplatesPage — the generated card grid (#10051 AC-4)", () => {
 
   it("emits an ItemList with as many elements as cards", async () => {
     const sections = await renderedSections(["a", "b", "c"]);
+    // eslint-disable-next-line no-restricted-syntax -- the builder returns a loose JSON-LD node; this test reads one nested key of it
     const jsonLd = buildTemplatesList({
       type: "TemplatesList",
       slug: "templates",

package/templates/apps/web/lib/__tests__/hub-children.fixtures.ts

@@ -162,6 +162,7 @@ export function describeHub(
         loaders(listType, childType, children, [HERO, CLOSING]),
       );
       const sections = await input.getPageSections({});
+      // eslint-disable-next-line no-restricted-syntax -- buildJsonLd returns a loose JSON-LD node; this case reads one nested key of it
       const jsonLd = buildJsonLd({
         type: listType,
         slug: route,

package/templates/tools/declared-env.ts

@@ -1025,6 +1025,12 @@ export interface PlanEnvRowsOptions {
    * with no reader and so no `scope`; a platform or refused name is skipped.
    */
   declare?: readonly string[];
+  /**
+   * When set, only reads in these site-relative files get a row (#10173):
+   * `update` declares what the files it wrote read, never a name only the
+   * site's own code reads.
+   */
+  onlyFiles?: ReadonlySet<string>;
 }
 
 /** The header the writer puts above a block it creates. */
@@ -1066,6 +1072,7 @@ export function planEnvRows(
   const refused = new Set(opts.topology === "spoke" ? SPOKE_REFUSED_ENV : []);
   const files = new Map<string, string[]>();
   for (const read of collectSiteReads(root).reads) {
+    if (opts.onlyFiles !== undefined && !opts.onlyFiles.has(read.file)) continue;
     if (isPlatformEnvName(read.name) || refused.has(read.name)) continue;
     if (declared.has(read.name)) continue;
     const list = files.get(read.name) ?? [];

package/versions.json

@@ -38,7 +38,7 @@
   "@working-theory/ui": "0.50.0",
   "@working-theory/validation": "0.50.0",
   "@working-theory/web-i18n": "0.50.0",
-  "@working-theory/admin": "0.7.0",
+  "@working-theory/admin": "0.7.1",
   "@working-theory/api-commerce": "0.1.4",
   "@working-theory/api-content-write": "0.1.4",
   "@working-theory/api-hub": "0.3.1",