@forgecart/cli 2.202610280649.0 → 2.202610280926.0

package/templates/storefront-shadcn-blank/src/app/robots.ts

@@ -0,0 +1,69 @@
+import type { MetadataRoute } from 'next';
+
+import { NOINDEX_PATHS, NOINDEX_QUERY_KEYS } from '../lib/seo/noindex';
+import { getPublicOrigin } from '../lib/seo/public-origin';
+
+/**
+ * `robots.txt` (#1347, epic launch#54 W1-9) — the crawler-facing half of the
+ * indexability contract in `lib/seo/noindex.ts`.
+ *
+ * FORCE-DYNAMIC, and that is load-bearing rather than cautious. Next
+ * pre-renders metadata routes at build time by default, and a storefront is
+ * built once then run with its per-channel environment supplied afterwards. A
+ * build-time answer would freeze the BUILDER's environment — which never has a
+ * channel's public origin — into `Disallow: /` for every store shipped from
+ * that image, permanently, with no way to correct it short of a rebuild. The
+ * scaffold is frozen at provisioning time (#1041), so "permanently" is literal.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * Infrastructure routes that are never a destination for a human or a crawler:
+ * the tracking relay, the error beacon, the SDK proxy and the health probe.
+ *
+ * Deliberately NOT derived from the locale grammar's `UNPREFIXED_FIRST_SEGMENTS`
+ * despite the overlap. That set answers "which first segments are not a
+ * language?" and correctly contains `sitemap.xml`, `robots.txt`, `_next` and
+ * `favicon.ico` — every one of which a crawler MUST be allowed to fetch.
+ * Sharing one list would make the next infrastructure route silently
+ * uncrawlable, or a crawlable asset silently unprefixed.
+ */
+const INFRASTRUCTURE_DISALLOW: readonly string[] = [
+  '/api/',
+  '/__fc/',
+  '/__forge_beacon',
+  '/ping',
+];
+
+/**
+ * Without a public origin the storefront asserts nothing, so `robots.txt`
+ * refuses the whole tree. With one, it mirrors the noindex set — the page
+ * rules are DERIVED from `noindex.ts` rather than restated, because a
+ * `robots.txt` that disagrees with the pages' own `robots` metadata is the
+ * exact drift this module exists to prevent.
+ *
+ * The `Sitemap:` line rides the origin BRANCH, not merely the origin value: the
+ * URL it names has to be absolute, and the document it points at is empty
+ * without an origin. Announcing an empty sitemap is a claim about the catalog;
+ * announcing nothing is the absence of one, which is all a deployment that has
+ * not been told its own address is entitled to say.
+ */
+export default function robots(): MetadataRoute.Robots {
+  const publicOrigin = getPublicOrigin();
+  if (publicOrigin === null) {
+    return { rules: { userAgent: '*', disallow: '/' } };
+  }
+
+  return {
+    rules: {
+      userAgent: '*',
+      allow: '/',
+      disallow: [
+        ...NOINDEX_PATHS,
+        ...INFRASTRUCTURE_DISALLOW,
+        ...NOINDEX_QUERY_KEYS.map((key) => `/*?${key}=`),
+      ],
+    },
+    sitemap: `${publicOrigin}/sitemap.xml`,
+  };
+}

package/templates/storefront-shadcn-blank/src/app/sitemap.ts

