@forgecart/cli 2.202609240732.0 → 2.202609290106.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202609240732.0",
+  "version": "2.202609290106.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/src/app/pages/[slug]/page.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 import { cache } from 'react';
 
+import { pageContentClaims } from '../../../lib/content/page-metadata';
 import { PageFields } from '../../../lib/content/render-fields';
 import { resolvePage } from '../../../lib/content/resolve-page';
 import {
@@ -11,7 +12,6 @@ import {
   type PageGroup,
 } from '../../../lib/forgecart';
 import { getRequestLocale } from '../../../lib/locale/request-binding';
-import { staticPathsByLocale } from '../../../lib/seo/alternates';
 import { routeMetadata } from '../../../lib/seo/metadata';
 import type { RouteSearchParams } from '../../../lib/seo/noindex';
 import { PAGE_ROUTE_PREFIX } from '../../../lib/seo/sitemap-entries';
@@ -53,14 +53,16 @@ const pageForRequest = cache(
 );
 
 /**
- * A page's indexability comes from the same resolution the route acts on, so
- * the tag and the status can never disagree about what this URL is.
+ * A page's metadata comes from the same resolution the route acts on, so the
+ * head and the status can never disagree about what this URL is.
  *
- * The title is the merchant's own page name — the one piece of per-page SEO
- * that exists today. A page has no per-language SEO sidecar yet (#1375), so
- * there is no description, no social image, and the alternate set is the
- * structural one: a page route is the SAME address in every language the
- * channel offers, exactly like `/products`.
+ * Its CONTENT claims — title, description, social card, alternates and
+ * indexability — are the record's per-language SEO sidecar (#1375), decided in
+ * `lib/content/page-metadata.ts` by the rules the product route uses: the
+ * definition's `seoSources` mapping and the merchant's stored overrides arrive
+ * already resolved into each language, and a language with no copy of its own
+ * renders as a fallback that claims nothing (noindex, no canonical, never an
+ * hreflang alternate). This file only dispatches.
  */
 export async function generateMetadata({
   params,
@@ -73,16 +75,15 @@ export async function generateMetadata({
     await Promise.all([params, searchParams, getRequestLocale()]);
   const { group, entries } = await pageForRequest(slug);
   const resolution = resolvePage({ requestedRoute: slug, group, entries });
+  const pathname = `${PAGE_ROUTE_PREFIX}/${slug}`;
 
   return routeMetadata({
     binding,
     shopName,
     channelResolved,
-    pathname: `${PAGE_ROUTE_PREFIX}/${slug}`,
-    pathsByLocale: staticPathsByLocale(languageCodes, `${PAGE_ROUTE_PREFIX}/${slug}`),
+    pathname,
     searchParams: resolvedSearchParams,
-    title: resolution.kind === 'ok' ? resolution.group.name : null,
-    contentIndexable: resolution.kind === 'ok',
+    ...pageContentClaims(resolution, { locale: binding.locale, languageCodes, pathname }),
   });
 }
 

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -61,11 +61,11 @@ const productForRequest = cache(async (slug: string) => getProductBySlug(slug));
  * merchant's own `indexable: false`. Redirect and notFound need no directive —
  * their metadata is discarded with the response body.
  *
- * This is the one route whose title, description and social image are the
- * MERCHANT's rather than the template's: they come from the per-language SEO
- * sidecar through `entityMetadata`, already resolved into the request's
- * language by the shop API, so a German product page carries a German title
- * without this file knowing anything about translation.
+ * Like an ACF page's (`/pages/<route>`, #1375), this route's title, description
+ * and social image are the MERCHANT's rather than the template's: they come
+ * from the per-language SEO sidecar through `entityMetadata`, already resolved
+ * into the request's language by the shop API, so a German product page
+ * carries a German title without this file knowing anything about translation.
  */
 export async function generateMetadata({
   params,

package/templates/storefront/src/app/products/page.tsx

@@ -18,7 +18,8 @@ import type { RouteSearchParams } from '../../lib/seo/noindex';
  * `<h1>`: structural surfaces are not translated content, and inventing a
  * translation layer for them here would put a second, weaker source of truth
  * beside the shop API's. The pages whose titles a merchant actually cares
- * about — products — take theirs from the localized SEO sidecar.
+ * about — products and the merchant's own ACF pages — take theirs from the
+ * localized SEO sidecar.
  */
 export async function generateMetadata({
   searchParams,

package/templates/storefront/src/lib/content/page-metadata.ts

@@ -0,0 +1,113 @@
+import { staticPathsByLocale } from '../seo/alternates';
+import { entityMetadata } from '../seo/metadata';
+import type { MetadataInput, SeoMetaRow } from '../seo/metadata';
+import { advertisedPathsByLocale, ownContentRow } from '../seo/sidecar';
+import type { SeoLanguageRow } from '../seo/sidecar';
+import type { PageResolution } from './resolve-page';
+
+/**
+ * What a page URL claims about its own CONTENT (#1375, epic launch#54 D11 as
+ * amended by ruling ANSWER-1547Z) — the half of `/pages/<route>`'s metadata the
+ * page decides, as a value the route spreads into `routeMetadata`.
+ *
+ * Every claim is read off the page record's per-language SEO sidecar, through
+ * the SAME rules the product route uses, so a page and a product can never
+ * disagree about what a language without its own copy is (ruling Q6: product
+ * parity):
+ *
+ *  - title, description and social image come from `entityMetadata` — the
+ *    sidecar's row for this locale, the title falling back to the page
+ *    definition's own name, and the social card armed only by a STORED image
+ *    (a page's mapped image never arms it);
+ *  - the alternates cluster is the route's address in every language the
+ *    channel offers, narrowed to the languages that hold content of their own
+ *    (`advertisedPathsByLocale`) — an untranslated language is never an
+ *    hreflang alternate, and its own copy claims no canonical;
+ *  - indexability is the merchant's choice for a language with its own copy,
+ *    and `false` for a derived fallback (`ownContentRow`).
+ *
+ * PURE BY CONTRACT, for the reason `resolve-page.ts` is: the template-spec
+ * imports it by relative path, which is what makes these claims a table of
+ * vectors rather than something only a running pod can exercise. The inputs
+ * are structural for the same reason — the generated query types satisfy them,
+ * so the scaffold's own compiler proves the assignment.
+ */
+
+/** One language of a page record's sidecar, as these claims read it. */
+export type PageSeoRow = SeoLanguageRow & SeoMetaRow;
+
+/** The definition fields these claims read. */
+export interface ClaimingPageGroup {
+  /** The merchant's name for the page — the title when the sidecar names none. */
+  readonly name: string;
+}
+
+/**
+ * The record fields these claims read.
+ *
+ * The sidecar is optional AND nullable because the generated selection is: the
+ * shop API answers `seo: null` for a definition that is not a page kind. A
+ * resolution that reached its `ok` arm has already proven the definition IS a
+ * page, so a null here means the API and the definition disagree — read, like a
+ * missing language row, as "no language has content of its own".
+ */
+export interface ClaimingPageEntry {
+  readonly seo?: { readonly languages: readonly PageSeoRow[] } | null;
+}
+
+/** Where the page is being rendered, and every language its route exists in. */
+export interface PageClaimsContext {
+  /** The locale this page is being rendered in. */
+  locale: string;
+  /** Every language the channel offers — the languages a page ROUTE exists in. */
+  languageCodes: readonly string[];
+  /** The locale-STRIPPED address of this page (`/pages/<route>`). */
+  pathname: string;
+}
+
+/** The content half of a page's `MetadataInput`, every key decided. */
+export type PageContentClaims = Required<
+  Pick<
+    MetadataInput,
+    'pathsByLocale' | 'title' | 'description' | 'socialImage' | 'contentIndexable'
+  >
+>;
+
+/** The sidecar a record without one is read as: no language holds its own copy. */
+const NO_SIDECAR: NonNullable<ClaimingPageEntry['seo']> = { languages: [] };
+
+/**
+ * A URL that is not a page claims nothing about content: no name of its own, no
+ * alternates, and not indexable — the refusal the product route states for a
+ * missing product, stated here rather than left to whatever Next does with the
+ * head of a page that answers 404.
+ */
+const NOT_FOUND_CLAIMS: PageContentClaims = {
+  pathsByLocale: {},
+  title: null,
+  description: null,
+  socialImage: null,
+  contentIndexable: false,
+};
+
+/**
+ * Decide the content claims of one page URL from the resolution the route acts
+ * on — the same value that decides its status, so the head and the response
+ * can never disagree about what the URL is.
+ */
+export function pageContentClaims(
+  resolution: PageResolution<ClaimingPageGroup, ClaimingPageEntry>,
+  { locale, languageCodes, pathname }: PageClaimsContext,
+): PageContentClaims {
+  if (resolution.kind === 'notFound') return NOT_FOUND_CLAIMS;
+
+  const seo = resolution.entry.seo ?? NO_SIDECAR;
+  const entity = entityMetadata({ name: resolution.group.name, seo }, locale);
+  return {
+    pathsByLocale: advertisedPathsByLocale(staticPathsByLocale(languageCodes, pathname), seo),
+    title: entity.title,
+    description: entity.description,
+    socialImage: entity.socialImage,
+    contentIndexable: ownContentRow(seo, locale)?.indexable ?? false,
+  };
+}

package/templates/storefront/src/lib/forgecart.ts

@@ -133,9 +133,9 @@ import type {
   RefreshShippingRateGroupsMutation,
   SeoEntriesQuery,
   ShopEligiblePaymentProvidersQuery,
-  ShopEntriesQuery,
   ShopOrderByCodeQuery,
   ShopPageByRouteQuery,
+  ShopPageEntriesQuery,
   ShopProductQuery,
 } from '@forgecart/sdk/shop';
 
@@ -163,8 +163,12 @@ export type SeoEntryFeedPage = SeoEntriesQuery['seoEntries'];
 export type PageGroup = NonNullable<ShopPageByRouteQuery['pageByRoute']>;
 /** One field definition of a page — the label and the identity of a value. */
 export type PageFieldDefinition = PageGroup['fieldDefinitions'][number];
-/** One record of a page, with its values and repeater rows. */
-export type PageEntry = ShopEntriesQuery['entries']['items'][number];
+/**
+ * One record of a page, with its values, its repeater rows and its per-language
+ * SEO sidecar (#1375) — the page's title, description, indexability and
+ * alternates are read off `seo` by `lib/content/page-metadata.ts`.
+ */
+export type PageEntry = ShopPageEntriesQuery['entries']['items'][number];
 /** One stored value, discriminated by `__typename` over the ACF field types. */
 export type PageFieldValue = PageEntry['fields'][number];
 
@@ -298,14 +302,17 @@ export async function getPageByRoute(route: string): Promise<PageGroup | null> {
 }
 
 /**
- * The record a page URL serves, as a list of at most one (#1934).
+ * The record a page URL serves, as a list of at most one (#1934), with its SEO
+ * sidecar (#1375).
  *
  * `take: 1` because a route is ONE address; `createdAt ASC` because that makes
  * it the page's ORIGINAL record. The shop API's own default is `createdAt
  * DESC`, and inheriting it would mean that adding a second record to a live
  * page silently REPLACES what the URL has been serving — a content change
  * nobody asked for, made by a create. Ascending is a stable answer: the page a
- * merchant published stays the page at that URL.
+ * merchant published stays the page at that URL. The bound also prices the
+ * sidecar: `seo` costs one per-language resolve per returned record, which is
+ * why it rides this one-record read (`ShopPageEntries`) and never a listing.
  *
  * The list may come back EMPTY, and that is the feature's whole 404 arm: every
  * storefront read is fenced to published content, so a page whose only records
@@ -315,7 +322,7 @@ export async function getPageByRoute(route: string): Promise<PageGroup | null> {
 export async function getPageEntries(definitionCode: string): Promise<PageEntry[]> {
   const { entries } = await (
     await getShopClient()
-  ).acf.shopEntries({
+  ).acf.shopPageEntries({
     definitionCode,
     options: { take: 1, sort: [{ field: 'createdAt', direction: 'ASC' }] },
   });

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

@@ -98,7 +98,10 @@ export function buildAlternates({
  * Structural routes are not translated content: `/products` is the same route
  * in every cluster, so every offered language has it and each one is a genuine
  * alternate. That is the opposite of a product, where membership has to be
- * earned per language (see `productPathsByLocale`).
+ * earned per language (see `productPathsByLocale`). An ACF page sits between
+ * the two: its route is this same address in every language, but its content
+ * is translated, so the map is narrowed by the page's sidecar before it is
+ * advertised (`advertisedPathsByLocale`, #1375).
  */
 export function staticPathsByLocale(
   languageCodes: readonly string[],

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

@@ -168,12 +168,19 @@ export interface SeoMetaRow {
   description?: string | null;
   /** Armed exactly when a social image is STORED — never derived. */
   socialEnabled?: boolean;
+  /**
+   * The stored social image, else an ACF page entry's MAPPED image (#1375).
+   * Not an opt-in by itself: a mapped image arrives here with the flag down.
+   */
   socialImage?: { preview: string } | null;
 }
 
 /** An entity that carries a per-language SEO sidecar. */
 export interface EntityMetadataSource {
-  /** The entity's own display name, already in the request's language. */
+  /**
+   * The entity's own display name — a product's, already in the request's
+   * language, or an ACF page definition's.
+   */
   name: string;
   seo: { languages: readonly SeoMetaRow[] };
 }
@@ -188,19 +195,24 @@ export interface EntityMetadata {
 /**
  * The sidecar's answer for one locale.
  *
- * `title` falls back to the entity's own name rather than to nothing: the
- * sidecar's derived default IS the translated name, so a null title means the
- * sidecar had nothing to say, not that the page has no name. `description`
- * does NOT fall back to the entity's body — a product description is rich text
- * from the dashboard, and putting raw HTML in a `<meta name="description">` is
- * how a store ends up with `<p>` in its search results. The sidecar already
- * derives a first-sentence description when the merchant sets none; if even
- * that is absent there is nothing honest to emit.
+ * `title` falls back to the entity's own name rather than to nothing: a null
+ * title means the sidecar had nothing to say — a product's derived default IS
+ * its translated name, and an ACF page whose definition maps no title source
+ * derives none (#1375) — not that the page has no name. `description` does NOT
+ * fall back to the entity's body — a product description is rich text from the
+ * dashboard, and putting raw HTML in a `<meta name="description">` is how a
+ * store ends up with `<p>` in its search results. The sidecar already derives
+ * one wherever an honest source exists (a product's first sentence, a page's
+ * mapped description or excerpt); if even that is absent there is nothing
+ * honest to emit, and the page inherits the shell's.
  *
- * The social image requires BOTH the armed flag and an actual image. They are
- * supposed to agree — `socialEnabled` is defined as "a social image is stored"
- * — but a storefront that assumes an invariant it cannot enforce is one API
- * change away from emitting an `og:image` with no URL.
+ * The social image requires BOTH the armed flag and an actual image, and the
+ * flag is the opt-in. For a product the two agree by construction, but an ACF
+ * page entry's row legitimately carries its MAPPED image with the flag down
+ * (#1375: a mapped image fills the image slot and never arms social) — and even
+ * where they are supposed to agree, a storefront that assumes an invariant it
+ * cannot enforce is one API change away from emitting an `og:image` with no
+ * URL.
  */
 export function entityMetadata(source: EntityMetadataSource, locale: string): EntityMetadata {
   const row = source.seo.languages.find((entry) => entry.languageCode === locale);

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