npm - @forgecart/cli - Versions diffs - 2.202608221935.0 → 2.202609190800.0 - Mend

@forgecart/cli 2.202608221935.0 → 2.202609190800.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/templates/storefront/src/lib/locale/channel-locales-loader.ts ADDED Viewed

@@ -0,0 +1,169 @@
+import 'server-only';
+import { createChannelLocalesCache } from './channel-locales';
+import type { ChannelLocales, ChannelLocalesResolution } from './channel-locales';
+import { toChannelLocales } from './channel-locales-map';
+import type { RawChannelLocales } from './channel-locales-map';
+/**
+ * Binds the channel-language cache to the shop API (#1346, W1-8 / S1).
+ *
+ * Transport is a plain GraphQL POST, deliberately — NOT the SDK's shop client.
+ * This read happens inside the root layout, which is outside every Suspense
+ * boundary, so it sits on the first byte of every route. The SDK client's
+ * language is a per-CONNECTION header fixed at socket handshake, so using it
+ * here would put a WebSocket handshake plus an anonymous-session mint on that
+ * path, and a hung socket would hold the document open with no bound. The
+ * experiments config-fetch (`experiments.ts`) already reads the shop API this
+ * way for the same reason; this follows it, and adds the timeout that path
+ * lacks.
+ *
+ * Failure policy, in three layers, because this module decides what a
+ * storefront looks like when its backend is unwell:
+ *
+ *  1. Not configured yet — no fetch at all. The workspace-pod prewarm boots
+ *     this server with no `.env`, and the layout must render anyway.
+ *  2. Fetch fails with a warm cache — the cache serves the last good snapshot
+ *     and retries on the next request. Nothing here to do.
+ *  3. Fetch fails on a COLD process — {@link FALLBACK_LOCALES}. A site-wide
+ *     500 is the worst thing a crawler can be shown (5xx throttles crawl rate
+ *     and drops URLs), so the storefront renders instead. The fallback is
+ *     English-only, which is byte-for-byte what the root layout hardcoded
+ *     before this slice existed — so an outage degrades to the previous
+ *     behaviour rather than to something new. It renders, and it says so:
+ *     `resolved: false` rides the snapshot, and the metadata floor turns that
+ *     into `noindex` (#1347). Serving a guessed language is survivable;
+ *     letting a crawler INDEX the guess is not.
+ */
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+/**
+ * The bound on how long the document shell may wait for the channel read.
+ * Short by intent: past this, serving the fallback beats holding the shell.
+ */
+const CHANNEL_FETCH_TIMEOUT_MS = 2_000;
+/**
+ * The channel snapshot the storefront's shell renders from.
+ *
+ * `ChannelLocales` plus the two facts that are not about languages but come
+ * from the same `activeChannel` document, and must come from the same SNAPSHOT
+ * of it: a shell that paired one window's language set with another window's
+ * shop name would be a torn read of the identical kind the locale resolution
+ * itself is built to avoid.
+ */
+export interface StorefrontChannel extends ChannelLocales {
+  /**
+   * The merchant's shop name, or null when unset. The title suffix (#1347) —
+   * `null` and `''` both mean "no suffix", and that emptiness rule lives with
+   * the title rule, not here: this module reports what the channel said.
+   */
+  shopName: string | null;
+  /**
+   * Whether this snapshot came from a real `activeChannel` read.
+   *
+   * FALSE is the honest admission that the storefront does not know what
+   * channel it is serving — an unconfigured scaffold, or a cold process whose
+   * backend it could not reach. It rides on the snapshot rather than being
+   * derived by the caller because it is a property OF the snapshot: a stale
+   * one still says `true`, and correctly so — its languages were established,
+   * they are merely a minute old.
+   */
+  resolved: boolean;
+}
+/**
+ * What an unconfigured scaffold, or a cold process with an unreachable
+ * backend, serves. For the UNCONFIGURED case `en` is not a guess about the
+ * merchant — it is the value `<html lang>` carried unconditionally before the
+ * locale layer existed, and nothing real is being served anyway (the prewarm
+ * contract: answer the request, do not crash).
+ *
+ * For a CONFIGURED store on a cold process it IS a guess, and it is marked as
+ * one: `resolved: false`. A channel whose default is not English briefly
+ * serves `<html lang="en">` over its own language and 404s its default-language
+ * prefix instead of canonicalizing it, and no value here can fix that — the
+ * scaffold never learns the channel's default language, since `.env` carries
+ * the token and the URLs and nothing else.
+ *
+ * What CAN be fixed is the asserting. A storefront that does not know its
+ * channel makes no indexable claim at all: `resolved: false` closes the
+ * metadata floor (`lib/seo/metadata.ts`), so the shell renders — the prewarm
+ * contract holds — while telling crawlers to ignore it. That is the same
+ * posture this template already takes for a deployment with no public origin,
+ * and it closes the #1346 hand-off recorded on #1347.
+ */
+const FALLBACK_LOCALES: StorefrontChannel = {
+  languageCodes: ['en'],
+  defaultLanguageCode: 'en',
+  shopName: null,
+  resolved: false,
+};
+const ACTIVE_CHANNEL_QUERY = `query ActiveChannelLocales {
+  activeChannel {
+    defaultLanguageCode
+    availableLanguageCodes
+    shopName
+  }
+}`;
+/**
+ * The shop name rides this read rather than one of its own: the layout already
+ * awaits this document on the first byte of every route, and a second cached
+ * fetch for one string would double that cost for a value the same response
+ * already carries.
+ */
+type RawActiveChannel = RawChannelLocales & { shopName?: string | null };
+interface ActiveChannelResponse {
+  data?: { activeChannel?: RawActiveChannel | null } | null;
+}
+/**
+ * THROWS on any failure, deliberately. The cache distinguishes "refresh
+ * failed, keep the good snapshot" from "cold start, nothing to serve", and it
+ * can only do that if this reports failure as failure. Returning a fallback
+ * here instead would cache English-only for a full TTL window on the first
+ * blip — rendering every locale in English while looking perfectly healthy.
+ */
+async function loadChannelLocales(): Promise<StorefrontChannel> {
+  if (!SHOP_API_URL || !CHANNEL_TOKEN) return FALLBACK_LOCALES;
+  const response = await fetch(SHOP_API_URL, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', 'forgecart-token': CHANNEL_TOKEN },
+    body: JSON.stringify({ query: ACTIVE_CHANNEL_QUERY }),
+    signal: AbortSignal.timeout(CHANNEL_FETCH_TIMEOUT_MS),
+  });
+  if (!response.ok) {
+    throw new Error(`activeChannel read failed: HTTP ${response.status}`);
+  }
+  const payload = (await response.json()) as ActiveChannelResponse;
+  const channel = payload.data?.activeChannel;
+  if (!channel?.defaultLanguageCode) {
+    throw new Error('activeChannel read returned no defaultLanguageCode');
+  }
+  return { ...toChannelLocales(channel), shopName: channel.shopName ?? null, resolved: true };
+}
+const channelLocales = createChannelLocalesCache(loadChannelLocales);
+/**
+ * The channel and whether it offers `candidate`, from one snapshot — and never
+ * rejecting, whatever the backend is doing. This is the boundary where layer 3
+ * of the failure policy is applied: the cache propagates a cold-start failure
+ * so that the decision is made HERE, in one visible place, rather than being
+ * invented inside the cache.
+ */
+export async function resolveChannelLocales(
+  candidate: string | null,
+): Promise<ChannelLocalesResolution<StorefrontChannel>> {
+  try {
+    return await channelLocales.resolve(candidate);
+  } catch {
+    return { channel: FALLBACK_LOCALES, offered: false };
+  }
+}

