@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/lib/locale/grammar.ts

@@ -0,0 +1,194 @@
+/**
+ * The storefront's locale URL grammar (#1346, epic launch#54 W1-8 / S1) — the
+ * ONE place the path shape is decided.
+ *
+ * The invariant: the channel's DEFAULT language is served UNPREFIXED, every
+ * other language under `/<xx>/`. A single-language channel therefore never
+ * serves a prefix at all — its only language is the default, so the
+ * "never prefixed" case falls out of the rule rather than needing its own
+ * branch.
+ *
+ * PURE BY CONTRACT: no Next imports, no `process.env`, no fetch, no I/O. Two
+ * consumers depend on that literally. The middleware runs this on every
+ * request under the edge runtime, whose own contract is zero-fetch/zero-env
+ * (see `src/middleware.ts`); and `tool/storefront-template-spec` imports this
+ * file directly by relative path from OUTSIDE the scaffold, so anything
+ * reachable from here must resolve without the template's Next toolchain.
+ *
+ * A first segment is only ever a CANDIDATE here. This module cannot know the
+ * channel's language set, and deliberately does not try: validation happens at
+ * request time against `activeChannel` (`request-locale.ts`), which is what
+ * lets a language added a moment ago work on its very first request instead of
+ * 404ing until a cache expires.
+ *
+ * Every function takes a pathname only — never a full URL, never a query
+ * string. Callers strip those first; mixing them in is how a `?` ends up
+ * inside a path segment.
+ */
+
+/**
+ * A 2-letter lowercase primary language tag.
+ *
+ * Regional tags (`en-GB`) are deliberately OUT of the grammar: the platform's
+ * language registry is 2-char primary tags (launch#52 law 1), and admitting a
+ * 5-char form here would mint URLs the channel can never validate. The epic
+ * lists regional tags as a non-goal with an explicit revisit trigger.
+ */
+const LOCALE_SEGMENT_PATTERN = /^[a-z]{2}$/;
+
+/**
+ * Routes that exist ONCE PER STORE, never once per language.
+ *
+ * The XML sitemap and robots.txt are absolute and enumerate every locale
+ * themselves (S5); the readiness probe, the marketing relay and the error
+ * beacon are called by infrastructure that knows nothing about languages;
+ * `/api` is the storefront's own server surface; and `_next` / `favicon.ico`
+ * are build artifacts. Prefixing any of them would mint a URL the crawler
+ * contract forbids, or hand a probe a language it cannot mean.
+ *
+ * The set is consulted from two directions, and they want OPPOSITE answers for
+ * the same input, which is why neither check lives in `parseLocalePath`:
+ *
+ *  - BUILDING (`localePrefixedPath`): strip whatever prefix the caller handed
+ *    in, then refuse to add one back. `/de/sitemap.xml` must build to
+ *    `/sitemap.xml`, so the parse it relies on has to strip normally.
+ *  - REQUEST (`planLocaleRewrite`): refuse the rewrite outright. `/de/ping`
+ *    must NOT be served as `/ping`, or all 676 two-letter spellings would
+ *    answer 200 where each previously 404'd — and nothing downstream can undo
+ *    that, since the request-time locale check lives in the layout and
+ *    `route.ts` handlers render no layout.
+ *
+ * `parseLocalePath` therefore stays a plain parse and each side applies the
+ * rule it needs. Folding the request-side refusal into the parse looks
+ * tempting and is wrong: it silently makes `localePrefixedPath` stack a second
+ * prefix onto `/de/ping`.
+ *
+ * `_next` and `favicon.ico` are in the set for the request side specifically:
+ * the middleware matcher's negative lookahead is anchored at the start of the
+ * path, so it excludes `/_next/static/x.js` but not `/de/_next/static/x.js`.
+ *
+ * `verify` and `reset-password` are the two ACCOUNT-LINK routes (#1472), and
+ * they are here for a different reason than the rest: they render for humans
+ * and could carry a language. They exist once per store because the URL is not
+ * addressed by a shopper at all — the platform mints it into a one-shot e-mail
+ * link, where a wrong prefix is not a redirect but a dead token. One address
+ * per store is the only spelling every mail, in every language, can produce
+ * without the mail composer having to know this grammar. The page still reads
+ * the request's language like every other page; with no prefix to read, that is
+ * the channel's default (`request-locale.ts`), which is the same language the
+ * storefront serves to anyone who arrives without choosing one.
+ */
+const UNPREFIXED_FIRST_SEGMENTS: ReadonlySet<string> = new Set([
+  'sitemap.xml',
+  'robots.txt',
+  'ping',
+  '__fc',
+  '__forge_beacon',
+  'api',
+  '_next',
+  'favicon.ico',
+  'verify',
+  'reset-password',
+]);
+
+/** The parse of a request path against the grammar. */
+export interface ParsedLocalePath {
+  /**
+   * The 2-letter first segment when the path carries one, else `null`.
+   * CANDIDATE only — never assume the channel offers it.
+   */
+  localeCandidate: string | null;
+  /**
+   * The path with any locale prefix removed: always leading-slashed, and
+   * never trailing-slashed except for the root `/`. This is what the
+   * middleware rewrites to, so it must be the shape the route tree expects.
+   */
+  pathname: string;
+}
+
+/** Whether a single path segment could be a locale under this grammar. */
+export function isLocaleSegment(segment: string): boolean {
+  return LOCALE_SEGMENT_PATTERN.test(segment);
+}
+
+/**
+ * Whether this path is one of the never-prefixed infrastructure routes, in
+ * which case the locale stage must not touch it at all.
+ */
+export function isUnprefixedPath(pathname: string): boolean {
+  return UNPREFIXED_FIRST_SEGMENTS.has(firstSegment(pathname));
+}
+
+/**
+ * Split a request path into its locale candidate and the remaining route path.
+ *
+ * A path whose first segment is not 2 lowercase letters — or which IS an
+ * infrastructure route — parses as `{ localeCandidate: null }` and keeps its
+ * pathname, normalized.
+ *
+ * A prefix worn OVER an infrastructure route still parses as a candidate here:
+ * `/de/sitemap.xml` is `de` over `/sitemap.xml`. That is what the link builder
+ * needs in order to strip it. Refusing to SERVE that URL is the request side's
+ * rule, and lives in `planLocaleRewrite` — see {@link UNPREFIXED_FIRST_SEGMENTS}.
+ */
+export function parseLocalePath(pathname: string): ParsedLocalePath {
+  const normalized = normalizePathname(pathname);
+  if (isUnprefixedPath(normalized)) return { localeCandidate: null, pathname: normalized };
+
+  const segment = firstSegment(normalized);
+  if (!isLocaleSegment(segment)) return { localeCandidate: null, pathname: normalized };
+
+  // `/en` and `/en/` both mean the locale's home page.
+  const rest = normalized.slice(segment.length + 1);
+  return { localeCandidate: segment, pathname: rest === '' ? '/' : normalizePathname(rest) };
+}
+
+/**
+ * The route path a locale-prefixed request maps onto — i.e. the same thing
+ * `parseLocalePath` returns, for callers that only want the path.
+ */
+export function stripLocalePrefix(pathname: string): string {
+  return parseLocalePath(pathname).pathname;
+}
+
+/**
+ * Build the canonical URL path for `pathname` in `locale`.
+ *
+ * The default locale is unprefixed; every other locale is prefixed. `pathname`
+ * may itself already carry a prefix — it is stripped first, so this is
+ * idempotent and safe to hand a current request path when switching language.
+ *
+ * Emits no trailing slash (the template's Next config does not use them), so
+ * the home page in a non-default locale is `/de`, not `/de/`. `parseLocalePath`
+ * still accepts both, because a crawler or a hand-typed URL will produce both.
+ */
+export function localePrefixedPath(
+  locale: string,
+  pathname: string,
+  defaultLocale: string,
+): string {
+  const route = stripLocalePrefix(pathname);
+  // Infrastructure routes are single-copy by contract — never prefix them,
+  // even when the caller asks for a non-default locale.
+  if (locale === defaultLocale || isUnprefixedPath(route)) return route;
+  return route === '/' ? `/${locale}` : `/${locale}${route}`;
+}
+
+/** The first path segment, without slashes; `''` for the root path. */
+function firstSegment(pathname: string): string {
+  const normalized = normalizePathname(pathname);
+  const end = normalized.indexOf('/', 1);
+  return end === -1 ? normalized.slice(1) : normalized.slice(1, end);
+}
+
+/**
+ * Leading slash guaranteed, trailing slash removed except at the root, and
+ * repeated slashes collapsed — so `//de//products/` and `/de/products` parse
+ * identically instead of minting a second URL for the same page.
+ */
+function normalizePathname(pathname: string): string {
+  const withLeadingSlash = pathname.startsWith('/') ? pathname : `/${pathname}`;
+  const collapsed = withLeadingSlash.replace(/\/{2,}/g, '/');
+  if (collapsed === '/') return '/';
+  return collapsed.endsWith('/') ? collapsed.slice(0, -1) : collapsed;
+}

