create-ailk 0.2.0 → 0.4.0

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

@@ -28,26 +28,243 @@
  * `extractModuleBundle` therefore extracts into a throwaway temp dir first
  * (same validation, same guards), and ONLY on full success copies each
  * validated file into its place under `targetDir` — so a rejected or
- * partially-decompressed bundle never touches the scaffold at all.
+ * partially-decompressed bundle never touches the scaffold at all. This
+ * guarantee extends all the way through `patches` (below): NOTHING is
+ * written to `targetDir` — not the bundle's own plain content, not an
+ * `installMap` destination, not a patched file — until every patch target
+ * has been computed successfully in memory.
+ *
+ * `installMap` / `postInstall` (spec 5373 § D7): a bundle may carry an
+ * `ailk-module.json` at its root, `{name, version, installMap, postInstall}`.
+ * `installMap` remaps specific staged files to a different scaffold
+ * destination (e.g. the docs-blog `llms-route.ts` landing on
+ * `app/llms.txt/route.ts`) — every source must be a file the validated
+ * extraction produced in staging (an absolute path, a `..` segment, or a
+ * path absent from staging rejects the WHOLE bundle, nothing copied), and
+ * every destination gets the same fail-closed containment check as a tar
+ * entry. A mapped source is copied to its destination only, never also to
+ * its original path. `postInstall` is printed to stdout after a successful
+ * merge, with C0/C1 control characters (other than newline) stripped first
+ * so a bundle cannot inject terminal escape sequences. `ailk-module.json`
+ * itself is never copied into the scaffold.
+ *
+ * `patches` (spec 5418 § 3 D1-D6): a sibling manifest field naming
+ * declarative edits to files the buyer's scaffold already has (or that this
+ * SAME bundle is about to deliver — see below). Validated at the same
+ * fail-closed point as `installMap` (D6), then COMPUTED — every patch
+ * target's new content resolved in memory, throwing on the first conflict /
+ * missing-target / unparseable-target failure (D4) — before `copyTree` or
+ * the `installMap` copy loop runs at all. A patch target the bundle itself
+ * delivers (as plain content or as an `installMap` destination) is read
+ * from the STAGED tree for this computation, since `targetDir` would not
+ * have it yet; every other target is read from the already-scaffolded
+ * `targetDir` file. Only once every target computes successfully does
+ * `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, readdirSync, rmSync, writeFileSync, } from "node:fs";
+import { copyFileSync, createReadStream, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 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 { 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
+/** 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"]),
+    "next-config": new Set(["add-transpile-package", "wrap-export-with"]),
+    "jest-config": new Set([
+        "add-module-name-mapper",
+        "add-transform-ignore-pattern",
+        "add-transform",
+    ]),
+};
+/** True iff `child` is the same path as `parent` or a descendant of it. */
+function isPathInside(parent, child) {
+    const rel = relative(parent, child);
+    if (rel === "")
+        return true;
+    if (rel.startsWith(".."))
+        return false;
+    if (isAbsolute(rel))
+        return false;
+    return true;
+}
+/**
+ * Reject an absolute path or any `..` segment — the same shape check
+ * `safeExtractTarGz` applies to tar entries, reused here for `installMap`
+ * keys/values, which come from bundle-controlled JSON rather than tar
+ * entries and so need the same fail-closed treatment.
+ */
+function hasUnsafeSegment(p) {
+    if (isAbsolute(p))
+        return true;
+    const normalized = normalize(p);
+    return (normalized === ".." ||
+        normalized.startsWith(`..${sep}`) ||
+        normalized.split(sep).includes(".."));
+}
+/**
+ * Read `ailk-module.json` from the validated staging tree, if present.
+ * Malformed JSON is treated as absent — the manifest is written by the
+ * producer (D7), never hand-authored, so a parse failure is a producer bug,
+ * not a security boundary to fail closed on with a rejected install.
+ */
+function readAilkModuleManifest(extractedRoot) {
+    const manifestPath = join(extractedRoot, AILK_MODULE_JSON);
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch {
+        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, subject) {
+    for (const [source, destination] of Object.entries(installMap)) {
+        if (hasUnsafeSegment(source)) {
+            throw new Error(`${subject}: unsafe installMap source "${source}"`);
+        }
+        const sourceAbs = resolve(extractedRoot, source);
+        if (!isPathInside(extractedRoot, sourceAbs)) {
+            throw new Error(`${subject}: installMap source "${source}" resolves outside staging`);
+        }
+        let sourceStat;
+        try {
+            sourceStat = statSync(sourceAbs);
+        }
+        catch {
+            throw new Error(`${subject}: installMap source "${source}" is not a file the bundle produced`);
+        }
+        if (!sourceStat.isFile()) {
+            throw new Error(`${subject}: installMap source "${source}" is not a file the bundle produced`);
+        }
+        if (hasUnsafeSegment(destination)) {
+            throw new Error(`${subject}: unsafe installMap destination "${destination}"`);
+        }
+        const destAbs = resolve(targetAbs, destination);
+        if (!isPathInside(targetAbs, destAbs)) {
+            throw new Error(`${subject}: installMap destination "${destination}" resolves outside target`);
+        }
+    }
+}
+/**
+ * Validate every `patches` entry against `targetDir` — the same fail-closed
+ * point and containment guard `validateInstallMap` above uses, extended
+ * (spec 5418 § 3 D6): `target` must resolve inside `targetDir`; `kind` and
+ * every `op.op` must be a recognized vocabulary member. Any violation
+ * refuses the WHOLE bundle before `copyTree` runs — this is D4 class 4
+ * (unknown kind/op), resolved here at validation time, never inside
+ * `applyModulePatches` (which never sees an invalid kind/op).
+ */
+function validatePatches(patches, targetAbs, subject) {
+    for (const patch of patches) {
+        if (hasUnsafeSegment(patch.target)) {
+            throw new Error(`${subject}: unsafe patch target "${patch.target}"`);
+        }
+        const targetAbsPath = resolve(targetAbs, patch.target);
+        if (!isPathInside(targetAbs, targetAbsPath)) {
+            throw new Error(`${subject}: patch target "${patch.target}" resolves outside target`);
+        }
+        const validOps = VALID_OPS_BY_KIND[patch.kind];
+        if (!validOps) {
+            throw new Error(`invalid module manifest: unknown patch kind "${patch.kind}" for target ${patch.target}`);
+        }
+        for (const op of patch.ops) {
+            if (!validOps.has(op.op)) {
+                throw new Error(`invalid module manifest: unknown patch op "${op.op}" for target ${patch.target}`);
+            }
+        }
+    }
+}
+/** 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, "");
+}
 /**
  * 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 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}`);
