create-ailk 0.6.1 → 0.8.0

package/dist/license-set.js

@@ -0,0 +1,194 @@
+/**
+ * `create-ailk license set <key|-> [dir]` — put a licence key into an existing
+ * scaffold and, when it is Vercel-linked, into production (#6683 § 3 D9).
+ *
+ * The one-liner a buyer runs is `pnpm create ailk@latest license set <key>`:
+ * `create-ailk` is the public CLI they already have (§ 1.8).
+ *
+ *   1. The target (default: cwd) must contain `architecture.yaml` — the
+ *      `sync-routes` precondition — else exit 1 with nothing written.
+ *   2. `writeLicenseKeyFiles` — `ailk.key` + `apps/api/.env`, both 0600 and
+ *      gitignored; the same writer `--license` uses.
+ *   3. For each of `<dir>`, `<dir>/apps/api`, `<dir>/apps/web` holding
+ *      `.vercel/project.json`, with that directory as `cwd`:
+ *        a. print the linked `projectId` about to change (SEC-13);
+ *        b. list `ailk.key` and `.env` in its `.vercelignore` — a CLI deploy
+ *           uploads the local tree, which `.gitignore` does not govern (SEC-10);
+ *        c. `vercel env rm AILK_LICENSE_KEY production --yes` (failure
+ *           tolerated: the variable may not exist yet);
+ *        d. `vercel env add AILK_LICENSE_KEY production`, the key on STDIN;
+ *        e. `vercel deploy --prod --yes`.
+ *
+ * The key is never an argv element of a spawned process and never appears in
+ * an error (SEC-11). `vercel` missing → exit 1 naming what was written and the
+ * exact manual commands; a failed `env add` after `env rm` → exit 1 saying the
+ * production variable is now UNSET, with the command that finishes the job.
+ * No Vercel link → exit 0 after the local write.
+ *
+ * Pure module (no `import.meta.url`): every effect on the outside world —
+ * output, stdin, the process runner — is injected, so jest drives it directly.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { LICENSE_ENV_FILE, LICENSE_ENV_VAR, LICENSE_KEY_FILE, assertLicenseKeyShape, writeLicenseKeyFiles, } from "./lib/license-key-files.js";
+export const LICENSE_SET_HELP = `create-ailk license set — put your licence key into an existing site.
+
+Usage:
+  pnpm create ailk@latest license set <key> [<target-dir>]
+  pnpm create ailk@latest license set - [<target-dir>] < key.txt
+
+Arguments:
+  <key>                    Your licence key, or \`-\` to read it from stdin
+                           (keeps it out of your shell history).
+  <target-dir>             An already-scaffolded repo (contains
+                           architecture.yaml). Defaults to the current dir.
+
+Writes the key to ailk.key and apps/api/.env (owner-only, gitignored). When the
+site (or apps/api, or apps/web) is linked to Vercel, it also replaces the
+production AILK_LICENSE_KEY variable and redeploys.
+`;
+const LINK_DIRS = [".", join("apps", "api"), join("apps", "web")];
+const VERCELIGNORE_LINES = [LICENSE_KEY_FILE, ".env"];
+const ENV_RM = ["env", "rm", LICENSE_ENV_VAR, "production", "--yes"];
+const ENV_ADD = ["env", "add", LICENSE_ENV_VAR, "production"];
+const DEPLOY = ["deploy", "--prod", "--yes"];
+/** `spawnSync`, never through a shell; stdin piped only when there is input. */
+export const defaultRunner = (args, options) => {
+    const res = spawnSync("vercel", [...args], {
+        cwd: options.cwd,
+        shell: false,
+        stdio: [options.input !== undefined ? "pipe" : "inherit", "inherit", "inherit"],
+        ...(options.input !== undefined ? { input: options.input } : {}),
+    });
+    return {
+        status: res.status,
+        ...(res.error !== undefined
+            ? { error: res.error }
+            : {}),
+    };
+};
+class LicenseSetError extends Error {
+}
+/**
+ * Hand-parsed rather than through `node:util` `parseArgs`: its errors quote
+ * the offending token, and the token here may be the key.
+ */
+function parseLicenseSetArgs(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        return { help: true, key: undefined, target: undefined };
+    }
+    if (argv.length > 2) {
+        throw new LicenseSetError(`expected <key|-> and at most one target directory, got ${argv.length} arguments`);
+    }
+    return { help: false, key: argv[0], target: argv[1] };
+}
+/** Append whichever of `lines` the file does not already list. */
+function ensureVercelIgnore(dir) {
+    const path = join(dir, ".vercelignore");
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const present = new Set(text.split("\n").map((l) => l.trim()));
+    const missing = VERCELIGNORE_LINES.filter((l) => !present.has(l) && !present.has(`/${l}`));
+    if (missing.length === 0)
+        return;
+    const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
+    writeFileSync(path, `${text}${sep}${missing.join("\n")}\n`);
+}
+function readProjectId(dir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(dir, ".vercel", "project.json"), "utf8"));
+        if (typeof raw.projectId === "string" && raw.projectId.length > 0) {
+            return raw.projectId;
+        }
+    }
+    catch {
+        // fall through
+    }
+    throw new LicenseSetError(`${join(dir, ".vercel", "project.json")} has no readable projectId; run \`vercel link\` there, then re-run.`);
+}
+/** The exact commands that finish the push by hand, from `dir`. */
+function manualCommands(dir, keyFile, from) {
+    const keyRel = relative(dir, keyFile) || LICENSE_KEY_FILE;
+    const lines = [`  cd ${dir}`];
+    if (from === "rm")
+        lines.push(`  vercel ${ENV_RM.join(" ")}`);
+    lines.push(`  tr -d '\\n' < ${keyRel} | vercel ${ENV_ADD.join(" ")}`);
+    lines.push(`  vercel ${DEPLOY.join(" ")}`);
+    return lines.join("\n");
+}
+/**
+ * Run `license set` with `argv` = everything after the `license set` words.
+ * Returns the process exit code; never throws for an expected failure.
+ */
+export function runLicenseSet(argv, io) {
+    const runner = io.runner ?? defaultRunner;
+    const fail = (message) => {
+        io.stderr(`[create-ailk] license set: ${message}\n`);
+        return 1;
+    };
+    let args;
+    try {
+        args = parseLicenseSetArgs(argv);
+    }
+    catch (err) {
+        return fail(`${err.message}\n\n${LICENSE_SET_HELP}`);
+    }
+    if (args.help) {
+        io.stdout(LICENSE_SET_HELP);
+        return 0;
+    }
+    if (args.key === undefined) {
+        return fail(`missing <key>.\n\n${LICENSE_SET_HELP}`);
+    }
+    const key = args.key === "-" ? io.readStdin().trim() : args.key;
+    try {
+        assertLicenseKeyShape(key);
+    }
+    catch (err) {
+        return fail(err.message);
+    }
+    const target = resolve(io.cwd, args.target ?? ".");
+    if (!existsSync(join(target, "architecture.yaml"))) {
+        return fail(`not a scaffolded repo: no architecture.yaml at ${target}. Run it from your site's root, or pass the site's directory.`);
+    }
+    writeLicenseKeyFiles(target, key);
+    const keyFile = join(target, LICENSE_KEY_FILE);
+    const written = `Wrote ${LICENSE_KEY_FILE} and ${LICENSE_ENV_FILE.split("\\").join("/")} in ${target}`;
+    io.stdout(`[create-ailk] ${written} (owner-only, gitignored).\n`);
+    const linked = LINK_DIRS.map((d) => join(target, d)).filter((d) => existsSync(join(d, ".vercel", "project.json")));
+    if (linked.length === 0) {
+        io.stdout("[create-ailk] No Vercel link found (.vercel/project.json); nothing pushed. Set AILK_LICENSE_KEY on your host yourself if you deploy elsewhere.\n");
+        return 0;
+    }
+    for (const dir of linked) {
+        let projectId;
+        try {
+            projectId = readProjectId(dir);
+        }
+        catch (err) {
+            return fail(err.message);
+        }
+        io.stdout(`[create-ailk] Updating ${LICENSE_ENV_VAR} (production) on Vercel project ${projectId}, linked at ${dir}\n`);
+        ensureVercelIgnore(dir);
+        const rm = runner(ENV_RM, { cwd: dir });
+        if (rm.error?.code === "ENOENT") {
+            return fail(`the vercel CLI was not found. ${written}; nothing was pushed. Install it (npm i -g vercel), or finish by hand:\n${manualCommands(dir, keyFile, "rm")}`);
+        }
+        // `rm` may fail because the variable never existed — tolerated — but then
+        // it removed nothing, and the message below must not say it did.
+        const removed = rm.error === undefined && rm.status === 0;
+        const add = runner(ENV_ADD, { cwd: dir, input: key });
+        if (add.error !== undefined || add.status !== 0) {
+            const state = removed
+                ? `The production variable ${LICENSE_ENV_VAR} is now UNSET there (the old value was removed).`
+                : `The production variable ${LICENSE_ENV_VAR} was not changed (removing the old value also failed).`;
+            return fail(`\`vercel ${ENV_ADD.join(" ")}\` failed on project ${projectId}. ${state} Finish with:\n${manualCommands(dir, keyFile, removed ? "add" : "rm")}`);
+        }
+        const deploy = runner(DEPLOY, { cwd: dir });
+        if (deploy.error !== undefined || deploy.status !== 0) {
+            return fail(`\`vercel ${DEPLOY.join(" ")}\` failed on project ${projectId}. ${LICENSE_ENV_VAR} is set in production; redeploy with:\n  cd ${dir}\n  vercel ${DEPLOY.join(" ")}`);
+        }
+    }
+    io.stdout("[create-ailk] Licence key set and production redeployed.\n");
+    return 0;
+}

