create-ailk 0.3.0 → 0.5.0

package/dist/lib/extract-module-bundle.js

@@ -62,6 +62,20 @@
  * `copyTree`/`installMap` run, followed by one write pass for the computed
  * patches — so a patch failure leaves `targetDir` exactly as it was before
  * this call, including files THIS bundle would otherwise have added.
+ *
+ * SITE TEMPLATES (spec 5481; parent record D9, D10, DD4, DD7). A template's
+ * root manifest is `ailk-template.json` — `ailk-module.json`'s shape plus a
+ * mandatory `requires`, cross-checked against the client registry's list so a
+ * stale client cannot land a template built for a different module set. Two
+ * differences from the module path, both deliberate and both confined to
+ * reading the manifest: a template's manifest MUST be present and parseable
+ * (a module's absent-or-unparseable manifest legitimately degrades to a plain
+ * content merge; a template's `requires` is mandatory, so treat-as-absent
+ * would make the cross-check optional at the bundle's own discretion), and a
+ * `requires` disagreement rejects. Everything after that — traversal,
+ * containment, link rejection, the limits, the atomicity ordering — is the
+ * same code, reached through `installBundleTree`, which the keyless Free path
+ * calls directly with `site-templates/<name>/` as its source root.
  */
 import { copyFileSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
@@ -69,12 +83,21 @@ import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import * as tar from "tar";
+import { coOwnedModuleDestinations, } from "../module-architecture.js";
+import { validateTemplateLayout, } from "../site-chrome.js";
 import { computeModulePatches, writeModulePatches } from "./apply-module-patches.js";
 /** Soft limits to prevent decompression-bomb / zip-bomb attacks. Same values as extractBundle. */
 const MAX_ENTRIES = 1000;
-const MAX_TOTAL_SIZE_BYTES = 50 * 1024 * 1024; // 50 MiB
+/** Exported for `fetch-template.ts`/`fetch-module.ts`'s Content-Length guard (#5514) — one cap, not two literals. */
+export const MAX_TOTAL_SIZE_BYTES = 50 * 1024 * 1024; // 50 MiB
 /** The bundle-root manifest file (spec § D7). Never copied into the scaffold. */
 const AILK_MODULE_JSON = "ailk-module.json";
+/**
+ * A SITE TEMPLATE's root manifest (spec 5481 § 4; parent record D10) — the
+ * same shape as `ailk-module.json` plus one mandatory field, `requires`.
+ * Never copied into the scaffold either.
+ */
+const AILK_TEMPLATE_JSON = "ailk-template.json";
 /** The op names valid for each patch `kind` (spec 5418 § 3 D1's ModulePatchOp union, partitioned). */
 const VALID_OPS_BY_KIND = {
     json: new Set(["merge-keys", "append-unique"]),
@@ -127,37 +150,113 @@ function readAilkModuleManifest(extractedRoot) {
         return null;
     }
 }
+/**
+ * Read `ailk-template.json` from a template tree's root and cross-check its
+ * `requires` against the client registry's list for that template.
+ *
+ * REFUSES where `readAilkModuleManifest` degrades (spec 5481 § 3 DD4). A
+ * module's manifest fields are all optional, so an absent or unparseable one
+ * legitimately means "a plain content merge". A template's `requires` is
+ * mandatory (record D10) — inheriting treat-as-absent would make the
+ * cross-check optional at the bundle's own discretion, since a bundle
+ * carrying no manifest would never be checked at all.
+ *
+ * The disagreement check is a boundary check, and the boundary is the bundle:
+ * `expectedRequires` comes from the caller's own `TEMPLATE_MANIFESTS` entry
+ * (internal, compile-checked against `RECOGNIZED_MODULES`), while `requires`
+ * is whatever the archive says. Compared as SETS, not as sequences — the
+ * registry's declaration order is not part of the contract.
+ */
+function readAilkTemplateManifest(sourceRoot, name, expectedRequires, expectedExtends) {
+    const manifestPath = join(sourceRoot, AILK_TEMPLATE_JSON);
+    if (!existsSync(manifestPath)) {
+        throw new Error(`template "${name}": bundle carries no ${AILK_TEMPLATE_JSON} — a template manifest is mandatory`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} is not readable JSON`);
+    }
+    const declaredRaw = manifest.requires;
+    if (!Array.isArray(declaredRaw)) {
+        throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} declares no "requires" list`);
+    }
+    // #5514: every element must be a string BEFORE the comparison below — a
+    // prior `join(",")` comparison would let a non-string element (or one
+    // containing a comma) defeat the disagreement check by colliding with an
+    // unrelated element-set on the joined string.
+    for (const item of declaredRaw) {
+        if (typeof item !== "string") {
+            throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} "requires" contains a non-string entry`);
+        }
+    }
+    const declared = declaredRaw;
+    const expected = [...new Set(expectedRequires)].sort();
+    const actual = [...new Set(declared)].sort();
+    const disagrees = expected.length !== actual.length ||
+        expected.some((value, index) => value !== actual[index]);
+    if (disagrees) {
+        throw new Error(`template "${name}": bundle requires [${actual.join(", ")}] but this create-ailk's registry requires [${expected.join(", ")}] — upgrade create-ailk`);
+    }
+    // #5618 D2 — `extends` joins `requires` as the sibling cross-check, with
+    // the same "upgrade create-ailk" posture: the registry's value is the
+    // caller's compile-checked lineage, the bundle's is whatever the archive
+    // says. Compared exactly (a single parent, not a set). The base layer is
+    // the terminus and declares none — its caller passes none.
+    const declaredExtends = manifest.extends;
+    if (declaredExtends !== undefined && typeof declaredExtends !== "string") {
+        throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} "extends" is not a string`);
+    }
+    if (declaredExtends !== expectedExtends) {
+        const show = (value) => value === undefined ? "nothing" : `"${value}"`;
+        throw new Error(`template "${name}": bundle extends ${show(declaredExtends)} but this create-ailk's registry extends ${show(expectedExtends)} — upgrade create-ailk`);
+    }
+    // #5612 D1 — validated here (throws naming the field on an unrecognized
+    // value), never merely stored: a bundle's `layout` is untrusted JSON,
+    // unlike the code registry's compile-time-checked `TemplateManifest.layout`.
+    validateTemplateLayout(manifest.layout, `template "${name}"`);
+    return manifest;
+}
 /**
  * Validate every `installMap` entry against the staged tree and the target
  * scaffold, throwing on the first violation — called BEFORE any copy, so a
  * bad entry rejects the whole bundle with nothing written to `targetDir`.
  * Returns the map unchanged (validation only) for the caller to apply.
  */
