@forgecart/cli 2.202608300703.0 → 2.202609190800.0

package/templates/storefront/src/lib/seo/noindex.ts

@@ -0,0 +1,218 @@
+import { getPublicOrigin } from './public-origin';
+
+/**
+ * The ONE noindex mechanism (#1347, epic launch#54 W1-9).
+ *
+ * Indexability is decided here and expressed in exactly one way: the `robots`
+ * field of Next's metadata. The middleware stays a zero-logic rewrite stage and
+ * never emits an `X-Robots-Tag`, because two mechanisms mean two answers — and
+ * the one a crawler honours is whichever it happens to read first. A merchant
+ * debugging "why is my page not indexed" must have exactly one place to look.
+ *
+ * `follow: true` throughout: a page we do not want INDEXED is still a page
+ * whose links we want CRAWLED. `noindex, nofollow` on the cart would strand
+ * every product reachable only from it.
+ */
+
+/**
+ * Routes that are never indexable, at any origin.
+ *
+ * `/verify` and `/reset-password` (#1472) are here for a stronger reason than
+ * the funnel pair: they are only ever reached through a one-shot token in a
+ * private e-mail. A crawler that indexed one would publish a page whose only
+ * meaningful state is reached with a credential it cannot have, and would
+ * FETCH the URLs it found — spending real tokens on a shopper's behalf.
+ * `robots.ts` derives its `Disallow` list from this set, which is what keeps
+ * a well-behaved crawler from making that request at all.
+ *
+ * `/register` (#1471) is here for the FUNNEL reason instead. It is an ordinary
+ * addressable page — a shopper reaches it from a link on this storefront, and
+ * it stays locale-prefixable unlike the two link routes — but it is a form with
+ * no content of its own, identical for every visitor, so there is nothing for a
+ * search result to be about. One entry covers every language: this set is
+ * matched against the locale-STRIPPED path.
+ */
+export const NOINDEX_PATHS: readonly string[] = [
+  '/cart',
+  '/checkout',
+  '/verify',
+  '/reset-password',
+  '/register',
+];
+
+/**
+ * Query keys that turn a URL into a VIEW of a page rather than the page.
+ *
+ * Each names a distinct duplicate-content source: `sort` reorders a listing
+ * whose canonical form is the unsorted one, `fc-exp` pins an experiment arm,
+ * and `fc-preview` renders unpublished content. Indexing any of them competes
+ * with the page's own canonical URL using near-identical copy.
+ *
+ * Presence is the signal, not the value — `?fc-preview` and `?fc-preview=1`
+ * are equally a preview URL.
+ */
+export const NOINDEX_QUERY_KEYS: readonly string[] = ['sort', 'fc-exp', 'fc-preview'];
+
+/** Next's shape for a page's resolved `searchParams`. */
+export type RouteSearchParams = Record<string, string | string[] | undefined>;
+
+/**
+ * The facts that refuse indexing for EVERY route of a deployment, including
+ * ones this template has never heard of.
+ *
+ * Separated from the per-route input because these two arms are what the root
+ * layout's floor is made of, and the floor and the routes MUST decide them
+ * identically: Next merges page metadata over the layout's, so a page that
+ * evaluated fewer arms than the floor would publish itself straight through
+ * it. One rule, two callers — see {@link deploymentRefusesIndexing}.
+ */
+export interface DeploymentPosture {
+  /** The deployment's public origin, or null when it has none. */
+  publicOrigin: string | null;
+  /**
+   * Whether the channel behind this render was established (#1347, hand-off
+   * from #1346).
+   *
+   * `false` means the storefront does not know what it is serving — an
+   * unconfigured scaffold, or a cold process whose backend it could not reach
+   * — so it is rendering a GUESSED language set. Undefined means the caller
+   * has no opinion, which is not the same as `true`: as with
+   * `contentIndexable`, a caller that never checked must not thereby assert.
+   */
+  channelResolved?: boolean;
+}
+
+/** Everything the indexability decision reads. */
+export interface NoindexInput extends DeploymentPosture {
+  /** The locale-STRIPPED route path (`/de/cart` is decided as `/cart`). */
+  pathname: string;
+  /** The request's query, when the caller is a page. Layouts never receive one. */
+  searchParams?: RouteSearchParams;
+  /**
+   * The CONTENT's own indexability, for routes that have resolved it — the
+   * merchant's explicit choice (`SeoMetaLanguage.indexable`) or the fact that
+   * this language is showing a derived fallback copy rather than real content.
+   *
+   * Undefined means the route has no content-level opinion, which is not the
+   * same as `true`: a route that never resolved one must not be able to assert
+   * indexability it never checked.
+   */
+  contentIndexable?: boolean;
+}
+
+/**
+ * The robots directive shape, declared here rather than imported as Next's
+ * `Metadata['robots']`.
+ *
+ * This module is PURE — it imports nothing from `next` — for the same reason
+ * `lib/locale/grammar.ts` is: a rule that decides what search engines may index
+ * has to be unit-testable as a table of vectors, and the template-spec cannot
+ * resolve `next` (the template carries its own `node_modules`, outside the
+ * workspace). A structural type keeps the rules testable while remaining
+ * assignable to `Metadata['robots']` at every call site.
+ */
+export interface RobotsDirective {
+  index: boolean;
+  follow: boolean;
+}
+
+/** The directive for anything we have decided not to have indexed. */
+export const NOINDEX_ROBOTS: RobotsDirective = { index: false, follow: true };
+
+/**
+ * Whether the DEPLOYMENT refuses indexing, whatever route is being rendered.
+ *
+ * Both arms are the same shape of refusal: the storefront cannot answer
+ * authoritatively, so it declines to make a claim rather than making a guess a
+ * crawler would act on. Neither is about the page — a page cannot opt out of
+ * either — which is why they are the floor the root layout applies and the
+ * first thing every route's own decision consults.
+ */
+export function deploymentRefusesIndexing({
+  publicOrigin,
+  channelResolved,
+}: DeploymentPosture): boolean {
+  // No stable public address ⇒ no claim this deployment makes could be true
+  // tomorrow. This arm is what makes a preview pod safe by default.
+  if (publicOrigin === null) return true;
+
+  // The channel behind this render was never established, so the language set,
+  // the default language and every URL derived from them are a fallback GUESS
+  // (`lib/locale/channel-locales-loader.ts`). The page still renders — the
+  // prewarm contract requires it, and a site-wide 5xx is the worst thing a
+  // crawler can be shown — but a guess must not be indexed under an address
+  // that will serve something else once the backend answers.
+  return channelResolved === false;
+}
+
+/**
+ * Whether this route must not be indexed.
+ *
+ * Pure and total, so the rule set is unit-testable without a running Next.
+ * Ordered cheapest-first; every arm is independently sufficient.
+ */
+export function shouldNoindex({
+  pathname,
+  searchParams,
+  publicOrigin,
+  channelResolved,
+  contentIndexable,
+}: NoindexInput): boolean {
+  if (deploymentRefusesIndexing({ publicOrigin, channelResolved })) return true;
+
+  // The content itself says no — either the merchant set it, or this language
+  // is showing a derived copy. Either way it outranks the route's own opinion:
+  // a product page is normally the most indexable thing a storefront has, and
+  // that is exactly why an explicit refusal has to survive it.
+  if (contentIndexable === false) return true;
+
+  const route = normalizeRoute(pathname);
+  if (NOINDEX_PATHS.some((path) => route === path || route.startsWith(`${path}/`))) return true;
+
+  if (!searchParams) return false;
+  return NOINDEX_QUERY_KEYS.some((key) => searchParams[key] !== undefined);
+}
+
+/**
+ * Trailing slashes are equivalent addresses for the same route, and a nested
+ * route under a noindex parent inherits the decision (`/checkout/payment` is
+ * no more indexable than `/checkout`). The root is left alone — `/` normalizing
+ * to `''` would make every `startsWith` test true.
+ */
+function normalizeRoute(pathname: string): string {
+  if (pathname.length > 1 && pathname.endsWith('/')) return pathname.slice(0, -1);
+  return pathname;
+}
+
+/**
+ * The `robots` metadata for a page, or undefined when it is indexable.
+ *
+ * Undefined rather than an explicit `index: true` so an indexable page emits no
+ * robots tag at all, which is what "no opinion" means to a crawler and keeps
+ * the assertion surface to the pages that genuinely make one.
+ *
+ * Callers pass their own route literal rather than reading the current path:
+ * under the locale rewrite the rendered route and the browser's URL differ, and
+ * a route file already knows which route it is with certainty.
+ *
+ * Every page MUST go through this rather than hand-rolling a robots value.
+ * Next merges page metadata over the layout's, and a key that is PRESENT with
+ * an undefined value still overrides — so a page returning a bare
+ * `robots: undefined` would punch a hole straight through the preview-posture
+ * floor and publish itself from an ephemeral host. This function cannot do
+ * that: its first arm is the same origin check the floor uses, so page and
+ * floor can never disagree.
+ */
+export function routeRobots(
+  pathname: string,
+  searchParams?: RouteSearchParams,
+  contentIndexable?: boolean,
+): RobotsDirective | undefined {
+  const noindex = shouldNoindex({
+    pathname,
+    searchParams,
+    publicOrigin: getPublicOrigin(),
+    contentIndexable,
+  });
+  return noindex ? NOINDEX_ROBOTS : undefined;
+}

