create-ailk 0.21.0 → 0.23.0

package/dist/spoke-checkout.js

@@ -1,78 +1,82 @@
 /**
- * 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`, copied from the template tree: the site's own
+ * `lib/checkout-config.ts` (its stamp) and the thank-you and unavailable
+ * return pages with their tests (`SPOKE_CHECKOUT_TEMPLATE_PATHS`). A spoke
+ * that signs in through its hub also gets the billing action, the one file
+ * allowed to import the package besides the thank-you page, and the web seam
+ * render that reaches it (#8217 D6–D8); that action is rendered here.
+ *
+ * A spoke sells through its hub's Offerings buy route
+ * (`apps/web/app/api/offerings/checkout/[lookupKey]/route.ts`), never its own
+ * key. The legacy env-key buy route, its Stripe webhook route, `lib/checkout.ts`
+ * (the fulfilment) and the checkout e2e workflow are retired (#9142):
+ * `create-ailk sync-routes --apply` removes them from an existing spoke
+ * (`RETIRED_SPOKE_CHECKOUT_PATHS`, sync-routes.ts).
  *
  * 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.
  *
- * 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 { SPOKE_CHECKOUT_ROUTE_FILES } from "./derive-architecture.js";
+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_BILLING_ACTION_PATH } from "./derive-architecture.js";
 import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
 import { substituteWorkspaceVersions, } from "./substitute.js";
 import { TopologyError, WEB_SEAM_PATH, renderWebSeam, } from "./topology.js";
-/** The checkout package a spoke's two route files import. */
+/** The checkout package a spoke's billing action and thank-you page 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 stamp — 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. */
+/** The two return pages a commerce spoke still carries (#8748 D5). */
 export const SPOKE_CHECKOUT_PAGE_FILES = Object.freeze([
     "apps/web/app/[locale]/checkout/thank-you/page.tsx",
     "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 spoke checkout's template paths, scaffold-relative (#8748 D3). A
+ * directory entry covers every file under it, so the tests that sit beside
+ * the 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)";
-/** The variables a commerce spoke depends on (D9). The package reads three of them. */
+export const SPOKE_CHECKOUT_TEMPLATE_PATHS = Object.freeze([
+    "apps/web/app/[locale]/checkout",
+    SPOKE_CHECKOUT_CONFIG_PATH,
+]);
+/** The variables a commerce spoke depends on (D9): the package reads both. */
 export const SPOKE_CHECKOUT_ENV_CATALOG = Object.freeze({
     STRIPE_SECRET_KEY: {
-        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: a test key (sk_test_ or rk_test_), or a restricted live key the operator sets with STRIPE_MODE=live.`,
-        secret: true,
-    },
-    STRIPE_WEBHOOK_SECRET: {
-        description: `Read by ${SPOKE_CHECKOUT_PACKAGE}: the signing secret of this site's Stripe webhook endpoint.`,
+        description: `Read by ${SPOKE_CHECKOUT_PACKAGE} for the thank-you page's paid-session read and the billing reads, never to sell: a test key (sk_test_ or rk_test_), or a restricted live key the operator sets with STRIPE_MODE=live.`,
         secret: true,
     },
     STRIPE_MODE: {
         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,
-    },
 });
 /** The names a commerce spoke declares although only the package reads them (D9). */
 export const SPOKE_CHECKOUT_DECLARED_ENV = Object.freeze([
     "STRIPE_SECRET_KEY",
-    "STRIPE_WEBHOOK_SECRET",
     "STRIPE_MODE",
 ]);
 /**
  * The catalog (and declared names) a spoke's `appendEnvRows` call passes: a
- * commerce spoke adds the checkout's four rows (D9). `ENV_CATALOG` itself is
+ * commerce spoke adds the package's two rows (D9). `ENV_CATALOG` itself is
  * unchanged — its test fails on an entry the monorepo's apps never read.
  */
 export function spokeEnvRowOptions(commerce) {
@@ -83,7 +87,7 @@ export function spokeEnvRowOptions(commerce) {
         }
         : { catalog: ENV_CATALOG };
 }
-/** `metadata.site` / an offering slug — the package's own pattern. */
+/** `metadata.site` — the package's own pattern. */
 const SITE_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** A stamp a renderer may interpolate: the package's pattern, never `default` (D6). */
 function isValidSite(site) {
@@ -112,42 +116,17 @@ 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 billing action's first line, which marks the file as create-ailk's to rewrite. */
+export const BILLING_ACTION_MARKER = "// The spoke billing action — GENERATED by create-ailk (#8217). Do not edit:";
 /**
  * The spoke billing action (#8217 D6): wiring only, byte-identical across
  * sites, so every guarantee arrives by a package bump. A plain server module
  * (C2): its two exports take no argument, and the hub's read is its only
- * source of customer ids.
+ * source of customer ids. It builds its config from the site's stamp and the
+ * site's own origin (#9142: no longer from `lib/checkout.ts`).
  */
-const BILLING_ACTION = [
-    "// The spoke billing action — GENERATED by create-ailk (#8217). Do not edit:",
+export const BILLING_ACTION = [
+    BILLING_ACTION_MARKER,
     "// every guarantee lives in the spoke-checkout package and arrives by a",
     "// package bump. A plain server module, not a Server Action file: neither",
     "// export takes an argument, and the hub's GET /v1/member/billing is the only",
@@ -158,366 +137,74 @@ const BILLING_ACTION = [
     "",
     `import { checkoutConfig } from "../../../../../lib/checkout-config";`,
     `import { forwardedCookieInit } from "../../../../../lib/server-api";`,
+    `import { resolveBaseUrl } from "../../../../../src/lib/routes";`,
     "",
-    "const billing = createSpokeCheckout(checkoutConfig).billing.forMember(",
-    "  async () => member.billing(await forwardedCookieInit()),",
-    ");",
+    "const billing = createSpokeCheckout({",
+    "  site: checkoutConfig.site,",
+    "  siteBaseUrl: resolveBaseUrl(),",
+    "}).billing.forMember(async () => member.billing(await forwardedCookieInit()));",
     "",
     "export const readSpokeBilling = billing.read;",
     "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";
 /**
- * The Stripe CLI release the workflow installs, and the SHA-256 of its
- * `stripe_<v>_linux_x86_64.tar.gz` from that release's own
- * `stripe-linux-checksums.txt`. Never bump one without re-reading the other.
+ * The rendered part of the slice for `site` (#8748 D3): with `signIn: "hub"`
+ * the billing action (#8217 D8), else nothing. It does not depend on `site`.
+ * The rest of the slice is template source, copied by
+ * `writeSpokeCheckoutSlice`. Throws `TopologyError` for an invalid stamp
+ * (SEC-7838-10).
  */
-export const STRIPE_CLI_VERSION = "1.51.1";
-export const STRIPE_CLI_LINUX_X64_SHA256 = "38c8de73a8cab810a4aab8a4015cd4e3398b7b87aa42b6944d09d89ed524ac53";
-/** The Playwright the workflow installs — the monorepo's own pinned version. */
-export const E2E_PLAYWRIGHT_VERSION = "1.61.1";
-/**
- * Every action the workflow uses, pinned to the commit its `v4` tag named
- * when this was written (SEC-7839-2): `gh api repos/<action>/commits/v4`.
- */
-export const E2E_ACTION_PINS = Object.freeze({
-    "actions/checkout": "11d5960a326750d5838078e36cf38b85af677262",
-    "pnpm/action-setup": "b906affcce14559ad1aafd4ab0e942779e9f58b1",
-    "actions/setup-node": "49933ea5288caeca8642d1e84afbd3f7d6820020",
-    "actions/upload-artifact": "ea165f8d65b6e75b540449e92b4886f43607fa02",
-});
-function uses(action) {
-    return `uses: ${action}@${E2E_ACTION_PINS[action]} # v4`;
+export function renderSpokeCheckoutFiles(site, opts = {}) {
+    assertSite(site);
+    return opts.signIn === "hub" ? [[SPOKE_BILLING_ACTION_PATH, BILLING_ACTION]] : [];
 }
+/** The one line of the template's config the writer stamps (#8748 D2). */
+const SITE_LINE = /^const SITE = "[a-z0-9-]+";$/gm;
 /**
- * The workflow text (D8). Identical for every spoke at one create-ailk
- * version. Every `${{ … }}` sits in an env-style value, never in a script.
- */
-export const CHECKOUT_E2E_WORKFLOW = `# Checkout e2e — GENERATED by create-ailk (#7839). Do not edit: it changes
-# with the ${SPOKE_CHECKOUT_PACKAGE} command it runs.
-#
-# Pays each named offering once through Stripe's hosted Checkout in TEST
-# mode, then checks Stripe's webhook was answered 2xx and this site's
-# fulfilment ran. Start it by hand (Actions > Checkout e2e > Run workflow)
-# after a checkout change and before any live flip. It never runs on a push
-# or a pull request: it needs the network, the Stripe CLI and test-mode state.
-#
-# Setup, once: create the GitHub Environment "checkout-e2e", limit its
-# deployment branches to the default branch, and add to it the secrets
-# STRIPE_TEST_SECRET_KEY (an sk_test_ or rk_test_ key) and AILK_SPOKE_KEY,
-# and the variable AILK_API_URL (https). Each paid session posts one
-# test-mode lead to the hub. Test subscriptions it creates are cancelled.
-name: Checkout e2e
-
-on:
-  workflow_dispatch:
-    inputs:
-      offerings:
-        description: Comma-separated fixed offering slugs from apps/web/lib/checkout-config.ts
-        required: true
-        type: string
-
-permissions:
-  contents: read
-
-concurrency:
-  group: checkout-e2e
-  cancel-in-progress: false
-
-jobs:
-  checkout-e2e:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    environment: checkout-e2e
-    env:
-      NEXT_PUBLIC_BASE_URL: http://localhost:3000
-      STRIPE_MODE: test
-    steps:
-      - name: Refuse a live key or a missing setting
-        env:
-          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
-          AILK_SPOKE_KEY: \${{ secrets.AILK_SPOKE_KEY }}
-          AILK_API_URL: \${{ vars.AILK_API_URL }}
-        run: |
-          case "$STRIPE_SECRET_KEY" in
-            sk_test_*|rk_test_*) ;;
-            *) echo "::error::STRIPE_TEST_SECRET_KEY must be an sk_test_ or rk_test_ key"; exit 2 ;;
-          esac
-          if [ -z "$AILK_SPOKE_KEY" ]; then
-            echo "::error::set the AILK_SPOKE_KEY secret in the checkout-e2e environment"; exit 2
-          fi
-          case "$AILK_API_URL" in
-            https://*) ;;
-            *) echo "::error::AILK_API_URL must be the hub's https origin"; exit 2 ;;
-          esac
-
-      - ${uses("actions/checkout")}
-
-      - ${uses("pnpm/action-setup")}
-
-      - run: test -f pnpm-lock.yaml || touch pnpm-lock.yaml
-
-      - ${uses("actions/setup-node")}
-        with:
-          node-version: 20
-          cache: pnpm
-          cache-dependency-path: pnpm-lock.yaml
-
-      - name: Install
-        run: |
-          if [ -s pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; else pnpm install; fi
-
-      - name: Install the Stripe CLI (pinned, checksum-checked)
-        run: |
-          curl -fsSL -o "$RUNNER_TEMP/stripe.tar.gz" \\
-            https://github.com/stripe/stripe-cli/releases/download/v${STRIPE_CLI_VERSION}/stripe_${STRIPE_CLI_VERSION}_linux_x86_64.tar.gz
-          echo "${STRIPE_CLI_LINUX_X64_SHA256}  $RUNNER_TEMP/stripe.tar.gz" | sha256sum -c -
-          mkdir -p "$RUNNER_TEMP/stripe-cli"
-          tar -xzf "$RUNNER_TEMP/stripe.tar.gz" -C "$RUNNER_TEMP/stripe-cli" stripe
-
-      - name: Install Playwright (pinned) and Chromium
-        run: |
-          npm install --no-save --ignore-scripts --prefix "$RUNNER_TEMP/e2e-deps" playwright@${E2E_PLAYWRIGHT_VERSION}
-          "$RUNNER_TEMP/e2e-deps/node_modules/.bin/playwright" install --with-deps chromium
-
-      - name: Fetch the Stripe CLI's signing secret
-        env:
-          STRIPE_API_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
-        run: |
-          umask 077
-          secret="$("$RUNNER_TEMP/stripe-cli/stripe" listen --print-secret)"
-          echo "::add-mask::$secret"
-          printf '%s' "$secret" > "$RUNNER_TEMP/stripe-whsec"
-
-      - name: Build the site
-        run: pnpm --filter ./apps/web build
-
-      - name: Start the site
-        env:
-          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
-          AILK_SPOKE_KEY: \${{ secrets.AILK_SPOKE_KEY }}
-          AILK_API_URL: \${{ vars.AILK_API_URL }}
-        run: |
-          STRIPE_WEBHOOK_SECRET="$(cat "$RUNNER_TEMP/stripe-whsec")"
-          export STRIPE_WEBHOOK_SECRET
-          cd apps/web
-          nohup pnpm exec next start -p 3000 -H localhost > "$RUNNER_TEMP/next.log" 2>&1 &
-          echo $! > "$RUNNER_TEMP/next.pid"
-          for _ in $(seq 1 60); do
-            curl -fsS -o /dev/null http://localhost:3000/checkout/thank-you && exit 0
-            sleep 2
-          done
-          echo "::error::the site did not start on localhost:3000; run it locally with the same settings to see why"
-          exit 1
-
-      - name: Pay each offering
-        working-directory: apps/web
-        env:
-          STRIPE_SECRET_KEY: \${{ secrets.STRIPE_TEST_SECRET_KEY }}
-          OFFERINGS: \${{ inputs.offerings }}
-          SPOKE_CHECKOUT_E2E_DEPS: \${{ runner.temp }}/e2e-deps
-          STRIPE_CLI_PATH: \${{ runner.temp }}/stripe-cli/stripe
-        run: |
-          STRIPE_WEBHOOK_SECRET="$(cat "$RUNNER_TEMP/stripe-whsec")"
-          export STRIPE_WEBHOOK_SECRET
-          pnpm exec spoke-checkout-e2e --base-url http://localhost:3000 --offerings "$OFFERINGS" --out "$RUNNER_TEMP/checkout-e2e"
-
-      - name: Stop the site
-        if: always()
-        run: |
-          if [ -f "$RUNNER_TEMP/next.pid" ]; then pkill -P "$(cat "$RUNNER_TEMP/next.pid")" || true; kill "$(cat "$RUNNER_TEMP/next.pid")" || true; fi
-          rm -f "$RUNNER_TEMP/stripe-whsec"
-
-      - name: Keep the report
-        if: always()
-        ${uses("actions/upload-artifact")}
-        with:
-          name: checkout-e2e
-          path: \${{ runner.temp }}/checkout-e2e
-          if-no-files-found: ignore
-          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).
+ * 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.
  */
-export function renderSpokeCheckoutFiles(site, opts = {}) {
-    assertSite(site);
-    const [buyPath, webhookPath, billingActionPath] = SPOKE_CHECKOUT_ROUTE_FILES;
-    const [thankYouPath, unavailablePath] = SPOKE_CHECKOUT_PAGE_FILES;
-    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],
-    ];
+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. */
@@ -556,28 +243,79 @@ 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 rendered billing action
+ * calls the package's current `createSpokeCheckout` shape, which an older
+ * pin does not take (#9142). 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 (existsSync(abs)) {
+        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 (lstatExists(abs)) {
             rows.push({ path, action: "skipped", wanted: text });
             continue;
         }
@@ -617,3 +355,43 @@ 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" : ""}`);
+}
+// ── #9142 — the retired legacy env-key checkout ─────────────────────────────
+/**
+ * What the legacy env-key checkout left in a spoke, scaffold-relative: the
+ * buy route and the Stripe webhook route (a directory entry covers the tests
+ * beside each), `lib/checkout.ts` (the fulfilment) and its test. Each was a
+ * template copy create-ailk recorded in `.ailk-template-files.json`;
+ * `create-ailk sync-routes --apply` removes the ones still byte-identical to
+ * that record.
+ */
+export const RETIRED_SPOKE_CHECKOUT_PATHS = Object.freeze([
+    "apps/web/app/api/checkout",
+    "apps/web/app/api/webhooks/stripe",
+    "apps/web/lib/checkout.ts",
+    "apps/web/lib/__tests__/checkout.test.ts",
+]);
+/** The retired checkout e2e workflow — rendered, never recorded (#7839 D8). */
+export const RETIRED_CHECKOUT_E2E_WORKFLOW_PATH = ".github/workflows/checkout-e2e.yml";
+/** The workflow's first line, which marks it as create-ailk's to remove. */
+export const RETIRED_CHECKOUT_E2E_MARKER = "# Checkout e2e — GENERATED by create-ailk (#7839). Do not edit: it changes";