create-ailk 0.1.0 → 0.2.0

package/dist/module-architecture.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Module → architecture-slice registry.
+ *
+ * The single source that turns the `--modules` selection into a scaffolded
+ * site's `architecture.yaml` (its code-boundary config — the apps/packages/
+ * namespaces the linter walks + the import rules it enforces). Each recognized
+ * module maps to the architecture FRAGMENT it contributes; `deriveArchitecture`
+ * (derive-architecture.ts) composes a module-independent BASE + the selected
+ * slices into one deterministic document.
+ *
+ * Grounded in the root AILK `architecture.yaml` `composition_model`: a customer
+ * site is the three-tier AILK app (data · api · presentation) COMPOSED of the
+ * selected modules. `marketing` is the thin presentation default and is
+ * validated end-to-end; `docs` (a mountable presentation surface) and
+ * `multi-tenant` (a full-stack module) are registry-defined ahead of their
+ * template trees (per spec #3787 D3). `scheduling` (#4633) contributes all
+ * three tiers — the provider client, the /v1/schedule/* routes, and the
+ * booker + confirmation pages — into the marketing surface.
+ *
+ * Design (spec #3787 D1): a code registry, NOT N hand-maintained per-module
+ * `architecture.yaml` template files — a fixed template IS the drift this
+ * removes.
+ */
+import { type ModuleName } from "./parse-args.js";
+/** A forbidden import/usage pattern the architecture linter enforces. */
+export interface ForbiddenPattern {
+    pattern: string;
+    reason: string;
+    paths_excluded?: string[];
+}
+/** An app-tier workspace boundary (apps/web, apps/api, apps/mcp). */
+export interface ArchApp {
+    path: string;
+    description: string;
+    may_import_from: string[];
+    may_not_import_from: string[];
+    forbidden_patterns?: ForbiddenPattern[];
+}
+/** A package-tier workspace boundary. */
+export interface ArchPackage {
+    description: string;
+    may_import_from: string[];
+}
+/** A database/ namespace member. */
+export interface ArchNamespaceMember {
+    path: string;
+    description: string;
+}
+/** The database/ per-namespace boundary block (data-tier modules). */
+export interface ArchNamespaces {
+    description: string;
+    members: Record<string, ArchNamespaceMember>;
+    rules: string[];
+}
+/**
+ * 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.
+ */
+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?: Record<string, ArchApp>;
+    /** Packages this module contributes. */
+    packages?: Record<string, ArchPackage>;
+    /** database/ namespaces this module's data tier introduces. */
+    namespaces?: ArchNamespaces;
+    /** Top-level forbidden patterns this module contributes. */
+    forbiddenPatterns?: ForbiddenPattern[];
+    /**
+     * The literal file inventory a strip tool consumes (S1, #5088 — B2, #5082
+     * reads this to know exactly which files to delete from a public/OSS
+     * release of THIS repo). Repo-root-relative, POSIX `/`-separated SOURCE
+     * file paths only — no test files (`__tests__/`, `.test.ts`, `.stories.tsx`),
+     * no generated output, no `node_modules`. Undefined/omitted for a module
+     * that is not (yet) part of a strip pass (e.g. `marketing`, which is base
+     * and never stripped).
+     *
+     * This is a DIFFERENT kind of fact than every field above it. `webImports` /
+     * `apps` / `packages` / `namespaces` model import-boundary PERMISSIONS for a
+     * *scaffolded customer site's* `architecture.yaml` — "apps/web MAY import
+     * packages/fumadocs-schema." `ownedFiles` instead names, one literal path at
+     * a time, which files in *this* monorepo physically belong to the module —
+     * "apps/api/src/routes/schedule/index.ts IS the scheduling module." A
+     * package can appear in one view and not the other: `packages/fumadocs-schema`
+     * is a `webImports` entry (a permission — a docs scaffold installs it) but
+     * NOT an `ownedFiles` entry (it is `oss`-tiered; the strip keeps it).
+     * The two views can disagree on purpose: a file may be physically
+     * owned by a module (`ownedFiles`) while living inside a package that
+     * OTHER modules also import from (so no `webImports`/`packages` entry
+     * disappears just because one module's slice of it does).
+     *
+     * One entry in the arrays below is deliberately a GLOB
+     * (`"apps-paid/workspace/**"`) rather than enumerated file-by-file — a
+     * whole app with dozens of files, owned outright by one module; every other
+     * entry is a literal file
+     * path. A file that a module's own docs mention but that lives inside a
+     * package SHARED with other modules (e.g. `packages/validation`,
+     * `packages/api-client`) is deliberately left OUT of `ownedFiles` even when
+     * genuinely single-purpose — see the inline comments above each module's
+     * array for the specific files considered and excluded, and why.
+     *
+     * THE STRIP'S AUTHORITY IS THE UNION of this list and the public split
+     * manifest's PUB-200..260 DELETE entries (B2, #5082) — not this list alone
+     * (#5182 D6). The two disagree by eight files, on purpose:
+     *
+     *   - Six are manifest-only: the content-write trio in
+     *     `apps/api/src/routes/content/` and its `apps/mcp/src/tools/` twins.
+     *     They are NOT added here, because `MODULE_SLICES` is typed
+     *     `Record<ModuleName, ModuleSlice>` and `ModuleName` comes from
+     *     `RECOGNIZED_MODULES`, so adding a `content-write` key would make
+     *     `create-ailk --modules content-write` a valid scaffold selection. It is
+     *     not one — content-write is a licence-tier line drawn inside a single
+     *     app, never a customer opt-in (see `apps/api/src/config/modules.ts`).
+     *   - Two are this-list-only and the manifest simply never recorded them:
+     *     `apps/web/app/[locale]/docs/[[...slug]]/page.tsx` and
+     *     `apps/web/app/[locale]/schedule/confirmed/page.tsx`.
+     *
+     * A file's TEST and STORY companions are never listed here (the
+     * SOURCE-files-only rule above still holds) but DO carry the marker. They
+     * are derived from the import graph — a test or story file carries
+     * `oss: false` iff it imports a slice file — never from filename stems,
+     * which miss eleven and over-mark three.
+     */
+    ownedFiles?: 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`.
+ */
+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";
+        };
+    };
+    /** 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";
+        }];
+    };
+    /** Standalone-site forbidden-pattern floor (top-level, always present). */
+    readonly forbiddenPatterns: ForbiddenPattern[];
+};
+/**
+ * The per-module slices. Authored for every `RECOGNIZED_MODULES` value; only
+ * `marketing` (the default) is validated end-to-end against a golden.
+ */
+export declare const MODULE_SLICES: Record<ModuleName, ModuleSlice>;
+/**
+ * Normalize a requested module list to the unique set, ordered by the canonical
+ * `RECOGNIZED_MODULES` sequence — so the derivation is a pure function of the
+ * SET, independent of input order (`['docs','marketing']` ≡ `['marketing','docs']`).
+ *
+ * @throws Error on an unrecognized module (a defensive backstop; `parse-args`
+ *   rejects unrecognized values upstream before they reach derivation).
+ */
+export declare function normalizeModules(modules: string[]): ModuleName[];