@forgecart/cli 2.202609221621.0 → 2.202609282317.0

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

@@ -1,5 +1,7 @@
 import { localizedPath } from '../locale/localized-path';
 import type { LocaleBinding } from '../locale/localized-path';
+import { advertisedPathsByLocale, ownContentRow } from './sidecar';
+import type { SeoSidecar } from './sidecar';
 
 /**
  * The language-first slug law for product URLs (#1347, epic launch#54 W1-9).
@@ -22,15 +24,6 @@ import type { LocaleBinding } from '../locale/localized-path';
  * 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;
@@ -43,28 +36,22 @@ export interface ResolvableProduct {
   slug: string;
   /** Every language's slug for this product, translated or not. */
   translations: readonly ProductTranslationRow[];
-  seo: { languages: readonly SeoLanguageRow[] };
+  seo: SeoSidecar;
 }
 
 /**
  * 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.
+ * A product's ADDRESS is earned per language — `translations` says a language
+ * has a SLUG — and the sidecar's intersection rule (`advertisedPathsByLocale`)
+ * keeps only the ones that also have CONTENT, so a slug-bearing fallback copy
+ * is never advertised as an hreflang alternate.
  */
 export function productPathsByLocale(product: ResolvableProduct): Record<string, string> {
-  const translated = new Set(
-    product.seo.languages.filter((row) => row.translated).map((row) => row.languageCode),
+  const addresses = Object.fromEntries(
+    product.translations.map((row) => [row.languageCode, `/products/${row.slug}`]),
   );
-  const paths: Record<string, string> = {};
-  for (const row of product.translations) {
-    if (translated.has(row.languageCode)) paths[row.languageCode] = `/products/${row.slug}`;
-  }
-  return paths;
+  return advertisedPathsByLocale(addresses, product.seo);
 }
 
 /** What the route must do with this URL. */
@@ -105,19 +92,13 @@ export function resolveProductPath({
     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.
+  // No content of this language's own (`ownContentRow` — a missing row reads
+  // as untranslated) means the shopper is looking at a derived copy. 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' };
+  const row = ownContentRow(product.seo, binding.locale);
+  if (row === null) 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

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

@@ -0,0 +1,75 @@
+import type { PathsByLocale } from './alternates';
+
+/**
+ * What the per-language SEO sidecar says about an entity's COPIES (#1341,
+ * ACF pages #1375): which languages hold content of their own, and whether
+ * this locale's copy may be indexed.
+ *
+ * One rule for every entity that carries a sidecar. A product and an ACF page
+ * entry ask the same two questions of the same rows, and two spellings of the
+ * answer would let a product and a page disagree about what an untranslated
+ * language is — one advertising a fallback copy the other refuses to (#1375
+ * ruling Q6: pages take product parity).
+ *
+ * PURE, for the reason every module under `lib/seo/` is: the template-spec
+ * imports it by relative path from outside the scaffold, so nothing reachable
+ * from here may need the template's Next toolchain.
+ */
+
+/** One language's row in the sidecar, narrowed to what these claims read. */
+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;
+}
+
+/** An entity's sidecar, as far as these claims read it. */
+export interface SeoSidecar {
+  languages: readonly SeoLanguageRow[];
+}
+
+/**
+ * This locale's row when the locale holds content of its own, or null when the
+ * shopper is looking at a derived fallback copy — real content in another
+ * language, shown here so the URL is not a dead end.
+ *
+ * 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.
+ */
+export function ownContentRow(seo: SeoSidecar, locale: string): SeoLanguageRow | null {
+  const row = seo.languages.find((entry) => entry.languageCode === locale);
+  return row?.translated ? row : null;
+}
+
+/**
+ * The languages that may be ADVERTISED for this entity, mapped to their paths:
+ * every language that has an address in `addresses` AND content of its own.
+ *
+ * The intersection of two different facts, and taking either alone is a bug.
+ * An address says the language can be REACHED — a product's per-language slug,
+ * or a page route that exists in every language the channel offers; the
+ * sidecar's `translated` says the language 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.
+ *
+ * `indexable: false` does NOT remove a language: the merchant suppressing a
+ * page they own leaves the translation in place, so its siblings must keep
+ * naming it or the cluster's reciprocity breaks. Indexability is `noindex.ts`'s
+ * job, not this map's. The order is the addresses' own.
+ */
+export function advertisedPathsByLocale(
+  addresses: PathsByLocale,
+  seo: SeoSidecar,
+): Record<string, string> {
+  const translated = new Set(
+    seo.languages.filter((row) => row.translated).map((row) => row.languageCode),
+  );
+  return Object.fromEntries(
+    Object.entries(addresses).filter(([languageCode]) => translated.has(languageCode)),
+  );
+}

package/templates/storefront/src/lib/seo/site-verification.ts

@@ -0,0 +1,98 @@
+import 'server-only';
+
+import { cache } from 'react';
+
+import { getShopClient } from '../forgecart';
+import type { SiteVerificationMeta } from './metadata';
+
+/**
+ * What the channel's SEO providers need this storefront to serve (#1530).
+ *
+ * A provider proves the merchant owns this address by asking them to place a
+ * token on it. The platform mints that token per account and per origin, and
+ * this read is the storefront's half of the handshake: it asks the shop API
+ * what to serve, and `metadata.ts` turns each descriptor into one
+ * `<meta name content>` tag. Nothing here knows which provider minted what —
+ * the NAME arrives in the descriptor, so a second provider is a server change
+ * and no template change at all.
+ *
+ * Only `META` placements are served. The mechanism rides in the descriptor
+ * precisely so that a provider verifying some other way — a DNS record, a file
+ * at a path this template does not route — cannot have its token silently
+ * rendered as a meta tag, which would be a placement that looks made and is
+ * not.
+ *
+ * PER REQUEST, and no further. React's `cache()` collapses the callers of one
+ * render into a single read; there is deliberately no TTL and no process memo
+ * above it. A verifier makes ONE fetch, and a token re-minted while a replica
+ * still serves a cached copy of the old one is a verification that fails with
+ * every part of the system reporting health — the same reason
+ * `sitemap-cache.ts`'s window is safe (a stale URL list costs a crawl) and one
+ * here would not be.
+ *
+ * Failure is ALWAYS an empty list, never a throw. This read happens inside the
+ * root layout's `generateMetadata`, structurally outside every Suspense
+ * boundary (D8), so a throw here is a 500 on every route of the store — and
+ * what is lost instead is one meta tag whose absence the platform already
+ * detects and retries on its next sync. An unconfigured scaffold reaches the
+ * same arm: `getShopClient()` throws when `.env` carries no coordinates, and
+ * the prewarm contract says a storefront with no configuration must SERVE.
+ */
+
+/** The answer whenever there is nothing honest to serve. */
+const NONE: readonly SiteVerificationMeta[] = [];
+
+/**
+ * The one mechanism this template can satisfy — a tag in the document it
+ * renders. Compared against the descriptor's own value rather than assumed.
+ */
+const META_METHOD = 'META';
+
+/**
+ * How long the document shell may wait for this read.
+ *
+ * The same bound, for the same reason, as the channel read in
+ * `locale/channel-locales-loader.ts`: the shell has no Suspense boundary above
+ * it, so an unbounded wait holds the whole document open with nothing to time
+ * it out. Past this the storefront serves without the tag, which is the lesser
+ * of the two failures by a wide margin.
+ */
+const VERIFICATION_READ_TIMEOUT_MS = 2_000;
+
+/**
+ * The placements this storefront must serve, for THIS request.
+ *
+ * Read through the generated SDK like every other shop-API call in the
+ * template — there are no hand-written query documents here, which is what
+ * keeps the storefront's reads and the API's schema from drifting apart.
+ *
+ * The request's own client is used rather than one pinned to the channel
+ * default: the answer is the same in every language, so the cheaper of two
+ * correct options wins, and that is the socket this render already has open.
+ */
+export const getSiteVerifications = cache(async (): Promise<readonly SiteVerificationMeta[]> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      readPlacements(),
+      new Promise<readonly SiteVerificationMeta[]>((resolve) => {
+        timer = setTimeout(() => {
+          resolve(NONE);
+        }, VERIFICATION_READ_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    // The template's sanctioned catch: an external SDK call, wrapped at its
+    // call site, exactly as `forgecart.ts#runAccountOperation` and
+    // `shop-session.ts` do. Nothing is swallowed that anyone here could act on
+    // — the platform's sync ladder is what observes an unserved placement.
+    return NONE;
+  } finally {
+    clearTimeout(timer);
+  }
+});
+
+async function readPlacements(): Promise<readonly SiteVerificationMeta[]> {
+  const { seoSiteVerifications } = await (await getShopClient()).seo.seoSiteVerifications();
+  return seoSiteVerifications.filter((placement) => placement.method === META_METHOD);
+}

package/templates/storefront/src/server/forge/live-revision.ts

@@ -0,0 +1,158 @@
+/**
+ * The revision this server is SERVING, for the dev-only error beacon (#847).
+ *
+ * A browser error report used to be stamped with whatever revision was live at
+ * the moment the pod RECEIVED it (`storefront-beacon.service.ts`, `atRevision:
+ * this.target.getLiveRevision()`). A promote that advances between serve and
+ * throw therefore made the report blame the NEW revision for the OLD one's
+ * crash, and the receiver's same-revision fold then marked a healthy tree
+ * DEGRADED. The cure is to resolve the revision where the page is RENDERED —
+ * here — stamp it into the HTML, and let the report carry it back.
+ *
+ * WHERE THE RAW VALUE COMES FROM (settled by ruling ANSWER-0425Z-agent-004):
+ * the pod's supervisor publishes the serving sha to a DERIVED, read-only file
+ * inside the workspace's `.forge/` island by the same act that re-publishes its
+ * runtime state, and this module reads that file per request. Explicitly NOT a
+ * beacon hop on the render path, and explicitly NOT an environment variable —
+ * one dev-server process outlives many promotes, so a value handed to it at
+ * spawn time could only ever name the revision it BOOTED at, which is this
+ * module's own bug reintroduced one layer down. The retired
+ * `.forge/liveRevision` sentinel (appendix design law 5, §7.3) is not that file
+ * and is not read here; see `FORGE_SERVING_REVISION_FILE` below.
+ *
+ * The split is still the shape of the feature:
+ *
+ *  - `parseLiveRevision` is PURE and fully specified by vectors. It owns the
+ *    whole question of what counts as a revision, independently of where the
+ *    raw value came from.
+ *  - `readLiveRevisionSource` is the ONE impure line — the file read, and
+ *    nothing else in the template touches the filesystem for this.
+ *
+ * FAIL OPEN, ALWAYS. Every unresolvable case answers `null`, which means no
+ * meta tag, which means an untagged report, which means the receiver keeps its
+ * existing behaviour (confirm probe included). A page must never fail to render
+ * because the revision is unknown, so there is no throw on this path: an
+ * unknown revision is an ordinary, expected state — every non-storefront pod,
+ * and every pod before its bootstrap primes the ref — not a fault.
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The meta tag's `name`. The CONTRACT between this module (which resolves the
+ * value), `app/layout.tsx` (which emits the tag) and
+ * `components/ForgeErrorBeacon.tsx` (which reads it back out of the DOM at send
+ * time). The beacon is a CLIENT component and must not import a `src/server/`
+ * module, so it repeats the literal with a comment pointing here — the same way
+ * the `/__forge_beacon` URL is repeated across this feature's three producers
+ * rather than shared through an import.
+ */
+export const FORGE_REVISION_META = 'forge-revision';
+
+/**
+ * The workspace-relative path the pod's supervisor publishes the serving sha to.
+ *
+ * MIRRORS `SERVING_REVISION_FILE` in
+ * `app/workspace-manager/src/supervisor/workspace-supervisor.service.ts`, whose
+ * doc carries the full reasoning for the path — `.forge/` because that island is
+ * the board repo's ignore authority and a file anywhere else would dirty the
+ * serving tree on every publish, and NEITHER retired legacy path, both of which
+ * the pod's own bootstrap deletes at boot. It is repeated here instead of
+ * imported because this template is scaffolding DATA — copied verbatim into a
+ * merchant's project, with its own `package.json` and toolchain, outside that
+ * monorepo's build graph — exactly like the `/__forge_beacon` URL. Nothing in a
+ * compiler connects the two copies: a rename on either side would silently stop
+ * the file from being found and every report would go back to untagged, so
+ * `tool/storefront-template-spec/src/live-revision.spec.ts` compares them.
+ *
+ * Resolved against `process.cwd()`, which IS the workspace root the supervisor
+ * writes into: it spawns `npm run dev` with `cwd` = the configured workspace
+ * path (resolved in `process-supervisor.service.ts`, handed to the child in
+ * `managed-process.ts`), and `npm` runs the script from the package root without
+ * moving it. `lib/seo/scaffolded-routes.ts` already reads a workspace-relative
+ * path this way on a request path.
+ */
+export const FORGE_SERVING_REVISION_FILE = '.forge/serving-revision';
+
+/**
+ * A revision is a full git commit sha and nothing else: exactly 40 hex digits,
+ * case-insensitive, surrounding whitespace trimmed. That is precisely what the
+ * supervisor's source produces — `git rev-parse --verify refs/heads/serving^{commit}`
+ * (`board-git.service.ts`) — so anything else reaching here is not a revision
+ * and must not be stamped.
+ *
+ * The rejections are the load-bearing half, because a stamped non-sha is worse
+ * than no stamp at all: the receiver compares the payload's value to the live
+ * revision by EQUALITY to decide whether to fold without probing, so a
+ * placeholder that could also BE the live value would skip the probe on
+ * evidence that means nothing. `'unversioned'` is the concrete instance of that
+ * hazard — it is literally what the supervisor reports for a pod with no board
+ * repo, so an unversioned pod stamping `'unversioned'` would match itself and
+ * defeat the guard. Rejecting it here is what makes the receiver's equality
+ * check safe.
+ *
+ * @param raw the candidate revision, exactly as obtained from the source
+ * @returns the normalised lowercase sha, or `null` when `raw` is not one
+ */
+export function parseLiveRevision(raw: string): string | null {
+  const trimmed = raw.trim();
+  if (!/^[0-9a-f]{40}$/i.test(trimmed)) return null;
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Obtain the raw revision value — THE ONE impure line in this module.
+ *
+ * A plain read of {@link FORGE_SERVING_REVISION_FILE}, the file the pod's
+ * supervisor re-publishes on every serving advance. There is deliberately NO
+ * environment fallback: the ruling excluded one, and an env value read here
+ * would be strictly worse than nothing, because the only process that could
+ * supply it is the dev-server's own spawn — which happens once and then serves
+ * every later promote under the revision it started at.
+ *
+ * Read per CALL, never captured at module scope, for the same reason:
+ * a value snapshotted at first import would keep stamping the boot revision
+ * forever. `lib/seo/sitemap-cache.ts` carries the same getter-not-a-constant
+ * reasoning.
+ *
+ * SYNCHRONOUS, unlike `lib/seo/scaffolded-routes.ts`, which reads on a request
+ * path asynchronously and explains why. That reasoning does not transfer: it
+ * fans out over a directory of arbitrarily many JSON fragments, whereas this is
+ * ONE page-cached read of at most 41 bytes, sitting beside an awaited channel
+ * read in the same `generateMetadata` that dwarfs it. Going async would cost
+ * `resolveLiveRevision` its synchronous signature for nothing measurable.
+ *
+ * Every failure answers `null`, and the ordinary case IS a failure: the file is
+ * absent on every pod before its first publish, on a non-storefront workspace
+ * that publishes none, and in a merchant's own checkout of this template, where
+ * no supervisor exists at all. Absent, unreadable and garbage all mean the same
+ * thing here — no tag, an untagged report, the receiver's existing behaviour —
+ * so there is nothing worth distinguishing between them and nothing worth
+ * throwing over on a render path.
+ */
+export function readLiveRevisionSource(): string | null {
+  try {
+    return readFileSync(join(process.cwd(), FORGE_SERVING_REVISION_FILE), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The revision to stamp into this response, or `null` when it cannot be
+ * resolved. Composes the source and the acceptance rule and holds no policy of
+ * its own, so the ruling can move the source without touching any caller.
+ *
+ * The DEV-ONLY gate lives at the call site (`app/layout.tsx`), not here — the
+ * placement every other file in this feature uses (`ForgeErrorBeacon.tsx`,
+ * `app/%5F%5Fforge_beacon/route.ts` and `instrumentation.ts` each check
+ * `NODE_ENV` at their own top), which is what lets a production build
+ * dead-code-eliminate the whole path rather than merely reach a function that
+ * answers `null`.
+ */
+export function resolveLiveRevision(): string | null {
+  const raw = readLiveRevisionSource();
+  if (raw === null) return null;
+  return parseLiveRevision(raw);
+}