@@ -0,0 +1,107 @@
+import type { MetadataRoute } from 'next';
+
+import { getProductSeoEntries, getServedPageRoutes } from '../lib/forgecart';
+import { resolveChannelLocales } from '../lib/locale/channel-locales-loader';
+import { getPublicOrigin } from '../lib/seo/public-origin';
+import { readScaffoldedRoutes } from '../lib/seo/scaffolded-routes';
+import { createSitemapCache, sitemapWindowMs } from '../lib/seo/sitemap-cache';
+import {
+  MAX_SITEMAP_URLS,
+  collectProductSitemapUrls,
+  mergeScaffoldedRoutes,
+  pageSitemapRoutes,
+  sitemapBudgetWarning,
+  staticSitemapUrls,
+} from '../lib/seo/sitemap-entries';
+import { STATIC_ROUTES } from '../seo/static-routes';
+
+/**
+ * `sitemap.xml` (#1347, epic launch#54 W1-9) — the discovery half of the SEO
+ * contract, listing every URL this deployment is willing to be indexed at.
+ *
+ * FORCE-DYNAMIC for the same load-bearing reason as `robots.ts`: Next
+ * pre-renders metadata routes at build time, the storefront image is built
+ * once and handed its channel environment afterwards, and the scaffold is
+ * frozen at provisioning time (#1041). A build-time answer would freeze the
+ * BUILDER's empty environment — no origin, no channel, no catalog — into an
+ * empty sitemap for every store shipped from that image, permanently. The
+ * 60s window is held in-process by `createSitemapCache` for exactly the same
+ * reason ISR is refused here: `revalidate` would pre-render the first response
+ * at build time too, which is the identical failure wearing a TTL.
+ */
+export const dynamic = 'force-dynamic';
+
+/**
+ * An empty document without a public origin, and no `<lastmod>` claims — the
+ * same refusal `robots.ts` and every page's `robots` metadata make in that
+ * state. Every URL a sitemap lists is absolute, so a deployment with no origin
+ * has nothing truthful to put in one.
+ *
+ * A backend failure is deliberately NOT caught: an unreachable shop makes this
+ * route 5xx, which tells a crawler to come back. Serving an empty sitemap
+ * instead would assert that the catalog is empty — the one answer that is
+ * actively false, and the one a crawler would act on by dropping URLs.
+ */
+const cache = createSitemapCache(build, { ttlMs: sitemapWindowMs });
+
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+  return cache.get();
+}
+
+/**
+ * The refusal is inside the window rather than guarding it, because the origin
+ * is memoized for the life of the process: an unconfigured deployment stays
+ * unconfigured until it restarts, so caching its empty answer cannot make it
+ * any staler than the memo already has.
+ */
+async function build(): Promise<MetadataRoute.Sitemap> {
+  const publicOrigin = getPublicOrigin();
+  if (publicOrigin === null) return [];
+
+  const { channel } = await resolveChannelLocales(null);
+  const { languageCodes, defaultLanguageCode } = channel;
+
+  // The row's own routes (`src/seo/static-routes.ts`, #3478), every page
+  // scaffolded since, and every ACF page the shop says it currently SERVES
+  // (#1934). Read per build rather than at module load, so a page created a
+  // moment ago is in the document on the next window — the reason
+  // `createStorefrontPage` writes a row at all, and the reason the ACF feed is
+  // a live query rather than a file: an ACF page is published through the API
+  // and writes nothing to this pod's disk.
+  //
+  // PRECEDENCE falls out of the merge and is worth naming: the base table wins
+  // over both, and within the appended list the FIRST claimant of a path wins —
+  // so a code-scaffolded page at `/pages/x` outranks an ACF page at the same
+  // slug. That is also how Next routes them (a literal `app/pages/x/page.tsx`
+  // shadows the dynamic `[slug]`), so the document cannot disagree with the
+  // router about which page an address serves.
+  const [scaffolded, servedPageRoutes] = await Promise.all([
+    readScaffoldedRoutes(),
+    getServedPageRoutes(defaultLanguageCode),
+  ]);
+  const routes = mergeScaffoldedRoutes(STATIC_ROUTES, [
+    ...scaffolded,
+    ...pageSitemapRoutes(servedPageRoutes),
+  ]);
+  const staticUrls = staticSitemapUrls(languageCodes, defaultLanguageCode, publicOrigin, routes);
+  const productUrls = await collectProductSitemapUrls(
+    async (skip, take) => getProductSeoEntries(defaultLanguageCode, { skip, take }),
+    defaultLanguageCode,
+    publicOrigin,
+    Math.max(0, MAX_SITEMAP_URLS - staticUrls.length),
+  );
+
+  const urls = [...staticUrls, ...productUrls];
+
+  // The one place this template writes to the console, and it earns it: a
+  // catalog that outgrows a single XML sitemap would otherwise stop being
+  // submitted for indexing in complete silence, inside the feature whose whole
+  // job is getting pages indexed. There is no logger in a scaffolded storefront
+  // and no channelId to tag — only the channel token, which is a credential and
+  // must never reach a log — so the pod's stdout is the channel, and the 60s
+  // window bounds this to at most one line a minute.
+  const warning = sitemapBudgetWarning(urls.length);
+  if (warning !== null) console.warn(warning);
+
+  return urls;
+}