package/templates/storefront-shadcn/src/lib/locale/localized-path.ts

@@ -0,0 +1,55 @@
+import { localePrefixedPath } from './grammar';
+
+/**
+ * Link-layer API over the locale grammar (#1346, epic launch#54 W1-8 / S2).
+ *
+ * Components never call the grammar directly and never derive the locale
+ * themselves. Under the middleware rewrite the browser's URL and the rendered
+ * route DIFFER — `/de/products` renders the `/products` route — so
+ * `usePathname()` returns the REWRITTEN path and reading the locale from it
+ * would silently yield the default for every request. The locale therefore
+ * travels as a PROP from the layout's request-time hole down to every link.
+ *
+ * This module exists so that rule has one place to be stated and one API to
+ * enforce it: give it the binding, get a correct href.
+ */
+
+/** The request's locale context, threaded down from the layout hole. */
+export interface LocaleBinding {
+  /** The locale this request is being rendered in. */
+  locale: string;
+  /** The channel's default language — the one served unprefixed. */
+  defaultLocale: string;
+}
+
+/**
+ * The href for `path` in the CURRENT locale — what every internal link uses.
+ *
+ * Keeping links inside their own locale cluster is the whole point. A German
+ * page whose links all point at the English cluster leaves every German page
+ * but the entry point unreachable by following links, so a crawler never
+ * discovers them and the locale is effectively unindexed.
+ */
+export function localizedPath(path: string, binding: LocaleBinding): string {
+  return localePrefixedPath(binding.locale, path, binding.defaultLocale);
+}
+
+/**
+ * The href for the SAME page in `targetLocale` — the language switcher's
+ * destination.
+ *
+ * `currentPath` may already carry a prefix; the grammar strips before it
+ * prefixes, so switching de → fr yields `/fr/...` rather than `/fr/de/...`.
+ *
+ * The switcher navigates here AND calls `setLanguage`: the URL is what
+ * crawlers index, the session is what a returning human gets. Neither alone is
+ * sufficient — a session-only switch gives crawlers one indexable copy, and a
+ * URL-only switch forgets the choice on the next bare link.
+ */
+export function switchedLocalePath(
+  targetLocale: string,
+  currentPath: string,
+  binding: LocaleBinding,
+): string {
+  return localePrefixedPath(targetLocale, currentPath, binding.defaultLocale);
+}

