create-ailk 0.14.0 → 0.15.0

package/dist/topology.js

@@ -0,0 +1,533 @@
+/**
+ * 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).
+ *
+ * Spec: docs/specs/7426-spoke-topology-option-spec.md.
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly. The
+ * package's own `templates/` dir is supplied by the caller.
+ */
+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";
+/**
+ * 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 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",
+];
+/** The two generated seam files (D5). 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";
+export const SPOKE_SEAM_FILES = [
+    WEB_SEAM_PATH,
+    MCP_SEAM_PATH,
+];
+/**
+ * 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;
+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. */
+function spokeSeeds(opts) {
+    return SPOKE_REMOVAL_SEEDS.filter((seed) => opts.mcp || !underPrefix(seed, SPOKE_MCP_ROOT));
+}
+/** Whether a closure member is one the registry allows a spoke to drop. */
+export function isRemovableClosureMember(path) {
+    const p = toPosix(path);
+    return (p.split("/").includes("__tests__") ||
+        SPOKE_REMOVABLE_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))
+        .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.some((prefix) => underPrefix(p, prefix));
+}
+// ── 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 sign-in and no database of its own,
+// so its render reads no session and imports nothing.`;
+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 };
+} | null;`;
+/** `apps/web/lib/topology.generated.ts` for `topology` (D5). */
+export function renderWebSeam(topology) {
+    if (topology === "hub") {
+        return `${WEB_SEAM_HEADER}
+import { auth } from "../auth";
+
+export const TOPOLOGY: "hub" | "spoke" = "hub";
+export const SIGN_IN_ENABLED: boolean = true;
+
+${SITE_SESSION_TYPE}
+
+export async function readSession(headers: Headers): Promise<SiteSession> {
+  return auth.api.getSession({ headers });
+}
+
+export async function registerSiteStores(): Promise<void> {
+  const { registerLicenseKeyStore } = await import("./license-key-store");
+  await registerLicenseKeyStore();
+}
+`;
+    }
+    return `${WEB_SEAM_HEADER}
+
+export const TOPOLOGY: "hub" | "spoke" = "spoke";
+export const SIGN_IN_ENABLED: boolean = false;
+
+${SITE_SESSION_TYPE}
+
+export function readSession(headers: Headers): Promise<SiteSession> {
+  void headers;
+  return Promise.resolve(null);
+}
+
+export function registerSiteStores(): Promise<void> {
+  return Promise.resolve();
+}
+`;
+}
+/**
+ * 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();
+}
+`;
+}
+// ── 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 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).
+ * @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", transformRootPackageJson);
+    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"));
+    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) {
+    const webDir = join(targetDir, "apps", "web");
+    const assigned = new RegExp(`^\\s*(?:export\\s+)?${HUB_ORIGIN_ENV_VAR}\\s*=\\s*\\S`, "m");
+    const already = NEXT_ENV_FILES.some((name) => {
+        const path = join(webDir, name);
+        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, `${HUB_ORIGIN_ENV_VAR}=${origin}`));
+    }
+    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"));
+}
+// ── 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 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/auth.ts"',
+        '      - "apps/web/app/api/auth/**"',
+        '      - "apps/web/app/[locale]/(auth)/**"',
+        '      - "apps/web/app/[locale]/(authed)/**"',
+        "    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. */
+const SPOKE_REFUSAL_REASONS = {
+    scheduling: "its spoke admission lands with #7872",
+    commerce: "its spoke admission lands with #7838",
+    "multi-tenant": "it needs a database or the Admin app",
+    workspace: "it needs a database or the Admin app",
+    "signal-collectors": "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 ")})`);
+}
+// ── 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).`);
+    }
+    let url;
+    try {
+        url = new URL(raw.trim());
+    }
+    catch {
+        throw new TopologyError(`the hub origin 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(`the hub origin 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(`the hub origin must be an origin only — no path, query or fragment. ${inputs} to ${url.origin}.`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new TopologyError(`the hub origin must not carry credentials. ${inputs} to ${url.protocol}//${url.host}.`);
+    }
+    return url.origin;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,8 +27,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.36.0",
-    "@working-theory/templates": "0.36.0"
+    "@working-theory/schema": "0.37.0",
+    "@working-theory/templates": "0.37.0"
   },
   "repository": {
     "type": "git",

package/site-templates/designs/minimalism/DESIGN.md

@@ -325,7 +325,7 @@ Copy density: sparse — minimalism pages carry far fewer words than a standard
 
 <!-- generated:end -->
 
-Square corners everywhere (`theme.corners: square`) — buttons, cards, the auth card, image placeholders; the tokens above are the base foundation's defaults a site overrides.
+Square corners everywhere (`theme.corners: square`) — cards, the auth card, image placeholders; the tokens above are the base foundation's defaults a site overrides.
 
 ## Components
 
@@ -354,7 +354,7 @@ Mark-only: no link row. On the deck home the header is bare: no bar, no rule and
 
 ### Footer
 
-On the deck home the footer is the deck's closing slide (#7742): one viewport tall with its content centred, the wordmark (an image wordmark at the display size), at most two contact lines and one muted legal line (copyright, Privacy, Terms, Cookie settings, FAQ), and an up-chevron button at its foot that returns to the first slide. No nav links, social icons, theme switch, language switcher or Sign in / Sign up. Every other page ends in one bar: the copyright, the legal links and Sign in / Sign up (the Account link when signed in). The cookie banner sits on the page ground with a hairline above it and no shadow, and the deck's chevron rises above it while it shows.
+On the deck home the footer is the deck's closing slide (#7742): one viewport tall with its content centred, the wordmark (an image wordmark at the display size), at most two contact lines and one muted legal line (copyright, Privacy, Terms, Cookie settings, FAQ), up to two actions (the first a button, the second a text link: the closing slide's exception to the home-slide one-button rule, capped there; a third is not shown), and an up-chevron button at its foot that returns to the first slide. No nav links, social icons, theme switch, language switcher or Sign in / Sign up. Every other page ends in one bar: the copyright, the legal links and Sign in / Sign up (the Account link when signed in). The cookie banner sits on the page ground with a hairline above it and no shadow; its Accept is a text link beside the Decline, not a button, so the one-button rule holds. On the deck home it waits for the first slide to leave view (slide 1 is a clean landing) and first shows on slide 2, where the deck's chevron rises above it; on every other page it shows on load.
 
 ### Index and profile pages
 
@@ -366,7 +366,7 @@ The foundation's pinned direction is the pacing of a classic wireframe marketing
 
 | Trait                                                  | How it is set                                                                                     |
 | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
-| Square corners on buttons, cards and inputs            | `theme.corners: square` in `_site.mdx`                                                            |
+| Square corners on cards and inputs                     | `theme.corners: square` in `_site.mdx`                                                            |
 | Section label in sentence case, no tracking            | `theme.eyebrowCase: sentence`                                                                     |
 | Solid grey image placeholders, no outline              | `theme.placeholders: fill`                                                                        |
 | Bare check and cross marks, no circle badge            | `theme.checkmarks: plain`                                                                         |

package/templates/apps/api/CLAUDE.md

@@ -55,7 +55,7 @@ Routes are versioned under `/v1/*`:
 - `/v1/workspaces/:workspaceId/submissions` (GET, `?limit=&state=unhandled&magnetId=`), `/v1/workspaces/:workspaceId/submissions/:leadId` (GET, PATCH) — the Inbox submissions API (#7535, `src/routes/workspaces/submissions.ts` over `src/services/inbox-submissions.ts`): every flow completion and waitlist signup of the caller's active workspace, newest first and bounded (`?limit=` 1–200, default 50), the item read (handled or not), and the one-way idempotent handled stamp (`{ "handled": true }` only, `.strict()`; a second PATCH returns the first `handledAt`). Same registration, scope and tenant guard as the messages bullet above. A submission is a `Lead` whose `source` is a fixed submission source (`SUBMISSION_FIXED_SOURCE_LIST` in `@working-theory/validation`) or `flow:<slug>` for a NON-newsletter magnet of THIS workspace — decided only in `tenantDb(tenant).leads`, never in the route; a `flow:` row naming no magnet of the workspace never lists. The list row is seven keys — the message row's six plus `magnet: { slug, title } | null` — and never `payload`. `?magnetId=` narrows to one magnet (limit 1–50) and adds `answers`, `answersTruncated` and `deliverableSentAt` per row; the item read serves the same three. `answers` is `payload` narrowed by `toAnswers`: server-owned keys dropped, control and bidi characters stripped, every key, value and the entry count bounded. `?state=unhandled` filters `handledAt IS NULL` in the query (the Admin's For-you read); any other `state` is a 400. Every miss on the item read and the PATCH — a malformed, absent or foreign id, a message, an application, a newsletter-magnet lead — is the SAME `404 No such submission`; a `?magnetId=` that is absent, foreign or a newsletter magnet is `404 No such magnet`. Every success body is re-parsed against its own `.strict()` schema before it is sent. Role floor: `inbox-read` on the GETs and `inbox-act` on PATCH (`@working-theory/validation`'s permission table (#7636 D2) — every role, a member included), checked before any read or write. The handlers and the service never log a lead id, email, name or answer. No anonymous MCP twin — identity-bound tenant routes. Each route's twin is a signed-in tool on `/mcp/workspace` (#3591 D13): `list_inbox_submissions` (list), `get_inbox_submission` (item read) and `mark_inbox_submission_done` (PATCH).
 - `/v1/workspaces/:workspaceId/subscribers` (GET, `?limit=`) — the workspace's newsletter signups, read-only (#7535, `src/routes/workspaces/subscribers.ts`): `{ count, items }`, where `count` is every signup and `items` the newest (1–200, default 50), each `{ id, email, source, subscribedAt, magnet: { slug, title } | null }`. A signup is a `Subscriber` row of this workspace or the `Lead` a newsletter-kind magnet of this workspace wrote, both from `tenantDb(tenant).subscribers`, called directly. No item route and no write: a subscriber is never an item to open or mark handled. Same registration, scope, tenant guard and `inbox-read` floor as the submissions bullet above. No MCP twin — identity-bound tenant route (#3591 exception).
 - `/v1/workspaces/:workspaceId/members` (GET) — the org's member roster (`userId`, `name`, `email`, `role`), the Pro `workspace` module's Team tab (#5371). Read-only by design: granting a Membership is the invite flow, which is its own spec with a mandatory security review (§2.3), so no POST/PUT/DELETE is routed at this path. Scoped to `request.tenant.organizationId` — Membership is org-level — server-resolved from the validated session. Role floor: `members-read` (owner, admin — `@working-theory/validation`'s permission table (#7636 D2)): the roster carries every member's email, and who the other members are is not a member's job. No MCP twin — identity-bound tenant route (#3591 exception).
-- `/v1/workspaces/:workspaceId/agents` (GET `?userId=`, POST), `/v1/workspaces/:workspaceId/agents/:agentId/key` (POST), `/v1/workspaces/:workspaceId/agents/:agentId` (PATCH `{ enabled }`), and `/v1/agent/context` (GET) — the agent seat (#3591, `src/routes/workspaces/agents.ts` over `src/lib/agent-store.ts`, `// oss: false`). An agent is a stored delegate of one person, bound to one workspace. The four management routes refuse an agent caller outright (403), check `agents-manage` (owner, admin) before any read, and scope every read and write to `tenant.organizationId`, never a body or query value; an agent of another organization is the same 404 as a missing one. Create returns 201 with the key shown once; re-key returns the new key once. Each successful create, re-key and switch writes an `agents.*` audit record. `/v1/agent/context` is the agent's own read and needs no permission beyond the workspace guard. Same registration scope as the routes above (`workspace || multi-tenant`).
+- `/v1/workspaces/:workspaceId/agents` (GET `?userId=`, POST), `/v1/workspaces/:workspaceId/agents/:agentId/key` (POST), `/v1/workspaces/:workspaceId/agents/:agentId` (PATCH `{ enabled }`), `PUT /v1/workspaces/:workspaceId/agents/:agentId/grants` (`{ grants }`, #7864), and `/v1/agent/context` (GET) — the agent seat (#3591, `src/routes/workspaces/agents.ts` over `src/lib/agent-store.ts`, `// oss: false`). An agent is a stored delegate of one person, bound to one workspace. The five management routes refuse an agent caller outright (403), check `agents-manage` (owner, admin) before any read, and scope every read and write to `tenant.organizationId`, never a body or query value; an agent of another organization is the same 404 as a missing one. Create returns 201 with the key shown once; re-key returns the new key once. Each successful create, re-key, switch and grant change writes an `agents.*` audit record. **Grants (#7864, `docs/specs/7864-agent-key-grants-spec.md`).** An agent acts at `member`, plus any of five permissions an owner or admin granted it one by one — `content-edit`, `content-publish`, `assets-write`, `magnets-manage`, `meeting-types-manage` (`@working-theory/validation`'s `AGENT_GRANTABLE_PERMISSIONS`, held to that set by the `agents_grants_allowed` CHECK). The grant PUT replaces the whole set (an empty list removes every grant) and refuses a grant the agent's person's own role does not hold, `409 grant_exceeds_person`. The clamp is one function both tenant guards call (`services/default-tenant.ts`'s `agentTenant`): an agent holds a stored grant only while its person's role holds it, so a demoted person's agent keeps the row but not the permission. The routes for the five check `allows(tenant, "<permission>")`, which reads the grants; every other check keeps `can(tenant.role, …)`, so no other owner or admin permission is reachable. Every agent write on content, assets and meeting types writes one `recordAgentWrite` row naming the agent and its person (magnets already did); a person's writes there stay unaudited. No grant raises the ceiling. `/v1/agent/context` is the agent's own read, unchanged by grants, and needs no permission beyond the workspace guard. Same registration scope as the routes above (`workspace || multi-tenant`).
 - `/v1/workspaces/:workspaceId/content` (GET, POST), `/v1/workspaces/:workspaceId/content/:type/:slug` (GET, PATCH), `/v1/workspaces/:workspaceId/content/:type/:slug/{publish,unpublish}` (POST) — the tenant-guarded content editor's write surface (#5853, `src/routes/workspaces/content.ts`): list, create, read/save the draft tip (under `If-Match`), and publish/unpublish, all over `Artifact`/`ArtifactVersion`. `:type` is validated against the page-type registry (`z.enum(SCHEMA_ORG_TYPES)`) rather than accepted as a free string on every addressed operation — an unregistered type is a 400 before any lookup, since it is echoed back and passed to `notifyRevalidate` as the site's cache tag. Role floors from `@working-theory/validation`'s permission table (#7636 D2): publish and unpublish need `content-publish`, and create, read and save need `content-edit` (both owner, admin — an admin builds, a member operates). The list serves `content-edit` the editor's full view and a caller holding only `docs-read` (a member) a published-only projection (D4): draft rows dropped, every row `status: "published"`, `version: null`, `valid: true`, and a `published_with_draft` page's `type`/`tags` read from its PUBLISHED version — applied before every filter, so a member's `?status=draft` or a draft tip's `?tag=` matches nothing. **The GET list is a UNION of page artifacts and DOCUMENT assets** (#6093, D1/D9 — "one store, two views"): every row carries `tags: string[]` (never null, read from the draft tip's stored content for a page, from `Asset.tags` for a file) and a DERIVED `kind: "page" | "post" | "file"` (`BlogPosting` alone maps to `"post"`; an asset row is always `"file"`) — an optional `?tag=<slug>` filters the union AFTER it is built, so a file is returned under either its own tag or a shared one. The asset half of the union (`DOCUMENT_CONTENT_TYPES`, i.e. `application/pdf`) is skipped entirely when `locale`/`type` is supplied or `status` names anything but `"published"`, since a file row can never satisfy those. A foreign `:workspaceId` costs zero artifact **and** zero asset queries. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as the sibling `/v1/workspaces/*` routes).
 - `/v1/workspaces/:workspaceId/assets` (GET, POST), `/v1/workspaces/:workspaceId/assets/:assetId` (PATCH, DELETE), `/v1/assets/:assetId` (GET, public/anonymous) — the workspace asset store (#5854 upload/read; #6093 list/PATCH/DELETE, `src/routes/assets/{index,upload,read,manage}.ts`). Upload accepts an allowlisted union of three named classes (`src/routes/assets/index.ts`): five RASTER images (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`), one VECTOR image (`image/svg+xml`, admitted under the operator's 2026-09-18 `allow-svg-assets` ruling — issue #6093 comment `5731573595` — superseding #5854's original SVG exclusion) and one DOCUMENT type (`application/pdf`), all under the existing 20 MB cap; `?tags=<slug>[,<slug>…]` stores tags on the row. The public read serves a RASTER type `inline` exactly as before; every OTHER admitted type (SVG, PDF) is served `attachment`, with the filename's extension pinned to the stored content type (closing extension spoofing) and a five-directive `Content-Security-Policy` (`default-src 'none'; sandbox; frame-ancestors 'none'; form-action 'none'; base-uri 'none'`) that makes the bytes never a document on this origin — this is what makes admitting SVG safe with NO server-side sanitizer. `GET …/assets` (`assets-read` — every role, a member included) lists a workspace's assets, metadata only, never `bytes`, with an optional `?tag=<slug>` filter; this is what narrows the store's prior "nothing lists assets" premise to its precise form — no ANONYMOUS and no CROSS-TENANT enumeration, both still true. `PATCH …/assets/:assetId` updates `title`/`description`/`tags` (`assets-write`, owner and admin, the upload's permission too; `null` clears a text field to SQL `NULL`, `""` stores empty; the asset's `id` and public URL are untouched). `DELETE …/assets/:assetId` (`assets-write`) removes the row and the bytes at the ORIGIN only — already-cached copies elsewhere are not recallable under the year-long `immutable` promise, and no reference check protects a page that still embeds the URL; absent and foreign ids both take the same 404. Every tenant route here is identity-bound; no MCP twin (#3591 exception). The public read has no MCP twin either — it serves bytes to an `<img>`/download, the same boundary `upload.ts` records for its own sibling.
 - `/v1/billing` (GET), `/v1/billing/portal-session` (POST) — org-scoped billing read + Stripe customer-portal session creation. The read stays open to every member (the Admin's plan gate reads it); the portal needs `billing-manage` — the owner alone (`@working-theory/validation`'s permission table (#7636 D2); an admin is refused before any Stripe call). `/v1/billing/usage` (GET) needs `billing-read` (owner, admin).
@@ -162,7 +162,9 @@ sweep's own DB constraint (never a caller-side lock).
 - Don't put session state in `apps/api`. It's stateless.
 - Don't bundle `apps/api` (esbuild, rollup, webpack). Slice specifiers cannot survive it — see `## Deploy path`.
 
-Last updated: 2026-10-05 — doc-sync: added the agent seat routes (#3591, #7678) to Endpoint conventions — verified against `apps/api/src/routes/workspaces/agents.ts`.
+Last updated: 2026-10-08 — agent key grants (#7864): the agent-seat bullet names `PUT /v1/workspaces/:workspaceId/agents/:agentId/grants`, the five grantable permissions and the person clamp — verified against `apps/api/src/routes/workspaces/agents.ts`, `apps/api/src/services/default-tenant.ts` and `packages/validation/src/schemas/permissions.ts`.
+
+Prior: 2026-10-05 — doc-sync: added the agent seat routes (#3591, #7678) to Endpoint conventions — verified against `apps/api/src/routes/workspaces/agents.ts`.
 
 Prior: 2026-10-04 — doc-sync: the agent seat, step E (#7684) — the messages and submissions bullets now name each route's signed-in MCP twin on `/mcp/workspace` (#3591 D13) in place of the retired no-twin exception — verified against `apps/api/src/routes/workspaces/{messages,submissions}.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/api/package.json

@@ -15,6 +15,7 @@
     "deliverable:resend": "tsx src/bin/deliverable-resend.ts",
     "seed:presets": "tsx src/bin/seed-presets.ts",
     "spokes": "tsx src/bin/spokes.ts",
+    "flows:copy": "tsx src/bin/flows-copy.ts",
     "build": "tsc",
     "build:vercel": "cd ../../database && pnpm exec prisma generate && cd ../.. && pnpm --filter @working-theory/validation build && pnpm --filter @working-theory/api build && mkdir -p apps/api/public && echo '{}' > apps/api/public/.vercel",
     "start": "node dist/cli.js",