create-ailk 0.22.0 → 0.24.0

package/dist/sync-routes.js

@@ -19,26 +19,32 @@
  *   - Expected bytes are what `copyTemplate` would write. The copier's
  *     text/binary + marker rules are NOT re-implemented here: the template's
  *     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. 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).
+ *   - Never overwrite, never delete — with one named exception. 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.
+ *     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). The exception is the retired legacy spoke checkout
+ *     (#9142): on a spoke, `--apply` deletes its files that are still
+ *     byte-identical to the template record and rewrites the generated
+ *     billing action off them (`retireLegacySpokeCheckout`); an edited or
+ *     unrecorded file is reported and left alone.
  *
  * Pure module: no `import.meta.url`, so jest can import it directly. The
  * package's own `templates/` dir is supplied by programmatic.ts.
  */
-import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
-import { basename, dirname, join, resolve, sep } from "node:path";
+import { basename, dirname, join, posix, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
-import { copyTemplate } from "./copy.js";
+import { copyTemplate, renderTemplateFile } from "./copy.js";
+import { SPOKE_BILLING_ACTION_PATH } from "./derive-architecture.js";
 import { appendEnvRows } from "./lib/declared-env.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
-import { substituteMarkers } from "./substitute.js";
+import { BILLING_ACTION, BILLING_ACTION_MARKER, RETIRED_CHECKOUT_E2E_MARKER, RETIRED_CHECKOUT_E2E_WORKFLOW_PATH, RETIRED_SPOKE_CHECKOUT_PATHS, } from "./spoke-checkout.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 { TEMPLATE_RECORD_PATH, parseTemplateRecord, serializeTemplateRecord, 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]";
@@ -50,12 +56,184 @@ export const STRUCTURED_DATA_TEST_PATH = "apps/web/lib/__tests__/structured-data
  * `projects/apply` (#5048) is signal-collectors' own owned file
  * (`ListingApplicationClient.tsx`, D-48) — its module bundle restores it
  * whenever signal-collectors is selected, independent of the unrelated
- * "projects" content surface's own selection. See the doc comment on
- * `syncRoutes`'s `carried` computation.
+ * "projects" content surface's own selection. `careers/apply` and
+ * `careers/[slug]` (#8840 D13) are the same case: signal-collectors' bundle
+ * lands the Job application walks (`careers/apply/page.tsx`,
+ * `careers/[slug]/apply/**`) whenever the module is selected, so a site that
+ * turned the careers pages off must not read as carrying "careers" — a site
+ * that carries them keeps `careers/page.tsx`, which still counts. See the doc
+ * comment on `syncRoutes`'s `carried` computation.
  */
 const NESTED_FOREIGN_MODULE_ENTRIES = new Set([
     "projects/apply",
+    "careers/apply",
+    "careers/[slug]",
 ]);
+/** Extensions whose files are scanned for import specifiers (#9406 DD1). */
+const SOURCE_FILE = /\.(?:ts|tsx|js|jsx|mjs|mts)$/;
+/**
+ * Static import and re-export (`import … from`, `export … from`), side-effect
+ * (`import "…"`) and dynamic (`import("…")`) specifiers (#9406 DD1). Matched
+ * over the whole text: `[^'"]*?` spans newlines, so a multi-line
+ * `import {\n  a,\n} from "…"` is caught from its `import` line.
+ */
+const IMPORT_PATTERNS = [
+    /^\s*(?:import|export)\b[^'"]*?\bfrom\s*['"]([^'"]+)['"]/gm,
+    /^\s*import\s*['"]([^'"]+)['"]/gm,
+    /\bimport\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+/** The site-local (`./`, `../`) import specifiers of a source text, deduplicated. */
+function relativeImportSpecifiers(text) {
+    const out = new Set();
+    for (const pattern of IMPORT_PATTERNS) {
+        for (const match of text.matchAll(pattern)) {
+            const specifier = match[1];
+            if (specifier !== undefined && (specifier.startsWith("./") || specifier.startsWith("../"))) {
+                out.add(specifier);
+            }
+        }
+    }
+    return [...out];
+}
+/**
+ * The scaffold-relative files `specifier`, imported from `importer`, may name —
+ * in #9406 DD2's probe order: a `.js`/`.jsx` specifier's `.ts`/`.tsx` spelling
+ * first, then the exact path, the extension probes and the directory index.
+ * Empty when the path climbs out of the scaffold root.
+ */
+function importCandidates(importer, specifier) {
+    const base = posix.normalize(posix.join(posix.dirname(importer), specifier));
+    if (base === ".." || base.startsWith("../"))
+        return [];
+    const out = [];
+    const js = /\.(jsx?)$/.exec(base);
+    if (js !== null) {
+        const stem = base.slice(0, -js[0].length);
+        if (js[1] === "js")
+            out.push(`${stem}.ts`);
+        out.push(`${stem}.tsx`);
+    }
+    out.push(base);
+    for (const ext of [".ts", ".tsx", ".js", ".jsx", ".mjs"])
+        out.push(base + ext);
+    out.push(`${base}/index.ts`, `${base}/index.tsx`);
+    return out;
+}
+/** Whether `root`/`rel` (`/`-separated) is an existing regular file. */
+function isRegularFile(root, rel) {
+    try {
+        return statSync(join(root, ...rel.split("/"))).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The deepest route in `missingRoutes` a scaffold-relative path sits under —
+ * the route whose own copy writes it — or undefined.
+ */
+function ownerRoute(path, missingRoutes) {
+    if (!path.startsWith(`${ROUTE_ROOT}/`))
+        return undefined;
+    const rel = path.slice(ROUTE_ROOT.length + 1);
+    let owner;
+    for (const m of missingRoutes) {
+        if (rel.startsWith(`${m}/`) && (owner === undefined || m.length > owner.length))
+            owner = m;
+    }
+    return owner;
+}
+/**
+ * Resolve the site-local imports of every file `route`'s own copy writes, and
+ * transitively of every helper that brings (#9406 DD1–DD3). Each import is
+ * resolved against the site first, then the template. A file the site has
+ * ends the walk there (the site owns its closure); a file another missing
+ * route's copy brings is recorded for DD4's propagation; a file only the
+ * template has is a copy — unless the spoke drops it or its surface is not
+ * carried, which refuses the route.
+ */
+function walkRouteImports(route, ctx) {
+    const inScratch = (path) => path.startsWith(`${ROUTE_ROOT}/`) ? path.slice(ROUTE_ROOT.length + 1) : undefined;
+    const templateHas = (path) => {
+        const rel = inScratch(path);
+        return rel !== undefined
+            ? isRegularFile(ctx.scratch, rel)
+            : isRegularFile(ctx.templatesDir, path);
+    };
+    // The bytes `copyTemplate` (a route file) or `copyDependencyFile` (any
+    // other) would write for `path`.
+    const templateBytes = (path) => {
+        const rel = inScratch(path);
+        if (rel !== undefined)
+            return readFileSync(join(ctx.scratch, ...rel.split("/")));
+        return Buffer.from(renderTemplateFile(readFileSync(join(ctx.templatesDir, ...path.split("/"))), path, ctx.versions, ctx.markers));
+    };
+    const copies = new Set();
+    const differs = new Set();
+    const unresolved = [];
+    const reached = [];
+    const queue = regularFilesUnder(ctx.scratch, route)
+        .map((rel) => `${ROUTE_ROOT}/${rel}`)
+        .filter((path) => ownerRoute(path, ctx.missingRoutes) === route);
+    const visited = new Set(queue);
+    for (let from = queue.shift(); from !== undefined; from = queue.shift()) {
+        if (!SOURCE_FILE.test(from))
+            continue;
+        const importer = from;
+        for (const specifier of relativeImportSpecifiers(templateBytes(importer).toString("utf8"))) {
+            const candidates = importCandidates(importer, specifier);
+            const inSite = candidates.find((c) => isRegularFile(ctx.targetAbs, c));
+            const path = inSite ?? candidates.find(templateHas);
+            if (path === undefined) {
+                unresolved.push({ specifier, from: importer, reason: "not in the template" });
+                continue;
+            }
+            const owner = ownerRoute(path, ctx.missingRoutes);
+            if (owner !== undefined) {
+                if (owner !== route)
+                    reached.push({ path, owner, specifier, from: importer });
+                continue;
+            }
+            if (inSite !== undefined) {
+                const siteBytes = readFileSync(join(ctx.targetAbs, ...path.split("/")));
+                if (templateHas(path) && !templateBytes(path).equals(siteBytes))
+                    differs.add(path);
+                continue;
+            }
+            if (ctx.spoke !== undefined && isSpokeExcluded(path, ctx.spoke)) {
+                unresolved.push({ specifier, from: importer, reason: "the spoke does not carry it" });
+                continue;
+            }
+            const routeRel = inScratch(path);
+            const surface = routeRel === undefined ? "core" : surfaceForRouteDir(routeRel);
+            if (surface === undefined || !ctx.carried.has(surface)) {
+                unresolved.push({
+                    specifier,
+                    from: importer,
+                    reason: `its surface (${surface ?? "none"}) is not carried by this site`,
+                });
+                continue;
+            }
+            copies.add(path);
+            if (!visited.has(path)) {
+                visited.add(path);
+                queue.push(path);
+            }
+        }
+    }
+    return {
+        route,
+        copies: [...copies].sort(),
+        differs: [...differs].sort(),
+        unresolved: sortUnresolved(unresolved),
+        reached,
+    };
+}
+/** `unresolved` rows sorted by `from`, then `specifier`. */
+function sortUnresolved(rows) {
+    const key = (row) => `${row.from}\u0000${row.specifier}`;
+    return [...rows].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));
+}
 /**
  * The elements of `source`'s `NO_STRUCTURED_DATA_ROUTES` array literal, by a
  * brace scan that skips string literals and comments. Empty when the
@@ -229,6 +407,141 @@ function isModified(expectedDir, targetDir, skip = () => false) {
     }
     return false;
 }
+/** Directories a retirement never removes, even when it leaves them empty. */
+const RETIRE_STOP_DIRS = new Set([
+    "apps/web/app/api",
+    "apps/web/lib",
+    "apps/web/lib/__tests__",
+    ".github/workflows",
+]);
+/** Every regular file at or under `rel` in `targetAbs`, `/`-separated. A symlink is skipped, never followed. */
+function regularFilesUnder(targetAbs, rel) {
+    const abs = join(targetAbs, ...rel.split("/"));
+    let stat;
+    try {
+        stat = lstatSync(abs);
+    }
+    catch {
+        return [];
+    }
+    if (stat.isFile())
+        return [rel];
+    if (!stat.isDirectory())
+        return [];
+    return readdirSync(abs)
+        .sort()
+        .flatMap((name) => regularFilesUnder(targetAbs, `${rel}/${name}`));
+}
+/** The first line of a text file. */
+function firstLine(text) {
+    const eol = text.indexOf("\n");
+    return eol === -1 ? text : text.slice(0, eol);
+}
+/**
+ * Retire the legacy env-key spoke checkout from a spoke (#9142): its buy
+ * route, Stripe webhook route, `lib/checkout.ts`, their tests
+ * (`RETIRED_SPOKE_CHECKOUT_PATHS`) and the generated checkout e2e workflow.
+ *
+ * - A copied file is deleted only when the template record lists it and its
+ *   bytes still hash to the recorded copy — the rule `create-ailk update`
+ *   uses for a file the template dropped; its record row goes with it. An
+ *   edited file, or one the record does not list, is reported in `kept`.
+ * - The workflow, never recorded, is deleted only when its first line is
+ *   still create-ailk's generated marker.
+ * - The billing action (a spoke that signs in through its hub) imported
+ *   `lib/checkout.ts`; when its first line is still the generated marker and
+ *   it differs from the current render, it is rewritten to `BILLING_ACTION`.
+ *   An edited one that still imports `lib/checkout` is reported in `kept`.
+ *
+ * Without `apply` nothing is written: the lists say what `--apply` would do.
+ * Directories the deletes leave empty are removed, up to `RETIRE_STOP_DIRS`.
+ */
+export function retireLegacySpokeCheckout(targetAbs, apply) {
+    const retired = [];
+    const kept = [];
+    const rewritten = [];
+    const recordPath = join(targetAbs, TEMPLATE_RECORD_PATH);
+    let record;
+    if (existsSync(recordPath)) {
+        try {
+            record = parseTemplateRecord(readFileSync(recordPath, "utf8"));
+        }
+        catch {
+            record = undefined;
+        }
+    }
+    for (const path of RETIRED_SPOKE_CHECKOUT_PATHS.flatMap((rel) => regularFilesUnder(targetAbs, rel))) {
+        const recorded = record?.files[path]?.sha256;
+        if (recorded === undefined) {
+            kept.push({
+                path,
+                reason: record === undefined
+                    ? "no readable template record, so an edit cannot be told apart"
+                    : "not in the template record",
+            });
+        }
+        else if (sha256Hex(readFileSync(join(targetAbs, ...path.split("/")))) !== recorded) {
+            kept.push({ path, reason: "edited here" });
+        }
+        else {
+            retired.push(path);
+        }
+    }
+    const workflow = regularFilesUnder(targetAbs, RETIRED_CHECKOUT_E2E_WORKFLOW_PATH);
+    for (const path of workflow) {
+        const text = readFileSync(join(targetAbs, ...path.split("/")), "utf8");
+        if (firstLine(text) === RETIRED_CHECKOUT_E2E_MARKER)
+            retired.push(path);
+        else
+            kept.push({ path, reason: "edited here" });
+    }
+    const billingAbs = join(targetAbs, ...SPOKE_BILLING_ACTION_PATH.split("/"));
+    if (regularFilesUnder(targetAbs, SPOKE_BILLING_ACTION_PATH).length === 1) {
+        const text = readFileSync(billingAbs, "utf8");
+        if (text !== BILLING_ACTION) {
+            if (firstLine(text) === BILLING_ACTION_MARKER) {
+                rewritten.push(SPOKE_BILLING_ACTION_PATH);
+            }
+            else if (/lib\/checkout["'`]/.test(text)) {
+                kept.push({
+                    path: SPOKE_BILLING_ACTION_PATH,
+                    reason: "edited here, and it imports the retired lib/checkout",
+                });
+            }
+        }
+    }
+    if (apply) {
+        for (const path of retired) {
+            const abs = resolve(join(targetAbs, ...path.split("/")));
+            if (!abs.startsWith(targetAbs + sep)) {
+                throw new Error(`refusing to delete outside target dir: ${abs}`);
+            }
+            rmSync(abs);
+            let dir = dirname(path);
+            while (dir !== "." && !RETIRE_STOP_DIRS.has(dir)) {
+                const dirAbs = join(targetAbs, ...dir.split("/"));
+                if (!existsSync(dirAbs) || readdirSync(dirAbs).length > 0)
+                    break;
+                rmdirSync(dirAbs);
+                dir = dirname(dir);
+            }
+        }
+        if (rewritten.length > 0)
+            writeFileSync(billingAbs, BILLING_ACTION);
+        if (record !== undefined && retired.some((path) => path in record.files)) {
+            const files = { ...record.files };
+            for (const path of retired)
+                delete files[path];
+            writeFileSync(recordPath, serializeTemplateRecord({ ...record, files }));
+        }
+    }
+    const byPath = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return {
+        retired: retired.sort(byPath),
+        kept: kept.sort((a, b) => byPath(a.path, b.path)),
+        rewritten,
+    };
+}
 /**
  * Compare an already-scaffolded repo's route tree with the template's and,
  * when `apply` is set, copy in the route dirs it is missing.
@@ -313,6 +626,7 @@ export function syncRoutes(opts) {
     const targetRouteRoot = join(targetAbs, ROUTE_ROOT);
     const missing = [];
     const modified = [];
+    let walks = [];
     const scratch = mkdtempSync(join(tmpdir(), "ailk-sync-routes-"));
     try {
         copyTemplate({
@@ -330,18 +644,73 @@ export function syncRoutes(opts) {
                 modified.push(report);
             }
         }
+        // #9406 — resolve each missing route's site-local imports while the
+        // scratch render is still on disk.
+        walks = missing.map((r) => walkRouteImports(r.route, {
+            scratch,
+            templatesDir: opts.templatesDir,
+            targetAbs,
+            missingRoutes: missing.map((m) => m.route),
+            versions: opts.versions,
+            markers,
+            spoke,
+            carried: new Set(["core", "authed", ...carried]),
+        }));
     }
     finally {
         rmSync(scratch, { recursive: true, force: true });
     }
+    // #9406 DD4 — a route refuses when an import resolves nowhere; refusal
+    // inherits to its sub-routes and to any route importing a file only a
+    // refused route's copy would write, iterated to a fixpoint. Never upward:
+    // an ancestor is still copied without the refused sub-tree.
+    const missingRoutes = missing.map((r) => r.route);
+    const refusedSet = new Set(walks.filter((w) => w.unresolved.length > 0).map((w) => w.route));
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const walk of walks) {
+            if (refusedSet.has(walk.route))
+                continue;
+            if (missingRoutes.some((a) => refusedSet.has(a) && walk.route.startsWith(`${a}/`))) {
+                refusedSet.add(walk.route);
+                changed = true;
+                continue;
+            }
+            const dangling = walk.reached.filter((r) => refusedSet.has(r.owner));
+            if (dangling.length > 0) {
+                walk.unresolved = sortUnresolved([
+                    ...walk.unresolved,
+                    ...dangling.map(({ path, owner, specifier, from }) => ({
+                        specifier,
+                        from,
+                        reason: `${path} is brought by ${owner}, which is refused`,
+                    })),
+                ]);
+                refusedSet.add(walk.route);
+                changed = true;
+            }
+        }
+    }
+    const refused = missingRoutes.filter((r) => refusedSet.has(r)).sort();
+    const routeImports = walks
+        .filter((w) => w.copies.length + w.differs.length + w.unresolved.length > 0)
+        .map(({ route, copies, differs, unresolved }) => ({ route, copies, differs, unresolved }))
+        .sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
     // #5014 third clause: a route's ROUTE_DEPENDENCIES files must exist in the
     // target too, or `--apply` leaves a route that cannot compile. Computed
     // from `missing` only — a route already present is assumed to already have
     // brought its own dependencies along (or the site owner has otherwise
     // satisfied them); re-checking every IN-SCOPE route's dependencies on every
     // run would report a pre-existing, unrelated gap as if this sync caused it.
+    // #9406 — unioned with the copies each route's imports resolve to, and
+    // never for a refused route: its helpers are neither required nor copied.
     const missingDependencies = [
-        ...new Set(missing.flatMap((r) => r.dependencies.filter((dep) => !existsSync(join(targetAbs, dep))))),
+        ...new Set(missing
+            .filter((r) => !refusedSet.has(r.route))
+            .flatMap((r) => [
+            ...r.dependencies.filter((dep) => !existsSync(join(targetAbs, dep))),
+            ...(walks.find((w) => w.route === r.route)?.copies ?? []),
+        ])),
     ].sort();
     const missingMessageNamespaces = [
         ...new Set(missing.flatMap((r) => r.messageNamespaces.filter((ns) => !hasMessageNamespace(targetAbs, ns)))),
@@ -349,11 +718,11 @@ export function syncRoutes(opts) {
     const applied = [];
     const appliedDependencies = [];
     if (opts.apply === true) {
-        const missingRoutes = missing.map((r) => r.route);
-        for (const route of missingRoutes) {
+        const writable = missingRoutes.filter((r) => !refusedSet.has(r));
+        for (const route of writable) {
             applied.push(route);
             // An ancestor route dir's subtree copy already brings this one.
-            if (missingRoutes.some((m) => route.startsWith(m + "/")))
+            if (writable.some((m) => route.startsWith(m + "/")))
                 continue;
             const dst = resolve(join(targetRouteRoot, route));
             if (!dst.startsWith(targetAbs + sep)) {
@@ -364,6 +733,10 @@ export function syncRoutes(opts) {
                 targetDir: dst,
                 versions: opts.versions,
                 markers,
+                // #9406 DD4 — hold back each refused sub-route from the ancestor's copy.
+                excludePaths: refused
+                    .filter((r) => r.startsWith(route + "/"))
+                    .map((r) => r.slice(route.length + 1)),
             });
         }
         for (const dep of missingDependencies) {
@@ -371,7 +744,7 @@ export function syncRoutes(opts) {
             if (!dst.startsWith(targetAbs + sep)) {
                 throw new Error(`refusing to write outside target dir: ${dst}`);
             }
-            copyDependencyFile(join(opts.templatesDir, dep), dst, markers);
+            copyDependencyFile(opts.templatesDir, dep, dst, opts.versions, markers);
             appliedDependencies.push(dep);
         }
         // #7874 D9 — a spoke declares what the copied routes read, as the last
@@ -387,11 +760,16 @@ export function syncRoutes(opts) {
         missing,
         modified,
         applied,
+        refused,
+        routeImports,
         missingDependencies,
         appliedDependencies,
         missingMessageNamespaces,
         skippedSurfaces,
         structuredDataEntries: structuredDataEntriesFor(targetAbs, opts.templatesDir, applied),
+        retiredCheckout: spoke !== undefined
+            ? retireLegacySpokeCheckout(targetAbs, opts.apply === true)
+            : { retired: [], kept: [], rewritten: [] },
     };
 }
 /**
@@ -420,19 +798,20 @@ function hasMessageNamespace(targetAbs, namespace) {
     }
 }
 /**
- * Copy one dependency file from the template into the target, applying the
- * same marker substitution `copyTemplate` applies to text files — every
- * `ROUTE_DEPENDENCIES` entry is `.ts`/`.tsx`, always text. Never overwrites:
- * the caller (`syncRoutes`) only calls this for a path already confirmed
- * absent from the target, but the check is repeated here so this helper is
- * safe to call on its own.
+ * Copy one dependency file (`rel`, template-relative) from the template into
+ * the target through `renderTemplateFile` — the renderer `copyTemplate` uses,
+ * so a text file gets its markers and a non-text asset an import reached
+ * (`./logo.png`, #9406) is copied byte-for-byte. Never overwrites: the caller
+ * (`syncRoutes`) only calls this for a path already confirmed absent from the
+ * target, but the check is repeated here so this helper is safe to call on
+ * its own.
  */
-function copyDependencyFile(src, dst, markers) {
+function copyDependencyFile(templatesDir, rel, dst, versions, markers) {
     if (existsSync(dst))
         return;
     mkdirSync(dirname(dst), { recursive: true });
-    const text = readFileSync(src, "utf8");
-    writeFileSync(dst, substituteMarkers(text, markers));
+    const bytes = readFileSync(join(templatesDir, ...rel.split("/")));
+    writeFileSync(dst, renderTemplateFile(bytes, rel, versions, markers));
 }
 /** Render the report the CLI prints after a run. Ends with a newline. */
 export function formatSyncRoutesReport(result, apply) {
@@ -446,7 +825,7 @@ export function formatSyncRoutesReport(result, apply) {
     }
     else if (apply) {
         lines.push(`[create-ailk] Copied ${result.applied.length} route(s):`);
-        lines.push(...result.missing.map(entry));
+        lines.push(...result.missing.filter((r) => result.applied.includes(r.route)).map(entry));
     }
     else {
         lines.push(`[create-ailk] ${result.missing.length} template route(s) missing:`);
@@ -459,6 +838,32 @@ export function formatSyncRoutesReport(result, apply) {
     if (result.skippedSurfaces.length > 0) {
         lines.push(`[create-ailk] Surfaces this site does not carry (skipped): ${result.skippedSurfaces.join(", ")}`);
     }
+    // #9406 DD5 — per missing route, what its imports copy, leave, or cannot
+    // resolve; then the routes a dangling import holds back.
+    if (result.routeImports.length > 0) {
+        lines.push("[create-ailk] Local modules the missing route(s) import:");
+        for (const { route, copies, differs, unresolved } of result.routeImports) {
+            lines.push(`  ${route}`);
+            if (copies.length > 0) {
+                lines.push("    copies:");
+                lines.push(...copies.map((path) => `      ${path}`));
+            }
+            if (differs.length > 0) {
+                lines.push("    left as-is (differs from the template):");
+                lines.push(...differs.map((path) => `      ${path}`));
+            }
+            if (unresolved.length > 0) {
+                lines.push("    cannot resolve:");
+                lines.push(...unresolved.map(({ specifier, from, reason }) => `      ${specifier} (from ${from}): ${reason}`));
+            }
+        }
+    }
+    if (result.refused.length > 0) {
+        lines.push(apply
+            ? `[create-ailk] ${result.refused.length} route(s) not copied — an import does not resolve:`
+            : `[create-ailk] ${result.refused.length} route(s) would not be copied — an import does not resolve:`);
+        lines.push(...result.refused.map((route) => `  ${route}`));
+    }
     // #5014 third clause: the routes/messages/lib a synced route needs to
     // compile, reported (and, for lib files, applied) alongside the route.
     if (result.missingDependencies.length > 0) {
@@ -478,6 +883,25 @@ export function formatSyncRoutesReport(result, apply) {
             lines.push(...entry.split("\n").map((line) => `    ${line}`));
         }
     }
+    // #9142 — the retired legacy spoke checkout, named so the operator sees
+    // exactly what left and what stays for them to delete.
+    const retiredCheckout = result.retiredCheckout;
+    if (retiredCheckout.retired.length > 0) {
+        lines.push(apply
+            ? `[create-ailk] Removed ${retiredCheckout.retired.length} file(s) of the retired legacy spoke checkout (a spoke sells through its hub's Offerings buy route):`
+            : `[create-ailk] ${retiredCheckout.retired.length} file(s) of the retired legacy spoke checkout to remove with --apply (a spoke sells through its hub's Offerings buy route):`);
+        lines.push(...retiredCheckout.retired.map((path) => `  ${path}`));
+    }
+    if (retiredCheckout.rewritten.length > 0) {
+        lines.push(apply
+            ? "[create-ailk] Rewrote the generated billing action off the retired lib/checkout:"
+            : "[create-ailk] The generated billing action imports the retired lib/checkout; --apply rewrites it:");
+        lines.push(...retiredCheckout.rewritten.map((path) => `  ${path}`));
+    }
+    if (retiredCheckout.kept.length > 0) {
+        lines.push(`[create-ailk] ${retiredCheckout.kept.length} file(s) of the retired legacy spoke checkout left in place — delete or rewrite by hand:`);
+        lines.push(...retiredCheckout.kept.map(({ path, reason }) => `  ${path}  (${reason})`));
+    }
     if (result.missing.length > 0 && !apply) {
         lines.push("Run `create-ailk sync-routes <target> --apply` to copy the missing routes.");
     }
@@ -500,7 +924,9 @@ Options:
 
 Checks every core route plus the routes of each surface the site carries; a
 surface gated off at scaffold time is skipped, not drift. A route the site has
-changed locally is reported and never overwritten. Nothing is ever deleted.
+changed locally is reported and never overwritten. Nothing is deleted except,
+on a spoke, the retired legacy checkout's files that still match create-ailk's
+copy: --apply removes them and rewrites the generated billing action (#9142).
 `;
 /**
  * Parse the argv AFTER the `sync-routes` word. Strict `node:util` parseArgs,

package/dist/template-record.d.ts

@@ -3,7 +3,7 @@ export declare const TEMPLATE_RECORD_PATH = ".ailk-template-files.json";
 /**
  * The app paths a generator rewrites after `copyTemplate` lands its copy
  * (§1): the nav, the site chrome, the site fonts, the paid-sections
- * registry, the four spoke seams, and a commerce spoke's checkout config,
+ * registry and its module-presence flags (#8843 D10), the four spoke seams, and a commerce spoke's checkout config,
  * which the checkout writer stamps and the site owns from then on (#8748
  * D2). Composed from each writer's own exported path constant, so a renamed
  * constant carries its path along here too (#8522 D2).

package/dist/template-record.js

@@ -18,7 +18,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { PAID_SECTIONS_PATH } from "./paid-sections.js";
+import { MODULE_FLAGS_PATH, PAID_SECTIONS_PATH } from "./paid-sections.js";
 import { SITE_CHROME_PATH } from "./site-chrome.js";
 import { SITE_FONTS_PATH } from "./site-fonts.js";
 import { SPOKE_CHECKOUT_CONFIG_PATH } from "./spoke-checkout.js";
@@ -29,7 +29,7 @@ export const TEMPLATE_RECORD_PATH = ".ailk-template-files.json";
 /**
  * The app paths a generator rewrites after `copyTemplate` lands its copy
  * (§1): the nav, the site chrome, the site fonts, the paid-sections
- * registry, the four spoke seams, and a commerce spoke's checkout config,
+ * registry and its module-presence flags (#8843 D10), the four spoke seams, and a commerce spoke's checkout config,
  * which the checkout writer stamps and the site owns from then on (#8748
  * D2). Composed from each writer's own exported path constant, so a renamed
  * constant carries its path along here too (#8522 D2).
@@ -39,6 +39,7 @@ export const REGENERATED_APP_PATHS = [
     SITE_CHROME_PATH,
     SITE_FONTS_PATH,
     PAID_SECTIONS_PATH,
+    MODULE_FLAGS_PATH,
     ...SPOKE_SEAM_FILES,
     SPOKE_CHECKOUT_CONFIG_PATH,
 ];

package/dist/update.js

@@ -26,6 +26,7 @@ import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core
 import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
 import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
 import { mergeThreeWay } from "./lib/merge-three-way.js";
+import { MODULE_FLAGS_PATH, writeModuleFlags } 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";
@@ -514,6 +515,15 @@ export async function updateSite(opts) {
     if (recordChanged) {
         writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
     }
+    // #8843 D10 — the module-presence flags are generated, never copied
+    // (REGENERATED_APP_PATHS): render them from this site's own
+    // apps/web/package.json on every run, so a site updated onto a layout
+    // that imports them has them before it builds. Not recorded.
+    const flags = writeModuleFlags(targetDir);
+    if (flags === "added")
+        moved.added.push(MODULE_FLAGS_PATH);
+    else if (flags === "updated")
+        moved.updated.push(MODULE_FLAGS_PATH);
     return {
         targetDir,
         version,