package/templates/storefront-shadcn-blank/src/components/ForgeErrorBeacon.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { useEffect } from 'react';
+
+/**
+ * DEV-ONLY storefront error beacon. Renders nothing.
+ *
+ * Registers `window.onerror` + `window.onunhandledrejection` and POSTs the failure
+ * detail to the same-origin Next API route `/__forge_beacon`, which forwards it
+ * server-side to the in-pod workspace-manager receiver. This surfaces the crash
+ * class the pod's dev-server stderr scan CANNOT see: a client-component runtime
+ * error or a hydration/SSR-boundary throw that never reaches the dev-server's
+ * output. The browser only ever talks SAME-ORIGIN — the API route is the only thing
+ * that knows the pod-internal receiver address.
+ *
+ * Production builds ship zero bytes of this: the literal `NODE_ENV` check is inlined
+ * by the bundler, so the effect body is dead-code-eliminated from `next build` /
+ * `next start` output — a deployed storefront registers no global error handlers and
+ * has no beacon API route reachable in prod (the route itself is dev-gated too).
+ *
+ * The beacon is best-effort and never blocks the page: the POST is fire-and-forget
+ * with `keepalive` so it survives an unload, and a delivery failure is swallowed —
+ * the page's own error boundary still renders. The full
+ * browser → API route → pod → supervisor-fold path is exercised at the e2e layer,
+ * not in this template.
+ *
+ * Every report carries the revision the PAGE WAS SERVED AT (#847), read out of the
+ * `forge-revision` meta tag the server wrote into this document rather than looked
+ * up fresh at throw time. That distinction is the entire point: a fresh lookup would
+ * answer whatever is live NOW, so a promote landing between serve and throw would
+ * make this report blame the new revision for the old one's crash — and the pod's
+ * same-revision fold would then mark a healthy tree DEGRADED. The tag cannot drift,
+ * because it was rendered with the markup that broke.
+ */
+export function ForgeErrorBeacon() {
+  useEffect(() => {
+    if (process.env.NODE_ENV !== 'development') {
+      return;
+    }
+
+    /**
+     * The revision this document was SERVED at, or `undefined` when the server
+     * did not stamp one (production, or a pod that cannot resolve it — both
+     * normal). `'forge-revision'` is repeated here as a literal on purpose: the
+     * resolver lives in `src/server/forge/live-revision.ts`, which a client
+     * component must not import, so this is the same repeated-contract shape the
+     * `/__forge_beacon` URL already uses across this feature's producers.
+     *
+     * An absent tag, an absent attribute and an empty value all answer
+     * `undefined`, which `JSON.stringify` then omits from the body entirely —
+     * so an unstamped page sends exactly the payload it sent before, and the pod
+     * keeps its existing untagged behaviour instead of receiving a blank string
+     * it would have to interpret.
+     */
+    const readServedRevision = (): string | undefined => {
+      const content = document
+        .querySelector('meta[name="forge-revision"]')
+        ?.getAttribute('content');
+      if (!content) return undefined;
+      return content;
+    };
+
+    const send = (message: string, stack?: string) => {
+      const body = JSON.stringify({
+        message,
+        stack,
+        route: window.location.pathname,
+        source: 'browser',
+        atRevision: readServedRevision(),
+      });
+      // Same-origin POST; keepalive lets it survive a navigation/unload. A failed
+      // delivery is intentionally swallowed — the beacon is a backstop signal, not
+      // a hard dependency of the page.
+      void fetch('/__forge_beacon', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body,
+        keepalive: true,
+      }).catch(() => undefined);
+    };
+
+    const onError = (event: ErrorEvent) => {
+      send(event.message || 'window.onerror', event.error?.stack);
+    };
+    const onRejection = (event: PromiseRejectionEvent) => {
+      const reason = event.reason;
+      const message =
+        reason instanceof Error ? reason.message : String(reason ?? 'unhandledrejection');
+      const stack = reason instanceof Error ? reason.stack : undefined;
+      send(message, stack);
+    };
+
+    window.addEventListener('error', onError);
+    window.addEventListener('unhandledrejection', onRejection);
+    return () => {
+      window.removeEventListener('error', onError);
+      window.removeEventListener('unhandledrejection', onRejection);
+    };
+  }, []);
+
+  return null;
+}