@forgecart/cli 2.202610052310.0 → 2.202610071755.0

package/templates/storefront-shadcn/src/app/api/%5F%5Fbackend/methods/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from 'next/server';
+
+import { getBackend } from '../../../../server/bootstrap';
+
+/**
+ * DEV-ONLY registry listing — the agent's verification surface for backend
+ * features. After authoring a method, the agent probes this route and
+ * confirms the new name is listed; a boot failure (the api-map drift check)
+ * surfaces here as a 500 carrying the actionable message.
+ *
+ * Gated on `NODE_ENV === 'development'`: the literal check is inlined by
+ * the bundler, so a production build answers 404 and dead-code-eliminates
+ * the body. Method NAMES are the only thing exposed — never inputs,
+ * outputs, or configuration.
+ */
+export async function GET(): Promise<NextResponse> {
+  if (process.env.NODE_ENV !== 'development') {
+    return NextResponse.json({ error: 'not found' }, { status: 404 });
+  }
+  try {
+    const { registry } = await getBackend();
+    return NextResponse.json({ methods: [...registry.keys()].sort() });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: reason }, { status: 500 });
+  }
+}

package/templates/storefront-shadcn/src/app/cart/page.tsx

@@ -0,0 +1,53 @@
+import type { Metadata } from 'next';
+import { connection } from 'next/server';
+import { Suspense } from 'react';
+
+import { CartView } from '../../components/CartView';
+import { Skeleton } from '../../components/ui/skeleton';
+import { getChannelSellingPlanGroups } from '../../lib/forgecart';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeRobots } from '../../lib/seo/noindex';
+
+/**
+ * Never indexable: a cart is per-shopper state, identical in copy for everyone
+ * and meaningless to a visitor arriving from a search result.
+ */
+export function generateMetadata(): Metadata {
+  return { robots: routeRobots('/cart') };
+}
+
+/**
+ * Cart route. The shopper's cart itself lives on their OWN websocket
+ * (`CartView` hydrates it client-side); the server's only read here is the
+ * PUBLIC channel subscription plans off the anonymous channel singleton —
+ * streamed as a hole while the shell renders.
+ */
+export default function CartPage() {
+  return (
+    <Suspense fallback={<CartRouteSkeleton />}>
+      <CartWithPlans />
+    </Suspense>
+  );
+}
+
+async function CartWithPlans() {
+  await connection();
+  const { binding } = await getRequestLocale();
+  // Channel-wide subscription plans are public channel data — the one
+  // server-fetched input; the "Subscribe to your whole order" box renders
+  // only when there are any.
+  const channelGroups = await getChannelSellingPlanGroups();
+  return <CartView channelGroups={channelGroups} locale={binding} />;
+}
+
+function CartRouteSkeleton() {
+  return (
+    <div className="space-y-8" aria-busy="true" aria-label="Loading your cart">
+      <h1 className="text-3xl font-bold tracking-tight">Your cart</h1>
+      <div className="grid items-start gap-8 lg:grid-cols-[minmax(0,1fr)_360px]">
+        <Skeleton className="h-64 w-full" />
+        <Skeleton className="h-80 w-full" />
+      </div>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/checkout/page.tsx

@@ -0,0 +1,53 @@
+import type { Metadata } from 'next';
+import { connection } from 'next/server';
+import { Suspense } from 'react';
+
+import { CheckoutGate } from '../../components/checkout/CheckoutGate';
+import { Skeleton } from '../../components/ui/skeleton';
+import { getAvailableCountries } from '../../lib/forgecart';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeRobots } from '../../lib/seo/noindex';
+
+/**
+ * Never indexable: checkout is a funnel step, not a destination, and every
+ * nested step inherits the decision through `NOINDEX_PATHS`.
+ */
+export function generateMetadata(): Metadata {
+  return { robots: routeRobots('/checkout') };
+}
+
+/**
+ * Checkout entry. The server's only job here is the PUBLIC prefetch — the
+ * channel's shipping countries off the anonymous channel singleton, streamed
+ * as a hole. The session work (the order itself, every
+ * checkout mutation) lives on the shopper's websocket: `CheckoutGate`
+ * hydrates the live cart client-side and mounts the flow, or shows the
+ * honest empty state.
+ */
+export default function CheckoutPage() {
+  return (
+    <div className="mx-auto max-w-2xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">Checkout</h1>
+      <Suspense fallback={<CheckoutRouteSkeleton />}>
+        <CheckoutWithCountries />
+      </Suspense>
+    </div>
+  );
+}
+
+async function CheckoutWithCountries() {
+  await connection();
+  const { binding } = await getRequestLocale();
+  const countries = await getAvailableCountries();
+  return <CheckoutGate countries={countries} locale={binding} />;
+}
+
+function CheckoutRouteSkeleton() {
+  return (
+    <div className="space-y-4" aria-busy="true" aria-label="Loading checkout">
+      <Skeleton className="h-10 w-full" />
+      <Skeleton className="h-40 w-full" />
+      <Skeleton className="h-10 w-40" />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/error.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { Button } from '../components/ui/button';
+
+/**
+ * Route-level backstop boundary. The action layer never throws (typed
+ * `ActionResult` envelopes end at inline UI), so landing here means a RENDER
+ * failed — e.g. a Server Component read against an unreachable shop API.
+ * Recovery is a re-render via `reset()`.
+ */
+export default function RouteError({ reset }: { error: Error; reset: () => void }) {
+  return (
+    <div className="mx-auto max-w-xl space-y-4 py-16 text-center">
+      <h1 className="text-2xl font-bold tracking-tight text-foreground">Something went wrong</h1>
+      <p className="text-muted-foreground">
+        The store could not load this page. Please try again in a moment.
+      </p>
+      <Button type="button" onClick={() => reset()}>
+        Try again
+      </Button>
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/app/global-error.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+/**
+ * Root backstop: replaces the whole document when the root layout itself
+ * fails to render. Must own its own <html>/<body> — the layout that normally
+ * provides them is the thing that crashed. Styled inline (no globals.css —
+ * that import lives in the crashed layout).
+ */
+export default function GlobalError({ reset }: { error: Error; reset: () => void }) {
+  return (
+    <html lang="en">
+      <body
+        style={{ fontFamily: 'system-ui, sans-serif', padding: '4rem 1rem', textAlign: 'center' }}
+      >
+        <h1>Something went wrong</h1>
+        <p>The store is temporarily unavailable. Please try again in a moment.</p>
+        <button type="button" onClick={() => reset()} style={{ padding: '0.5rem 1.25rem' }}>
+          Try again
+        </button>
+      </body>
+    </html>
+  );
+}

package/templates/storefront-shadcn/src/app/globals.css

@@ -0,0 +1,156 @@
+@import "tailwindcss";
+
+/*
+ * ═══════════════════════════════════════════════════════════════════════════
+ * STOREFRONT THEME — the single brand mutation point (design-system contract)
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * Every component in this template speaks SEMANTIC shadcn/ui tokens (bg-card,
+ * text-muted-foreground, border-input, the Button / Badge / Alert variants,
+ * …), so the `:root` block below is the ONE place a brand lives. Restyling
+ * the storefront = editing those values — nothing else. Never scatter raw
+ * palette utilities (bg-gray-900, text-white, #hex) through components; if a
+ * component needs a color, it needs a TOKEN: declared once in `:root` and
+ * exposed to Tailwind through `@theme inline`, as the status tokens are.
+ *
+ * The daisyUI storefront and this one are rows of one template set. The table
+ * is how every daisyUI theme token reads here — the same brand decision under
+ * its shadcn/ui name:
+ *
+ *   daisyUI theme token            shadcn/ui token (this file)
+ *   ───────────────────────────    ──────────────────────────────────────────
+ *   --color-base-100               --card, --popover
+ *   --color-base-200               --background
+ *   --color-base-300               --border, --input
+ *   --color-base-content           --foreground (+ --card-foreground,
+ *                                  --popover-foreground)
+ *   --color-primary(-content)      --primary(-foreground)
+ *   --color-secondary(-content)    --secondary(-foreground)
+ *   --color-accent(-content)       --accent(-foreground)
+ *   --color-neutral(-content)      --muted(-foreground)
+ *   --color-error                  --destructive
+ *   --color-success(-content)      --success(-foreground)  declared by this variant
+ *   --color-warning(-content)      --warning(-foreground)  declared by this variant
+ *   --color-info(-content)         --info(-foreground)     declared by this variant
+ *   --radius-selector              --radius-sm
+ *   --radius-field                 --radius-md
+ *   --radius-box                   --radius-lg (= --radius)
+ *   --font-sans (@theme)           --font-sans (@theme inline)
+ *
+ * shadcn/ui names no success, warning or info color, so this variant declares
+ * them beside --destructive, each with the -foreground that stays legible on
+ * it (the Alert's status variants fill with them). --ring has no daisyUI
+ * counterpart — daisyUI draws a focus outline in the control's own color — so
+ * it takes the primary ink.
+ *
+ * The baseline is the daisyUI storefront's own, deliberately UNBRANDED
+ * monochrome (near-black on soft gray), carried value for value through the
+ * table — with one deliberate exception, the muted pair. daisyUI's neutral is
+ * a high-contrast FILL; shadcn/ui's muted pair is the SUBDUED one every
+ * vendored component reads for quiet surfaces and secondary text (bg-muted,
+ * text-muted-foreground — an input's placeholder among them). The baseline
+ * keeps that role: --muted is a soft gray surface, and --muted-foreground the
+ * mid-gray ink the daisyUI template writes as text-base-content/60. Accent
+ * keeps daisyUI's dark highlight, which is also what a ghost or outline
+ * button turns on hover.
+ *
+ * Radius: daisyUI's selector and field radii are both 0.375rem and its box
+ * radius 0.5rem, so --radius is the box radius and the sm/md steps sit one
+ * notch below it. A brand font goes in `@theme inline`: swap the --font-sans
+ * stack (and add the font's `@font-face`/import above it).
+ */
+:root {
+  /* Base — white surfaces over a soft-gray substrate, near-black text. */
+  --background: #f9fafb;
+  --foreground: #111827;
+  --card: #ffffff;
+  --card-foreground: #111827;
+  --popover: #ffffff;
+  --popover-foreground: #111827;
+  --border: #e5e7eb;
+  --input: #e5e7eb;
+
+  /* Actions — unbranded monochrome. */
+  --primary: #111827;
+  --primary-foreground: #ffffff;
+  --secondary: #374151;
+  --secondary-foreground: #ffffff;
+  --accent: #1f2937;
+  --accent-foreground: #ffffff;
+  --muted: #f3f4f6;
+  --muted-foreground: #6b7280;
+  --ring: #111827;
+
+  /* Status — conventional semantics, not brand. */
+  --destructive: #dc2626;
+  --success: #16a34a;
+  --success-foreground: #ffffff;
+  --warning: #d97706;
+  --warning-foreground: #ffffff;
+  --info: #2563eb;
+  --info-foreground: #ffffff;
+
+  /* Shape — the daisyUI storefront's box radius. */
+  --radius: 0.5rem;
+}
+
+/* The tokens as Tailwind theme values: bg-card, text-muted-foreground, rounded-md, font-sans, … */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+
+  --radius-sm: calc(var(--radius) - 2px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+
+  /* Brand typography mutation point — swap the stack to give the store a font. */
+  --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji",
+    "Segoe UI Symbol", "Noto Color Emoji";
+}
+
+/* The shadcn/ui base layer: token-colored borders and focus outlines, the page on --background. */
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+/*
+ * Base document behavior (structural — NOT part of the theme contract).
+ * A horizontal touchpad glide must never trigger the browser's swipe-back
+ * navigation: mid-checkout that discards the shopper's in-progress state
+ * (the refresh-resume path recovers the payment step, but preventing the
+ * accidental navigation is the real fix). The back button and keyboard
+ * navigation are untouched — only the overscroll gesture is consumed.
+ */
+html,
+body {
+  overscroll-behavior-x: none;
+}

package/templates/storefront-shadcn/src/app/layout.tsx

@@ -0,0 +1,185 @@
+import type { Metadata } from 'next';
+import { notFound, permanentRedirect } from 'next/navigation';
+import { Suspense, type ReactNode } from 'react';
+
+import { ForgeErrorBeacon } from '../components/ForgeErrorBeacon';
+import { ForgeTracker } from '../components/ForgeTracker';
+import { ForgecartDesigner } from '../components/ForgecartDesigner';
+import { Header } from '../components/Header';
+import { LocaleLink } from '../components/LocaleLink';
+import { CartProvider } from '../lib/cart-context';
+import { getRequestLocale } from '../lib/locale/request-binding';
+import { shellMetadata } from '../lib/seo/metadata';
+import { getSiteVerifications } from '../lib/seo/site-verification';
+import { getBrowserShopConfig } from '../lib/shop-config';
+import { FORGE_REVISION_META, resolveLiveRevision } from '../server/forge/live-revision';
+
+import './globals.css';
+
+/**
+ * The deployment-wide metadata floor.
+ *
+ * Resolved per REQUEST rather than declared as a static `metadata` object,
+ * because everything in it arrives in the environment of the running server
+ * rather than of the machine that built the bundle: the public origin from
+ * `.env` (see `lib/seo/public-origin.ts`) and the shop name from the channel
+ * itself. A build-time answer would bake the builder's empty environment into
+ * every store shipped from that image.
+ *
+ * The title is the STORE's name, so a merchant who scaffolds a page and writes
+ * no metadata gets their own store in the browser tab instead of the word
+ * `Storefront` — which is what every page of every ForgeCart store displayed
+ * before this. Route-specific claims live on the routes; this is only the
+ * floor, and it deliberately carries no canonical (it does not know which
+ * route it is wrapping).
+ *
+ * It reads the SAME resolution the layout body reads below — React's request
+ * cache makes `getRequestLocale()` one channel read per request no matter how
+ * many callers there are, so the floor costs nothing extra.
+ *
+ * The site-verification placements (#1530) are read on the same request cache
+ * and handed to the SAME composer, so `lib/seo/metadata.ts` stays the only
+ * thing in this template that turns a placement into a `<meta>`: the
+ * alternative — a hand-written tag in the markup below — would be a second
+ * emitter with its own idea of when a placement is servable. They ride the
+ * FLOOR rather than a route, because the verifier chooses which page it fetches
+ * and a tag on only some of them is a verification that works until it does not.
+ *
+ * It also carries the DEV-ONLY revision stamp (#847). The tag has to be written
+ * where the page is RENDERED, because that is the only moment that knows which
+ * tree the shopper is actually looking at: the browser beacon reads it back at
+ * throw time, so a promote landing between serve and throw can no longer make
+ * the report blame the new revision for the old one's crash. It rides
+ * `generateMetadata` rather than a `<meta>` in the JSX below because arbitrary
+ * head tags are what `other` is for, and the shell's own metadata contract then
+ * stays untouched — the stamp is spread ON TOP of `shellMetadata`'s answer and
+ * adds a key no SEO surface reads.
+ *
+ * Dev-gated at this call site, like every other file in the beacon path: the
+ * literal `NODE_ENV` check is what lets a production build eliminate the
+ * resolution entirely, so a deployed storefront emits no tag and leaks no
+ * revision. Unresolvable is a NORMAL answer and means no tag — the report then
+ * arrives untagged and the receiver keeps its existing behaviour.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { shopName, channelResolved } = await getRequestLocale();
+  const siteVerifications = await getSiteVerifications();
+  const shell = shellMetadata({ shopName, channelResolved, siteVerifications });
+  if (process.env.NODE_ENV !== 'development') return shell;
+  const revision = resolveLiveRevision();
+  if (revision === null) return shell;
+  // MERGED into the shell's `other`, never written over it: that key carries the
+  // site-verification placements (#1530), and a storefront pod serves through
+  // `npm run dev`, so an overwrite here would strip the provider's tag from
+  // every page its verifier can fetch.
+  return { ...shell, other: { ...shell.other, [FORGE_REVISION_META]: revision } };
+}
+
+/**
+ * The root layout — DYNAMIC on every route, by design (D8).
+ *
+ * It reads the request locale to write `<html lang>`, and `lang` is an
+ * attribute on the document root: structurally outside every Suspense
+ * boundary, so it cannot come from a streamed hole. That single requirement
+ * decides the rendering model for the whole storefront, and `next.config.js`
+ * carries the reasoning — Cache Components is off because the escape hatch it
+ * would force (a `<Suspense>` above `<body>`) is exactly what makes the two
+ * throws below unable to set a status.
+ *
+ * Those throws are the locale contract's teeth. Raised HERE, in the shell,
+ * they reach the one place Next assigns a status: `permanentRedirect` gives a
+ * real 308 with a `Location`, and `notFound` a real 404. Raised from inside
+ * any boundary they would resolve as client-rendered content instead, and the
+ * response would be a 200 carrying a 404 page — a soft-404, which a crawler
+ * indexes rather than drops.
+ *
+ * One consequence worth knowing: on `notFound()` Next discards the app tree
+ * and seeds a bare error document, so `app/not-found.tsx` reaches the shopper
+ * on client hydration rather than in the SSR body. The STATUS is correct
+ * either way, which is what the crawler consumes.
+ *
+ * The cart still hydrates CLIENT-side over the shopper's own websocket
+ * (`CartProvider` + `shop-session.ts`), armed with the channel coordinates
+ * serialized here (public storefront token — the admin secret never takes this
+ * path).
+ */
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const { decision, binding, languageCodes } = await getRequestLocale();
+  if (decision.kind === 'redirect') permanentRedirect(decision.to);
+  if (decision.kind === 'notFound') notFound();
+
+  // The shopper's own socket is opened CLIENT-side, so it cannot read the
+  // request headers the server resolved the locale from. It gets the resolved
+  // language here, which keeps one source of truth — the URL — for both the
+  // server's per-locale clients and the browser's session client. Without it
+  // the cart would answer in the channel default on a German page.
+  const shopConfig = getBrowserShopConfig(binding.locale);
+  return (
+    <html lang={binding.locale}>
+      <body className="min-h-screen bg-background font-sans text-foreground antialiased">
+        <CartProvider shopConfig={shopConfig}>
+          <Header locale={binding} languageCodes={languageCodes} />
+          <main className="mx-auto max-w-6xl px-4 py-10">{children}</main>
+          <footer className="mt-8 border-t bg-card px-6 py-8 text-sm text-muted-foreground sm:px-10">
+            <div className="flex flex-col gap-6 sm:flex-row sm:items-center sm:justify-between">
+              <aside>
+                <p className="font-medium text-foreground">Storefront</p>
+                <p>Powered by ForgeCart</p>
+              </aside>
+              <nav aria-label="Footer">
+                <div className="grid grid-flow-col gap-4">
+                  <LocaleLink
+                    href="/"
+                    locale={binding}
+                    className="underline-offset-4 hover:text-foreground hover:underline"
+                  >
+                    Home
+                  </LocaleLink>
+                  <LocaleLink
+                    href="/products"
+                    locale={binding}
+                    className="underline-offset-4 hover:text-foreground hover:underline"
+                  >
+                    Products
+                  </LocaleLink>
+                  <LocaleLink
+                    href="/cart"
+                    locale={binding}
+                    className="underline-offset-4 hover:text-foreground hover:underline"
+                  >
+                    Cart
+                  </LocaleLink>
+                  {/* The only affordance for `/register` (#1471). It sits in the
+                      footer rather than the header nav on purpose: the template
+                      ships no sign-in surface yet, and an account entry in the
+                      primary nav would advertise an account AREA that does not
+                      exist. A merchant who adds sign-in moves it up. */}
+                  <LocaleLink
+                    href="/register"
+                    locale={binding}
+                    className="underline-offset-4 hover:text-foreground hover:underline"
+                  >
+                    Create account
+                  </LocaleLink>
+                </div>
+              </nav>
+            </div>
+          </footer>
+        </CartProvider>
+        {/* Invisible client plumbing. The tracker reads usePathname(), which
+            needs a boundary of its own — null fallback, these render nothing.
+            This must stay INSIDE <body>: a boundary above it would make the
+            shell resumable and cost the statuses above. */}
+        <Suspense fallback={null}>
+          <ForgecartDesigner />
+          <ForgeErrorBeacon />
+          <ForgeTracker
+            enabled={Boolean(
+              process.env.FORGECART_SHOP_API_URL && process.env.FORGECART_CHANNEL_TOKEN,
+            )}
+          />
+        </Suspense>
+      </body>
+    </html>
+  );
+}