create-ailk 0.15.0 → 0.17.0

package/dist/spoke-checkout.js

@@ -0,0 +1,562 @@
+/**
+ * The spoke checkout slice (#7838) — what a spoke carrying `commerce` gets in
+ * `apps/web`: the buy route and the Stripe webhook route (the only two files
+ * allowed to import the checkout package, #7873), the site's own
+ * `lib/checkout-config.ts`, and the thank-you and unavailable return pages.
+ *
+ * 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.
+ *
+ * Spec: docs/specs/7838-spoke-web-checkout-slice-spec.md (D3–D7, D9).
+ *
+ * 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).
+ */
+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 { ENV_CATALOG } from "./lib/env-catalog.js";
+import { diffTwoStrings, } from "./lib/extract-module-bundle.js";
+import { substituteWorkspaceVersions, } from "./substitute.js";
+import { TopologyError } 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. */
+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([
+    "apps/web/app/[locale]/checkout/thank-you/page.tsx",
+    "apps/web/app/[locale]/checkout/unavailable/page.tsx",
+]);
+/** 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: {
+        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.`,
+        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
+ * unchanged — its test fails on an entry the monorepo's apps never read.
+ */
+export function spokeEnvRowOptions(commerce) {
+    return commerce
+        ? {
+            catalog: { ...ENV_CATALOG, ...SPOKE_CHECKOUT_ENV_CATALOG },
+            declare: SPOKE_CHECKOUT_DECLARED_ENV,
+        }
+        : { catalog: ENV_CATALOG };
+}
+/** `metadata.site` / an offering slug — 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) {
+    return SITE_PATTERN.test(site) && site !== "default";
+}
+function assertSite(site) {
+    if (!isValidSite(site)) {
+        throw new TopologyError(`spoke checkout: site stamp ${JSON.stringify(site)} must match ^[a-z0-9][a-z0-9-]{0,39}$ and must not be "default"`);
+    }
+}
+/**
+ * The site stamp for a project name (D6): lower-cased, every run outside
+ * `a-z0-9` collapsed to `-`, trimmed, cut to 40. A name that leaves nothing
+ * usable — or `default`, which is also an unset hub's own stamp — gets
+ * `site-` and the first 8 hex characters of its SHA-256. Never `AILK_SITE_ID`.
+ */
+export function spokeCheckoutSite(projectName) {
+    const slug = projectName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    if (isValidSite(slug))
+        return slug;
+    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 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. Those two are the only files allowed to 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} — GENERATED by create-ailk (#7838).`,
+        ...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.
+ */
+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`;
+}
+/**
+ * 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`. Throws `TopologyError` for an invalid stamp (SEC-7838-10).
+ */
+export function renderSpokeCheckoutFiles(site) {
+    assertSite(site);
+    const [buyPath, webhookPath] = SPOKE_CHECKOUT_ROUTE_FILES;
+    const [thankYouPath, unavailablePath] = SPOKE_CHECKOUT_PAGE_FILES;
+    return [
+        [buyPath, BUY_ROUTE],
+        [webhookPath, WEBHOOK_ROUTE],
+        [SPOKE_CHECKOUT_CONFIG_PATH, renderConfig(site)],
+        [thankYouPath, THANK_YOU_PAGE],
+        [unavailablePath, UNAVAILABLE_PAGE],
+        [SPOKE_CHECKOUT_E2E_WORKFLOW_PATH, CHECKOUT_E2E_WORKFLOW],
+    ];
+}
+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) {
+    const out = {};
+    let placed = false;
+    for (const [key, value] of Object.entries(deps)) {
+        // Code-unit order, as package managers sort — never the host's locale.
+        if (!placed && key > name) {
+            out[name] = version;
+            placed = true;
+        }
+        out[key] = value;
+    }
+    if (!placed)
+        out[name] = version;
+    return out;
+}
+/** A plain `x.y.z`, `^x.y.z` or `~x.y.z` pin's version; null for any other range. */
+function pinnedVersion(range) {
+    const match = /^[\^~]?(\d+)\.(\d+)\.(\d+)$/.exec(range.trim());
+    return match === null
+        ? null
+        : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/** True when `current` pins a version strictly older than `wanted` does. */
+function isOlderPin(current, wanted) {
+    const a = pinnedVersion(current);
+    const b = pinnedVersion(wanted);
+    if (a === null || b === null)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    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
+ * written. 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.
+ */
+export function writeSpokeCheckoutSlice(targetDir, opts) {
+    const files = renderSpokeCheckoutFiles(opts.site);
+    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 rows = [];
+    for (const [path, text] of files) {
+        const abs = join(targetDir, path);
+        if (existsSync(abs)) {
+            rows.push({ path, action: "skipped", wanted: text });
+            continue;
+        }
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, text);
+        rows.push({ path, action: "written" });
+    }
+    const deps = pkg.dependencies ?? {};
+    const current = Object.prototype.hasOwnProperty.call(deps, SPOKE_CHECKOUT_PACKAGE)
+        ? deps[SPOKE_CHECKOUT_PACKAGE]
+        : undefined;
+    if (current === undefined || isOlderPin(current, version)) {
+        pkg.dependencies =
+            current === undefined
+                ? withDependency(deps, SPOKE_CHECKOUT_PACKAGE, version)
+                : { ...deps, [SPOKE_CHECKOUT_PACKAGE]: version };
+        const after = `${JSON.stringify(pkg, null, 2)}${before.endsWith("\n") ? "\n" : ""}`;
+        writeFileSync(pkgPath, after);
+        rows.push({
+            path: WEB_PACKAGE_JSON,
+            action: "patched",
+            change: diffTwoStrings(WEB_PACKAGE_JSON, before, after, true),
+        });
+    }
+    return rows;
+}

package/dist/surfaces.js

@@ -626,6 +626,10 @@ export const ROUTE_SINCE = {
     "(authed)/account/inbox/[kind]/[id]": "0.30.0",
     "(authed)/account/settings": "0.30.0",
     "(authed)/account/support": "0.30.0",
+    // #7920 — the member file read a message's file action opens. Genuinely
+    // new, so it attaches at today's fixed-group version, the same rule #7430
+    // applied above.
+    "(authed)/account/inbox/message/[id]/file": "0.37.0",
     // The leads inbox (#5678). The ROUTE ships in every scaffold, Free
     // included — lead capture is a never-gate surface, so reading a lead back
     // is one too. Whether it shows a ROW is a separate question with two
@@ -756,6 +760,9 @@ export const ROUTE_DEPENDENCIES = {
         `${ROUTE_ROOT}/(authed)/account/error-row.tsx`,
         `${ROUTE_ROOT}/(authed)/account/retry-button.tsx`,
     ],
+    // #7920 — the member file read re-serves the hub's bytes with the
+    // credential `forwardedCookieInit` returns.
+    "(authed)/account/inbox/message/[id]/file": ["apps/web/lib/server-api.ts"],
     "(authed)/account/settings": [
         "apps/web/lib/account-config.ts",
         "apps/web/lib/auth-env.ts",

package/dist/sync-routes.js

@@ -31,9 +31,11 @@ import { tmpdir } from "node:os";
 import { basename, dirname, join, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { copyTemplate } from "./copy.js";
+import { appendEnvRows } from "./lib/declared-env.js";
+import { ENV_CATALOG } from "./lib/env-catalog.js";
 import { substituteMarkers } from "./substitute.js";
 import { GATEABLE_SURFACES, NON_ROUTE_DIRS, ROUTE_DEPENDENCIES, ROUTE_MESSAGE_NAMESPACES, ROUTE_SINCE, surfaceForRouteDir, } from "./surfaces.js";
-import { isSpokeExcluded, readSiteTopology } from "./topology.js";
+import { SPOKE_SEAM_FILES, isSpokeExcluded, readSpokeShape, } from "./topology.js";
 /** Template-relative prefix every `apps/web` route directory sits under. */
 const ROUTE_ROOT = "apps/web/app/[locale]";
 /**
@@ -99,9 +101,9 @@ function reportFor(route) {
  * byte-for-byte in, the target's copy. Non-recursive: nested directories are
  * route dirs of their own, or `__tests__`.
  */
-function isModified(expectedDir, targetDir) {
+function isModified(expectedDir, targetDir, skip = () => false) {
     for (const entry of readdirSync(expectedDir, { withFileTypes: true })) {
-        if (!entry.isFile())
+        if (!entry.isFile() || skip(entry.name))
             continue;
         const targetFile = join(targetDir, entry.name);
         if (!existsSync(targetFile))
@@ -167,10 +169,17 @@ export function syncRoutes(opts) {
     // #7426 D13 — on a spoke, a route dir the spoke does not carry (the
     // `(auth)` and `(authed)` groups) is out of scope: neither reported nor
     // copied. This is the one filter point for add-module, add-route and the
-    // sync-routes subcommand alike; a hub's scope is unchanged.
-    const spoke = readSiteTopology(targetAbs) === "spoke"
-        ? { mcp: existsSync(join(targetAbs, "apps", "mcp")) }
-        : undefined;
+    // sync-routes subcommand alike; a hub's scope is unchanged. The spoke's
+    // sign-in mode rides along (#7894 D1): a hub sign-in spoke keeps its
+    // `(authed)` account area in scope and its operator surfaces out.
+    const spoke = readSpokeShape(targetAbs);
+    // A spoke's own render of a seam, and a file it does not carry, are not
+    // "modified" (#7894 D8): the template holds the hub's.
+    const spokeSkip = (route) => (name) => {
+        const path = `${ROUTE_ROOT}/${route}/${name}`;
+        return (spoke !== undefined &&
+            (SPOKE_SEAM_FILES.includes(path) || isSpokeExcluded(path, spoke)));
+    };
     const inScope = listTemplateRouteDirs(opts.templatesDir)
         .map(reportFor)
         // "authed" (#5014): the `(authed)` route group ships unconditionally in
@@ -202,7 +211,7 @@ export function syncRoutes(opts) {
             if (!existsSync(targetRoute)) {
                 missing.push(report);
             }
-            else if (isModified(join(scratch, report.route), targetRoute)) {
+            else if (isModified(join(scratch, report.route), targetRoute, spokeSkip(report.route))) {
                 modified.push(report);
             }
         }
@@ -250,6 +259,12 @@ export function syncRoutes(opts) {
             copyDependencyFile(join(opts.templatesDir, dep), dst, markers);
             appliedDependencies.push(dep);
         }
+        // #7874 D9 — a spoke declares what the copied routes read, as the last
+        // write. A malformed env_contract block throws EnvContractError naming
+        // its line; the files copied above stay.
+        if (spoke !== undefined) {
+            appendEnvRows(targetAbs, { topology: "spoke", catalog: ENV_CATALOG });
+        }
     }
     return {
         targetDir: targetAbs,