create-ailk 0.20.0 → 0.22.0

package/dist/spoke-checkout.js

@@ -1,26 +1,35 @@
 /**
- * The spoke checkout slice (#7838) — what a spoke carrying `commerce` gets in
- * `apps/web`: the buy route and the Stripe webhook route (allowed to import
- * the checkout package, #7873), the site's own `lib/checkout-config.ts`, and
- * the thank-you and unavailable return pages. A spoke that signs in through
- * its hub also gets the billing action, the third file allowed to import the
- * package, and the web seam render that reaches it (#8217 D6–D8).
+ * The spoke checkout slice (#7838, #8748) — what a spoke carrying `commerce`
+ * gets in `apps/web`: the standard spoke checkout, copied from the template
+ * tree. That is the buy route and the Stripe webhook route (allowed to import
+ * the checkout package, #7873), `lib/checkout.ts` (the standard fulfilment),
+ * the site's own `lib/checkout-config.ts`, the thank-you and unavailable
+ * return pages and their tests (`SPOKE_CHECKOUT_TEMPLATE_PATHS`). A spoke that
+ * signs in through its hub also gets the billing action, the third file
+ * allowed to import the package, and the web seam render that reaches it
+ * (#8217 D6–D8); that action and the checkout e2e workflow are still rendered
+ * here.
  *
  * Every guarantee lives in `@working-theory/spoke-checkout` and arrives by a
- * package bump; these files are thin and, apart from the config's one stamp
- * line, byte-identical across spokes at one create-ailk version (roadmap D3,
- * AC-SPOKE-02). A hub never gets them: its checkout is `apps/api`'s.
+ * package bump; the copied files are `apps/web` source, tested in the
+ * monorepo and kept current by `create-ailk update`, and apart from the
+ * config's one stamp line they are byte-identical across spokes at one
+ * create-ailk version (roadmap D3, AC-SPOKE-02). A hub never gets them: its
+ * checkout is `apps/api`'s.
  *
- * Spec: docs/specs/7838-spoke-web-checkout-slice-spec.md (D3–D7, D9).
+ * Spec: docs/specs/7838-spoke-web-checkout-slice-spec.md (D3–D7, D9);
+ * docs/specs/8748-a-standard-spoke-checkout-route-spec.md (D2, D3).
  *
- * Pure module: no `import.meta.url`, so jest imports it directly. Every
- * package specifier in a rendered file is interpolated from a constant, so the
- * monorepo's own architecture lint never reads a rendered line as an import
- * create-ailk makes (the `CONTENT_ADAPTERS_PACKAGE` idiom in topology.ts).
+ * Pure module: no `import.meta.url`, so jest imports it directly — the caller
+ * passes `templatesDir`. Every package specifier in a rendered file is
+ * interpolated from a constant, so the monorepo's own architecture lint never
+ * reads a rendered line as an import create-ailk makes (the
+ * `CONTENT_ADAPTERS_PACKAGE` idiom in topology.ts).
  */
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, writeFileSync, } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { buildScaffoldMarkers, renderTemplateFile, templateDestination } from "./copy.js";
 import { SPOKE_CHECKOUT_ROUTE_FILES } from "./derive-architecture.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
@@ -29,9 +38,7 @@ import { TopologyError, WEB_SEAM_PATH, renderWebSeam, } from "./topology.js";
 /** The checkout package a spoke's two route files import. */
 export const SPOKE_CHECKOUT_PACKAGE = "@working-theory/spoke-checkout";
 const API_CLIENT_PACKAGE = "@working-theory/api-client";
