create-ailk 0.19.1 → 0.21.0

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/template-record.d.ts

@@ -0,0 +1,59 @@
+/** Where the per-file record lives, beside `.ailk-site-manifest.json`. */
+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, and the four spoke seams. Composed from each writer's own
+ * exported path constant, so a renamed constant carries its path along
+ * here too (#8522 D2).
+ */
+export declare const REGENERATED_APP_PATHS: readonly string[];
+/**
+ * Whether a destination path (`/`-separated, as `templateDestination`
+ * returns it) is one `update` ever records or touches (#8522 D2): under one
+ * of the three app trees, not a `package.json`, not an `.env*` file, no
+ * `.claude` segment, and not a path a generator rewrites after the copy.
+ */
+export declare function isRecordable(destRel: string): boolean;
+/** The hex sha256 digest of `bytes` — the one hash every record row uses. */
+export declare function sha256Hex(bytes: Uint8Array): string;
+export interface TemplateFileRow {
+    sha256: string;
+    version: string;
+}
+export interface TemplateRecord {
+    schema: 1;
+    projectName: string;
+    files: Record<string, TemplateFileRow>;
+}
+/** Thrown by `parseTemplateRecord` on a malformed or unsafe record. */
+export declare class TemplateRecordError extends Error {
+    constructor(message: string);
+}
+/**
+ * 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).
+ */
+export declare function parseTemplateRecord(text: string): TemplateRecord;
+/** `record` as `scaffold()` and `update` write it: sorted keys, trailing newline. */
+export declare function serializeTemplateRecord(record: TemplateRecord): string;
+export interface PlanTemplateRecordOptions {
+    /** The freshly scaffolded site. */
+    targetDir: string;
+    /** Destination path -> sha256 of the bytes `copyTemplate`'s `onWrite` wrote, for every recordable path. */
+    copied: ReadonlyMap<string, string>;
+    /** The create-ailk version that wrote this scaffold. */
+    version: string;
+    projectName: string;
+}
+/**
+ * The record a fresh scaffold writes (#8522 D2): one row per copied path
+ * whose file still exists and whose current bytes still hash to the copy —
+ * a later layer (a module bundle's patch, a generator) that rewrote the
+ * file drops it from the record, exactly as it is absent from the record a
+ * `create-ailk update` keeps current for it.
+ */
+export declare function planTemplateRecord(opts: PlanTemplateRecordOptions): TemplateRecord;

package/dist/template-record.js

@@ -0,0 +1,183 @@
+/**
+ * `.ailk-template-files.json` — the per-file record of what a scaffold's
+ * copied app code is (#8522 D1/D2).
+ *
+ * Written beside `.ailk-site-manifest.json` at the site root, it lists every
+ * `apps/web/`, `apps/api/` and `apps/mcp/` file the base `templates/` copy
+ * wrote and no later layer rewrote, with the sha256 of the template's copy
+ * of that file and the create-ailk version it came from. `create-ailk
+ * update` (`update.ts`) reads it to tell an untouched copy from an owner's
+ * edit; `scaffold()` (`programmatic.ts`) writes it, as its last write, from
+ * the `onWrite` hook `copyTemplate` (`copy.ts`) calls once per file.
+ *
+ * Pure module: no `import.meta.url`, no filesystem write — `planTemplateRecord`
+ * only READS the scaffold's own disk to confirm a copied path's final bytes
+ * (a later layer may have rewritten it, D2); every write goes through the
+ * caller.
+ */
+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 { SITE_CHROME_PATH } from "./site-chrome.js";
+import { SITE_FONTS_PATH } from "./site-fonts.js";
+import { NAV_CONFIG_PATH } from "./surfaces.js";
+import { SPOKE_SEAM_FILES } from "./topology.js";
+/** Where the per-file record lives, beside `.ailk-site-manifest.json`. */
+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, and the four spoke seams. Composed from each writer's own
+ * exported path constant, so a renamed constant carries its path along
+ * here too (#8522 D2).
+ */
+export const REGENERATED_APP_PATHS = [
+    NAV_CONFIG_PATH,
+    SITE_CHROME_PATH,
+    SITE_FONTS_PATH,
+    PAID_SECTIONS_PATH,
+    ...SPOKE_SEAM_FILES,
+];
+const REGENERATED_SET = new Set(REGENERATED_APP_PATHS);
+const RECORDABLE_APP_ROOT = /^apps\/(web|api|mcp)\//;
+/**
+ * Whether a destination path (`/`-separated, as `templateDestination`
+ * returns it) is one `update` ever records or touches (#8522 D2): under one
+ * of the three app trees, not a `package.json`, not an `.env*` file, no
+ * `.claude` segment, and not a path a generator rewrites after the copy.
+ */
+export function isRecordable(destRel) {
+    if (!RECORDABLE_APP_ROOT.test(destRel))
+        return false;
+    const segments = destRel.split("/");
+    const base = segments[segments.length - 1] ?? "";
+    if (base === "package.json")
+        return false;
+    if (base.startsWith(".env"))
+        return false;
+    if (segments.includes(".claude"))
+        return false;
+    if (REGENERATED_SET.has(destRel))
+        return false;
+    return true;
+}
+/** The hex sha256 digest of `bytes` — the one hash every record row uses. */
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Thrown by `parseTemplateRecord` on a malformed or unsafe record. */
+export class TemplateRecordError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TemplateRecordError";
+    }
+}
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+/**
+ * Whether `key` is traversal-safe: no `..`, no empty segment, no backslash,
+ * no leading `/` (D1). This alone does not make `key` a path `update` may
+ * touch — `parseTemplateRecord` also requires `isRecordable(key)`, so a
+ * tampered record can never direct a write or delete outside the three app
+ * trees nor at a non-recordable path (`package.json`, `.env*`, a
+ * `REGENERATED_APP_PATHS` entry, …) inside them.
+ */
+function isSafeRecordKey(key) {
+    if (key.length === 0 || key.startsWith("/") || key.includes("\\")) {
+        return false;
+    }
+    const segments = key.split("/");
+    return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/**
+ * 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).
+ */
+export function parseTemplateRecord(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch (err) {
+        throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} is not valid JSON: ${err.message}`);
+    }
+    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
+        throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} is not a JSON object`);
+    }
+    const record = doc;
+    const allowed = new Set(["schema", "projectName", "files"]);
+    for (const key of Object.keys(record)) {
+        if (!allowed.has(key)) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} has an unknown top-level key "${key}"`);
+        }
+    }
+    if (record["schema"] !== 1) {
+        throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "schema" must be 1, got ${JSON.stringify(record["schema"])}`);
+    }
+    const projectName = record["projectName"];
+    if (typeof projectName !== "string" || projectName.length === 0) {
+        throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "projectName" must be a non-empty string`);
+    }
+    const filesRaw = record["files"];
+    if (typeof filesRaw !== "object" || filesRaw === null || Array.isArray(filesRaw)) {
+        throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" must be an object`);
+    }
+    const files = {};
+    for (const [key, value] of Object.entries(filesRaw)) {
+        if (!isSafeRecordKey(key)) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has an unsafe key "${key}"`);
+        }
+        if (!isRecordable(key)) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files" has a key "${key}" that is not a recordable path`);
+        }
+        if (typeof value !== "object" || value === null) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files"["${key}"] must be an object`);
+        }
+        const row = value;
+        const sha = row["sha256"];
+        if (typeof sha !== "string" || !SHA256_PATTERN.test(sha)) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files"["${key}"].sha256 must be 64 lowercase hex characters`);
+        }
+        const version = row["version"];
+        if (typeof version !== "string" || !VERSION_PATTERN.test(version)) {
+            throw new TemplateRecordError(`${TEMPLATE_RECORD_PATH} "files"["${key}"].version must be a semver string`);
+        }
+        files[key] = { sha256: sha, version };
+    }
+    return { schema: 1, projectName, files };
+}
+/** `record` as `scaffold()` and `update` write it: sorted keys, trailing newline. */
+export function serializeTemplateRecord(record) {
+    const files = {};
+    for (const key of Object.keys(record.files).sort()) {
+        files[key] = record.files[key];
+    }
+    return (JSON.stringify({ schema: record.schema, projectName: record.projectName, files }, null, 2) +
+        "\n");
+}
+/**
+ * The record a fresh scaffold writes (#8522 D2): one row per copied path
+ * whose file still exists and whose current bytes still hash to the copy —
+ * a later layer (a module bundle's patch, a generator) that rewrote the
+ * file drops it from the record, exactly as it is absent from the record a
+ * `create-ailk update` keeps current for it.
+ */
+export function planTemplateRecord(opts) {
+    const files = {};
+    for (const path of [...opts.copied.keys()].sort()) {
+        const hash = opts.copied.get(path);
+        if (hash === undefined)
+            continue;
+        const abs = join(opts.targetDir, ...path.split("/"));
+        if (!existsSync(abs))
+            continue;
+        if (sha256Hex(readFileSync(abs)) !== hash)
+            continue;
+        files[path] = { sha256: hash, version: opts.version };
+    }
+    return { schema: 1, projectName: opts.projectName, files };
+}

package/dist/update.d.ts

@@ -0,0 +1,53 @@
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export declare class UpdateRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface UpdateSiteOptions {
+    /** The existing site. */
+    targetDir: string;
+    /** The running package's own `templates/` directory. */
+    templatesDir: string;
+    /** The running create-ailk version. */
+    version: string;
+    /** Overrides `AILK_NPM_REGISTRY_URL` / the public npm registry default. */
+    registryUrl?: string;
+    /** Injected fetch for tests. Never a live network call in CI. */
+    fetchImpl?: typeof fetch;
+}
+export interface UpdateResult {
+    targetDir: string;
+    version: string;
+    updated: string[];
+    merged: string[];
+    added: string[];
+    removed: string[];
+    current: string[];
+    review: Array<{
+        path: string;
+        reason: string;
+    }>;
+    skipped: Array<{
+        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;
+    };
+}
+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;
+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\". 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;