create-ailk 0.20.0 → 0.21.0

package/dist/programmatic.js

@@ -25,7 +25,7 @@ import { CATALOG_TARGET_PATH, writeComponentCatalog, } from "./component-catalog
 import { buildScaffoldMarkers, copyTemplate } from "./copy.js";
 import { deriveArchitecture } from "./derive-architecture.js";
 import { compileDesignFonts, compileDesignTheme } from "./design-compile.js";
-import { HOME_PAGE_PATH, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, } from "./design-home.js";
+import { DESIGN_SEED_PAGES, designHomeSeeds, planDesignHome, shapeHomePath, shippedHomeSeeds, siteIdentityName, } from "./design-home.js";
 import { applyDesignPresets, readSectionLookCatalog, shippedPageTypes, validateDesignPresets, } from "./design-presets.js";
 import { resolveDesign, spliceThemeBlock, } from "./design-scaffold.js";
 import { writeAuthSecretFile } from "./lib/auth-secret-file.js";
@@ -330,6 +330,10 @@ export async function scaffold(opts) {
     const designSeeds = resolvedDesign !== undefined
         ? designHomeSeeds(resolvedDesign, { designsDir: DESIGNS_DIR, catalog })
         : [];
+    // #8661 D11 — and its contact seeds, read and validated the same way.
+    const designContactSeeds = resolvedDesign !== undefined
+        ? designHomeSeeds(resolvedDesign, { designsDir: DESIGNS_DIR, catalog, page: "contact" })
+        : [];
     // #6813 D7 — the resolved design only when the CALLER chose one (`opts.design`);
     // a template's own declared design is never gated (#6778 option (c)).
     const chosenDesign = opts.design !== undefined ? resolvedDesign : undefined;
@@ -719,21 +723,35 @@ export async function scaffold(opts) {
         // every layer has landed, before the presets dress it. A home that is not
         // the shape's placeholder is never written; `--design standard` (no
         // seeds) leaves the shape's home byte-identical. The one
-        // `planDesignHome` call site in scaffold().
-        const homePath = join(result.targetDir, ...HOME_PAGE_PATH.split("/"));
-        let homeSeeded = false;
+        // `planDesignHome` call site in scaffold(). #8661 D11 — the contact page
+        // is planned right after the home, its heading named from the scaffold's
+        // `siteIdentity.name`.
+        const seededPages = [];
         if (template !== undefined) {
-            const homePlan = planDesignHome({
-                current: existsSync(homePath) ? readFileSync(homePath, "utf8") : undefined,
-                shape: template.shape,
-                target: designSeeds.find((seed) => seed.shape === template.shape),
-                shapeHome: readFileSync(shapeHomePath(template.shape, { siteTemplatesDir: SITE_TEMPLATES_DIR, templatesDir: TEMPLATES_DIR }), "utf8"),
-                shippedSeeds: shippedHomeSeeds({ designsDir: DESIGNS_DIR, catalog }),
-                catalog: catalog(),
-            });
-            if (homePlan.outcome === "seeded" && homePlan.text !== undefined) {
-                writeFileSync(homePath, homePlan.text);
-                homeSeeded = true;
+            const siteName = siteIdentityName(existsSync(siteMdxPath) ? readFileSync(siteMdxPath, "utf8") : undefined);
+            for (const [page, pageSeeds] of [
+                ["home", designSeeds],
+                ["contact", designContactSeeds],
+            ]) {
+                const pagePath = join(result.targetDir, ...DESIGN_SEED_PAGES[page].path.split("/"));
+                const plan = planDesignHome({
+                    page,
+                    siteName,
+                    current: existsSync(pagePath) ? readFileSync(pagePath, "utf8") : undefined,
+                    shape: template.shape,
+                    target: pageSeeds.find((seed) => seed.shape === template.shape),
+                    shapeHome: readFileSync(shapeHomePath(template.shape, {
+                        siteTemplatesDir: SITE_TEMPLATES_DIR,
+                        templatesDir: TEMPLATES_DIR,
+                        page,
+                    }), "utf8"),
+                    shippedSeeds: shippedHomeSeeds({ designsDir: DESIGNS_DIR, catalog, page }),
+                    catalog: catalog(),
+                });
+                if (plan.outcome === "seeded" && plan.text !== undefined) {
+                    writeFileSync(pagePath, plan.text);
+                    seededPages.push(page);
+                }
             }
         }
         // #6816 D6 step 10b — the design's section presets, written onto the
@@ -761,12 +779,18 @@ export async function scaffold(opts) {
             }
         }
         // #7743 D6 — the manifest's `/` row records the seeded home's sections,
-        // as the presets left them.
+        // as the presets left them. #8661 — and the `/contact` row the seeded
+        // contact page's.
         const rosterPath = join(result.targetDir, SITE_ROSTER_PATH);
-        if (homeSeeded && existsSync(rosterPath)) {
-            const nextManifest = planHomeRecord(readFileSync(rosterPath, "utf8"), readFileSync(homePath, "utf8"), catalog());
-            if (nextManifest !== undefined)
-                writeFileSync(rosterPath, nextManifest);
+        if (seededPages.length > 0 && existsSync(rosterPath)) {
+            const recorded = readFileSync(rosterPath, "utf8");
+            let manifestText = recorded;
+            for (const page of seededPages) {
+                const pagePath = join(result.targetDir, ...DESIGN_SEED_PAGES[page].path.split("/"));
+                manifestText = planHomeRecord(manifestText, readFileSync(pagePath, "utf8"), catalog(), page) ?? manifestText;
+            }
+            if (manifestText !== recorded)
+                writeFileSync(rosterPath, manifestText);
         }
     }
     // #7838 D8 — a commerce spoke's own checkout: two routes, its config and

package/dist/site-roster.d.ts

@@ -1,4 +1,5 @@
 import type { CompiledDesignTheme } from "./design-compile.js";
+import { type DesignSeedPage } from "./design-home.js";
 import { type SectionLookCatalog } from "./design-presets.js";
 import { type PageRosterRow } from "./module-architecture.js";
 import type { ModuleName } from "./parse-args.js";
@@ -102,9 +103,10 @@ export declare const MANIFEST_OPTION_KEYS: readonly ["itemStyle", "actionsPositi
  * `MANIFEST_OPTION_KEYS` values, as the generator writes them. `undefined`
  * when the record already says so, or the manifest has no `/` row with a
  * `sections` key. The value is spliced in place at its own depth; no other
- * byte moves.
+ * byte moves. `page: "contact"` records the `/contact` row from the contact
+ * page instead (#8661 D11).
  */
-export declare function planHomeRecord(manifestText: string, homeText: string, catalog: SectionLookCatalog): string | undefined;
+export declare function planHomeRecord(manifestText: string, homeText: string, catalog: SectionLookCatalog, page?: DesignSeedPage): string | undefined;
 /**
  * The generator's row for each of a module's `pageContributions`, in
  * declaration order — read from the committed manifest of the first

package/dist/site-roster.js

@@ -28,7 +28,7 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader, } from "./add-module-core.js";
-import { HOME_PAGE_PATH } from "./design-home.js";
+import { DESIGN_SEED_PAGES } from "./design-home.js";
 import { locatePageSections } from "./design-presets.js";
 import { diffTwoStrings } from "./lib/extract-module-bundle.js";
 import { MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
@@ -296,14 +296,16 @@ function scalarValue(raw) {
  * `MANIFEST_OPTION_KEYS` values, as the generator writes them. `undefined`
  * when the record already says so, or the manifest has no `/` row with a
  * `sections` key. The value is spliced in place at its own depth; no other
- * byte moves.
+ * byte moves. `page: "contact"` records the `/contact` row from the contact
+ * page instead (#8661 D11).
  */
-export function planHomeRecord(manifestText, homeText, catalog) {
+export function planHomeRecord(manifestText, homeText, catalog, page = "home") {
+    const { route, path } = DESIGN_SEED_PAGES[page];
     const file = parseRosterFile(manifestText, SITE_ROSTER_PATH);
-    const row = file.rows.find((r) => r.value["route"] === "/");
+    const row = file.rows.find((r) => r.value["route"] === route);
     if (row === undefined || !("sections" in row.value))
         return undefined;
-    const sections = (locatePageSections(homeText, HOME_PAGE_PATH) ?? []).map((section) => {
+    const sections = (locatePageSections(homeText, path) ?? []).map((section) => {
         const options = {};
         for (const key of MANIFEST_OPTION_KEYS) {
             const entry = section.entries.find((e) => e.key === key);

package/dist/starter-grid.js

@@ -117,6 +117,10 @@ const TEMPLATE_BASE_ROSTER = [
     { route: "/sign-up" },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
     {
         route: "/purchase-policy",
         content: ["content/en/PurchasePolicyPage/purchase-policy.mdx"],
@@ -235,6 +239,10 @@ const ORGANIZATION_SERVICE_ROWS = [
     { route: "/sign-up" },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
     {
         route: "/purchase-policy",
         content: ["content/en/PurchasePolicyPage/purchase-policy.mdx"],
@@ -267,6 +275,10 @@ const LOCAL_BUSINESS_SERVICE_ROWS = [
     },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
 ];
 /**
  * `person-service`'s own rows (#6758 D1, D3), derived from
@@ -302,6 +314,10 @@ const PERSON_SERVICE_ROWS = [
     },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
 ];
 /**
  * Each buildable shape's standard roster (#6753 D3) — the rows an alias starts

package/dist/surfaces.js

@@ -331,6 +331,13 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/whitepapers`],
         content: ["content/<locale>/Whitepaper"],
     },
+    {
+        // #8661 D10 — the working agreement, module-less like `privacy` and
+        // `terms`: every shape roster names it right after /terms.
+        id: "working-agreement",
+        routes: [`${ROUTE_ROOT}/working-agreement`],
+        content: ["content/<locale>/WorkingAgreementPage"],
+    },
 ];
 /** The recognized `--surfaces` vocabulary, sorted. */
 export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
@@ -552,6 +559,7 @@ export function isUnservedSurfaceContent(path, enabled) {
  */
 export const ROUTE_SINCE = {
     about: "0.0.0",
+    "about/[slug]": "0.42.0",
     "blog/[[...slug]]": "0.0.0",
     careers: "0.0.0",
     "careers/[slug]": "0.0.0",
@@ -638,6 +646,9 @@ export const ROUTE_SINCE = {
     "vs/[slug]": "0.28.0",
     whitepapers: "0.0.0",
     "whitepapers/[slug]": "0.0.0",
+    // #8661 D10 — the working-agreement page. Genuinely new, so it attaches at
+    // the fixed group's next release line, the same rule #7430 applied.
+    "working-agreement": "0.42.0",
     // #5014 — the (authed) route GROUP: layout.tsx + sign-in-gate.tsx sit
     // directly under "(authed)" (a Next.js route group — its parens are not a
     // URL segment); account/ and waitlist/ are its two syncable sub-trees.

package/dist/sync-routes.d.ts

@@ -1,4 +1,6 @@
 import type { WorkspaceVersionMap } from "./substitute.js";
+/** The site test that fails a route neither rendered through `renderPage` nor in its `NO_STRUCTURED_DATA_ROUTES` (#8704). */
+export declare const STRUCTURED_DATA_TEST_PATH = "apps/web/lib/__tests__/structured-data.test.tsx";
 export interface SyncRoutesOptions {
     /**
      * The already-scaffolded repo (absolute or relative). Must exist, be a
@@ -65,7 +67,32 @@ export interface SyncRoutesResult {
     missingMessageNamespaces: string[];
     /** Gateable surface ids the target does not carry, sorted. */
     skippedSurfaces: string[];
+    /**
+     * When `apply` added a route the template exempts in its structured-data
+     * test and the site's copy of that test is site-edited (its bytes differ
+     * from the recorded hash), each template `NO_STRUCTURED_DATA_ROUTES` entry
+     * the site's test lacks, verbatim, with the added routes it covers (#8704).
+     * Sorted by entry; empty otherwise. The site's test is never written.
+     */
+    structuredDataEntries: Array<{
+        routes: string[];
+        entry: string;
+    }>;
+}
+/** One `NO_STRUCTURED_DATA_ROUTES` element: its source text, dedented, and the routes it exempts. */
+interface StructuredDataExemption {
+    route: string;
+    subtree: boolean;
+    text: string;
 }
+/**
+ * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
+ * brace scan that skips string literals and comments. Empty when the
+ * file declares no such array. It assumes what the template's array holds:
+ * object literals of string, boolean and identifier-array values — no regex
+ * literal or `${…}` interpolation.
+ */
+export declare function parseStructuredDataExemptions(source: string): StructuredDataExemption[];
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -99,3 +126,4 @@ export declare const SYNC_ROUTES_HELP = "create-ailk sync-routes \u2014 copy tem
  * like `parseCliArgs`; at most one positional.
  */
 export declare function parseSyncRoutesArgs(argv: string[]): SyncRoutesArgs;
+export {};

package/dist/sync-routes.js

@@ -21,7 +21,10 @@
  *     route root is copied once into a scratch dir and compared from there.
  *   - Never overwrite, never delete. A route dir the site has changed is
  *     reported as modified and left alone; `--apply` only creates directories
- *     that do not exist, so a second run is a no-op.
+ *     that do not exist, so a second run is a no-op. When the site has edited
+ *     its structured-data test, a route `--apply` adds that the template
+ *     exempts there is reported with the exact `NO_STRUCTURED_DATA_ROUTES`
+ *     entry to add — the test itself is never written (#8704).
  *
  * Pure module: no `import.meta.url`, so jest can import it directly. The
  * package's own `templates/` dir is supplied by programmatic.ts.
@@ -35,9 +38,12 @@ import { appendEnvRows } from "./lib/declared-env.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
+import { TEMPLATE_RECORD_PATH, parseTemplateRecord, sha256Hex } from "./template-record.js";
 import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
+/** The site test that fails a route neither rendered through `renderPage` nor in its `NO_STRUCTURED_DATA_ROUTES` (#8704). */
+export const STRUCTURED_DATA_TEST_PATH = "apps/web/lib/__tests__/structured-data.test.tsx";
 /**
  * `<surface id>/<entry name>` pairs that live directly under a GATEABLE
  * surface's top-level directory but belong to a DIFFERENT module (#5366).
@@ -50,6 +56,114 @@ const ROUTE_ROOT = "apps/web/app/[locale]";
 const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
     "projects/apply",
 ]);
+/**
+ * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
+ * brace scan that skips string literals and comments. Empty when the
+ * file declares no such array. It assumes what the template's array holds:
+ * object literals of string, boolean and identifier-array values — no regex
+ * literal or `${…}` interpolation.
+ */
+export function parseStructuredDataExemptions(source) {
+    const decl = source.indexOf("const NO_STRUCTURED_DATA_ROUTES");
+    if (decl === -1)
+        return [];
+    const open = /=\s*\[/.exec(source.slice(decl));
+    if (open === null)
+        return [];
+    const out = [];
+    let depth = 0;
+    let start = -1;
+    for (let i = decl + open.index + open[0].length; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === '"' || ch === "'" || ch === "`") {
+            for (i++; i < source.length && source[i] !== ch; i++) {
+                if (source[i] === "\\")
+                    i++;
+            }
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "/") {
+            const eol = source.indexOf("\n", i);
+            i = eol === -1 ? source.length : eol;
+            continue;
+        }
+        if (ch === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            i = end === -1 ? source.length : end + 1;
+            continue;
+        }
+        if (ch === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0 && start !== -1) {
+                const raw = source.slice(start, i + 1) + (source[i + 1] === "," ? "," : "");
+                const route = /\broute:\s*["']([^"']+)["']/.exec(raw)?.[1];
+                if (route !== undefined) {
+                    const indent = /[ \t]*$/.exec(source.slice(source.lastIndexOf("\n", start) + 1, start))?.[0] ?? "";
+                    const text = raw
+                        .split("\n")
+                        .map((line) => (line.startsWith(indent) ? line.slice(indent.length) : line))
+                        .join("\n");
+                    out.push({ route, subtree: /\bsubtree:\s*true\b/.test(raw), text });
+                }
+                start = -1;
+            }
+        }
+        else if (ch === "]" && depth === 0) {
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * The first exemption covering `route` by the structured-data test's route
+ * rule (`route` itself, or under a `subtree` entry). An entry's `requires`
+ * strings are not checked: they key only the generated spoke checkout pages,
+ * which no template route dir — so no `--apply` — ever adds.
+ */
+function exemptionFor(exemptions, route) {
+    return exemptions.find((e) => route === e.route || (e.subtree && route.startsWith(`${e.route}/`)));
+}
+/**
+ * The template `NO_STRUCTURED_DATA_ROUTES` entries the site's structured-data
+ * test must gain for `added` routes (#8704). Empty unless that test is
+ * recorded and site-edited — an untouched copy is `create-ailk update`'s to
+ * bring forward, and an unrecorded one cannot be told apart from an edit.
+ */
+function structuredDataEntriesFor(targetAbs, templatesDir, added) {
+    const sitePath = join(targetAbs, STRUCTURED_DATA_TEST_PATH);
+    const templatePath = join(templatesDir, STRUCTURED_DATA_TEST_PATH);
+    const recordPath = join(targetAbs, TEMPLATE_RECORD_PATH);
+    if (added.length === 0 || !existsSync(sitePath) || !existsSync(templatePath) || !existsSync(recordPath)) {
+        return [];
+    }
+    let recordedHash;
+    try {
+        recordedHash = parseTemplateRecord(readFileSync(recordPath, "utf8")).files[STRUCTURED_DATA_TEST_PATH]?.sha256;
+    }
+    catch {
+        return [];
+    }
+    const siteBytes = readFileSync(sitePath);
+    if (recordedHash === undefined || sha256Hex(siteBytes) === recordedHash)
+        return [];
+    const templateExemptions = parseStructuredDataExemptions(readFileSync(templatePath, "utf8"));
+    const siteExemptions = parseStructuredDataExemptions(siteBytes.toString("utf8"));
+    const byEntry = new Map();
+    for (const route of [...added].sort()) {
+        const needed = exemptionFor(templateExemptions, route);
+        if (needed === undefined || exemptionFor(siteExemptions, route) !== undefined)
+            continue;
+        byEntry.set(needed.text, [...(byEntry.get(needed.text) ?? []), route]);
+    }
+    return [...byEntry.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([entry, routes]) => ({ routes, entry }));
+}
 /**
  * The template's route directories, ROUTE_ROOT-relative and sorted.
  *
@@ -276,6 +390,7 @@ export function syncRoutes(opts) {
         appliedDependencies,
         missingMessageNamespaces,
         skippedSurfaces,
+        structuredDataEntries: structuredDataEntriesFor(targetAbs, opts.templatesDir, applied),
     };
 }
 /**
@@ -355,6 +470,13 @@ export function formatSyncRoutesReport(result, apply) {
         lines.push(`[create-ailk] Also required — message namespace(s) not found in apps/web/messages/en.json (add manually, not auto-merged):`);
         lines.push(...result.missingMessageNamespaces.map((ns) => `  ${ns}`));
     }
+    if (result.structuredDataEntries.length > 0) {
+        lines.push(`[create-ailk] Also required — ${STRUCTURED_DATA_TEST_PATH} is edited here, so add these NO_STRUCTURED_DATA_ROUTES entries to it by hand (not written):`);
+        for (const { routes, entry } of result.structuredDataEntries) {
+            lines.push(`  for ${routes.join(", ")}:`);
+            lines.push(...entry.split("\n").map((line) => `    ${line}`));
+        }
+    }
     if (result.missing.length > 0 && !apply) {
         lines.push("Run `create-ailk sync-routes <target> --apply` to copy the missing routes.");
     }

package/dist/update.d.ts

@@ -31,6 +31,11 @@ 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). */
+    heldBack: Array<{
+        file: string;
+        tests: string[];
+    }>;
     backfilled?: {
         version: string;
         files: number;
@@ -43,6 +48,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 whose template copy changed is\noverwritten. An edited file whose template copy also changed is three-way\nmerged with `git` (git must be on PATH); a conflict leaves the file alone\nand is listed under \"Needs review\" \u2014 nothing else in the run is held back.\nA site with no record gets one on its first run, from the version its\n.ailk-site-manifest.json already records. Commit before running, and review\nthe diff 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 whose template copy changed is\noverwritten. An edited file whose template copy also changed is three-way\nmerged with `git` (git must be on PATH); a conflict leaves the file alone\nand is listed 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. Commit before running, and review\nthe diff 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

@@ -9,10 +9,12 @@
  * 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". A
- * site with no record gets one backfilled from `.ailk-site-manifest.json`'s
- * `patternVersion` on its first run, then updates normally. Every refusal
- * throws before the first write.
+ * 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
+ * `.ailk-site-manifest.json`'s `patternVersion` on its first run, then
+ * updates normally. Every refusal throws before the first write.
  *
  * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
  * `adopt.ts` / `add-route.ts` split.
@@ -132,6 +134,50 @@ function containsKnownPath(prefix, knownPaths) {
     }
     return false;
 }
+/** A template test file: a `*.test.*` / `*.spec.*` module, or anything under `__tests__/`. */
+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 RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+/**
+ * The record-style paths a relative specifier in `fromPath` can resolve to:
+ * the path as written, with each source extension, a `.js`-family suffix
+ * 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("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            parts.pop();
+        else
+            parts.push(segment);
+    }
+    const target = parts.join("/");
+    const out = [target, ...RESOLVE_EXTENSIONS.map((ext) => `${target}${ext}`)];
+    const jsSuffix = /\.([cm]?)jsx?$/.exec(target);
+    if (jsSuffix !== null) {
+        const stem = target.slice(0, -jsSuffix[0].length);
+        out.push(`${stem}.${jsSuffix[1]}ts`, `${stem}.tsx`);
+    }
+    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) {
+    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;
+        for (const candidate of relativeImportCandidates(fromPath, specifier)) {
+            if (held.has(candidate))
+                out.add(candidate);
+        }
+    }
+    return [...out];
+}
 export async function updateSite(opts) {
     const targetDir = resolve(opts.targetDir);
     const version = opts.version;
@@ -391,37 +437,85 @@ export async function updateSite(opts) {
         nextFiles[path] = { sha256: sha256Hex(newBytes), version };
         added.push(path);
     }
+    // ── Hold back the template tests of every file left alone (#8704) ────
+    // A test this run would move forward (update, merge, add, remove, or
+    // advance as current) that imports a file under review or skipped stays
+    // exactly as the site has it, and its row keeps its recorded version — so
+    // the tests on disk always match the code they exercise. The imports are
+    // read from both the site's copy and the running template's: either one
+    // 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.
+    const heldFiles = new Set([...review, ...skipped].map((row) => row.path));
+    const heldBackByFile = new Map();
+    const heldTests = new Set();
+    const moving = [...updated, ...merged, ...added, ...removed, ...current]
+        .filter((path) => TEST_FILE.test(path))
+        .sort();
+    for (let grew = heldFiles.size > 0; grew;) {
+        grew = false;
+        for (const path of moving) {
+            if (heldTests.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)
+                continue;
+            heldTests.add(path);
+            heldFiles.add(path);
+            grew = true;
+            for (const file of imported) {
+                heldBackByFile.set(file, [...(heldBackByFile.get(file) ?? []), path]);
+            }
+        }
+    }
+    for (const path of heldTests) {
+        const recorded = record.files[path];
+        if (recorded !== undefined)
+            nextFiles[path] = recorded;
+        else
+            delete nextFiles[path];
+    }
+    const notHeld = (path) => !heldTests.has(path);
+    const heldBack = [...heldBackByFile.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([file, tests]) => ({ file, tests }));
     // ── Apply: writes and removals, then the record (D4 Order) ───────────
-    for (const write of writes) {
+    for (const write of writes.filter((w) => notHeld(w.path))) {
         const abs = join(targetDir, ...write.path.split("/"));
         mkdirSync(dirname(abs), { recursive: true });
         writeFileSync(abs, write.bytes);
     }
-    for (const path of deletes) {
+    for (const path of deletes.filter(notHeld)) {
         rmSync(join(targetDir, ...path.split("/")));
     }
     const backfilled = backfillPatternVersion !== undefined
         ? { version: backfillPatternVersion, files: Object.keys(record.files).length }
         : undefined;
-    const recordChanged = backfilled !== undefined ||
-        updated.length > 0 ||
-        merged.length > 0 ||
-        added.length > 0 ||
-        removed.length > 0 ||
-        current.length > 0;
+    const moved = {
+        updated: updated.filter(notHeld),
+        merged: merged.filter(notHeld),
+        added: added.filter(notHeld),
+        removed: removed.filter(notHeld),
+        current: current.filter(notHeld),
+    };
+    const recordChanged = backfilled !== undefined || Object.values(moved).some((paths) => paths.length > 0);
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
     return {
         targetDir,
         version,
-        updated,
-        merged,
-        added,
-        removed,
-        current,
+        ...moved,
         review,
         skipped,
+        heldBack,
         ...(backfilled !== undefined ? { backfilled } : {}),
     };
 }
@@ -448,6 +542,10 @@ 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}`));
+    }
     if (result.skipped.length > 0) {
         lines.push(`Skipped (${result.skipped.length}):`);
         lines.push(...result.skipped.map((row) => `  ${row.path} — ${row.reason}`));
@@ -481,7 +579,11 @@ every template scaffold) to tell an untouched copy from an edit. An
 untouched apps/web, apps/api or apps/mcp file 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" — nothing else in the run is held back.
+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.
 A site with no record gets one on its first run, from the version its
 .ailk-site-manifest.json already records. Commit before running, and review
 the diff after.