create-ailk 0.2.0 → 0.4.0

package/dist/lib/apply-module-patches.js

@@ -0,0 +1,370 @@
+/**
+ * Applies a module bundle's declarative `patches` (spec 5418 § 3 D1) onto an
+ * already-scaffolded target — the only mechanism that edits a file the
+ * buyer's scaffold already has (`installMap`/`postInstall`, spec 5373 § D7,
+ * can only add a file or print a message). Computes every patched file in
+ * memory first; only after every target's in-memory pass succeeds does a
+ * second pass write the changed files back to disk, once (D4) — so a
+ * conflict, a missing target, or an unparseable target anywhere in the
+ * manifest's patch set leaves the scaffold exactly as `copyTree`/`installMap`
+ * left it, nothing partial.
+ *
+ * `kind` decides how a target is read and re-serialized:
+ *   - "json" — `package.json` (object-shaped fields, `merge-keys`) and
+ *     `tsconfig.json` (array-shaped, `append-unique`). Parsed with
+ *     `JSON.parse`, mutated in place, re-serialized with
+ *     `JSON.stringify(obj, null, 2) + "\n"` (D2). A `package.json` target
+ *     then runs through `substituteWorkspaceVersions`, mirroring
+ *     `copy.ts`'s `isPackageJson` branch for a freshly-copied file.
+ *   - "next-config" / "jest-config" — treated as text, never parsed or
+ *     evaluated (NFR1 — no AST dependency). Each op is one of five named,
+ *     idempotent, anchored transforms (D3): checked "already applied" →
+ *     "anchor found, apply" → "not found, unparseable" — never a
+ *     best-effort splice.
+ *
+ * Every failure mode here is one of D4's classes 1-3 (conflict, missing
+ * target, unparseable target). Class 4 (unknown kind/op) is caught earlier,
+ * at manifest validation (D6, `extract-module-bundle.ts`), before this
+ * function is ever called — every op here is assumed to be a recognized
+ * vocabulary member for its patch's `kind`.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { substituteWorkspaceVersions, } from "../substitute.js";
+/** D4 class 1 — a merge-keys key, or a JS-config anchor's already-applied value, disagrees. */
+function conflict(target, locator, existing, wanted) {
+    return new Error(`patch conflict in ${target}: "${locator}" is ${JSON.stringify(existing)}, module wants ${JSON.stringify(wanted)}`);
+}
+/** D4 class 2 — `resolve(targetDir, target)` does not exist on disk. */
+function missingTarget(target) {
+    return new Error(`patch target missing: ${target} does not exist in this scaffold`);
+}
+/** D4 class 3 — a json target fails JSON.parse. */
+function unparseableJson(target) {
+    return new Error(`patch target unparseable: ${target} is not valid JSON`);
+}
+/** D4 class 3 — a next-config/jest-config anchor (or a JSON `path`) cannot be located at all. */
+function unparseableAnchor(target, anchor) {
+    return new Error(`patch target unparseable: ${target} — could not locate "${anchor}"`);
+}
+/**
+ * Navigate `path` into `root`, requiring every intermediate segment to
+ * already resolve to a plain object. Returns the immediate parent + final
+ * key, or `null` if any intermediate segment is missing / not an object —
+ * the caller decides what "the final key's own container is missing or the
+ * wrong shape" means for its own op (D2: never create structure the buyer
+ * never had; a missing/wrong-shape container is `unparseableAnchor`, the
+ * same disposition the "if under-specified" resolution gives `merge-keys`
+ * and, by symmetry, `append-unique`).
+ */
+function resolvePathParent(root, path) {
+    let cur = root;
+    for (let i = 0; i < path.length - 1; i++) {
+        const seg = path[i];
+        if (typeof cur !== "object" ||
+            cur === null ||
+            Array.isArray(cur) ||
+            !Object.prototype.hasOwnProperty.call(cur, seg)) {
+            return null;
+        }
+        cur = cur[seg];
+    }
+    if (typeof cur !== "object" || cur === null || Array.isArray(cur))
+        return null;
+    return { parent: cur, key: path[path.length - 1] };
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Resolve `workspace:*` to the concrete published semver BEFORE the
+ * merge-keys comparison/write, not only at final text-level serialization
+ * (D2 mirrors `copy.ts`'s `isPackageJson` branch, but that branch runs on a
+ * FRESHLY-COPIED file that never gets re-read; a patch target does — a
+ * second `applyModulePatches` run reads back the ALREADY-substituted `^x.y.z`
+ * value, so comparing it against a still-literal `"workspace:*"` `entries`
+ * value would misreport idempotent re-application as a conflict). Reuses
+ * `substituteWorkspaceVersions` itself (same regex, same throw-on-missing
+ * behavior) rather than re-deriving the caret-prefix rule.
+ */
+function resolveEntryValue(key, value, versions) {
+    if (value !== "workspace:*" || !key.startsWith("@working-theory/"))
+        return value;
+    const substituted = substituteWorkspaceVersions(`"${key}": "workspace:*"`, versions);
+    const match = /:\s*"([^"]+)"$/.exec(substituted);
+    return match ? match[1] : value;
+}
+function applyJsonMergeKeys(target, root, op, versions, isPackageJson) {
+    const resolved = resolvePathParent(root, op.path);
+    const container = resolved ? resolved.parent[resolved.key] : undefined;
+    if (!resolved || typeof container !== "object" || container === null || Array.isArray(container)) {
+        throw unparseableAnchor(target, op.path.join("."));
+    }
+    const obj = container;
+    for (const [key, rawValue] of Object.entries(op.entries)) {
+        const value = isPackageJson ? resolveEntryValue(key, rawValue, versions) : rawValue;
+        if (!Object.prototype.hasOwnProperty.call(obj, key)) {
+            obj[key] = value;
+        }
+        else if (!deepEqual(obj[key], value)) {
+            throw conflict(target, [...op.path, key].join("."), obj[key], value);
+        }
+        // Present with the identical value — no-op (idempotent).
+    }
+}
+function applyJsonAppendUnique(target, root, op) {
+    const resolved = resolvePathParent(root, op.path);
+    const container = resolved ? resolved.parent[resolved.key] : undefined;
+    if (!resolved || !Array.isArray(container)) {
+        throw unparseableAnchor(target, op.path.join("."));
+    }
+    for (const item of op.items) {
+        if (!container.some((existing) => deepEqual(existing, item))) {
+            container.push(item);
+        }
+    }
+}
+function applyJsonOps(target, text, ops, versions, isPackageJson) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        throw unparseableJson(target);
+    }
+    for (const op of ops) {
+        if (op.op === "merge-keys")
+            applyJsonMergeKeys(target, root, op, versions, isPackageJson);
+        else if (op.op === "append-unique")
+            applyJsonAppendUnique(target, root, op);
+        else {
+            throw new Error(`invalid module manifest: unknown patch op "${op.op}" for target ${target}`);
+        }
+    }
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/** The `[...]` span of the array literal opened right after `anchorLiteral`, or `null` if the anchor/array can't be located. */
+function findArraySpan(text, anchorLiteral) {
+    const anchorIdx = text.indexOf(anchorLiteral);
+    if (anchorIdx === -1)
+        return null;
+    const openIdx = text.indexOf("[", anchorIdx);
+    if (openIdx === -1)
+        return null;
+    let depth = 0;
+    let closeIdx = -1;
+    for (let i = openIdx; i < text.length; i++) {
+        if (text[i] === "[")
+            depth++;
+        else if (text[i] === "]") {
+            depth--;
+            if (depth === 0) {
+                closeIdx = i;
+                break;
+            }
+        }
+    }
+    if (closeIdx === -1)
+        return null;
+    return { openIdx, closeIdx };
+}
+/** Whether `elementLine` already occurs WITHIN the array literal opened after `anchorLiteral` (not merely somewhere in the file). */
+function arrayContainsElement(text, anchorLiteral, elementLine) {
+    const span = findArraySpan(text, anchorLiteral);
+    if (span === null)
+        return false;
+    return text.slice(span.openIdx, span.closeIdx).includes(elementLine);
+}
+/** Insert `elementLine` (already including its own trailing "\n") as the last element of the array literal opened right after `anchorLiteral`. */
+function insertAsLastArrayElement(text, anchorLiteral, elementLine) {
+    const span = findArraySpan(text, anchorLiteral);
+    if (span === null)
+        return null;
+    const { openIdx, closeIdx } = span;
+    const body = text.slice(openIdx + 1, closeIdx);
+    const trailingMatch = /\n[ \t]*$/.exec(body);
+    const trailingWs = trailingMatch ? trailingMatch[0] : "\n";
+    const bodyCore = trailingMatch ? body.slice(0, -trailingWs.length) : body;
+    const newBody = `${bodyCore}\n${elementLine.replace(/\n$/, "")}${trailingWs}`;
+    return text.slice(0, openIdx + 1) + newBody + text.slice(closeIdx);
+}
+/** Insert `entryText` (including its own trailing "\n") immediately after the line containing `anchorLiteral`. */
+function insertAfterAnchorLine(text, anchorLiteral, entryText) {
+    const anchorIdx = text.indexOf(anchorLiteral);
+    if (anchorIdx === -1)
+        return null;
+    const lineEnd = text.indexOf("\n", anchorIdx);
+    if (lineEnd === -1)
+        return null;
+    return text.slice(0, lineEnd + 1) + entryText + text.slice(lineEnd + 1);
+}
+function applyAddTranspilePackage(target, text, op) {
+    const elementLine = `    "${op.package}",\n`;
+    if (arrayContainsElement(text, "transpilePackages: [", elementLine))
+        return text; // already applied — idempotent no-op.
+    const next = insertAsLastArrayElement(text, "transpilePackages: [", elementLine);
+    if (next === null)
+        throw unparseableAnchor(target, "transpilePackages: [");
+    return next;
+}
+function applyWrapExportWith(target, text, op) {
+    let next = text;
+    if (!next.includes(op.importLine)) {
+        const re = /^import\b.*\n/gm;
+        let lastEnd = -1;
+        let m;
+        while ((m = re.exec(next)))
+            lastEnd = m.index + m[0].length;
+        if (lastEnd === -1)
+            throw unparseableAnchor(target, op.importLine.trimEnd());
+        next = next.slice(0, lastEnd) + op.importLine + next.slice(lastEnd);
+    }
+    if (next.includes(op.replaceWith))
+        return next; // already applied — idempotent no-op.
+    if (!next.includes(op.find))
+        throw unparseableAnchor(target, op.find);
+    return next.replace(op.find, op.replaceWith);
+}
+function applyAddTransformIgnorePattern(target, text, op) {
+    if (text.includes(op.replaceWith))
+        return text; // already applied — idempotent no-op.
+    if (!text.includes(op.find))
+        throw unparseableAnchor(target, op.find);
+    return text.replace(op.find, op.replaceWith);
+}
+/**
+ * Shared by add-module-name-mapper / add-transform: a keyed entry inside an
+ * object literal. `renderedValue` is the exact FILE-TEXT form of the wanted
+ * value (quoted for a mapper's string value; verbatim for a transform's raw
+ * source text) — used only for the idempotence text comparison and the
+ * insertion. `plainWantedValue` is the LOGICAL value — used for the D4
+ * class-1 message, which JSON.stringifies it itself (D4's `<newValueJSON>`
+ * shape); passing the already-quoted `renderedValue` there would double-quote it.
+ * `unwrapQuotes` strips one layer of literal `"…"` off the captured
+ * existing-file text before it goes into the message, for the same reason —
+ * on for add-module-name-mapper (always a quoted string), off for
+ * add-transform (verbatim source, not necessarily quoted at all).
+ */
+function applyKeyedEntry(target, text, anchorLiteral, locatorPrefix, pattern, renderedValue, plainWantedValue, unwrapQuotes, entryText) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const keyRe = new RegExp(`"${escaped}":\\s*(.+?),`, "s");
+    const match = keyRe.exec(text);
+    if (match) {
+        const existingRaw = match[1].trim();
+        if (existingRaw === renderedValue.trim())
+            return text; // already applied — idempotent no-op.
+        const plainExisting = unwrapQuotes
+            ? existingRaw.replace(/^"([\s\S]*)"$/, "$1")
+            : existingRaw;
+        throw conflict(target, `${locatorPrefix}["${pattern}"]`, plainExisting, plainWantedValue);
+    }
+    const next = insertAfterAnchorLine(text, anchorLiteral, entryText);
+    if (next === null)
+        throw unparseableAnchor(target, anchorLiteral);
+    return next;
+}
+function applyAddModuleNameMapper(target, text, op) {
+    const renderedValue = `"${op.value}"`;
+    const entryText = `    "${op.pattern}":\n      ${renderedValue},\n`;
+    return applyKeyedEntry(target, text, "moduleNameMapper: {", "moduleNameMapper", op.pattern, renderedValue, op.value, true, entryText);
+}
+function applyAddTransform(target, text, op) {
+    const entryText = `    "${op.pattern}": ${op.value},\n`;
+    return applyKeyedEntry(target, text, "transform: {", "transform", op.pattern, op.value, op.value, false, entryText);
+}
+function applyTextOps(target, text, ops) {
+    let next = text;
+    for (const op of ops) {
+        if (op.op === "add-transpile-package")
+            next = applyAddTranspilePackage(target, next, op);
+        else if (op.op === "wrap-export-with")
+            next = applyWrapExportWith(target, next, op);
+        else if (op.op === "add-transform-ignore-pattern")
+            next = applyAddTransformIgnorePattern(target, next, op);
+        else if (op.op === "add-module-name-mapper")
+            next = applyAddModuleNameMapper(target, next, op);
+        else if (op.op === "add-transform")
+            next = applyAddTransform(target, next, op);
+        else {
+            throw new Error(`invalid module manifest: unknown patch op "${op.op}" for target ${target}`);
+        }
+    }
+    return next;
+}
+/**
+ * Compute every patched target's new content in memory — throws on the
+ * first D4 class 1-3 failure encountered (deterministic order — targets in
+ * `patches` array order) and writes nothing anywhere; returns only the
+ * targets whose content actually changed. Pure with respect to the
+ * filesystem: reads go through `options.readTarget`, nothing is written.
+ * Pair with `writeModulePatches` for the second pass, deferred until every
+ * other part of the caller's own operation (e.g. `copyTree`/`installMap`)
+ * has ALSO succeeded, so a patch failure can never leave partial output
+ * from an earlier step in place either.
+ */
+export function computeModulePatches(patches, options) {
+    if (patches.length === 0)
+        return [];
+    // Group by target — a manifest MAY list the same target across multiple
+    // ModulePatch entries; every op targeting a file applies, in array order,
+    // to that one file's in-memory buffer.
+    const byTarget = new Map();
+    for (const patch of patches) {
+        const existing = byTarget.get(patch.target);
+        if (existing)
+            existing.ops.push(...patch.ops);
+        else
+            byTarget.set(patch.target, { kind: patch.kind, ops: [...patch.ops] });
+    }
+    const computed = [];
+    for (const [target, { kind, ops }] of byTarget) {
+        const original = options.readTarget(target);
+        if (original === undefined)
+            throw missingTarget(target);
+        let content;
+        if (kind === "json") {
+            const isPackageJson = basename(target) === "package.json";
+            content = applyJsonOps(target, original, ops, options.versions, isPackageJson);
+            if (isPackageJson) {
+                content = substituteWorkspaceVersions(content, options.versions);
+            }
+        }
+        else if (kind === "next-config" || kind === "jest-config") {
+            content = applyTextOps(target, original, ops);
+        }
+        else {
+            throw new Error(`invalid module manifest: unknown patch kind "${kind}" for target ${target}`);
+        }
+        if (content !== original)
+            computed.push({ target, content });
+    }
+    return computed;
+}
+/** Write every `computeModulePatches` result to disk, resolved against `baseDir`, once. */
+export function writeModulePatches(computed, baseDir) {
+    const baseAbs = resolve(baseDir);
+    for (const { target, content } of computed) {
+        writeFileSync(resolve(baseAbs, target), content);
+    }
+}
+/**
+ * Apply every patch in `patches` onto the scaffold at `targetDir` — reads
+ * every target directly from `targetDir` (no staging tree involved) and
+ * writes once everything computes cleanly. The convenience form for a
+ * patch set whose targets are ALL pre-existing scaffold files; a caller
+ * whose bundle also delivers some of those targets itself (via plain
+ * content or `installMap`) should use `computeModulePatches`/
+ * `writeModulePatches` directly so a patch failure can roll back the
+ * whole merge, not just the patch step.
+ */
+export function applyModulePatches(patches, targetDir, options) {
+    const targetAbs = resolve(targetDir);
+    const readTarget = (target) => {
+        const absPath = resolve(targetAbs, target);
+        if (!existsSync(absPath))
+            return undefined;
+        return readFileSync(absPath, "utf8");
+    };
+    const computed = computeModulePatches(patches, { ...options, readTarget });
+    writeModulePatches(computed, targetAbs);
+}

