create-ailk 0.22.0 → 0.24.0

package/dist/add-route.js

@@ -24,11 +24,16 @@
  * this. A route the site already declares is a no-op: a second run changes
  * nothing, even where the site has since deleted a seed.
  *
+ * `create-ailk add-route magnet --path <path> --flow <slug>` (#8840 D12) is
+ * the second mode: it writes a site's own magnet page pair at `<path>` and
+ * `<path>/start`, bound to one flow slug, over the standard renderers in
+ * `flows/[slug]/magnet-page.tsx` — see `addMagnetToScaffold`.
+ *
  * Pure module: no `import.meta.url`, so jest can import it directly — the
  * package-rooted inputs are supplied by the CLI, the `add-module.ts` split.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { AddModuleRefusedError, readArchitectureHeader, syncNavConfig, } from "./add-module.js";
 import { isTextFile } from "./copy.js";
@@ -57,16 +62,7 @@ export class AddRouteRefusedError extends Error {
  */
 export function addRouteToScaffold(opts) {
     const targetAbs = resolve(opts.targetDir);
-    if (!existsSync(targetAbs)) {
-        throw new Error(`add-route target does not exist: ${targetAbs}. Point add-route at an already-scaffolded repo.`);
-    }
-    if (!statSync(targetAbs).isDirectory()) {
-        throw new Error(`add-route target is not a directory: ${targetAbs}`);
-    }
-    const archPath = join(targetAbs, "architecture.yaml");
-    if (!existsSync(archPath)) {
-        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
-    }
+    const archPath = scaffoldArchitecturePath(targetAbs);
     // #7426 D13 — a spoke stays a spoke. Read before the first write: an
     // unreadable manifest is a refusal this command names (exit 2).
     let spoke;
@@ -134,6 +130,20 @@ export function addRouteToScaffold(opts) {
     }
     return { targetDir: targetAbs, route, surfaces, report, routes };
 }
+/** The site's `architecture.yaml`, after checking `targetAbs` is a scaffold. */
+function scaffoldArchitecturePath(targetAbs) {
+    if (!existsSync(targetAbs)) {
+        throw new Error(`add-route target does not exist: ${targetAbs}. Point add-route at an already-scaffolded repo.`);
+    }
+    if (!statSync(targetAbs).isDirectory()) {
+        throw new Error(`add-route target is not a directory: ${targetAbs}`);
+    }
+    const archPath = join(targetAbs, "architecture.yaml");
+    if (!existsSync(archPath)) {
+        throw new Error(`not a scaffolded repo: no architecture.yaml at ${targetAbs}. Run \`create-ailk <target-dir>\` to scaffold first.`);
+    }
+    return archPath;
+}
 /** The canonical id for one route argument, refusing an unknown one. */
 function canonicalRoute(raw) {
     let parsed;
@@ -216,13 +226,16 @@ export function formatAddRouteReport(result) {
     const skipped = result.report.filter((row) => row.action === "skipped");
     const routes = result.routes ?? {
         applied: [],
+        refused: [],
         appliedDependencies: [],
         missingMessageNamespaces: [],
     };
     const lines = [
         `[create-ailk] add-route ${result.route} → ${result.targetDir}`,
     ];
-    if (result.report.length === 0 && routes.applied.length === 0) {
+    if (result.report.length === 0 &&
+        routes.applied.length === 0 &&
+        routes.refused.length === 0) {
         lines.push(`Nothing to add — the site already carries the ${result.route} route.`);
     }
     if (routes.applied.length > 0) {
@@ -233,6 +246,9 @@ export function formatAddRouteReport(result) {
         lines.push(`Also copied ${routes.appliedDependencies.length} file(s) those routes import:`);
         lines.push(...routes.appliedDependencies.map((dep) => `  ${dep}`));
     }
+    if (routes.refused.length > 0) {
+        lines.push(`Routes not copied (${routes.refused.length}) — an import does not resolve (run create-ailk sync-routes for the paths): ${routes.refused.join(", ")}`);
+    }
     if (written.length > 0) {
         lines.push(`Written (${written.length}):`);
         lines.push(...written.map((row) => `  ${row.path}`));
@@ -255,10 +271,251 @@ export function formatAddRouteReport(result) {
     }
     return lines.join("\n") + "\n";
 }
+// ── add-route magnet (#8840 D12) ───────────────────────────────────────────
+/** The route word that selects the magnet mode. */
+export const MAGNET_ROUTE = "magnet";
+/**
+ * The header-comment marker every standard magnet page carries — the same
+ * string `flows/[slug]/magnet-page.tsx` exports, which the site's
+ * `structured-data.test.tsx` reads to exempt the pair (#8840 D13).
+ */
+export const MAGNET_PAGE_MARKER = "Standard magnet page (#8840)";
+/** The module whose renderers and flow routes a magnet pair mounts. */
+const MAGNET_MODULE = "signal-collectors";
+/**
+ * `flowSlugSchema`'s rule (`@working-theory/validation`), restated because
+ * create-ailk has no runtime dependency; `add-route-magnet.test.ts` pins the
+ * two equal over a fixed table.
+ */
+const FLOW_SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const FLOW_SLUG_MAX = 59;
+/** One to three kebab-case segments, nothing else (SEC-8840-J). */
+const MAGNET_PATH_RE = /^\/[a-z0-9]+(-[a-z0-9]+)*(\/[a-z0-9]+(-[a-z0-9]+)*){0,2}$/;
+/** A walk's own last segments: `<path>/start` is the pair's, `apply` the careers walks'. */
+const RESERVED_LAST_SEGMENTS = new Set(["start", "apply"]);
+/**
+ * First segments a pair may not take: the API and relay prefixes, the flows
+ * routes, the account and Admin areas, and `apps/web/lib/auth-routes.ts`'s
+ * `AUTH_SEGMENTS` (restated — create-ailk cannot import `apps/web`).
+ */
+const RESERVED_FIRST_SEGMENTS = new Set([
+    "api",
+    "v1",
+    "flows",
+    "account",
+    "admin",
+    "sign-in",
+    "sign-up",
+    "forgot-password",
+    "reset-password",
+    "verify-email",
+]);
+/** A first segment next-intl would read as a locale prefix. */
+const LOCALE_SHAPED_RE = /^[a-z]{2}(-[a-z]{2})?$/;
+/** Template-relative root every page directory sits under. */
+const WEB_ROUTE_ROOT = "apps/web/app/[locale]";
+/** Whether `slug` passes `flowSlugSchema`'s rule. */
+export function isMagnetFlowSlug(slug) {
+    return slug.length <= FLOW_SLUG_MAX && FLOW_SLUG_RE.test(slug);
+}
+/**
+ * Write a magnet page pair — `apps/web/app/[locale]/<path>/page.tsx` (the
+ * landing) and `<path>/start/page.tsx` (the walk) — bound to one flow slug.
+ * Each page is a few lines over the factories in `flows/[slug]/magnet-page`;
+ * the copy, consent and ending come from the flow's record.
+ *
+ * Every refusal throws `AddRouteRefusedError` before the first write. A page
+ * that already exists is never overwritten: a second run reports both
+ * `skipped`. No `architecture.yaml`, nav or seed changes — the pair is the
+ * site's own, with no `ROUTE_SINCE` key or routes-map row (D13).
+ */
+export function addMagnetToScaffold(opts) {
+    const targetAbs = resolve(opts.targetDir);
+    const archPath = scaffoldArchitecturePath(targetAbs);
+    let modules;
+    try {
+        modules = readArchitectureHeader(readFileSync(archPath, "utf8")).modules;
+    }
+    catch (err) {
+        if (err instanceof AddModuleRefusedError) {
+            throw new AddRouteRefusedError(err.message);
+        }
+        throw err;
+    }
+    if (!modules.includes(MAGNET_MODULE)) {
+        throw new AddRouteRefusedError(`a magnet page mounts the "${MAGNET_MODULE}" module's flow stepper, which this site does not carry — add it with \`create-ailk add-module ${MAGNET_MODULE}\``);
+    }
+    if (!isMagnetFlowSlug(opts.flow)) {
+        throw new AddRouteRefusedError(`--flow "${opts.flow}" is not a flow slug: kebab-case (lowercase letters, digits and single hyphens), at most ${FLOW_SLUG_MAX} characters`);
+    }
+    const segments = magnetPathSegments(opts.path);
+    if (segments.length === 1) {
+        const shadowed = shadowedLandingPage(targetAbs, segments[0]);
+        if (shadowed !== undefined) {
+            throw new AddRouteRefusedError(`--path ${opts.path} would shadow the site's own page ${shadowed} — pick another path`);
+        }
+    }
+    const routeDir = segments.join("/");
+    const landing = `${WEB_ROUTE_ROOT}/${routeDir}/page.tsx`;
+    const walk = `${WEB_ROUTE_ROOT}/${routeDir}/start/page.tsx`;
+    const served = staticPageServing(targetAbs, [routeDir, `${routeDir}/start`], {
+        ownPages: [landing, walk],
+    });
+    if (served !== undefined) {
+        throw new AddRouteRefusedError(`--path ${opts.path} is already served by ${served} — pick another path`);
+    }
+    const pages = [
+        [
+            landing,
+            renderMagnetPage("landing", opts.path, opts.flow, segments.length),
+        ],
+        [walk, renderMagnetPage("walk", opts.path, opts.flow, segments.length + 1)],
+    ];
+    const report = [];
+    for (const [path, text] of pages) {
+        const dest = join(targetAbs, path);
+        if (existsSync(dest)) {
+            report.push({ path, action: "skipped" });
+            continue;
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, text);
+        report.push({ path, action: "written" });
+    }
+    return { targetDir: targetAbs, path: opts.path, flow: opts.flow, report };
+}
+/** `--path`'s segments, refusing a path a pair may not take (SEC-8840-J). */
+function magnetPathSegments(path) {
+    if (!MAGNET_PATH_RE.test(path)) {
+        throw new AddRouteRefusedError(`--path "${path}" is not a magnet path: one to three kebab-case segments after a leading slash, e.g. /diagnostic or /careers/writer`);
+    }
+    const segments = path.slice(1).split("/");
+    const first = segments[0];
+    const last = segments[segments.length - 1];
+    if (RESERVED_LAST_SEGMENTS.has(last)) {
+        throw new AddRouteRefusedError(`--path ${path} ends in "${last}", which a walk route uses — the pair's walk is written at <path>/start`);
+    }
+    if (RESERVED_FIRST_SEGMENTS.has(first) || LOCALE_SHAPED_RE.test(first)) {
+        throw new AddRouteRefusedError(`--path ${path} starts with "${first}", a segment the site reserves (the API, flows, account, Admin and sign-in routes, and locale prefixes)`);
+    }
+    return segments;
+}
+/**
+ * The site's `content/<locale>/LandingPage/<segment>.mdx`, in any locale,
+ * that a one-segment pair would shadow (the generic `[slug]` route serves it).
+ */
+function shadowedLandingPage(targetAbs, segment) {
+    const contentRoot = join(targetAbs, "content");
+    if (!existsSync(contentRoot))
+        return undefined;
+    for (const entry of readdirSync(contentRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const rel = `content/${entry.name}/LandingPage/${segment}.mdx`;
+        if (existsSync(join(targetAbs, rel)))
+            return rel;
+    }
+    return undefined;
+}
+/**
+ * The first `page.tsx` under the site's `[locale]` tree whose directory, with
+ * route-group segments removed, is one of `dirs` — a path the site already
+ * serves statically. A dynamic segment never matches (`careers/[slug]` does
+ * not serve `careers/writer` once a static `careers/writer` exists), and the
+ * pair's own two files are skipped, so a rerun reaches the no-overwrite rule.
+ */
+function staticPageServing(targetAbs, dirs, { ownPages }) {
+    const root = join(targetAbs, WEB_ROUTE_ROOT);
+    const wanted = new Set(dirs);
+    const own = new Set(ownPages);
+    const walk = (abs) => {
+        if (!existsSync(abs))
+            return undefined;
+        const entries = readdirSync(abs, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            const full = join(abs, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "__tests__" || entry.name === "node_modules")
+                    continue;
+                const hit = walk(full);
+                if (hit !== undefined)
+                    return hit;
+                continue;
+            }
+            if (!entry.isFile() || entry.name !== "page.tsx")
+                continue;
+            const rel = relative(targetAbs, full).split(sep).join("/");
+            if (own.has(rel) &&
+                readFileSync(full, "utf8").includes(MAGNET_PAGE_MARKER)) {
+                continue;
+            }
+            const dir = relative(root, abs)
+                .split(sep)
+                .filter((segment) => segment !== "" && !/^\(.*\)$/.test(segment))
+                .join("/");
+            if (wanted.has(dir))
+                return rel;
+        }
+        return undefined;
+    };
+    return walk(root);
+}
+/**
+ * One page of the pair. `depth` is the page directory's segment count under
+ * `[locale]`, so the import climbs back to `flows/[slug]/magnet-page`. Every
+ * interpolated value has passed `MAGNET_PATH_RE` or `FLOW_SLUG_RE`, so none
+ * can leave its string literal (SEC-8840-V5).
+ */
+function renderMagnetPage(kind, path, flow, depth) {
+    const [page, metadata, role] = kind === "landing"
+        ? [
+            "magnetLanding",
+            "magnetLandingMetadata",
+            `the landing of the ${path} magnet pair, its copy from the ${flow} flow's record`,
+        ]
+        : [
+            "magnetStart",
+            "magnetStartMetadata",
+            `the walk of the ${path} magnet pair, its back arrow to ${path}`,
+        ];
+    return [
+        `// Generated by \`create-ailk add-route magnet --path ${path} --flow ${flow}\`.`,
+        `// ${MAGNET_PAGE_MARKER} — ${role}.`,
+        `import { ${page}, ${metadata} } from "${"../".repeat(depth)}flows/[slug]/magnet-page";`,
+        "",
+        `const MAGNET = { slug: "${flow}", path: "${path}" } as const;`,
+        "",
+        'export const dynamic = "force-dynamic";',
+        `export const generateMetadata = ${metadata}(MAGNET);`,
+        `export default ${page}(MAGNET);`,
+        "",
+    ].join("\n");
+}
+/** The report `add-route magnet` prints. */
+export function formatAddMagnetReport(result) {
+    const written = result.report.filter((row) => row.action === "written");
+    const skipped = result.report.filter((row) => row.action === "skipped");
+    const lines = [
+        `[create-ailk] add-route magnet ${result.path} (flow ${result.flow}) → ${result.targetDir}`,
+    ];
+    if (written.length > 0) {
+        lines.push(`Written (${written.length}):`);
+        lines.push(...written.map((row) => `  ${row.path}`));
+    }
+    if (skipped.length > 0) {
+        lines.push(`Skipped (${skipped.length}) — the site already has this page, left untouched:`);
+        lines.push(...skipped.map((row) => `  ${row.path}`));
+    }
+    if (written.length > 0) {
+        lines.push(`Next: pnpm build, then open ${result.path}. The page's copy comes from the ${result.flow} flow's record.`);
+    }
+    return lines.join("\n") + "\n";
+}
 export const ADD_ROUTE_HELP = `create-ailk add-route — add a route family to an existing site.
 
 Usage:
   create-ailk add-route <route> [<target-dir>]
+  create-ailk add-route magnet --path <path> --flow <slug> [<target-dir>]
 
 Arguments:
   <route>                  One route family, named as --surfaces names it,
@@ -267,6 +524,9 @@ Arguments:
                            architecture.yaml). Defaults to the current dir.
 
 Options:
+  --path <path>            magnet only: the site path the landing serves,
+                           one to three kebab-case segments, e.g. /diagnostic.
+  --flow <slug>            magnet only: the flow slug the pages are bound to.
   --help, -h               Print this message.
 
 Copies the route's pages, writes its seed content, declares it in
@@ -278,11 +538,25 @@ Like add-module, it also restores any other page route the site carries but
 lacks. A route a module delivers (blog and docs come with docs-blog) is
 refused; add that module with create-ailk add-module. Running it again changes
 nothing.
+
+add-route magnet writes a magnet page pair bound to one flow: a landing at
+apps/web/app/[locale]/<path>/page.tsx and a full-screen walk at
+<path>/start/page.tsx, each a few lines over the standard magnet pages, so the
+copy, consent and ending come from the flow's record. It needs the
+signal-collectors module, and refuses (nothing written) a path the site already
+serves, a one-segment path a LandingPage seed of the same slug owns, a path
+ending in start or apply, a reserved first segment (api, v1, flows, account,
+admin, the sign-in routes, a locale) and a slug the flow API would refuse. A
+page that exists is never overwritten: running it again skips both. It changes
+no architecture.yaml, nav or seed.
 `;
 /**
  * Parse the argv AFTER the `add-route` word. Strict `node:util` parseArgs,
  * like `parseAddModuleArgs`; the route itself is validated by
  * `addRouteToScaffold`, which refuses an unknown one naming the recognized.
+ * `--path` and `--flow` belong to the `magnet` route word alone (#8840 D12):
+ * with any other route they are refused (`AddRouteRefusedError`, exit 2),
+ * and `magnet` needs both. Their values are checked by `addMagnetToScaffold`.
  */
 export function parseAddRouteArgs(argv) {
     const parsed = parseArgs({
@@ -291,9 +565,12 @@ export function parseAddRouteArgs(argv) {
         allowPositionals: true,
         options: {
             help: { type: "boolean", default: false, short: "h" },
+            path: { type: "string" },
+            flow: { type: "string" },
         },
     });
     const help = parsed.values.help === true;
+    const { path, flow } = parsed.values;
     const [route, target, ...rest] = parsed.positionals;
     if (rest.length > 0) {
         throw new ParseError(`expected a route and at most one target directory, got ${parsed.positionals.length} arguments`);
@@ -306,5 +583,16 @@ export function parseAddRouteArgs(argv) {
     if (route.includes(",")) {
         throw new ParseError(`add-route takes exactly one route, got "${route}" — run it once per route`);
     }
-    return { route, target, help };
+    if (route !== MAGNET_ROUTE) {
+        if (path !== undefined || flow !== undefined) {
+            throw new AddRouteRefusedError(`--path and --flow belong to \`create-ailk add-route magnet\`, not to the "${route}" route`);
+        }
+        return { route, target, help };
+    }
+    if (help)
+        return { route, target, help };
+    if (path === undefined || flow === undefined) {
+        throw new ParseError("add-route magnet needs --path and --flow, e.g. `create-ailk add-route magnet --path /diagnostic --flow growth`");
+    }
+    return { route, target, help, path, flow };
 }

package/dist/cli.js

@@ -6,7 +6,8 @@
  *   0. on an `add-module` / `upgrade` subcommand: parse its own argv, run
  *      addModule(), print the report, exit (2 on a refusal it names)
  *      on an `add-route` subcommand: add one route surface to an existing
- *      site, print the report, exit (2 on a refusal it names) (#6947)
+ *      site, print the report, exit (2 on a refusal it names) (#6947); with
+ *      the `magnet` route word, write a magnet page pair instead (#8840)
  *      on an `adopt` subcommand: record an existing site's topology and
  *      pattern version in its manifest, print the report, exit (2 on a
  *      refusal it names) (#7875)
@@ -45,15 +46,17 @@
  */
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { ADD_MODULE_HELP, AddModuleRefusedError, formatAddModuleReport, parseAddModuleArgs, } from "./add-module.js";
-import { ADD_ROUTE_HELP, AddRouteRefusedError, addRouteToScaffold, formatAddRouteReport, parseAddRouteArgs, } from "./add-route.js";
+import { ADD_ROUTE_HELP, AddRouteRefusedError, MAGNET_ROUTE, addMagnetToScaffold, addRouteToScaffold, formatAddMagnetReport, formatAddRouteReport, parseAddRouteArgs, } from "./add-route.js";
 import { ADOPT_HELP, AdoptRefusedError, adoptSite, formatAdoptReport, parseAdoptArgs, } from "./adopt.js";
 import { APPLY_DESIGN_HELP, applyDesign, formatApplyDesignReport, parseApplyDesignArgs, } from "./apply-design.js";
 import { CLAUDE_MD_CHECK_PATH } from "./claude-md.js";
 import { buildScaffoldMarkers } from "./copy.js";
 import { assertReleased } from "./lib/module-license-gate.js";
+import { withNpmTokenUserConfig } from "./lib/npm-auth.js";
 import { FREE_PREREQUISITES_NOTE, LICENSED_PREREQUISITES_NOTE, isLicensedInstall, proCallout, } from "./lib/pro-callout.js";
 import { LICENSE_SET_HELP, runLicenseSet } from "./license-set.js";
 import { PLUGIN_INSTALL_LINES, helpText, parseCliArgs, parseModules, resolveCliShape, toScaffoldOptions, } from "./parse-args.js";
@@ -147,14 +150,26 @@ async function main() {
     // scaffolded without — add-module's route, architecture and nav steps with
     // no licence and no bundle. A refusal it names (an unknown route, one a
     // module delivers, an unreadable architecture.yaml) exits 2.
+    // `add-route magnet --path <path> --flow <slug> [dir]` (#8840 D12) writes a
+    // magnet page pair instead; its refusals (no signal-collectors, a path the
+    // site serves or reserves, a bad slug, --path/--flow on another route) exit 2.
     if (argv[0] === "add-route") {
-        const args = parseAddRouteArgs(argv.slice(1));
-        if (args.help || args.route === undefined) {
-            process.stdout.write(ADD_ROUTE_HELP);
-            process.exit(0);
-        }
-        const targetDir = resolve(args.target ?? process.cwd());
         try {
+            const args = parseAddRouteArgs(argv.slice(1));
+            if (args.help || args.route === undefined) {
+                process.stdout.write(ADD_ROUTE_HELP);
+                process.exit(0);
+            }
+            const targetDir = resolve(args.target ?? process.cwd());
+            if (args.route === MAGNET_ROUTE) {
+                const result = addMagnetToScaffold({
+                    targetDir,
+                    path: args.path ?? "",
+                    flow: args.flow ?? "",
+                });
+                process.stdout.write(formatAddMagnetReport(result));
+                process.exit(0);
+            }
             const result = addRouteToScaffold({
                 targetDir,
                 route: args.route,
@@ -428,11 +443,13 @@ async function main() {
     const templateName = starter?.template ?? opts.template;
     if (opts.install) {
         // Hard-coded argv. User input only flows through `cwd`, never the command.
-        const result = spawnSync("pnpm", ["install"], {
+        // NPM_TOKEN reaches pnpm at user level, never a project .npmrc (#9092).
+        const result = withNpmTokenUserConfig(process.env, homedir(), (env) => spawnSync("pnpm", ["install"], {
             cwd: targetAbs,
+            env,
             stdio: "inherit",
             shell: false,
-        });
+        }));
         if (result.status !== 0) {
             throw new Error(`pnpm install failed in ${targetAbs} (exit ${result.status}). Run it manually after fixing the issue.`);
         }

package/dist/derive-architecture.d.ts

@@ -22,20 +22,22 @@ export interface DeriveArchitectureOptions {
     /** Spoke only: whether the spoke keeps `apps/mcp` (default true). */
     mcp?: boolean;
 }
+/** The billing action a spoke that signs in through its hub renders (#8217 D6). */
+export declare const SPOKE_BILLING_ACTION_PATH = "apps/web/app/[locale]/(authed)/account/billing/spoke-billing.action.ts";
 /**
  * The only spoke files that may import @working-theory/spoke-checkout (#7873):
- * the buy route, the webhook route and — on a spoke that signs in through its
- * hub — the billing action (#8217 D9, a reviewed change to the #7873 rule).
+ * the billing action, on a spoke that signs in through its hub (#8217 D9).
+ * The buy route and the Stripe webhook route that were also here are retired
+ * (#9142): a spoke sells through its hub's Offerings buy route.
  */
 export declare const SPOKE_CHECKOUT_ROUTE_FILES: readonly string[];
 /**
  * The spoke files that may import @working-theory/spoke-checkout to READ a
  * paid session, and nothing else: the thank-you page's `readPaidCheckoutEmail`
- * (#8757 D13). Kept apart from SPOKE_CHECKOUT_ROUTE_FILES so it does not
- * also admit them to `lib/checkout`, the one file that fulfils an order.
+ * (#8757 D13).
  */
 export declare const SPOKE_CHECKOUT_READER_FILES: readonly string[];
-/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). */
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). The fulfilment pattern that guarded `lib/checkout.ts` retired with it (#9142). */
 export declare const SPOKE_WEB_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];
 /** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
 export declare const SPOKE_MCP_FORBIDDEN_PATTERNS: readonly ForbiddenPattern[];

package/dist/derive-architecture.js

@@ -15,6 +15,8 @@
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
 import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+/** The npm scope a site consumes and never forks (#9191). */
+const PACKAGE_SCOPE = "@working-theory/";
 /** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
 const SPOKE_TIERS = {
     data: "none — the hub's database",
@@ -27,21 +29,21 @@ const SPOKE_TIERS = {
 // import only to a workspace on disk, so the one way to ban an npm package is
 // a line-level forbidden pattern. These go under the spoke's own `apps.web`
 // and `apps.mcp` only — never top level, and never on a hub derivation.
+/** The billing action a spoke that signs in through its hub renders (#8217 D6). */
+export const SPOKE_BILLING_ACTION_PATH = "apps/web/app/[locale]/(authed)/account/billing/spoke-billing.action.ts";
 /**
  * The only spoke files that may import @working-theory/spoke-checkout (#7873):
- * the buy route, the webhook route and — on a spoke that signs in through its
- * hub — the billing action (#8217 D9, a reviewed change to the #7873 rule).
+ * the billing action, on a spoke that signs in through its hub (#8217 D9).
+ * The buy route and the Stripe webhook route that were also here are retired
+ * (#9142): a spoke sells through its hub's Offerings buy route.
  */
 export const SPOKE_CHECKOUT_ROUTE_FILES = Object.freeze([
-    "apps/web/app/api/checkout/[offering]/route.ts",
-    "apps/web/app/api/webhooks/stripe/route.ts",
-    "apps/web/app/[locale]/(authed)/account/billing/spoke-billing.action.ts",
+    SPOKE_BILLING_ACTION_PATH,
 ]);
 /**
  * The spoke files that may import @working-theory/spoke-checkout to READ a
  * paid session, and nothing else: the thank-you page's `readPaidCheckoutEmail`
- * (#8757 D13). Kept apart from SPOKE_CHECKOUT_ROUTE_FILES so it does not
- * also admit them to `lib/checkout`, the one file that fulfils an order.
+ * (#8757 D13).
  */
 export const SPOKE_CHECKOUT_READER_FILES = Object.freeze([
     "apps/web/app/[locale]/checkout/thank-you/page.tsx",
@@ -62,7 +64,7 @@ function specifierForm(specifier) {
 /** P1 with no exclusions — a kept apps/mcp's form; apps/web adds the route files. */
 const SPOKE_CHECKOUT_PATTERN = Object.freeze({
     pattern: specifierForm("@working-theory/spoke-checkout"),
-    reason: "Spoke checkout: only the buy route, the webhook route, the billing action and the thank-you page may import @working-theory/spoke-checkout (brief Part 2 §2, #7873, #8217, #8757)",
+    reason: "Spoke checkout: only the billing action and the thank-you page may import @working-theory/spoke-checkout (brief Part 2 §2, #7873, #8217, #8757, #9142)",
 });
 const STRIPE_CLIENT_PATTERN = Object.freeze({
     pattern: specifierForm("@working-theory/stripe-client"),
@@ -72,29 +74,7 @@ const STRIPE_SDK_PATTERN = Object.freeze({
     pattern: specifierForm("stripe"),
     reason: "A spoke never imports the stripe SDK directly — it reaches Stripe only through @working-theory/spoke-checkout (#7873)",
 });
-/**
- * The standard spoke checkout's fulfilment (`lib/checkout.ts`) sends the one
- * `Idempotency-Key` the hub reads as a purchase, so only the files allowed to
- * import the package may reach it (#8748 D3, SEC-8748-A): any relative or
- * `@/`-aliased import (apps/web's tsconfig maps `@/*` to the app root) whose
- * last segment is `checkout` (with or without a `.js`/`.ts`-family
- * extension, which `bundler` resolution maps to the same file), in every form
- * `specifierForm` covers. The
- * closing quote straight after `checkout` keeps `checkout-config` and
- * `checkout.actions` out of it. The checkout tests the writer copies are
- * excluded too: the scaffold's lint reads test files.
- */
-const SPOKE_FULFILMENT_PATTERN = Object.freeze({
-    pattern: "\\b(?:from|import|require)\\s*\\(?\\s*['\"`](?:(?:\\.{1,2}/)+|@/)(?:[^'\"`]*/)?checkout(?:\\.[cm]?[jt]sx?)?['\"`]",
-    paths_excluded: [
-        ...SPOKE_CHECKOUT_ROUTE_FILES,
-        "apps/web/app/api/checkout/__tests__/**",
-        "apps/web/app/api/webhooks/stripe/__tests__/**",
-        "apps/web/lib/__tests__/checkout.test.ts",
-    ],
-    reason: "Spoke checkout: only the buy route, the webhook route and the billing action may import lib/checkout, the one file that sends the hub an Idempotency-Key (#8748)",
-});
-/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). */
+/** The forbidden patterns a spoke's apps/web carries (#7873, brief Part 2 §2; #8748). The fulfilment pattern that guarded `lib/checkout.ts` retired with it (#9142). */
 export const SPOKE_WEB_FORBIDDEN_PATTERNS = Object.freeze([
     Object.freeze({
         ...SPOKE_CHECKOUT_PATTERN,
@@ -102,7 +82,6 @@ export const SPOKE_WEB_FORBIDDEN_PATTERNS = Object.freeze([
     }),
     STRIPE_CLIENT_PATTERN,
     STRIPE_SDK_PATTERN,
-    SPOKE_FULFILMENT_PATTERN,
 ]);
 /** The same three for a spoke's kept apps/mcp — no MCP file may import the package (#7873). */
 export const SPOKE_MCP_FORBIDDEN_PATTERNS = Object.freeze([
@@ -337,6 +316,20 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
     for (const s of slices)
         extraForbidden.push(...(s.forbiddenPatterns ?? []));
     const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
+    // The upgradeable-consumer rules (#9191): the workspaces this scaffold
+    // creates and the in-scope package names it gives them. The site lint
+    // reads this block to refuse a forked, patched or pinned-off package.
+    // Every app the scaffold ships is named `@working-theory/<dir>`.
+    const upgradeableConsumer = {
+        package_scope: PACKAGE_SCOPE,
+        workspaces: spoke ? ["apps/*"] : ["apps/*", "database"],
+        scaffold_packages: [
+            ...(spoke ? [] : ["database"]),
+            ...Object.keys(apps),
+        ]
+            .map((dir) => `${PACKAGE_SCOPE}${dir}`)
+            .sort(),
+    };
     const doc = {
         version: ARCHITECTURE_BASE.version,
         ...(spoke ? { topology: "spoke" } : {}),
@@ -353,6 +346,7 @@ export function deriveArchitecture(modules = ["marketing"], surfaces, options =
         apps,
         ...(nsSlice ? { namespaces: namespacesToYaml(nsSlice) } : {}),
         forbidden_patterns: forbidden.map(forbiddenToYaml),
+        upgradeable_consumer: upgradeableConsumer,
     };
     const header = [
         "# Architecture Boundaries — AI Launch Kit site",

package/dist/lib/design-checks.js

@@ -134,11 +134,13 @@ export function admitSeededPeopleSlide(before, after) {
     if (!Array.isArray(graph))
         return after;
     const [page, ...people] = graph;
+    // A seeded `{placeholder}` name or title never reaches the graph (#8797 D8.4).
+    const slot = (value) => /^\{[^{}]+\}$/.test(value.trim());
     const expected = TEAM_SEED_MEMBERS.map((m) => ({
         "@context": "https://schema.org",
         "@type": "Person",
-        name: m.name,
-        jobTitle: m.role,
+        ...(!slot(m.name) && { name: m.name }),
+        ...(!slot(m.role) && { jobTitle: m.role }),
     }));
     const isPeopleSlide = isDeepStrictEqual(page, JSON.parse(standard.jsonld)) && isDeepStrictEqual(people, expected);
     return isPeopleSlide ? { ...after, [HOME_PAGE]: standard } : after;

package/dist/lib/env-catalog.js

@@ -207,10 +207,6 @@ export const ENV_CATALOG = {
         description: "Shared secret the /dev/purchase action sends to the API's checkout route; must equal the API's value. Server-only.",
         secret: true,
     },
-    SCHEDULING_CAL_LINK: {
-        description: 'Which event /meet books, as "<owner>/<event-slug>"; unset makes /meet 404.',
-        secret: false,
-    },
     SENTRY_AUTH_TOKEN: {
         description: "Build-time Sentry token that uploads source maps; unset skips the upload.",
         secret: true,

package/dist/lib/npm-auth.d.ts

@@ -0,0 +1,9 @@
+/** The one user-level line: the registry mapped to the env var, no value. */
+export declare const NPM_TOKEN_AUTH_LINE = "//registry.npmjs.org/:_authToken=${NPM_TOKEN}";
+/**
+ * Calls `run` with the env the install should use: `env` itself, or — when
+ * `NPM_TOKEN` is set and no user npmrc exists — `env` plus
+ * `NPM_CONFIG_USERCONFIG` naming a temporary reference-only npmrc, which is
+ * removed once `run` returns or throws.
+ */
+export declare function withNpmTokenUserConfig<T>(env: NodeJS.ProcessEnv, home: string, run: (env: NodeJS.ProcessEnv) => T): T;