@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/middleware.ts

@@ -0,0 +1,379 @@
+import { NextResponse } from 'next/server';
+import type { NextRequest } from 'next/server';
+import { uuidv7 } from 'uuidv7';
+
+import {
+  hasServerAuthoredHeaders,
+  localeRequestHeaders,
+  planLocaleRewrite,
+} from './lib/locale/middleware-plan';
+import type { LocaleRewritePlan } from './lib/locale/middleware-plan';
+import { planRedirect } from './lib/seo/redirect-plan';
+import { REDIRECTS } from './seo/redirects';
+
+/**
+ * Visitor-identity + forced-experiment-entry + locale-rewrite middleware
+ * (design doc S6 + F-B; locale stage = epic launch#54 W1-8 / S1).
+ *
+ * S6 — visitor identity. Mints the durable anonymous visitor key — the
+ * `forgecart-visitor` cookie (UUIDv7, so ids sort by first-touch time) —
+ * exactly once per browser. It is the A/B-test subject key and a
+ * marketing-event property; it is deliberately NOT a session and NOT a
+ * marketing identity.
+ *
+ * Contract:
+ *  - Mint ONLY when the cookie is absent. An identified visitor's response
+ *    carries NO `Set-Cookie` at all — re-sending it on every response would
+ *    make every page uncacheable for shared caches.
+ *  - The key is DUAL-HOMED (#1079 P1, deliberate posture change): the
+ *    canonical `forgecart-visitor` cookie stays httpOnly (server reads:
+ *    `getVariant()`'s assignment, header forwarding), and a byte-identical
+ *    NON-httpOnly mirror `forgecart-visitor-client` (the
+ *    `forgecart-session-client` pattern) exposes it to browser JS so the
+ *    SDK can send it in WS connection params — visitor-subject goal events
+ *    are unattributable without it. The id is a UUIDv7, not a secret, and
+ *    the httpOnly original stays authoritative: a missing or tampered
+ *    mirror is re-synced FROM it (one extra `Set-Cookie` response per
+ *    legacy visitor, then the steady state is Set-Cookie-free again).
+ *  - Zero fetches, zero environment reads: the workspace-pod prewarm boots
+ *    this dev server with no `.env`, and the middleware must be inert
+ *    to that (it never crashes a request, env or not).
+ *  - Harmless on `<Link>` prefetches: they carry cookies like any navigation,
+ *    so an identified visitor's prefetch passes straight through; page-view
+ *    EMISSION stays in the client tracker precisely because prefetches reach
+ *    middleware (design doc §H.1) — this file only persists the id.
+ *  - Infra routes are excluded via the matcher: `/ping` (the pod readiness
+ *    probe polls it forever — it must stay zero-overhead and byte-stable) and
+ *    `/__forge_beacon` (error beacon; a browser that reaches it already has
+ *    the cookie from the page), plus Next static internals.
+ *
+ * F-B — forced campaign entry. Campaign URLs carry
+ * `?fc-exp=<experimentKey>:<variantKey>[,<experimentKey>:<variantKey>…]`
+ * (at most {@link FORCED_URL_ENTRY_CAP} entries; both sides must match the
+ * backend's slug grammar). Valid entries MERGE into the `forgecart-exp-force`
+ * cookie — a JSON map `{ experimentKey: variantKey }`, httpOnly (server-read
+ * only), 30 days — and the request continues WITHOUT a redirect, so the
+ * campaign link stays shareable (the leak is the point). Whether a forced key
+ * actually overrides the hash is decided downstream by the assignment engine
+ * (`allowForcedEntry` + variant existence) — the middleware only persists.
+ *
+ * The merged map is ALSO written back onto this request's own `cookie` header
+ * (`NextResponse.next({ request })`), so the landing render itself already
+ * sees the forced variant — Set-Cookie alone would only reach the NEXT
+ * request. `getVariant()` still never relies on middleware→RSC cookie
+ * propagation for the VISITOR id (it reads-else-mints within a
+ * request-scoped cache); the forced map is different: it either rode in on
+ * the request cookie or is deterministically rewritten here.
+ *
+ * S1 — locale rewrite. `/<xx>/<rest>` is rewritten to `/<rest>`, with the
+ * locale carried forward on the request as `x-forgecart-locale` and announced
+ * on the response as `Content-Language`. The route tree therefore stays FLAT:
+ * no `[locale]` segment, no root catch-all (#1041 law).
+ *
+ * The locale DECISION is not here — it is `planLocaleRewrite`, a pure module
+ * the template spec project pins. This file imports `next/server`, so nothing
+ * in it can be reached by that project; the locale stage therefore keeps no
+ * decision of its own and only maps the two plan cases onto Next responses.
+ * (The F-B parsing and merging below predate that split and are still
+ * unpinned — they are covered, like the rest of this file's runtime
+ * behaviour, only by the storefront-verify phases.)
+ *
+ * Three properties of this stage are load-bearing:
+ *
+ *  - It obeys the same zero-fetch / zero-env contract as the rest of this
+ *    file. A two-letter first segment is only a CANDIDATE here; whether the
+ *    channel offers it is decided in the layout's request-time hole, the only
+ *    place that can ask. Validating here would require a fetch, and a fetch in
+ *    middleware is exactly what the prewarm boot cannot afford.
+ *  - It runs BEFORE, and independently of, the cookie fast path below. A
+ *    rewrite is not cookie work: an already-identified visitor carrying no
+ *    forced entry does no cookie work at all, so a locale stage placed inside
+ *    that branch would render the DEFAULT language for every prefixed URL a
+ *    returning visitor opens.
+ *  - It is the only place `Content-Language` can be set at all. No RSC API
+ *    lets a layout or page write a response header, so this is the single
+ *    emitter by necessity rather than by policy — and nothing downstream may
+ *    add a second, which would produce two header lines.
+ *
+ *    Two consequences are accepted deliberately. It labels the CANDIDATE,
+ *    because validity is not knowable here: `/zz/x` carries
+ *    `Content-Language: zz` on the 404 the layout then raises, and
+ *    `/en/x` carries `Content-Language: en` on its 308. Both are inert — a
+ *    crawler drops a 404 rather than indexing its language, and a 308 has no
+ *    body to describe. And the UNPREFIXED default-language response carries no
+ *    header at all, since this stage cannot know the channel's default without
+ *    a fetch. The layout announces that one as `<html lang>`, which is the
+ *    signal search engines actually consume for language; the header is the
+ *    weaker of the two and is required here only for the prefixed case.
+ *
+ * Store-wide routes are protected from the locale stage by `planLocaleRewrite`,
+ * not by the matcher. The matcher below excludes only `_next/static`,
+ * `_next/image`, `favicon.ico`, `ping` and `__forge_beacon`, and only in their
+ * UNPREFIXED spelling — its negative lookahead is anchored at the start of the
+ * path, so `/de/ping` reaches this file even though `/ping` does not.
+ * `sitemap.xml`, `robots.txt`, `api` and `__fc` are not excluded at all and run
+ * through this middleware in every spelling. What keeps every one of them
+ * unrewritten is the planner's `pass`, whose list is the grammar's.
+ */
+
+const VISITOR_COOKIE_NAME = 'forgecart-visitor';
+
+/**
+ * Browser-readable mirror of {@link VISITOR_COOKIE_NAME} (#1079 P1) — same
+ * value, same lifetime, NOT httpOnly. Read by the shop-session SDK
+ * bootstrap and sent as the `forgecart-visitor` WS connection-params
+ * header. Never read server-side: the httpOnly original is authoritative.
+ */
+const VISITOR_MIRROR_COOKIE_NAME = 'forgecart-visitor-client';
+
+/** 400 days — Chrome's upper bound on cookie lifetime (RFC 6265bis). */
+const VISITOR_COOKIE_MAX_AGE_SECONDS = 400 * 24 * 60 * 60;
+
+/** Forced-entry URL param + cookie (design doc F-B). */
+const FORCED_ENTRY_PARAM = 'fc-exp';
+const FORCED_ENTRY_COOKIE_NAME = 'forgecart-exp-force';
+
+/** 30 days — the campaign-entry window the design doc fixes. */
+const FORCED_ENTRY_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+
+/** At most this many `exp:variant` entries are honored per URL (design doc). */
+const FORCED_URL_ENTRY_CAP = 3;
+
+/**
+ * At most this many experiments are retained in the merged cookie (oldest
+ * evicted first). At the slug grammar's 64-char ceiling per side that keeps
+ * the serialized JSON well under the 4096-byte browser cookie cap, so a
+ * hostile chain of campaign URLs can never grow the header unboundedly.
+ */
+const FORCED_COOKIE_ENTRY_CAP = 12;
+
+/**
+ * The backend's experiment/variant slug grammar
+ * (`ExperimentService`'s SLUG_REGEX) — both sides of every `exp:variant`
+ * entry must match it or the entry is dropped.
+ */
+const SLUG_REGEX = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+
+/**
+ * Parse the raw `?fc-exp=` value into at most {@link FORCED_URL_ENTRY_CAP}
+ * slug-valid `experimentKey → variantKey` entries (later duplicates of the
+ * same experiment win; invalid entries are dropped silently — a mangled
+ * campaign URL must still serve the page). `null` when nothing valid remains.
+ */
+function parseForcedEntryParam(raw: string | null): Map<string, string> | null {
+  if (!raw) return null;
+  const entries = new Map<string, string>();
+  for (const item of raw.split(',')) {
+    const separatorAt = item.indexOf(':');
+    if (separatorAt === -1) continue;
+    const experimentKey = item.slice(0, separatorAt);
+    const variantKey = item.slice(separatorAt + 1);
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    if (!entries.has(experimentKey) && entries.size >= FORCED_URL_ENTRY_CAP) continue;
+    entries.set(experimentKey, variantKey);
+  }
+  return entries.size > 0 ? entries : null;
+}
+
+/**
+ * Read the existing `forgecart-exp-force` cookie into slug-valid entries.
+ * Malformed JSON / shapes are discarded wholesale — the cookie is
+ * client-tamperable, and the next valid campaign URL rewrites it anyway.
+ */
+function readForcedEntryCookie(request: NextRequest): Map<string, string> {
+  const entries = new Map<string, string>();
+  const raw = request.cookies.get(FORCED_ENTRY_COOKIE_NAME)?.value;
+  if (!raw) return entries;
+  let parsed: unknown;
+  try {
+    // `request.cookies` already percent-decodes — `raw` is the JSON text.
+    parsed = JSON.parse(raw);
+  } catch {
+    return entries;
+  }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return entries;
+  for (const [experimentKey, variantKey] of Object.entries(parsed)) {
+    if (typeof variantKey !== 'string') continue;
+    if (!SLUG_REGEX.test(experimentKey) || !SLUG_REGEX.test(variantKey)) continue;
+    entries.set(experimentKey, variantKey);
+  }
+  return entries;
+}
+
+/**
+ * Merge URL entries over the stored map (URL wins; re-set keys move to the
+ * newest position) and evict oldest entries past {@link FORCED_COOKIE_ENTRY_CAP}.
+ * Returns the cookie-ready serialized value, or `null` when the URL carried
+ * no valid entry (the common case — zero cookie work on normal traffic).
+ */
+function mergeForcedEntries(request: NextRequest): string | null {
+  const fromUrl = parseForcedEntryParam(request.nextUrl.searchParams.get(FORCED_ENTRY_PARAM));
+  if (!fromUrl) return null;
+  const merged = readForcedEntryCookie(request);
+  for (const [experimentKey, variantKey] of fromUrl) {
+    merged.delete(experimentKey);
+    merged.set(experimentKey, variantKey);
+  }
+  while (merged.size > FORCED_COOKIE_ENTRY_CAP) {
+    const oldest = merged.keys().next().value;
+    if (oldest === undefined) break;
+    merged.delete(oldest);
+  }
+  // RAW JSON on purpose: Next's cookie APIs percent-encode on serialize and
+  // decode on parse — symmetrically for the response Set-Cookie AND the
+  // request-header rewrite below — so pre-encoding here would double-encode.
+  return JSON.stringify(Object.fromEntries(merged));
+}
+
+/**
+ * The response the cookie steps decorate — one per plan case.
+ *
+ * A `pass` keeps the untouched `NextResponse.next()` whenever it can, and that
+ * is a deliberate budget decision rather than a leftover: passing
+ * `{ request: { headers } }` makes Next copy the ENTIRE inbound header block
+ * into `x-middleware-request-*` on the middleware→server hop, against Node's
+ * 16 KB default. This matcher covers `/api/*`, `_next/data`, `sitemap.xml` and
+ * every RSC prefetch, so paying that on all of them — to sanitize the few
+ * requests that actually arrive forged — would be a poor trade. The mutated
+ * path is taken only when there is something to say or something to strip.
+ *
+ * Headers are cloned AFTER any forced-entry cookie rewrite, so a rewritten
+ * request carries the merged cookie header too — the landing render in a
+ * prefixed locale must still see its forced variant. The query string survives
+ * because `nextUrl.clone()` carries it and only `pathname` is reassigned.
+ */
+function buildBaseResponse(
+  request: NextRequest,
+  plan: LocaleRewritePlan,
+  requestHeadersMutated: boolean,
+): NextResponse {
+  if (plan.kind === 'pass') {
+    if (!requestHeadersMutated && !hasServerAuthoredHeaders(request.headers)) {
+      return NextResponse.next();
+    }
+    const headers = localeRequestHeaders(request.headers, plan, request.nextUrl.search);
+    return NextResponse.next({ request: { headers } });
+  }
+
+  const url = request.nextUrl.clone();
+  url.pathname = plan.routePath;
+  const headers = localeRequestHeaders(request.headers, plan, request.nextUrl.search);
+  const response = NextResponse.rewrite(url, { request: { headers } });
+  response.headers.set('Content-Language', plan.locale);
+  return response;
+}
+
+export function middleware(request: NextRequest): NextResponse {
+  // W1-9 — rename redirects, BEFORE everything else. A retired URL is not a
+  // page of this site any more, so nothing downstream should spend work on it:
+  // not the locale rewrite (the destination gets its own pass), not the cookie
+  // stages (the browser follows the 308 and is identified on the hop that
+  // actually renders). The query string rides along, so a campaign link's
+  // `?fc-exp=` survives a rename.
+  //
+  // The table is a SOURCE file (`src/seo/redirects.ts`) rather than
+  // `next.config.js`'s `redirects()` because that one is read once at boot: an
+  // entry added there does nothing until the server restarts, which in a
+  // workspace pod means the merchant watches their rename not work.
+  const redirectTo = planRedirect(request.nextUrl.pathname, REDIRECTS);
+  if (redirectTo !== null) {
+    const destination = request.nextUrl.clone();
+    destination.pathname = redirectTo;
+    return NextResponse.redirect(destination, 308);
+  }
+
+  // Then the locale plan — outside the cookie fast path below, because it is
+  // not cookie work. An identified visitor with no forced entry does no cookie
+  // work at all, so a locale stage inside that branch would serve the default
+  // language for every prefixed URL a returning visitor opens.
+  const plan = planLocaleRewrite(request.nextUrl.pathname);
+  const forcedEntryValue = mergeForcedEntries(request);
+  const storedVisitorId = request.cookies.get(VISITOR_COOKIE_NAME)?.value;
+  const mintVisitor = !storedVisitorId;
+  // Mirror sync (#1079 P1): absent on every pre-mirror visitor's first
+  // request back, and re-synced whenever it disagrees with the httpOnly
+  // original (client JS can rewrite it — the original is authoritative).
+  // `mintVisitor` implies a sync: a fresh id is written to BOTH homes.
+  const syncMirror =
+    mintVisitor || request.cookies.get(VISITOR_MIRROR_COOKIE_NAME)?.value !== storedVisitorId;
+  // The steady-state fast path: an identified visitor on an unprefixed URL with
+  // no campaign parameter needs no request-header override at all, and skipping
+  // it avoids Next copying the entire inbound header block into
+  // `x-middleware-request-*` on every such request.
+  //
+  // `hasServerAuthoredHeaders` MUST be part of this condition, not only of
+  // `buildBaseResponse`. A bare `NextResponse.next()` emits no
+  // `x-middleware-override-headers`, and Next deletes non-overridden inbound
+  // request headers ONLY under that header — so returning early here would let a
+  // forged `x-forgecart-locale` survive into the render on the exact path most
+  // real traffic takes (every returning browser: visitor cookie present and its
+  // mirror in agreement). A forged request instead falls through to
+  // `buildBaseResponse`, which strips the server-authored names and re-emits.
+  if (
+    plan.kind === 'pass' &&
+    !forcedEntryValue &&
+    !syncMirror &&
+    !hasServerAuthoredHeaders(request.headers)
+  ) {
+    return NextResponse.next();
+  }
+
+  if (forcedEntryValue) {
+    // Rewrite this request's own cookie header so the landing render already
+    // resolves the forced variant (Set-Cookie alone reaches only the NEXT
+    // request), then persist for subsequent navigations. The forced-entry
+    // stage itself never redirects — the campaign URL stays shareable — and
+    // when the locale stage does canonicalize one, the query string rides
+    // along, so the entry survives the hop either way.
+    request.cookies.set(FORCED_ENTRY_COOKIE_NAME, forcedEntryValue);
+  }
+
+  const response = buildBaseResponse(request, plan, forcedEntryValue !== null);
+
+  if (forcedEntryValue) {
+    response.cookies.set({
+      name: FORCED_ENTRY_COOKIE_NAME,
+      value: forcedEntryValue,
+      httpOnly: true,
+      secure: true,
+      sameSite: 'lax',
+      maxAge: FORCED_ENTRY_COOKIE_MAX_AGE_SECONDS,
+      path: '/',
+    });
+  }
+
+  if (syncMirror) {
+    const visitorId = storedVisitorId ?? uuidv7();
+    if (mintVisitor) {
+      // `secure` is honored on https (deployed storefronts) and on localhost;
+      // browsers may drop it on other plain-http dev hosts — acceptable, since a
+      // stable visitor identity is a production concern, not a preview one.
+      response.cookies.set({
+        name: VISITOR_COOKIE_NAME,
+        value: visitorId,
+        httpOnly: true,
+        secure: true,
+        sameSite: 'lax',
+        maxAge: VISITOR_COOKIE_MAX_AGE_SECONDS,
+        path: '/',
+      });
+    }
+    // Deliberately NOT httpOnly — see VISITOR_MIRROR_COOKIE_NAME.
+    response.cookies.set({
+      name: VISITOR_MIRROR_COOKIE_NAME,
+      value: visitorId,
+      httpOnly: false,
+      secure: true,
+      sameSite: 'lax',
+      maxAge: VISITOR_COOKIE_MAX_AGE_SECONDS,
+      path: '/',
+    });
+  }
+  return response;
+}
+
+export const config = {
+  // Every page and route EXCEPT Next internals/static assets and the infra
+  // routes documented above.
+  matcher: ['/((?!_next/static|_next/image|favicon.ico|ping|__forge_beacon).*)'],
+};

