create-ailk 0.6.1 → 0.8.0

package/dist/parse-args.js

@@ -7,7 +7,9 @@
  * On any parse / validation failure: throws ParseError. The orchestrator's
  * top-level catch turns this into a stderr write + non-zero exit.
  */
+import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
+import { assertLicenseKeyShape } from "./lib/license-key-files.js";
 import { RECOGNIZED_SURFACES, parseSurfaces } from "./surfaces.js";
 import { RECOGNIZED_TEMPLATES } from "./template-names.js";
 /**
@@ -28,8 +30,33 @@ export const RECOGNIZED_MODULES = [
     "signal-collectors",
     "commerce",
 ];
-/** The default module selection when `--modules` is absent (reproduces today's scaffold). */
-const DEFAULT_MODULES = ["marketing"];
+/**
+ * Shapes a starter can be built from today (`--shape`, #6754 D1).
+ *
+ * Declared HERE rather than imported from `template-manifest.ts` for the
+ * reason `RECOGNIZED_MODULES` is: importing the registry closes the runtime
+ * cycle `template-names.ts`'s header records. `parse-args.test.ts` pins this
+ * list, `RESERVED_SHAPES` and `RECOGNIZED_DESIGNS` to their authorities
+ * (`STARTER_SHAPES`, `STARTER_DESIGNS`, `SHAPE_ROSTERS`).
+ */
+export const RECOGNIZED_SHAPES = [
+    "organization-product",
+    "organization-service",
+    "local-business-service",
+    "person-service",
+];
+/** Shapes the contract names but no release builds yet. */
+export const RESERVED_SHAPES = ["local-business-product"];
+/** The `--design` vocabulary (#6754 D1) — `STARTER_DESIGNS`, pinned by test. */
+export const RECOGNIZED_DESIGNS = ["standard", "minimalism"];
+/** What each shape is, for the prompt (D3). A shape without one is a type error. */
+const SHAPE_DESCRIPTIONS = {
+    "organization-product": "a company selling a product",
+    "organization-service": "a company selling a service",
+    "local-business-service": "a local business selling a service",
+    "person-service": "a person selling their own service",
+};
+const SHAPE_LIST = RECOGNIZED_SHAPES.join(", ");
 export class ParseError extends Error {
     constructor(message) {
         super(message);
@@ -50,11 +77,31 @@ Arguments:
 Options:
   --modules <csv>          Comma-separated list of modules to compose the site
                            from (recognized: ${RECOGNIZED_MODULES.join(", ")}).
-                           Defaults to \`marketing\`, which reproduces today's
-                           scaffold. A module is a composable unit across the
-                           three tiers (data · API · presentation).
+                           Trims or ADDS relative to the level your licence
+                           key unlocks (#6759) — it never replaces it. With no
+                           key, the level is Free (\`marketing\`). A Pro key
+                           switches on docs-blog, scheduling and
+                           signal-collectors too; Pro Plus adds multi-tenant.
+                           Naming modules here keeps EXACTLY those, trimming
+                           the level's default. Naming only \`commerce\` (a
+                           per-site add-on) or \`workspace\` (included at Pro,
+                           opt-in) ADDS it on top of the level's default
+                           without trimming. A module your licence does not
+                           include is refused, naming the level that does. A
+                           module is a composable unit across the three tiers
+                           (data · API · presentation).
+  --shape <shape>          The kind of site to build (recognized:
+                           ${SHAPE_LIST}).
+                           Installs that shape's Free starter. A run naming
+                           neither --shape nor --template asks for a shape on
+                           a terminal, and refuses without one.
+  --design <design>        The look to render the starter in (recognized:
+                           ${RECOGNIZED_DESIGNS.join(", ")}). Defaults to the
+                           starter's own.
   --template <name>        The site template to install (recognized:
                            ${RECOGNIZED_TEMPLATES.join(", ")}).
+                           A template already fixes its shape and design, so
+                           it cannot be combined with --shape or --design.
                            A template is a page roster plus seed content and
                            config — never code. Its required modules are ADDED
                            to whatever \`--modules\` names, so the two compose.
@@ -73,7 +120,7 @@ Options:
                            Surfaces the declared architecture does not carry are
                            NOT scaffolded — their routes are absent, so a fresh
                            site never serves a stock page with placeholder
-                           content. Add one later with the \`scaffold-page\`
+                           content. Add one later with the \`add-page\`
                            skill, or re-run with the surface named here.
   --sync-architecture <csv> Regenerate architecture.yaml in place in an
                            already-scaffolded repo from the given module set
@@ -93,14 +140,17 @@ Options:
                            file, at the target dir (positional arg, else cwd).
                            Bypasses the scaffold path — copies no template, runs
                            no install. Re-run after upgrading create-ailk.
+  --license <key>          Your licence key: fetch paid modules with it and
+                           write it into the scaffold (apps/api/.env and a
+                           gitignored ailk.key, both owner-only).
   --install                After scaffolding, run \`pnpm install\` in the
                            target directory. Off by default.
   --help, -h               Print this message.
   --version                Print the scaffolder version.
 
 Examples:
-  pnpm create ailk@latest my-site
-  pnpm create ailk@latest /tmp/test-site --install
+  pnpm create ailk@latest my-site --shape organization-product
+  pnpm create ailk@latest /tmp/test-site --template marketing-site-free --install
 
 Next steps after a successful scaffold:
   cd <target-dir>
@@ -109,7 +159,12 @@ Next steps after a successful scaffold:
 
 Reference: ADR 0007 — \`pnpm create ailk@latest\` is the canonical install path.
 `;
-export function parseCliArgs(argv) {
+/**
+ * Parse `create-ailk` argv. `env.interactive` defaults to false —
+ * fail-closed: a caller that does not assert a human is present gets refusal
+ * R1, never a prompt it cannot answer (#6754 D2).
+ */
+export function parseCliArgs(argv, env = { interactive: false }) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -119,6 +174,9 @@ export function parseCliArgs(argv) {
             options: {
                 modules: { type: "string" },
                 template: { type: "string" },
+                shape: { type: "string" },
+                design: { type: "string" },
+                license: { type: "string" },
                 surfaces: { type: "string" },
                 "sync-architecture": { type: "string" },
                 "sync-catalog": { type: "boolean", default: false },
@@ -135,12 +193,18 @@ export function parseCliArgs(argv) {
     const help = parsed.values.help === true;
     const version = parsed.values.version === true;
     const install = parsed.values.install === true;
-    const modules = parseModules(parsed.values.modules);
+    // #6759 D3 — an absent flag stays `undefined` (the key's level decides);
+    // only a PRESENT value goes through `parseModules`.
+    const rawModules = parsed.values.modules;
+    const modules = rawModules === undefined ? undefined : parseModules(rawModules);
     const template = parseTemplate(parsed.values.template);
+    const shape = parseShape(parsed.values.shape);
+    const design = parseDesign(parsed.values.design);
     const surfaces = parseSurfaceList(parsed.values.surfaces);
     const syncArchitecture = parsed.values["sync-architecture"];
     const syncCatalog = parsed.values["sync-catalog"] === true;
     const withCatalog = parsed.values["with-catalog"] === true;
+    const license = parseLicense(parsed.values.license);
     // The two sync modes each exit after rewriting their one file, so asking for
     // both in one invocation has no coherent meaning.
     if (syncCatalog && syncArchitecture !== undefined) {
@@ -157,6 +221,7 @@ export function parseCliArgs(argv) {
         return {
             target: undefined,
             template: undefined,
+            needsShapePrompt: false,
             install,
             help,
             version,
@@ -175,6 +240,7 @@ export function parseCliArgs(argv) {
         return {
             target: parsed.positionals[0],
             template,
+            needsShapePrompt: false,
             install,
             help,
             version,
@@ -191,9 +257,27 @@ export function parseCliArgs(argv) {
     if (parsed.positionals.length > 1) {
         throw new ParseError(`expected exactly one target directory, got ${parsed.positionals.length}`);
     }
+    // R3 — a template already fixes its shape and design.
+    if (template !== undefined && (shape !== undefined || design !== undefined)) {
+        const flags = shape !== undefined && design !== undefined
+            ? "--shape and --design"
+            : shape !== undefined
+                ? "--shape"
+                : "--design";
+        throw new ParseError(`--template cannot be combined with ${flags}: a template already fixes its shape and design. Pass --template alone, or --shape with an optional --design.`);
+    }
+    // R1 — no silent default: with neither a template nor a shape, ask on a
+    // terminal and refuse without one.
+    const needsShapePrompt = template === undefined && shape === undefined;
+    if (needsShapePrompt && !env.interactive) {
+        throw new ParseError(`no shape given, and there is no terminal to ask on. Pass --shape <shape> (one of: ${SHAPE_LIST}), or --template <name>.`);
+    }
     return {
         target: parsed.positionals[0],
         template,
+        ...(shape !== undefined ? { shape } : {}),
+        ...(design !== undefined ? { design } : {}),
+        needsShapePrompt,
         install,
         help,
         version,
@@ -202,8 +286,136 @@ export function parseCliArgs(argv) {
         syncCatalog,
         withCatalog,
         syncArchitecture: undefined,
+        ...(license !== undefined ? { license } : {}),
     };
 }
+/**
+ * Validate `--shape` (#6754 D2 step 2): trimmed and lowercased. A reserved
+ * shape is refusal R2; any other unrecognized value names the recognized set.
+ */
+function parseShape(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim().toLowerCase();
+    if (RESERVED_SHAPES.includes(name)) {
+        throw new ParseError(`shape "${name}" is not available yet. Choose one of: ${SHAPE_LIST}.`);
+    }
+    if (!RECOGNIZED_SHAPES.includes(name)) {
+        throw new ParseError(`unknown shape "${raw}". Recognized: ${SHAPE_LIST}`);
+    }
+    return name;
+}
+/** Validate `--design` (#6754 D2 step 2): trimmed and lowercased. */
+function parseDesign(raw) {
+    if (raw === undefined)
+        return undefined;
+    const name = raw.trim().toLowerCase();
+    if (!RECOGNIZED_DESIGNS.includes(name)) {
+        throw new ParseError(`unknown design "${raw}". Recognized: ${RECOGNIZED_DESIGNS.join(", ")}`);
+    }
+    return name;
+}
+/** How many answers the prompt takes before it gives up. */
+const PROMPT_ATTEMPTS = 3;
+/**
+ * Ask once for a shape (#6754 D3): a number 1–4 or a shape name. A bad answer
+ * re-asks, naming what was wrong; the third bad answer, or a closed input,
+ * throws. There is no default — an empty line is a bad answer.
+ */
+export async function promptForShape(io) {
+    const width = Math.max(...RECOGNIZED_SHAPES.map((s) => s.length));
+    io.output.write([
+        "Which kind of site is this?",
+        ...RECOGNIZED_SHAPES.map((s, i) => `  ${i + 1}) ${s.padEnd(width)}  ${SHAPE_DESCRIPTIONS[s]}`),
+        "",
+    ].join("\n"));
+    const noShape = new ParseError(`no shape chosen. Re-run with --shape <shape> (one of: ${SHAPE_LIST}).`);
+    const rl = createInterface({ input: io.input, terminal: false });
+    // The async iterator buffers every line, so an answer typed (or piped)
+    // ahead of its question is never dropped, and a closed input ends it.
+    const lines = rl[Symbol.asyncIterator]();
+    try {
+        for (let attempt = 0; attempt < PROMPT_ATTEMPTS; attempt++) {
+            io.output.write(`Shape [1-${RECOGNIZED_SHAPES.length} or name]: `);
+            const next = await lines.next();
+            if (next.done === true)
+                throw noShape;
+            const answer = next.value;
+            const picked = pickShape(answer);
+            if (picked !== undefined)
+                return picked;
+            const shown = answer.trim();
+            io.output.write(shown === ""
+                ? "No answer given.\n"
+                : `"${shown}" is not a shape. Answer 1-${RECOGNIZED_SHAPES.length} or a shape name.\n`);
+        }
+        throw noShape;
+    }
+    finally {
+        rl.close();
+    }
+}
+/** A prompt answer as a shape, or undefined when it names none. */
+function pickShape(answer) {
+    const value = answer.trim().toLowerCase();
+    if (/^[0-9]+$/.test(value))
+        return RECOGNIZED_SHAPES[Number(value) - 1];
+    return RECOGNIZED_SHAPES.includes(value)
+        ? value
+        : undefined;
+}
+/**
+ * Fill `opts.shape` by prompting when, and only when, `needsShapePrompt` is
+ * set (#6754 D3). Help, version, sync and every run naming a shape or a
+ * template come back unchanged, with nothing written to `io.output`.
+ */
+export async function resolveCliShape(opts, io) {
+    if (!opts.needsShapePrompt)
+        return opts;
+    const shape = await promptForShape(io);
+    return { ...opts, shape, needsShapePrompt: false };
+}
+/**
+ * The one mapping from parsed flags to `scaffold()` options (#6754 D4).
+ * `template`, `shape`, `design` and `license` are each spread only when set,
+ * so a `--template` run hands `scaffold()` the object it did before #6754.
+ *
+ * @throws ParseError when the shape prompt is unresolved or the target is
+ *   unset — an unresolved prompt must never fall through to the bare overlay.
+ */
+export function toScaffoldOptions(opts) {
+    if (opts.needsShapePrompt) {
+        throw new ParseError(`no shape given. Pass --shape <shape> (one of: ${SHAPE_LIST}), or --template <name>.`);
+    }
+    if (opts.target === undefined) {
+        throw new ParseError("missing target directory. Usage: pnpm create ailk@latest <target-dir>");
+    }
+    return {
+        targetDir: opts.target,
+        surfaces: opts.surfaces,
+        withCatalog: opts.withCatalog,
+        ...(opts.modules !== undefined ? { modules: opts.modules } : {}),
+        ...(opts.template !== undefined ? { template: opts.template } : {}),
+        ...(opts.shape !== undefined ? { shape: opts.shape } : {}),
+        ...(opts.design !== undefined ? { design: opts.design } : {}),
+        ...(opts.license !== undefined ? { license: opts.license } : {}),
+    };
+}
+/**
+ * Shape-check the `--license` value through the one validator `license set`
+ * also uses, re-thrown as a ParseError. The message never repeats the value.
+ */
+function parseLicense(raw) {
+    if (raw === undefined)
+        return undefined;
+    try {
+        assertLicenseKeyShape(raw);
+    }
+    catch (err) {
+        throw new ParseError(`--license: ${err.message}`);
+    }
+    return raw;
+}
 /**
  * Validate the `--template` value against the declared template set
  * (spec 5481 § 3 DD1).
@@ -248,20 +460,20 @@ function parseSurfaceList(raw) {
  * validated, normalized string[].
  *
  * Splits on `,`, trims and lowercases each entry, drops empties, and validates
- * each against RECOGNIZED_MODULES. An absent flag (or an all-empty value)
- * defaults to DEFAULT_MODULES (`['marketing']`) — reproducing today's scaffold.
+ * each against RECOGNIZED_MODULES. Takes a PRESENT value only — an ABSENT
+ * `--modules` flag is `undefined` (#6759 D3: the key's level decides) and
+ * never reaches this function; an all-empty value (`--modules ""`,
+ * `--modules ,`) still names the Free set, spelled inline here.
  *
  * @throws ParseError on an unrecognized module value, naming the recognized set.
  */
 export function parseModules(raw) {
-    if (raw === undefined)
-        return [...DEFAULT_MODULES];
     const requested = raw
         .split(",")
         .map((m) => m.trim().toLowerCase())
         .filter(Boolean);
     if (requested.length === 0)
-        return [...DEFAULT_MODULES];
+        return ["marketing"];
     for (const m of requested) {
         if (!RECOGNIZED_MODULES.includes(m)) {
             throw new ParseError(`unknown module "${m}". Recognized: ${RECOGNIZED_MODULES.join(", ")}`);

package/dist/programmatic.d.ts

@@ -15,10 +15,12 @@
  *   import { scaffoldSync } from './programmatic.js';
  *   const result = scaffoldSync({ targetDir: '/tmp/my-site', projectName: 'my-site' });
  */
+import { type AddModuleResult } from "./add-module.js";
 import { CATALOG_TARGET_PATH } from "./component-catalog.js";
 import { type ModuleName } from "./parse-args.js";
 import { type TemplateLayout } from "./site-chrome.js";
 import { type SyncRoutesResult } from "./sync-routes.js";
+import { type StarterDesign, type StarterShape } from "./template-manifest.js";
 export interface ScaffoldOptions {
     /** Absolute or relative path to the target directory. Must not exist or be empty. */
     targetDir: string;
@@ -34,9 +36,10 @@ export interface ScaffoldOptions {
      *
      * Consumed ONLY by the async `scaffold()` below. `scaffoldSync` stays
      * template-oblivious for exactly the reason it stays licensing-oblivious
-     * (spec 5481 § 3 DD3): a call naming no template takes a code path with no
-     * new statement in it, which is a stronger byte-identity guarantee than a
-     * test asserting the output happens to match.
+     * (spec 5481 § 3 DD3): a call naming neither a template nor a `shape`
+     * takes a code path with no new statement in it — the bare overlay, the
+     * library's default. The CLI never takes that path (#6754 D2: it refuses a
+     * run naming neither, or asks for a shape on a terminal).
      *
      * What a template DOES change is `modules` — `scaffold()` unions the
      * template's `requires` with whatever `--modules` named and passes THAT
@@ -44,6 +47,13 @@ export interface ScaffoldOptions {
      * `architecture.yaml` and the generated nav are all functions of the union.
      */
     template?: string;
+    /**
+     * The starter shape to install (`--shape`, #6754 D5): `scaffold()` resolves
+     * it to the one template of that shape whose delivery is `free`, then runs
+     * exactly as a `template` naming it would. Mutually exclusive with
+     * `template`. A shape with no Free starter yet is refused (D6).
+     */
+    shape?: StarterShape;
     /**
      * Selected modules (recognized: marketing, docs-blog, multi-tenant,
      * scheduling). Defaults to
@@ -84,6 +94,14 @@ export interface ScaffoldOptions {
      * bare/all-Free scaffold reads neither).
      */
     licenseKey?: string;
+    /**
+     * The buyer's licence key (`--license`, #6683 D9). Takes precedence over
+     * `licenseKey` and `AILK_LICENSE_KEY` for bundle fetches, and — unlike
+     * them — is PERSISTED: after a successful scaffold it is written to the
+     * target's `ailk.key` and `apps/api/.env` (`writeLicenseKeyFiles`). Unset,
+     * the scaffold is byte-identical to one made before the option existed.
+     */
+    license?: string;
     /** Overrides `AILK_MODULE_REGISTRY_URL` / the built-in module-distribution default. */
     moduleRegistryUrl?: string;
     /** Overrides `AILK_TEMPLATE_REGISTRY_URL` / the built-in template-distribution default. */
@@ -99,6 +117,16 @@ export interface ScaffoldOptions {
      * caller) writes the same defaults `site-chrome.ts` always has.
      */
     layout?: TemplateLayout;
+    /**
+     * The design whose layout knobs fill what `layout` leaves unset (#6638,
+     * `DESIGN_LAYOUTS`). `scaffold()` sets it from the resolved template's
+     * `design`; a caller may name one to OVERRIDE the template's — the
+     * shape × design pairing `verify-scaffold.mjs --design` renders (#6638
+     * DD-4), and the CLI's `--design` beside `--shape` (#6754). Unset (every
+     * existing `scaffoldSync` caller) resolves exactly as before. Gated
+     * (#6760): a design outside `FREE_DESIGNS` needs a Pro or Pro Plus level.
+     */
+    design?: StarterDesign;
 }
 export interface ScaffoldResult {
     /** Resolved absolute path to the scaffolded directory. */
@@ -107,6 +135,21 @@ export interface ScaffoldResult {
     filesCreated: number;
     /** The gateable route surfaces this scaffold declares (sorted). */
     surfaces: string[];
+    /**
+     * The starter this scaffold resolved (#6754 D5) — set whenever a template
+     * was resolved, from `template` or from `shape`; absent for the bare overlay.
+     */
+    starter?: {
+        template: string;
+        shape: StarterShape;
+        design: StarterDesign;
+    };
+    /**
+     * The effective module set this scaffold installed (#6759 D6) — what
+     * `scaffoldSync` actually received, never the requested `--modules` alone:
+     * a keyed run with no `--modules` carries the key's derived level here.
+     */
+    modules: ModuleName[];
 }
 /**
  * Scaffold an AI Launch Kit starter project into targetDir (synchronous).
@@ -133,8 +176,14 @@ export declare function scaffoldSync(opts: ScaffoldOptions): ScaffoldResult;
  *      its fetched bundle or — when it requires only free modules — from the
  *      `site-templates/` tree this package ships.
  *
- * And, ahead of all five when `opts.template` is set (0): resolve the
- * template and union its `requires` with `opts.modules`, so every step above
+ * Between 2 and 3, `assertDesignAllowed` (#6760) refuses a design the caller
+ * CHOSE (`opts.design`) for a level below Pro, HERE, also before anything is
+ * written to disk. A template's own declared design is never gated (#6778
+ * option (c)): the template's `requires` already decide its level.
+ *
+ * And, ahead of all five when `opts.template` (or `opts.shape`, #6754 D5) is
+ * set (0): resolve the template and union its `requires` with `opts.modules`,
+ * so every step above
  * runs over the EFFECTIVE module set rather than the requested one.
  *
  * `scaffoldSync` itself stays licensing-oblivious on purpose: every existing
@@ -233,6 +282,33 @@ export interface SyncRoutesSyncOptions {
 export declare function syncRoutesSync(opts: SyncRoutesSyncOptions): SyncRoutesResult;
 /** Re-exported beside the other sync results so consumers see one surface. */
 export type { RouteReport, SyncRoutesResult } from "./sync-routes.js";
+export interface AddModuleOptions {
+    /** The already-scaffolded site (absolute or relative). */
+    targetDir: string;
+    /** The module to add (validated upstream by `parseAddModuleArgs`). */
+    moduleName: ModuleName;
+    /** Defaults to `process.env["AILK_LICENSE_KEY"]`, as for `scaffold()`. */
+    licenseKey?: string;
+    /** Defaults to `AILK_MODULE_REGISTRY_URL` / the built-in default. */
+    moduleRegistryUrl?: string;
+    /** Defaults to `globalThis.fetch`. Never a live call in tests. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Apply a purchased module to an already-scaffolded site in place
+ * (`create-ailk add-module`, #6653). The thin package-rooted wrapper around
+ * `add-module.ts`'s `applyModuleToScaffold`, the `syncRoutesSync` split:
+ *
+ *   1. the target must be an existing scaffold — the same check as the sync
+ *      subcommands above;
+ *   2. a free module is refused before any key read or network call — it
+ *      ships with every scaffold, there is no bundle to add;
+ *   3. `resolvePaidModules` — the SAME gate `scaffold()` runs, so a missing
+ *      key or a key that does not cover the module is refused with the
+ *      scaffold-time message, before anything is written;
+ *   4. the fetched bundle is merged under the plus-config policy.
+ */
+export declare function addModule(opts: AddModuleOptions): Promise<AddModuleResult>;
 /** Re-exported so the CLI can name the file it wrote without duplicating it. */
 export { CATALOG_TARGET_PATH };
 /**