@forgecart/cli 2.202608300703.0 → 2.202609190800.0

package/templates/storefront/src/lib/seo/json-ld.ts

@@ -0,0 +1,266 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+import { toPriceString } from '../money';
+
+/**
+ * Structured data (#1347, epic launch#54 W1-9) — entity data only, ever.
+ *
+ * JSON-LD is where a storefront is most tempted to assert things it cannot
+ * know. `Organization` wants a legal name, a logo and `sameAs` social
+ * profiles; `WebSite` wants a `SearchAction` sitelinks searchbox. None of that
+ * is derivable from a product row — a template emitting it would be inventing
+ * facts about a real business, and an unearned `SearchAction` is a claim about
+ * a search endpoint that may not exist. Those types are refused **at the type
+ * level** rather than by review: {@link JsonLdNode} is a closed union, so an
+ * `Organization` node does not compile, and no amount of later editing can
+ * reintroduce one without deleting this sentence first.
+ *
+ * Everything here is pure — no `next`, no SDK types — so the shapes are a
+ * table of vectors instead of something only a rendered page could exercise.
+ * Inputs are declared structurally for the same reason.
+ */
+
+/** The only context this template speaks. */
+type SchemaContext = 'https://schema.org';
+
+/** schema.org availability, spelled as the full IRIs Google expects. */
+export const IN_STOCK = 'https://schema.org/InStock';
+export const OUT_OF_STOCK = 'https://schema.org/OutOfStock';
+
+export interface OfferNode {
+  '@type': 'Offer';
+  /** A decimal string in the currency's own digits — never a formatted price. */
+  price: string;
+  priceCurrency: string;
+  availability: typeof IN_STOCK | typeof OUT_OF_STOCK;
+  sku?: string;
+  url: string;
+}
+
+export interface ProductNode {
+  '@context': SchemaContext;
+  '@type': 'Product';
+  name: string;
+  description?: string;
+  image?: string;
+  sku?: string;
+  /** The page's canonical — the same URL its `<link rel="canonical">` claims. */
+  url: string;
+  offers: OfferNode[];
+}
+
+export interface ListItemNode {
+  '@type': 'ListItem';
+  position: number;
+  name: string;
+  /** Absent on the last crumb: it IS this page, and a self-link adds nothing. */
+  item?: string;
+}
+
+export interface BreadcrumbListNode {
+  '@context': SchemaContext;
+  '@type': 'BreadcrumbList';
+  itemListElement: ListItemNode[];
+}
+
+export interface PersonNode {
+  '@type': 'Person';
+  name: string;
+}
+
+/**
+ * A blog post, as the #1347 allowlist admits it (#1992): every field is entity
+ * data the post's own record carries — its name, its dek, its stamps and its
+ * cover — and nothing about the business publishing it.
+ */
+export interface BlogPostingNode {
+  '@context': SchemaContext;
+  '@type': 'BlogPosting';
+  headline: string;
+  description?: string;
+  /** Absolute, or absent: a crawler reads a relative image as no image at all. */
+  image?: string;
+  /** ISO-8601, as the shop API stamps the post's `createdAt` / `updatedAt`. */
+  datePublished: string;
+  dateModified: string;
+  /** The page's canonical — the same URL its `<link rel="canonical">` claims. */
+  url: string;
+  author?: PersonNode;
+}
+
+/**
+ * The allowlist, as a type.
+ *
+ * `Organization`, `WebSite`, `SearchAction`, `logo` and `sameAs` are absent by
+ * construction — not filtered at runtime, which would be a check someone can
+ * disable, but unrepresentable. `BlogPosting` joined with #1992 for #1041's
+ * content routes, which have a post record behind every node; the promote
+ * verifier judges each node's SHAPE under `SEO_SCHEMA_BLOGPOSTING_INVALID`.
+ */
+export type JsonLdNode = ProductNode | BreadcrumbListNode | BlogPostingNode;
+
+/** One variant, as much of it as structured data has any business knowing. */
+export interface OfferableVariant {
+  sku?: string | null;
+  priceWithTax: number;
+  currencyCode: string;
+  stockOnHand: number;
+  enabled: boolean;
+}
+
+export interface ProductJsonLdInput {
+  name: string;
+  description?: string | null;
+  image?: string | null;
+  canonical: string;
+  variants: readonly OfferableVariant[];
+}
+
+/**
+ * The `Product` node for a product page.
+ *
+ * `url` is the CANONICAL, not the requested address: structured data that
+ * named a redirecting or query-bearing URL would compete with the page's own
+ * canonical for the same content, which is the duplicate-content bug the
+ * canonical exists to prevent.
+ *
+ * Disabled variants are not offered. An offer is a statement that something
+ * can be bought, and a disabled variant cannot be.
+ */
+export function productJsonLd({
+  name,
+  description,
+  image,
+  canonical,
+  variants,
+}: ProductJsonLdInput): ProductNode {
+  const offers = variants
+    .filter((variant) => variant.enabled)
+    .map(
+      (variant): OfferNode => ({
+        '@type': 'Offer',
+        price: toPriceString(variant.priceWithTax, variant.currencyCode),
+        priceCurrency: variant.currencyCode,
+        availability: variant.stockOnHand > 0 ? IN_STOCK : OUT_OF_STOCK,
+        ...(variant.sku ? { sku: variant.sku } : {}),
+        url: canonical,
+      }),
+    );
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name,
+    // Omitted rather than emitted empty: an absent field is "not stated", an
+    // empty one is a stated blank, and only the first is true here.
+    ...(description ? { description } : {}),
+    ...(image ? { image } : {}),
+    url: canonical,
+    offers,
+  };
+}
+
+export interface BreadcrumbInput {
+  binding: LocaleBinding;
+  publicOrigin: string;
+  /** The trail's leaf — this page, named but not linked. */
+  leafName: string;
+  /** The structural ancestors, unprefixed; the locale is applied here. */
+  trail: readonly { name: string; path: string }[];
+}
+
+/**
+ * The `BreadcrumbList` for a page, locale-aware and absolute.
+ *
+ * The ancestor paths are localized through the same `localizedPath` the visible
+ * breadcrumbs use, so the trail a crawler reads and the trail a shopper clicks
+ * are the same trail — in the same language. A German page whose structured
+ * data pointed at the English catalog would be describing a different site.
+ */
+export function breadcrumbJsonLd({
+  binding,
+  publicOrigin,
+  leafName,
+  trail,
+}: BreadcrumbInput): BreadcrumbListNode {
+  const itemListElement: ListItemNode[] = trail.map(
+    (crumb, index): ListItemNode => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: crumb.name,
+      item: `${publicOrigin}${localizedPath(crumb.path, binding)}`,
+    }),
+  );
+
+  itemListElement.push({
+    '@type': 'ListItem',
+    position: trail.length + 1,
+    name: leafName,
+  });
+
+  return { '@context': 'https://schema.org', '@type': 'BreadcrumbList', itemListElement };
+}
+
+export interface BlogPostingJsonLdInput {
+  headline: string;
+  description?: string | null;
+  image?: string | null;
+  /** The post's `createdAt` as the shop API stamps it — ISO-8601. */
+  publishedAt: string;
+  /** The post's `updatedAt`, the same way. */
+  updatedAt: string;
+  canonical: string;
+  authorName?: string | null;
+}
+
+/** An `http(s)` URL with an origin — the only image a crawler attaches to a post. */
+const ABSOLUTE_HTTP_URL = /^https?:\/\/\S+$/i;
+
+/**
+ * The `BlogPosting` node for a blog post — the ONE such node a post page emits.
+ *
+ * Every optional field is omitted rather than emitted empty, for the reason
+ * {@link productJsonLd} gives, and the image is omitted unless it is absolute:
+ * a relative `image` is read by a crawler as no image, and by the promote
+ * verifier as a defect (`SEO_SCHEMA_BLOGPOSTING_INVALID`), so emitting it would
+ * turn an undescribed cover into a refused promote. The dates pass through as
+ * the shop API stamped them — already ISO-8601 — because re-parsing a timestamp
+ * to re-print it can only lose precision or throw.
+ */
+export function blogPostingJsonLd({
+  headline,
+  description,
+  image,
+  publishedAt,
+  updatedAt,
+  canonical,
+  authorName,
+}: BlogPostingJsonLdInput): BlogPostingNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BlogPosting',
+    headline,
+    ...(description ? { description } : {}),
+    ...(image && ABSOLUTE_HTTP_URL.test(image) ? { image } : {}),
+    datePublished: publishedAt,
+    dateModified: updatedAt,
+    url: canonical,
+    ...(authorName ? { author: { '@type': 'Person', name: authorName } } : {}),
+  };
+}
+
+/**
+ * A node as the text of a `<script type="application/ld+json">`.
+ *
+ * `<` becomes its JSON unicode escape, and that single substitution is the
+ * whole escape rule — necessary AND sufficient. Inside a script element only
+ * three sequences change how the parser behaves (`</script`, `<script` and
+ * `<!--`), every one of them begins with `<`, and a JSON parser decodes
+ * `<` straight back to `<`. So a product description containing
+ * `</script>` — rich text from the dashboard, which is exactly where such a
+ * string comes from — cannot close the element early and turn the rest of the
+ * document into markup.
+ */
+export function serializeJsonLd(node: JsonLdNode): string {
+  return JSON.stringify(node).replace(/</g, '\\u003c');
+}

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

