create-ailk 0.19.1 → 0.20.0

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,48 @@
+/** 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;
+    }>;
+    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\" \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";
+/** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
+export declare function parseUpdateArgs(argv: string[]): UpdateArgs;