package/templates/storefront/src/lib/locale/channel-locales-map.ts ADDED Viewed

@@ -0,0 +1,46 @@
+import { isLocaleSegment } from './grammar';
+import type { ChannelLocales } from './channel-locales';
+/**
+ * The channel payload → {@link ChannelLocales} coercion (#1346, W1-8 / S1).
+ *
+ * Pure and SDK-type-free on purpose: this is the one place the shop API's
+ * shape can be got wrong, and keeping it importable by the template spec
+ * project means it is pinned exhaustively instead of exercised only through a
+ * live channel.
+ */
+/** The shape the shop API returns, with its own nullability. */
+export interface RawChannelLocales {
+  defaultLanguageCode: string;
+  /**
+   * NULLABLE in the schema (`availableLanguageCodes: [String!]`) and in the
+   * SDK (`Maybe<Array<...>>`). The schema's own comment says null means "none
+   * enabled beyond the default" and that storefronts coalesce to
+   * `[defaultLanguageCode]` — which is exactly what this function does.
+   */
+  availableLanguageCodes?: readonly string[] | null;
+}
+/**
+ * Coerce the channel payload into the non-null set the grammar consumes.
+ *
+ * Union-with-the-default FIRST, which makes the result null-safe and
+ * empty-safe in one expression and lets the single-language channel fall out
+ * of the rule rather than needing its own branch: its only language IS the
+ * default, so it never serves a prefix.
+ *
+ * The extras are filtered through {@link isLocaleSegment}, the default is not.
+ * A stray `en-GB` from a channel configured outside the platform's 2-char
+ * registry is unreachable as a URL — the grammar can never parse a prefix for
+ * it — so admitting it would only mint a language-switcher link to a page that
+ * 404s. The default is exempt because it is never URL-visible: it is the
+ * language served UNPREFIXED, so its spelling never has to survive a parse.
+ */
+export function toChannelLocales(raw: RawChannelLocales): ChannelLocales {
+  const codes = new Set<string>([raw.defaultLanguageCode]);
+  for (const code of raw.availableLanguageCodes ?? []) {
+    if (isLocaleSegment(code)) codes.add(code);
+  }
+  return { languageCodes: [...codes], defaultLanguageCode: raw.defaultLanguageCode };
+}

