@forgecart/cli 2.202608221935.0 → 2.202609190800.0

package/templates/storefront/src/lib/track-forward.ts

@@ -122,21 +122,21 @@ export function isObviousBot(userAgent: string): boolean {
 }
 
 /**
- * Forward one event as a raw HTTP GraphQL POST. Any failure — missing config,
- * network, HTTP status, GraphQL errors — resolves to `accepted:false`; the
- * forwarder is best-effort by design (analytics must never break the
- * storefront) and `accepted:false` is terminal (callers never retry).
+ * The header set every upstream call carries.
+ *
+ * ONE builder, shared with the marketing-identity forwarder
+ * (`identify-forward.ts`), because both speak about the SAME shopper: the
+ * session riding as `Authorization` decides which identity a row is written to,
+ * so a header set that drifted between them would split one visitor in two and
+ * nothing downstream could put them back together.
  */
-export async function forwardTrackEvent(
-  input: TrackEventInput,
+export function buildUpstreamHeaders(
+  channelToken: string,
   { sessionToken, userAgent, forwardedFor, secChUa, secChUaMobile, secChUaPlatform }: ForwardHeaders,
-): Promise<UpstreamOutcome> {
-  const upstream = getUpstreamConfig();
-  if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
-
+): Record<string, string> {
   const headers: Record<string, string> = {
     'content-type': 'application/json',
-    'forgecart-token': upstream.channelToken,
+    'forgecart-token': channelToken,
   };
   if (sessionToken) headers['Authorization'] = `Bearer ${sessionToken}`;
   if (userAgent) headers['user-agent'] = userAgent;
@@ -144,18 +144,47 @@ export async function forwardTrackEvent(
   if (secChUa) headers['sec-ch-ua'] = secChUa;
   if (secChUaMobile) headers['sec-ch-ua-mobile'] = secChUaMobile;
   if (secChUaPlatform) headers['sec-ch-ua-platform'] = secChUaPlatform;
+  return headers;
+}
+
+/**
+ * The session the shop API minted for a cookie-less request, if it minted one.
+ *
+ * Surfaced in the response `extensions` exactly once. Shared with the identity
+ * forwarder for the same reason the headers are: both relays may ESTABLISH the
+ * shopper's `forgecart-session` cookie from this value, and two readings of
+ * "did the upstream mint a session" would eventually mean two cookies.
+ */
+export function readMintedSessionToken(
+  extensions: Record<string, unknown> | undefined,
+): string | null {
+  const minted = extensions?.['forgecart-auth-token'];
+  return typeof minted === 'string' && minted.length > 0 ? minted : null;
+}
+
+/**
+ * Forward one event as a raw HTTP GraphQL POST. Any failure — missing config,
+ * network, HTTP status, GraphQL errors — resolves to `accepted:false`; the
+ * forwarder is best-effort by design (analytics must never break the
+ * storefront) and `accepted:false` is terminal (callers never retry).
+ */
+export async function forwardTrackEvent(
+  input: TrackEventInput,
+  forward: ForwardHeaders,
+): Promise<UpstreamOutcome> {
+  const upstream = getUpstreamConfig();
+  if (!upstream) return { accepted: false, eventId: null, sessionToken: null };
 
   try {
     const response = await fetch(upstream.shopApiUrl, {
       method: 'POST',
-      headers,
+      headers: buildUpstreamHeaders(upstream.channelToken, forward),
       body: JSON.stringify({ query: TRACK_EVENT_MUTATION, variables: { input } }),
     });
     if (!response.ok) return { accepted: false, eventId: null, sessionToken: null };
 
     const payload = (await response.json()) as GraphQLTrackResponse;
-    const minted = payload.extensions?.['forgecart-auth-token'];
-    const capturedToken = typeof minted === 'string' && minted.length > 0 ? minted : null;
+    const capturedToken = readMintedSessionToken(payload.extensions);
     const trackEvent = payload.data?.trackEvent;
     if (!trackEvent) return { accepted: false, eventId: null, sessionToken: capturedToken };
     return {

package/templates/storefront/src/middleware.ts

@@ -2,8 +2,18 @@ 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 middleware (design doc S6 + F-B).
+ * 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) —
@@ -15,6 +25,16 @@ import { uuidv7 } from 'uuidv7';
  *  - 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).
@@ -44,10 +64,68 @@ import { uuidv7 } from 'uuidv7';
  * 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;
 
@@ -147,21 +225,112 @@ function mergeForcedEntries(request: NextRequest): string | null {
   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 mintVisitor = !request.cookies.has(VISITOR_COOKIE_NAME);
-  if (!forcedEntryValue && !mintVisitor) {
+  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();
   }
 
-  let response: NextResponse;
   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. No redirect — the
-    // campaign URL stays shareable.
+    // 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);
-    response = NextResponse.next({ request: { headers: request.headers } });
+  }
+
+  const response = buildBaseResponse(request, plan, forcedEntryValue !== null);
+
+  if (forcedEntryValue) {
     response.cookies.set({
       name: FORCED_ENTRY_COOKIE_NAME,
       value: forcedEntryValue,
@@ -171,18 +340,29 @@ export function middleware(request: NextRequest): NextResponse {
       maxAge: FORCED_ENTRY_COOKIE_MAX_AGE_SECONDS,
       path: '/',
     });
-  } else {
-    response = NextResponse.next();
   }
 
-  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.
+  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_COOKIE_NAME,
-      value: uuidv7(),
-      httpOnly: true,
+      name: VISITOR_MIRROR_COOKIE_NAME,
+      value: visitorId,
+      httpOnly: false,
       secure: true,
       sameSite: 'lax',
       maxAge: VISITOR_COOKIE_MAX_AGE_SECONDS,

package/templates/storefront/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/src/server/runner.ts

@@ -4,13 +4,12 @@ import { extractError, type ExtractedError } from '@forgecart/sdk';
 import { cookies } from 'next/headers';
 
 import { UNREACHABLE_ERROR, type ActionResult } from '../lib/action-result';
+import { SESSION_COOKIE } from '../lib/session-cookies';
 import { getBackend } from './bootstrap';
 import { ForgeCartClientFactory } from './forgecart/forgecart-client.factory';
 import { BackendError } from './types';
 import type { BackendSession } from './types';
 
-const SESSION_COOKIE = 'forgecart-session';
-
 /** The gate has no env yet (image pre-warm / before `forgecart init`). */
 const NOT_CONFIGURED: ExtractedError = {
   code: 'BACKEND_NOT_CONFIGURED',