create-ailk 0.7.0 → 0.9.0

package/dist/lib/design-checks.d.ts

@@ -0,0 +1,78 @@
+/** One row of theme's contrast audit, as the audit script prints it. */
+export interface ContrastRow {
+    name: string;
+    bg: string;
+    fg: string;
+    ratio: number | null;
+    threshold: number;
+    status: "pass" | "fail" | "unmeasurable";
+}
+export type DesignContrastVerdict = {
+    ok: true;
+    pairs: number;
+} | {
+    ok: false;
+    pairs: number;
+    failing: ContrastRow[];
+    reason: string;
+};
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export declare function assessDesignContrast(design: string, results: ContrastRow[]): DesignContrastVerdict;
+/** `__tests__/fixtures/page-jsonld.ts`'s stdout: page path → its composed JSON-LD. */
+export type ComposedPages = Record<string, {
+    jsonld: string;
+    sectionsValid: boolean;
+}>;
+/** One changed node: the page and its JSON-pointer path (or a `(page …)` pseudo-path). */
+export interface DriftNode {
+    page: string;
+    path: string;
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export declare function jsonLdDrift(before: ComposedPages, after: ComposedPages): DriftNode[];
+export type JsonLdDriftVerdict = {
+    ok: true;
+    pages: number;
+} | {
+    ok: false;
+    pages: number;
+    changed: DriftNode[];
+    reason: string;
+};
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export declare function assessJsonLdDrift(design: string, before: ComposedPages, after: ComposedPages): JsonLdDriftVerdict;
+export interface MeasureApplyDesignDriftOptions {
+    /** create-ailk's built `dist/cli.js`. */
+    cliPath: string;
+    /** The monorepo's `tsx` binary. */
+    tsxPath: string;
+    /** `__tests__/fixtures/page-jsonld.ts` — the one production composer, run from source. */
+    composerPath: string;
+    /** Its tsconfig, passed as `TSX_TSCONFIG_PATH`. */
+    composerTsconfig: string;
+    /** The design `apply-design` applies (a name or a package path). */
+    design: string;
+    /** An existing empty directory; the drift site is scaffolded at `<workDir>/site`. */
+    workDir: string;
+    /** The loopback registry the CLI resolves modules and templates from. */
+    registryUrl?: string;
+    /** Written to the site's own `ailk.key`, which `apply-design` gates a non-Free design on. */
+    licenseKey?: string;
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export declare function measureApplyDesignDrift(opts: MeasureApplyDesignDriftOptions): {
+    before: ComposedPages;
+    after: ComposedPages;
+    applyStdout: string;
+};

package/dist/lib/design-checks.js

@@ -0,0 +1,174 @@
+/**
+ * The two design checks a design-wearing run of `scripts/verify-scaffold.mjs`
+ * runs before install (#6823, spec
+ * docs/specs/6823-the-matrix-runs-the-derived-spec.md D3).
+ *
+ * CONTRAST — `assessDesignContrast` turns the rows
+ * `packages/theme/scripts/audit-site-theme-contrast.ts` prints (theme's
+ * `auditTokenSetContrast` over the design's derived token set) into a verdict
+ * naming every non-passing `{bg, fg}` pair and the design. The WCAG math and
+ * the pair list stay theme's; this file only decides pass/fail.
+ *
+ * DRIFT — `jsonLdDrift` / `assessJsonLdDrift` compare every page's composed
+ * JSON-LD before and after `apply-design`, excluding the logo image (the PRD
+ * metric "structural drift after apply"), and `measureApplyDesignDrift`
+ * gathers the two snapshots (the `renderRoute` precedent, #6821 D4): it
+ * touches the filesystem and processes only through the paths it is handed,
+ * so the driver and `__tests__/verify-scaffold-checks.test.ts` run the same
+ * procedure. Nothing here imports `@working-theory/theme`.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+function describePair(row) {
+    const measured = row.status === "unmeasurable" || row.ratio === null
+        ? "unmeasurable"
+        : `${row.ratio.toFixed(2)}:1 < ${row.threshold}:1`;
+    return `${row.name} {bg ${row.bg}, fg ${row.fg}} ${measured}`;
+}
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export function assessDesignContrast(design, results) {
+    const pairs = results.length;
+    if (pairs === 0) {
+        return { ok: false, pairs, failing: [], reason: `design ${design}: no contrast pair was audited` };
+    }
+    const failing = results.filter((row) => row.status !== "pass");
+    if (failing.length === 0)
+        return { ok: true, pairs };
+    return {
+        ok: false,
+        pairs,
+        failing,
+        reason: `design ${design}: ${failing.length} of ${pairs} contrast pair(s) below WCAG AA — ${failing
+            .map(describePair)
+            .join("; ")}`,
+    };
+}
+/** schema.org's logo property — the one subtree the PRD's "excluding the logo image" skips. */
+const LOGO_KEY = "logo";
+const kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+function walk(before, after, path, out) {
+    const kind = kindOf(before);
+    if (kind !== kindOf(after)) {
+        out.push(path);
+        return;
+    }
+    if (kind === "array") {
+        const a = before;
+        const b = after;
+        if (a.length !== b.length)
+            out.push(path);
+        for (let i = 0; i < Math.min(a.length, b.length); i++)
+            walk(a[i], b[i], `${path}/${i}`, out);
+        return;
+    }
+    if (kind === "object") {
+        const a = before;
+        const b = after;
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+            if (key === LOGO_KEY)
+                continue;
+            walk(a[key], b[key], `${path}/${key}`, out);
+        }
+        return;
+    }
+    if (before !== after)
+        out.push(path);
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export function jsonLdDrift(before, after) {
+    const nodes = [];
+    for (const page of [...new Set([...Object.keys(before), ...Object.keys(after)])]) {
+        const b = before[page];
+        const a = after[page];
+        if (a === undefined) {
+            nodes.push({ page, path: "(page removed)" });
+        }
+        else if (b === undefined) {
+            nodes.push({ page, path: "(page added)" });
+        }
+        else if (!a.sectionsValid) {
+            nodes.push({ page, path: "(sections invalid)" });
+        }
+        else {
+            const paths = [];
+            walk(JSON.parse(b.jsonld), JSON.parse(a.jsonld), "", paths);
+            for (const path of paths)
+                nodes.push({ page, path: path === "" ? "/" : path });
+        }
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return nodes.sort((x, y) => cmp(x.page, y.page) || cmp(x.path, y.path));
+}
+/** How many changed nodes a drift reason lists before it stops. */
+const REASON_NODE_LIMIT = 10;
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export function assessJsonLdDrift(design, before, after) {
+    const pages = Object.keys(before).length;
+    if (pages === 0) {
+        return { ok: false, pages, changed: [], reason: `design ${design}: no page was composed` };
+    }
+    const changed = jsonLdDrift(before, after);
+    if (changed.length === 0)
+        return { ok: true, pages };
+    const listed = changed
+        .slice(0, REASON_NODE_LIMIT)
+        .map((n) => `${n.page} ${n.path}`)
+        .join("; ");
+    return {
+        ok: false,
+        pages,
+        changed,
+        reason: `design ${design}: ${changed.length} JSON-LD node(s) changed by apply-design — ${listed}${changed.length > REASON_NODE_LIMIT ? "; …" : ""}`,
+    };
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export function measureApplyDesignDrift(opts) {
+    const baseEnv = { ...process.env };
+    delete baseEnv["AILK_LICENSE_KEY"];
+    const registryEnv = opts.registryUrl === undefined
+        ? {}
+        : { AILK_MODULE_REGISTRY_URL: opts.registryUrl, AILK_TEMPLATE_REGISTRY_URL: opts.registryUrl };
+    const site = join(opts.workDir, "site");
+    const exec = (label, cmd, args, env) => {
+        try {
+            return execFileSync(cmd, args, {
+                encoding: "utf8",
+                env: { ...baseEnv, ...env },
+                stdio: ["ignore", "pipe", "pipe"],
+                maxBuffer: 64 * 1024 * 1024,
+            });
+        }
+        catch (err) {
+            const { stderr, message } = err;
+            throw new Error(`drift: ${label} failed: ${(stderr || message || "").trim()}`, { cause: err });
+        }
+    };
+    const compose = (label) => {
+        const stdout = exec(label, opts.tsxPath, [opts.composerPath, site], { TSX_TSCONFIG_PATH: opts.composerTsconfig });
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`drift: ${label} printed no JSON: ${err.message}`, { cause: err });
+        }
+    };
+    exec("scaffold organization-product on standard", process.execPath, [opts.cliPath, site, "--shape", "organization-product", "--design", "standard"], registryEnv);
+    if (opts.licenseKey !== undefined)
+        writeFileSync(join(site, "ailk.key"), `${opts.licenseKey}\n`);
+    const before = compose("compose JSON-LD before apply-design");
+    const applyStdout = exec(`apply-design ${opts.design}`, process.execPath, [opts.cliPath, "apply-design", opts.design, "--target", site], opts.registryUrl === undefined ? {} : { AILK_MODULE_REGISTRY_URL: opts.registryUrl });
+    const after = compose("compose JSON-LD after apply-design");
+    return { before, after, applyStdout };
+}

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

@@ -655,6 +655,11 @@ export function installBundleTree(options) {
  * path-safety check is needed here — `srcRoot` is our own staging tree, not
  * attacker-controlled input.
  *
+ * A directory is created only as the parent of a file actually copied, never
+ * for its own sake: a source directory whose every file is excluded (mapped
+ * away) leaves nothing behind at its original path (#6787 — an empty root
+ * `content/en/blog/` reads as an unregistered page type).
+ *
  * `markers`, when given, is substituted into every TEXT file on the way
  * through (#6460) — see `InstallBundleTreeOptions.markers`.
  */
@@ -669,7 +674,6 @@ function copyTree(srcRoot, destRoot, excluded, markers, policy, report) {
             const rel = relative(srcRoot, srcPath);
             const destPath = join(destRoot, rel);
             if (entry.isDirectory()) {
-                mkdirSync(destPath, { recursive: true });
                 stack.push(srcPath);
             }
             else if (entry.isFile()) {

package/dist/lib/license-key-files.d.ts

@@ -6,6 +6,15 @@ export declare const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
  * describes the rule, never the value.
  */
 export declare function assertLicenseKeyShape(key: string): void;
+/**
+ * Write `content` only when it differs, with mode 0600 either way. An existing
+ * file is tightened BEFORE the write — `mode` applies only on creation, so a
+ * looser pre-existing `.env` would otherwise hold the key for a moment at its
+ * old permissions.
+ */
+export declare function writeOwnerOnly(path: string, content: string): void;
+/** `text` plus `line`, starting on a fresh line. */
+export declare function appendLine(text: string, line: string): string;
 /**
  * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
  * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for

package/dist/lib/license-key-files.js

@@ -48,7 +48,7 @@ export function assertLicenseKeyShape(key) {
  * looser pre-existing `.env` would otherwise hold the key for a moment at its
  * old permissions.
  */
-function writeOwnerOnly(path, content) {
+export function writeOwnerOnly(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     if (existsSync(path))
         chmodSync(path, 0o600);
@@ -58,7 +58,7 @@ function writeOwnerOnly(path, content) {
     chmodSync(path, 0o600);
 }
 /** `text` plus `line`, starting on a fresh line. */
-function appendLine(text, line) {
+export function appendLine(text, line) {
     const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
     return `${text}${sep}${line}\n`;
 }

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

@@ -16,8 +16,13 @@
  * `resolvePaidModules` returns immediately, before touching `process.env` or
  * the network, so a bare/all-Free scaffold is provably unaffected by this
  * gate (K1's regression floor).
+ *
+ * Also carries the design gate (#6760): `assertDesignAllowed` refuses a
+ * non-`standard` design at the `free` level, naming the design and the
+ * run's level, before `scaffold()`'s first disk write.
  */
 import type { ModuleName } from "../parse-args.js";
+import { type Level } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
  * `/pro` route and there will not be one (#6439, operator decision OD-2) —
@@ -33,6 +38,29 @@ export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 export declare class LicenseRequiredError extends Error {
     constructor(message: string);
 }
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
+export declare const FREE_DESIGNS: readonly string[];
+/** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
+export declare const DESIGN_LEVELS: readonly Level[];
+/**
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
+ */
+export declare function assertDesignAllowed(design: string | undefined, level: Level, free?: boolean): void;
 export interface ResolvePaidModulesOptions {
     /** The requested module set's paid subset (see `module-tier.ts`). */
     paidModules: ModuleName[];
@@ -52,7 +80,20 @@ export interface ResolvePaidModulesOptions {
      * to do. Absent ⟹ a plain `--modules` run, whose messages are unchanged.
      */
     templateName?: string;
+    /**
+     * The key's derived level (#6759 D5), when one was derived on this call's
+     * path. Absent on the `--modules`-keep branch, where no level is derived
+     * (NFR-2) — the refusal then names only the module and its own level,
+     * never the caller's.
+     */
+    level?: Level;
 }
+/**
+ * The message phrase for one module (D5): what level includes it, or that it
+ * is an add-on. Pure — derived from `levelOf`, never from the current run's
+ * own derived level.
+ */
+export declare function levelPhrase(m: ModuleName): string;
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw
  * `LicenseRequiredError` naming exactly why the run cannot proceed. Never
@@ -61,3 +102,51 @@ export interface ResolvePaidModulesOptions {
  * BEFORE the scaffold copy — see `programmatic.ts`'s `scaffold()`).
  */
 export declare function resolvePaidModules(options: ResolvePaidModulesOptions): Promise<Map<ModuleName, Uint8Array>>;
+/** Inputs shared by `deriveLevel` and `resolveModuleSet` (D4/D5). */
+export interface GateOptions {
+    /** Defaults to `process.env["AILK_LICENSE_KEY"]`. Injectable for tests. */
+    licenseKey?: string | undefined;
+    /** Forwarded to `fetchModule`; defaults to `AILK_MODULE_REGISTRY_URL` / the built-in default. */
+    registryUrl?: string;
+    /** Forwarded to `fetchModule`; defaults to this package's own version. */
+    version?: string;
+    /** Forwarded to `fetchModule`; defaults to `globalThis.fetch`. Never a live call in tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Derive the key's level from what the registry actually answers (D4) — the
+ * level only chooses which modules to ASK FOR; every byte is still
+ * authorized by the registry per module. Nothing client-side is an
+ * entitlement claim: the JWT is never parsed here.
+ *
+ * No key ⟹ `"free"`, zero network. A present key is shape-checked first,
+ * whichever source it came from (SEC-2). Then: probe every paid member of
+ * `LEVEL_MODULES.pro`, in order — a licence error on any of them is refused
+ * (a key that does not unlock all of Pro is not silently downgraded); any
+ * other failure (404, 5xx, unreachable) is wrapped so the caller sees it
+ * could not determine the level, and is told the escape hatch (`--modules`).
+ * Then probe `multi-tenant` (what Pro Plus adds beyond Pro): a licence error
+ * there is the expected "this key is Pro, not Pro Plus" answer, not a
+ * refusal.
+ */
+export declare function deriveLevel(options: GateOptions): Promise<{
+    level: Level;
+    bundles: Map<ModuleName, Uint8Array>;
+}>;
+/**
+ * The one entry point that turns `--modules` + the key into the effective
+ * module set and its resolved bundles (D5) — `programmatic.ts`'s `scaffold()`
+ * calls this for every run except a named `--template` alias (NFR-4).
+ *
+ * A named list with a non-addition (the KEEP branch, D2) resolves it exactly
+ * as today, with no level derived and no extra request (NFR-2). Otherwise the
+ * level is derived first, the set composed from it, and any named addition
+ * not already fetched during the level probe is resolved on top.
+ */
+export declare function resolveModuleSet(options: GateOptions & {
+    named?: readonly ModuleName[] | undefined;
+}): Promise<{
+    modules: ModuleName[];
+    bundles: Map<ModuleName, Uint8Array>;
+    level?: Level;
+}>;

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

@@ -1,4 +1,6 @@
 import { FetchModuleError, fetchModule } from "./fetch-module.js";
+import { assertLicenseKeyShape } from "./license-key-files.js";
+import { ADD_ONS, LEVEL_LABEL, LEVEL_MODULES, OPT_IN_MODULES, PAID_MODULES, classifyModules, composeModuleSet, levelOf, } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
  * `/pro` route and there will not be one (#6439, operator decision OD-2) —
@@ -17,6 +19,64 @@ export class LicenseRequiredError extends Error {
         this.name = "LicenseRequiredError";
     }
 }
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
+export const FREE_DESIGNS = ["standard"];
+/** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
+export const DESIGN_LEVELS = ["pro", "pro-plus"];
+/**
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
+ */
+export function assertDesignAllowed(design, level, free = design !== undefined && FREE_DESIGNS.includes(design)) {
+    if (design === undefined || free)
+        return;
+    if (DESIGN_LEVELS.includes(level))
+        return;
+    throw new LicenseRequiredError(`design "${design}" is a Pro feature — this run's licence level is ${LEVEL_LABEL[level]}; pass --license <key> or set AILK_LICENSE_KEY with a Pro or Pro Plus key → ${CONVERSION_HINT_URL}`);
+}
+/**
+ * The message phrase for one module (D5): what level includes it, or that it
+ * is an add-on. Pure — derived from `levelOf`, never from the current run's
+ * own derived level.
+ */
+export function levelPhrase(m) {
+    const level = levelOf(m);
+    if (level === "add-on") {
+        return `"${m}" is an add-on, bought on top of Pro or Pro Plus`;
+    }
+    if (level === "free") {
+        return `"${m}" is included at ${LEVEL_LABEL.free}`;
+    }
+    return `"${m}" is included at ${LEVEL_LABEL[level]}`;
+}
+/** M1 / M1t (D5): the no-key refusal, with or without a named template. */
+function noKeyMessage(paidModules, templateName) {
+    const phrases = paidModules.map((m) => levelPhrase(m)).join("; ");
+    const intro = templateName !== undefined
+        ? `template "${templateName}" needs a licence: ${phrases}`
+        : `no licence key, so this is a Free scaffold: ${phrases}`;
+    return `${intro} — set AILK_LICENSE_KEY first → ${CONVERSION_HINT_URL}`;
+}
+/** M2 (D5): a key the registry rejected for one module. */
+function licenseErrorMessage(err, moduleName, templateName, level) {
+    const templateSuffix = templateName !== undefined ? ` (required by template "${templateName}")` : "";
+    const levelSuffix = level !== undefined ? ` — your licence is at ${LEVEL_LABEL[level]}` : "";
+    return `${err.message}; ${levelPhrase(moduleName)}${templateSuffix}${levelSuffix} → ${CONVERSION_HINT_URL}`;
+}
 /**
  * Resolve every requested paid module to its fetched bundle bytes, or throw
  * `LicenseRequiredError` naming exactly why the run cannot proceed. Never
@@ -33,8 +93,11 @@ 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, options.templateName));
+        throw new LicenseRequiredError(noKeyMessage(paidModules, options.templateName));
     }
+    // SEC-2 — the `--license` flag and the env var are validated alike,
+    // whichever source this token came from, before it reaches a request.
+    assertLicenseKeyShape(token);
     const bundles = new Map();
     for (const moduleName of paidModules) {
         try {
@@ -55,11 +118,9 @@ export async function resolvePaidModules(options) {
             if (err instanceof FetchModuleError) {
                 if (err.isLicenseError) {
                     // 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}`);
+                    // does not cover; the template and level are appended so the buyer
+                    // can see WHICH of the things they asked for needs it.
+                    throw new LicenseRequiredError(licenseErrorMessage(err, moduleName, options.templateName, options.level));
                 }
                 // Not a license-gating signal (e.g. 404 "not yet available", or the
                 // registry unreachable) — a generic failure, not the honest-denial
@@ -72,10 +133,108 @@ export async function resolvePaidModules(options) {
     }
     return bundles;
 }
-function conversionHint(paidModules, templateName) {
-    const list = paidModules.join(", ");
-    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}`;
+function forward(options) {
+    return {
+        ...(options.registryUrl !== undefined ? { registryUrl: options.registryUrl } : {}),
+        ...(options.version !== undefined ? { version: options.version } : {}),
+        ...(options.fetchImpl !== undefined ? { fetchImpl: options.fetchImpl } : {}),
+    };
+}
+/**
+ * Derive the key's level from what the registry actually answers (D4) — the
+ * level only chooses which modules to ASK FOR; every byte is still
+ * authorized by the registry per module. Nothing client-side is an
+ * entitlement claim: the JWT is never parsed here.
+ *
+ * No key ⟹ `"free"`, zero network. A present key is shape-checked first,
+ * whichever source it came from (SEC-2). Then: probe every paid member of
+ * `LEVEL_MODULES.pro`, in order — a licence error on any of them is refused
+ * (a key that does not unlock all of Pro is not silently downgraded); any
+ * other failure (404, 5xx, unreachable) is wrapped so the caller sees it
+ * could not determine the level, and is told the escape hatch (`--modules`).
+ * Then probe `multi-tenant` (what Pro Plus adds beyond Pro): a licence error
+ * there is the expected "this key is Pro, not Pro Plus" answer, not a
+ * refusal.
+ */
+export async function deriveLevel(options) {
+    const token = options.licenseKey ?? process.env["AILK_LICENSE_KEY"];
+    if (token === undefined || token.length === 0) {
+        return { level: "free", bundles: new Map() };
+    }
+    assertLicenseKeyShape(token);
+    const bundles = new Map();
+    const proModules = LEVEL_MODULES.pro.filter((m) => PAID_MODULES.includes(m));
+    for (const moduleName of proModules) {
+        try {
+            const bytes = await fetchModule({ moduleName, token, ...forward(options) });
+            bundles.set(moduleName, bytes);
+        }
+        catch (err) {
+            if (err instanceof FetchModuleError) {
+                if (err.isLicenseError) {
+                    throw new LicenseRequiredError(licenseErrorMessage(err, moduleName));
+                }
+                throw new FetchModuleError(`could not determine your licence level: ${err.message} — name the modules you want with --modules`);
+            }
+            throw err;
+        }
+    }
+    try {
+        const bytes = await fetchModule({
+            moduleName: "multi-tenant",
+            token,
+            ...forward(options),
+        });
+        bundles.set("multi-tenant", bytes);
+        return { level: "pro-plus", bundles };
+    }
+    catch (err) {
+        if (err instanceof FetchModuleError) {
+            if (err.isLicenseError) {
+                return { level: "pro", bundles };
+            }
+            throw new FetchModuleError(`could not determine your licence level: ${err.message} — name the modules you want with --modules`);
+        }
+        throw err;
+    }
+}
+/**
+ * The one entry point that turns `--modules` + the key into the effective
+ * module set and its resolved bundles (D5) — `programmatic.ts`'s `scaffold()`
+ * calls this for every run except a named `--template` alias (NFR-4).
+ *
+ * A named list with a non-addition (the KEEP branch, D2) resolves it exactly
+ * as today, with no level derived and no extra request (NFR-2). Otherwise the
+ * level is derived first, the set composed from it, and any named addition
+ * not already fetched during the level probe is resolved on top.
+ */
+export async function resolveModuleSet(options) {
+    const namedList = options.named ?? [];
+    const additions = [...ADD_ONS, ...OPT_IN_MODULES];
+    const isKeep = namedList.some((m) => !additions.includes(m));
+    if (isKeep) {
+        const modules = composeModuleSet(namedList, "free");
+        const { paid } = classifyModules(modules);
+        const bundles = await resolvePaidModules({
+            paidModules: paid,
+            licenseKey: options.licenseKey,
+            ...forward(options),
+        });
+        return { modules, bundles };
+    }
+    const { level, bundles } = await deriveLevel(options);
+    const modules = composeModuleSet(namedList, level);
+    const { paid } = classifyModules(modules);
+    const missing = paid.filter((m) => !bundles.has(m));
+    if (missing.length > 0) {
+        const extra = await resolvePaidModules({
+            paidModules: missing,
+            licenseKey: options.licenseKey,
+            level,
+            ...forward(options),
+        });
+        for (const [k, v] of extra)
+            bundles.set(k, v);
+    }
+    return { modules, bundles, level };
 }