package/templates/storefront-shadcn/src/seo/redirects.ts

@@ -0,0 +1,44 @@
+/**
+ * Rename redirects — the one file you edit when a page moves.
+ *
+ * When a page's URL changes, the old address does not stop existing: it is in
+ * search results, in links other people wrote, and in browser history. Left to
+ * 404 it loses everything the old URL had earned. A 308 hands that across to
+ * the new address instead.
+ *
+ * Add an entry and save. The dev server picks it up immediately, so the
+ * redirect is live in the same session — which is exactly why this is a source
+ * file and not `next.config.js`'s `redirects()`: that one is read once at boot,
+ * so an entry added there does nothing until the server restarts.
+ *
+ *     export const REDIRECTS: readonly RedirectRule[] = [
+ *       { from: '/summer-sale', to: '/promotions/summer' },
+ *     ];
+ *
+ * Three things to know, all enforced in `lib/seo/redirect-plan.ts`:
+ *
+ *  - **Paths are written WITHOUT a language prefix.** `/summer-sale` covers
+ *    `/de/summer-sale` too, and each redirects inside its own language. Writing
+ *    `/de/summer-sale` here would cover only German — and the language you
+ *    forgot would keep 404ing, silently.
+ *  - **Matching is exact.** `/summer-sale` does not match `/summer-sale/tents`
+ *    or `/summer-sale-2024`. Each moved page gets its own entry, because a
+ *    prefix rule would drag URLs you never meant to move.
+ *  - **Chains collapse and cycles are refused.** `/a → /b → /c` answers ONE
+ *    308 straight to `/c`, since every extra hop weakens the signal a crawler
+ *    carries across. A cycle redirects nowhere at all rather than trapping a
+ *    browser in a loop.
+ */
+
+/** One moved page: an old address and the address that replaced it. */
+export interface RedirectRule {
+  /** The retired path, unprefixed and rooted — e.g. `/summer-sale`. */
+  from: string;
+  /** Where it lives now, unprefixed and rooted — e.g. `/promotions/summer`. */
+  to: string;
+}
+
+/**
+ * The table. Empty in a fresh scaffold — nothing has been renamed yet.
+ */
+export const REDIRECTS: readonly RedirectRule[] = [];

