create-ailk 0.6.1 → 0.8.0

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,53 @@ export class LicenseRequiredError extends Error {
         this.name = "LicenseRequiredError";
     }
 }
+/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+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-`standard` design at a level below Pro (#6760 D1, D6). 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).
+ */
+export function assertDesignAllowed(design, level) {
+    if (design === undefined || FREE_DESIGNS.includes(design))
+        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 +82,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 +107,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 +122,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 };
 }

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

@@ -1,19 +1,3 @@
-/**
- * Free vs paid module classification (K1, #5089 — REL-015.3 "AI Launch Kit —
- * Commercial line", D-17 "Flavor 3").
- *
- * The commercial line is decided: the paid modules do NOT ship on public npm
- * — delivery itself is the gate. `create-ailk` scaffolds Free's modules from
- * `templates/` with no key (today's path, unchanged); a paid module is
- * FETCHED from the internal module distribution when `AILK_LICENSE_KEY`
- * verifies (see `fetch-module.ts` + `module-license-gate.ts`).
- *
- * `FREE_MODULES` is the one hand-authored list (today just `marketing`, the
- * always-available default). `PAID_MODULES` is derived from it — every other
- * `RECOGNIZED_MODULES` entry — so adding a new module to the vocabulary
- * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
- * to `FREE_MODULES`, rather than silently shipping it free.
- */
 import { type ModuleName } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export declare const FREE_MODULES: readonly ModuleName[];
@@ -24,6 +8,51 @@ export declare const FREE_MODULES: readonly ModuleName[];
  * from `RECOGNIZED_MODULES` silently.
  */
 export declare const PAID_MODULES: readonly ModuleName[];
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export declare const LEVELS: readonly ["free", "pro", "pro-plus"];
+export type Level = (typeof LEVELS)[number];
+export declare const LEVEL_LABEL: Readonly<Record<Level, string>>;
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export declare const ADD_ONS: readonly ModuleName[];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export declare const OPT_IN_MODULES: readonly ModuleName[];
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export declare const LEVEL_MODULES: Readonly<Record<Level, readonly ModuleName[]>>;
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export declare function levelOf(m: ModuleName): Level | "add-on";
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export declare function composeModuleSet(named: readonly ModuleName[] | undefined, level: Level): ModuleName[];
 export interface ModuleClassification {
     free: ModuleName[];
     paid: ModuleName[];

package/dist/lib/module-tier.js

@@ -14,6 +14,7 @@
  * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
  * to `FREE_MODULES`, rather than silently shipping it free.
  */
+import { normalizeModules } from "../module-architecture.js";
 import { RECOGNIZED_MODULES } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export const FREE_MODULES = ["marketing"];
@@ -24,6 +25,81 @@ export const FREE_MODULES = ["marketing"];
  * from `RECOGNIZED_MODULES` silently.
  */
 export const PAID_MODULES = RECOGNIZED_MODULES.filter((m) => !FREE_MODULES.includes(m));
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export const LEVELS = ["free", "pro", "pro-plus"];
+export const LEVEL_LABEL = {
+    free: "Free",
+    pro: "Pro",
+    "pro-plus": "Pro Plus",
+};
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export const ADD_ONS = ["commerce"];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export const OPT_IN_MODULES = ["workspace"];
+/** The Pro Plus membership: what Pro Plus switches on beyond Pro. */
+const PRO_PLUS_MODULES = ["multi-tenant"];
+/** Named modules that never trim the level default when composing a set (D2). */
+const ADDITIONS = [...ADD_ONS, ...OPT_IN_MODULES];
+const PRO_EXCLUDED = new Set([...ADDITIONS, ...PRO_PLUS_MODULES]);
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export const LEVEL_MODULES = Object.freeze({
+    free: [...FREE_MODULES],
+    pro: RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !PRO_EXCLUDED.has(m))),
+    "pro-plus": RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !ADDITIONS.includes(m))),
+});
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export function levelOf(m) {
+    if (FREE_MODULES.includes(m))
+        return "free";
+    if (ADD_ONS.includes(m))
+        return "add-on";
+    if (PRO_PLUS_MODULES.includes(m))
+        return "pro-plus";
+    return "pro";
+}
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export function composeModuleSet(named, level) {
+    const namedList = [...(named ?? [])];
+    const keep = namedList.filter((m) => !ADDITIONS.includes(m));
+    if (keep.length > 0) {
+        return normalizeModules(namedList);
+    }
+    const add = namedList.filter((m) => ADDITIONS.includes(m));
+    return normalizeModules([...LEVEL_MODULES[level], ...add]);
+}
 /**
  * Split a requested (already-validated, `ModuleName`) module set into its
  * free and paid subsets, each preserving the input's relative order.

package/dist/lib/pro-callout.d.ts

@@ -1,12 +1,18 @@
+export declare function proCallout(): string;
+/** The closing prerequisites note on a free install (#6440 AC4). */
+export declare const FREE_PREREQUISITES_NOTE = "No database, no licence key and no vendor API key are needed to run or build this site.";
 /**
- * `proCallout()` — the AI-guided setup conversion message appended to
- * `pnpm create ailk-app`'s closing summary.
- *
- * Wording is locked in `docs/internal/specs/ailk-onboard-site-spec.md` §2.1 and
- * `docs/internal/specs/ailk-onboard-site-spec.md` §5.1 (Sam-verifiable AC).
- *
- * The message is always shown — no flags, no env gating. Free-tier users
- * see it as a discovery surface for Pro; Pro users see it as a reminder
- * of the `/onboard-site` skill they can install.
+ * The same note on a licensed install (#6480): it drops the licence-key claim,
+ * which would contradict the key the customer just installed with.
  */