@@ -0,0 +1,323 @@
+import type { LocaleBinding } from '../locale/localized-path';
+import { buildAlternates } from './alternates';
+import type { Alternates, PathsByLocale } from './alternates';
+import { NOINDEX_ROBOTS, deploymentRefusesIndexing, shouldNoindex } from './noindex';
+import type { DeploymentPosture, RobotsDirective, RouteSearchParams } from './noindex';
+import { getPublicOrigin } from './public-origin';
+
+/**
+ * What every page SAYS it is (#1347, epic launch#54 W1-9).
+ *
+ * One composer for every route's `generateMetadata`, rather than each route
+ * assembling its own object. The reason is not tidiness: a page's title, its
+ * canonical, its hreflang set, its robots directive and its social card are
+ * five claims about the SAME address, and a route that builds them separately
+ * can emit any subset — a title with no canonical, an og:url that disagrees
+ * with the canonical, hreflang on a page marked noindex. Nothing in the
+ * template would notice. Built together, they cannot disagree.
+ *
+ * PURE, and it imports nothing from `next` — the same constraint `noindex.ts`
+ * and `alternates.ts` carry, for the same reason: the storefront template ships
+ * with its own `node_modules`, so a module that imports `next` is unreachable
+ * from the template-spec project and its rules stop being vectors. The shapes
+ * below are structural and assignable to Next's `Metadata` at the call sites;
+ * a production `next build` is what proves that, and it is part of this
+ * slice's acceptance.
+ *
+ * Three deliberate renames from the signature the issue sketches
+ * (`{locale, pathsByLocale, title, description, image?, noindex?}`):
+ *
+ *  - `locale` → `binding`, the template's own name for the (rendering locale,
+ *    channel default) pair every path helper already takes.
+ *  - `image` → `socialImage`. The 2026-09-05 operator amendment makes the
+ *    social block opt-in on the entity's SOCIAL image specifically
+ *    (`SeoMetaLanguage.socialEnabled`), never on `featuredAsset.preview` —
+ *    and a parameter called `image` sitting next to a product that has a
+ *    featured asset is an invitation to wire exactly the wrong one.
+ *  - `noindex` → `contentIndexable`, matching `noindex.ts`'s existing
+ *    vocabulary. An inverted boolean named `noindex` passed into a rule set
+ *    whose fields mean the opposite is a defect waiting to be written.
+ */
+
+/** The floor the root layout emits — no route, so no route-specific claims. */
+export interface ShellMetadata {
+  title: string;
+  description: string;
+  robots?: RobotsDirective;
+}
+
+/**
+ * The Open Graph block. `type` is `website` for every storefront surface: a
+ * product is not an article, and og's own `product` type is not something a
+ * crawler treats better than a well-formed website card.
+ */
+export interface OpenGraphMetadata {
+  type: 'website';
+  locale: string;
+  alternateLocale?: string[];
+  url: string;
+  title: string;
+  description?: string;
+  images: string[];
+}
+
+export interface TwitterMetadata {
+  card: 'summary_large_image';
+  title: string;
+  description?: string;
+  images: string[];
+}
+
+/** One page's complete claim set. */
+export interface PageMetadata {
+  title: string;
+  description?: string;
+  robots?: RobotsDirective;
+  alternates?: Alternates;
+  openGraph?: OpenGraphMetadata;
+  twitter?: TwitterMetadata;
+}
+
+export interface ShellMetadataInput extends DeploymentPosture {
+  /** The merchant's shop name, or null/empty when unset. */
+  shopName?: string | null;
+}
+
+export interface MetadataInput extends DeploymentPosture {
+  binding: LocaleBinding;
+  /** Every language that genuinely has this content, mapped to its own path. */
+  pathsByLocale: PathsByLocale;
+  /** The locale-STRIPPED route this page IS. */
+  pathname: string;
+  /** The request's query, for the query-state noindex rules. */
+  searchParams?: RouteSearchParams;
+  shopName?: string | null;
+  /**
+   * This page's own name, or null when it has none of its own — the home page
+   * and the shell, whose name IS the store's.
+   */
+  title: string | null;
+  description?: string | null;
+  /**
+   * The entity's SOCIAL image. Its presence is the entire opt-in: unset means
+   * no `og:*` and no `twitter:*` tags at all (operator amendment 2026-09-05).
+   */
+  socialImage?: string | null;
+  /** The content's own indexability — see `noindex.ts`. */
+  contentIndexable?: boolean;
+}
+
+/**
+ * One language's row of the SEO sidecar (#1341), narrowed to what a page's
+ * metadata reads. A structural subset of the SDK's `SeoMetaLanguage`, for the
+ * same reason `resolve-path.ts` narrows it: the rule is then a table of
+ * vectors instead of something only a live channel can exercise.
+ */
+export interface SeoMetaRow {
+  languageCode: string;
+  title?: string | null;
+  description?: string | null;
+  /** Armed exactly when a social image is STORED — never derived. */
+  socialEnabled?: boolean;
+  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. */
+  name: string;
+  seo: { languages: readonly SeoMetaRow[] };
+}
+
+/** What the sidecar contributes to one locale's metadata. */
+export interface EntityMetadata {
+  title: string;
+  description: string | null;
+  socialImage: string | null;
+}
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function entityMetadata(source: EntityMetadataSource, locale: string): EntityMetadata {
+  const row = source.seo.languages.find((entry) => entry.languageCode === locale);
+  const socialImage = row?.socialEnabled === true ? (row.socialImage?.preview ?? null) : null;
+  return {
+    title: row?.title?.trim() ? row.title : source.name,
+    description: row?.description?.trim() ? row.description : null,
+    socialImage,
+  };
+}
+
+/** What a storefront is called when the merchant has not named it. */
+export const FALLBACK_SITE_TITLE = 'Storefront';
+
+/** The description every route inherits unless it carries its own. */
+export const SITE_DESCRIPTION = 'A ForgeCart channel storefront.';
+
+/**
+ * `<page name> | <shop name>`, and every degenerate case decided here.
+ *
+ * The suffix appears ONLY when the shop name is non-empty, so a channel that
+ * has not set one gets `Boots` rather than `Boots | ` — and a page with no
+ * name of its own gets the shop name alone rather than ` | Acme`. Whitespace
+ * counts as empty on both sides: a merchant who typed a space into the shop
+ * name field has not named their store, and `SeoMetaLanguage.title` is a
+ * merchant override that can be saved blank.
+ */
+export function pageTitle(name?: string | null, shopName?: string | null): string {
+  const page = name?.trim() ?? '';
+  const site = shopName?.trim() ?? '';
+  if (page === '') return site === '' ? FALLBACK_SITE_TITLE : site;
+  if (site === '') return page;
+  return `${page} | ${site}`;
+}
+
+/**
+ * The deployment-wide floor, applied by the root layout.
+ *
+ * A merchant who scaffolds `app/impressum/page.tsx` and writes no metadata
+ * still inherits this, so neither a preview pod nor a process that never
+ * reached its channel can leak a page through a route nobody remembered to
+ * annotate. It carries NO canonical and NO hreflang on purpose: those are
+ * claims about a specific address, and the layout does not know which route it
+ * is wrapping — a floor that named one would make every unannotated route
+ * claim to be the home page.
+ */
+export function buildShellMetadata({
+  shopName,
+  publicOrigin,
+  channelResolved,
+}: ShellMetadataInput): ShellMetadata {
+  const refuses = deploymentRefusesIndexing({ publicOrigin, channelResolved });
+  return {
+    title: pageTitle(null, shopName),
+    description: SITE_DESCRIPTION,
+    ...(refuses ? { robots: NOINDEX_ROBOTS } : {}),
+  };
+}
+
+/**
+ * One page's metadata.
+ *
+ * Keys carrying no value are OMITTED rather than set to `undefined`, and that
+ * is load-bearing: Next merges a page's metadata over the layout's, and a key
+ * that is PRESENT with an undefined value still wins the merge. A page
+ * returning `robots: undefined` would punch a hole straight through the floor
+ * above and publish itself from a preview host; a page returning
+ * `description: undefined` would blank the inherited one instead of keeping
+ * it. Absent means "inherit", which is what these routes actually mean.
+ */
+export function buildMetadata(input: MetadataInput): PageMetadata {
+  const { binding, pathsByLocale, publicOrigin, channelResolved } = input;
+  const title = pageTitle(input.title, input.shopName);
+  const description = input.description?.trim() ? input.description : null;
+
+  const noindex = shouldNoindex({
+    pathname: input.pathname,
+    searchParams: input.searchParams,
+    publicOrigin,
+    channelResolved,
+    contentIndexable: input.contentIndexable,
+  });
+
+  // An UNRESOLVED channel forfeits the alternates entirely, where a missing
+  // public origin does not: without an origin the language set is still known
+  // and the canonical is merely relative (`alternates.ts`), but without a
+  // channel the set itself is a fallback guess — and hreflang is a claim about
+  // OTHER URLs, which a guess must never make. The two refusals look alike and
+  // are not: one lacks an address, the other lacks the facts.
+  const alternates =
+    channelResolved === false ? undefined : buildAlternates({ binding, pathsByLocale, publicOrigin });
+
+  return {
+    title,
+    ...(description === null ? {} : { description }),
+    ...(noindex ? { robots: NOINDEX_ROBOTS } : {}),
+    ...(alternates === undefined ? {} : { alternates }),
+    ...socialTags({ ...input, title, description, alternates }),
+  };
+}
+
+/** `buildMetadata` with the deployment's origin filled in — what routes call. */
+export function routeMetadata(input: Omit<MetadataInput, 'publicOrigin'>): PageMetadata {
+  return buildMetadata({ ...input, publicOrigin: getPublicOrigin() });
+}
+
+/** `buildShellMetadata` with the origin filled in — what the root layout calls. */
+export function shellMetadata(input: Omit<ShellMetadataInput, 'publicOrigin'>): ShellMetadata {
+  return buildShellMetadata({ ...input, publicOrigin: getPublicOrigin() });
+}
+
+interface SocialTagsInput extends MetadataInput {
+  title: string;
+  description: string | null;
+  alternates: Alternates | undefined;
+}
+
+/**
+ * The `og:*` / `twitter:*` block, or nothing at all.
+ *
+ * OPT-IN on the social image, by operator amendment: an entity with no social
+ * image set emits no social tags whatsoever. Deriving one from the product
+ * photo would put a square catalog crop into every share card and make the
+ * merchant's explicit choice indistinguishable from the default — the whole
+ * point of `SeoMetaLanguage.socialEnabled` being armed only by a stored image.
+ *
+ * Two further gates, and neither is redundant with the opt-in: `og:url` must
+ * be ABSOLUTE, so a deployment with no public origin cannot emit one; and the
+ * canonical it uses comes from the alternates, which are absent for a fallback
+ * copy and for an unresolved channel. A share card pointing at an address this
+ * page has just declined to claim would be the same contradiction the
+ * alternates avoid, one protocol over.
+ *
+ * Deliberately NOT gated on indexability. `noindex` is an instruction to
+ * search engines about a page's place in an INDEX; an og card is what a link
+ * to it looks like when a shopper pastes it into a chat. An experiment-pinned
+ * URL should still preview when someone shares it.
+ */
+function socialTags({
+  socialImage,
+  binding,
+  pathsByLocale,
+  publicOrigin,
+  alternates,
+  title,
+  description,
+}: SocialTagsInput): Pick<PageMetadata, 'openGraph' | 'twitter'> {
+  if (!socialImage) return {};
+  if (publicOrigin === null || alternates === undefined) return {};
+
+  const images = [socialImage];
+  const shared = { title, ...(description === null ? {} : { description }), images };
+  // The channel's own language codes, unmodified. Open Graph conventionally
+  // carries `en_US`-shaped values, but the platform's registry is two-letter
+  // codes and there is no honest way to invent the territory half — an
+  // invented `en_US` would be a claim about a market nobody configured.
+  const alternateLocale = Object.keys(pathsByLocale).filter((code) => code !== binding.locale);
+
+  return {
+    openGraph: {
+      type: 'website',
+      locale: binding.locale,
+      ...(alternateLocale.length === 0 ? {} : { alternateLocale }),
+      url: alternates.canonical,
+      ...shared,
+    },
+    twitter: { card: 'summary_large_image', ...shared },
+  };
+}