create-ailk 0.14.0 → 0.16.0

package/dist/topology.js

@@ -0,0 +1,942 @@
+/**
+ * The spoke topology (#7426) — `create-ailk --topology spoke`.
+ *
+ * A spoke is the existing scaffold with nodes REMOVED, never a second
+ * template tree: no `apps/api`, no `database/`, no sign-in, and `apps/mcp`
+ * kept as a stateless front unless `--without-mcp`. Its forms, flows and
+ * listings reach a hub at `AILK_API_URL` from server code. Everything that
+ * decides what a spoke is lives here, in one registry, so the spoke tree
+ * cannot drift from the hub tree it is cut from:
+ *
+ *   - `SPOKE_REMOVED_ROOTS` / `SPOKE_REMOVAL_SEEDS` and `spokeExclusions` —
+ *     the paths a spoke does not carry: the removed roots, the sign-in and
+ *     database seeds, and every file that imports a seed (D4);
+ *   - `isSpokeExcluded` — the ONE predicate every writer (the base copy,
+ *     each module bundle, the template layer, the later commands) asks;
+ *   - the two generated seam files (D5) — the only place hub and spoke code
+ *     differ, rendered here for either topology;
+ *   - the root-file transforms (D6), the hard floors (D9), the module
+ *     admission (D7), the manifest reader (D10) and the hub origin (D2);
+ *   - the sign-in-through-the-hub mode (`signIn: "hub"`, #7894): its seeds,
+ *     its renders of the web and `(authed)` gate seams, its env and floors.
+ *
+ * Specs: docs/specs/7426-spoke-topology-option-spec.md,
+ * docs/specs/7894-the-hub-signs-in-its-spec.md (D1, D8, D9, D11).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly. The
+ * package's own `templates/` dir is supplied by the caller.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { ENV_LOCAL_IGNORE_LINES } from "./lib/auth-secret-file.js";
+import { listFilesUnder, relativeImportsOf, resolveRelativeImport, } from "./lib/import-graph.js";
+import { appendLine, writeOwnerOnly } from "./lib/license-key-files.js";
+import { MODULE_SLICES } from "./module-architecture.js";
+import { RECOGNIZED_MODULES } from "./parse-args.js";
+/** The two topologies. `hub` is the default and the only one before #7426. */
+export const TOPOLOGIES = ["hub", "spoke"];
+/** A refusal or a malformed input this module names. */
+export class TopologyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TopologyError";
+    }
+}
+// ── D4 — the removal registry ──────────────────────────────────────────────
+/** Roots no spoke carries. `apps/mcp` joins them with `--without-mcp`. */
+export const SPOKE_REMOVED_ROOTS = ["apps/api", "database"];
+/** The root `--without-mcp` removes. */
+export const SPOKE_MCP_ROOT = "apps/mcp";
+/** Commerce's apps/web files that reach the hub's own checkout (spoke-intake Rule 3, #7838). */
+export const SPOKE_HUB_CHECKOUT_SEEDS = [
+    "apps/web/app/[locale]/flows/[slug]/checkout.actions.ts",
+    "apps/web/app/[locale]/flows/[slug]/results",
+    "apps/web/app/[locale]/dev/purchase",
+];
+/**
+ * The files a spoke does not carry — files and directories, scaffold-relative:
+ * the sign-in and database seeds, then the commerce files that call the hub's
+ * own checkout (`SPOKE_HUB_CHECKOUT_SEEDS`; a spoke keeps its own, #7838).
+ * Every other file that imports one of them goes with it (`spokeExclusions`).
+ */
+export const SPOKE_REMOVAL_SEEDS = [
+    "apps/web/auth.ts",
+    "apps/web/lib/prisma-for-auth.ts",
+    "apps/web/lib/license-key-store.ts",
+    "apps/web/app/api/auth",
+    "apps/web/app/[locale]/(auth)",
+    "apps/web/app/[locale]/(authed)",
+    "apps/mcp/src/lib/prisma.ts",
+    "apps/mcp/src/lib/public-workspace.ts",
+    "apps/mcp/src/lib/license-key-store.ts",
+    ...SPOKE_HUB_CHECKOUT_SEEDS,
+];
+/**
+ * Module paths a spoke drops even when it carries the module (#7876 D8,
+ * clarified 2026-10-09). `signal-collectors`' report reader links a
+ * grant-gated report's bytes on the hub from `NEXT_PUBLIC_AILK_API_URL`,
+ * which a spoke refuses (#7874: its hub origin is server-only), and a
+ * deliverable is hub-side anyway — so a spoke carries neither the
+ * `/reports` routes nor the report seeds that would have no route.
+ */
+export const SPOKE_EXCLUDED_MODULE_PATHS = [
+    "apps/web/app/[locale]/reports",
+    "content/en/ReportPage",
+    "content/en/ReportsList",
+];
+/**
+ * The `(authed)` seeds of the sign-in-through-the-hub mode (#7894 D9): the
+ * whole `(authed)` group goes in the default mode; in the hub mode its account
+ * area, layout and gate seam stay, and only these go — the operator surfaces,
+ * the Better Auth gate and the suites that mock `auth.ts` by path.
+ */
+export const HUB_MODE_AUTHED_SEEDS = [
+    "apps/web/app/[locale]/(authed)/__tests__",
+    "apps/web/app/[locale]/(authed)/account/__tests__",
+    "apps/web/app/[locale]/(authed)/admin",
+    "apps/web/app/[locale]/(authed)/appointments",
+    "apps/web/app/[locale]/(authed)/edit",
+    "apps/web/app/[locale]/(authed)/leads",
+    "apps/web/app/[locale]/(authed)/waitlist",
+    "apps/web/app/[locale]/(authed)/sign-in-gate.tsx",
+];
+/** The default mode's one `(authed)` seed, which the hub mode replaces. */
+const AUTHED_SEED = "apps/web/app/[locale]/(authed)";
+/** The generated seam files (D5; #7874 D12). A seam is rewritten, never removed. */
+export const WEB_SEAM_PATH = "apps/web/lib/topology.generated.ts";
+export const MCP_SEAM_PATH = "apps/mcp/src/lib/topology.generated.ts";
+/** The browser API origin seam (#7874 D12): a spoke's render reads no env. */
+export const API_ORIGIN_SEAM_PATH = "apps/web/lib/api-origin.generated.ts";
+/**
+ * The `(authed)` layout's signed-out gate (#7894 D8). Under the `(authed)`
+ * seed, so a default-mode spoke drops it with its group and never renders it.
+ */
+export const AUTHED_GATE_SEAM_PATH = "apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx";
+export const SPOKE_SEAM_FILES = [
+    WEB_SEAM_PATH,
+    MCP_SEAM_PATH,
+    API_ORIGIN_SEAM_PATH,
+    AUTHED_GATE_SEAM_PATH,
+];
+/**
+ * Template files only a spoke carries (#7874 D11): the declared-env check.
+ * `scaffoldSync` excludes them from a hub's copy (`copyTemplate`'s
+ * `excludePaths` matches an exact file path).
+ */
+export const SPOKE_ONLY_FILES = [
+    "tools/declared-env.ts",
+    "tools/check-declared-env.ts",
+];
+/**
+ * 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 const SPOKE_REMOVABLE_PREFIXES = SPOKE_REMOVAL_SEEDS;
+/** The seeds for a sign-in mode, before the mcp filter. */
+function modeSeeds(signIn) {
+    return signIn === "hub"
+        ? SPOKE_REMOVAL_SEEDS.flatMap((seed) => seed === AUTHED_SEED ? [...HUB_MODE_AUTHED_SEEDS] : [seed])
+        : [...SPOKE_REMOVAL_SEEDS];
+}
+function toPosix(path) {
+    return path.split("\\").join("/").replace(/^\.\//, "");
+}
+/** `path` equals `prefix` or sits below it, at a directory boundary. */
+function underPrefix(path, prefix) {
+    const p = prefix.replace(/\/+$/, "");
+    return path === p || path.startsWith(`${p}/`);
+}
+/** The removed roots for these options. */
+export function spokeRemovedRoots(opts) {
+    return opts.mcp
+        ? [...SPOKE_REMOVED_ROOTS]
+        : [...SPOKE_REMOVED_ROOTS, SPOKE_MCP_ROOT];
+}
+/**
+ * The seeds that apply — an mcp seed is moot when `apps/mcp` itself goes; in
+ * the hub sign-in mode the `(authed)` seed is replaced by eight (#7894 D9).
+ */
+function spokeSeeds(opts) {
+    return modeSeeds(opts.signIn).filter((seed) => opts.mcp || !underPrefix(seed, SPOKE_MCP_ROOT));
+}
+/**
+ * Whether a closure member is one the registry allows a spoke to drop: under
+ * a seed of THAT sign-in mode, or a test. In the hub mode a surviving account
+ * file that imports `auth.ts` is therefore not removable, and
+ * `spokeExclusions` throws naming it (#7894 D9).
+ */
+export function isRemovableClosureMember(path, opts = {}) {
+    const p = toPosix(path);
+    const prefixes = opts.signIn === "hub" ? modeSeeds("hub") : SPOKE_REMOVABLE_PREFIXES;
+    return (p.split("/").includes("__tests__") ||
+        prefixes.some((prefix) => underPrefix(p, prefix)));
+}
+/**
+ * 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 function spokeExclusions(templatesDir, opts) {
+    const roots = ["apps/web", ...(opts.mcp ? [SPOKE_MCP_ROOT] : [])];
+    const seeds = spokeSeeds(opts);
+    const seams = new Set(SPOKE_SEAM_FILES);
+    const candidates = listFilesUnder(templatesDir, roots);
+    for (const seam of seams)
+        candidates.delete(seam);
+    const closed = new Set();
+    for (const file of candidates) {
+        if (seeds.some((seed) => underPrefix(file, seed)))
+            closed.add(file);
+    }
+    for (;;) {
+        let grew = false;
+        for (const file of candidates) {
+            if (closed.has(file))
+                continue;
+            for (const spec of relativeImportsOf(join(templatesDir, file))) {
+                const target = resolveRelativeImport(file, spec, candidates);
+                if (target !== undefined && closed.has(target)) {
+                    closed.add(file);
+                    grew = true;
+                    break;
+                }
+            }
+        }
+        if (!grew)
+            break;
+    }
+    const outside = [...closed]
+        .filter((file) => !isRemovableClosureMember(file, opts))
+        .sort();
+    if (outside.length > 0) {
+        throw new TopologyError(`a spoke cannot drop ${outside.join(", ")}: ${outside.length === 1 ? "it imports" : "each imports"} a sign-in or database file, and ${outside.length === 1 ? "it is" : "they are"} not a sign-in path or a test. Move the import behind the generated seam (${WEB_SEAM_PATH} / ${MCP_SEAM_PATH}) rather than widening SPOKE_REMOVABLE_PREFIXES.`);
+    }
+    const covered = (file) => seeds.some((seed) => underPrefix(file, seed));
+    return [
+        ...new Set([
+            ...spokeRemovedRoots(opts),
+            ...seeds,
+            ...[...closed].filter((file) => !covered(file)),
+        ]),
+    ].sort();
+}
+/**
+ * The one predicate for "a spoke does not carry this path" (the Phase 2
+ * generator contract). Scaffold-relative, `/`- or `\`-separated.
+ */
+export function isSpokeExcluded(path, opts) {
+    const p = toPosix(path);
+    const prefixes = opts.exclusions ?? [
+        ...spokeRemovedRoots(opts),
+        ...spokeSeeds(opts),
+    ];
+    return [...prefixes, ...SPOKE_EXCLUDED_MODULE_PATHS].some((prefix) => underPrefix(p, prefix));
+}
+/** A module flow file a hub installs under `database/` (#7876 D10). */
+const DATABASE_FLOW_FILE = /^database\/flows\/([^/]+)\.flow\.json$/;
+/**
+ * Where a module bundle's `installMap` destination lands on a spoke (#7876
+ * D10): `database/flows/<name>.flow.json` becomes `flows/<name>.json` — a
+ * declared flow `create-ailk seed-flows` sends to the hub — and every other
+ * destination is returned unchanged. Applied before the spoke filter, so a
+ * remapped flow survives it while the rest of `database/` is dropped. A hub
+ * install passes no remap.
+ */
+export function spokeDestination(destination) {
+    const match = DATABASE_FLOW_FILE.exec(toPosix(destination));
+    return match ? `flows/${match[1]}.json` : destination;
+}
+// ── D5 — the generated seam files ───────────────────────────────────────────
+const WEB_SEAM_HEADER = `// topology.generated.ts — how this site reads a session and registers its stores.
+//
+// GENERATED by create-ailk for this site's topology (#7426). Do not edit:
+// every scaffold rewrites it. A hub reads the session through Better Auth.
+// A spoke (\`--topology spoke\`) has no database of its own: by default it
+// has no sign-in, so its render reads no session and imports nothing; with
+// \`--hub-sign-in\` (#7894) it reads the sealed hub-session cookie.`;
+const MCP_SEAM_HEADER = `// topology.generated.ts — how this MCP server resolves its workspace store.
+//
+// GENERATED by create-ailk for this site's topology (#7426). Do not edit:
+// every scaffold rewrites it. A hub resolves its workspace through the
+// database; a spoke (\`--topology spoke\`) has none, so its content tools
+// read the spoke's own MDX and its writes go to the hub at AILK_API_URL.`;
+const SITE_SESSION_TYPE = `export type SiteSession = {
+  user: {
+    name?: string | null;
+    email: string;
+    emailVerified: boolean;
+    createdAt?: Date | string | null;
+  };
+} | null;`;
+/** The sign-in exports every web seam render carries (#7894 D8). */
+function signInExports(values) {
+    const literal = (value) => value === null ? "null" : JSON.stringify(value);
+    return `export const SIGN_IN_ENABLED: boolean = ${values.enabled};
+export const SIGN_IN_PROVIDER: "site" | "hub" | "none" = ${JSON.stringify(values.provider)};
+export const SIGN_IN_PATH: string | null = ${literal(values.signInPath)};
+export const SIGN_UP_PATH: string | null = ${literal(values.signUpPath)};
+export const SIGN_OUT_ENDPOINT: string | null = ${literal(values.signOutEndpoint)};`;
+}
+/**
+ * `apps/web/lib/topology.generated.ts` for `topology` (D5) and, on a spoke,
+ * its sign-in mode (#7894 D8). The hub render loads `auth.ts` only when a
+ * session is read, so a module that imports this seam for a constant never
+ * loads Better Auth.
+ */
+export function renderWebSeam(topology, signIn = "off") {
+    if (topology === "hub") {
+        return `${WEB_SEAM_HEADER}
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+${signInExports({ enabled: true, provider: "site", signInPath: "/sign-in", signUpPath: "/sign-up", signOutEndpoint: null })}
+
+${SITE_SESSION_TYPE}
+
+export async function readSession(headers: Headers): Promise<SiteSession> {
+  const { auth } = await import("../auth");
+  return auth.api.getSession({ headers });
+}
+
+export async function registerSiteStores(): Promise<void> {
+  const { registerLicenseKeyStore } = await import("./license-key-store");
+  await registerLicenseKeyStore();
+}
+`;
+    }
+    if (signIn === "hub") {
+        return `${WEB_SEAM_HEADER}
+import { readHubSession } from "./hub-session/session";
+
+export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${signInExports({ enabled: true, provider: "hub", signInPath: "/account", signUpPath: null, signOutEndpoint: "/api/hub-session/sign-out" })}
+
+${SITE_SESSION_TYPE}
+
+export function readSession(headers: Headers): Promise<SiteSession> {
+  return readHubSession(headers);
+}
+
+export function registerSiteStores(): Promise<void> {
+  return Promise.resolve();
+}
+`;
+    }
+    return `${WEB_SEAM_HEADER}
+
+export const TOPOLOGY: "hub" | "spoke" = "spoke";
+${signInExports({ enabled: false, provider: "none", signInPath: null, signUpPath: null, signOutEndpoint: null })}
+
+${SITE_SESSION_TYPE}
+
+export function readSession(headers: Headers): Promise<SiteSession> {
+  void headers;
+  return Promise.resolve(null);
+}
+
+export function registerSiteStores(): Promise<void> {
+  return Promise.resolve();
+}
+`;
+}
+const AUTHED_GATE_SEAM_HEADER = `// signed-out-gate.generated.tsx — what the (authed) group shows a signed-out visitor.
+//
+// GENERATED by create-ailk for this site's topology and sign-in mode (#7894).
+// Do not edit: every scaffold rewrites it. A hub renders its own sign-in —
+// the operator gate, or the account area's member gate; a spoke that signs in
+// through its hub (\`--hub-sign-in\`) renders the hub-session gate.`;
+/**
+ * The packages the gate seam imports. Interpolated, not written inline, for
+ * the reason `CONTENT_ADAPTERS_PACKAGE` below is.
+ */
+const UI_PACKAGE = "@working-theory/ui";
+const WEB_I18N_PACKAGE = "@working-theory/web-i18n";
+const NEXT_INTL_SERVER = "next-intl/server";
+const REACT_PACKAGE = "react";
+const AUTHED_GATE_PROPS = `export interface SignedOutGateProps {
+  locale: string;
+  /** The incoming request's headers (\`x-pathname\` names the requested page). */
+  requestHeaders: Headers;
+}`;
+/**
+ * `apps/web/app/[locale]/(authed)/signed-out-gate.generated.tsx` (#7894 D8).
+ * The hub render is the `(authed)` layout's no-session branch, moved; the
+ * `signIn: "hub"` render imports only the hub-session gate. A default-mode
+ * spoke carries no `(authed)` group, so it has no render.
+ * @throws TopologyError for a spoke in the default mode.
+ */
+export function renderAuthedGateSeam(topology, signIn = "off") {
+    if (topology === "hub") {
+        return `${AUTHED_GATE_SEAM_HEADER}
+import { localeHref } from "${UI_PACKAGE}";
+import { Button, Heading, Link, Text } from "${UI_PACKAGE}/primitives";
+import type { AuthPanelProvider } from "${UI_PACKAGE}/sections";
+import { readLocales } from "${WEB_I18N_PACKAGE}";
+import { getTranslations } from "${NEXT_INTL_SERVER}";
+import type { ReactElement } from "${REACT_PACKAGE}";
+
+import { resolveSignInCardText } from "../(auth)/sign-in/sign-in-text";
+import { getActiveProviderIds } from "../../../lib/auth-env";
+import { isAccountPath } from "../../../lib/auth-routes";
+
+import { SignInGate } from "./sign-in-gate";
+
+const SUPPORTED_PROVIDERS: readonly AuthPanelProvider[] = ["google", "github"];
+
+${AUTHED_GATE_PROPS}
+
+export async function SignedOutGate({
+  locale,
+  requestHeaders,
+}: SignedOutGateProps): Promise<ReactElement> {
+  // No \`x-pathname\`, no locale read: a render outside the middleware keeps
+  // the operator gate without touching the locale config.
+  const pathname = requestHeaders.get("x-pathname");
+  const isAccount =
+    pathname !== null && isAccountPath(pathname, readLocales());
+  const t = await getTranslations({
+    locale,
+    namespace: isAccount ? "account.gate" : "waitlistDashboard.gate",
+  });
+  const active = getActiveProviderIds();
+  const emailLink = active.includes("magic-link")
+    ? { text: await resolveSignInCardText(locale) }
+    : undefined;
+  const providers = active.filter((id): id is AuthPanelProvider =>
+    (SUPPORTED_PROVIDERS as readonly string[]).includes(id),
+  );
+  const signInPath = localeHref(locale, "/sign-in");
+
+  if (isAccount && providers.length === 0 && !emailLink) {
+    return (
+      <div
+        className="flex min-h-screen flex-col items-center justify-center gap-4 py-section text-center"
+        data-testid="account-sign-in-gate"
+      >
+        <Heading level={1} visual={4}>
+          {t("emptyHeadline")}
+        </Heading>
+        <Text variant="body-sm" tone="muted" className="max-w-xs">
+          {t("emptyDescription")}
+        </Text>
+        {/* With no sign-in method on, /sign-in has nothing for a member
+            either, so the one action goes back to the site. Outline
+            action, 44px on a phone and 36px from md up. */}
+        <Button asChild variant="secondary" className="max-md:min-h-11">
+          <Link
+            href={localeHref(locale, "/")}
+            variant="bare"
+            data-testid="account-sign-in-gate-home"
+          >
+            {t("homeLink")}
+          </Link>
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <SignInGate
+      labels={{
+        emptyHeadline: t("emptyHeadline"),
+        emptyDescription: t("emptyDescription"),
+        signInLinkLabel: t("signInLink"),
+      }}
+      signInPath={signInPath}
+      providers={providers}
+      {...(emailLink ? { emailLink } : {})}
+    />
+  );
+}
+`;
+    }
+    if (signIn !== "hub") {
+        throw new TopologyError(`${AUTHED_GATE_SEAM_PATH}: a spoke without --hub-sign-in carries no (authed) group, so it has no gate to render`);
+    }
+    return `${AUTHED_GATE_SEAM_HEADER}
+import type { ReactElement } from "${REACT_PACKAGE}";
+
+import { HubSignInGate } from "../../../lib/hub-session/sign-in-gate";
+
+${AUTHED_GATE_PROPS}
+
+export function SignedOutGate({
+  locale,
+  requestHeaders,
+}: SignedOutGateProps): Promise<ReactElement> {
+  return HubSignInGate({ locale, requestHeaders });
+}
+`;
+}
+/**
+ * The package the spoke mcp seam takes its one type from. Interpolated, not
+ * written inline: an inline specifier in this template would read as an
+ * import create-ailk itself makes (`tools/lint-architecture.ts`), and
+ * create-ailk carries no runtime dependency.
+ */
+const CONTENT_ADAPTERS_PACKAGE = "@working-theory/content-adapters";
+/** `apps/mcp/src/lib/topology.generated.ts` for `topology` (D5). */
+export function renderMcpSeam(topology) {
+    if (topology === "hub") {
+        return `${MCP_SEAM_HEADER}
+import {
+  initMcpPublicWorkspace,
+  mcpPublicWorkspace,
+  type McpWorkspaceResolution,
+} from "./public-workspace.js";
+
+export { registerLicenseKeyStore } from "./license-key-store.js";
+export type { McpWorkspaceResolution };
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+
+export async function initPublicWorkspace(): Promise<void> {
+  await initMcpPublicWorkspace();
+}
+
+export function publicWorkspace(): McpWorkspaceResolution {
+  return mcpPublicWorkspace();
+}
+`;
+    }
+    return `${MCP_SEAM_HEADER}
+import type { ArtifactPrismaClient } from "${CONTENT_ADAPTERS_PACKAGE}";
+
+export type McpWorkspaceResolution =
+  | { kind: "not-required" }
+  | { kind: "resolved"; workspaceId: string; prisma: ArtifactPrismaClient }
+  | { kind: "unresolved"; reason: "ambiguous" };
+
+export const TOPOLOGY: "hub" | "spoke" = "spoke";
+
+export function initPublicWorkspace(): Promise<void> {
+  return Promise.resolve();
+}
+
+export function publicWorkspace(): McpWorkspaceResolution {
+  return { kind: "not-required" };
+}
+
+export function registerLicenseKeyStore(): Promise<void> {
+  return Promise.resolve();
+}
+`;
+}
+const API_ORIGIN_SEAM_HEADER = `// api-origin.generated.ts — the browser-facing API origin this site's server reads.
+//
+// GENERATED by create-ailk for this site's topology (#7874). Do not edit:
+// every scaffold rewrites it. A hub reads NEXT_PUBLIC_AILK_API_URL as a
+// fallback API origin; a spoke (\`--topology spoke\`) has no browser-facing
+// API origin — its hub origin is server-only (AILK_API_URL) — so its render
+// reads no environment variable.`;
+/** `apps/web/lib/api-origin.generated.ts` for `topology` (#7874 D12). */
+export function renderApiOriginSeam(topology) {
+    if (topology === "hub") {
+        return `${API_ORIGIN_SEAM_HEADER}
+
+export function browserApiOrigin(): string | undefined {
+  return process.env.NEXT_PUBLIC_AILK_API_URL;
+}
+`;
+    }
+    return `${API_ORIGIN_SEAM_HEADER}
+
+export function browserApiOrigin(): string | undefined {
+  return undefined;
+}
+`;
+}
+// ── D6 — the root-file transforms ───────────────────────────────────────────
+/**
+ * `text` with every line `drop` matches removed, then the dangling comma a
+ * removed last member leaves fixed. Validated as JSON when `json` is set.
+ */
+function dropLines(text, drop, label, json) {
+    const kept = text.split("\n").filter((line) => !drop(line));
+    const next = kept.join("\n").replace(/,(\s*\n\s*[}\]])/g, "$1");
+    if (json) {
+        try {
+            JSON.parse(next);
+        }
+        catch (err) {
+            throw new TopologyError(`${label}: the spoke transform left it unparseable: ${err.message}`);
+        }
+    }
+    return next;
+}
+/** `pnpm-workspace.yaml` without its `database` package entry. */
+export function transformWorkspaceYaml(text) {
+    const entry = /^\s*-\s*["']?database["']?\s*$/;
+    if (!text.split("\n").some((line) => entry.test(line))) {
+        throw new TopologyError(`pnpm-workspace.yaml: no "database" package entry to remove`);
+    }
+    return dropLines(text, (line) => entry.test(line), "pnpm-workspace.yaml", false);
+}
+/** The root `package.json` without its `db:*` scripts. */
+export function transformRootPackageJson(text) {
+    const pkg = JSON.parse(text);
+    if (pkg.scripts === undefined) {
+        throw new TopologyError(`package.json: no "scripts" block to remove the db:* scripts from`);
+    }
+    const scriptLine = /^\s*"db:[^"]*"\s*:/;
+    return dropLines(text, (line) => scriptLine.test(line), "package.json", true);
+}
+/** The spoke's declared-env script (#7874 D11) — named apart from the monorepo's `env:check`. */
+export const ENV_DECLARED_SCRIPT = "env:declared";
+const ENV_DECLARED_COMMAND = "tsx tools/check-declared-env.ts";
+/**
+ * The spoke's root `package.json` with the declared-env check (#7874 D11):
+ * an `env:declared` script after `claude-md:check`, and `preflight` running
+ * it right after `claude-md:check`. Applied after `transformRootPackageJson`.
+ * @throws TopologyError when either anchor is missing.
+ */
+export function addEnvCheckScripts(text) {
+    const lines = text.split("\n");
+    const anchor = lines.findIndex((line) => /^\s*"claude-md:check"\s*:/.test(line));
+    if (anchor === -1) {
+        throw new TopologyError(`package.json: no "claude-md:check" script to add ${ENV_DECLARED_SCRIPT} after`);
+    }
+    const preflightAt = lines.findIndex((line) => /^\s*"preflight"\s*:/.test(line));
+    const step = "pnpm claude-md:check && ";
+    if (preflightAt === -1 || !(lines[preflightAt] ?? "").includes(step)) {
+        throw new TopologyError(`package.json: no "preflight" script running "${step.trim()}" to add ${ENV_DECLARED_SCRIPT} to`);
+    }
+    lines[preflightAt] = (lines[preflightAt] ?? "").replace(step, `${step}pnpm ${ENV_DECLARED_SCRIPT} && `);
+    const indent = /^\s*/.exec(lines[anchor] ?? "")?.[0] ?? "";
+    lines.splice(anchor + 1, 0, `${indent}${JSON.stringify(ENV_DECLARED_SCRIPT)}: ${JSON.stringify(ENV_DECLARED_COMMAND)},`);
+    const next = lines.join("\n");
+    try {
+        JSON.parse(next);
+    }
+    catch (err) {
+        throw new TopologyError(`package.json: adding ${ENV_DECLARED_SCRIPT} left it unparseable: ${err.message}`);
+    }
+    return next;
+}
+/**
+ * The spoke's `.github/workflows/ci.yml` (#7874 D11): a `pnpm env:declared`
+ * step after `pnpm claude-md:check`, and no `pnpm db:generate` step — a
+ * spoke has no `database/` and no `db:*` script, so that step would fail
+ * first (#7962). The comment block directly above the dropped step goes with
+ * it.
+ * @throws TopologyError when either anchor is missing.
+ */
+export function transformCiWorkflow(text) {
+    const lines = text.split("\n");
+    const dbAt = lines.findIndex((line) => /^\s*- run: pnpm db:generate\s*$/.test(line));
+    if (dbAt === -1) {
+        throw new TopologyError(`.github/workflows/ci.yml: no "- run: pnpm db:generate" step to remove`);
+    }
+    let start = dbAt;
+    while (start > 0 && /^\s*#/.test(lines[start - 1] ?? ""))
+        start--;
+    // Drop the blank line that separated the removed block from the step above.
+    const dropBlank = start > 0 && (lines[start - 1] ?? "").trim() === "" ? 1 : 0;
+    lines.splice(start - dropBlank, dbAt - start + 1 + dropBlank);
+    const anchor = lines.findIndex((line) => /^\s*- run: pnpm claude-md:check\s*$/.test(line));
+    if (anchor === -1) {
+        throw new TopologyError(`.github/workflows/ci.yml: no "- run: pnpm claude-md:check" step to add ${ENV_DECLARED_SCRIPT} after`);
+    }
+    const indent = /^\s*/.exec(lines[anchor] ?? "")?.[0] ?? "";
+    lines.splice(anchor + 1, 0, "", `${indent}# A process.env read with no project.yaml env_contract row — the same check \`pnpm preflight\` runs locally.`, `${indent}- run: pnpm ${ENV_DECLARED_SCRIPT}`);
+    return lines.join("\n");
+}
+/** The root `tsconfig.json` without a reference under a removed root. */
+export function transformRootTsconfig(text, opts) {
+    const roots = spokeRemovedRoots(opts);
+    const refLine = /"path"\s*:\s*"([^"]+)"/;
+    return dropLines(text, (line) => {
+        const m = refLine.exec(line);
+        return (m !== null &&
+            roots.some((root) => underPrefix(toPosix(m[1] ?? ""), root)));
+    }, "tsconfig.json", true);
+}
+/**
+ * An app's `package.json` without its `@working-theory/database` dependency.
+ * @throws TopologyError when `required` and the dependency is absent.
+ */
+export function transformAppPackageJson(text, label, required) {
+    const depLine = /^\s*"@working-theory\/database"\s*:/;
+    if (required && !text.split("\n").some((line) => depLine.test(line))) {
+        throw new TopologyError(`${label}: no "@working-theory/database" dependency to remove`);
+    }
+    return dropLines(text, (line) => depLine.test(line), label, true);
+}
+/**
+ * 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). Also the declared-env check's root
+ * script and CI step (#7874 D11), and the browser API origin seam (D12).
+ * @throws TopologyError naming the file whose anchor is missing.
+ */
+export function applySpokeTransforms(targetDir, opts) {
+    const edit = (rel, transform) => {
+        const path = join(targetDir, rel);
+        if (!existsSync(path)) {
+            throw new TopologyError(`${rel}: missing, so the spoke transform cannot run`);
+        }
+        const text = readFileSync(path, "utf8");
+        const next = transform(text);
+        if (next !== text)
+            writeFileSync(path, next);
+    };
+    edit("pnpm-workspace.yaml", transformWorkspaceYaml);
+    edit("package.json", (text) => addEnvCheckScripts(transformRootPackageJson(text)));
+    edit(".github/workflows/ci.yml", transformCiWorkflow);
+    edit("tsconfig.json", (text) => transformRootTsconfig(text, opts));
+    edit("apps/web/package.json", (text) => transformAppPackageJson(text, "apps/web/package.json", true));
+    if (opts.mcp) {
+        edit("apps/mcp/package.json", (text) => transformAppPackageJson(text, "apps/mcp/package.json", false));
+    }
+    edit("project.yaml", (text) => transformProjectYaml(text, opts));
+    writeFileSync(join(targetDir, WEB_SEAM_PATH), renderWebSeam("spoke", opts.signIn));
+    // #7894 D8 — the gate seam lives in the `(authed)` group only the hub
+    // sign-in mode keeps.
+    if (opts.signIn === "hub") {
+        writeFileSync(join(targetDir, AUTHED_GATE_SEAM_PATH), renderAuthedGateSeam("spoke", "hub"));
+    }
+    writeFileSync(join(targetDir, API_ORIGIN_SEAM_PATH), renderApiOriginSeam("spoke"));
+    if (opts.mcp) {
+        writeFileSync(join(targetDir, MCP_SEAM_PATH), renderMcpSeam("spoke"));
+    }
+}
+/** The env var a spoke reaches its hub through. */
+export const HUB_ORIGIN_ENV_VAR = "AILK_API_URL";
+/** Env files `next start` loads for an app, highest precedence first. */
+const NEXT_ENV_FILES = [
+    ".env.production.local",
+    ".env.local",
+    ".env.production",
+    ".env",
+];
+/**
+ * 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 function writeHubOriginEnv(targetDir, origin) {
+    writeWebEnv(targetDir, HUB_ORIGIN_ENV_VAR, () => origin);
+}
+/**
+ * `<name>=<value()>` into the spoke's `apps/web/.env.local`, unless any env
+ * file Next loads for `apps/web` already assigns `name` (`value` is then never
+ * called); and `.env.local` gitignored either way.
+ */
+function writeWebEnv(targetDir, name, value) {
+    const webDir = join(targetDir, "apps", "web");
+    const assigned = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*\\S`, "m");
+    const already = NEXT_ENV_FILES.some((file) => {
+        const path = join(webDir, file);
+        return existsSync(path) && assigned.test(readFileSync(path, "utf8"));
+    });
+    if (!already) {
+        const file = join(webDir, ".env.local");
+        const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+        writeOwnerOnly(file, appendLine(existing, `${name}=${value()}`));
+    }
+    const ignorePath = join(targetDir, ".gitignore");
+    const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
+    const covered = ignore
+        .split("\n")
+        .some((line) => ENV_LOCAL_IGNORE_LINES.has(line.trim()));
+    if (!covered)
+        writeFileSync(ignorePath, appendLine(ignore, ".env.local"));
+}
+/** The env var naming the hub's web origin a hub-mode spoke signs in at (#7894 D11). */
+export const HUB_SIGN_IN_URL_ENV_VAR = "AILK_HUB_SIGN_IN_URL";
+/** The env var holding a hub-mode spoke's own cookie key material (#7894 D7, D11). */
+export const HUB_SESSION_SECRET_ENV_VAR = "AILK_HUB_SESSION_SECRET";
+/**
+ * Write a hub-mode spoke's sign-in env (#7894 D11) to `apps/web/.env.local`,
+ * under `writeHubOriginEnv`'s never-clobber rule: the hub's web origin, and a
+ * fresh session secret (32 random bytes, 43 base64url characters). Never the
+ * client id or client secret — the hub issues those (`spokes sign-in-client`)
+ * — and never `BETTER_AUTH_SECRET` or a database URL.
+ */
+export function writeHubSignInEnv(targetDir, origin) {
+    writeWebEnv(targetDir, HUB_SIGN_IN_URL_ENV_VAR, () => origin);
+    writeWebEnv(targetDir, HUB_SESSION_SECRET_ENV_VAR, () => randomBytes(32).toString("base64url"));
+}
+// ── D9 — the spoke's hard floors ────────────────────────────────────────────
+/** The `hard_floors:` block a spoke's `project.yaml` carries (D9). */
+export function renderSpokeHardFloors(opts) {
+    const lines = [
+        "hard_floors:",
+        "  # Surfaces that always require human review on merge, regardless of",
+        "  # automation level. This site is a SPOKE (create-ailk --topology spoke):",
+        "  # it has no apps/api, no database and no sign-in of its own. Pricing, the",
+        "  # Stripe webhook route, the checkout route and its price map, and the",
+        "  # sign-in paths are floored so their arrival here is a human merge.",
+        "  - kind: pricing",
+        "  - kind: stripe_live_mode",
+        "  - paths:",
+        '      - "apps/web/app/api/webhooks/stripe/**"',
+        "    reason: Stripe webhook route — payment state requires human review",
+        "  - paths:",
+        '      - "apps/web/app/api/checkout/**"',
+        '      - "apps/web/lib/checkout-config.ts"',
+        "    reason: Spoke checkout — the buy route and the price map require human review",
+        "  - paths:",
+        '      - "apps/web/auth.ts"',
+        '      - "apps/web/app/api/auth/**"',
+        '      - "apps/web/app/[locale]/(auth)/**"',
+        '      - "apps/web/app/[locale]/(authed)/**"',
+        '      - "apps/web/lib/hub-session/**"',
+        '      - "apps/web/app/api/hub-session/**"',
+        opts.signIn === "hub"
+            ? "    reason: sign-in paths — this spoke signs in through its hub; every change requires human review"
+            : "    reason: sign-in paths — absent on a spoke; their return requires human review",
+    ];
+    if (opts.mcp) {
+        lines.push("  - paths:", '      - "apps/mcp/src/tools/**"', "    reason: MCP tool surface — signatures require human review");
+    }
+    return `${lines.join("\n")}\n`;
+}
+/** `project.yaml` with its `hard_floors:` block replaced by the spoke's (D9). */
+export function transformProjectYaml(text, opts) {
+    const lines = text.split("\n");
+    const start = lines.findIndex((line) => line === "hard_floors:");
+    if (start === -1 || lines.indexOf("hard_floors:", start + 1) !== -1) {
+        throw new TopologyError(`project.yaml: no single top-level "hard_floors:" block to replace`);
+    }
+    let end = start + 1;
+    while (end < lines.length && !/^\S/.test(lines[end] ?? ""))
+        end++;
+    // Keep the blank line(s) that separate the block from the next key.
+    while (end > start + 1 && (lines[end - 1] ?? "").trim() === "")
+        end--;
+    const block = renderSpokeHardFloors(opts).replace(/\n$/, "").split("\n");
+    return [...lines.slice(0, start), ...block, ...lines.slice(end)].join("\n");
+}
+// ── D7 — the module admission ───────────────────────────────────────────────
+/** Why a module is not admitted on a spoke, and where its admission lives. */
+export const SPOKE_REFUSAL_REASONS = {
+    "multi-tenant": "it needs a database or the Admin app",
+    workspace: "it needs a database or the Admin app",
+};
+/** The modules a spoke may carry — every slice declaring `spoke: true`. */
+export function spokeModules() {
+    return RECOGNIZED_MODULES.filter((name) => MODULE_SLICES[name].spoke === true);
+}
+/** The refusal for a module a spoke cannot carry, or undefined when admitted. */
+export function spokeModuleRefusal(name) {
+    if (MODULE_SLICES[name].spoke === true)
+        return undefined;
+    const reason = SPOKE_REFUSAL_REASONS[name] ?? "it is not admitted on a spoke";
+    return `module "${name}" cannot be added to a spoke: ${reason}. A spoke carries ${spokeModules().join(", ")}.`;
+}
+// ── D10 — reading a site's topology ─────────────────────────────────────────
+/** The manifest a templated scaffold writes (`site-roster.ts` `SITE_ROSTER_PATH`). */
+const SITE_MANIFEST_PATH = ".ailk-site-manifest.json";
+/**
+ * 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 function readSiteTopology(targetDir) {
+    const path = join(targetDir, SITE_MANIFEST_PATH);
+    if (!existsSync(path))
+        return "hub";
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        throw new TopologyError(`${SITE_MANIFEST_PATH} is not JSON, so this site's topology is unknown: ${err.message}`);
+    }
+    const value = doc["topology"];
+    if (value === undefined)
+        return "hub";
+    if (typeof value === "string" &&
+        TOPOLOGIES.includes(value)) {
+        return value;
+    }
+    throw new TopologyError(`${SITE_MANIFEST_PATH} records an unknown topology ${JSON.stringify(value)} (expected ${TOPOLOGIES.join(" or ")})`);
+}
+/**
+ * The spoke options `<targetDir>` records (#7894 D1), for the later commands
+ * (`sync-routes`, `add-module`): `undefined` on a hub; on a spoke, `mcp` from
+ * whether it still carries `apps/mcp` and `signIn` from the manifest's
+ * `signIn` key — absent reads as `"off"`, every spoke before #7894.
+ * @throws TopologyError on an unreadable manifest or an unknown value.
+ */
+export function readSpokeShape(targetDir) {
+    if (readSiteTopology(targetDir) !== "spoke")
+        return undefined;
+    const doc = JSON.parse(readFileSync(join(targetDir, SITE_MANIFEST_PATH), "utf8"));
+    const value = doc["signIn"];
+    if (value !== undefined && value !== "hub") {
+        throw new TopologyError(`${SITE_MANIFEST_PATH} records an unknown sign-in mode ${JSON.stringify(value)} (expected "hub", or no key)`);
+    }
+    return {
+        mcp: existsSync(join(targetDir, SPOKE_MCP_ROOT)),
+        signIn: value === "hub" ? "hub" : "off",
+    };
+}
+// ── D2 — the hub origin ─────────────────────────────────────────────────────
+/**
+ * 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 const LOOPBACK_HOSTS = ["localhost", "127.0.0.1"];
+/**
+ * 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 function normalizeHubUrl(raw) {
+    const inputs = "Pass --hub-url <origin>, or set AILK_API_URL";
+    if (raw === undefined || raw.trim() === "") {
+        throw new TopologyError(`a spoke needs its hub's origin, and none was given. ${inputs} (e.g. https://hub.example.com).`);
+    }
+    return normalizeOrigin(raw, "the hub origin", inputs);
+}
+/**
+ * The hub's WEB origin a hub-mode spoke signs in at (`--hub-sign-in`, #7894
+ * D1) — `normalizeHubUrl`'s rules, each refusal naming the flag.
+ * @throws TopologyError when `raw` is not such an origin.
+ */
+export function normalizeHubSignInUrl(raw) {
+    return normalizeOrigin(raw, "the --hub-sign-in origin", "Pass --hub-sign-in <origin>");
+}
+/** `raw` normalized to an https (or loopback http) origin; refusals name `what` and `inputs`. */
+function normalizeOrigin(raw, what, inputs) {
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new TopologyError(`${what} is not a URL. ${inputs} to an origin such as https://hub.example.com.`);
+    }
+    const loopback = LOOPBACK_HOSTS.includes(url.hostname);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new TopologyError(`${what} must be https: (http: only on ${LOOPBACK_HOSTS.join(" or ")}), got ${url.protocol}//${url.host}. ${inputs}.`);
+    }
+    if (url.pathname !== "/" || url.search !== "" || url.hash !== "") {
+        throw new TopologyError(`${what} must be an origin only — no path, query or fragment. ${inputs} to ${url.origin}.`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new TopologyError(`${what} must not carry credentials. ${inputs} to ${url.protocol}//${url.host}.`);
+    }
+    return url.origin;
+}