package/dist/module-architecture.d.ts

@@ -61,6 +61,14 @@ export interface PageRosterRow {
      * (`/meet` renders from the scheduling API, not from an MDX file).
      */
     content?: readonly string[];
+    /**
+     * Scaffold-relative seed DIRECTORY a dynamic detail row serves, e.g.
+     * `content/en/Service` under `/services/[slug]` (#6646 disposition (a)).
+     * `content` names files; a detail route whose seeds are a whole directory
+     * declares the directory instead. Every `.mdx` under it is a declared page,
+     * so it installs; a seed no row names does not.
+     */
+    contentDir?: string;
 }
 /**
  * The architecture fragment one module contributes.
@@ -144,6 +152,8 @@ export interface ModuleSlice {
      * `ownedFiles` names which files in THIS monorepo physically belong to the
      * module; `pageContributions` names which PAGES the module brings to a
      * template's roster. `template-manifest.ts`'s `mergeRoster` reads it.
+     * A row's `contentDir` names seeds a TEMPLATE supplies, not the module:
+     * the module's bundle stages only `content` files (#6646).
      *
      * A contribution never carries route CODE. How the route code reaches a
      * scaffold is a property of the module, not of the contribution (parent
@@ -399,3 +409,13 @@ export declare function normalizeModules(modules: string[]): ModuleName[];
 export declare function coOwnedModuleDestinations(): ReadonlySet<string>;
 export declare const EXCLUDE_TEMPLATE_DIRS: readonly string[];
 export declare function paidModuleTemplateExclusions(snapshotRoots: readonly string[], repoRoot: string): string[];
+/** The scaffold's architecture linter, relative to the site root (#6649). */
+export declare const ARCHITECTURE_LINT_PATH = "tools/lint-architecture.ts";
+/**
+ * What a scaffold needs so its `architecture.yaml` is enforced rather than
+ * declared (#6649): the linter, the `architecture` + `preflight` root scripts
+ * that run it, and a `.claude/settings.json` PostToolUse hook on Edit|Write
+ * that runs it in-session. Returns one line per missing piece — empty means
+ * all present. `verify-scaffold.mjs` fails on a non-empty result.
+ */
+export declare function missingArchitectureEnforcement(siteDir: string): string[];