package/templates/storefront-shadcn/src/lib/locale/middleware-plan.ts

@@ -0,0 +1,107 @@
+import { isUnprefixedPath, parseLocalePath } from './grammar';
+
+/**
+ * What the middleware does with a request path (#1346, epic launch#54 W1-8 /
+ * S1) — the edge stage's whole locale decision, as a value.
+ *
+ * PURE BY CONTRACT, for the same two reasons `grammar.ts` is: it runs on every
+ * request under the edge runtime, and `tool/storefront-template-spec` imports
+ * it directly from outside the scaffold. `middleware.ts` itself can never be
+ * pinned by that project — it imports `next/server` — so the decision lives
+ * here and the middleware is left as dispatch.
+ */
+
+/** The edge stage's decision for one request path. */
+export type LocaleRewritePlan =
+  | { kind: 'pass' }
+  | { kind: 'rewrite'; locale: string; routePath: string };
+
+/**
+ * Plan the locale stage for `pathname`.
+ *
+ *  - `pass` — no locale prefix (the default-language majority of traffic), or
+ *    a prefix worn over a store-wide route.
+ *  - `rewrite` — serve `routePath` in `locale`.
+ *
+ * The `pass` on a prefixed infrastructure route is the load-bearing one.
+ * `/ping` never reaches middleware, but `/de/ping` does: the matcher's
+ * negative lookahead is anchored at the start of the path, so it is a
+ * whole-path prefix test. Rewriting that onto the real readiness probe would
+ * give it 676 two-letter spellings that answer 200 — each with a `Set-Cookie`
+ * attached, on a route whose contract is to be byte-stable and cacheable —
+ * where every one of them previously 404'd. Passing leaves the path whole, so
+ * it reaches a route tree that has no such route.
+ *
+ * The candidate is NOT validated here — that needs the channel's languages,
+ * and this stage is zero-fetch by contract. An unknown locale still plans a
+ * `rewrite`; `decideRequestLocale` turns it into a 404 at request time.
+ *
+ * Canonicalization is deliberately absent: Next's own `/:path+/` → `/:path+`
+ * redirect and its repeated-slash normalization are ordered BEFORE middleware
+ * in `resolve-routes.js`, so a non-canonical path has already been 308'd by
+ * the time this runs. The grammar still normalizes, which makes this total for
+ * any input, but there is no canonicalizing branch here because there is no
+ * request that would reach it.
+ */
+export function planLocaleRewrite(pathname: string): LocaleRewritePlan {
+  const { localeCandidate, pathname: routePath } = parseLocalePath(pathname);
+  if (localeCandidate === null) return { kind: 'pass' };
+  if (isUnprefixedPath(routePath)) return { kind: 'pass' };
+
+  return { kind: 'rewrite', locale: localeCandidate, routePath };
+}
+
+/**
+ * Headers the middleware puts ON the request for the render to read. They are
+ * SERVER-AUTHORED and the render trusts them completely, which is exactly why
+ * an inbound copy is an attack rather than input.
+ *
+ * `ROUTE_PATH` and `SEARCH` exist because the render sees the REWRITTEN path
+ * and cannot reconstruct the original — the layout needs both to build the
+ * canonical target when it redirects a default-locale prefix.
+ */
+export const LOCALE_REQUEST_HEADER = 'x-forgecart-locale';
+export const ROUTE_PATH_REQUEST_HEADER = 'x-forgecart-route-path';
+export const SEARCH_REQUEST_HEADER = 'x-forgecart-search';
+
+const SERVER_AUTHORED_HEADERS: readonly string[] = [
+  LOCALE_REQUEST_HEADER,
+  ROUTE_PATH_REQUEST_HEADER,
+  SEARCH_REQUEST_HEADER,
+];
+
+/**
+ * Whether a request arrived wearing a header only the server may set.
+ *
+ * A client sending `x-forgecart-locale: de` to `/products` would otherwise get
+ * a German render at the canonical English URL — content negotiation by request
+ * header, at a URL whose entire contract is that the URL is the only locale
+ * selector. The middleware uses this to decide whether a `pass` needs
+ * sanitizing at all, so clean traffic keeps the untouched fast path.
+ */
+export function hasServerAuthoredHeaders(headers: Headers): boolean {
+  return SERVER_AUTHORED_HEADERS.some((name) => headers.has(name));
+}
+
+/**
+ * The headers the render should see: every inbound copy of the server-authored
+ * set removed, then the real values written when there is a locale to forward.
+ *
+ * Strip-then-set, always in that order and unconditionally — a `pass` must be
+ * left carrying none of them, or a forged value survives into the render on
+ * exactly the paths that have no locale of their own.
+ */
+export function localeRequestHeaders(
+  headers: Headers,
+  plan: LocaleRewritePlan,
+  search: string,
+): Headers {
+  const sanitized = new Headers(headers);
+  for (const name of SERVER_AUTHORED_HEADERS) sanitized.delete(name);
+  if (plan.kind !== 'rewrite') return sanitized;
+
+  sanitized.set(LOCALE_REQUEST_HEADER, plan.locale);
+  sanitized.set(ROUTE_PATH_REQUEST_HEADER, plan.routePath);
+  sanitized.set(SEARCH_REQUEST_HEADER, search);
+  return sanitized;
+}