@@ -58,23 +275,114 @@ export async function extractModuleBundle(options) {
         writeFileSync(stagingTar, bytes);
         const extractedRoot = join(stagingDir, "extracted");
         mkdirSync(extractedRoot, { recursive: true });
-        await safeExtractTarGz(stagingTar, extractedRoot, moduleName);
-        // Full validation passed — merge into 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.
-        copyTree(extractedRoot, targetAbs);
+        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 } : {}),
+        });
     }
     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. Runs ONLY after `safeExtractTarGz` has validated
- * every entry, so no additional path-safety check is needed here — `srcRoot`
- * is our own staging tree, not attacker-controlled input.
+ * directories as needed, except any path in `excluded` (relative to
+ * `srcRoot`, POSIX-normalized) — the bundle manifest and any `installMap`
+ * source, which land only at their mapped destination. Runs ONLY after
+ * `safeExtractTarGz` has validated every entry, so no additional
+ * path-safety check is needed here — `srcRoot` is our own staging tree, not
+ * attacker-controlled input.
  */
-function copyTree(srcRoot, destRoot) {
+function copyTree(srcRoot, destRoot, excluded = new Set()) {
     const stack = [srcRoot];
     while (stack.length > 0) {
         const dir = stack.pop();
@@ -89,6 +397,8 @@ function copyTree(srcRoot, destRoot) {
                 stack.push(srcPath);
             }
             else if (entry.isFile()) {
+                if (excluded.has(rel.split(sep).join("/")))
+                    continue;
                 mkdirSync(join(destPath, ".."), { recursive: true });
                 copyFileSync(srcPath, destPath);
             }
@@ -101,14 +411,14 @@ function copyTree(srcRoot, destRoot) {
  * 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;
     };
@@ -171,14 +481,3 @@ async function safeExtractTarGz(tarGzPath, targetDir, moduleName) {
         throw captured.error;
     }
 }
-/** True iff `child` is the same path as `parent` or a descendant of it. */
-function isPathInside(parent, child) {
-    const rel = relative(parent, child);
-    if (rel === "")
-        return true;
-    if (rel.startsWith(".."))
-        return false;
-    if (isAbsolute(rel))
-        return false;
-    return true;
-}

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

@@ -1,47 +1,12 @@
-/**
- * Authenticated paid-module-bundle fetch (K1, #5089 — Flavor 3).
- *
- * Posture lifted verbatim from `packages/cli/src/lib/fetch-bundle.ts`
- * (`fetchBundle`, the skill-registry twin of this function):
- *   - Bearer-JWT auth on every request.
- *   - `redirect: "error"` so a maliciously redirected response can't drop us
- *     onto an unintended host — the CLI must hit the configured module
- *     distribution only.
- *   - Empty-token guard before any network call (defense in depth — the
- *     caller should already have gated on an empty/absent key).
- *   - Status-code mapping: 401 → license invalid/revoked/lapsed, 404 →
- *     module content not yet available, other 4xx/5xx → upstream body.
- *
- * Deliberately DOES NOT depend on `@working-theory/license` or
- * `@working-theory/cli` — both are `publishConfig.access: "restricted"` and
- * `create-ailk` is the one package in this monorepo published to PUBLIC npm
- * (Apache-2.0, A1 disposed it `oss`). A runtime dependency on a restricted
- * package would break `pnpm install` for every free-tier consumer, not just
- * gate the paid modules — so this file re-states fetchBundle's POSTURE
- * rather than importing it. Named in the K1 PR body as the public-package
- * boundary this card had to draw.
- *
- * Also deliberately skips fetchBundle's caller-side `checkLicense()` local
- * JWT pre-check (install-skill.ts's step 2): that local verification lives
- * in `@working-theory/license`, which for the same publish-boundary reason
- * above cannot be a runtime dependency here. Instead the module distribution
- * endpoint's own 401 response IS the license verdict — exactly the signal
- * `fetchBundle` already surfaces via `isLicenseError`. This trades one local,
- * no-network check for one authoritative, server-verified one; the caller-
- * visible contract (present-but-invalid key ⟹ the honest "does not cover
- * this" message) is unchanged.
- *
- * Returns the response body bytes on 200; throws a descriptive
- * `FetchModuleError` on any failure path so the caller can map to an honest
- * exit uniformly.
- */
 export declare const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
 export interface FetchModuleOptions {
     moduleName: string;
     /** JWT used as `Authorization: Bearer <token>`. Must be non-empty. */
     token: string;
-    /** Registry root; the module name is appended as a single path segment. */
+    /** Registry root; `<name>/<version>` is appended as two path segments. */
     registryUrl?: string;
+    /** The module 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;
 }

package/dist/lib/fetch-module.js

@@ -35,7 +35,20 @@
  * `FetchModuleError` on any failure path so the caller can map to an honest
  * exit uniformly.
  */
+import pkg from "../../package.json" with { type: "json" };
 export const DEFAULT_AILK_MODULE_REGISTRY_URL = "https://ailaunchkit.ai/api/modules";
+/**
+ * This package's own `package.json` `"version"`. Deliberately a static JSON
+ * import (`resolveJsonModule`), not `import.meta.url` + `fileURLToPath` (the
+ * technique `cli.ts:56-58`'s `readPackageVersion` uses) — `fetch-module.ts`
+ * is loaded directly by `fetch-module.test.ts`, and `import.meta` is a
+ * SyntaxError under ts-jest's CommonJS transform (the same reason
+ * `module-architecture.ts`'s `paidModuleTemplateExclusions` doc gives for
+ * avoiding it in any jest-reachable file). A bundle overlays the scaffold
+ * `create-ailk` just copied from its own `templates/`, so the default
+ * version request must be the running package's own.
+ */
+const CREATE_AILK_VERSION = pkg.version;
 export class FetchModuleError extends Error {
     isLicenseError;
     constructor(message, 
@@ -47,25 +60,26 @@ export class FetchModuleError extends Error {
     }
 }
 /**
- * Build the fetch URL by joining `registryUrl` with `moduleName` as a single
- * trailing path segment. `encodeURIComponent` on the module name is defense
- * in depth — `parse-args.ts`'s `parseModules` already restricts the value to
- * `RECOGNIZED_MODULES`, but a hostile value can never smuggle a path
- * separator or query string here regardless.
+ * Build the fetch URL by joining `registryUrl` with `moduleName` and
+ * `version` as two trailing path segments. `encodeURIComponent` on each is
+ * defense in depth — `parse-args.ts`'s `parseModules` already restricts
+ * `moduleName` to `RECOGNIZED_MODULES`, but a hostile value can never smuggle
+ * a path separator or query string here regardless.
  */
-function buildUrl(registryUrl, moduleName) {
+function buildUrl(registryUrl, moduleName, version) {
     const trimmed = registryUrl.replace(/\/+$/, "");
-    return `${trimmed}/${encodeURIComponent(moduleName)}`;
+    return `${trimmed}/${encodeURIComponent(moduleName)}/${encodeURIComponent(version)}`;
 }
 export async function fetchModule(options) {
     const { moduleName, token } = options;
     if (token.length === 0) {
         throw new FetchModuleError("internal error: fetchModule called without a token");
     }
+    const version = options.version ?? CREATE_AILK_VERSION;
     const registryUrl = options.registryUrl ??
         process.env["AILK_MODULE_REGISTRY_URL"] ??
         DEFAULT_AILK_MODULE_REGISTRY_URL;
-    const url = buildUrl(registryUrl, moduleName);
+    const url = buildUrl(registryUrl, moduleName, version);
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     let response;
     try {
@@ -86,6 +100,10 @@ export async function fetchModule(options) {
         throw new FetchModuleError(`your licence does not cover the "${moduleName}" module (invalid, revoked, or lapsed)`, 
         /* isLicenseError */ true);
     }
+    if (response.status === 403) {
+        throw new FetchModuleError(`your licence does not include the "${moduleName}" module, 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 FetchModuleError(`"${moduleName}" module content not yet available — ping us at hello@ailaunchkit.ai`);
     }

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>;