@forgecart/cli 2.202610052310.0 → 2.202610060357.0

package/package.json

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

package/templates/storefront-shadcn/.forgecartignore

@@ -0,0 +1,2 @@
+node_modules
+.next

package/templates/storefront-shadcn/Procfile

@@ -0,0 +1 @@
+web: npm run start

package/templates/storefront-shadcn/README.md

@@ -0,0 +1,229 @@
+# Storefront
+
+A [Next.js](https://nextjs.org) (App Router) storefront for a ForgeCart
+channel: product browsing, a server-backed cart, and a complete multi-step
+checkout — all speaking the ForgeCart shop GraphQL API through the generated
+`@forgecart/sdk` client, styled with [shadcn/ui](https://ui.shadcn.com)
+components on Tailwind CSS.
+
+This directory is the scaffold copied verbatim into your project by
+`forgecart init --ui shadcn`. Nothing here is compiled by the ForgeCart
+monorepo; it ships as-is in the published `@forgecart/cli` package.
+
+To migrate a storefront built before the locale and SEO layer, follow [`SEO-MIGRATION.md`](SEO-MIGRATION.md).
+
+## Configuration
+
+The storefront reads three environment variables (server-side only):
+
+| Variable                  | Purpose                                                        |
+| ------------------------- | -------------------------------------------------------------- |
+| `FORGECART_CHANNEL_TOKEN` | Identifies the channel; sent as the `forgecart-token` header.  |
+| `FORGECART_SHOP_API_URL`  | Base URL of the channel's shop GraphQL API (`.../shop-api`).   |
+| `FORGECART_ADMIN_SECRET`  | Channel admin secret for server-side admin operations.         |
+
+`forgecart init` writes all of them to `.env` — it is the sole author of that
+file, and `.env` is the only env file this project ever has (no `.env.example`,
+no `.env.local`). None of the values ever reaches the
+browser: every module that constructs an SDK client starts with
+`import 'server-only'`, so a client component importing one is a **build
+error**, and the workspace-pod image build additionally asserts no SDK code
+lands in the client chunks.
+
+## The backend gate (`sdk.backend`)
+
+The storefront embeds a real NestJS backend under `src/server/` — booted as
+an application context (no HTTP server; Next.js owns HTTP) in
+`instrumentation.ts`, with normal `@Module`/`@Injectable` structure. A
+service method decorated with `@BackendMethod()` (and declared in
+`backend-api.ts`) becomes callable from any client component through the
+typed proxy:
+
+```ts
+import { backend } from '@/lib/backend-client';
+
+const result = await backend.assignCustomerHash({});
+if (!result.ok) renderError(result.error);
+```
+
+One Server Action is the transport — no routes, no fetch calls, no
+websockets. Methods receive a per-invocation session `{ admin, shop,
+hasSession }`: `admin` is the channel-admin SDK gate (from
+`FORGECART_ADMIN_SECRET`) and each method owns what that authority may be
+used for; inputs are untrusted. The decorator is the allowlist, boot fails
+loudly if the decorator scan and `backend-api.ts` drift, and in dev
+`/api/__backend/methods` lists the live registry. The worked example
+(`src/server/customer-extras/`) mints a random referral hash for the
+signed-in customer and stores it as an ACF custom-field entry.
+
+## Design system
+
+Styling is Tailwind v4 + shadcn/ui. The components are **vendored**, the way
+shadcn/ui intends: they live in [`src/components/ui/`](src/components/ui/)
+(`button`, `card`, `input`, `native-select`, `label`, `alert`, `badge`,
+`skeleton`) as source you own and edit, built on `class-variance-authority`,
+`clsx`, `tailwind-merge` and the Radix primitives they import. Their `cn`
+helper is [`src/components/ui/utils.ts`](src/components/ui/utils.ts), and
+[`components.json`](components.json) points the shadcn/ui CLI at both, so
+`npx shadcn@latest add <component>` lands a new component beside them.
+
+Every component uses **semantic** tokens only (`bg-card`, `text-foreground`,
+`border-input`, `bg-primary`, …), never a palette colour. The single source of
+brand truth is the `:root` block in [`src/app/globals.css`](src/app/globals.css),
+exposed to Tailwind through its `@theme inline` block — restyling the whole
+storefront means editing those variables and nothing else. The stylesheet's
+header carries the mapping from the daisyUI theme tokens of the daisyUI
+storefront onto these variables, so a brand written for one row carries over
+to the other.
+
+## Data flow
+
+**Transport.** The generated SDK carries every operation over graphql-ws — a
+per-request client is a per-request websocket connection. All SDK calls run on
+the server; nothing SDK-shaped ships to the browser.
+
+- [`src/lib/forgecart.ts`](src/lib/forgecart.ts) — the channel-scoped
+  singleton client for anonymous reads (products, selling plans) via typed
+  helpers (`getProducts`, `getProductBySlug`, `getFeaturedProducts`,
+  `getChannelSellingPlanGroups`, …), plus the SDK type re-exports the
+  components render. Pure display helpers (`formatPrice`,
+  `getStartingPrice`, plan labels) live in
+  [`src/lib/format.ts`](src/lib/format.ts), which client components import
+  freely — it carries no SDK runtime.
+- [`src/lib/shop-action.ts`](src/lib/shop-action.ts) — the Server-Action
+  runner: builds a per-request client around the shopper's
+  `forgecart-session` cookie, runs one operation, persists any newly minted
+  session token, translates failure into the typed envelope, and
+  `dispose()`s the client so no action leaks its socket.
+- [`src/lib/action-result.ts`](src/lib/action-result.ts) — `ActionResult<T>`:
+  Server Actions **never throw** across the RSC boundary (Next production
+  redacts thrown action errors). Failures arrive in-band as the SDK's
+  `ExtractedError` (`code`, server-localized `message`, `variables`), which
+  the UI renders inline.
+
+**Cart.** [`src/lib/cart-actions.ts`](src/lib/cart-actions.ts) drives the
+shop **order** API — the real cart, never browser storage. The interactive
+state lives in [`src/lib/cart-context.tsx`](src/lib/cart-context.tsx): seeded
+with the server-fetched order, updated from each action's returned order, and
+carrying the typed `error` channel the cart UI renders. Coupons
+(`applyCoupon`/`removeCoupon`) recalculate discounts and totals server-side;
+setting a line's quantity to `0` removes it.
+
+**Checkout.** [`src/lib/checkout-actions.ts`](src/lib/checkout-actions.ts) +
+[`src/components/checkout/`](src/components/checkout/) implement the
+reference flow behind a numbered step indicator (an ordered list whose current
+step carries `aria-current="step"` — shadcn/ui ships no stepper):
+
+1. **Contact** — guest email + name (`setCustomerForOrder`).
+2. **Address** — type-ahead via the shop `addressAutocomplete` API (optional
+   capability; manual entry always works), country select populated from
+   `availableCountries` (never a hardcoded list), and the **required phone
+   number** the API enforces.
+3. **Shipping** — `refreshShippingRateGroups` quotes carriers explicitly (the
+   read query never does), rates render grouped per shipment with per-group
+   carrier failures, and the customer picks — the ArrangingPayment
+   transition requires a selection in every group.
+4. **Payment** — eligible providers → `createPaymentSession` →
+   `getSessionTemplate` renders the provider's hosted form in
+   [`PaymentFormEmbed`](src/components/checkout/PaymentFormEmbed.tsx), which
+   listens for the origin-pinned `iframe-ready` / `payment-success` /
+   `payment-error` handshake. No provider-specific code exists in the
+   template; coupon edits freeze once a session exists (the amount is
+   locked at session creation).
+5. **Confirmation** — the order code and summary.
+
+Errors render where they belong: field-level for coded field errors
+(`SHIPPING_ADDRESS_PHONE_REQUIRED`, `SHIPPING_ADDRESS_COUNTRY_*`,
+`COUPON_CODE_*`) — the field marked `aria-invalid`, which is also what paints
+its destructive border — a step-level `Alert` (`role="alert"`) otherwise, with
+[`src/app/error.tsx`](src/app/error.tsx) and `global-error.tsx` as render
+backstops.
+
+## Sessions
+
+The anonymous session is minted by the API on the first cart mutation and
+persisted into the session cookie PAIR — the httpOnly `forgecart-session` plus
+its JS-readable `forgecart-session-client` mirror, whose one contract lives in
+[`src/lib/session-cookies.ts`](src/lib/session-cookies.ts) — by the action
+runner. The `/__fc/track` and `/__fc/identify` relays may **establish** that
+pair for pure browsers but never replace an existing cookie, and the tracker
+defers its first flush so a fast add-to-cart wins the first-touch race. The
+mirror is what the browser's shop socket boots its auth from: written without
+it, a relay-established session would never reach the client at all.
+
+## Account links
+
+Two routes exist because the PLATFORM links to them from the e-mails it sends
+a shopper, not because anything in this storefront navigates there:
+
+| Route                        | Mail                | What it does                                                 |
+| ---------------------------- | ------------------- | ------------------------------------------------------------ |
+| `/verify?token=…`            | e-mail verification | consumes the token on RENDER and reports the outcome          |
+| `/reset-password?token=…`    | password reset      | renders the new-password form; the SUBMIT consumes the token  |
+| `/reset-password` (no token) | —                   | asks for an address and has a new link sent                   |
+
+**Do not rename or prefix them.** The path and the `?token=` parameter are the
+contract with the mail templates, and a link already sitting in a shopper's
+inbox cannot be re-issued. They are in the once-per-store set
+([`src/lib/locale/grammar.ts`](src/lib/locale/grammar.ts)), so they never carry
+a locale prefix, and in `NOINDEX_PATHS`
+([`src/lib/seo/noindex.ts`](src/lib/seo/noindex.ts)), so they are `noindex`,
+absent from the XML sitemap and `Disallow`ed in `robots.txt` — a crawler that
+fetched one would spend a real shopper's one-shot token.
+
+The COPY is yours to rewrite. The states behind it are not invented per page:
+[`src/lib/account/`](src/lib/account/) maps the shop API's `ErrorCode`s onto a
+small state set (verified / link-invalid / wrong-store / …) that both pages
+render, and each surface stamps `data-fc-account-mode` + `data-fc-account-state`
+onto the element it renders, so the state is readable from the served HTML.
+
+## Project layout
+
+```
+components.json          # the shadcn/ui CLI's config: style, stylesheet, aliases
+src/
+  lib/
+    forgecart.ts         # server-only shop client + typed reads + SDK types
+    format.ts            # pure display helpers (client-safe)
+    shop-action.ts       # per-request action runner (envelope + dispose)
+    action-result.ts     # ActionResult<T> + fallback error
+    cart-actions.ts      # cart Server Actions (incl. coupons)
+    checkout-actions.ts  # checkout Server Actions
+    cart-context.tsx     # client cart state + typed error channel
+    account-actions.ts   # password-reset Server Actions
+    account/             # pure account-link rules (token, states, ErrorCode map)
+  components/
+    ui/                  # the vendored shadcn/ui components + their cn helper
+    Header.tsx           # top nav with live cart count
+    ProductCard.tsx      # product tile
+    ProductPurchase.tsx  # variant picker + purchase options + add-to-cart
+    CartView.tsx         # cart lines, coupons, totals, checkout CTA
+    checkout/
+      CheckoutFlow.tsx     # the stepped flow orchestrator
+      AddressStep.tsx      # autocomplete + countries + phone
+      RatesStep.tsx        # grouped radio-card rate selection
+      PaymentFormEmbed.tsx # origin-checked hosted-form host
+    account/
+      AccountMessage.tsx           # the one outcome block both account pages use
+      ResetPasswordForm.tsx        # set a new password from a reset token
+      RequestPasswordResetForm.tsx # ask for a reset link
+  app/
+    layout.tsx           # html shell + header/footer + CartProvider
+    globals.css          # Tailwind + the :root brand tokens + @theme inline
+    error.tsx            # route render backstop
+    global-error.tsx     # root render backstop
+    page.tsx             # home: featured products
+    products/            # grid + [slug] detail
+    cart/page.tsx        # cart
+    checkout/page.tsx    # the stepped checkout
+    verify/page.tsx          # e-mail verification link target
+    reset-password/page.tsx  # password-reset link target + request form
+```
+
+## Development
+
+```bash
+npm install
+npm run dev     # Turbopack dev server (what workspace pods run)
+npm run build   # production build (what deploys run; see Procfile)
+```