package/templates/storefront-shadcn/src/lib/locale/request-binding.ts

@@ -0,0 +1,80 @@
+import 'server-only';
+
+import { cache } from 'react';
+import { headers } from 'next/headers';
+
+import { resolveChannelLocales } from './channel-locales-loader';
+import { decideRequestLocale } from './request-locale';
+import type { LocaleDecision } from './request-locale';
+import type { LocaleBinding } from './localized-path';
+import {
+  LOCALE_REQUEST_HEADER,
+  ROUTE_PATH_REQUEST_HEADER,
+  SEARCH_REQUEST_HEADER,
+} from './middleware-plan';
+
+/**
+ * The request's locale, resolved once and shared (#1346, W1-8 / S1+S2).
+ *
+ * This is the reader for the headers the middleware authored, and the only
+ * place the four-case decision is taken. A layout cannot pass props to a page
+ * — pages arrive as opaque `children` — so every server component that needs
+ * the locale calls this rather than receiving it, and React's `cache()` makes
+ * that one resolution per request no matter how many callers there are. The
+ * same primitive already backs `getVariant`'s request-scoped visitor id.
+ *
+ * Server-only by construction as well as by declaration: `headers()` throws in
+ * a client component, and `cache()` is an unmemoized pass-through in the
+ * client build. Client components receive the locale as a PROP instead — see
+ * `localized-path.ts` for why reading it from `usePathname()` cannot work
+ * under the rewrite.
+ */
+
+export interface RequestLocale {
+  /** What the layout must do with this request. */
+  decision: LocaleDecision;
+  /** What every link needs: the rendering locale and the channel default. */
+  binding: LocaleBinding;
+  /** The channel's languages, for the switcher. */
+  languageCodes: readonly string[];
+  /** The merchant's shop name, for the title suffix (#1347). Null when unset. */
+  shopName: string | null;
+  /**
+   * Whether the channel behind this render was actually established (#1347).
+   *
+   * Surfaced here rather than read from the loader directly because every
+   * `generateMetadata` in the template already awaits this resolution: the
+   * fact costs nothing to carry, and a route that has to fetch it separately
+   * is a route that will forget to.
+   */
+  channelResolved: boolean;
+  /** The pre-rewrite path and query, for building a canonical redirect. */
+  routePath: string;
+  search: string;
+}
+
+export const getRequestLocale = cache(async (): Promise<RequestLocale> => {
+  const requestHeaders = await headers();
+  const candidate = requestHeaders.get(LOCALE_REQUEST_HEADER);
+  const routePath = requestHeaders.get(ROUTE_PATH_REQUEST_HEADER) ?? '/';
+  const search = requestHeaders.get(SEARCH_REQUEST_HEADER) ?? '';
+
+  const { channel, offered } = await resolveChannelLocales(candidate);
+  const decision = decideRequestLocale({ candidate, routePath, channel, offered, search });
+
+  return {
+    decision,
+    // A redirect or a 404 never reaches a link, but the binding is built
+    // unconditionally so callers never have to branch: the channel default is
+    // the only honest locale for a request that is not being rendered.
+    binding: {
+      locale: decision.kind === 'render' ? decision.locale : channel.defaultLanguageCode,
+      defaultLocale: channel.defaultLanguageCode,
+    },
+    languageCodes: channel.languageCodes,
+    shopName: channel.shopName,
+    channelResolved: channel.resolved,
+    routePath,
+    search,
+  };
+});