package/dist/lib/extract-module-bundle.d.ts

@@ -1,3 +1,4 @@
+import type { WorkspaceVersionMap } from "../substitute.js";
 export interface ExtractModuleBundleOptions {
     /** The fetched bundle bytes (a gzipped tar archive). */
     bytes: Uint8Array;
@@ -5,12 +6,59 @@ export interface ExtractModuleBundleOptions {
     targetDir: string;
     /** The module name — used only for error messages and staging dir naming. */
     moduleName: string;
+    /**
+     * Canonical `@working-theory/*` package versions (spec 5418 § 3 D2), for
+     * `package.json` patch targets' `workspace:*` substitution — the same map
+     * `copyTemplate` threads to `substituteWorkspaceVersions`. Defaults to `{}`
+     * (a bundle with no `patches`, or none using `workspace:*`, needs nothing).
+     */
+    versions?: WorkspaceVersionMap;
+    /**
+     * Present ⟹ `moduleName` names a SITE TEMPLATE, not a module, and the
+     * archive's root manifest is `ailk-template.json` cross-checked against
+     * this list (record D10, DD4). See `InstallBundleTreeOptions`.
+     */
+    templateRequires?: readonly string[];
 }
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
  * the tree `copyTemplate` already wrote. Throws on any unsafe entry,
- * decompress error, or limit overrun — `targetDir` is left untouched on
- * failure (validation completes in a throwaway staging dir before any file
- * is copied into place).
+ * decompress error, limit overrun, invalid `installMap`, or `patches`
+ * failure (D4) — `targetDir` is left untouched on failure in every one of
+ * those cases: validation AND patch computation both complete before any
+ * file is copied or written into place.
  */
 export declare function extractModuleBundle(options: ExtractModuleBundleOptions): Promise<void>;
+export interface InstallBundleTreeOptions {
+    /**
+     * The validated tree whose files land in the scaffold. Two source roots,
+     * one install step (spec 5481 § 3 DD7): the staging dir
+     * `extractModuleBundle` above produced, or `site-templates/<name>/` read
+     * straight off disk on the keyless Free path.
+     */
+    sourceRoot: string;
+    /** The already-scaffolded target directory the files land in. */
+    targetDir: string;
+    /** The module or template name — error messages and nothing else. */
+    name: string;
+    /**
+     * Present ⟹ this tree is a SITE TEMPLATE's: the root manifest is
+     * `ailk-template.json`, it MUST be present and parseable, and its
+     * `requires` must agree with this list — the client registry's own
+     * (record D10, DD4). Absent ⟹ a module bundle, read exactly as before.
+     */
+    templateRequires?: readonly string[];
+    /** Canonical `@working-theory/*` versions for `workspace:*` substitution in patch targets. */
+    versions?: WorkspaceVersionMap;
+}
+/**
+ * Apply one resolved manifest's `installMap`, plain content and `patches`
+ * from `sourceRoot` into `targetDir`.
+ *
+ * Extracted from `extractModuleBundle` so the Free template path — which has
+ * no archive to unpack, only a local tree — runs the SAME step (DD7). The
+ * atomicity guarantee is this function's, not its callers': validation AND
+ * patch computation both complete before the first byte is written, so a
+ * rejected tree leaves `targetDir` exactly as it was.
+ */
+export declare function installBundleTree(options: InstallBundleTreeOptions): void;