package/templates/storefront/src/lib/seo/public-origin.ts

@@ -0,0 +1,166 @@
+/**
+ * The storefront's public origin (#1347, epic launch#54 W1-9).
+ *
+ * This one value decides whether the deployment is ENTITLED to make claims to
+ * a search engine. A storefront reachable only at an ephemeral preview URL has
+ * no stable address to be canonical about, so every absolute claim it could
+ * emit — canonical, hreflang, sitemap entry — would name a host that stops
+ * existing when the pod is reaped. The posture that follows is "assert
+ * nothing": see `noindex.ts`, which reads this and nothing else to decide the
+ * deployment-wide floor.
+ *
+ * The value is supplied by `forgecart init` (`--public-origin`), which writes
+ * `FORGECART_PUBLIC_ORIGIN` for a published storefront and OMITS it for
+ * preview pods. Absence is therefore a real, expected, meaningful state — not
+ * a misconfiguration to warn about.
+ *
+ * ABSENT and REJECTED are different states and are reported differently
+ * (#1677). Both produce a null origin and therefore `Disallow: /`, and for a
+ * long time both did so in complete silence — so a deployment configured with,
+ * say, a scheme-less `DEPLOYMENT_URL_TEMPLATE` built, deployed, served 200s,
+ * rendered correctly to a human, and told every crawler not to index it, with
+ * no error anywhere. The first signal was an unexplained traffic collapse.
+ *
+ * The asymmetry that caused it: this module is a SECURITY boundary and must
+ * reject anything it cannot vouch for, while the OPERATOR needs to know their
+ * configuration was rejected. Silence served the first obligation and betrayed
+ * the second. The rejections below are unchanged — they were always correct —
+ * and a rejected value is now stated on stdout instead of being swallowed.
+ */
+
+/** Why a present value could not be used as a public origin. */
+export type PublicOriginRejection =
+  | 'not-a-url'
+  | 'unsupported-scheme'
+  | 'carries-path'
+  | 'carries-query-or-fragment';
+
+/**
+ * The three genuinely different states of this variable.
+ *
+ * A discriminated union rather than `string | null`, because the null was
+ * doing two incompatible jobs: "this is a preview deployment, as intended" and
+ * "your configuration is broken". Collapsing them is what made the second one
+ * invisible.
+ */
+export type PublicOriginResolution =
+  | { kind: 'absent' }
+  | { kind: 'ok'; origin: string }
+  | { kind: 'rejected'; raw: string; reason: PublicOriginRejection };
+
+/**
+ * Classify a raw `FORGECART_PUBLIC_ORIGIN`.
+ *
+ * Never throws: this runs inside `robots.txt` and every page's metadata, where
+ * a throw would surface as a 500 on the one route whose entire job is to answer
+ * conservatively — strictly worse than the `Disallow: /` a refusal produces.
+ *
+ * Rejected on purpose:
+ * - non-http(s) schemes — `javascript:` and `data:` in a canonical `<link>` or
+ *   a `Sitemap:` line are injection surfaces, not addresses;
+ * - anything carrying a path, query or fragment — an origin with a path
+ *   silently produces double-pathed canonicals (`https://x/shop/products` from
+ *   origin `https://x/shop`), which is a duplicate-content bug that looks
+ *   correct in review.
+ */
+export function resolvePublicOrigin(raw: string | undefined): PublicOriginResolution {
+  const trimmed = raw?.trim();
+  if (!trimmed) return { kind: 'absent' };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { kind: 'rejected', raw: trimmed, reason: 'not-a-url' };
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { kind: 'rejected', raw: trimmed, reason: 'unsupported-scheme' };
+  }
+  // Unreachable for http/https — they are WHATWG "special" schemes, for which
+  // an empty host is a parse failure that the catch above already took. Kept
+  // as a belt on a security boundary, and classified as malformed because that
+  // is what an http URL with no host is.
+  if (!parsed.host) return { kind: 'rejected', raw: trimmed, reason: 'not-a-url' };
+  // `new URL('https://x')` normalizes pathname to '/', so '/' is the only
+  // pathname a bare origin can have.
+  if (parsed.pathname !== '/') {
+    return { kind: 'rejected', raw: trimmed, reason: 'carries-path' };
+  }
+  if (parsed.search || parsed.hash) {
+    return { kind: 'rejected', raw: trimmed, reason: 'carries-query-or-fragment' };
+  }
+
+  return { kind: 'ok', origin: `${parsed.protocol}//${parsed.host}` };
+}
+
+/**
+ * The origin, or null when there is none to use.
+ *
+ * Kept as the shape every caller wants — `noindex.ts` and `alternates.ts` ask
+ * "do we have an address", not "why not". The classification above is for the
+ * one caller that has to REPORT, immediately below.
+ */
+export function parsePublicOrigin(raw: string | undefined): string | null {
+  const resolution = resolvePublicOrigin(raw);
+  return resolution.kind === 'ok' ? resolution.origin : null;
+}
+
+/** What an operator needs to hear, per rejection reason. */
+function rejectionDetail(reason: PublicOriginRejection): string {
+  switch (reason) {
+    case 'not-a-url':
+      // The scheme hint is safe to give unconditionally: every value this
+      // reason can describe fails to parse as an absolute URL, and every
+      // absolute URL this module would accept begins with one of those two
+      // schemes. It is also the likeliest cause by far — a deployment template
+      // written as a host pattern rather than a URL pattern.
+      return 'it is not a parseable absolute URL (an origin must begin with the http:// or https:// scheme)';
+    case 'unsupported-scheme':
+      return 'it has no http:// or https:// scheme (a bare host is not an origin)';
+    case 'carries-path':
+      return 'it carries a path — an origin is scheme + host only';
+    case 'carries-query-or-fragment':
+      return 'it carries a query or fragment — an origin is scheme + host only';
+  }
+}
+
+/**
+ * Cached because the origin is deployment identity: it cannot change without
+ * a new process, and every rendered route asks for it.
+ *
+ * Resolved LAZILY rather than at module load. A module-level constant is
+ * evaluated when the bundle is first imported, which for a `next build` can be
+ * build time — freezing whatever the builder's environment happened to hold
+ * into the shipped bundle. Storefronts are built once and run with per-channel
+ * env supplied later, so a build-time read would bake "no origin" into every
+ * published store permanently.
+ */
+let cached: { readonly value: string | null } | null = null;
+
+/**
+ * The deployment's public origin, or null when it has none.
+ *
+ * A REJECTED value is reported here, exactly once per process — the memo makes
+ * that free, and once is right: this is deployment identity, so repeating it
+ * per request would bury the line it is trying to surface. An ABSENT value
+ * says nothing, because a preview pod with no origin is working as designed
+ * and a warning there would train operators to ignore this channel.
+ *
+ * `console.error` and not a thrown error, for the reason the classifier above
+ * does not throw either: the storefront must keep serving. It just must stop
+ * doing so silently.
+ */
+export function getPublicOrigin(): string | null {
+  if (cached === null) {
+    const resolution = resolvePublicOrigin(process.env.FORGECART_PUBLIC_ORIGIN);
+    if (resolution.kind === 'rejected') {
+      console.error(
+        `[public-origin] FORGECART_PUBLIC_ORIGIN is set to ${JSON.stringify(resolution.raw)} but was REJECTED: ${rejectionDetail(resolution.reason)}. ` +
+          'This storefront will serve "Disallow: /" and every page will be noindex until it is corrected — the site stays reachable, but no search engine will index it.',
+      );
+    }
+    cached = { value: resolution.kind === 'ok' ? resolution.origin : null };
+  }
+  return cached.value;
+}