package/templates/storefront-shadcn/src/server/app.module.ts

@@ -0,0 +1,18 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { CustomerExtrasModule } from './customer-extras/customer-extras.module';
+import { ForgeCartModule } from './forgecart/forgecart.module';
+
+/**
+ * Root of the storefront's embedded NestJS backend.
+ *
+ * `bootstrap.ts` boots this module as an APPLICATION CONTEXT — the module
+ * system, DI container, and lifecycle only; Next.js keeps owning HTTP — and
+ * scans it for `@BackendMethod()` methods, which become the `sdk.backend`
+ * surface. Every domain module registers here; a module that is not
+ * imported does not exist to the scan.
+ */
+@Module({ imports: [ForgeCartModule, CustomerExtrasModule] })
+export class AppModule {}

package/templates/storefront-shadcn/src/server/backend-api.ts

@@ -0,0 +1,26 @@
+import 'server-only';
+
+import type {
+  AssignCustomerHashInput,
+  AssignCustomerHashResult,
+} from './customer-extras/type/customer-extras.types';
+
+/**
+ * The compile-time surface of the backend gate — the typed twin of the
+ * runtime `@BackendMethod()` scan.
+ *
+ * `lib/backend-client.ts` types the `sdk.backend` proxy from this interface
+ * (a type-only import, so nothing here reaches the client bundle), and
+ * `bootstrap.ts` validates at boot that the decorator scan discovered
+ * EXACTLY the names below — a mismatch in either direction fails the boot
+ * with a message naming the drifted method.
+ *
+ * Adding a method = the decorated service method + one signature here (+
+ * the name in the list below). See the `backend-feature-authoring` recipe.
+ */
+export interface BackendApi {
+  assignCustomerHash: (input: AssignCustomerHashInput) => Promise<AssignCustomerHashResult>;
+}
+
+/** The declared names, for the boot-time drift check against the scan. */
+export const BACKEND_API_METHOD_NAMES: readonly (keyof BackendApi)[] = ['assignCustomerHash'];

