create-ailk 0.19.1 → 0.20.0

package/README.md

@@ -262,6 +262,62 @@ the route-surface registry in the same file.
 `ROUTE_SINCE` entry — `__tests__/sync-routes.test.ts` fails otherwise (and it
 fails on a stale entry for a route the template no longer ships).
 
+### Update the copied app code
+
+A fresh scaffold records every `apps/web`, `apps/api` and `apps/mcp` file the
+base template copy wrote — and no later layer (a module bundle's patch, a
+generator) rewrote — in `.ailk-template-files.json`, beside
+`.ailk-site-manifest.json`: each file's content hash and the create-ailk
+version it came from. `update` reads that record to bring a template fix
+into a site that already exists, instead of a per-site porting issue:
+
+```bash
+create-ailk update ./my-site
+```
+
+For each recorded file, `update` compares the site's current bytes to the
+recorded hash:
+
+- **Untouched** (the bytes still match the record) and the running
+  version's copy differs: the file is overwritten, and the record's hash
+  and version move forward. Reported as **Updated**.
+- **Untouched** and the running version's copy is gone: the file is
+  deleted and dropped from the record. Reported as **Removed**.
+- **Edited** (the bytes differ from the record) and the running version's
+  copy also changed: the two changes are three-way merged with `git
+merge-file` against the recorded version's own copy as the base. A clean
+  merge keeps your edit AND the fix, and is reported as **Merged**. A
+  conflict leaves the file exactly as it was — never written with conflict
+  markers — and is reported under **Needs review** with both versions
+  named; nothing else in the run is held back by it.
+- A recordable file the running version adds that the site lacks is
+  **Added**, unless it sits under a route or directory the site deliberately
+  does not carry (a gated-off surface, a spoke exclusion, or a directory you
+  deleted entirely) — those are left alone.
+
+A file outside the gated-off surfaces and spoke exclusions the site's scope
+no longer covers is **Skipped**, as is one that exists on disk but was never
+recorded (a module bundle's own file, say) when its bytes differ from the
+running copy. Nothing the base scaffold did not write is ever touched. No
+template change at all means `Already up to date` and zero files written.
+
+**A site scaffolded before this record existed** gets one built on its first
+`update` run, from the `patternVersion` `.ailk-site-manifest.json` already
+records — no separate command, no per-site setup. If that version predates
+the site's actual files (an adopted site, or one whose `patternVersion` was
+bumped by hand per "Keeping a spoke current" below), a file `update` cannot
+tell was edited may show up under Needs review even though you never touched
+it; the merge itself still never loses content.
+
+**Requirements.** `git` must be on `PATH` — the merge runs `git merge-file`,
+never a shell. Fetching an old template version (when it is not the running
+package's own) reads the public npm registry at
+`https://registry.npmjs.org`, overridable with `AILK_NPM_REGISTRY_URL` for a
+mirror. `update` never touches content, env files, `.claude/`, lockfiles or
+any `package.json` — those stay `add-module`'s and the consumer version
+bump's job. Commit before running `update`, and review the diff after: a
+clean merge is still worth reading.
+
 ### Adopting an existing site
 
 A site that create-ailk did not scaffold, or that was scaffolded before
@@ -311,13 +367,14 @@ included). A second run is refused with exit 2 and the manifest untouched.
 
 ### Keeping a spoke current
 
-A spoke's scaffold-written files are few: the generated seams, the
-declared-env check (`tools/declared-env.ts`, `tools/check-declared-env.ts`)
-and the one-line route re-exports; everything else is content, or code that arrives
-through a `@working-theory/*` package bump. create-ailk does not re-scaffold a
-site in place, and there is no re-sync command: `add-module` never overwrites
-an edited file, so a re-sync could only report. Moving a spoke to a new
-create-ailk version is a per-version review instead:
+`create-ailk update` (above) brings the copied `apps/web`, `apps/api` and
+`apps/mcp` code forward on its own. What it leaves alone still needs a
+per-version review: the generated seams, the declared-env check
+(`tools/declared-env.ts`, `tools/check-declared-env.ts`) and the one-line
+route re-exports are regenerated, not recorded, so `update` never touches
+them; everything else is content, or code that arrives through a
+`@working-theory/*` package bump. Moving a spoke to a new create-ailk
+version still means:
 
 1. **Read the changesets.** A create-ailk changeset that changes what
    create-ailk writes into a scaffold-written spoke file names each such file

package/dist/cli.js