-export declare function proCallout(): string;
+export declare const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key are needed to run or build this site.";
+/**
+ * Whether an install delivered paid content — any paid module in the effective
+ * module set, `union(template.requires, --modules)`, the same union
+ * `scaffold()` gates on. A paid template is covered by that union too:
+ * `templateDelivery` derives "paid" from `requires` alone.
+ */
+export declare function isLicensedInstall(opts: {
+    template?: string;
+    modules?: string[];
+}): boolean;

package/dist/lib/pro-callout.js

@@ -5,10 +5,12 @@
  * Wording is locked in `docs/internal/specs/ailk-onboard-site-spec.md` §2.1 and
  * `docs/internal/specs/ailk-onboard-site-spec.md` §5.1 (Sam-verifiable AC).
  *
- * The message is always shown — no flags, no env gating. Free-tier users
- * see it as a discovery surface for Pro; Pro users see it as a reminder
- * of the `/onboard-site` skill they can install.
+ * Shown on a free install only (#6480): it is a discovery surface for Pro,
+ * and a licensed install already owns the tier it pitches.
  */
+import { normalizeModules } from "../module-architecture.js";
+import { SHAPE_STARTERS, resolveTemplate } from "../template-manifest.js";
+import { classifyModules } from "./module-tier.js";
 export function proCallout() {
     return [
         "Want AI-guided setup? Pro's `/onboard-site` interviews you about",
@@ -18,3 +20,32 @@ export function proCallout() {
         "free scaffolders one at a time → ailaunchkit.ai/pricing",
     ].join("\n");
 }
+/** The closing prerequisites note on a free install (#6440 AC4). */
+export const FREE_PREREQUISITES_NOTE = "No database, no licence key and no vendor API key are needed to run or build this site.";
+/**
+ * The same note on a licensed install (#6480): it drops the licence-key claim,
+ * which would contradict the key the customer just installed with.
+ */
+export const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key are needed to run or build this site.";
+/**
+ * Whether an install delivered paid content — any paid module in the effective
+ * module set, `union(template.requires, --modules)`, the same union
+ * `scaffold()` gates on. A paid template is covered by that union too:
+ * `templateDelivery` derives "paid" from `requires` alone.
+ */
+export function isLicensedInstall(opts) {
+    // #6757 D6 row 4 — a bare-shape starter's name (the shape itself, passed
+    // here after #6754 D4 item 3 resolves it) is looked up through
+    // SHAPE_STARTERS first; `resolveTemplate` alone throws `unknown template`
+    // for one (NFR-3).
+    const requires = opts.template !== undefined
+        ? Object.prototype.hasOwnProperty.call(SHAPE_STARTERS, opts.template)
+            ? SHAPE_STARTERS[opts.template].requires
+            : resolveTemplate(opts.template).requires
+        : [];
+    const modules = normalizeModules([
+        ...requires,
+        ...(opts.modules ?? ["marketing"]),
+    ]);
+    return classifyModules(modules).paid.length > 0;
+}

package/dist/license-set.d.ts

@@ -0,0 +1,34 @@
+export interface LicenseSetRunResult {
+    /** Exit status; null when the process never ran or was killed. */
+    status: number | null;
+    /** Set when the process could not be spawned (e.g. `ENOENT`). */
+    error?: NodeJS.ErrnoException;
+}
+/**
+ * Runs `vercel <args>`. The command itself is fixed — a runner is never
+ * handed one to run, per the package's hard-coded-command invariant
+ * (security.test.ts).
+ * `input`, when given, is written to the child's stdin.
+ */
+export type LicenseSetRunner = (args: readonly string[], options: {
+    cwd: string;
+    input?: string;
+}) => LicenseSetRunResult;
+export interface LicenseSetIO {
+    /** Resolves a relative or absent `[dir]`. */
+    cwd: string;
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    /** Reads all of stdin — used only by the `-` form. */
+    readStdin: () => string;
+    /** Defaults to `spawnSync` with `shell: false` (see `defaultRunner`). */
+    runner?: LicenseSetRunner;
+}
+export declare const LICENSE_SET_HELP = "create-ailk license set \u2014 put your licence key into an existing site.\n\nUsage:\n  pnpm create ailk@latest license set <key> [<target-dir>]\n  pnpm create ailk@latest license set - [<target-dir>] < key.txt\n\nArguments:\n  <key>                    Your licence key, or `-` to read it from stdin\n                           (keeps it out of your shell history).\n  <target-dir>             An already-scaffolded repo (contains\n                           architecture.yaml). Defaults to the current dir.\n\nWrites the key to ailk.key and apps/api/.env (owner-only, gitignored). When the\nsite (or apps/api, or apps/web) is linked to Vercel, it also replaces the\nproduction AILK_LICENSE_KEY variable and redeploys.\n";
+/** `spawnSync`, never through a shell; stdin piped only when there is input. */
+export declare const defaultRunner: LicenseSetRunner;
+/**
+ * Run `license set` with `argv` = everything after the `license set` words.
+ * Returns the process exit code; never throws for an expected failure.
+ */
+export declare function runLicenseSet(argv: string[], io: LicenseSetIO): number;