create-ailk 0.14.0 → 0.15.0

package/dist/site-chrome.d.ts

@@ -76,6 +76,8 @@ export interface TemplateLayout {
     colorMode?: SiteChromeColorMode;
     /** #7742 D1 — `minimal`: the minimal closing slide, consent bar and themed 404. */
     chromeStyle?: SiteChromeChromeStyle;
+    /** #7797 D1 — route paths whose page ends on the closing footer (wordmark, contact lines, legal line). */
+    closingFooterPaths?: readonly string[];
 }
 /** `TemplateLayout` with every field resolved — what `site-chrome.ts` exports. */
 export interface ResolvedSiteChrome {
@@ -93,6 +95,8 @@ export interface ResolvedSiteChrome {
     colorMode?: "light";
     /** Present only when it resolves to "minimal" — never "default" (#7742 D1). */
     chromeStyle?: "minimal";
+    /** Present only when a non-empty list resolves — never `[]` (#7797 D1). */
+    closingFooterPaths?: readonly string[];
 }
 /** Defaults (#5612 D1; banner off since #6469). */
 export declare const DEFAULT_SITE_CHROME: ResolvedSiteChrome;

package/dist/site-chrome.js

@@ -66,6 +66,14 @@ const HOME_VALUES = ["default", "deck"];
 const INNER_PAGES_VALUES = ["default", "bare"];
 const COLOR_MODE_VALUES = ["user", "light"];
 const CHROME_STYLE_VALUES = ["default", "minimal"];
+/**
+ * A `closingFooterPaths` member (#7797): a route path as the site writes it —
+ * a leading "/" and no query, fragment, whitespace or control character. The
+ * layout normalizes the visitor's pathname (locale prefix, trailing slash)
+ * before comparing, so "/about" and "/about/" name the same page.
+ */
+// eslint-disable-next-line no-control-regex -- the class deliberately refuses control characters
+const CLOSING_FOOTER_PATH = /^\/[^\s?#\u0000-\u001f]*$/;
 /**
  * Validate an UNTRUSTED `layout` value (a bundle's `ailk-template.json`
  * `layout` field — arbitrary JSON, never compile-time checked the way the
@@ -144,6 +152,16 @@ export function validateTemplateLayout(value, subject) {
         }
         result.chromeStyle = raw.chromeStyle;
     }
+    if ("closingFooterPaths" in raw && raw.closingFooterPaths !== undefined) {
+        const paths = raw.closingFooterPaths;
+        const badIndex = Array.isArray(paths)
+            ? paths.findIndex((p) => typeof p !== "string" || !CLOSING_FOOTER_PATH.test(p))
+            : -1;
+        if (!Array.isArray(paths) || paths.length === 0 || badIndex !== -1) {
+            throw new TemplateLayoutError(`${subject}: layout.closingFooterPaths must be a non-empty list of route paths ("/about") with no query or fragment — got ${JSON.stringify(badIndex !== -1 ? paths[badIndex] : paths)}`);
+        }
+        result.closingFooterPaths = paths;
+    }
     return result;
 }
 /**
@@ -195,6 +213,12 @@ export function resolveSiteChrome(layout, designLayout) {
     if ((layout?.chromeStyle ?? fromDesign.chromeStyle) === "minimal") {
         resolved.chromeStyle = "minimal";
     }
+    // #7797 D1 — the list resolves as a whole (an explicit layout wins over the
+    // design's), and only a non-empty list is ever a key.
+    const closingFooterPaths = layout?.closingFooterPaths ?? fromDesign.closingFooterPaths;
+    if (closingFooterPaths !== undefined && closingFooterPaths.length > 0) {
+        resolved.closingFooterPaths = closingFooterPaths;
+    }
     return resolved;
 }
 /**
@@ -225,6 +249,10 @@ export function renderSiteChrome(resolved) {
     // only for the opt-in values.
     const colorModeValue = resolved.colorMode === "light" ? '\n  colorMode: "light",' : "";
     const chromeStyleValue = resolved.chromeStyle === "minimal" ? '\n  chromeStyle: "minimal",' : "";
+    // #7797 D1 — the same form: member and bullet always, the value line only for a non-empty list.
+    const closingFooterPathsValue = resolved.closingFooterPaths === undefined
+        ? ""
+        : `\n  closingFooterPaths: [${resolved.closingFooterPaths.map((p) => JSON.stringify(p)).join(", ")}],`;
     return `// site-chrome.ts — resolved template layout knobs.
 //
 // GENERATED by create-ailk from the declared template's \`layout\` block
@@ -247,7 +275,9 @@ export function renderSiteChrome(resolved) {
 //     switch; dark appears only as a deck ground.
 //   - chromeStyle: "minimal" → the deck's closing slide is the wordmark,
 //     contact lines and one legal line; the consent bar is a hairline bar on
-//     the page ground; the 404 renders in the site's theme.${groundsComment}
+//     the page ground; the 404 renders in the site's theme.
+//   - closingFooterPaths → each listed inner page ends on the closing footer
+//     (the wordmark, contact lines and legal line) instead of its usual footer.${groundsComment}
 
 export interface SiteChrome {
   nav: "full" | "mark-only";
@@ -257,14 +287,15 @@ export interface SiteChrome {
   innerPages?: "bare";
   deckPresentation?: true;
   colorMode?: "light";
-  chromeStyle?: "minimal";${groundsMember}
+  chromeStyle?: "minimal";
+  closingFooterPaths?: readonly string[];${groundsMember}
 }
 
 export const siteChrome: SiteChrome = {
   nav: ${JSON.stringify(resolved.nav)},
   footer: ${JSON.stringify(resolved.footer)},
   announcementBanner: ${JSON.stringify(resolved.announcementBanner)},
-  home: ${JSON.stringify(resolved.home)},${groundsValue}${innerPagesValue}${presentationValue}${colorModeValue}${chromeStyleValue}
+  home: ${JSON.stringify(resolved.home)},${groundsValue}${innerPagesValue}${presentationValue}${colorModeValue}${chromeStyleValue}${closingFooterPathsValue}
 };
 `;
 }

package/dist/site-manifest.d.ts

@@ -2,6 +2,7 @@ import type { Level } from "./lib/module-tier.js";
 import type { ModuleName } from "./parse-args.js";
 import { type SiteRoster } from "./site-roster.js";
 import type { MarkerMap } from "./substitute.js";
+import type { Topology } from "./topology.js";
 export interface PlanSiteManifestOptions {
     targetDir: string;
     /** The installed manifest, read after every layer landed. */
@@ -10,16 +11,22 @@ export interface PlanSiteManifestOptions {
     modules: readonly ModuleName[];
     /** The level the key path derived, or undefined when it derived none. */
     level: Level | undefined;
+    /** The scaffold's topology (#7426 D10). */
+    topology: Topology;
+    /** The create-ailk version that wrote the scaffold (`CREATE_AILK_VERSION`). */
+    patternVersion: string;
     siteTemplatesDir: string;
     templatesDir: string;
     markers: MarkerMap;
 }
 /**
- * The manifest's next text: `modules` (and `level`, when derived) after
- * `requires`, and a row for every route present on disk.
+ * The manifest's next text: `modules` (and `level`, when derived), then
+ * `topology` and `patternVersion`, after `requires`, and a row for every
+ * route present on disk.
  *
- * @throws AddModuleRefusedError when the file already records `modules` or
- *   `level`, or its layout is not the generator's (`rows` last, `requires`
- *   at the top level) — guessing would silently mis-record the site.
+ * @throws AddModuleRefusedError when the file already records `modules`,
+ *   `level`, `topology` or `patternVersion`, or its layout is not the
+ *   generator's (`rows` last, `requires` at the top level) — guessing would
+ *   silently mis-record the site.
  */
 export declare function planSiteManifest(opts: PlanSiteManifestOptions): string;

package/dist/site-manifest.js

@@ -15,6 +15,10 @@
  *     (`resolveModuleSet` / `deriveLevel`). Never inferred from `modules`:
  *     the level comes only from the key. An alias or `--modules` keep run
  *     derives none and records none;
+ *   - `topology` and `patternVersion` (#7426 D10) — `"hub"` or `"spoke"`,
+ *     and the create-ailk version that wrote the files, on every scaffold.
+ *     A site with no `topology` predates the option and reads as a hub
+ *     (`topology.ts` `readSiteTopology`);
  *   - a row for every route present on disk — each module's contributed rows
  *     through `planRosterAppend` (add-module's own append), the sample pages
  *     a module's bundle installs (`sampleRows`), and a code-route row for any
@@ -51,16 +55,18 @@ const CODE_ROUTE_ROW = {
     sections: [],
 };
 /**
- * The manifest's next text: `modules` (and `level`, when derived) after
- * `requires`, and a row for every route present on disk.
+ * The manifest's next text: `modules` (and `level`, when derived), then
+ * `topology` and `patternVersion`, after `requires`, and a row for every
+ * route present on disk.
  *
- * @throws AddModuleRefusedError when the file already records `modules` or
- *   `level`, or its layout is not the generator's (`rows` last, `requires`
- *   at the top level) — guessing would silently mis-record the site.
+ * @throws AddModuleRefusedError when the file already records `modules`,
+ *   `level`, `topology` or `patternVersion`, or its layout is not the
+ *   generator's (`rows` last, `requires` at the top level) — guessing would
+ *   silently mis-record the site.
  */
 export function planSiteManifest(opts) {
     const { roster } = opts;
-    for (const key of ["modules", "level"]) {
+    for (const key of ["modules", "level", "topology", "patternVersion"]) {
         if (key in roster.doc) {
             throw new AddModuleRefusedError(`${roster.path} already records "${key}"`);
         }
@@ -81,7 +87,7 @@ export function planSiteManifest(opts) {
         ...codeRouteRows(opts.targetDir, declared),
     ];
     const withRows = appendRows(appended, extra, roster);
-    return insertRecord(withRows, opts.modules, opts.level, roster.path);
+    return insertRecord(withRows, opts, roster.path);
 }
 /**
  * The rows for the sample pages a module's bundle installs through its
@@ -233,8 +239,12 @@ function appendRows(text, rows, roster) {
         ? text.slice(0, end) + rendered + roster.trail + text.slice(close)
         : text.slice(0, end) + "," + rendered + text.slice(end);
 }
-/** `text` with `modules` (and `level`, when derived) inserted after the top-level `requires`. */
-function insertRecord(text, modules, level, label) {
+/**
+ * `text` with `modules` (and `level`, when derived), `topology` and
+ * `patternVersion` inserted after the top-level `requires`.
+ */
+function insertRecord(text, opts, label) {
+    const { modules, level, topology, patternVersion } = opts;
     const anchor = '\n  "requires": ';
     const at = text.indexOf(anchor);
     if (at === -1 || text.indexOf(anchor, at + 1) !== -1) {
@@ -243,11 +253,15 @@ function insertRecord(text, modules, level, label) {
     const end = text.indexOf("]", at) + 1;
     const name = '"modules": ';
     const record = `,\n  ${name}${renderJson([...modules], 2, name.length, 1)}` +
-        (level !== undefined ? `,\n  "level": ${JSON.stringify(level)}` : "");
+        (level !== undefined ? `,\n  "level": ${JSON.stringify(level)}` : "") +
+        `,\n  "topology": ${JSON.stringify(topology)}` +
+        `,\n  "patternVersion": ${JSON.stringify(patternVersion)}`;
     const next = text.slice(0, end) + record + text.slice(end);
     const doc = JSON.parse(next);
     if (!isDeepStrictEqual(doc["modules"], [...modules]) ||
-        doc["level"] !== level) {
+        doc["level"] !== level ||
+        doc["topology"] !== topology ||
+        doc["patternVersion"] !== patternVersion) {
         throw new AddModuleRefusedError(`${label}: the module set could not be recorded beside "requires"`);
     }
     return next;

package/dist/sync-routes.js

@@ -33,6 +33,7 @@ import { parseArgs } from "node:util";
 import { copyTemplate } from "./copy.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
+import { isSpokeExcluded, readSiteTopology } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
 /**
@@ -163,12 +164,20 @@ export function syncRoutes(opts) {
             skippedSurfaces.push(surface.id);
     }
     skippedSurfaces.sort();
+    // #7426 D13 — on a spoke, a route dir the spoke does not carry (the
+    // `(auth)` and `(authed)` groups) is out of scope: neither reported nor
+    // copied. This is the one filter point for add-module, add-route and the
+    // sync-routes subcommand alike; a hub's scope is unchanged.
+    const spoke = readSiteTopology(targetAbs) === "spoke"
+        ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
+        : undefined;
     const inScope = listTemplateRouteDirs(opts.templatesDir)
         .map(reportFor)
         // "authed" (#5014): the `(authed)` route group ships unconditionally in
-        // every scaffold today, the same as "core" — it is checked regardless of
+        // every hub scaffold, the same as "core" — it is checked regardless of
         // `carried`, which only tracks GATEABLE_SURFACES opt-in.
-        .filter((r) => r.surface === "core" || r.surface === "authed" || carried.has(r.surface));
+        .filter((r) => r.surface === "core" || r.surface === "authed" || carried.has(r.surface))
+        .filter((r) => spoke === undefined || !isSpokeExcluded(`${ROUTE_ROOT}/${r.route}`, spoke));
     // Identical to scaffoldSync's defaults, so a synced route matches a fresh
     // scaffold of the same target byte-for-byte.
     const markers = {

package/dist/topology.d.ts

@@ -0,0 +1,131 @@
+import { type ModuleName } from "./parse-args.js";
+/** The two topologies. `hub` is the default and the only one before #7426. */
+export declare const TOPOLOGIES: readonly ["hub", "spoke"];
+export type Topology = (typeof TOPOLOGIES)[number];
+/** A refusal or a malformed input this module names. */
+export declare class TopologyError extends Error {
+    constructor(message: string);
+}
+/** Roots no spoke carries. `apps/mcp` joins them with `--without-mcp`. */
+export declare const SPOKE_REMOVED_ROOTS: readonly string[];
+/** The root `--without-mcp` removes. */
+export declare const SPOKE_MCP_ROOT = "apps/mcp";
+/**
+ * The sign-in and database files a spoke does not carry — files and
+ * directories, scaffold-relative. Every other file that imports one of them
+ * goes with it (`spokeExclusions`).
+ */
+export declare const SPOKE_REMOVAL_SEEDS: readonly string[];
+/** The two generated seam files (D5). A seam is rewritten, never removed. */
+export declare const WEB_SEAM_PATH = "apps/web/lib/topology.generated.ts";
+export declare const MCP_SEAM_PATH = "apps/mcp/src/lib/topology.generated.ts";
+export declare const SPOKE_SEAM_FILES: readonly string[];
+/**
+ * The closure's allow-list: a file `spokeExclusions` removes must sit under
+ * one of these prefixes, or under a `__tests__/` directory. A member outside
+ * both is a defect — a shared file started importing a sign-in or database
+ * file — and `spokeExclusions` throws naming it rather than cut it silently.
+ */
+export declare const SPOKE_REMOVABLE_PREFIXES: readonly string[];
+export interface SpokeShapeOptions {
+    /** Whether the spoke keeps `apps/mcp` (the default; `--without-mcp` drops it). */
+    mcp: boolean;
+}
+/** The removed roots for these options. */
+export declare function spokeRemovedRoots(opts: SpokeShapeOptions): string[];
+/** Whether a closure member is one the registry allows a spoke to drop. */
+export declare function isRemovableClosureMember(path: string): boolean;
+/**
+ * Every path a spoke does not carry, computed over the built `templates/`
+ * tree: the removed roots, the seeds that apply, and every source file under
+ * the kept apps that reaches a seed through relative imports, to a fixed
+ * point. Sorted; directories and files alike, matched at a directory
+ * boundary by `isSpokeExcluded` and `copyTemplate`'s `excludePaths`.
+ *
+ * The walk is the relative-import resolution `importClosure` uses
+ * (`lib/import-graph.ts`), with ONE difference: a seam file is never a
+ * candidate, so the walk never crosses it. The hub render of a seam imports
+ * a seed by design (D5); its importers keep their place on a spoke because
+ * the spoke render of the same file imports none.
+ *
+ * @throws TopologyError naming every closure member outside
+ *   `SPOKE_REMOVABLE_PREFIXES` and not a test — a new shared file importing
+ *   a sign-in or database file, which removing would silently break the
+ *   spoke (spec § 5.3: escalate, never widen).
+ */
+export declare function spokeExclusions(templatesDir: string, opts: SpokeShapeOptions): string[];
+export interface IsSpokeExcludedOptions extends SpokeShapeOptions {
+    /**
+     * The full `spokeExclusions(...)` list, when the caller computed it. Absent,
+     * only the removed roots and the seeds are checked — exact for any path
+     * that is not a file of the built `templates/` tree (a module bundle's
+     * file, a route directory), since only a template file can be a closure
+     * member.
+     */
+    exclusions?: readonly string[];
+}
+/**
+ * The one predicate for "a spoke does not carry this path" (the Phase 2
+ * generator contract). Scaffold-relative, `/`- or `\`-separated.
+ */
+export declare function isSpokeExcluded(path: string, opts: IsSpokeExcludedOptions): boolean;
+/** `apps/web/lib/topology.generated.ts` for `topology` (D5). */
+export declare function renderWebSeam(topology: Topology): string;
+/** `apps/mcp/src/lib/topology.generated.ts` for `topology` (D5). */
+export declare function renderMcpSeam(topology: Topology): string;
+/** `pnpm-workspace.yaml` without its `database` package entry. */
+export declare function transformWorkspaceYaml(text: string): string;
+/** The root `package.json` without its `db:*` scripts. */
+export declare function transformRootPackageJson(text: string): string;
+/** The root `tsconfig.json` without a reference under a removed root. */
+export declare function transformRootTsconfig(text: string, opts: SpokeShapeOptions): string;
+/**
+ * An app's `package.json` without its `@working-theory/database` dependency.
+ * @throws TopologyError when `required` and the dependency is absent.
+ */
+export declare function transformAppPackageJson(text: string, label: string, required: boolean): string;
+/**
+ * Apply every D6 root-file transform to the spoke at `targetDir` (after the
+ * base copy, before any module or template layer), and write the spoke
+ * render of each seam it carries (D5).
+ * @throws TopologyError naming the file whose anchor is missing.
+ */
+export declare function applySpokeTransforms(targetDir: string, opts: SpokeShapeOptions): void;
+/** The env var a spoke reaches its hub through. */
+export declare const HUB_ORIGIN_ENV_VAR = "AILK_API_URL";
+/**
+ * Write `AILK_API_URL=<origin>` to the spoke's `apps/web/.env.local` (D2) —
+ * the `auth-secret-file.ts` never-clobber rule: an assignment already in any
+ * env file Next loads for `apps/web` is kept, and `.env.local` stays
+ * gitignored. Never writes `AILK_SPOKE_KEY` or `AILK_VISITOR_FORWARD_KEY`:
+ * the hub issues those.
+ */
+export declare function writeHubOriginEnv(targetDir: string, origin: string): void;
+/** The `hard_floors:` block a spoke's `project.yaml` carries (D9). */
+export declare function renderSpokeHardFloors(opts: SpokeShapeOptions): string;
+/** `project.yaml` with its `hard_floors:` block replaced by the spoke's (D9). */
+export declare function transformProjectYaml(text: string, opts: SpokeShapeOptions): string;
+/** The modules a spoke may carry — every slice declaring `spoke: true`. */
+export declare function spokeModules(): ModuleName[];
+/** The refusal for a module a spoke cannot carry, or undefined when admitted. */
+export declare function spokeModuleRefusal(name: ModuleName): string | undefined;
+/**
+ * The topology `<targetDir>` records. A missing manifest, or one without a
+ * `topology` key, reads as `"hub"` — every site scaffolded before #7426.
+ * @throws TopologyError on an unreadable manifest or an unknown value.
+ */
+export declare function readSiteTopology(targetDir: string): Topology;
+/**
+ * Hosts a spoke may reach over plain `http:` — the set
+ * `packages/api-client/src/http.ts` sends the spoke key under. Named here
+ * rather than imported: create-ailk carries no runtime dependency.
+ */
+export declare const LOOPBACK_HOSTS: readonly string[];
+/**
+ * The hub origin for a spoke: `--hub-url`, else `AILK_API_URL`. An `https:`
+ * URL, or `http:` on a loopback host, with no path but `/`, no query and no
+ * fragment — normalized to its origin with no trailing slash.
+ * @throws TopologyError naming both inputs when neither is set or the value
+ *   is not such an origin. Never echoes a query or fragment.
+ */
+export declare function normalizeHubUrl(raw: string | undefined): string;