package/templates/storefront/src/lib/seo/redirect-plan.ts

@@ -0,0 +1,86 @@
+import type { RedirectRule } from '../../seo/redirects';
+import { isUnprefixedPath, parseLocalePath } from '../locale/grammar';
+
+/**
+ * The rename-redirect rule (#1347, epic launch#54 W1-9).
+ *
+ * Separate from the table it reads (`src/seo/redirects.ts`) on purpose. That
+ * file is edited by a merchant and rewritten by the agent on every rename; if
+ * the matching logic lived beside the data, an edit meant to add one row could
+ * silently take the rule with it. Data there, machinery here, and the boundary
+ * is what makes an automated edit to that file structurally safe.
+ *
+ * Pure, like every other rule in this layer — the middleware imports
+ * `next/server` and is therefore unreachable by the template spec project, so
+ * a decision left in the middleware could only ever be exercised by booting a
+ * server. This is the same split `planLocaleRewrite` uses.
+ */
+
+/** How many links of a redirect chain are followed before giving up. */
+export const MAX_REDIRECT_HOPS = 8;
+
+/**
+ * Where this request should be sent, or null when it should be served.
+ *
+ * Returns the FINAL destination of a chain rather than the next link in it.
+ * `/a → /b → /c` answers one 308 to `/c`: each additional hop costs a
+ * round-trip, and search engines both dilute the signal they carry across a
+ * chain and stop following one entirely after a handful of links, so a chain
+ * served link-by-link quietly loses exactly what the redirect existed to save.
+ *
+ * A cycle resolves to null — the page is served (or 404s) instead. That is the
+ * strictly better failure: a browser caught in a redirect loop shows an error
+ * page for every URL in the cycle, while a missing redirect costs only the one
+ * URL that was renamed. The hop cap makes the same choice for a chain too long
+ * to be worth following.
+ */
+export function planRedirect(pathname: string, table: readonly RedirectRule[]): string | null {
+  // Infrastructure routes are not pages and must never be redirected: a
+  // merchant entry for `/robots.txt` or `/api/...` would break crawling or the
+  // SDK proxy, and nothing downstream would report it.
+  if (isUnprefixedPath(pathname)) return null;
+
+  const { localeCandidate, pathname: routePath } = parseLocalePath(pathname);
+
+  const seen = new Set<string>([routePath]);
+  let current = routePath;
+  for (let hop = 0; hop < MAX_REDIRECT_HOPS; hop += 1) {
+    const next = table.find((rule) => normalize(rule.from) === current);
+    if (!next) {
+      // Unmoved on the first look means there is nothing to do at all; unmoved
+      // later means the chain ended, and `current` is where it ended.
+      return current === routePath ? null : prefixed(current, localeCandidate);
+    }
+    const target = normalize(next.to);
+    if (seen.has(target)) return null;
+    seen.add(target);
+    current = target;
+  }
+  return null;
+}
+
+/**
+ * The redirect re-enters the language it left from.
+ *
+ * The candidate is re-attached unvalidated, deliberately: middleware is
+ * zero-fetch by contract and cannot know which languages the channel offers.
+ * `/zz/summer-sale` therefore redirects to `/zz/promotions/summer`, which the
+ * layout then 404s — the same answer `/zz/promotions/summer` would have given
+ * if it had been requested directly, which is the point. Validity is decided
+ * in one place, and it is not this one.
+ */
+function prefixed(path: string, localeCandidate: string | null): string {
+  return localeCandidate === null ? path : `/${localeCandidate}${path}`;
+}
+
+/**
+ * A table entry as an address, so `/summer-sale/` and `/summer-sale` are the
+ * same entry. Matching is otherwise EXACT — no prefixes, no patterns: a rule
+ * that matched `/summer-sale/tents` because `/summer-sale` moved would drag
+ * along URLs nobody decided to move.
+ */
+function normalize(path: string): string {
+  const trimmed = path.trim();
+  const rooted = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  return rooted.length > 1 && rooted.endsWith('/') ? rooted.slice(0, -1) : rooted;
+}