package/templates/storefront-shadcn/src/lib/locale/request-locale.ts

@@ -0,0 +1,66 @@
+import type { ChannelLocales } from './channel-locales';
+
+/**
+ * The request-time locale decision (#1346, epic launch#54 W1-8 / S1).
+ *
+ * The middleware cannot make this call — it is zero-fetch by contract — so it
+ * rewrites on a CANDIDATE and the real decision happens in the layout's
+ * request-time hole, where the channel's languages are reachable.
+ *
+ * This module is deliberately PURE and deliberately does not import
+ * `next/navigation`. Returning a decision instead of calling `notFound()` /
+ * `permanentRedirect()` is what keeps the interesting logic — which of four
+ * outcomes a request gets — inside the seam the template spec project can
+ * import. The layout performs the dispatch, and dispatch is the part with
+ * nothing left to get wrong.
+ */
+
+/** What the layout should do with this request. */
+export type LocaleDecision =
+  | { kind: 'render'; locale: string }
+  | { kind: 'redirect'; to: string }
+  | { kind: 'notFound' };
+
+export interface RequestLocaleInput {
+  /** The two-letter first segment the middleware stripped, if there was one. */
+  candidate: string | null;
+  /** The path AFTER the prefix was stripped — what the route tree serves. */
+  routePath: string;
+  /** The channel's advertised languages. */
+  channel: ChannelLocales;
+  /**
+   * Whether the channel offers `candidate`, already resolved through
+   * `channel-locales` (which reloads once on a miss, so a language added a
+   * moment ago answers `true` here on its first request).
+   */
+  offered: boolean;
+  /** The original query string, `''` or leading `?` — preserved on redirect. */
+  search?: string;
+}
+
+/**
+ * Decide the outcome for a request whose locale prefix has already been parsed.
+ *
+ * The four cases, in the order they must be tested:
+ *
+ *  1. No prefix at all → render in the channel's default language. This is the
+ *     canonical shape for the default locale.
+ *  2. The prefix names the DEFAULT language → permanent redirect to the
+ *     unprefixed path. `/en/products` and `/products` would otherwise be two
+ *     URLs serving one page, which is the duplicate-content split the whole
+ *     grammar exists to avoid. Tested BEFORE `offered`, because the default
+ *     language is always offered and would otherwise render prefixed.
+ *  3. The prefix names a language the channel does not offer → 404. Not a
+ *     redirect: silently rewriting an unknown locale to the default would tell
+ *     a crawler that `/zz/x` is a real page.
+ *  4. Otherwise → render in that language.
+ */
+export function decideRequestLocale(input: RequestLocaleInput): LocaleDecision {
+  const { candidate, routePath, channel, offered } = input;
+  if (candidate === null) return { kind: 'render', locale: channel.defaultLanguageCode };
+  if (candidate === channel.defaultLanguageCode) {
+    return { kind: 'redirect', to: `${routePath}${input.search ?? ''}` };
+  }
+  if (!offered) return { kind: 'notFound' };
+  return { kind: 'render', locale: candidate };
+}