package/dist/module-architecture.js

@@ -21,7 +21,8 @@
  * `architecture.yaml` template files — a fixed template IS the drift this
  * removes.
  */
-import { sep } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, sep } from "node:path";
 import { importClosure } from "./lib/import-graph.js";
 import { PAID_MODULES } from "./lib/module-tier.js";
 import { RECOGNIZED_MODULES } from "./parse-args.js";
@@ -149,6 +150,15 @@ const ASSET_STORE_FILES = [
     "apps/api/src/routes/assets/manage.ts",
     "apps/api/src/lib/asset-store.ts",
 ];
+/**
+ * The auth-adapter exception (#587 in the AILK repo's own architecture.yaml):
+ * the base apps/web hands Better Auth its Prisma client from
+ * `lib/prisma-for-auth.ts`, whatever modules are selected. Every slice that
+ * contributes `webImports` — and so makes apps/web's allowlist non-empty —
+ * names it, so no module set yields an allowlist the scaffold's own
+ * tools/lint-architecture.ts fails on (#6649).
+ */
+const WEB_AUTH_ADAPTER_IMPORT = "database";
 /**
  * The per-module slices. Authored for every `RECOGNIZED_MODULES` value; only
  * `marketing` (the default) is validated end-to-end against a golden.
@@ -157,6 +167,7 @@ export const MODULE_SLICES = {
     // ── marketing — thin presentation module (the default) ───────────────────
     marketing: {
         webImports: [
+            WEB_AUTH_ADAPTER_IMPORT,
             "packages/content-adapters",
             "packages/jsonld",
             "packages/metadata",
@@ -236,7 +247,7 @@ export const MODULE_SLICES = {
     },
     // ── docs-blog — Pro module: both fumadocs surfaces (D-46) ────────────────
     "docs-blog": {
-        webImports: ["packages/fumadocs-schema"],
+        webImports: [WEB_AUTH_ADAPTER_IMPORT, "packages/fumadocs-schema"],
         packages: {
             "fumadocs-schema": {
                 description: "Fumadocs ↔ schema.org bridge — BlogList / DocsPage JSON-LD from Fumadocs MDX",
@@ -376,7 +387,10 @@ export const MODULE_SLICES = {
                         path: ["scripts"],
                         entries: {
                             prebuild: "fumadocs-mdx",
-                            pretypecheck: "fumadocs-mdx",
+                            // `pretype-check`, not `pretypecheck`: pnpm runs `pre<name>`
+                            // only before a script named `<name>`, and the scaffold's is
+                            // `type-check` (#6680).
+                            "pretype-check": "fumadocs-mdx",
                             pretest: "fumadocs-mdx",
                         },
                     },
@@ -795,7 +809,7 @@ export const MODULE_SLICES = {
         // dependency under `node_modules/`, never as a `packages/admin-ui`
         // source sibling; the `patches` entry below is what puts it in the
         // buyer's apps/web/package.json.
-        webImports: ["packages/admin-ui"],
+        webImports: [WEB_AUTH_ADAPTER_IMPORT, "packages/admin-ui"],
         packages: {
             "admin-ui": {
                 description: "Shared Admin-settings components — the settings shell plus the General / Site / Team panels, presentational only (data + save callbacks as props)",
@@ -892,12 +906,9 @@ export const MODULE_SLICES = {
     // all, and no scheduling value is ever published to the browser as a
     // `NEXT_PUBLIC_` variable.
     //
-    // NOTE — a scaffolded site cannot run these yet. It receives
-    // `architecture.yaml` and a `package.json` whose `architecture` script names
-    // `tools/lint-architecture.ts`, but `build-templates.mjs` snapshots only
-    // `apps/` and `database/`, so `tools/` is absent. The rules are declarative
-    // there until the scaffold ships its linter; they ARE enforced in the AILK
-    // repo, whose own architecture.yaml carries the same four.
+    // A scaffolded site enforces these with its own `tools/lint-architecture.ts`
+    // (template-overlay/, #6649) via `pnpm architecture`; the AILK repo's own
+    // architecture.yaml carries the same four.
     //
     // The `api` block is a VERBATIM copy of multi-tenant's, deliberately. Two
     // reasons: `deriveArchitecture` merges app blocks with `Object.assign`, so
@@ -1434,8 +1445,10 @@ export const MODULE_SLICES = {
             { route: "/flows/[slug]/results/[payload]" },
             // #5562 — the report reader. Unlike the three rows above, this row's
             // code IS this module's own `ownedFiles` (see the note beside it), so
-            // the contribution and the delivery shape carrying it agree here.
-            { route: "/reports/[slug]" },
+            // the contribution and the delivery shape carrying it agree here. Its
+            // seeds are a directory a template supplies (minimalism-site's four
+            // reports), so the row declares that directory (#6646).
+            { route: "/reports/[slug]", contentDir: "content/en/ReportPage" },
         ],
         // installMap (#5618 D6.3) — the module's ten sample files, moved here out
         // of `site-templates/marketing-site/` so the module OWNS its samples
@@ -1451,13 +1464,13 @@ export const MODULE_SLICES = {
         //
         // Four entries are real renames (the flow and waitlist seeds the API
         // reads, and the report PDF under apps/web/public/); the six MDX entries
-        // are self-addressed because no `pageContributions` row declares
-        // `/projects`, `/projects/[slug]` or `/thanks/[slug]` yet (spec § 7
-        // finding 7 — declaring them changes the enabled-surface set and so the
-        // Pro scaffold's file set, a separate decision). Once those rows exist
-        // the six move to `pageContributions[].content` with no further
-        // migration. `generate-sample-report.py` keeps its root-level
-        // destination (finding 1 — AC7 forbids changing the Pro file set).
+        // are self-addressed. Their `/projects`, `/projects/[slug]` and
+        // `/thanks/[slug]` rows are declared by the templates that install them
+        // (`template-manifest.ts`'s signal-collectors sample rows, #6646), not
+        // here — a module contribution would change the enabled-surface set and
+        // so the Pro scaffold's file set (spec 5618 § 7 finding 7).
+        // `generate-sample-report.py` keeps its root-level destination
+        // (finding 1 — AC7 forbids changing the Pro file set).
         installMap: {
             "packages/create-ailk/module-templates/signal-collectors/content/en/ProjectsList/projects.mdx": "content/en/ProjectsList/projects.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/Project/fit-check-funnel.mdx": "content/en/Project/fit-check-funnel.mdx",
@@ -1801,3 +1814,48 @@ export function paidModuleTemplateExclusions(snapshotRoots, repoRoot) {
     // question with the same resolution this answer was computed with (#5701).
     return [...importClosure(repoRoot, [...roots], seeds)].sort();
 }
+/** The scaffold's architecture linter, relative to the site root (#6649). */
+export const ARCHITECTURE_LINT_PATH = "tools/lint-architecture.ts";
+/**
+ * What a scaffold needs so its `architecture.yaml` is enforced rather than
+ * declared (#6649): the linter, the `architecture` + `preflight` root scripts
+ * that run it, and a `.claude/settings.json` PostToolUse hook on Edit|Write
+ * that runs it in-session. Returns one line per missing piece — empty means
+ * all present. `verify-scaffold.mjs` fails on a non-empty result.
+ */
+export function missingArchitectureEnforcement(siteDir) {
+    const missing = [];
+    if (!existsSync(join(siteDir, ARCHITECTURE_LINT_PATH))) {
+        missing.push(ARCHITECTURE_LINT_PATH);
+    }
+    const readJson = (rel) => {
+        const p = join(siteDir, rel);
+        if (!existsSync(p))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const scripts = readJson("package.json")
+        ?.scripts ?? {};
+    if (!scripts.architecture?.includes(ARCHITECTURE_LINT_PATH)) {
+        missing.push(`package.json scripts.architecture (runs ${ARCHITECTURE_LINT_PATH})`);
+    }
+    if (!scripts.preflight?.includes("pnpm architecture")) {
+        missing.push("package.json scripts.preflight (runs pnpm architecture)");
+    }
+    const postToolUse = readJson(".claude/settings.json")?.hooks?.PostToolUse ?? [];
+    const hooked = postToolUse.some((entry) => {
+        const tools = (entry.matcher ?? "").split("|");
+        return (tools.includes("Edit") &&
+            tools.includes("Write") &&
+            (entry.hooks ?? []).some((h) => /\bpnpm\b.*\barchitecture\b/.test(h.command ?? "")));
+    });
+    if (!hooked) {
+        missing.push(".claude/settings.json PostToolUse hook on Edit|Write (runs pnpm architecture)");
+    }
+    return missing;
+}

package/dist/parse-args.d.ts

@@ -1,3 +1,4 @@
+import type { ScaffoldOptions } from "./programmatic.js";
 /**
  * The recognized module vocabulary for the `--modules` selector.
  *
@@ -9,23 +10,52 @@
  */
 export declare const RECOGNIZED_MODULES: readonly ["marketing", "docs-blog", "multi-tenant", "workspace", "scheduling", "signal-collectors", "commerce"];
 export type ModuleName = (typeof RECOGNIZED_MODULES)[number];
+/**
+ * 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 declare const RECOGNIZED_SHAPES: readonly ["organization-product", "organization-service", "local-business-service", "person-service"];
+export type ShapeName = (typeof RECOGNIZED_SHAPES)[number];
+/** Shapes the contract names but no release builds yet. */
+export declare const RESERVED_SHAPES: readonly ["local-business-product"];
+/** The `--design` vocabulary (#6754 D1) — `STARTER_DESIGNS`, pinned by test. */
+export declare const RECOGNIZED_DESIGNS: readonly ["standard", "minimalism"];
+export type DesignName = (typeof RECOGNIZED_DESIGNS)[number];
 export interface CliOptions {
     /** Positional target directory (the dir to scaffold into). Optional only
      *  when `help` or `version` is set. */
     target: string | undefined;
     /**
      * The site template to install (`--template`), validated against
-     * `RECOGNIZED_TEMPLATES` at parse time. Undefined when the flag is absent —
-     * and a run naming no template scaffolds exactly what it did before the
-     * flag existed (spec 5481 § 3 DD3).
+     * `RECOGNIZED_TEMPLATES` at parse time. Undefined when the flag is absent.
+     * The CLI never scaffolds a run naming neither a template nor a shape
+     * (#6754 D2 — refusal R1, or the shape prompt on a terminal).
      */
     template: string | undefined;
+    /** The starter's shape (`--shape`, #6754), normalized. Never set with `template`. */
+    shape?: ShapeName;
+    /** The starter's design (`--design`, #6754). Never set with `template`. */
+    design?: DesignName;
+    /**
+     * True when a scaffold run named neither `--shape` nor `--template` on a
+     * terminal: `resolveCliShape` must ask before anything is scaffolded.
+     */
+    needsShapePrompt: boolean;
     install: boolean;
     help: boolean;
     version: boolean;
-    /** Selected modules (recognized: marketing, docs-blog, multi-tenant, scheduling).
-     *  Defaults to ['marketing'] when the flag is absent. */
-    modules: string[];
+    /**
+     * Selected modules (recognized: marketing, docs-blog, multi-tenant,
+     * scheduling). `undefined` when `--modules` is absent — the key's level
+     * decides (#6759 D3); never read as `['marketing']` here. An empty or
+     * all-empty `--modules` value still names the Free set (`parseModules`).
+     */
+    modules: string[] | undefined;
     /** Explicitly requested route surfaces (`--surfaces`). Empty when the flag is
      *  absent — the module set alone then decides (see surfaces.ts
      *  `resolveSurfaces`). Validated, lowercased, deduped and sorted. */
@@ -47,20 +77,65 @@ export interface CliOptions {
      *  value is validated through `parseModules` at parse time; cli.ts re-parses
      *  it to the module list. Undefined when the flag is absent (scaffold mode). */
     syncArchitecture: string | undefined;
+    /**
+     * The licence key (`--license <key>`, #6683 D9), shape-checked at parse
+     * time. When set, `scaffold()` fetches paid bundles with it and writes it
+     * into the new scaffold (`ailk.key` + `apps/api/.env`). Absent when the
+     * flag is.
+     */
+    license?: string;
 }
 export declare class ParseError extends Error {
     constructor(message: string);
 }
+/** The caller's terminal state (#6754 D2). */
+export interface ParseEnv {
+    /** A human can answer a prompt: `process.stdin.isTTY === true` in cli.ts. */
+    interactive: boolean;
+}
 export declare const helpText: string;
-export declare function parseCliArgs(argv: string[]): CliOptions;
+/**
+ * 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 declare function parseCliArgs(argv: string[], env?: ParseEnv): CliOptions;
+/** The streams the shape prompt reads and writes (a `PassThrough` pair in tests). */
+export interface PromptIo {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+}
+/**
+ * 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 declare function promptForShape(io: PromptIo): Promise<ShapeName>;
+/**
+ * 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 declare function resolveCliShape(opts: CliOptions, io: PromptIo): Promise<CliOptions>;
+/**
+ * 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 declare function toScaffoldOptions(opts: CliOptions): ScaffoldOptions;
 /**
  * Parse a module CSV (the `--modules` or `--sync-architecture` value) into a
  * 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 declare function parseModules(raw: string | undefined): string[];
+export declare function parseModules(raw: string): string[];