@forgecart/cli 2.202610052310.0 → 2.202610060357.0

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

@@ -0,0 +1,106 @@
+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,
+  STATIC_ROUTES,
+  collectProductSitemapUrls,
+  mergeScaffoldedRoutes,
+  pageSitemapRoutes,
+  sitemapBudgetWarning,
+  staticSitemapUrls,
+} from '../lib/seo/sitemap-entries';
+
+/**
+ * `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 template's own routes, 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/src/app/verify/page.tsx

@@ -0,0 +1,157 @@
+import type { Metadata } from 'next';
+import { connection } from 'next/server';
+import { Suspense } from 'react';
+
+import { AccountMessage, type AccountMessageTone } from '../../components/account/AccountMessage';
+import { LocaleLink } from '../../components/LocaleLink';
+import { buttonVariants } from '../../components/ui/button';
+import { Skeleton } from '../../components/ui/skeleton';
+import { readLinkToken, type AccountLinkOutcome } from '../../lib/account/account-link';
+import { verifyState, type VerifyState } from '../../lib/account/verify-state';
+import { verifyCustomerAccount } from '../../lib/forgecart';
+import { getRequestLocale } from '../../lib/locale/request-binding';
+import { routeMetadata } from '../../lib/seo/metadata';
+import type { RouteSearchParams } from '../../lib/seo/noindex';
+
+/**
+ * `/verify?token=…` — the page the platform's verification e-mail links to
+ * (#1472).
+ *
+ * Before this route existed, that link pointed at one platform-global host
+ * that served no such page, so every shopper who clicked it got a 404 and no
+ * account was ever verified from a mail. The link now resolves to the
+ * CHANNEL's own storefront, which is the only place that can both consume the
+ * token and tell the shopper, in the store's own voice, what happened to it.
+ *
+ * The token is consumed by the RENDER. That is what a mail link is: a GET
+ * whose entire purpose is to spend a one-shot credential, so there is no
+ * button to press first — pressing one would only add a step between the
+ * shopper and the outcome. It also means the second load of the same link is
+ * an expected state (`link-invalid`), not an error, which is why
+ * `verifyCustomerAccount` answers instead of throwing.
+ */
+
+const PAGE_TITLE = 'Verify your e-mail';
+
+/**
+ * Noindex via `NOINDEX_PATHS`, and NO alternates.
+ *
+ * `pathsByLocale` is deliberately empty rather than `staticPathsByLocale(…)`:
+ * `/verify` exists once per store (see `lib/locale/grammar.ts`), so there is no
+ * cluster of per-language addresses to claim — and building one would emit
+ * hreflang tags pointing every language at the same URL.
+ *
+ * The request's query is deliberately NOT passed either. The route rule
+ * already refuses indexing, so the only thing `searchParams` could add here is
+ * a shopper's one-shot token inside the metadata layer.
+ */
+export async function generateMetadata(): Promise<Metadata> {
+  const { binding, shopName, channelResolved } = await getRequestLocale();
+  return routeMetadata({
+    binding,
+    shopName,
+    channelResolved,
+    pathname: '/verify',
+    pathsByLocale: {},
+    title: PAGE_TITLE,
+  });
+}
+
+/**
+ * Every account surface stamps `data-fc-account-mode` + `data-fc-account-state`
+ * on the element it renders (the same shape as the home page's
+ * `data-fc-variant`).
+ *
+ * The states of these pages are, by construction, the hardest thing in the
+ * template to observe: each is reached once, with a credential the visit
+ * destroys. The markers make the state machine READABLE from the served HTML,
+ * which is what `tool/storefront-verify` asserts against — deliberately
+ * instead of the copy, because the copy belongs to the merchant and is the
+ * first thing a rebrand rewrites, while the state set is the contract.
+ */
+
+/** What each outcome tells the shopper, and where it sends them next. */
+const VERIFY_COPY: Readonly<
+  Record<VerifyState, { tone: AccountMessageTone; title: string; body: string; cta: string }>
+> = {
+  verified: {
+    tone: 'success',
+    title: 'Your e-mail address is verified',
+    body: 'Your account is ready — you can sign in with the address you registered.',
+    cta: 'Start shopping',
+  },
+  'no-token': {
+    tone: 'warning',
+    title: 'This link is missing its verification token',
+    body: 'Open the link straight from the e-mail we sent you. It carries a one-time token this page needs, and copying only part of the address leaves it behind.',
+    cta: 'Go to the store',
+  },
+  'link-invalid': {
+    tone: 'warning',
+    title: 'This verification link is no longer valid',
+    body: 'It has either been used already or it has expired. If your account is still unverified, request a new verification e-mail and open the newest link.',
+    cta: 'Go to the store',
+  },
+  'wrong-store': {
+    tone: 'warning',
+    title: 'This link belongs to a different store',
+    body: 'The account it verifies does not shop here. Open the link from the e-mail that store sent you — every store sends its own.',
+    cta: 'Go to the store',
+  },
+  failed: {
+    tone: 'error',
+    title: 'We could not verify your e-mail address',
+    body: 'Something went wrong on our side. Please open the link again in a few minutes — and if it has stopped working by then, request a new verification e-mail.',
+    cta: 'Go to the store',
+  },
+};
+
+export default function VerifyPage({ searchParams }: { searchParams: Promise<RouteSearchParams> }) {
+  return (
+    <div className="mx-auto max-w-xl space-y-6">
+      <h1 className="text-2xl font-bold tracking-tight">{PAGE_TITLE}</h1>
+      <Suspense fallback={<VerifyRouteSkeleton />}>
+        <VerifyOutcome searchParams={searchParams} />
+      </Suspense>
+    </div>
+  );
+}
+
+/**
+ * The request-time hole: the token is read and spent here, inside the Suspense
+ * boundary, so the shell paints while the API is asked.
+ *
+ * The `searchParams` promise is passed DOWN rather than awaited in the shell —
+ * awaiting it above would pull the token into the static part of the render for
+ * no benefit, since nothing above this component reads it.
+ */
+async function VerifyOutcome({ searchParams }: { searchParams: Promise<RouteSearchParams> }) {
+  await connection();
+  const [params, { binding }] = await Promise.all([searchParams, getRequestLocale()]);
+
+  const token = readLinkToken(params);
+  const outcome: AccountLinkOutcome =
+    token === null ? { kind: 'no-token' } : await verifyCustomerAccount(token);
+  const state = verifyState(outcome);
+  const copy = VERIFY_COPY[state];
+
+  return (
+    <div className="space-y-6" data-fc-account-mode="verify" data-fc-account-state={state}>
+      <AccountMessage tone={copy.tone} title={copy.title}>
+        {copy.body}
+      </AccountMessage>
+      <LocaleLink href="/" locale={binding} className={buttonVariants()}>
+        {copy.cta}
+      </LocaleLink>
+    </div>
+  );
+}
+
+function VerifyRouteSkeleton() {
+  return (
+    <div className="space-y-6" aria-busy="true" aria-label="Verifying your e-mail address">
+      <Skeleton className="h-20 w-full" />
+      <Skeleton className="h-12 w-44" />
+    </div>
+  );
+}