-function validateInstallMap(installMap, extractedRoot, targetAbs, moduleName) {
+function validateInstallMap(installMap, extractedRoot, targetAbs, subject, isTemplate) {
     for (const [source, destination] of Object.entries(installMap)) {
         if (hasUnsafeSegment(source)) {
-            throw new Error(`module "${moduleName}": unsafe installMap source "${source}"`);
+            throw new Error(`${subject}: unsafe installMap source "${source}"`);
         }
         const sourceAbs = resolve(extractedRoot, source);
         if (!isPathInside(extractedRoot, sourceAbs)) {
-            throw new Error(`module "${moduleName}": installMap source "${source}" resolves outside staging`);
+            throw new Error(`${subject}: installMap source "${source}" resolves outside staging`);
         }
         let sourceStat;
         try {
             sourceStat = statSync(sourceAbs);
         }
         catch {
-            throw new Error(`module "${moduleName}": installMap source "${source}" is not a file the bundle produced`);
+            throw new Error(`${subject}: installMap source "${source}" is not a file the bundle produced`);
         }
         if (!sourceStat.isFile()) {
-            throw new Error(`module "${moduleName}": installMap source "${source}" is not a file the bundle produced`);
+            throw new Error(`${subject}: installMap source "${source}" is not a file the bundle produced`);
         }
         if (hasUnsafeSegment(destination)) {
-            throw new Error(`module "${moduleName}": unsafe installMap destination "${destination}"`);
+            throw new Error(`${subject}: unsafe installMap destination "${destination}"`);
         }
         const destAbs = resolve(targetAbs, destination);
         if (!isPathInside(targetAbs, destAbs)) {
-            throw new Error(`module "${moduleName}": installMap destination "${destination}" resolves outside target`);
+            throw new Error(`${subject}: installMap destination "${destination}" resolves outside target`);
+        }
+        // #5514 (Medium) — content, never code (spec 5462 D9/D16): a template's
+        // installMap can only ever ADD a file, so a code-extension destination
+        // is refused outright, same fail-closed point as the containment checks
+        // above.
+        if (isTemplate && hasTemplateForbiddenExtension(destination)) {
+            throw new Error(`${subject}: a template must not carry a code file — installMap destination "${destination}" (spec 5462 D9)`);
         }
     }
 }
@@ -170,14 +269,14 @@ function validateInstallMap(installMap, extractedRoot, targetAbs, moduleName) {
  * (unknown kind/op), resolved here at validation time, never inside
  * `applyModulePatches` (which never sees an invalid kind/op).
  */
-function validatePatches(patches, targetAbs, moduleName) {
+function validatePatches(patches, targetAbs, subject) {
     for (const patch of patches) {
         if (hasUnsafeSegment(patch.target)) {
-            throw new Error(`module "${moduleName}": unsafe patch target "${patch.target}"`);
+            throw new Error(`${subject}: unsafe patch target "${patch.target}"`);
         }
         const targetAbsPath = resolve(targetAbs, patch.target);
         if (!isPathInside(targetAbs, targetAbsPath)) {
-            throw new Error(`module "${moduleName}": patch target "${patch.target}" resolves outside target`);
+            throw new Error(`${subject}: patch target "${patch.target}" resolves outside target`);
         }
         const validOps = VALID_OPS_BY_KIND[patch.kind];
         if (!validOps) {
@@ -190,11 +289,130 @@ function validatePatches(patches, targetAbs, moduleName) {
         }
     }
 }
+/**
+ * TEMPLATE-only "content, never code" guard (spec 5462 § D9/D16; #5514). A
+ * template's manifest and tree are UNTRUSTED — fetched from the registry —
+ * so the rule that a template contributes content, never code, is enforced
+ * here, at the same fail-closed validation point as `installMap`/`patches`
+ * below, rather than only by the two jest cases that assert it against the
+ * `site-templates/` tree this create-ailk itself ships (those only prove
+ * OUR tree is honest, not that a hostile registry response is refused).
+ */
+const TEMPLATE_FORBIDDEN_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+function hasTemplateForbiddenExtension(p) {
+    return TEMPLATE_FORBIDDEN_EXTENSIONS.some((ext) => p.toLowerCase().endsWith(ext));
+}
+/**
+ * Walks `srcRoot` and throws on the first file (not in `excluded`) whose
+ * name ends in a code extension — before any copy, so a violation rejects
+ * the whole tree with nothing written to `targetDir` (same posture as
+ * `validateInstallMap`/`validatePatches`). `excluded` is the SAME
+ * POSIX-normalized set `copyTree` below will use, so the manifest itself and
+ * any installMap source never trip this guard a second time.
+ */
+function validateTemplateContentOnly(srcRoot, excluded, subject) {
+    const stack = [srcRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const srcPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(srcPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = relative(srcRoot, srcPath).split(sep).join("/");
+            if (excluded.has(rel))
+                continue;
+            if (hasTemplateForbiddenExtension(rel)) {
+                throw new Error(`${subject}: a template must not carry a code file — "${rel}" (spec 5462 D9)`);
+            }
+            // symlinks: never present — safeExtractTarGz rejects them outright.
+        }
+    }
+}
 /** C0 (0x00-0x1F) and C1 (0x7F-0x9F) control characters, newline excepted. */
 function stripControlCharacters(text) {
     // eslint-disable-next-line no-control-regex -- deliberately stripping control chars
     return text.replace(/[\x00-\x09\x0B-\x1F\x7F-\x9F]/g, "");
 }
+/**
+ * The additive-overlap rule (#5618 D4), checked in the validation block
+ * before the first write so a refusal leaves `targetDir` exactly as it was:
+ *
+ *   | incoming layer | destination owned by          | outcome                     |
+ *   | base           | nothing (it is first)         | records                     |
+ *   | module         | base or an earlier module     | REFUSED — unless a declared |
+ *   |                |                               | `patches` target            |
+ *   | module         | nothing recorded              | allowed, records            |
+ *   | template       | anything                      | allowed, records            |
+ *
+ * The template layer may overwrite anything because it is the customer's
+ * copy — that is how a template overrides a module's seed page (D3), and
+ * refusing it would refuse `--template marketing-site` as shipped. The
+ * `patches` escape hatch is unambiguously module-only: a template carrying
+ * `patches` at all is refused outright above.
+ *
+ * The SECOND module-only escape hatch is DECLARED CO-OWNERSHIP
+ * (`coOwnedModuleDestinations()`): a repo file that more than one module's
+ * `ownedFiles` names. Both bundles stage it from the same source, so the
+ * second to land writes the bytes already there — no disagreement to
+ * resolve, which is the only thing this rule protects against. #5677 needs
+ * it: the review surface registers under `multi-tenant || signal-collectors`
+ * and so must ship in both bundles, and `saas-product` selects both. An
+ * overlap neither module declares is still refused.
+ *
+ * Mirrors `mergeRoster`'s `claimedBy` refusal one grain down: a collision is
+ * named with both claimants and the path, never resolved by a silent
+ * last-writer-wins.
+ */
+function validateLayerOwnership(destinations, ownership, subject, isTemplate, patchTargets, coOwned) {
+    if (isTemplate)
+        return;
+    for (const destination of destinations) {
+        const owner = ownership.get(destination);
+        if (owner !== undefined &&
+            !patchTargets.has(destination) &&
+            !coOwned.has(destination)) {
+            throw new Error(`${subject}: destination "${destination}" is already owned by ${owner} — a module's contribution to a file another layer wrote must be a declared patch, never an overwrite (#5618 D4)`);
+        }
+    }
+}
+/**
+ * Every scaffold-relative destination this tree will write: each unmapped
+ * staged file at its own path (exactly the set `copyTree` lands, same walk,
+ * same exclusions) plus every `installMap` destination. Computed before any
+ * write, for `validateLayerOwnership` and then for the record.
+ */
+function collectLayerDestinations(srcRoot, excluded, installMap) {
+    const out = [];
+    const stack = [srcRoot];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const srcPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(srcPath);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = relative(srcRoot, srcPath).split(sep).join("/");
+            if (excluded.has(rel))
+                continue;
+            out.push(rel);
+        }
+    }
+    for (const destination of Object.values(installMap)) {
+        out.push(normalize(destination).split(sep).join("/"));
+    }
+    return out;
+}
 /**
  * Extract a fetched module bundle into `targetDir`, merging its files onto
  * the tree `copyTemplate` already wrote. Throws on any unsafe entry,
@@ -204,7 +422,7 @@ function stripControlCharacters(text) {
  * file is copied or written into place.
  */
 export async function extractModuleBundle(options) {
-    const { bytes, targetDir, moduleName } = options;
+    const { bytes, targetDir, moduleName, templateRequires } = options;
     const targetAbs = resolve(targetDir);
     if (!existsSync(targetAbs)) {
         throw new Error(`extractModuleBundle: target directory does not exist: ${targetAbs}`);
@@ -215,77 +433,154 @@ export async function extractModuleBundle(options) {
         writeFileSync(stagingTar, bytes);
         const extractedRoot = join(stagingDir, "extracted");
         mkdirSync(extractedRoot, { recursive: true });
-        await safeExtractTarGz(stagingTar, extractedRoot, moduleName);
-        // installMap validation runs BEFORE any copy, so a bad entry rejects the
-        // whole bundle with nothing written to targetDir (same posture as the
-        // tar-entry validation above).
-        const manifest = readAilkModuleManifest(extractedRoot);
-        const installMap = manifest?.installMap ?? {};
-        validateInstallMap(installMap, extractedRoot, targetAbs, moduleName);
-        // patches validation (spec 5418 § 3 D6) runs at the same point, before
-        // any copy — a bad target/kind/op rejects the whole bundle with nothing
-        // written to targetDir, same posture as installMap and the tar-entry
-        // validation above.
-        const patches = manifest?.patches ?? [];
-        validatePatches(patches, targetAbs, moduleName);
-        // Compute every patch target's new content BEFORE any write to
-        // targetDir — including before copyTree/installMap below, not only
-        // before the patch step's own write (spec 5418 § 3 D4/§ 6.2): a
-        // conflict, missing-target, or unparseable-target failure must leave
-        // the scaffold exactly as it was, which includes the bundle's own
-        // plain content and installMap destinations never landing either. A
-        // patch target the bundle itself delivers (as plain content or as an
-        // installMap destination) is read from the STAGED tree here, since
-        // targetDir would not have it yet at this point.
-        const installMapDestinationToSource = new Map(Object.entries(installMap).map(([source, destination]) => [destination, source]));
-        const readPatchTarget = (target) => {
-            const mappedSource = installMapDestinationToSource.get(target);
-            if (mappedSource !== undefined) {
-                const sourceAbs = resolve(extractedRoot, mappedSource);
-                return existsSync(sourceAbs) ? readFileSync(sourceAbs, "utf8") : undefined;
-            }
-            const stagedAbs = resolve(extractedRoot, target);
-            if (existsSync(stagedAbs) && statSync(stagedAbs).isFile()) {
-                return readFileSync(stagedAbs, "utf8");
-            }
-            const targetAbsPath = resolve(targetAbs, target);
-            return existsSync(targetAbsPath) ? readFileSync(targetAbsPath, "utf8") : undefined;
-        };
-        const computedPatches = computeModulePatches(patches, {
-            versions: options.versions ?? {},
-            readTarget: readPatchTarget,
+        await safeExtractTarGz(stagingTar, extractedRoot, templateRequires !== undefined
+            ? `template "${moduleName}"`
+            : `module "${moduleName}"`);
+        return installBundleTree({
+            sourceRoot: extractedRoot,
+            targetDir: targetAbs,
+            name: moduleName,
+            ...(templateRequires !== undefined ? { templateRequires } : {}),
+            ...(options.templateExtends !== undefined
+                ? { templateExtends: options.templateExtends }
+                : {}),
+            ...(options.ownership !== undefined ? { ownership: options.ownership } : {}),
+            ...(options.versions !== undefined ? { versions: options.versions } : {}),
         });
-        // Full validation AND patch computation passed — only now does anything
-        // get written to targetDir. Copies only (never deletes anything): a
-        // fetched module's files ADD to the free scaffold, they never remove
-        // what the free copy already wrote. ailk-module.json and every
-        // installMap source are excluded from the whole-tree copy — the
-        // manifest never lands in the scaffold, and a mapped source lands ONLY
-        // at its mapped destination, never also at its original path.
-        const excluded = new Set([
-            AILK_MODULE_JSON,
-            ...Object.keys(installMap),
-        ]);
-        copyTree(extractedRoot, targetAbs, excluded);
-        for (const [source, destination] of Object.entries(installMap)) {
-            const destAbs = resolve(targetAbs, destination);
-            mkdirSync(join(destAbs, ".."), { recursive: true });
-            copyFileSync(resolve(extractedRoot, source), destAbs);
-        }
-        // patches write AFTER every file the bundle brought is in place (D5) —
-        // after installMap, before postInstall — so a patch can never race a
-        // file its own ownedFiles/installMap just delivered, and (since it was
-        // COMPUTED above, before either ran) overwrites rather than conflicts
-        // with content copyTree/installMap just placed at the same path.
-        writeModulePatches(computedPatches, targetAbs);
-        if (manifest?.postInstall) {
-            process.stdout.write(`${stripControlCharacters(manifest.postInstall)}\n`);
-        }
     }
     finally {
         rmSync(stagingDir, { recursive: true, force: true });
     }
 }
+/**
+ * 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 function installBundleTree(options) {
+    const { sourceRoot, name, templateRequires, templateExtends, ownership } = options;
+    const targetAbs = resolve(options.targetDir);
+    const isTemplate = templateRequires !== undefined;
+    const subject = isTemplate ? `template "${name}"` : `module "${name}"`;
+    // installMap validation runs BEFORE any copy, so a bad entry rejects the
+    // whole tree with nothing written to targetDir (same posture as the
+    // tar-entry validation in safeExtractTarGz).
+    const manifest = isTemplate
+        ? readAilkTemplateManifest(sourceRoot, name, templateRequires, templateExtends)
+        : readAilkModuleManifest(sourceRoot);
+    const installMap = manifest?.installMap ?? {};
+    validateInstallMap(installMap, sourceRoot, targetAbs, subject, isTemplate);
+    // patches validation (spec 5418 § 3 D6) runs at the same point, before
+    // any copy — a bad target/kind/op rejects the whole tree with nothing
+    // written to targetDir, same posture as installMap and the tar-entry
+    // validation above.
+    const patches = manifest?.patches ?? [];
+    // #5514 (Medium) — content, never code (spec 5462 D9/D16): every `patches`
+    // kind either edits a code file directly (`next-config`, `jest-config`)
+    // or a manifest a template has no legitimate reason to touch
+    // (`package.json`/`tsconfig.json` belong to the scaffold, not to a
+    // content template) — no shipped template uses it, so the simplest
+    // fail-closed reading refuses it outright rather than enumerating an
+    // allowed subset that has no current user.
+    if (isTemplate && patches.length > 0) {
+        throw new Error(`${subject}: a template must not carry patches — content, never code (spec 5462 D9)`);
+    }
+    validatePatches(patches, targetAbs, subject);
+    // The exclusion set copyTree/the content-only guard both use — built from
+    // NORMALIZED installMap keys (#5514) so a "./x" key excludes the same
+    // string `rel`'s traversal below computes, rather than colliding with it
+    // only by accident. Both manifest filenames are excluded unconditionally
+    // (previously a ternary picked one) — a module bundle carrying a stray
+    // ailk-template.json, or vice versa, should never land either.
+    const excluded = new Set([
+        AILK_TEMPLATE_JSON,
+        AILK_MODULE_JSON,
+        ...Object.keys(installMap).map((key) => normalize(key).split(sep).join("/")),
+    ]);
+    if (isTemplate) {
+        validateTemplateContentOnly(sourceRoot, excluded, subject);
+    }
+    // #5618 D4 — the additive-overlap check, at the same seam as the
+    // installMap/patches/content-only validation above: BEFORE the first write
+    // at copyTree below, so a refused layer leaves targetDir exactly as it
+    // was. The destination set is what copyTree + the installMap loop will
+    // land; the record happens after writeModulePatches, once it has.
+    const layerDestinations = ownership !== undefined
+        ? collectLayerDestinations(sourceRoot, excluded, installMap)
+        : [];
+    if (ownership !== undefined) {
+        validateLayerOwnership(layerDestinations, ownership, subject, isTemplate, new Set(patches.map((patch) => normalize(patch.target).split(sep).join("/"))), coOwnedModuleDestinations());
+    }
+    // Compute every patch target's new content BEFORE any write to
+    // targetDir — including before copyTree/installMap below, not only
+    // before the patch step's own write (spec 5418 § 3 D4/§ 6.2): a
+    // conflict, missing-target, or unparseable-target failure must leave
+    // the scaffold exactly as it was, which includes the bundle's own
+    // plain content and installMap destinations never landing either. A
+    // patch target the bundle itself delivers (as plain content or as an
+    // installMap destination) is read from the STAGED tree here, since
+    // targetDir would not have it yet at this point.
+    const installMapDestinationToSource = new Map(Object.entries(installMap).map(([source, destination]) => [destination, source]));
+    const readPatchTarget = (target) => {
+        const mappedSource = installMapDestinationToSource.get(target);
+        if (mappedSource !== undefined) {
+            const sourceAbs = resolve(sourceRoot, mappedSource);
+            return existsSync(sourceAbs) ? readFileSync(sourceAbs, "utf8") : undefined;
+        }
+        const stagedAbs = resolve(sourceRoot, target);
+        if (existsSync(stagedAbs) && statSync(stagedAbs).isFile()) {
+            return readFileSync(stagedAbs, "utf8");
+        }
+        const targetAbsPath = resolve(targetAbs, target);
+        return existsSync(targetAbsPath) ? readFileSync(targetAbsPath, "utf8") : undefined;
+    };
+    const computedPatches = computeModulePatches(patches, {
+        versions: options.versions ?? {},
+        readTarget: readPatchTarget,
+    });
+    // Full validation AND patch computation passed — only now does anything
+    // get written to targetDir. Copies only (never deletes anything): a
+    // fetched module's or template's files ADD to the free scaffold, they
+    // never remove what the free copy already wrote. The root manifest and
+    // every installMap source are excluded from the whole-tree copy — the
+    // manifest never lands in the scaffold, and a mapped source lands ONLY
+    // at its mapped destination, never also at its original path.
+    copyTree(sourceRoot, targetAbs, excluded);
+    for (const [source, destination] of Object.entries(installMap)) {
+        const destAbs = resolve(targetAbs, destination);
+        mkdirSync(join(destAbs, ".."), { recursive: true });
+        copyFileSync(resolve(sourceRoot, source), destAbs);
+    }
+    // patches write AFTER every file the tree brought is in place (D5) —
+    // after installMap, before postInstall — so a patch can never race a
+    // file its own ownedFiles/installMap just delivered, and (since it was
+    // COMPUTED above, before either ran) overwrites rather than conflicts
+    // with content copyTree/installMap just placed at the same path.
+    writeModulePatches(computedPatches, targetAbs);
+    // #5618 D4 — record this layer's destinations only now that every one of
+    // them is in place (a later layer's overwrite is judged against the layer
+    // that actually wrote the bytes). Patch targets are NOT recorded: a patch
+    // edits a file another layer (or the snapshot) owns and does not claim it.
+    if (ownership !== undefined) {
+        for (const destination of layerDestinations)
+            ownership.set(destination, subject);
+    }
+    if (manifest?.postInstall) {
+        process.stdout.write(`${stripControlCharacters(manifest.postInstall)}\n`);
+    }
+    // #5612 D1/D2 — already validated above (readAilkTemplateManifest calls
+    // validateTemplateLayout); returned as-is (defaults unfilled) for the
+    // caller to resolve alongside whatever the code registry's own
+    // `TemplateManifest.layout` says.
+    return isTemplate && manifest?.layout !== undefined
+        ? { layout: manifest.layout }
+        : {};
+}
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
  * directories as needed, except any path in `excluded` (relative to
@@ -324,14 +619,14 @@ function copyTree(srcRoot, destRoot, excluded = new Set()) {
  * file doc for why this is a port and not an import). Extracts `tarGzPath`
  * into `targetDir`, which the caller guarantees is empty.
  */
-async function safeExtractTarGz(tarGzPath, targetDir, moduleName) {
+async function safeExtractTarGz(tarGzPath, targetDir, subject) {
     const resolvedTarget = resolve(targetDir);
     let entryCount = 0;
     let totalSize = 0;
     const captured = { error: null };
     const reject = (msg) => {
         if (captured.error === null) {
-            captured.error = new Error(`module "${moduleName}": ${msg}`);
+            captured.error = new Error(`${subject}: ${msg}`);
         }
         return false;
     };
@@ -383,7 +678,7 @@ async function safeExtractTarGz(tarGzPath, targetDir, moduleName) {
         },
     });
     try {
-        await pipeline(createReadStream(tarGzPath), createGunzip(), extractStream);
+        await pipeline(createReadStream(tarGzPath), createGunzip({ maxOutputLength: MAX_TOTAL_SIZE_BYTES }), extractStream);
     }
     catch (err) {
         if (captured.error !== null)

package/dist/lib/fetch-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Per-request timeout applied to every template/module registry fetch.
+ * 30s is generous for a small tarball fetch over a real network while still
+ * bounding a hung connection or slow-drip response.
+ */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** `AbortSignal.timeout(REQUEST_TIMEOUT_MS)` — one call site, one constant. */
+export declare function fetchTimeoutSignal(): AbortSignal;
+/**
+ * Reject a registry URL whose origin is not `https:`, unless its host is
+ * loopback (above) — the mock registry the test suite spawns is deliberately
+ * plain `http://127.0.0.1:<port>`. `ErrorCtor` lets each
+ * caller throw its own error class (`FetchTemplateError` / `FetchModuleError`)
+ * so this is a new FAILURE MODE, never a new error type from the caller's
+ * point of view — and never a licence error (`isLicenseError` stays false).
+ */
+export declare function assertHttpsRegistryUrl<E extends Error>(registryUrl: string, ErrorCtor: new (message: string) => E): void;
+/**
+ * Reject a `Response` whose `Content-Length` header declares a size larger
+ * than `MAX_TOTAL_SIZE_BYTES` — called by the caller right after its
+ * existing status-code checks succeed, BEFORE `.arrayBuffer()` ever runs, so
+ * an oversized body is never buffered into memory. A missing or unparseable
+ * `Content-Length` is not itself a violation (a chunked/streamed response may
+ * omit it) — this is defense in depth against a declared size, not a
+ * replacement for the tar-entry cumulative-size cap `extract-module-bundle.ts`
+ * still enforces downstream.
+ */
+export declare function assertContentLengthWithinLimit<E extends Error>(response: Response, ErrorCtor: new (message: string) => E): void;