package/templates/storefront-shadcn/src/server/backend-method.decorator.ts

@@ -0,0 +1,23 @@
+import 'server-only';
+
+import { SetMetadata, type CustomDecorator } from '@nestjs/common';
+
+/** Metadata key marking a service method as browser-invocable via `sdk.backend`. */
+export const BACKEND_METHOD_KEY = 'forgecart:backend-method';
+
+/**
+ * Opt a service method into the `sdk.backend` gate.
+ *
+ * The decorator IS the allowlist: the bootstrap scan exposes decorated
+ * methods and nothing else, so a method becomes browser-callable only by
+ * carrying this marker (plus its line in `backend-api.ts` — the boot-time
+ * drift check keeps the two in lock-step). Method names must be unique
+ * across ALL services; a duplicate fails the boot loudly.
+ *
+ * A decorated method runs shopper-invocable with the ADMIN client available
+ * in its session — the method body owns the decision of what that authority
+ * may be used for, and must treat its `input` as untrusted data.
+ */
+export function BackendMethod(): CustomDecorator<string> {
+  return SetMetadata(BACKEND_METHOD_KEY, true);
+}

package/templates/storefront-shadcn/src/server/bootstrap.ts

@@ -0,0 +1,122 @@
+import 'server-only';
+import 'reflect-metadata';
+
+import type { INestApplicationContext } from '@nestjs/common';
+import { MetadataScanner, ModulesContainer, NestFactory, Reflector } from '@nestjs/core';
+
+import { AppModule } from './app.module';
+import { BACKEND_API_METHOD_NAMES } from './backend-api';
+import { BACKEND_METHOD_KEY } from './backend-method.decorator';
+import type { BackendSession } from './types';
+
+/** A discovered method, bound to its service instance. */
+export type RegisteredBackendMethod = (session: BackendSession, input: unknown) => Promise<unknown>;
+
+export interface BackendRuntime {
+  ctx: INestApplicationContext;
+  registry: ReadonlyMap<string, RegisteredBackendMethod>;
+}
+
+/**
+ * Boot-once accessor for the embedded NestJS backend.
+ *
+ * The cache is MODULE-scoped on purpose: under `next dev`, editing anything
+ * in the backend graph makes HMR re-execute this module with a fresh scope,
+ * so the next invocation boots a NEW context with the new code — that is how
+ * agent edits take effect without a server restart. The previous context's
+ * handle rides `globalThis` (which HMR does NOT reset) solely so the new
+ * boot can close it — retired containers must not leak lifecycle hooks. In
+ * production there is no HMR and this degrades to boot-exactly-once.
+ *
+ * A failed boot (e.g. the api-map drift check) stays cached as a rejection:
+ * every invocation reports the same loud error until the FIX edit re-executes
+ * this module. Failing closed and visible beats a half-registered backend.
+ */
+let runtimePromise: Promise<BackendRuntime> | undefined;
+const handoff = globalThis as { __forgecartBackendPrev?: BackendRuntime };
+
+export function getBackend(): Promise<BackendRuntime> {
+  runtimePromise ??= boot();
+  return runtimePromise;
+}
+
+async function boot(): Promise<BackendRuntime> {
+  const ctx = await NestFactory.createApplicationContext(AppModule, {
+    logger: ['warn', 'error'],
+  });
+  const registry = scanForBackendMethods(ctx);
+  validateAgainstApi(registry);
+
+  const previous = handoff.__forgecartBackendPrev;
+  if (previous) {
+    try {
+      await previous.ctx.close();
+    } catch {
+      // A mid-reload teardown race is fine — the old container is gone either way.
+    }
+  }
+  const runtime: BackendRuntime = { ctx, registry };
+  handoff.__forgecartBackendPrev = runtime;
+  return runtime;
+}
+
+/**
+ * Walk every provider in the booted module graph and collect the methods
+ * carrying `@BackendMethod()` — the decorator is the allowlist, so the map
+ * built here is the ONLY surface `sdk.backend` can reach. Names are global:
+ * a duplicate across services fails the boot rather than shadowing.
+ */
+function scanForBackendMethods(
+  ctx: INestApplicationContext,
+): ReadonlyMap<string, RegisteredBackendMethod> {
+  const registry = new Map<string, RegisteredBackendMethod>();
+  const modules = ctx.get(ModulesContainer);
+  const scanner = new MetadataScanner();
+  const reflector = new Reflector();
+
+  for (const moduleRef of modules.values()) {
+    for (const wrapper of moduleRef.providers.values()) {
+      const instance = wrapper.instance as Record<string, unknown> | null;
+      if (!instance || typeof instance !== 'object') continue;
+      const prototype = Object.getPrototypeOf(instance) as Record<string, unknown> | null;
+      if (!prototype) continue;
+
+      for (const name of scanner.getAllMethodNames(prototype)) {
+        const handler = prototype[name];
+        if (typeof handler !== 'function') continue;
+        if (reflector.get<boolean | undefined>(BACKEND_METHOD_KEY, handler) !== true) continue;
+        if (registry.has(name)) {
+          throw new Error(
+            `Duplicate @BackendMethod name "${name}" — backend method names must be unique across all services.`,
+          );
+        }
+        registry.set(name, (handler as RegisteredBackendMethod).bind(instance));
+      }
+    }
+  }
+  return registry;
+}
+
+/**
+ * The drift tripwire: the runtime scan and the compile-time surface
+ * (`backend-api.ts`) must agree EXACTLY, in both directions, or the typed
+ * proxy the browser compiles against would lie. The error names the exact
+ * method so the fix is a one-line edit.
+ */
+function validateAgainstApi(registry: ReadonlyMap<string, RegisteredBackendMethod>): void {
+  const declared = new Set<string>(BACKEND_API_METHOD_NAMES);
+  for (const name of registry.keys()) {
+    if (!declared.has(name)) {
+      throw new Error(
+        `@BackendMethod "${name}" is not declared in backend-api.ts — add its signature to BackendApi and its name to BACKEND_API_METHOD_NAMES.`,
+      );
+    }
+  }
+  for (const name of declared) {
+    if (!registry.has(name)) {
+      throw new Error(
+        `backend-api.ts declares "${name}" but no @BackendMethod with that name was discovered — decorate the service method (and wire its module into app.module.ts) or remove the declaration.`,
+      );
+    }
+  }
+}

package/templates/storefront-shadcn/src/server/customer-extras/customer-extras.module.ts

@@ -0,0 +1,13 @@
+import 'server-only';
+
+import { Module } from '@nestjs/common';
+
+import { CustomerExtrasService } from './service/customer-extras.service';
+
+/**
+ * The worked-example domain module. New backend features follow this shape:
+ * one folder per domain, services under `service/`, the module listing them,
+ * and one `imports:` line in `app.module.ts`.
+ */
+@Module({ providers: [CustomerExtrasService] })
+export class CustomerExtrasModule {}