create-ailk 0.3.0 → 0.4.0

package/dist/cli.js

@@ -9,8 +9,9 @@
  *   2. on --help: print helpText, exit 0
  *   3. on --version: print version, exit 0
  *   4. delegate to scaffold() in programmatic.ts — gates + fetches any
- *      requested paid module (K1, #5089 — Flavor 3), then validates + copies
- *      the local template, then merges each fetched bundle in
+ *      requested paid module (K1, #5089 — Flavor 3) and any named site
+ *      template's own bundle (#5481), then validates + copies the local
+ *      template, then merges each fetched bundle in, the site template last
  *   5. when --install: spawn `pnpm install` (cwd = target, hard-coded argv)
  *   6. print next-steps message
  *
@@ -100,17 +101,24 @@ async function main() {
             process.stdout.write(drift);
         process.exit(0);
     }
-    // scaffold() gates + fetches any requested paid module (K1, #5089), then
-    // validates and copies the local template — throws ValidationError or
-    // LicenseRequiredError on rejection (caught at top level below). Neither
-    // AILK_LICENSE_KEY nor AILK_MODULE_REGISTRY_URL is read, and no network
-    // call is made, when `opts.modules` names no paid module — the regression
-    // floor (see `resolvePaidModules` in `lib/module-license-gate.ts`).
+    // scaffold() gates + fetches any requested paid module (K1, #5089) and any
+    // named site template's own bundle (#5481), then validates and copies the
+    // local template — throws ValidationError or LicenseRequiredError on
+    // rejection (caught at top level below). Neither AILK_LICENSE_KEY nor
+    // either registry URL is read, and no network call is made, when the
+    // effective module set names no paid module — the regression floor, which
+    // `--template marketing-site-free` deliberately rides (record D11): its
+    // `requires` is all-free, so it installs from the shipped
+    // `site-templates/` tree with no key and no request.
     const { targetDir: targetAbs, surfaces } = await scaffold({
         targetDir: opts.target,
         modules: opts.modules,
         surfaces: opts.surfaces,
         withCatalog: opts.withCatalog,
+        // Spread rather than passed as `undefined` so a run naming no template
+        // hands `scaffold()` exactly the option object it got before the flag
+        // existed (spec 5481 § 3 DD3's byte-identity floor).
+        ...(opts.template !== undefined ? { template: opts.template } : {}),
     });
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
@@ -126,7 +134,9 @@ async function main() {
     // Next-steps message.
     const lines = [
         "",
-        "Scaffolded AI Launch Kit starter.",
+        opts.template !== undefined
+            ? `Scaffolded AI Launch Kit starter from the "${opts.template}" template.`
+            : "Scaffolded AI Launch Kit starter.",
         "",
         "Next steps:",
         `  cd ${targetAbs}`,

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

@@ -13,6 +13,12 @@ export interface ExtractModuleBundleOptions {
      * (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
@@ -23,3 +29,36 @@ export interface ExtractModuleBundleOptions {
  * 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;

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";
@@ -75,6 +89,12 @@ const MAX_ENTRIES = 1000;
 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 +147,77 @@ 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) {
+    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 declared = manifest.requires;
+    if (!Array.isArray(declared)) {
+        throw new Error(`template "${name}": ${AILK_TEMPLATE_JSON} declares no "requires" list`);
+    }
+    const expected = [...new Set(expectedRequires)].sort();
+    const actual = [...new Set(declared)].sort();
+    if (expected.join(",") !== actual.join(",")) {
+        throw new Error(`template "${name}": bundle requires [${actual.join(", ")}] but this create-ailk's registry requires [${expected.join(", ")}] — upgrade create-ailk`);
+    }
+    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) {
     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`);
         }
     }
 }
@@ -170,14 +230,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) {
@@ -204,7 +264,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 +275,104 @@ 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}"`);
+        installBundleTree({
+            sourceRoot: extractedRoot,
+            targetDir: targetAbs,
+            name: moduleName,
+            ...(templateRequires !== undefined ? { templateRequires } : {}),
+            ...(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 } = 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)
+        : readAilkModuleManifest(sourceRoot);
+    const installMap = manifest?.installMap ?? {};
+    validateInstallMap(installMap, sourceRoot, targetAbs, subject);
+    // 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 ?? [];
+    validatePatches(patches, targetAbs, subject);
+    // 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.
+    const excluded = new Set([
+        isTemplate ? AILK_TEMPLATE_JSON : AILK_MODULE_JSON,
+        ...Object.keys(installMap),
+    ]);
+    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);
+    if (manifest?.postInstall) {
+        process.stdout.write(`${stripControlCharacters(manifest.postInstall)}\n`);
+    }
+}
 /**
  * Recursively copy every file from `srcRoot` into `destRoot`, creating parent
  * directories as needed, except any path in `excluded` (relative to
@@ -324,14 +411,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;
     };

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

@@ -0,0 +1,20 @@
+export declare const DEFAULT_AILK_TEMPLATE_REGISTRY_URL = "https://ailaunchkit.ai/api/templates";
+export interface FetchTemplateOptions {
+    templateName: string;
+    /** JWT used as `Authorization: Bearer <token>`. Must be non-empty. */
+    token: string;
+    /** Registry root; `<name>/<version>` is appended as two path segments. */
+    registryUrl?: string;
+    /** The template version to request. Defaults to this package's own version. */
+    version?: string;
+    /** Override for tests; defaults to `globalThis.fetch`. Never a live call in CI. */
+    fetchImpl?: typeof fetch;
+}
+export declare class FetchTemplateError extends Error {
+    /** True iff the failure was a license-gating signal (HTTP 401 or 403). */
+    readonly isLicenseError: boolean;
+    constructor(message: string, 
+    /** True iff the failure was a license-gating signal (HTTP 401 or 403). */
+    isLicenseError?: boolean);
+}
+export declare function fetchTemplate(options: FetchTemplateOptions): Promise<Uint8Array>;

package/dist/lib/fetch-template.js

@@ -0,0 +1,129 @@
+/**
+ * Authenticated site-template-bundle fetch (spec 5481 § 4; parent record
+ * D1, § 6).
+ *
+ * The client half of `GET /v1/templates/:name/:version` (#5480's route),
+ * reached publicly at `/api/templates/:path*`. Posture is
+ * `fetch-module.ts`'s, mirrored one-for-one rather than generalised into a
+ * shared helper: bearer-JWT auth, `redirect: "error"` so a redirected
+ * response cannot drop the bearer token onto an unintended host, an
+ * empty-token guard before any network call, and the same status mapping —
+ * 401 → licence invalid/revoked/lapsed, 403 → not included / term ended,
+ * 404 → content not yet available, other non-2xx → the upstream body.
+ *
+ * ONE word differs, and it is the whole reason this is a sibling rather
+ * than a second call site of `fetchModule` (spec 5481 § 3 DD5): the 404
+ * sentence names its subject, and the subject here is a TEMPLATE. Parent
+ * record D17 makes that sentence a specified outcome rather than an
+ * incidental one, so the fourth refusal reuses it — with the noun
+ * parameterised, since left alone it would call the template a module.
+ *
+ * Deliberately depends on neither `@working-theory/license` nor
+ * `@working-theory/cli`, for the reason `fetch-module.ts`'s file doc states
+ * at length: both are `publishConfig.access: "restricted"` and this is the
+ * one package published to PUBLIC npm, so a runtime dependency on either
+ * would break `pnpm install` for every Free consumer rather than merely
+ * gate the paid path. The registry's own 401 IS the licence verdict.
+ */
+import pkg from "../../package.json" with { type: "json" };
+export const DEFAULT_AILK_TEMPLATE_REGISTRY_URL = "https://ailaunchkit.ai/api/templates";
+/**
+ * This package's own `package.json` `"version"` — a static JSON import for
+ * the reason `fetch-module.ts`'s `CREATE_AILK_VERSION` doc gives: `import.meta`
+ * is a SyntaxError under ts-jest's CommonJS transform, and this file is
+ * reachable from jest. A template bundle overlays the scaffold this
+ * `create-ailk` just wrote, so the default version request is the running
+ * package's own.
+ */
+const CREATE_AILK_VERSION = pkg.version;
+export class FetchTemplateError extends Error {
+    isLicenseError;
+    constructor(message, 
+    /** True iff the failure was a license-gating signal (HTTP 401 or 403). */
+    isLicenseError = false) {
+        super(message);
+        this.isLicenseError = isLicenseError;
+        this.name = "FetchTemplateError";
+    }
+}
+/**
+ * Join `registryUrl` with `templateName` and `version` as two trailing path
+ * segments. `encodeURIComponent` on each is defense in depth —
+ * `parse-args.ts` already restricts `templateName` to `TEMPLATE_MANIFESTS`'s
+ * keys, but a hostile value can never smuggle a path separator or query
+ * string here regardless.
+ */
+function buildUrl(registryUrl, templateName, version) {
+    const trimmed = registryUrl.replace(/\/+$/, "");
+    return `${trimmed}/${encodeURIComponent(templateName)}/${encodeURIComponent(version)}`;
+}
+export async function fetchTemplate(options) {
+    const { templateName, token } = options;
+    if (token.length === 0) {
+        throw new FetchTemplateError("internal error: fetchTemplate called without a token");
+    }
+    const version = options.version ?? CREATE_AILK_VERSION;
+    const registryUrl = options.registryUrl ??
+        process.env["AILK_TEMPLATE_REGISTRY_URL"] ??
+        DEFAULT_AILK_TEMPLATE_REGISTRY_URL;
+    const url = buildUrl(registryUrl, templateName, version);
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/gzip, application/octet-stream",
+            },
+            redirect: "error",
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new FetchTemplateError(`template registry unreachable: ${detail}`);
+    }
+    if (response.status === 401) {
+        throw new FetchTemplateError(`your licence does not cover the "${templateName}" template (invalid, revoked, or lapsed)`, 
+        /* isLicenseError */ true);
+    }
+    if (response.status === 403) {
+        throw new FetchTemplateError(`your licence does not include the "${templateName}" template, or its term ended before create-ailk ${version} was released — use a create-ailk version released during your term`, 
+        /* isLicenseError */ true);
+    }
+    if (response.status === 404) {
+        throw new FetchTemplateError(`"${templateName}" template content not yet available — ping us at hello@ailaunchkit.ai`);
+    }
+    if (!response.ok) {
+        const body = await safeReadBody(response);
+        throw new FetchTemplateError(`template registry returned ${response.status} for "${templateName}": ${body}`);
+    }
+    const buf = await response.arrayBuffer();
+    return new Uint8Array(buf);
+}
+/**
+ * Best-effort error body extraction — the registry uses `{ error: "..." }`
+ * shapes, falls back to text, and swallows any read failure so the caller's
+ * message stays useful. `fetch-module.ts`'s helper of the same name.
+ */
+async function safeReadBody(response) {
+    try {
+        const text = await response.text();
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed !== null &&
+                typeof parsed === "object" &&
+                "error" in parsed &&
+                typeof parsed.error === "string") {
+                return parsed.error;
+            }
+        }
+        catch {
+            /* not JSON — fall through to raw text */
+        }
+        return text || response.statusText;
+    }
+    catch {
+        return response.statusText;
+    }
+}