package/templates/storefront/src/lib/seo/resolve-path.ts

@@ -0,0 +1,126 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+
+/**
+ * The language-first slug law for product URLs (#1347, epic launch#54 W1-9).
+ *
+ * Every product URL must end in one of four honest answers, and which one is
+ * decided HERE rather than in the route, so the rule is a table of vectors
+ * instead of a branch nobody can enumerate.
+ *
+ * The whole law rests on one backend guarantee (#1339): a product fetched
+ * through a locale's own client answers with THAT locale's current slug in
+ * `slug`, and `resolvedLanguageCode` names the language whose current *or
+ * previous* slug actually matched the lookup. So a stale slug, a renamed
+ * product's previous slug, and a request that used another language's slug all
+ * arrive here as the same observable fact — `product.slug` differs from what
+ * was asked for — and all three deserve the same answer: one permanent redirect
+ * to the address this locale actually uses.
+ *
+ * That collapse is deliberate. Treating them as three cases would mean three
+ * lookups of "which language was this slug from", and the backend has already
+ * done that work.
+ */
+
+/** One language's row in the SEO sidecar (#1341), narrowed to what the law reads. */
+export interface SeoLanguageRow {
+  languageCode: string;
+  /** Whether this language has real content, as opposed to a derived fallback. */
+  translated: boolean;
+  /** The merchant's explicit indexability choice for this language. */
+  indexable: boolean;
+}
+
+/** One language's slug for a product. */
+export interface ProductTranslationRow {
+  languageCode: string;
+  slug: string;
+}
+
+/** The product fields the law reads — a structural subset of the SDK's product. */
+export interface ResolvableProduct {
+  /** The CURRENT slug in the requesting locale's language. */
+  slug: string;
+  /** Every language's slug for this product, translated or not. */
+  translations: readonly ProductTranslationRow[];
+  seo: { languages: readonly SeoLanguageRow[] };
+}
+
+/**
+ * The languages that may be ADVERTISED for this product, mapped to their paths.
+ *
+ * The intersection of two different facts, and taking either alone is a bug:
+ * `translations` says a language has a SLUG, `seo.languages[].translated` says
+ * it has CONTENT. A language can have the first without the second — that is
+ * exactly the fallback copy — and advertising it as an hreflang alternate would
+ * point a crawler at a derived page and pull it into a reciprocal set it does
+ * not belong to.
+ */
+export function productPathsByLocale(product: ResolvableProduct): Record<string, string> {
+  const translated = new Set(
+    product.seo.languages.filter((row) => row.translated).map((row) => row.languageCode),
+  );
+  const paths: Record<string, string> = {};
+  for (const row of product.translations) {
+    if (translated.has(row.languageCode)) paths[row.languageCode] = `/products/${row.slug}`;
+  }
+  return paths;
+}
+
+/** What the route must do with this URL. */
+export type PathResolution =
+  | { kind: 'ok'; indexable: boolean }
+  | { kind: 'redirect'; to: string }
+  | { kind: 'fallback' }
+  | { kind: 'notFound' };
+
+export interface ResolveProductPathInput {
+  /** The slug exactly as it appeared in the URL. */
+  requestedSlug: string;
+  /** The product as fetched through THIS locale's client, or null when absent. */
+  product: ResolvableProduct | null;
+  binding: LocaleBinding;
+}
+
+/**
+ * Decide the honest answer for a product URL.
+ *
+ * Ordered so that each arm can assume the ones above it did not fire.
+ */
+export function resolveProductPath({
+  requestedSlug,
+  product,
+  binding,
+}: ResolveProductPathInput): PathResolution {
+  // No product answered to this slug in any language — a real 404, not a
+  // rendered "not found" page at a 200. A crawler indexes a soft-404; it drops
+  // a real one.
+  if (!product) return { kind: 'notFound' };
+
+  // The locale addresses this product by a different slug than the one asked
+  // for. One redirect covers a stale slug, a renamed product's previous slug
+  // (#1339's `previousSlug`), and a request that used another language's slug:
+  // the backend already resolved which, and the answer is the same regardless.
+  if (product.slug !== requestedSlug) {
+    return { kind: 'redirect', to: localizedPath(`/products/${product.slug}`, binding) };
+  }
+
+  const row = product.seo.languages.find((entry) => entry.languageCode === binding.locale);
+
+  // No row for this language means the shopper is looking at a derived copy —
+  // real content in another language, shown here so the URL is not a dead end.
+  // It renders, but it makes no claims: noindex, no hreflang, no canonical.
+  // Indexing it would put near-duplicate copy in competition with the language
+  // that genuinely has the content.
+  //
+  // A MISSING row is treated exactly like `translated: false`. The sidecar is
+  // supposed to carry one entry per channel language, so absence means the
+  // sidecar and the channel disagree — and the safe reading of a disagreement
+  // is the one that makes no claim.
+  if (!row || !row.translated) return { kind: 'fallback' };
+
+  // Real content in this language. The merchant's own indexability choice is
+  // the last word, and it rides on the resolution rather than being re-derived
+  // by the caller — one lookup, one answer.
+  return { kind: 'ok', indexable: row.indexable };
+}

