create-ailk 0.19.1 → 0.21.0

package/dist/update.js

@@ -0,0 +1,606 @@
+/**
+ * `create-ailk update [<target-dir>]` — bring template fixes into a site's
+ * already-copied `apps/web`, `apps/api` and `apps/mcp` code (#8522).
+ *
+ * Reads `.ailk-template-files.json` (`template-record.ts`) to tell an
+ * untouched copy from an owner's edit. An untouched file whose template
+ * copy changed is overwritten. An edited file whose template copy changed
+ * is three-way merged (`lib/merge-three-way.ts`) against its recorded
+ * version's copy — read from this package's own `templates/` when that is
+ * the running version, else re-materialised from the published npm tarball
+ * (`lib/fetch-template-snapshot.ts`) — and the running version's copy. A
+ * conflict leaves the file untouched and is listed under "Needs review". Every
+ * template test that imports a file left under review or skipped is held at
+ * the site's version with it, so a run never leaves a test newer than the
+ * code it exercises (#8704). A site with no record gets one backfilled from
+ * `.ailk-site-manifest.json`'s `patternVersion` on its first run, then
+ * updates normally. Every refusal throws before the first write.
+ *
+ * Pure module: no `import.meta.url` — the CLI supplies `templatesDir`, the
+ * `adopt.ts` / `add-route.ts` split.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError, readArchitectureHeader } from "./add-module-core.js";
+import { buildScaffoldMarkers, isExcluded, isTextFile, renderTemplateFile, templateDestination } from "./copy.js";
+import { fetchTemplateSnapshot } from "./lib/fetch-template-snapshot.js";
+import { mergeThreeWay } from "./lib/merge-three-way.js";
+import { ParseError } from "./parse-args.js";
+import { SITE_ROSTER_PATH } from "./site-roster.js";
+import { excludedRoutePaths } from "./surfaces.js";
+import { TEMPLATE_RECORD_PATH, isRecordable, parseTemplateRecord, serializeTemplateRecord, sha256Hex, } from "./template-record.js";
+import { TopologyError, isSpokeExcluded, readSpokeShape, spokeExclusions, } from "./topology.js";
+/** A refusal the CLI exits 2 on, thrown before anything is written. */
+export class UpdateRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "UpdateRefusedError";
+    }
+}
+/** `buildScaffoldMarkers`, with `CREATE_AILK_VERSION` set to the version being rendered (D3). */
+function markersForVersion(projectName, version) {
+    return { ...buildScaffoldMarkers(projectName), CREATE_AILK_VERSION: version };
+}
+const VERSION_TUPLE = /^(\d+)\.(\d+)\.(\d+)/;
+/** `true` iff semver `a` is strictly older than semver `b` (major, minor, patch, numerically). */
+function versionOlder(a, b) {
+    const ma = VERSION_TUPLE.exec(a);
+    const mb = VERSION_TUPLE.exec(b);
+    if (ma === null || mb === null)
+        return false;
+    for (let i = 1; i <= 3; i++) {
+        const na = Number(ma[i]);
+        const nb = Number(mb[i]);
+        if (na !== nb)
+            return na < nb;
+    }
+    return false;
+}
+/** Every file under `templatesDir`'s three app trees, raw bytes keyed by destination path (D3). */
+function walkLocalTemplates(templatesDir) {
+    const out = new Map();
+    for (const app of ["web", "api", "mcp"]) {
+        const root = join(templatesDir, "apps", app);
+        if (!existsSync(root))
+            continue;
+        const stack = [root];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (dir === undefined)
+                break;
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                const abs = join(dir, entry.name);
+                if (entry.isSymbolicLink())
+                    continue;
+                if (entry.isDirectory()) {
+                    stack.push(abs);
+                    continue;
+                }
+                const rel = `apps/${app}/${relativeToRoot(root, abs)}`;
+                const dest = templateDestination(rel);
+                if (dest === undefined)
+                    continue;
+                out.set(dest, readFileSync(abs));
+            }
+        }
+    }
+    return out;
+}
+/** `abs`'s path relative to `root` (both under the same app directory), `/`-separated. */
+function relativeToRoot(root, abs) {
+    return abs.slice(root.length + 1).split(sep).join("/");
+}
+/** The running or an old template version's recordable files, rendered (D3). */
+function renderSnapshot(raw, projectName, version) {
+    const markers = markersForVersion(projectName, version);
+    const out = new Map();
+    for (const [dest, bytes] of raw) {
+        if (!isRecordable(dest))
+            continue;
+        out.set(dest, renderTemplateFile(bytes, dest, {}, markers));
+    }
+    return out;
+}
+/** The root `package.json` `name`, falling back to the target's basename (D8). */
+function backfillProjectName(targetDir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(targetDir, "package.json"), "utf8"));
+        if (typeof pkg.name === "string" && pkg.name.length > 0)
+            return pkg.name;
+    }
+    catch {
+        // no readable root package.json — fall back below.
+    }
+    return targetDir.split(sep).filter(Boolean).pop() ?? targetDir;
+}
+/** The highest directory or file missing on disk on `destRel`'s chain below `apps/<app>/` (D4 rule iii). */
+function highestMissingAncestor(destRel, targetDir) {
+    const segments = destRel.split("/");
+    let current = segments.slice(0, 2).join("/");
+    for (let i = 2; i < segments.length; i++) {
+        current = `${current}/${segments[i]}`;
+        if (!existsSync(join(targetDir, ...current.split("/"))))
+            return current;
+    }
+    return undefined;
+}
+/** Whether `prefix` (or something under it) is one of `knownPaths` (D4 rule iii). */
+function containsKnownPath(prefix, knownPaths) {
+    for (const path of knownPaths) {
+        if (path === prefix || path.startsWith(`${prefix}/`))
+            return true;
+    }
+    return false;
+}
+/** A template test file: a `*.test.*` / `*.spec.*` module, or anything under `__tests__/`. */
+const TEST_FILE = /(^|\/)__tests__\/|\.(test|spec)\.[cm]?[jt]sx?$/;
+/** Module specifiers `import`/`export … from`, `import()`, `require()` and `jest.mock()` name. */
+const IMPORT_SPECIFIER = /\bfrom\s*["']([^"']+)["']|\bimport\s*["']([^"']+)["']|\b(?:import|require|jest\.mock|jest\.requireActual)\s*\(\s*["']([^"']+)["']/g;
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"];
+/**
+ * The record-style paths a relative specifier in `fromPath` can resolve to:
+ * the path as written, with each source extension, a `.js`-family suffix
+ * swapped for its TypeScript source, and as a directory's `index.*`.
+ */
+function relativeImportCandidates(fromPath, specifier) {
+    const parts = fromPath.split("/").slice(0, -1);
+    for (const segment of specifier.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..")
+            parts.pop();
+        else
+            parts.push(segment);
+    }
+    const target = parts.join("/");
+    const out = [target, ...RESOLVE_EXTENSIONS.map((ext) => `${target}${ext}`)];
+    const jsSuffix = /\.([cm]?)jsx?$/.exec(target);
+    if (jsSuffix !== null) {
+        const stem = target.slice(0, -jsSuffix[0].length);
+        out.push(`${stem}.${jsSuffix[1]}ts`, `${stem}.tsx`);
+    }
+    out.push(...RESOLVE_EXTENSIONS.map((ext) => `${target}/index${ext}`));
+    return out;
+}
+/** The files of `held` that `text`, the source of `fromPath`, imports by relative specifier. */
+function importedHeldFiles(fromPath, text, held) {
+    const out = new Set();
+    for (const match of text.matchAll(IMPORT_SPECIFIER)) {
+        const specifier = match[1] ?? match[2] ?? match[3];
+        if (specifier === undefined || !specifier.startsWith("."))
+            continue;
+        for (const candidate of relativeImportCandidates(fromPath, specifier)) {
+            if (held.has(candidate))
+                out.add(candidate);
+        }
+    }
+    return [...out];
+}
+export async function updateSite(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const version = opts.version;
+    // ── Load the record, or determine the backfill (D8) ──────────────────
+    const recordPath = join(targetDir, TEMPLATE_RECORD_PATH);
+    let record;
+    let backfillPatternVersion;
+    if (existsSync(recordPath)) {
+        try {
+            record = parseTemplateRecord(readFileSync(recordPath, "utf8"));
+        }
+        catch (err) {
+            throw new UpdateRefusedError(err.message);
+        }
+    }
+    else {
+        const manifestPath = join(targetDir, SITE_ROSTER_PATH);
+        let patternVersion;
+        if (existsSync(manifestPath)) {
+            try {
+                const doc = JSON.parse(readFileSync(manifestPath, "utf8"));
+                const value = doc["patternVersion"];
+                if (typeof value === "string" && value.length > 0)
+                    patternVersion = value;
+            }
+            catch {
+                // an unreadable manifest is the same refusal as a missing one, below.
+            }
+        }
+        if (patternVersion === undefined) {
+            throw new UpdateRefusedError(`no ${TEMPLATE_RECORD_PATH} and no "patternVersion" in ${SITE_ROSTER_PATH} to rebuild it from; run \`create-ailk adopt\` first`);
+        }
+        backfillPatternVersion = patternVersion;
+        record = { schema: 1, projectName: backfillProjectName(targetDir), files: {} };
+    }
+    // ── Refuse a downgrade before any fetch (D8) ──────────────────────────
+    const recordedVersions = backfillPatternVersion !== undefined
+        ? [backfillPatternVersion]
+        : [...new Set(Object.values(record.files).map((row) => row.version))];
+    for (const recorded of recordedVersions) {
+        if (versionOlder(version, recorded)) {
+            throw new UpdateRefusedError(`create-ailk ${version} is older than ${recorded}, already recorded in ${TEMPLATE_RECORD_PATH} — use a newer create-ailk to run update`);
+        }
+    }
+    // ── The site's scope: gated-off surfaces and spoke exclusions (D4 i/ii) ─
+    const archPath = join(targetDir, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new UpdateRefusedError(`${targetDir} has no architecture.yaml; run \`create-ailk adopt\` or \`--sync-architecture\` first`);
+    }
+    let header;
+    try {
+        header = readArchitectureHeader(readFileSync(archPath, "utf8"));
+    }
+    catch (err) {
+        if (err instanceof AddModuleRefusedError) {
+            throw new UpdateRefusedError(err.message);
+        }
+        throw err;
+    }
+    let spoke;
+    try {
+        spoke = readSpokeShape(targetDir);
+    }
+    catch (err) {
+        if (err instanceof TopologyError)
+            throw new UpdateRefusedError(err.message);
+        throw err;
+    }
+    const excludedRoutes = excludedRoutePaths(header.surfaces);
+    const spokeExclusionList = spoke !== undefined ? spokeExclusions(opts.templatesDir, spoke) : undefined;
+    const outOfScope = (destRel) => {
+        if (isExcluded(destRel, excludedRoutes))
+            return true;
+        if (spoke !== undefined && spokeExclusionList !== undefined) {
+            return isSpokeExcluded(destRel, { ...spoke, exclusions: spokeExclusionList });
+        }
+        return false;
+    };
+    // ── The running version's rendered copies ─────────────────────────────
+    const runningRaw = walkLocalTemplates(opts.templatesDir);
+    const newMap = renderSnapshot(runningRaw, record.projectName, version);
+    // ── A cache of rendered copies by version, fetched at most once each ──
+    const versionCache = new Map();
+    async function loadVersionMap(v) {
+        const cached = versionCache.get(v);
+        if (cached !== undefined)
+            return cached;
+        let result;
+        if (v === version) {
+            result = newMap;
+        }
+        else {
+            try {
+                const raw = await fetchTemplateSnapshot({
+                    version: v,
+                    ...(opts.registryUrl !== undefined ? { registryUrl: opts.registryUrl } : {}),
+                    ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+                });
+                result = renderSnapshot(raw, record.projectName, v);
+            }
+            catch (err) {
+                result = { error: err.message };
+            }
+        }
+        versionCache.set(v, result);
+        return result;
+    }
+    // ── The backfill: fetch the old base and build the synthetic record ──
+    let knownSnapshotPaths;
+    if (backfillPatternVersion !== undefined) {
+        const base = await loadVersionMap(backfillPatternVersion);
+        if ("error" in base) {
+            throw new UpdateRefusedError(`backfill: the ${backfillPatternVersion} template could not be read: ${base.error}`);
+        }
+        knownSnapshotPaths = new Set(base.keys());
+        const files = {};
+        for (const [path, bytes] of [...base.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+            if (outOfScope(path))
+                continue;
+            if (!existsSync(join(targetDir, ...path.split("/"))))
+                continue;
+            files[path] = { sha256: sha256Hex(bytes), version: backfillPatternVersion };
+        }
+        record = { schema: 1, projectName: record.projectName, files };
+    }
+    // ── Every recorded row (D4) ────────────────────────────────────────────
+    const updated = [];
+    const merged = [];
+    const added = [];
+    const removed = [];
+    const current = [];
+    const review = [];
+    const skipped = [];
+    const nextFiles = { ...record.files };
+    const writes = [];
+    const deletes = [];
+    for (const path of Object.keys(record.files).sort()) {
+        const rec = record.files[path];
+        if (outOfScope(path)) {
+            skipped.push({ path, reason: "outside this site's scope" });
+            continue;
+        }
+        const abs = join(targetDir, ...path.split("/"));
+        if (!existsSync(abs)) {
+            skipped.push({ path, reason: "deleted locally" });
+            continue;
+        }
+        const diskBytes = readFileSync(abs);
+        const diskHash = sha256Hex(diskBytes);
+        const edited = diskHash !== rec.sha256;
+        const newBytes = newMap.get(path);
+        if (!edited) {
+            if (newBytes === undefined) {
+                deletes.push(path);
+                delete nextFiles[path];
+                removed.push(path);
+                continue;
+            }
+            const newHash = sha256Hex(newBytes);
+            if (newHash === rec.sha256)
+                continue; // no template change
+            writes.push({ path, bytes: Buffer.from(newBytes) });
+            nextFiles[path] = { sha256: newHash, version };
+            updated.push(path);
+            continue;
+        }
+        // Edited.
+        if (newBytes === undefined) {
+            review.push({ path, reason: `edited here, removed from the template in ${version}` });
+            continue;
+        }
+        const newHash = sha256Hex(newBytes);
+        if (newHash === rec.sha256)
+            continue; // template unchanged for this file
+        if (diskHash === newHash) {
+            nextFiles[path] = { sha256: newHash, version };
+            current.push(path);
+            continue;
+        }
+        // Template changed, and the edit does not already match it: three-way merge.
+        const base = await loadVersionMap(rec.version);
+        if ("error" in base) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template could not be read: ${base.error}`,
+            });
+            continue;
+        }
+        const baseBytes = base.get(path);
+        if (baseBytes === undefined) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template could not be read: not present in that version's snapshot`,
+            });
+            continue;
+        }
+        if (sha256Hex(baseBytes) !== rec.sha256) {
+            review.push({
+                path,
+                reason: `edited here, and the ${rec.version} template copy does not match the record`,
+            });
+            continue;
+        }
+        if (!isTextFile(path)) {
+            review.push({ path, reason: "edited here; binary files are not merged" });
+            continue;
+        }
+        const mergeResult = mergeThreeWay({
+            ours: diskBytes.toString("utf8"),
+            base: Buffer.from(baseBytes).toString("utf8"),
+            theirs: Buffer.from(newBytes).toString("utf8"),
+            oursLabel: "yours",
+            baseLabel: `template ${rec.version}`,
+            theirsLabel: `template ${version}`,
+        });
+        if (mergeResult.status === "merged") {
+            const mergedBytes = Buffer.from(mergeResult.text, "utf8");
+            writes.push({ path, bytes: mergedBytes });
+            // D1/D5 — the row keeps the TEMPLATE's hash, never the merged disk
+            // bytes': that is what lets the next update still see the owner's
+            // edit (the disk bytes keep differing from the recorded hash) and
+            // merge against the right base, instead of reading a now-current
+            // file as "edited" against its own past self forever.
+            nextFiles[path] = { sha256: newHash, version };
+            merged.push(path);
+        }
+        else if (mergeResult.status === "conflict") {
+            review.push({
+                path,
+                reason: `conflicts with the template change ${rec.version} → ${version}`,
+            });
+        }
+        else {
+            review.push({ path, reason: `the three-way merge could not run: ${mergeResult.reason}` });
+        }
+    }
+    // ── Every recordable path the running template has that this record does not (D4) ──
+    const knownPaths = new Set([...Object.keys(record.files), ...(knownSnapshotPaths ?? [])]);
+    for (const path of [...newMap.keys()].sort()) {
+        if (Object.prototype.hasOwnProperty.call(record.files, path))
+            continue;
+        const abs = join(targetDir, ...path.split("/"));
+        const newBytes = newMap.get(path);
+        if (existsSync(abs)) {
+            const diskBytes = readFileSync(abs);
+            if (sha256Hex(diskBytes) !== sha256Hex(newBytes)) {
+                skipped.push({ path, reason: "exists, not in the record" });
+            }
+            continue;
+        }
+        if (outOfScope(path))
+            continue; // rule i/ii
+        const highest = highestMissingAncestor(path, targetDir);
+        if (highest !== undefined && containsKnownPath(highest, knownPaths))
+            continue; // rule iii
+        writes.push({ path, bytes: Buffer.from(newBytes) });
+        nextFiles[path] = { sha256: sha256Hex(newBytes), version };
+        added.push(path);
+    }
+    // ── Hold back the template tests of every file left alone (#8704) ────
+    // A test this run would move forward (update, merge, add, remove, or
+    // advance as current) that imports a file under review or skipped stays
+    // exactly as the site has it, and its row keeps its recorded version — so
+    // the tests on disk always match the code they exercise. The imports are
+    // read from both the site's copy and the running template's: either one
+    // exercising the held file is enough. A held test-support file
+    // (`__tests__/fixtures.ts`) holds the tests importing it in turn, until no
+    // further test is held.
+    const heldFiles = new Set([...review, ...skipped].map((row) => row.path));
+    const heldBackByFile = new Map();
+    const heldTests = new Set();
+    const moving = [...updated, ...merged, ...added, ...removed, ...current]
+        .filter((path) => TEST_FILE.test(path))
+        .sort();
+    for (let grew = heldFiles.size > 0; grew;) {
+        grew = false;
+        for (const path of moving) {
+            if (heldTests.has(path))
+                continue;
+            const sources = [];
+            const abs = join(targetDir, ...path.split("/"));
+            if (existsSync(abs))
+                sources.push(readFileSync(abs, "utf8"));
+            const newBytes = newMap.get(path);
+            if (newBytes !== undefined)
+                sources.push(Buffer.from(newBytes).toString("utf8"));
+            const imported = new Set(sources.flatMap((text) => importedHeldFiles(path, text, heldFiles)));
+            if (imported.size === 0)
+                continue;
+            heldTests.add(path);
+            heldFiles.add(path);
+            grew = true;
+            for (const file of imported) {
+                heldBackByFile.set(file, [...(heldBackByFile.get(file) ?? []), path]);
+            }
+        }
+    }
+    for (const path of heldTests) {
+        const recorded = record.files[path];
+        if (recorded !== undefined)
+            nextFiles[path] = recorded;
+        else
+            delete nextFiles[path];
+    }
+    const notHeld = (path) => !heldTests.has(path);
+    const heldBack = [...heldBackByFile.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([file, tests]) => ({ file, tests }));
+    // ── Apply: writes and removals, then the record (D4 Order) ───────────
+    for (const write of writes.filter((w) => notHeld(w.path))) {
+        const abs = join(targetDir, ...write.path.split("/"));
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, write.bytes);
+    }
+    for (const path of deletes.filter(notHeld)) {
+        rmSync(join(targetDir, ...path.split("/")));
+    }
+    const backfilled = backfillPatternVersion !== undefined
+        ? { version: backfillPatternVersion, files: Object.keys(record.files).length }
+        : undefined;
+    const moved = {
+        updated: updated.filter(notHeld),
+        merged: merged.filter(notHeld),
+        added: added.filter(notHeld),
+        removed: removed.filter(notHeld),
+        current: current.filter(notHeld),
+    };
+    const recordChanged = backfilled !== undefined || Object.values(moved).some((paths) => paths.length > 0);
+    if (recordChanged) {
+        writeFileSync(recordPath, serializeTemplateRecord({ schema: 1, projectName: record.projectName, files: nextFiles }));
+    }
+    return {
+        targetDir,
+        version,
+        ...moved,
+        review,
+        skipped,
+        heldBack,
+        ...(backfilled !== undefined ? { backfilled } : {}),
+    };
+}
+/** The printed report (D9): one section per non-empty list, in order. */
+export function formatUpdateReport(result) {
+    const lines = [`[create-ailk] update → ${result.targetDir}`];
+    if (result.backfilled !== undefined) {
+        lines.push(`Record written from ${result.backfilled.version}: ${result.backfilled.files} files`);
+    }
+    const sections = [
+        ["Updated", result.updated],
+        ["Merged", result.merged],
+        ["Added", result.added],
+        ["Removed", result.removed],
+        ["Already current", result.current],
+    ];
+    for (const [label, paths] of sections) {
+        if (paths.length === 0)
+            continue;
+        lines.push(`${label} (${paths.length}):`);
+        lines.push(...paths.map((path) => `  ${path}`));
+    }
+    if (result.review.length > 0) {
+        lines.push(`Needs review (${result.review.length}):`);
+        lines.push(...result.review.map((row) => `  ${row.path} — ${row.reason}`));
+    }
+    for (const { file, tests } of result.heldBack) {
+        lines.push(`Held back with ${file} (${tests.length}):`);
+        lines.push(...tests.map((path) => `  ${path}`));
+    }
+    if (result.skipped.length > 0) {
+        lines.push(`Skipped (${result.skipped.length}):`);
+        lines.push(...result.skipped.map((row) => `  ${row.path} — ${row.reason}`));
+    }
+    const nothingHappened = result.backfilled === undefined &&
+        result.updated.length === 0 &&
+        result.merged.length === 0 &&
+        result.added.length === 0 &&
+        result.removed.length === 0 &&
+        result.current.length === 0 &&
+        result.review.length === 0 &&
+        result.skipped.length === 0;
+    if (nothingHappened) {
+        return `[create-ailk] Already up to date (create-ailk ${result.version}).\n`;
+    }
+    return lines.join("\n") + "\n";
+}
+export const UPDATE_HELP = `create-ailk update — bring template fixes into a site's copied app code.
+
+Usage:
+  create-ailk update [<target-dir>]
+
+Arguments:
+  <target-dir>             The existing site. Defaults to the current dir.
+
+Options:
+  --help, -h               Print this message.
+
+Reads .ailk-template-files.json (written beside .ailk-site-manifest.json by
+every template scaffold) to tell an untouched copy from an edit. An
+untouched apps/web, apps/api or apps/mcp file whose template copy changed is
+overwritten. An edited file whose template copy also changed is three-way
+merged with \`git\` (git must be on PATH); a conflict leaves the file alone
+and is listed under "Needs review". Every template test that imports a file
+left under "Needs review" or "Skipped" (by a relative import) is held at the
+site's version with it, its record entry is not advanced, and it is listed
+under "Held back with <file>" — reconcile the file, then run update again to
+bring its tests forward. Every other file in the run still updates.
+A site with no record gets one on its first run, from the version its
+.ailk-site-manifest.json already records. Commit before running, and review
+the diff after.
+`;
+/** Parse the argv AFTER the `update` word. Strict `node:util` parseArgs, like `parseAdoptArgs`. */
+export function parseUpdateArgs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        strict: true,
+        allowPositionals: true,
+        options: {
+            help: { type: "boolean", default: false, short: "h" },
+        },
+    });
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`update takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return { target, help: parsed.values.help === true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.40.0",
-    "@working-theory/templates": "0.40.0"
+    "@working-theory/schema": "0.42.0",
+    "@working-theory/templates": "0.42.0"
   },
   "repository": {
     "type": "git",

package/site-templates/_base/ailk-template.json

@@ -1,6 +1,6 @@
 {
   "name": "_base",
   "requires": [],
-  "$comment": "The BASE LAYER (#5618 D1) — not a template. Every declared template reaches this tree by `extends: \"_base\"`; scaffold() installs it through installBundleTree before any module bundle and before the template's own tree, only when --template is named. It carries the seed content every template brings itself and no module owns: /pricing, /privacy and /terms (spec 5462 D16). No installMap: every file here is unmapped and lands at its own path under the scaffold root's content/, so a template overrides a base page by shipping the same path. Never published as a registry bundle; the leading underscore is the skip signal for the bundle producer and the site-templates/ directory scans.",
-  "postInstall": "Base layer installed: seed copy for /pricing, /privacy and /terms is in content/en/ - replace the placeholder copy before you launch."
+  "$comment": "The BASE LAYER (#5618 D1) — not a template. Every declared template reaches this tree by `extends: \"_base\"`; scaffold() installs it through installBundleTree before any module bundle and before the template's own tree, only when --template is named. It carries the seed content every template brings itself and no module owns: /pricing, /privacy, /terms (spec 5462 D16) and /working-agreement (#8661 D10). No installMap: every file here is unmapped and lands at its own path under the scaffold root's content/, so a template overrides a base page by shipping the same path. Never published as a registry bundle; the leading underscore is the skip signal for the bundle producer and the site-templates/ directory scans.",
+  "postInstall": "Base layer installed: seed copy for /pricing, /privacy, /terms and /working-agreement is in content/en/ - replace the placeholder copy before you launch."
 }