-const UI_SECTIONS_PACKAGE = "@working-theory/ui/sections";
-const VALIDATION_PACKAGE = "@working-theory/validation";
-/** The site's checkout data — written once, the site's from then on. */
+/** The site's checkout data — written once, the site's from then on (#8748 D2). */
 export const SPOKE_CHECKOUT_CONFIG_PATH = "apps/web/lib/checkout-config.ts";
 /** The two return pages: Stripe's success URL and every refused buy's target. */
 export const SPOKE_CHECKOUT_PAGE_FILES = Object.freeze([
@@ -39,12 +46,19 @@ export const SPOKE_CHECKOUT_PAGE_FILES = Object.freeze([
     "apps/web/app/[locale]/checkout/unavailable/page.tsx",
 ]);
 /**
- * The marker `renderPage()` stamps into both generated return pages' header
- * comment (D3). `apps/web`'s structured-data test cannot import create-ailk
- * (the import boundary), so it carries this text as a literal, kept in sync
- * by `packages/create-ailk/__tests__/spoke-checkout.test.ts` (#8513 AC-5).
+ * The standard spoke checkout's template paths, scaffold-relative (#8748 D3).
+ * A directory entry covers every file under it, so the tests that sit beside
+ * the routes and pages travel with them. `copyTemplate` skips all of them for
+ * every scaffold; `writeSpokeCheckoutSlice` copies them into a commerce spoke.
  */
-export const SPOKE_CHECKOUT_PAGE_MARKER = "GENERATED by create-ailk (#7838)";
+export const SPOKE_CHECKOUT_TEMPLATE_PATHS = Object.freeze([
+    "apps/web/app/api/checkout",
+    "apps/web/app/api/webhooks/stripe",
+    "apps/web/app/[locale]/checkout",
+    "apps/web/lib/checkout.ts",
+    SPOKE_CHECKOUT_CONFIG_PATH,
+    "apps/web/lib/__tests__/checkout.test.ts",
+]);
 /** The variables a commerce spoke depends on (D9). The package reads three of them. */
 export const SPOKE_CHECKOUT_ENV_CATALOG = Object.freeze({
     STRIPE_SECRET_KEY: {
@@ -59,10 +73,9 @@ export const SPOKE_CHECKOUT_ENV_CATALOG = Object.freeze({
         description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: test (the default) or live. Live is the operator's switch, per site.`,
         secret: false,
     },
-    AILK_SPOKE_KEY: {
-        description: "The hub-issued key this site sends as x-ailk-spoke-key; the checkout fulfilment refuses to run without it. Never committed.",
-        secret: true,
-    },
+    // Read by the standard spoke checkout's fulfilment, so the base catalog
+    // carries it too (#8748).
+    AILK_SPOKE_KEY: ENV_CATALOG["AILK_SPOKE_KEY"],
 });
 /** The names a commerce spoke declares although only the package reads them (D9). */
 export const SPOKE_CHECKOUT_DECLARED_ENV = Object.freeze([
@@ -112,34 +125,6 @@ export function spokeCheckoutSite(projectName) {
     const digest = createHash("sha256").update(projectName).digest("hex");
     return `site-${digest.slice(0, 8)}`;
 }
-/** One route file (D4): three lines of wiring, every guarantee in the package. */
-function renderRoute(opts) {
-    return [
-        `// ${opts.title} — GENERATED by create-ailk (#7838). Do not edit: every`,
-        "// guarantee lives in the spoke-checkout package and arrives by a package",
-        "// bump. This site's data is lib/checkout-config.ts.",
-        `import { createSpokeCheckout } from "${SPOKE_CHECKOUT_PACKAGE}";`,
-        "",
-        `import { checkoutConfig } from "../../../../lib/checkout-config";`,
-        "",
-        `export const runtime = "nodejs";`,
-        `export const dynamic = "force-dynamic";`,
-        "",
-        `// platform-decisions-waiver: api-versioning — ${opts.waiver} (spec 7838 §7)`,
-        opts.exportLine,
-        "",
-    ].join("\n");
-}
-const BUY_ROUTE = renderRoute({
-    title: "The buy route",
-    waiver: "a browser buy link that redirects to Stripe Checkout, not a versioned API contract",
-    exportLine: "export const { GET, POST } = createSpokeCheckout(checkoutConfig).buy;",
-});
-const WEBHOOK_ROUTE = renderRoute({
-    title: "The Stripe webhook route",
-    waiver: "the endpoint URL registered in Stripe, not a versioned API contract",
-    exportLine: "export const { POST } = createSpokeCheckout(checkoutConfig).webhook;",
-});
 /**
  * The spoke billing action (#8217 D6): wiring only, byte-identical across
  * sites, so every guarantee arrives by a package bump. A plain server module
@@ -156,10 +141,10 @@ const BILLING_ACTION = [
     `import { member } from "${API_CLIENT_PACKAGE}";`,
     `import { createSpokeCheckout } from "${SPOKE_CHECKOUT_PACKAGE}";`,
     "",
-    `import { checkoutConfig } from "../../../../../lib/checkout-config";`,
+    `import { spokeCheckoutConfig } from "../../../../../lib/checkout";`,
     `import { forwardedCookieInit } from "../../../../../lib/server-api";`,
     "",
-    "const billing = createSpokeCheckout(checkoutConfig).billing.forMember(",
+    "const billing = createSpokeCheckout(spokeCheckoutConfig).billing.forMember(",
     "  async () => member.billing(await forwardedCookieInit()),",
     ");",
     "",
@@ -167,162 +152,6 @@ const BILLING_ACTION = [
     "export const spokeBillingPortalUrl = billing.portalUrl;",
     "",
 ].join("\n");
-/** The site's checkout data (D5). Only the `const SITE` line varies by site. */
-function renderConfig(site) {
-    return [
-        "// checkout-config.ts — this spoke's checkout, as data (#7838).",
-        "//",
-        "// Written once by create-ailk and yours from then on: create-ailk never",
-        "// rewrites it. The buy route and the Stripe webhook route build their",
-        "// handlers from it, and so does the billing action on a spoke that signs",
-        "// in through its hub. Only those files may import the checkout package",
-        "// (architecture.yaml), so this file never imports it, stripe-client or the",
-        "// stripe SDK. Keep it to data and the fulfil callback.",
-        "//",
-        "// site       Stamped on every Checkout Session as metadata.site. This site's",
-        "//            webhook acts only on its own stamp, and the hub ignores any stamp",
-        "//            that is not its own, so the stamp must be unique on the Stripe",
-        '//            account this site shares. Never "default". Change it only before',
-        "//            any price exists: every lookup key starts with it.",
-        "// offerings  slug -> Stripe lookup_key. The buy link is /api/checkout/<slug>.",
-        "//            scaffold-commerce replaces the placeholder below.",
-        "// fulfil     Runs for each paid session, at least once. It posts one lead to",
-        "//            the hub with the session id as its Idempotency-Key, so a repeat",
-        "//            writes nothing new. The hub dedupes only an identical body: change",
-        "//            the payload's shape only when no webhook is failing.",
-        `import { leads } from "${API_CLIENT_PACKAGE}";`,
-        "",
-        `import { resolveBaseUrl } from "../src/lib/routes";`,
-        "",
-        `const SITE = "${site}";`,
-        "",
-        "/** What this site's fulfil callback reads from a completed checkout. */",
-        "interface CompletedCheckout {",
-        "  idempotencyKey: string;",
-        "  sessionId: string;",
-        "  offering: string;",
-        '  kind: "fixed" | "quoted";',
-        '  mode: "test" | "live";',
-        "  amountTotal: number | null;",
-        "  currency: string | null;",
-        "  email: string | null;",
-        "  customerId: string | null;",
-        "}",
-        "",
-        "export const checkoutConfig = {",
-        "  site: SITE,",
-        "  siteBaseUrl: resolveBaseUrl(),",
-        "  offerings: {",
-        "    // A placeholder until scaffold-commerce creates this site's prices.",
-        '    example: { kind: "fixed", lookupKey: `${SITE}_example`, cancelPath: "/" },',
-        "  },",
-        "  async fulfil(checkout: CompletedCheckout): Promise<void> {",
-        "    if (checkout.email === null) return;",
-        "    // No spoke key: the hub cannot place the lead in this site's workspace.",
-        "    // Fail, so Stripe retries and the dashboard shows a failed webhook.",
-        "    if (!process.env.AILK_SPOKE_KEY)",
-        '      throw new Error("AILK_SPOKE_KEY is not set");',
-        "    const result = await leads.submit(",
-        "      {",
-        "        siteId: SITE,",
-        '        source: "web",',
-        "        email: checkout.email,",
-        "        payload: {",
-        "          site: SITE,",
-        '          page: "checkout",',
-        "          offering: checkout.offering,",
-        "          checkoutKind: checkout.kind,",
-        "          mode: checkout.mode,",
-        "          amountTotal: checkout.amountTotal,",
-        "          currency: checkout.currency,",
-        "          stripeCustomerId: checkout.customerId,",
-        "          checkoutSession: checkout.sessionId,",
-        "        },",
-        "      },",
-        '      { headers: { "Idempotency-Key": checkout.idempotencyKey } },',
-        "    );",
-        "    // A replay under the same key answers 201 with the first lead; any",
-        "    // failure (422 idempotency_key_reused included) makes Stripe retry.",
-        "    if (!result.ok) throw new Error(`hub lead write answered ${result.status}`);",
-        "  },",
-        "};",
-        "",
-    ].join("\n");
-}
-/** One return page (D7): a server component that reads nothing but its copy. */
-function renderPage(opts) {
-    return [
-        `// ${opts.title} — ${SPOKE_CHECKOUT_PAGE_MARKER}.`,
-        ...opts.about.map((line) => `// ${line}`),
-        `import { SectionRenderer } from "${UI_SECTIONS_PACKAGE}";`,
-        `import type { PageSection } from "${VALIDATION_PACKAGE}";`,
-        `import type { Metadata } from "next";`,
-        `import { getTranslations } from "next-intl/server";`,
-        `import type { ReactElement } from "react";`,
-        "",
-        "interface Props {",
-        "  params: Promise<{ locale: string }>;",
-        "}",
-        "",
-        "export async function generateMetadata({ params }: Props): Promise<Metadata> {",
-        "  const { locale } = await params;",
-        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
-        `  return { title: t("title"), robots: { index: false, follow: false } };`,
-        "}",
-        "",
-        "export default async function Page({ params }: Props): Promise<ReactElement> {",
-        "  const { locale } = await params;",
-        `  const t = await getTranslations({ locale, namespace: "${opts.namespace}" });`,
-        "  const sections: PageSection[] = [",
-        ...opts.sections.map((line) => `    ${line}`),
-        "  ];",
-        "  return (",
-        '    <main id="main">',
-        "      <SectionRenderer sections={sections} locale={locale} leadingSectionOwnsTitle />",
-        "    </main>",
-        "  );",
-        "}",
-        "",
-    ].join("\n");
-}
-const THANK_YOU_PAGE = renderPage({
-    title: "The checkout thank-you page",
-    about: [
-        "Stripe returns a buyer here after paying. It reads no search parameter and",
-        "calls neither Stripe nor the hub: the webhook is what fulfils the order.",
-    ],
-    namespace: "checkoutThankYou",
-    sections: [
-        "{",
-        '  id: "checkout-thank-you",',
-        '  type: "content-block",',
-        '  data: { headline: t("title"), body: t("body") },',
-        "},",
-    ],
-});
-const UNAVAILABLE_PAGE = renderPage({
-    title: "The checkout unavailable page",
-    about: [
-        "Every refused buy lands here. It never says why: a reason is a probe's",
-        "answer, and the buyer needs only that nothing was charged.",
-    ],
-    namespace: "checkoutUnavailable",
-    sections: [
-        "{",
-        '  id: "checkout-unavailable",',
-        '  type: "content-block",',
-        '  data: { headline: t("title"), body: t("body") },',
-        "},",
-        "{",
-        '  id: "checkout-unavailable-cta",',
-        '  type: "cta",',
-        "  data: {",
-        '    headline: t("ctaHeadline"),',
-        '    primaryCta: { label: t("ctaLabel"), href: "/contact" },',
-        "  },",
-        "},",
-    ],
-});
 // ── #7839 D8 — the checkout e2e workflow ─────────────────────────────────────
 /** Where a commerce spoke's end-to-end checkout workflow lives. */
 export const SPOKE_CHECKOUT_E2E_WORKFLOW_PATH = ".github/workflows/checkout-e2e.yml";
@@ -497,28 +326,69 @@ jobs:
           retention-days: 7
 `;
 /**
- * The slice for `site`, in order: the two route files, the config, the two
- * pages (D3), then the checkout e2e workflow (#7839 D8), which does not
- * depend on `site`. With `signIn: "hub"` the billing action is the third
- * pair, so the first three paths are `SPOKE_CHECKOUT_ROUTE_FILES` (#8217 D8).
- * Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ * The rendered part of the slice for `site` (#8748 D3): with `signIn: "hub"`
+ * the billing action (#8217 D8), then the checkout e2e workflow (#7839 D8).
+ * Neither depends on `site`. The rest of the slice is template source,
+ * copied by `writeSpokeCheckoutSlice`. Throws `TopologyError` for an invalid
+ * stamp (SEC-7838-10).
  */
 export function renderSpokeCheckoutFiles(site, opts = {}) {
     assertSite(site);
-    const [buyPath, webhookPath, billingActionPath] = SPOKE_CHECKOUT_ROUTE_FILES;
-    const [thankYouPath, unavailablePath] = SPOKE_CHECKOUT_PAGE_FILES;
+    const billingActionPath = SPOKE_CHECKOUT_ROUTE_FILES[2];
     return [
-        [buyPath, BUY_ROUTE],
-        [webhookPath, WEBHOOK_ROUTE],
         ...(opts.signIn === "hub"
             ? [[billingActionPath, BILLING_ACTION]]
             : []),
-        [SPOKE_CHECKOUT_CONFIG_PATH, renderConfig(site)],
-        [thankYouPath, THANK_YOU_PAGE],
-        [unavailablePath, UNAVAILABLE_PAGE],
         [SPOKE_CHECKOUT_E2E_WORKFLOW_PATH, CHECKOUT_E2E_WORKFLOW],
     ];
 }
+/** The one line of the template's config the writer stamps (#8748 D2). */
+const SITE_LINE = /^const SITE = "[a-z0-9-]+";$/gm;
+/**
+ * Every template file under `SPOKE_CHECKOUT_TEMPLATE_PATHS`, sorted, as its
+ * destination path and its source. A symlink is skipped, never followed, as
+ * `copyTemplate` skips one; a `.gitkeep` has no destination.
+ */
+function templateCheckoutFiles(templatesDir) {
+    const out = [];
+    const visit = (rel) => {
+        const abs = join(templatesDir, ...rel.split("/"));
+        if (!existsSync(abs))
+            return;
+        const stat = lstatSync(abs);
+        if (stat.isSymbolicLink())
+            return;
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(abs))
+                visit(`${rel}/${name}`);
+            return;
+        }
+        const dest = templateDestination(rel);
+        if (dest !== undefined)
+            out.push([dest, abs]);
+    };
+    for (const entry of SPOKE_CHECKOUT_TEMPLATE_PATHS)
+        visit(entry);
+    return out.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+}
+/** Whether anything — a dangling symlink included — sits at `abs`. */
+function lstatExists(abs) {
+    try {
+        lstatSync(abs);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether a path, or (when absent) its nearest existing ancestor, resolves inside `targetReal`. */
+function resolvesInside(targetReal, abs) {
+    let probe = abs;
+    while (!existsSync(probe) && dirname(probe) !== probe)
+        probe = dirname(probe);
+    const real = realpathSync(probe);
+    return real === targetReal || real.startsWith(targetReal + sep);
+}
 const WEB_PACKAGE_JSON = "apps/web/package.json";
 /** `deps` with `name: version` added in sorted position, every other key kept in place. */
 function withDependency(deps, name, version) {
@@ -556,28 +426,78 @@ function isOlderPin(current, wanted) {
     return false;
 }
 /**
- * Write the slice into `targetDir` (D3). A file that already exists is left
- * byte-for-byte and reported `skipped` — the config is the site's once
+ * Write the slice into `targetDir` (#7838 D3, #8748 D3). The standard's
+ * template files (`SPOKE_CHECKOUT_TEMPLATE_PATHS`) are copied from
+ * `templatesDir`, each rendered with `copyTemplate`'s own renderer and
+ * markers, so a recorded hash equals what `create-ailk update` renders; the
+ * config's one `const SITE` line is stamped with `site`. `onWrite` is called
+ * once per template file written, as `copyTemplate` calls it. Then come the
+ * rendered files (`renderSpokeCheckoutFiles`). A file that already exists is
+ * left byte-for-byte and reported `skipped` — the config is the site's once
  * written. With `signIn: "hub"` (#8217 D8) the slice carries the billing
  * action, and the web seam — generated, so always rewritten — becomes the
- * billing render: reported `patched` when it changed, not at all when equal. Adds the package to `apps/web/package.json` when absent, and
- * raises a plain pin older than the one it writes (#7839): the generated
- * checkout e2e workflow runs a command a `^0.2.0` pin never reaches. Any
- * other range — newer, `workspace:`, a tag — is the site's and is kept.
+ * billing render: reported `patched` when it changed, not at all when equal.
+ * Adds the package to `apps/web/package.json` when absent, and raises a plain
+ * pin older than the one it writes (#7839): the generated checkout e2e
+ * workflow runs a command a `^0.2.0` pin never reaches. Any other range —
+ * newer, `workspace:`, a tag — is the site's and is kept.
  * Every refusal (an invalid stamp, a version map without the package, a
- * missing or malformed `apps/web/package.json`) throws before the first write.
+ * missing or malformed `apps/web/package.json`, a template missing any
+ * `SPOKE_CHECKOUT_TEMPLATE_PATHS` entry, a template config without exactly
+ * one `const SITE` line, a destination to write that resolves outside
+ * `targetDir`) throws before the first write.
  */
 export function writeSpokeCheckoutSlice(targetDir, opts) {
-    const files = renderSpokeCheckoutFiles(opts.site, { signIn: opts.signIn });
+    const rendered = renderSpokeCheckoutFiles(opts.site, { signIn: opts.signIn });
     const range = JSON.parse(substituteWorkspaceVersions(`{"${SPOKE_CHECKOUT_PACKAGE}": "workspace:*"}`, opts.versions));
     const version = range[SPOKE_CHECKOUT_PACKAGE];
     const pkgPath = join(targetDir, WEB_PACKAGE_JSON);
     const before = readFileSync(pkgPath, "utf8");
     const pkg = JSON.parse(before);
+    const markers = buildScaffoldMarkers(opts.projectName);
+    const copied = [];
+    for (const [path, source] of templateCheckoutFiles(opts.templatesDir)) {
+        let bytes = Buffer.from(renderTemplateFile(readFileSync(source), path, opts.versions, markers));
+        if (path === SPOKE_CHECKOUT_CONFIG_PATH) {
+            const text = bytes.toString("utf8");
+            const lines = text.match(SITE_LINE) ?? [];
+            if (lines.length !== 1) {
+                throw new TopologyError(`spoke checkout: the template's ${SPOKE_CHECKOUT_CONFIG_PATH} must hold exactly one const SITE line, found ${lines.length}`);
+            }
+            bytes = Buffer.from(text.replace(SITE_LINE, `const SITE = "${opts.site}";`), "utf8");
+        }
+        copied.push([path, bytes]);
+    }
+    const missing = SPOKE_CHECKOUT_TEMPLATE_PATHS.filter((entry) => !copied.some(([path]) => path === entry || path.startsWith(`${entry}/`)));
+    if (missing.length > 0) {
+        throw new TopologyError(`spoke checkout: the template has no ${missing.join(", ")}`);
+    }
+    // A file already there is skipped below, never written, so only a path
+    // that will be written must resolve inside the site.
+    const targetReal = realpathSync(targetDir);
+    for (const [path] of [...copied, ...rendered]) {
+        const abs = resolve(targetDir, path);
+        if (lstatExists(abs))
+            continue;
+        if (!resolvesInside(targetReal, abs)) {
+            throw new TopologyError(`spoke checkout: refusing to write outside the site: ${path}`);
+        }
+    }
     const rows = [];
-    for (const [path, text] of files) {
+    for (const [path, bytes] of copied) {
+        const abs = join(targetDir, path);
+        if (lstatExists(abs)) {
+            rows.push({ path, action: "skipped", wanted: bytes.toString("utf8") });
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, bytes);
+        opts.onWrite?.(path, bytes);
+        rows.push({ path, action: "written" });
+    }
+    for (const [path, text] of rendered) {
         const abs = join(targetDir, path);
-        if (existsSync(abs)) {
+        if (lstatExists(abs)) {
             rows.push({ path, action: "skipped", wanted: text });
             continue;
         }
@@ -617,3 +537,24 @@ export function writeSpokeCheckoutSlice(targetDir, opts) {
     }
     return rows;
 }
+/**
+ * Drop the checkout package from a scaffold that does not get the slice — a
+ * hub, or a spoke without `commerce` (#8748 D3). The template's
+ * `apps/web/package.json` depends on it because the monorepo's `apps/web`
+ * carries the standard. Every other key is kept in place; a site without the
+ * dependency, or without `apps/web/package.json`, is left as it is.
+ */
+export function dropSpokeCheckoutDependency(targetDir) {
+    const pkgPath = join(targetDir, WEB_PACKAGE_JSON);
+    if (!existsSync(pkgPath))
+        return;
+    const before = readFileSync(pkgPath, "utf8");
+    const pkg = JSON.parse(before);
+    const deps = pkg.dependencies;
+    if (deps === undefined ||
+        !Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)) {
+        return;
+    }
+    delete deps[SPOKE_CHECKOUT_PACKAGE];
+    writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}${before.endsWith("\n") ? "\n" : ""}`);
+}

package/dist/starter-grid.js

@@ -117,6 +117,10 @@ const TEMPLATE_BASE_ROSTER = [
     { route: "/sign-up" },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
     {
         route: "/purchase-policy",
         content: ["content/en/PurchasePolicyPage/purchase-policy.mdx"],
@@ -235,6 +239,10 @@ const ORGANIZATION_SERVICE_ROWS = [
     { route: "/sign-up" },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
     {
         route: "/purchase-policy",
         content: ["content/en/PurchasePolicyPage/purchase-policy.mdx"],
@@ -267,6 +275,10 @@ const LOCAL_BUSINESS_SERVICE_ROWS = [
     },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
 ];
 /**
  * `person-service`'s own rows (#6758 D1, D3), derived from
@@ -302,6 +314,10 @@ const PERSON_SERVICE_ROWS = [
     },
     { route: "/privacy", content: ["content/en/PrivacyPage/privacy.mdx"] },
     { route: "/terms", content: ["content/en/TermsPage/terms.mdx"] },
+    {
+        route: "/working-agreement",
+        content: ["content/en/WorkingAgreementPage/working-agreement.mdx"],
+    },
 ];
 /**
  * Each buildable shape's standard roster (#6753 D3) — the rows an alias starts

package/dist/surfaces.js

@@ -331,6 +331,13 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/whitepapers`],
         content: ["content/<locale>/Whitepaper"],
     },
+    {
+        // #8661 D10 — the working agreement, module-less like `privacy` and
+        // `terms`: every shape roster names it right after /terms.
+        id: "working-agreement",
+        routes: [`${ROUTE_ROOT}/working-agreement`],
+        content: ["content/<locale>/WorkingAgreementPage"],
+    },
 ];
 /** The recognized `--surfaces` vocabulary, sorted. */
 export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
@@ -552,6 +559,7 @@ export function isUnservedSurfaceContent(path, enabled) {
  */
 export const ROUTE_SINCE = {
     about: "0.0.0",
+    "about/[slug]": "0.42.0",
     "blog/[[...slug]]": "0.0.0",
     careers: "0.0.0",
     "careers/[slug]": "0.0.0",
@@ -638,6 +646,9 @@ export const ROUTE_SINCE = {
     "vs/[slug]": "0.28.0",
     whitepapers: "0.0.0",
     "whitepapers/[slug]": "0.0.0",
+    // #8661 D10 — the working-agreement page. Genuinely new, so it attaches at
+    // the fixed group's next release line, the same rule #7430 applied.
+    "working-agreement": "0.42.0",
     // #5014 — the (authed) route GROUP: layout.tsx + sign-in-gate.tsx sit
     // directly under "(authed)" (a Next.js route group — its parens are not a
     // URL segment); account/ and waitlist/ are its two syncable sub-trees.
@@ -787,38 +798,42 @@ export const ROUTE_DEPENDENCIES = {
         "apps/web/lib/auth-routes.ts",
     ],
     "(auth)/sign-in": ["apps/web/lib/auth-env.ts"],
-    // #8438 D13/D21 — the sign-up card's agreements gate also carries the
-    // carried-cookie mint, `sign-up.actions.ts`, beside it in this route's own
-    // directory.
+    // #8765 D8/D9 — the sign-up page links its agreements through the one
+    // localized policy map; the carried-cookie mint (`sign-up.actions.ts`) is
+    // deleted, since the server now refuses and records the agreements.
     "(auth)/sign-up": [
         "apps/web/lib/auth-env.ts",
-        `${ROUTE_ROOT}/(auth)/sign-up/sign-up.actions.ts`,
+        "apps/web/lib/consent-policies.ts",
     ],
     "(auth)/forgot-password": ["apps/web/lib/auth-env.ts"],
     "(auth)/reset-password": ["apps/web/lib/auth-env.ts"],
     // #7430 — the group's layout reads `isAccountPath()` to give the account
-    // area its member-facing signed-out gate.
+    // area its member-facing signed-out gate. #8765 D3/D4 — `auth.ts` imports
+    // the sign-up agreements plugin and hooks, so that file travels beside it.
     "(authed)": [
         "apps/web/auth.ts",
         "apps/web/lib/auth-env.ts",
         "apps/web/lib/auth-routes.ts",
+        "apps/web/lib/sign-up-agreements.ts",
     ],
     "(authed)/account": [
         "apps/web/lib/account-config.ts",
+        "apps/web/lib/consent-policies.ts",
         "apps/web/lib/server-api.ts",
         "apps/web/lib/site-brand.tsx",
         "apps/web/lib/site-logo.tsx",
-        // #8438 D13/D21 — two brand-new files in this already-existing route
-        // directory; a scaffold whose `(authed)/account` predates this unit
-        // needs them added, which the directory-level sync alone would not do
-        // (sync never overwrites or adds to a directory it already has).
-        // `acceptCarriedAgreementsAction` (the carried-cookie CONSUME side) lives
-        // in this directory's own `agreements-actions.ts`, never in
-        // `(auth)/sign-up` — see that file's header: `(auth)/**` is a sign-in
-        // seed a sign-in-less spoke drops, so a cross-directory reach from here
-        // into it would dangle.
+        // #8438 D13/D21, #8765 D7 — the agreements interstitial the layout shows
+        // a member with no current grant (`agreements-prompt.tsx`), its accept
+        // action (`agreements-actions.ts`) and the read the layout and the Inbox
+        // share (`agreements-gate.ts`). Listed because a scaffold
+        // whose `(authed)/account` predates #8438 needs them added, which the
+        // directory-level sync alone would not do (sync never overwrites or adds
+        // to a directory it already has). Both live in this directory, never in
+        // `(auth)/**` — a sign-in seed a sign-in-less spoke drops, so a
+        // cross-directory reach from here into it would dangle.
         `${ROUTE_ROOT}/(authed)/account/agreements-prompt.tsx`,
         `${ROUTE_ROOT}/(authed)/account/agreements-actions.ts`,
+        `${ROUTE_ROOT}/(authed)/account/agreements-gate.ts`,
     ],
     // #7430 — the three child routes also import files in their PARENT's
     // directory. A scaffold whose `(authed)/account` predates #7430 keeps its
@@ -923,6 +938,7 @@ export const ROUTE_DEPENDENCIES = {
     // D11 applied to Notifications' cookie-settings link.
     "(authed)/account/privacy": [
         "apps/web/lib/account-config.ts",
+        "apps/web/lib/consent-policies.ts",
         "apps/web/lib/server-api.ts",
         `${ROUTE_ROOT}/(authed)/account/account-data.ts`,
         `${ROUTE_ROOT}/(authed)/account/settings-frame.tsx`,