package/templates/storefront/src/lib/seo/scaffolded-routes.ts

@@ -0,0 +1,83 @@
+import 'server-only';
+
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { SCAFFOLDED_ROUTES_DIR, parseScaffoldedRoute } from './sitemap-entries';
+import type { StaticRoute } from './sitemap-entries';
+
+/**
+ * Reads the rows scaffolded pages dropped into `src/seo/routes.d/` (#1347).
+ *
+ * Separate from `sitemap-entries.ts` because it touches the filesystem, and
+ * that module is imported by the template spec project — an `node:fs` read
+ * there would move the sitemap's rules out of the vector layer and into
+ * something only a running server can exercise. Rules there, IO here.
+ *
+ * A directory rather than a generated barrel file for the same reason it is a
+ * directory on the writing side: an import list would have to be read, edited
+ * and rewritten, which two concurrent scaffolds can do in an order that loses
+ * one of them. Reading a directory has no such step.
+ */
+
+/**
+ * Every scaffolded route, or an empty list.
+ *
+ * Never throws, and that is deliberate: this runs inside `sitemap.xml`, where
+ * the alternatives to an empty list are a 5xx (which tells a crawler to come
+ * back to a broken document) or a half-built sitemap presented as complete. A
+ * missing directory is the NORMAL state — a scaffold that has created no pages
+ * has none — so it is not even a warning.
+ *
+ * A fragment that does not parse is skipped and named on stdout. Skipping is
+ * the honest half: the file is written by another process and editable by
+ * hand, so a malformed one is a bug in the writer, and guessing what it meant
+ * would publish a URL nobody chose. Naming it is the other half — a route
+ * silently missing from the sitemap is exactly the failure this feature
+ * exists to prevent, so it must not be able to happen quietly.
+ */
+export async function readScaffoldedRoutes(): Promise<StaticRoute[]> {
+  const directory = join(process.cwd(), SCAFFOLDED_ROUTES_DIR);
+
+  let files: string[];
+  try {
+    files = (await readdir(directory)).filter((name) => name.endsWith('.json'));
+  } catch {
+    // Absent (nothing scaffolded yet) or unreadable. Both mean the same thing
+    // to a sitemap: there are no scaffolded routes to list.
+    return [];
+  }
+
+  // Async, and read in parallel, because this runs on a request path: a
+  // merchant with a few hundred scaffolded pages is a few hundred file reads,
+  // and doing them synchronously would block the event loop for every other
+  // request in flight. The 60s window makes it rare, not free.
+  const named = files.sort((a, b) => a.localeCompare(b));
+  const parsed = await Promise.all(named.map((name) => readOne(join(directory, name))));
+
+  const routes: StaticRoute[] = [];
+  for (const [index, route] of parsed.entries()) {
+    if (route === null) {
+      console.warn(
+        `[sitemap] ignoring ${SCAFFOLDED_ROUTES_DIR}/${named[index]} — it is not a {"path","indexable"} row, so the page it names is NOT in the XML sitemap.`,
+      );
+      continue;
+    }
+    routes.push(route);
+  }
+  return routes;
+}
+
+/**
+ * One fragment, or null when it is unusable for any reason — unreadable,
+ * not JSON, or not the shape. The caller reports; this only decides.
+ */
+async function readOne(path: string): Promise<StaticRoute | null> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf8'));
+  } catch {
+    return null;
+  }
+  return parseScaffoldedRoute(parsed);
+}