package/dist/lib/module-license-gate.d.ts

@@ -39,6 +39,14 @@ export interface ResolvePaidModulesOptions {
     version?: string;
     /** Forwarded to `fetchModule`; defaults to `globalThis.fetch`. Never a live call in tests. */
     fetchImpl?: typeof fetch;
+    /**
+     * The site template whose `requires` put these modules in `paidModules`
+     * (spec 5481 § 3 DD5 rows 1-2). Present ⟹ every refusal below names it
+     * alongside the specific module, because the buyer asked for a TEMPLATE and
+     * a message naming only a module they never typed does not tell them what
+     * to do. Absent ⟹ a plain `--modules` run, whose messages are unchanged.
+     */
+    templateName?: string;
 }
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw

package/dist/lib/module-license-gate.js

@@ -28,7 +28,7 @@ export async function resolvePaidModules(options) {
     }
     const token = options.licenseKey ?? process.env["AILK_LICENSE_KEY"];
     if (token === undefined || token.length === 0) {
-        throw new LicenseRequiredError(conversionHint(paidModules));
+        throw new LicenseRequiredError(conversionHint(paidModules, options.templateName));
     }
     const bundles = new Map();
     for (const moduleName of paidModules) {
@@ -49,7 +49,12 @@ export async function resolvePaidModules(options) {
         catch (err) {
             if (err instanceof FetchModuleError) {
                 if (err.isLicenseError) {
-                    throw new LicenseRequiredError(`${err.message} → ${CONVERSION_HINT_URL}`);
+                    // DD5 row 2: the mapped 401/403 already names the module the key
+                    // does not cover; the template is appended so the buyer can see
+                    // WHICH of the things they asked for needs it.
+                    throw new LicenseRequiredError(options.templateName !== undefined
+                        ? `${err.message}, required by template "${options.templateName}" → ${CONVERSION_HINT_URL}`
+                        : `${err.message} → ${CONVERSION_HINT_URL}`);
                 }
                 // Not a license-gating signal (e.g. 404 "not yet available", or the
                 // registry unreachable) — a generic failure, not the honest-denial
@@ -62,7 +67,10 @@ export async function resolvePaidModules(options) {
     }
     return bundles;
 }
-function conversionHint(paidModules) {
+function conversionHint(paidModules, templateName) {
     const list = paidModules.join(", ");
-    return `Pro module(s) requested (${list}) — set AILK_LICENSE_KEY first → ${CONVERSION_HINT_URL}`;
+    const requested = templateName !== undefined
+        ? `template "${templateName}" requires Pro module(s) (${list})`
+        : `Pro module(s) requested (${list})`;
+    return `${requested} — set AILK_LICENSE_KEY first → ${CONVERSION_HINT_URL}`;
 }