@@ -19,6 +19,9 @@
  *      to a linked Vercel project and redeploy, exit (#6683 D9)
  *      on an `apply-design` subcommand: rewrite an existing site's look,
  *      print the changed-file report, exit (#6819)
+ *      on an `update` subcommand: bring template fixes into a site's
+ *      already-copied apps/web, apps/api and apps/mcp code, print the
+ *      per-file report, exit (2 on a refusal it names) (#8522)
  *   1. parse argv → CliOptions
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
@@ -58,6 +61,7 @@ import { addModule, formatSurfaceDrift, scaffold, syncArchitectureSync, syncCata
 import { SEED_FLOWS_HELP, SeedFlowsRefusedError, parseSeedFlowsArgs, seedFlows, } from "./seed-flows.js";
 import { CORE_SURFACE_PATHS, SURFACE_ALIASES } from "./surfaces.js";
 import { SYNC_ROUTES_HELP, formatSyncRoutesReport, parseSyncRoutesArgs, } from "./sync-routes.js";
+import { UPDATE_HELP, UpdateRefusedError, formatUpdateReport, parseUpdateArgs, updateSite, } from "./update.js";
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const PKG_JSON = resolve(PKG_ROOT, "package.json");
 function readPackageVersion() {
@@ -272,6 +276,35 @@ async function main() {
         process.stdout.write(formatApplyDesignReport(result));
         process.exit(0);
     }
+    // `update [<target-dir>]` (#8522): bring template fixes into a site's
+    // already-copied apps/web, apps/api and apps/mcp code. A refusal it names
+    // (no record and no patternVersion, an unparseable record, a downgrade, an
+    // unreadable architecture.yaml or manifest topology, a backfill whose
+    // fetch fails) exits 2 before anything is written. A clean run exits 0
+    // even when it lists files under "Needs review" — the review list is the
+    // hand-off, not a failure.
+    if (argv[0] === "update") {
+        const args = parseUpdateArgs(argv.slice(1));
+        if (args.help) {
+            process.stdout.write(UPDATE_HELP);
+            process.exit(0);
+        }
+        try {
+            const result = await updateSite({
+                targetDir: args.target ?? process.cwd(),
+                templatesDir: resolve(PKG_ROOT, "templates"),
+                version: readPackageVersion(),
+            });
+            process.stdout.write(formatUpdateReport(result));
+        }
+        catch (err) {
+            if (!(err instanceof UpdateRefusedError))
+                throw err;
+            process.stderr.write(`[create-ailk] ${err.message}\n`);
+            process.exit(err.exitCode);
+        }
+        process.exit(0);
+    }
     // No silent default (#6754 D2/D3): a scaffold run naming neither --shape
     // nor --template asks for a shape on a terminal and is refused without one.
     // A --design or --modules outside the release scope is refused before that
@@ -317,6 +350,8 @@ async function main() {
             "\n" +
             APPLY_DESIGN_HELP +
             "\n" +
+            UPDATE_HELP +
+            "\n" +
             LICENSE_SET_HELP);
         process.exit(0);
     }

package/dist/copy.d.ts

@@ -19,11 +19,52 @@ export interface CopyTemplateOptions {
      * `.../services` never excludes a sibling `.../services-extra`.
      */
     excludePaths?: string[];
+    /**
+     * Called once per file actually written, with its `/`-separated
+     * destination path (relative to `targetDir`) and the exact bytes written
+     * (#8522 D2) — `create-ailk update`'s per-file record is built from these
+     * calls. No existing caller passes this, so their behaviour is unchanged.
+     */
+    onWrite?: (relPath: string, bytes: Uint8Array) => void;
 }
+/**
+ * Whether a walked template-relative path is inside (or equal to) an excluded
+ * directory. Compares `/`-normalized paths so the check holds on Windows, and
+ * only at a directory boundary — a prefix that stops mid-segment is no match.
+ * Exported (#8522 D3) so `create-ailk update` applies the same surface-gating
+ * boundary to a candidate new file.
+ */
+export declare function isExcluded(relativePath: string, excluded: readonly string[]): boolean;
+/**
+ * The pack-safe name `build-templates.mjs` ships each snapshot `.gitignore`
+ * under (#7366 D1) — npm and pnpm strip a file literally named `.gitignore`
+ * from a packed tarball, but keep one named `_gitignore`. One definition,
+ * imported by `build-templates.mjs` (from the compiled `dist/copy.js`) and
+ * by `copyTemplate` below, so the two can never spell it differently.
+ */
+export declare const PACKED_GITIGNORE_NAME = "_gitignore";
 /**
  * Whether a scaffolded path's content is text we run markers over. Exported
  * because the template/base layer (`installBundleTree`) substitutes with the
  * same classifier — one definition, not two (#6460).
  */
 export declare function isTextFile(relativePath: string): boolean;
+/**
+ * The destination path a template-relative path (`/`-separated) copies to —
+ * `undefined` for a packaging-only `.gitkeep` or `.npmignore` (never a
+ * scaffold file), and a final `PACKED_GITIGNORE_NAME` restored to
+ * `.gitignore` in the same directory otherwise (#7366 D3) — so a scaffold
+ * never carries the packaging-only name. Exported (#8522 D3) as the one
+ * renderer of "the template's copy", shared by `copyTemplate` and by
+ * `create-ailk update`'s render of a running or an old template version.
+ */
+export declare function templateDestination(rel: string): string | undefined;
+/**
+ * The bytes a template-relative file copies as, at its destination path
+ * (#8522 D3): workspace versions plus markers for `package.json`, markers
+ * for `isTextFile`, raw bytes otherwise. Exported so `copyTemplate`'s walk
+ * and `create-ailk update`'s render of a running or an old template version
+ * share the one renderer — nothing about the copy itself changes.
+ */
+export declare function renderTemplateFile(bytes: Uint8Array, destRel: string, versions: WorkspaceVersionMap, markers: MarkerMap): Uint8Array;
 export declare function copyTemplate(opts: CopyTemplateOptions): void;

package/dist/copy.js

@@ -17,8 +17,23 @@
  *     alike. Symlinks are skipped outright (never followed, never copied) —
  *     the snapshotted templates/ tree is built without symlinks; any symlink
  *     present at scaffold time is treated as a packaging accident and ignored.
+ *
+ * Packed ignore files (#7366):
+ *   - npm and pnpm strip every file literally named `.gitignore` from a
+ *     packed tarball, so `build-templates.mjs` ships each snapshot
+ *     `.gitignore` under `PACKED_GITIGNORE_NAME` (`_gitignore`) instead. A
+ *     file named `PACKED_GITIGNORE_NAME` is restored to `.gitignore` in the
+ *     same directory on the way into a scaffold, classified and
+ *     marker-substituted exactly as a `.gitignore` is today (its destination
+ *     relative path, not its source name, drives `isTextFile`). A directory
+ *     carrying both `.gitignore` and `PACKED_GITIGNORE_NAME` is refused
+ *     outright, before either is written, rather than resolved by
+ *     `readdir()` order. `.npmignore` — the packaging-only sibling
+ *     `build-templates.mjs` writes beside each `PACKED_GITIGNORE_NAME` to
+ *     keep pack-time exclusions working — is skipped like `.gitkeep`: it
+ *     never belongs in a scaffold.
  */
-import { copyFileSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { extname, join, relative, resolve, sep } from "node:path";
 import pkg from "../package.json" with { type: "json" };
 import { substituteMarkers, substituteWorkspaceVersions, } from "./substitute.js";
@@ -57,8 +72,10 @@ export function buildScaffoldMarkers(projectName) {
  * Whether a walked template-relative path is inside (or equal to) an excluded
  * directory. Compares `/`-normalized paths so the check holds on Windows, and
  * only at a directory boundary — a prefix that stops mid-segment is no match.
+ * Exported (#8522 D3) so `create-ailk update` applies the same surface-gating
+ * boundary to a candidate new file.
  */
-function isExcluded(relativePath, excluded) {
+export function isExcluded(relativePath, excluded) {
     if (excluded.length === 0)
         return false;
     const rel = relativePath.split(sep).join("/");
@@ -71,6 +88,14 @@ function isExcluded(relativePath, excluded) {
     }
     return false;
 }
+/**
+ * The pack-safe name `build-templates.mjs` ships each snapshot `.gitignore`
+ * under (#7366 D1) — npm and pnpm strip a file literally named `.gitignore`
+ * from a packed tarball, but keep one named `_gitignore`. One definition,
+ * imported by `build-templates.mjs` (from the compiled `dist/copy.js`) and
+ * by `copyTemplate` below, so the two can never spell it differently.
+ */
+export const PACKED_GITIGNORE_NAME = "_gitignore";
 /** File extensions whose content we treat as text (and run markers over). */
 const TEXT_EXTS = new Set([
     ".md",
@@ -113,6 +138,46 @@ function isPackageJson(relativePath) {
     const base = relativePath.split(/[\\/]/).pop() ?? "";
     return base === "package.json";
 }
+/**
+ * The destination path a template-relative path (`/`-separated) copies to —
+ * `undefined` for a packaging-only `.gitkeep` or `.npmignore` (never a
+ * scaffold file), and a final `PACKED_GITIGNORE_NAME` restored to
+ * `.gitignore` in the same directory otherwise (#7366 D3) — so a scaffold
+ * never carries the packaging-only name. Exported (#8522 D3) as the one
+ * renderer of "the template's copy", shared by `copyTemplate` and by
+ * `create-ailk update`'s render of a running or an old template version.
+ */
+export function templateDestination(rel) {
+    const parts = rel.split("/");
+    const last = parts.length - 1;
+    if (last < 0)
+        return undefined;
+    if (parts[last] === ".gitkeep" || parts[last] === ".npmignore") {
+        return undefined;
+    }
+    if (parts[last] === PACKED_GITIGNORE_NAME) {
+        parts[last] = ".gitignore";
+    }
+    return parts.join("/");
+}
+/**
+ * The bytes a template-relative file copies as, at its destination path
+ * (#8522 D3): workspace versions plus markers for `package.json`, markers
+ * for `isTextFile`, raw bytes otherwise. Exported so `copyTemplate`'s walk
+ * and `create-ailk update`'s render of a running or an old template version
+ * share the one renderer — nothing about the copy itself changes.
+ */
+export function renderTemplateFile(bytes, destRel, versions, markers) {
+    if (isPackageJson(destRel)) {
+        const text = Buffer.from(bytes).toString("utf8");
+        return Buffer.from(substituteMarkers(substituteWorkspaceVersions(text, versions), markers), "utf8");
+    }
+    if (isTextFile(destRel)) {
+        const text = Buffer.from(bytes).toString("utf8");
+        return Buffer.from(substituteMarkers(text, markers), "utf8");
+    }
+    return Buffer.from(bytes);
+}
 export function copyTemplate(opts) {
     const templatesAbs = resolve(opts.templatesDir);
     const targetAbs = resolve(opts.targetDir);
@@ -124,19 +189,30 @@ export function copyTemplate(opts) {
         if (dir === undefined)
             break;
         const entries = readdirSync(dir, { withFileTypes: true });
+        // A directory carrying both the live name and the packed name would
+        // otherwise resolve by `readdir()` order — refuse outright, before
+        // writing either (#7366 D3).
+        const names = new Set(entries.map((entry) => entry.name));
+        if (names.has(".gitignore") && names.has(PACKED_GITIGNORE_NAME)) {
+            throw new Error(`templates directory carries both .gitignore and ${PACKED_GITIGNORE_NAME}: ${dir}`);
+        }
         for (const entry of entries) {
-            // .gitkeep is a packaging artifact for the empty-templates state in git;
-            // never propagate it to scaffolder output.
-            if (entry.name === ".gitkeep")
-                continue;
             const srcPath = join(dir, entry.name);
-            const rel = relative(templatesAbs, srcPath);
+            const rel = relative(templatesAbs, srcPath).split(sep).join("/");
             // Surface gating (#4154): a route directory belonging to a surface the
             // declared architecture does not carry is skipped outright — the route is
             // ABSENT from the scaffold, not present-and-serving-a-placeholder.
             if (isExcluded(rel, excluded))
                 continue;
-            const dstPath = join(targetAbs, rel);
+            // The destination path: `undefined` drops a packaging-only .gitkeep /
+            // .npmignore (#7366 D3); otherwise a packed .gitignore's name is
+            // restored. Everything below — the path-safety check, text
+            // classification, and marker substitution — runs on THIS path, never
+            // the source name.
+            const destRel = templateDestination(rel);
+            if (destRel === undefined)
+                continue;
+            const dstPath = join(targetAbs, destRel);
             // Path-safety guard: dstPath MUST be within targetAbs. Use `path.sep`
             // so the check holds on Windows (`\\`) as well as POSIX (`/`).
             const resolvedDst = resolve(dstPath);
@@ -152,19 +228,9 @@ export function copyTemplate(opts) {
                 stack.push(srcPath);
                 continue;
             }
-            if (isPackageJson(rel)) {
-                const text = readFileSync(srcPath, "utf8");
-                const transformed = substituteMarkers(substituteWorkspaceVersions(text, opts.versions), opts.markers);
-                writeFileSync(dstPath, transformed);
-            }
-            else if (isTextFile(rel)) {
-                const text = readFileSync(srcPath, "utf8");
-                writeFileSync(dstPath, substituteMarkers(text, opts.markers));
-            }
-            else {
-                // Binary or unknown — copy verbatim.
-                copyFileSync(srcPath, dstPath);
-            }
+            const rendered = renderTemplateFile(readFileSync(srcPath), destRel, opts.versions, opts.markers);
+            writeFileSync(dstPath, rendered);
+            opts.onWrite?.(destRel, rendered);
         }
     }
 }

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;