create-ailk 0.2.0 → 0.3.0

package/dist/module-architecture.d.ts

@@ -1,26 +1,3 @@
-/**
- * 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 {
@@ -127,6 +104,116 @@ export interface ModuleSlice {
      * which miss eleven and over-mark three.
      */
     ownedFiles?: string[];
+    /**
+     * Bundle-relative source → scaffold-relative destination (spec 5373 § D7).
+     * Every source must be a file the validated tar extraction produced in the
+     * bundle producer's staging directory — repo-relative, coinciding with the
+     * `ownedFiles`/`installMap`-source paths this module's producer step
+     * stages at, by construction. `extractModuleBundle` applies this map after
+     * the tar entries are validated: an absolute path, a `..` segment, or a
+     * path absent from staging rejects the whole bundle, as does a destination
+     * that resolves outside the scaffold. A mapped source is copied to its
+     * destination only, never also to its original path.
+     */
+    installMap?: Record<string, string>;
+    /**
+     * Plain text `extractModuleBundle` prints to stdout after a successful
+     * merge, with C0/C1 control characters (other than newline) stripped
+     * first so a bundle cannot inject terminal escape sequences.
+     */
+    postInstall?: string;
+    /**
+     * Declarative, all-or-nothing edits to files the buyer's scaffold already
+     * has (spec 5418 § 3 D1) — a sibling of `installMap`/`postInstall` above.
+     * `installMap`/`postInstall` can only ADD or PRINT; `patches` is the only
+     * mechanism that edits an existing scaffolded file (`package.json`,
+     * `tsconfig.json`, `next.config.mjs`, `jest.config.cjs`). Applied by
+     * `applyModulePatches` after `installMap`, before `postInstall` (D5).
+     */
+    patches?: ModulePatch[];
+}
+/**
+ * The four target-file kinds a patch can address (spec 5418 § 3 D1).
+ * `"json"` covers both `package.json` (object-shaped fields: `dependencies`,
+ * `devDependencies`, `scripts`) and `tsconfig.json` (array-shaped:
+ * `references`) — distinguished by which op shape a `path` pairs with, not
+ * by a fourth kind. `next.config.mjs`/`jest.config.cjs` are code, not data,
+ * so each gets its own kind: a `next-config` op has no meaning against
+ * `jest.config.cjs`, and vice versa.
+ */
+export type ModulePatchKind = "json" | "next-config" | "jest-config";
+/** One target file's patch set — every op in `ops` applies to `target`. */
+export interface ModulePatch {
+    /**
+     * Scaffold-relative destination, e.g. "apps/web/package.json". Validated
+     * the same way an `installMap` destination is (D6): `resolve(targetDir,
+     * target)` must stay inside `targetDir`.
+     */
+    target: string;
+    kind: ModulePatchKind;
+    ops: ModulePatchOp[];
+}
+export type ModulePatchOp = JsonMergeKeysOp | JsonAppendUniqueOp | AddTranspilePackageOp | WrapExportWithOp | AddModuleNameMapperOp | AddTransformIgnorePatternOp | AddTransformOp;
+/** kind: "json" — object-shaped field (package.json dependencies/devDependencies/scripts). */
+export interface JsonMergeKeysOp {
+    op: "merge-keys";
+    /** JSON-pointer segments to an OBJECT, e.g. ["dependencies"]. */
+    path: string[];
+    /** key -> value; each key is added, never overwritten (D2). */
+    entries: Record<string, string>;
+}
+/** kind: "json" — array-shaped field (tsconfig.json references). */
+export interface JsonAppendUniqueOp {
+    op: "append-unique";
+    /** Segments to an ARRAY, e.g. ["references"]. */
+    path: string[];
+    /** Appended iff not already deep-equal-present (D2). */
+    items: unknown[];
+}
+/** kind: "next-config". */
+export interface AddTranspilePackageOp {
+    op: "add-transpile-package";
+    /** e.g. "@working-theory/fumadocs-schema". */
+    package: string;
+}
+/** kind: "next-config". */
+export interface WrapExportWithOp {
+    op: "wrap-export-with";
+    /** Exact line, e.g. 'import { createMDX } from "fumadocs-mdx/next";\n'. */
+    importLine: string;
+    /** Exact substring to wrap, e.g. "withNextIntl(nextConfig)". */
+    find: string;
+    /** e.g. "withNextIntl(createMDX()(nextConfig))". */
+    replaceWith: string;
+}
+/** kind: "jest-config". */
+export interface AddModuleNameMapperOp {
+    op: "add-module-name-mapper";
+    /**
+     * The moduleNameMapper KEY, e.g. "^@/\\.source$" — the runtime value this
+     * op carries has two backslash characters, matching jest.config.cjs's own
+     * bytes (D3's escaping rule: the value is the literal text as it occurs in
+     * the target file, never re-escaped for a notation layer above it).
+     */
+    pattern: string;
+    /** The mapped value. */
+    value: string;
+}
+/** kind: "jest-config". */
+export interface AddTransformIgnorePatternOp {
+    op: "add-transform-ignore-pattern";
+    /** The CURRENT array-element string. */
+    find: string;
+    /** The WIDENED replacement. */
+    replaceWith: string;
+}
+/** kind: "jest-config". */
+export interface AddTransformOp {
+    op: "add-transform";
+    /** The transform object's KEY (a regex string). */
+    pattern: string;
+    /** The mapped value, verbatim source text. */
+    value: string;
 }
 /**
  * The module-independent base: `apps/web` (the Next.js presentation shell every
@@ -173,3 +260,32 @@ export declare const MODULE_SLICES: Record<ModuleName, ModuleSlice>;
  *   rejects unrecognized values upstream before they reach derivation).
  */
 export declare function normalizeModules(modules: string[]): ModuleName[];
+/**
+ * Template-relative paths that must never be written into `templates/` for a
+ * keyless starter: every PAID module's `ownedFiles` entry that resolves under
+ * a `build-templates` snapshot root, plus every file under those roots that
+ * imports one (transitively), which would otherwise ship dangling.
+ *
+ * This is the SINGLE starter-removal input for all four R1 extractions
+ * (#5364 commerce, #5365 docs + blog, #5366 signal-collectors, #5367 Pro Plus
+ * + scheduling). A module joins by gaining `ownedFiles` entries — never by
+ * adding a path to a list here.
+ *
+ * The input is `ownedFiles`, NOT the `oss: false` marker set. The two answer
+ * different questions: the strip's authority is their union (see the
+ * `ownedFiles` doc above), while the STARTER's authority is `ownedFiles`
+ * alone. The marker set includes the content-write trio, which D-44 keeps in
+ * public code licence-checked at runtime — deriving the starter exclusion from
+ * markers would remove a surface D-44 says must ship.
+ *
+ * Entries outside the snapshot roots — every `packages/**` path, and the paid
+ * app roots — are not snapshotted at all and are filtered here rather than
+ * special-cased at the call site. Today every glob entry is also out-of-root,
+ * so globs never reach the literal-path matcher below.
+ *
+ * @param snapshotRoots repo-relative roots `build-templates.mjs` snapshots.
+ * @param repoRoot absolute path to the monorepo root, for the import scan.
+ *   Passed in rather than derived from `import.meta.url`, which ts-jest cannot
+ *   load — the same reason `sync-routes.ts` documents for staying pure.
+ */
+export declare function paidModuleTemplateExclusions(snapshotRoots: readonly string[], repoRoot: string): string[];