package/templates/storefront/src/lib/locale/channel-locales.ts ADDED Viewed

@@ -0,0 +1,191 @@
+/**
+ * The channel's language set, cached per server process (#1346, epic
+ * launch#54 W1-8 / S1).
+ *
+ * The middleware cannot validate a locale — it is zero-fetch by contract — so
+ * a two-letter first segment reaches the layout as a CANDIDATE and is decided
+ * here, in the request-time hole.
+ *
+ * This cache sits on the critical path of the DOCUMENT SHELL of every route:
+ * the root layout must know the locale before it can write `<html lang>`, and
+ * that is structurally outside every Suspense boundary. Three requirements
+ * follow, and together they are the whole design of this module:
+ *
+ *  - **A language added a moment ago must work on its very first request.** A
+ *    plain TTL cache would 404 the new locale for up to a minute — exactly the
+ *    "I added German and the German page is broken" report this slice exists
+ *    to prevent. Hence: a MISS forces a live refetch before the answer is
+ *    allowed to be `false`.
+ *  - **But a miss is also what an unknown locale looks like.** Refetching on
+ *    every miss would turn `/zz/`, `/qq/`, `/aa/` … into one live call per
+ *    request, aimed at the storefront's own backend. Hence: at most ONE
+ *    miss-driven refetch per TTL window.
+ *  - **An expiry must never block a render, and a backend blip must never
+ *    become a 5xx.** A stale snapshot is served immediately while a refresh
+ *    runs behind it, and a refresh that fails leaves the last good snapshot in
+ *    place. Without this, one slow backend puts a full round-trip on the first
+ *    byte of every route once per window, and one unreachable backend turns
+ *    every page — including every 404 — into a site-wide 500. That is the most
+ *    damaging thing a crawler can see: 5xx throttles crawl rate site-wide and
+ *    drops URLs if it persists.
+ *
+ * Net behaviour: a real new language costs one extra fetch, once. A flood of
+ * junk locales costs one extra fetch, once, then is free. An expiry costs a
+ * background fetch and no latency. An outage costs nothing until the process
+ * restarts, and the caller decides what a cold start with no backend serves.
+ *
+ * The loader and the clock are injected so this logic is unit-testable with no
+ * network and no wall-clock waiting. The SDK loader is bound where the cache
+ * is consumed; this module stays free of both the SDK and the clock so the
+ * spec project can import it.
+ */
+/** The channel's advertised languages. */
+export interface ChannelLocales {
+  /** Every language the channel offers, including the default. */
+  languageCodes: readonly string[];
+  /** The language served UNPREFIXED. */
+  defaultLanguageCode: string;
+}
+/**
+ * One request's answer, derived from ONE snapshot.
+ *
+ * Returning both together is the point: resolving the channel and the
+ * candidate through two separate reads lets a request decide "render prefixed"
+ * against an old `defaultLanguageCode` while `offered` came from a snapshot in
+ * which that locale had BECOME the default — a torn read whose symptom is a
+ * page that should have 308'd rendering prefixed instead.
+ */
+export interface ChannelLocalesResolution<T extends ChannelLocales = ChannelLocales> {
+  channel: T;
+  offered: boolean;
+}
+/**
+ * Generic in the SNAPSHOT, because deciding `offered` is the only thing this
+ * cache does with it — everything else about the channel is a passenger.
+ *
+ * The passenger is not hypothetical: the storefront's shell also needs the
+ * shop name (the title suffix) and whether the read was authoritative at all
+ * (#1347). Both come from the SAME `activeChannel` document this cache already
+ * fetches, and they have to arrive on the same snapshot or the shell can pair
+ * one window's languages with another window's name. A second cached read
+ * would put a second round-trip on the first byte of every route, which is
+ * precisely what the docblock above rules out.
+ *
+ * Generic rather than widening {@link ChannelLocales} with those fields: this
+ * module is the LOCALE grammar's cache, its type is consumed by
+ * `decideRequestLocale`, and a shop name has no business in either. The
+ * constraint states exactly what is required of a snapshot, and anything
+ * further rides through untouched.
+ */
+export interface ChannelLocalesCache<T extends ChannelLocales = ChannelLocales> {
+  /** The current snapshot; refreshes behind the response once it is stale. */
+  get(): Promise<T>;
+  /**
+   * The channel AND whether it offers `candidate`, from a single snapshot. A
+   * miss against an existing snapshot forces one live reload before answering
+   * `false` — bounded to once per window, see the module docblock.
+   */
+  resolve(candidate: string | null): Promise<ChannelLocalesResolution<T>>;
+}
+export interface ChannelLocalesCacheOptions {
+  ttlMs?: number;
+  /** Injected clock — the specs drive time instead of waiting on it. */
+  now?: () => number;
+}
+/** The window S1 fixes for the channel-language snapshot. */
+export const CHANNEL_LOCALES_TTL_MS = 60_000;
+export function createChannelLocalesCache<T extends ChannelLocales>(
+  load: () => Promise<T>,
+  options: ChannelLocalesCacheOptions = {},
+): ChannelLocalesCache<T> {
+  const ttlMs = options.ttlMs ?? CHANNEL_LOCALES_TTL_MS;
+  const now = options.now ?? Date.now;
+  let snapshot: T | null = null;
+  let loadedAt = 0;
+  /** When a MISS last forced a reload, so the next miss can be answered free. */
+  let missReloadedAt: number | null = null;
+  /**
+   * The in-flight load, shared by every caller that arrives during it. A
+   * server handles requests concurrently; without this, a cold start under
+   * load would fan one expired snapshot out into N identical round-trips.
+   */
+  let inFlight: Promise<T> | null = null;
+  function isFresh(): boolean {
+    return snapshot !== null && now() - loadedAt < ttlMs;
+  }
+  async function reload(): Promise<T> {
+    if (inFlight) return inFlight;
+    inFlight = load();
+    try {
+      const loaded = await inFlight;
+      snapshot = loaded;
+      loadedAt = now();
+      return loaded;
+    } finally {
+      // Cleared on failure too, so a transient backend error does not pin a
+      // rejected promise as the permanent answer for every later request.
+      inFlight = null;
+    }
+  }
+  /**
+   * Refresh behind the response. The rejection is swallowed deliberately: the
+   * caller already has a usable snapshot, and an unhandled rejection here
+   * would take down the process for a failure that costs the request nothing.
+   * `loadedAt` is untouched on failure, so the next request retries.
+   */
+  function refreshInBackground(): void {
+    if (inFlight) return;
+    void reload().catch(() => undefined);
+  }
+  async function get(): Promise<T> {
+    if (snapshot !== null) {
+      if (!isFresh()) refreshInBackground();
+      return snapshot;
+    }
+    // Cold start only: there is nothing to serve, so this one awaits — and may
+    // reject. The caller decides what an unreachable backend serves on a cold
+    // process; this module will not invent a language set.
+    return reload();
+  }
+  async function resolve(candidate: string | null): Promise<ChannelLocalesResolution<T>> {
+    const hadSnapshot = snapshot !== null;
+    const channel = await get();
+    if (candidate === null) return { channel, offered: false };
+    if (channel.languageCodes.includes(candidate)) return { channel, offered: true };
+    // Loaded live in this very call, so the miss is authoritative — reloading
+    // again would ask the same question twice.
+    if (!hadSnapshot) return { channel, offered: false };
+    // Bounded: one miss-driven reload per window, however many junk locales
+    // arrive inside it.
+    if (missReloadedAt !== null && now() - missReloadedAt < ttlMs) {
+      return { channel, offered: false };
+    }
+    // Stamped on the ATTEMPT, not the result. Stamping after the await would
+    // leave the bound disarmed whenever the loader rejects — exactly the
+    // condition it exists to protect: a backend already failing, being asked
+    // again by every junk locale that arrives.
+    missReloadedAt = now();
+    // A failed miss-reload answers from the snapshot we already had rather
+    // than rejecting: this runs inside the document shell, where a throw is a
+    // site-wide 500 rather than a degraded section.
+    const reloaded = await reload().catch(() => channel);
+    return { channel: reloaded, offered: reloaded.languageCodes.includes(candidate) };
+  }
+  return { get, resolve };
+}

package/templates/storefront/src/lib/locale/grammar.ts ADDED Viewed

@@ -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/src/lib/locale/localized-path.ts ADDED Viewed

@@ -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);
+}