create-ailk 0.7.0 → 0.9.0

package/dist/module-architecture.d.ts

@@ -73,15 +73,19 @@ export interface PageRosterRow {
 /**
  * The architecture fragment one module contributes.
  *
- * `apps/web` (the presentation shell) is BASE — always present — so a module
- * extends it via `webImports` (packages added to `apps/web.may_import_from`)
- * rather than redeclaring it. Additional apps (api, mcp), packages, namespaces,
- * and top-level forbidden patterns are contributed outright.
+ * `apps/web`, `apps/api` and `apps/mcp` are BASE — always present. A module
+ * extends apps/web via `webImports` (added to `apps/web.may_import_from`)
+ * rather than redeclaring it; an `apps` entry replaces a base api/mcp block or
+ * adds an app (admin). Packages, namespaces and top-level forbidden patterns
+ * are contributed outright. `webImports`, `packages` and every `packages/*`
+ * entry describe this monorepo's boundaries: a scaffold has no `packages/`
+ * tree, so `deriveArchitecture` keeps only the entries naming a path the
+ * scaffold carries (#6940).
  */
 export interface ModuleSlice {
     /** Packages this module adds to apps/web.may_import_from (its presentation surface). */
     webImports?: string[];
-    /** Additional apps this module introduces (api, mcp). web is BASE, never here. */
+    /** Apps this module declares (api, mcp replace the base block; admin is new). web is BASE, never here. */
     apps?: Record<string, ArchApp>;
     /** Packages this module contributes. */
     packages?: Record<string, ArchPackage>;
@@ -308,33 +312,32 @@ export interface AddTransformOp {
     value: string;
 }
 /**
- * The module-independent base: `apps/web` (the Next.js presentation shell every
- * AILK site has) plus the standalone forbidden-pattern floor. `may_import_from`
- * starts EMPTY — the selected modules fill it via `webImports`.
+ * The module-independent base: the three apps every scaffold ships on disk
+ * (`apps/web`, `apps/api`, `apps/mcp` — template-overlay/apps carries all
+ * three whatever the module set, #6940) plus the standalone forbidden-pattern
+ * floor. apps/web's `may_import_from` starts EMPTY — the selected modules fill
+ * it via `webImports`; a module that declares `api`/`mcp` replaces the base
+ * block with its own.
  */
 export declare const ARCHITECTURE_BASE: {
     readonly version: 1;
     readonly composition_model: {
-        readonly reference: "claude-setup rules/need-to-know.md § Vocabulary (Module / Surface)";
         readonly tiers: {
             readonly data: "database/ — Prisma schema + migrations";
             readonly api: "apps/api (public HTTP API) + apps/mcp (agent tools)";
             readonly presentation: "apps/web — frontend surfaces";
         };
     };
+    /** Every declared app's own forbidden patterns (merged ahead of any the app adds). */
+    readonly appForbiddenPatterns: ForbiddenPattern[];
     /** The base apps/web shell. may_import_from is filled from the selected modules' webImports. */
     readonly web: {
         readonly path: "apps/web";
         readonly description: "Next.js — presentation tier. Frontend surfaces composed from the selected modules.";
         readonly may_not_import_from: readonly ["apps/api", "apps/mcp"];
-        readonly forbidden_patterns: readonly [{
-            readonly pattern: string;
-            readonly reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports";
-        }, {
-            readonly pattern: "@alkit/";
-            readonly reason: "Renamed to @working-theory/* on extraction";
-        }];
     };
+    /** The base apps/api and apps/mcp — present in every scaffold (#6940). */
+    readonly apps: Record<string, ArchApp>;
     /** Standalone-site forbidden-pattern floor (top-level, always present). */
     readonly forbiddenPatterns: ForbiddenPattern[];
 };

package/dist/module-architecture.js

@@ -83,35 +83,59 @@ const PUBLIC_SCHEDULING_VAR_PATTERN = [
  */
 const STRIPE_LIVE_KEY_PATTERN = ["(sk|pk|rk)_li", "ve_[A-Za-z0-9]"].join("");
 /**
- * The module-independent base: `apps/web` (the Next.js presentation shell every
- * AILK site has) plus the standalone forbidden-pattern floor. `may_import_from`
- * starts EMPTY — the selected modules fill it via `webImports`.
+ * The per-app forbidden-pattern floor every declared app carries — so each app
+ * a scaffold ships has its own rule in `architecture.yaml`, not only the
+ * top-level floor below.
+ */
+const APP_FORBIDDEN_FLOOR = [
+    {
+        pattern: NO_UPSTREAM_IMPORT_PATTERN,
+        reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports",
+    },
+    {
+        pattern: "@alkit/",
+        reason: "Renamed to @working-theory/* on extraction",
+    },
+];
+/**
+ * The module-independent base: the three apps every scaffold ships on disk
+ * (`apps/web`, `apps/api`, `apps/mcp` — template-overlay/apps carries all
+ * three whatever the module set, #6940) plus the standalone forbidden-pattern
+ * floor. apps/web's `may_import_from` starts EMPTY — the selected modules fill
+ * it via `webImports`; a module that declares `api`/`mcp` replaces the base
+ * block with its own.
  */
 export const ARCHITECTURE_BASE = {
     version: 1,
     composition_model: {
-        reference: "claude-setup rules/need-to-know.md § Vocabulary (Module / Surface)",
         tiers: {
             data: "database/ — Prisma schema + migrations",
             api: "apps/api (public HTTP API) + apps/mcp (agent tools)",
             presentation: "apps/web — frontend surfaces",
         },
     },
+    /** Every declared app's own forbidden patterns (merged ahead of any the app adds). */
+    appForbiddenPatterns: APP_FORBIDDEN_FLOOR,
     /** The base apps/web shell. may_import_from is filled from the selected modules' webImports. */
     web: {
         path: "apps/web",
         description: "Next.js — presentation tier. Frontend surfaces composed from the selected modules.",
         may_not_import_from: ["apps/api", "apps/mcp"],
-        forbidden_patterns: [
-            {
-                pattern: NO_UPSTREAM_IMPORT_PATTERN,
-                reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports",
-            },
-            {
-                pattern: "@alkit/",
-                reason: "Renamed to @working-theory/* on extraction",
-            },
-        ],
+    },
+    /** The base apps/api and apps/mcp — present in every scaffold (#6940). */
+    apps: {
+        api: {
+            path: "apps/api",
+            description: "Public HTTP API — routes + services (Fastify).",
+            may_import_from: ["database"],
+            may_not_import_from: ["apps/mcp", "apps/web"],
+        },
+        mcp: {
+            path: "apps/mcp",
+            description: "MCP server — agent-facing tools. Calls apps/api for writes.",
+            may_import_from: ["database"],
+            may_not_import_from: ["apps/api", "apps/web"],
+        },
     },
     /** Standalone-site forbidden-pattern floor (top-level, always present). */
     forbiddenPatterns: [
@@ -595,12 +619,12 @@ export const MODULE_SLICES = {
             {
                 pattern: "import.*['\"]stripe['\"]",
                 paths_excluded: ["packages/stripe-client/**"],
-                reason: "Stripe SDK imports go through packages/stripe-client only — single point of config",
+                reason: "Stripe SDK imports go through @working-theory/stripe-client only — single point of config",
             },
             {
                 pattern: "import.*['\"]resend['\"]|['\"]nodemailer['\"]",
                 paths_excluded: ["packages/email/**"],
-                reason: "Email provider SDKs go through packages/email — provider swap is a one-package change",
+                reason: "Email provider SDKs go through @working-theory/email — provider swap is a one-package change",
             },
         ],
         // ownedFiles (S1, #5088). Verified against the current filesystem and
@@ -1413,6 +1437,9 @@ export const MODULE_SLICES = {
             // upgrade-path fixture to protect either — it is net-new here, so nothing
             // in `templates/` can regress by its absence.
             "apps/web/app/[locale]/reports/[slug]/page.tsx",
+            // spec 6892 D2 — the /reports hub, alongside its reader above: also a
+            // URL segment MODULE_SURFACES["signal-collectors"] does not gate.
+            "apps/web/app/[locale]/reports/page.tsx",
             //
             // The two sections that route composes — `report-header` and
             // `reports-list` — are deliberately NOT owned here. They are
@@ -1446,11 +1473,13 @@ export const MODULE_SLICES = {
             // #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. Its
-            // seeds are a directory a template supplies (minimalism-site's four
-            // reports), so the row declares that directory (#6646).
+            // seeds are SELF-SEEDING (spec 6892 D3): this module's own `installMap`
+            // lands the four `ReportPage` samples below, so every template taking
+            // the module gets them — `moduleRosterRows` derives the code-route form
+            // for this row rather than requiring a template to ship one (D9).
             { route: "/reports/[slug]", contentDir: "content/en/ReportPage" },
         ],
-        // installMap (#5618 D6.3) — the module's ten sample files, moved here out
+        // installMap (#5618 D6.3) — the module's sample files, moved here out
         // of `site-templates/marketing-site/` so the module OWNS its samples
         // (Rule B) and a keyed `--modules signal-collectors` scaffold with no
         // template lands them. Their in-repo home is
@@ -1463,12 +1492,19 @@ export const MODULE_SLICES = {
         // `module-templates/` the two never meet.
         //
         // 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
+        // reads, and the report PDF under apps/web/public/); the ten MDX entries
         // 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).
+        // so the Pro scaffold's file set (spec 5618 § 7 finding 7). The four
+        // `ReportPage` seeds and the `ReportsList` hub seed are the one exception
+        // (spec 6892 D3): their `/reports/[slug]` and `/reports` rows ARE this
+        // module's own `pageContributions`/`starter-grid.ts` rows respectively,
+        // so this module installs its own seeds for them directly, unlike the
+        // sample rows above. `/referral`'s seed and flow move here the same way,
+        // moved out of the retired `minimalism-site` tree (spec 6892 D3), which
+        // owned no code of its own for either route.
         // `generate-sample-report.py` keeps its root-level destination
         // (finding 1 — AC7 forbids changing the Pro file set).
         installMap: {
@@ -1478,7 +1514,14 @@ export const MODULE_SLICES = {
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/contact.mdx": "content/en/ThankYouPage/contact.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/newsletter.mdx": "content/en/ThankYouPage/newsletter.mdx",
             "packages/create-ailk/module-templates/signal-collectors/content/en/ThankYouPage/apply.mdx": "content/en/ThankYouPage/apply.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/annual-letter-2024.mdx": "content/en/ReportPage/annual-letter-2024.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/field-notes-2023.mdx": "content/en/ReportPage/field-notes-2023.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/platform-shift-2025.mdx": "content/en/ReportPage/platform-shift-2025.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportPage/state-of-the-market-2026.mdx": "content/en/ReportPage/state-of-the-market-2026.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/ReportsList/reports.mdx": "content/en/ReportsList/reports.mdx",
+            "packages/create-ailk/module-templates/signal-collectors/content/en/LandingPage/referral.mdx": "content/en/LandingPage/referral.mdx",
             "packages/create-ailk/module-templates/signal-collectors/flows/fit-check.flow.json": "database/flows/fit-check.flow.json",
+            "packages/create-ailk/module-templates/signal-collectors/flows/referral.flow.json": "database/flows/referral.flow.json",
             "packages/create-ailk/module-templates/signal-collectors/waitlist/launch-waitlist.experiment.json": "database/waitlist/launch-waitlist.experiment.json",
             "packages/create-ailk/module-templates/signal-collectors/reports/sample-report.pdf": "apps/web/public/reports/sample-report.pdf",
             "packages/create-ailk/module-templates/signal-collectors/reports/generate-sample-report.py": "reports/generate-sample-report.py",

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,56 @@
  */
 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; widened to a path #6813 D1/D3):
+     * a recognized name, lowercased, or an absolute directory holding a
+     * `DESIGN.md`, case preserved. Never set with `template`.
+     */
+    design?: string;
+    /**
+     * 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. */
@@ -36,6 +70,12 @@ export interface CliOptions {
      * `--sync-architecture`: data-only, one file, an already-scaffolded target.
      */
     syncCatalog: boolean;
+    /**
+     * When set, rewrite the template-owned sections of the target's CLAUDE.md
+     * to the template this create-ailk ships and exit (#6904). The same sync
+     * shape: one file, an already-scaffolded target.
+     */
+    syncClaudeMd: boolean;
     /**
      * When set, a fresh scaffold ALSO gets COMPONENT-CATALOG.md. Off by default
      * so a scaffold that does not ask for the catalog is byte-identical to the
@@ -58,16 +98,54 @@ export interface CliOptions {
 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[];