package/templates/storefront-shadcn/src/components/CartView.tsx

@@ -0,0 +1,333 @@
+'use client';
+
+import type { LocaleBinding } from '../lib/locale/localized-path';
+import { LocaleLink } from './LocaleLink';
+import { useState } from 'react';
+
+import { Alert, AlertDescription } from './ui/alert';
+import { Badge } from './ui/badge';
+import { Button, buttonVariants } from './ui/button';
+import { Card, CardContent } from './ui/card';
+import { Input } from './ui/input';
+import { Skeleton } from './ui/skeleton';
+import { cn } from './ui/utils';
+import { getAssetAlt } from '../lib/asset-alt';
+import { useCart } from '../lib/cart-context';
+import type { SellingPlan, SellingPlanGroup } from '../lib/forgecart';
+import { formatPrice, getPlanCadenceLabel, getPlanSavingsLabel } from '../lib/format';
+
+/**
+ * The interactive cart, rendered off the live order from `useCart()` —
+ * Blueprint `pages/checkout-flow` cart shape: line items on the left,
+ * a sticky order-summary rail (coupon, totals, checkout) on the right.
+ *
+ * `channelGroups` are the channel-wide subscription selling plans, fetched
+ * server-side by the cart route and passed in (the shop client is server-only,
+ * so a client component can't fetch them itself). When present, a "Subscribe to
+ * your whole order" box lets the customer put the entire order on a recurring
+ * plan; the chosen plan is reflected by the order's `sellingPlanId`. Lines that
+ * carry their own `sellingPlanId` (per-line subscriptions added from a product
+ * page) get a small "Subscription" label.
+ */
+export function CartView({
+  channelGroups,
+  locale,
+}: {
+  channelGroups: SellingPlanGroup[];
+  /** Threaded from the server page — a client component cannot read it. */
+  locale: LocaleBinding;
+}) {
+  const {
+    cart,
+    itemCount,
+    subtotal,
+    hydrated,
+    setQuantity,
+    remove,
+    setSellingPlan,
+    applyCoupon,
+    removeCoupon,
+    pending,
+    error,
+    clearError,
+  } = useCart();
+  const [couponInput, setCouponInput] = useState('');
+  const lines = cart?.lines ?? [];
+
+  // The cart hydrates over the shopper's websocket after mount (PPR shell) —
+  // a skeleton, never a false "empty cart" flash.
+  if (!hydrated) {
+    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>
+    );
+  }
+
+  if (itemCount === 0) {
+    return (
+      <div className="mx-auto max-w-md space-y-4 py-16 text-center">
+        <h1 className="text-3xl font-bold tracking-tight">Your cart</h1>
+        <p className="text-muted-foreground">
+          Your cart is empty — it starts the moment you add your first item.
+        </p>
+        <LocaleLink
+          href="/products"
+          locale={locale}
+          data-fc-track="cart-browse-products"
+          className={buttonVariants()}
+        >
+          Browse products
+        </LocaleLink>
+      </div>
+    );
+  }
+
+  // Channel-wide plans (enabled only), flattened across the channel groups.
+  const channelPlans: SellingPlan[] = channelGroups
+    .flatMap((g) => g.plans)
+    .filter((p) => p.enabled);
+  const activePlanId = cart?.sellingPlanId ?? null;
+
+  return (
+    <div className="space-y-8">
+      <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]">
+        <div className="space-y-6">
+          <ul className="divide-y rounded-xl border bg-card text-card-foreground">
+            {lines.map((line) => (
+              <li
+                key={line.id}
+                className="grid grid-cols-[auto_minmax(0,1fr)] items-center gap-4 p-4 sm:grid-cols-[auto_minmax(0,1fr)_auto]"
+              >
+                <div className="size-16 overflow-hidden rounded-md bg-muted">
+                  {line.featuredAsset?.preview ? (
+                    // eslint-disable-next-line @next/next/no-img-element
+                    <img
+                      src={line.featuredAsset.preview}
+                      alt={getAssetAlt(line.featuredAsset)}
+                      className="h-full w-full object-cover"
+                    />
+                  ) : null}
+                </div>
+
+                <div className="min-w-0">
+                  <p className="truncate font-medium">{line.productVariant.name}</p>
+                  <p className="text-sm text-muted-foreground">
+                    {formatPrice(line.unitPriceWithTax)} each
+                  </p>
+                  {line.sellingPlanId && (
+                    <Badge variant="secondary" className="mt-1">
+                      Subscription
+                    </Badge>
+                  )}
+                </div>
+
+                <div className="col-span-2 flex items-center justify-end gap-3 sm:col-span-1">
+                  <label className="sr-only" htmlFor={`qty-${line.id}`}>
+                    Quantity
+                  </label>
+                  <Input
+                    id={`qty-${line.id}`}
+                    type="number"
+                    min={0}
+                    value={line.quantity}
+                    disabled={pending}
+                    onChange={(e) => {
+                      // 0 is a real value — updateLine removes the line for it.
+                      const parsed = Number.parseInt(e.target.value, 10);
+                      setQuantity(line.id, Number.isNaN(parsed) ? line.quantity : parsed);
+                    }}
+                    className="h-8 w-16"
+                  />
+                  <div className="w-20 text-right font-medium tabular-nums">
+                    {formatPrice(line.linePriceWithTax)}
+                  </div>
+                  <Button
+                    type="button"
+                    variant="link"
+                    size="sm"
+                    onClick={() => remove(line.id)}
+                    disabled={pending}
+                    className="h-auto px-0 text-xs text-muted-foreground hover:text-destructive"
+                    aria-label={`Remove ${line.productVariant.name}`}
+                  >
+                    Remove
+                  </Button>
+                </div>
+              </li>
+            ))}
+          </ul>
+
+          {channelPlans.length > 0 && (
+            <Card className="gap-0 py-0">
+              <CardContent className="flex flex-col gap-3 p-5">
+                <h2 className="text-base font-semibold">Subscribe to your whole order</h2>
+                <div className="flex flex-col gap-2">
+                  <button
+                    type="button"
+                    onClick={() => setSellingPlan(null)}
+                    disabled={pending}
+                    aria-pressed={activePlanId === null}
+                    className={cn(
+                      'rounded-md border px-3 py-2 text-left text-sm transition-colors disabled:opacity-50',
+                      activePlanId === null
+                        ? 'border-primary ring-1 ring-primary'
+                        : 'hover:border-primary',
+                    )}
+                  >
+                    <span className="font-medium">No, one-time</span>
+                  </button>
+                  {channelPlans.map((plan) => {
+                    const savings = getPlanSavingsLabel(plan);
+                    const hint = [
+                      savings,
+                      plan.trialDays > 0 ? `${plan.trialDays}-day free trial` : null,
+                    ]
+                      .filter(Boolean)
+                      .join(' · ');
+                    const active = activePlanId === plan.id;
+                    return (
+                      <button
+                        key={plan.id}
+                        type="button"
+                        onClick={() => setSellingPlan(plan.id)}
+                        disabled={pending}
+                        data-fc-track="cart-subscribe-order"
+                        aria-pressed={active}
+                        className={cn(
+                          'rounded-md border px-3 py-2 text-left text-sm transition-colors disabled:opacity-50',
+                          active ? 'border-primary ring-1 ring-primary' : 'hover:border-primary',
+                        )}
+                      >
+                        <span className="block font-medium">
+                          Subscribe — {getPlanCadenceLabel(plan)}
+                        </span>
+                        {hint && <span className="block text-xs text-muted-foreground">{hint}</span>}
+                      </button>
+                    );
+                  })}
+                </div>
+              </CardContent>
+            </Card>
+          )}
+        </div>
+
+        <aside className="lg:sticky lg:top-24" aria-label="Order summary">
+          <Card className="gap-0 py-0">
+            <CardContent className="flex flex-col gap-4 p-5">
+              <h2 className="text-base font-semibold">Order summary</h2>
+
+              <form
+                className="flex gap-2"
+                onSubmit={(e) => {
+                  e.preventDefault();
+                  const code = couponInput.trim();
+                  if (!code) return;
+                  applyCoupon(code);
+                  setCouponInput('');
+                }}
+              >
+                <label className="sr-only" htmlFor="coupon-code">
+                  Coupon code
+                </label>
+                <Input
+                  id="coupon-code"
+                  type="text"
+                  value={couponInput}
+                  placeholder="Coupon code"
+                  disabled={pending}
+                  onChange={(e) => setCouponInput(e.target.value)}
+                  className="h-8 flex-1"
+                />
+                <Button
+                  type="submit"
+                  variant="outline"
+                  size="sm"
+                  disabled={pending}
+                  data-fc-track="cart-apply-coupon"
+                >
+                  Apply
+                </Button>
+              </form>
+
+              {(cart?.couponCodes.length ?? 0) > 0 && (
+                <div className="flex flex-wrap gap-2">
+                  {cart!.couponCodes.map((code) => (
+                    <Badge key={code} variant="secondary">
+                      {code}
+                      <button
+                        type="button"
+                        onClick={() => removeCoupon(code)}
+                        disabled={pending}
+                        aria-label={`Remove coupon ${code}`}
+                      >
+                        ✕
+                      </button>
+                    </Badge>
+                  ))}
+                </div>
+              )}
+
+              {error && (
+                <Alert
+                  role="alert"
+                  variant="destructive"
+                  className="flex items-center justify-between gap-3"
+                >
+                  <AlertDescription>{error.message ?? error.code}</AlertDescription>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    className="h-7 px-2"
+                    onClick={clearError}
+                  >
+                    Dismiss
+                  </Button>
+                </Alert>
+              )}
+
+              <div className="space-y-1 border-t pt-3">
+                <div className="flex items-center justify-between">
+                  <span className="text-sm text-muted-foreground">
+                    Subtotal ({itemCount} items)
+                  </span>
+                  <span className="font-medium tabular-nums">{formatPrice(subtotal)}</span>
+                </div>
+                {(cart?.discounts ?? []).map((discount) => (
+                  <div key={discount.description} className="flex items-center justify-between">
+                    <span className="text-sm text-muted-foreground">{discount.description}</span>
+                    <span className="text-sm tabular-nums">
+                      −{formatPrice(Math.abs(discount.amountWithTax))}
+                    </span>
+                  </div>
+                ))}
+                <div className="flex items-center justify-between pt-1">
+                  <span className="text-sm text-muted-foreground">Total</span>
+                  <span className="text-lg font-semibold tabular-nums">
+                    {formatPrice(cart?.totalWithTax ?? subtotal)}
+                  </span>
+                </div>
+              </div>
+
+              <LocaleLink
+                href="/checkout"
+                locale={locale}
+                data-fc-track="cart-checkout"
+                className={cn(buttonVariants(), 'w-full')}
+              >
+                Checkout
+              </LocaleLink>
+            </CardContent>
+          </Card>
+        </aside>
+      </div>
+    </div>
+  );
+}