create-ailk 0.19.1 → 0.21.0

package/dist/design-home.js

@@ -10,17 +10,41 @@
  * fingerprint is a known placeholder (the shape's own home, or a shipped
  * design's arc of it); any authored home is left alone.
  *
+ * #8661 D11 — a design may also carry `contact/<shape>.mdx`, a complete
+ * `ContactPage` seeded the same way, with two differences: its
+ * `{{SITE_NAME}}` is filled from the site's `siteIdentity.name`, and it
+ * replaces the page's `title:` line as well as its `sections:` value (and a
+ * placeholder `description:` line), so the page is a placeholder only while
+ * its title is one too. Every reader and
+ * planner below takes the seeded page as `page` (default `"home"`).
+ *
  * Pure apart from `readDesignHomeSeeds`/`designHomeSeeds`: every directory it
  * reads is passed in (no `import.meta.url` — Jest's CJS transform).
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { buildScaffoldMarkers } from "./copy.js";
 import { DesignPackageError } from "./design-package.js";
 import { locatePageSections, pageTypeOf, } from "./design-presets.js";
 import { RECOGNIZED_SHAPES } from "./parse-args.js";
+import { substituteMarkers } from "./substitute.js";
 import { STARTER_DESIGNS, TemplateError } from "./template-manifest.js";
 /** Where a site's home page lives, site-relative. */
 export const HOME_PAGE_PATH = "content/en/HomePage/home.mdx";
+/** Where a site's contact page lives, site-relative (#8661 D11). */
+export const CONTACT_PAGE_PATH = "content/en/ContactPage/contact.mdx";
+/**
+ * The pages a design may seed (#8661 D11), keyed by the design-package
+ * directory that holds their seeds (`home/<shape>.mdx`, `contact/<shape>.mdx`).
+ */
+export const DESIGN_SEED_PAGES = {
+    home: { pageType: "HomePage", path: HOME_PAGE_PATH, route: "/" },
+    contact: { pageType: "ContactPage", path: CONTACT_PAGE_PATH, route: "/contact" },
+};
+/** The marker a contact seed's heading and title carry for the site's name (#8661 D11, C8). */
+const SITE_NAME_MARKER = "{{SITE_NAME}}";
+/** The name a contact seed takes when the site records none (#8661 D11). */
+const NO_SITE_NAME = "{Your Name}";
 // ── D1: reading a design's seeds ───────────────────────────────────────────
 /** Flow punctuation: whitespace beside it is layout, never content. */
 const FLOW_PUNCTUATION = new Set(["{", "}", "[", "]", ",", ":"]);
@@ -72,14 +96,18 @@ function rawEntry(text, sections, index, key) {
     return entry === undefined ? undefined : text.slice(entry.valueStart, entry.valueEnd);
 }
 /**
- * Read and validate `<dir>/home/*` (D1). Refuses with a `DesignPackageError`
- * naming the file, before any write: a basename that is not a recognized
- * shape, a page whose `type` is not `HomePage`, `sections` that cannot be
- * located (or are not in the flow form a carry can splice), a section type
- * the catalog does not carry, or a `logoCloud` whose `logos` is not `[]`.
+ * Read and validate `<dir>/home/*` (D1), or `<dir>/contact/*` for
+ * `page: "contact"` (#8661 D11). Refuses with a `DesignPackageError` naming
+ * the file, before any write: a basename that is not a recognized shape, a
+ * page whose `type` is not the page's (`HomePage`, `ContactPage`), `sections`
+ * that cannot be located (or are not in the flow form a carry can splice), a
+ * section type the catalog does not carry, or a `logoCloud` whose `logos` is
+ * not `[]`.
  */
 export function readDesignHomeSeeds(dir, opts) {
-    const homeDir = join(dir, "home");
+    const page = opts.page ?? "home";
+    const expectedType = DESIGN_SEED_PAGES[page].pageType;
+    const homeDir = join(dir, page);
     if (!existsSync(homeDir))
         return [];
     const seeds = [];
@@ -87,7 +115,7 @@ export function readDesignHomeSeeds(dir, opts) {
         const file = join(homeDir, name);
         const shape = name.replace(/\.mdx$/, "");
         if (!name.endsWith(".mdx") || !RECOGNIZED_SHAPES.includes(shape)) {
-            throw new DesignPackageError(file, "home", `is not named after a recognized shape (expected <shape>.mdx, one of ${RECOGNIZED_SHAPES.join(", ")})`);
+            throw new DesignPackageError(file, page, `is not named after a recognized shape (expected <shape>.mdx, one of ${RECOGNIZED_SHAPES.join(", ")})`);
         }
         const text = readFileSync(file, "utf8");
         let pageType;
@@ -101,8 +129,8 @@ export function readDesignHomeSeeds(dir, opts) {
                 throw err;
             throw new DesignPackageError(file, "sections", `cannot be located (${err.message})`);
         }
-        if (pageType !== "HomePage") {
-            throw new DesignPackageError(file, "type", `must be "HomePage" (got ${JSON.stringify(pageType ?? null)})`);
+        if (pageType !== expectedType) {
+            throw new DesignPackageError(file, "type", `must be "${expectedType}" (got ${JSON.stringify(pageType ?? null)})`);
         }
         if (sections === undefined || sections.some((s) => s.form !== "flow")) {
             throw new DesignPackageError(file, "sections", "must be a flow sequence of sections");
@@ -127,12 +155,12 @@ export function readDesignHomeSeeds(dir, opts) {
     return seeds;
 }
 /**
- * The seeds a resolved design uses (D1): its own `home/`, else — a
- * byte-identical copy of a shipped design IS that design — the shipped
- * design's, else none.
+ * The seeds a resolved design uses (D1): its own `home/` (or `contact/`),
+ * else — a byte-identical copy of a shipped design IS that design — the
+ * shipped design's, else none.
  */
 export function designHomeSeeds(resolved, opts) {
-    if (existsSync(join(resolved.dir, "home")))
+    if (existsSync(join(resolved.dir, opts.page ?? "home")))
         return readDesignHomeSeeds(resolved.dir, opts);
     if (STARTER_DESIGNS.includes(resolved.recorded)) {
         return readDesignHomeSeeds(join(opts.designsDir, resolved.recorded), opts);
@@ -143,10 +171,87 @@ export function designHomeSeeds(resolved, opts) {
 export function shippedHomeSeeds(opts) {
     return STARTER_DESIGNS.flatMap((name) => readDesignHomeSeeds(join(opts.designsDir, name), opts));
 }
-/** The shape's own home: its shape tree's, else the overlay's (spec § 1.4). */
+/** The shape's own home (or contact page): its shape tree's, else the overlay's (spec § 1.4). */
 export function shapeHomePath(shape, opts) {
-    const own = join(opts.siteTemplatesDir, "shapes", shape, ...HOME_PAGE_PATH.split("/"));
-    return existsSync(own) ? own : join(opts.templatesDir, ...HOME_PAGE_PATH.split("/"));
+    const path = DESIGN_SEED_PAGES[opts.page ?? "home"].path.split("/");
+    const own = join(opts.siteTemplatesDir, "shapes", shape, ...path);
+    return existsSync(own) ? own : join(opts.templatesDir, ...path);
+}
+// ── #8661 D11: the contact page's name and title ───────────────────────────
+/** The front matter's body, or undefined when the text opens with none. */
+function frontMatterOf(text) {
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?$/m.exec(text);
+    return fm && fm.index === 0 ? fm[1] : undefined;
+}
+/** A one-line YAML scalar's string value: a double-quoted value is JSON-read, a single-quoted one unescaped. */
+function unquote(raw) {
+    const value = raw.trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.startsWith("'") && value.endsWith("'") && value.length >= 2)
+        return value.slice(1, -1).replace(/''/g, "'");
+    return value;
+}
+/**
+ * A site's `siteIdentity.name` (#8661 D11, C8): the first `name:` line
+ * indented directly under `siteIdentity:` in `content/_site.mdx`'s front
+ * matter, quotes stripped. Undefined when there is no such line.
+ */
+export function siteIdentityName(siteMdx) {
+    const fm = siteMdx === undefined ? undefined : frontMatterOf(siteMdx);
+    if (fm === undefined)
+        return undefined;
+    const lines = fm.split(/\r?\n/);
+    const start = lines.findIndex((line) => /^siteIdentity:[ \t]*$/.test(line));
+    if (start < 0)
+        return undefined;
+    let indent;
+    for (const line of lines.slice(start + 1)) {
+        if (line.trim() === "" || line.trimStart().startsWith("#"))
+            continue;
+        const lead = line.length - line.trimStart().length;
+        if (lead === 0)
+            return undefined;
+        indent ??= lead;
+        if (lead !== indent)
+            continue;
+        const m = /^[ \t]+name:[ \t]*(.+?)[ \t]*$/.exec(line);
+        if (m) {
+            const name = unquote(m[1]);
+            return name === "" ? undefined : name;
+        }
+    }
+    return undefined;
+}
+/** `seed` with its `{{SITE_NAME}}` filled, escaped for the double-quoted strings it sits in. */
+function fillSiteName(seed, name) {
+    const escaped = JSON.stringify(name).slice(1, -1);
+    return { ...seed, text: seed.text.split(SITE_NAME_MARKER).join(escaped) };
+}
+/** The `<key>:` line's span in the front matter, or undefined. */
+function metaLine(text, key) {
+    const fm = frontMatterOf(text);
+    if (fm === undefined)
+        return undefined;
+    const m = new RegExp(`^${key}:[ \\t]*(.*?)[ \\t]*$`, "m").exec(fm);
+    if (!m)
+        return undefined;
+    const offset = text.indexOf(fm);
+    return { start: offset + m.index, end: offset + m.index + m[0].length, value: unquote(m[1]) };
+}
+/** `page` with its `<key>:` line replaced by `from`'s (or left as it is when either has none). */
+function spliceMeta(page, from, key) {
+    const at = metaLine(page, key);
+    const source = metaLine(from, key);
+    if (at === undefined || source === undefined)
+        return page;
+    return page.slice(0, at.start) + from.slice(source.start, source.end) + page.slice(at.end);
 }
 // ── D3: the content fingerprint ────────────────────────────────────────────
 function locate(text, file) {
@@ -219,16 +324,32 @@ export function applySeed(home, seed, file = "home.mdx") {
 /**
  * Plan a site home under a design (D3). Writes nothing: `text` is the new
  * home when the outcome is `seeded` or `restored`, and absent otherwise.
+ *
+ * `page: "contact"` (#8661 D11) plans the contact page instead. The seeds'
+ * `{{SITE_NAME}}` is filled with `siteName` (absent: `{Your Name}`) before
+ * anything is compared; the shape's own page is read with the scaffold
+ * markers substituted, as a scaffold installed it; the page is a placeholder
+ * only while its title is one too (the shape's own, or a seed's); and a write
+ * replaces the `title:` line as well as the sections, and the `description:`
+ * line while it is still a placeholder (the shape's own, or a seed's).
  */
 export function planDesignHome(opts) {
-    const { current, shape, target, shapeHome, catalog } = opts;
+    const page = opts.page ?? "home";
+    const contact = page === "contact";
+    const pagePath = DESIGN_SEED_PAGES[page].path;
+    const { current, shape, catalog } = opts;
     if (current === undefined)
         return { outcome: "no-home" };
     if (shape === undefined)
         return { outcome: "no-shape" };
+    const name = opts.siteName ?? NO_SITE_NAME;
+    const fill = (seed) => (contact ? fillSiteName(seed, name) : seed);
+    const target = opts.target === undefined ? undefined : fill(opts.target);
+    // The scaffold's own markers carry no project-specific value a contact page uses.
+    const shapeHome = contact ? substituteMarkers(opts.shapeHome, buildScaffoldMarkers("")) : opts.shapeHome;
     let currentPrint;
     try {
-        currentPrint = fingerprint(current, catalog, HOME_PAGE_PATH);
+        currentPrint = fingerprint(current, catalog, pagePath);
     }
     catch (err) {
         // A home whose sections cannot be read is not a placeholder: never write it.
@@ -236,21 +357,38 @@ export function planDesignHome(opts) {
             return { outcome: "authored" };
         throw err;
     }
-    const seeds = [...opts.shippedSeeds.filter((s) => s.shape === shape), ...(target !== undefined ? [target] : [])];
+    const seeds = [
+        ...opts.shippedSeeds.filter((s) => s.shape === shape).map(fill),
+        ...(target !== undefined ? [target] : []),
+    ];
     const placeholders = new Set([
         fingerprint(shapeHome, catalog),
         ...seeds.map((seed) => fingerprint(spliceSections(shapeHome, applySeed(shapeHome, seed), "shape home"), catalog)),
     ]);
     if (!placeholders.has(currentPrint))
         return { outcome: "authored" };
+    // #8661 D11 — a contact page whose title was retitled is authored, whatever its sections.
+    const placeholderTexts = [shapeHome, ...seeds.map((seed) => seed.text)];
+    const placeholderMeta = (key) => new Set(placeholderTexts.map((text) => metaLine(text, key)?.value));
+    if (contact && !placeholderMeta("title").has(metaLine(current, "title")?.value))
+        return { outcome: "authored" };
     const wanted = target !== undefined
-        ? applySeed(current, target, HOME_PAGE_PATH)
+        ? applySeed(current, target, pagePath)
         : (() => {
             const own = locate(shapeHome, "shape home");
             return shapeHome.slice(own.valueStart, own.valueEnd);
         })();
-    const text = spliceSections(current, wanted, HOME_PAGE_PATH);
-    if (fingerprint(text, catalog) === currentPrint)
+    let text = spliceSections(current, wanted, pagePath);
+    if (contact) {
+        const from = target?.text ?? shapeHome;
+        text = spliceMeta(text, from, "title");
+        // An edited description is the customer's: only a placeholder one is replaced.
+        if (placeholderMeta("description").has(metaLine(current, "description")?.value)) {
+            text = spliceMeta(text, from, "description");
+        }
+    }
+    const sameMeta = ["title", "description"].every((key) => metaLine(text, key)?.value === metaLine(current, key)?.value);
+    if (fingerprint(text, catalog) === currentPrint && sameMeta)
         return { outcome: "unchanged" };
     return { outcome: target !== undefined ? "seeded" : "restored", text };
 }

package/dist/lib/design-checks.d.ts

@@ -54,9 +54,14 @@ export type JsonLdDriftVerdict = {
  * returned as it is.
  */
 export declare function admitSeededPeopleSlide(before: ComposedPages, after: ComposedPages): ComposedPages;
+/**
+ * `after` with the standard contact page put back when the seeded one differs
+ * only in `name` and `description` (#8661 D11).
+ */
+export declare function admitSeededContactPage(before: ComposedPages, after: ComposedPages): ComposedPages;
 /**
  * Decide whether `apply-design <design>` left every page's JSON-LD unchanged
- * (logo excluded), the seeded people slide's Persons admitted.
+ * (logo excluded), the seeded people slide's Persons and contact page admitted.
  */
 export declare function assessJsonLdDrift(design: string, before: ComposedPages, after: ComposedPages): JsonLdDriftVerdict;
 export interface MeasureApplyDesignDriftOptions {

package/dist/lib/design-checks.js

@@ -21,11 +21,14 @@
  * organization home's people slide adds one `Person` per seeded team member to
  * the home's graph. `admitSeededPeopleSlide` puts the standard home back only
  * when the seeded home is exactly that, so any other change still counts.
+ * Likewise a design that seeds the contact page renames and re-describes it
+ * (#8661 D11); `admitSeededContactPage` admits only those two fields.
  */
 import { execFileSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
+import { CONTACT_PAGE_PATH } from "../design-home.js";
 import { TEAM_SEED_MEMBERS } from "../team-profiles.js";
 function describePair(row) {
     const measured = row.status === "unmeasurable" || row.ratio === null
@@ -140,18 +143,36 @@ export function admitSeededPeopleSlide(before, after) {
     const isPeopleSlide = isDeepStrictEqual(page, JSON.parse(standard.jsonld)) && isDeepStrictEqual(people, expected);
     return isPeopleSlide ? { ...after, [HOME_PAGE]: standard } : after;
 }
+/**
+ * `after` with the standard contact page put back when the seeded one differs
+ * only in `name` and `description` (#8661 D11).
+ */
+export function admitSeededContactPage(before, after) {
+    const standard = before[CONTACT_PAGE_PATH];
+    const seeded = after[CONTACT_PAGE_PATH];
+    if (standard === undefined || seeded === undefined || !seeded.sectionsValid)
+        return after;
+    const strip = (jsonld) => ({
+        ...JSON.parse(jsonld),
+        name: undefined,
+        description: undefined,
+    });
+    return isDeepStrictEqual(strip(seeded.jsonld), strip(standard.jsonld))
+        ? { ...after, [CONTACT_PAGE_PATH]: standard }
+        : after;
+}
 /** How many changed nodes a drift reason lists before it stops. */
 const REASON_NODE_LIMIT = 10;
 /**
  * Decide whether `apply-design <design>` left every page's JSON-LD unchanged
- * (logo excluded), the seeded people slide's Persons admitted.
+ * (logo excluded), the seeded people slide's Persons and contact page admitted.
  */
 export function assessJsonLdDrift(design, before, after) {
     const pages = Object.keys(before).length;
     if (pages === 0) {
         return { ok: false, pages, changed: [], reason: `design ${design}: no page was composed` };
     }
-    const changed = jsonLdDrift(before, admitSeededPeopleSlide(before, after));
+    const changed = jsonLdDrift(before, admitSeededContactPage(before, admitSeededPeopleSlide(before, after)));
     if (changed.length === 0)
         return { ok: true, pages };
     const listed = changed

package/dist/lib/fetch-template-snapshot.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_AILK_NPM_REGISTRY_URL = "https://registry.npmjs.org";
+export declare class FetchTemplateSnapshotError extends Error {
+    constructor(message: string);
+}
+export interface FetchTemplateSnapshotOptions {
+    /** The create-ailk version to re-materialise, e.g. "0.19.1". */
+    version: string;
+    /** Registry root; defaults to `AILK_NPM_REGISTRY_URL`, else the public npm registry. */
+    registryUrl?: string;
+    /** Injected fetch for tests. Never a live network call in CI. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch and re-materialise create-ailk `version`'s `templates/apps/{web,api,mcp}/`
+ * tree from its published npm tarball.
+ *
+ * @throws FetchTemplateSnapshotError on an invalid version, an unreachable
+ *   or malformed registry response, an integrity mismatch, or a symlink /
+ *   hard-link entry under one of the three app prefixes.
+ */
+export declare function fetchTemplateSnapshot(options: FetchTemplateSnapshotOptions): Promise<Map<string, Uint8Array>>;

package/dist/lib/fetch-template-snapshot.js

@@ -0,0 +1,205 @@
+/**
+ * Re-materialise an old create-ailk's `templates/apps/{web,api,mcp}/` tree
+ * from its published npm tarball (#8522 D6) — the merge base
+ * `create-ailk update` needs for a recorded version no longer sitting in
+ * this package's own `templates/`.
+ *
+ * Reads the public, unauthenticated npm registry — no bearer token, unlike
+ * `fetch-template.ts` / `fetch-module.ts` — through the same safety guards
+ * those two share (`fetch-guard.ts`): an `https:` (or loopback, for the test
+ * mock) registry URL, a request timeout, and a declared-`Content-Length`
+ * cap before the body is ever buffered. The tarball's integrity is verified
+ * against the packument's `dist.integrity` before it is gunzipped, and the
+ * gunzip itself is capped at the same `MAX_TOTAL_SIZE_BYTES`
+ * `extract-module-bundle.ts` enforces for a module bundle, so the whole
+ * fetch is bounded in memory regardless of what the tarball's own headers
+ * claim. The gunzipped tar is parsed in memory with `tar`'s own `Parser` —
+ * never extracted to disk — and only regular files under the three app
+ * prefixes are kept.
+ */
+import { createHash } from "node:crypto";
+import { gunzipSync } from "node:zlib";
+import * as tar from "tar";
+import { templateDestination } from "../copy.js";
+import { MAX_TOTAL_SIZE_BYTES } from "./extract-module-bundle.js";
+import { assertContentLengthWithinLimit, assertHttpsRegistryUrl, fetchTimeoutSignal, } from "./fetch-guard.js";
+export const DEFAULT_AILK_NPM_REGISTRY_URL = "https://registry.npmjs.org";
+/** The same version shape `.ailk-template-files.json` rows are checked against (D1). */
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/;
+/** The one tar path prefix a snapshot is read from, and the three app roots inside it. */
+const TAR_ROOT = "package/templates/";
+const APP_PREFIXES = ["apps/web/", "apps/api/", "apps/mcp/"];
+export class FetchTemplateSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FetchTemplateSnapshotError";
+    }
+}
+function detail(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** The one version's packument: `GET <registry>/create-ailk/<version>`. */
+async function fetchPackument(registryUrl, version, fetchImpl) {
+    const url = `${registryUrl.replace(/\/+$/, "")}/create-ailk/${encodeURIComponent(version)}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "GET",
+            headers: { Accept: "application/json" },
+            redirect: "error",
+            signal: fetchTimeoutSignal(),
+        });
+    }
+    catch (err) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument unreachable: ${detail(err)}`);
+    }
+    if (!response.ok) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument request failed: ${response.status}`);
+    }
+    let doc;
+    try {
+        doc = await response.json();
+    }
+    catch (err) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument is not JSON: ${detail(err)}`);
+    }
+    if (typeof doc !== "object" || doc === null) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument is not an object`);
+    }
+    const record = doc;
+    if (record["version"] !== version) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument names a different version: ${JSON.stringify(record["version"])}`);
+    }
+    const dist = record["dist"];
+    if (typeof dist !== "object" || dist === null) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument has no "dist"`);
+    }
+    const distRecord = dist;
+    const tarball = distRecord["tarball"];
+    if (typeof tarball !== "string" || tarball.length === 0) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument has no "dist.tarball"`);
+    }
+    const integrity = distRecord["integrity"];
+    if (typeof integrity !== "string" || !integrity.startsWith("sha512-")) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} packument has no "dist.integrity" starting "sha512-"`);
+    }
+    return { version, tarball, integrity };
+}
+async function fetchTarball(tarballUrl, integrity, version, fetchImpl) {
+    assertHttpsRegistryUrl(tarballUrl, FetchTemplateSnapshotError);
+    let response;
+    try {
+        response = await fetchImpl(tarballUrl, {
+            method: "GET",
+            headers: { Accept: "application/octet-stream" },
+            redirect: "error",
+            signal: fetchTimeoutSignal(),
+        });
+    }
+    catch (err) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} tarball unreachable: ${detail(err)}`);
+    }
+    if (!response.ok) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} tarball request failed: ${response.status}`);
+    }
+    assertContentLengthWithinLimit(response, FetchTemplateSnapshotError);
+    const buf = Buffer.from(await response.arrayBuffer());
+    const digest = `sha512-${createHash("sha512").update(buf).digest("base64")}`;
+    if (digest !== integrity) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} tarball failed its integrity check`);
+    }
+    return buf;
+}
+/** The app-relative path (no `package/templates/` prefix) for a tar entry path, or undefined outside the three app trees. */
+function appRelativePath(tarPath) {
+    if (!tarPath.startsWith(TAR_ROOT))
+        return undefined;
+    const rel = tarPath.slice(TAR_ROOT.length);
+    if (!APP_PREFIXES.some((prefix) => rel.startsWith(prefix)))
+        return undefined;
+    if (rel.length === 0)
+        return undefined;
+    const segments = rel.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        return undefined;
+    }
+    return rel;
+}
+/**
+ * Parse the gunzipped tar in memory and return every regular file under the
+ * three app trees, keyed by its destination path (D3's `templateDestination`
+ * — `_gitignore` restored to `.gitignore`, `.gitkeep` / `.npmignore` dropped).
+ * A symlink or hard link under one of those prefixes refuses the WHOLE
+ * snapshot, never just that entry.
+ */
+function parseSnapshot(gunzipped, version) {
+    const files = new Map();
+    let refusal;
+    const parser = new tar.Parser({
+        strict: true,
+        filter: (tarPath, rawEntry) => {
+            if (refusal !== undefined)
+                return false;
+            const rel = appRelativePath(tarPath);
+            if (rel === undefined)
+                return false;
+            const entryType = rawEntry.type;
+            if (entryType === "SymbolicLink" || entryType === "Link") {
+                refusal = `create-ailk ${version} snapshot: "${tarPath}" is a ${entryType} (refused)`;
+                return false;
+            }
+            return entryType === "File";
+        },
+        onReadEntry: (entry) => {
+            const rel = appRelativePath(entry.path);
+            const dest = rel !== undefined ? templateDestination(rel) : undefined;
+            if (dest === undefined) {
+                entry.resume();
+                return;
+            }
+            const chunks = [];
+            entry.on("data", (chunk) => chunks.push(chunk));
+            entry.on("end", () => files.set(dest, Buffer.concat(chunks)));
+        },
+    });
+    return new Promise((resolvePromise, rejectPromise) => {
+        parser.on("error", (err) => rejectPromise(err));
+        parser.on("end", () => {
+            if (refusal !== undefined) {
+                rejectPromise(new FetchTemplateSnapshotError(refusal));
+                return;
+            }
+            resolvePromise(files);
+        });
+        parser.end(gunzipped);
+    });
+}
+/**
+ * Fetch and re-materialise create-ailk `version`'s `templates/apps/{web,api,mcp}/`
+ * tree from its published npm tarball.
+ *
+ * @throws FetchTemplateSnapshotError on an invalid version, an unreachable
+ *   or malformed registry response, an integrity mismatch, or a symlink /
+ *   hard-link entry under one of the three app prefixes.
+ */
+export async function fetchTemplateSnapshot(options) {
+    const { version } = options;
+    if (!VERSION_PATTERN.test(version)) {
+        throw new FetchTemplateSnapshotError(`refusing to fetch create-ailk "${version}": not a valid version`);
+    }
+    const registryUrl = options.registryUrl ??
+        process.env["AILK_NPM_REGISTRY_URL"] ??
+        DEFAULT_AILK_NPM_REGISTRY_URL;
+    assertHttpsRegistryUrl(registryUrl, FetchTemplateSnapshotError);
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const packument = await fetchPackument(registryUrl, version, fetchImpl);
+    const tarball = await fetchTarball(packument.tarball, packument.integrity, version, fetchImpl);
+    let gunzipped;
+    try {
+        gunzipped = gunzipSync(tarball, { maxOutputLength: MAX_TOTAL_SIZE_BYTES });
+    }
+    catch (err) {
+        throw new FetchTemplateSnapshotError(`create-ailk ${version} tarball could not be decompressed: ${detail(err)}`);
+    }
+    return parseSnapshot(gunzipped, version);
+}

package/dist/lib/merge-three-way.d.ts

@@ -0,0 +1,31 @@
+export interface MergeThreeWayOptions {
+    /** The site's current (edited) text. */
+    ours: string;
+    /** The recorded version's rendered copy. */
+    base: string;
+    /** The running version's rendered copy. */
+    theirs: string;
+    oursLabel: string;
+    baseLabel: string;
+    theirsLabel: string;
+}
+export type MergeThreeWayResult = {
+    status: "merged";
+    text: string;
+} | {
+    status: "conflict";
+} | {
+    status: "error";
+    reason: string;
+};
+/**
+ * Run `git merge-file -p` over the three texts in a `mkdtemp` directory, no
+ * shell, argv holding only temp-file paths and the three labels (#8522 D5).
+ *
+ * Exit 0 is a clean merge (`merged`). Exit 1-127 is a conflicting hunk
+ * (`conflict`) — the file is never written with conflict markers by this
+ * function; the caller decides what to do with a conflict, and nothing here
+ * ever applies one. Any other exit, or a spawn failure (no `git` on `PATH`),
+ * is `error`.
+ */
+export declare function mergeThreeWay(opts: MergeThreeWayOptions): MergeThreeWayResult;

package/dist/lib/merge-three-way.js

@@ -0,0 +1,65 @@
+/**
+ * `git merge-file` wrapper — the three-way text merge `create-ailk update`
+ * runs for a copied app file the site owner edited and the template also
+ * changed (#8522 D5).
+ *
+ * `git merge-file` is the reference diff3 merge: every AILK owner already
+ * has `git` on `PATH` (it is how they cloned or will push this site), and
+ * using it adds no new npm dependency. The three versions are written to a
+ * fresh temp directory (never the site's own tree) and read back as text;
+ * nothing is left behind.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Run `git merge-file -p` over the three texts in a `mkdtemp` directory, no
+ * shell, argv holding only temp-file paths and the three labels (#8522 D5).
+ *
+ * Exit 0 is a clean merge (`merged`). Exit 1-127 is a conflicting hunk
+ * (`conflict`) — the file is never written with conflict markers by this
+ * function; the caller decides what to do with a conflict, and nothing here
+ * ever applies one. Any other exit, or a spawn failure (no `git` on `PATH`),
+ * is `error`.
+ */
+export function mergeThreeWay(opts) {
+    const dir = mkdtempSync(join(tmpdir(), "ailk-merge-"));
+    try {
+        const oursPath = join(dir, "ours");
+        const basePath = join(dir, "base");
+        const theirsPath = join(dir, "theirs");
+        writeFileSync(oursPath, opts.ours);
+        writeFileSync(basePath, opts.base);
+        writeFileSync(theirsPath, opts.theirs);
+        const result = spawnSync("git", [
+            "merge-file",
+            "-p",
+            "-L",
+            opts.oursLabel,
+            "-L",
+            opts.baseLabel,
+            "-L",
+            opts.theirsLabel,
+            oursPath,
+            basePath,
+            theirsPath,
+        ], { shell: false });
+        if (result.error !== undefined) {
+            return { status: "error", reason: result.error.message };
+        }
+        if (result.status === 0) {
+            return { status: "merged", text: result.stdout.toString("utf8") };
+        }
+        if (result.status !== null && result.status >= 1 && result.status <= 127) {
+            return { status: "conflict" };
+        }
+        return {
+            status: "error",
+            reason: `git merge-file exited ${result.status ?? `signal ${result.signal}`}`,
+        };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}