@forgecart/cli 2.0.0 → 2.1.1

package/dist/src/cli.d.ts

@@ -1,6 +1,9 @@
 import { Command } from 'commander';
-/** CLI version, kept in sync with `package.json`. */
-export declare const CLI_VERSION = "2.0.0";
+/**
+ * CLI version, read from `package.json` (the single source of truth) so the
+ * `--version` output can never drift from the published version.
+ */
+export declare const CLI_VERSION: string;
 /**
  * Build the `forgecart` commander program with the full command surface.
  *

package/dist/src/cli.js

@@ -1,9 +1,33 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { createInitCommand } from './commands/init.js';
 import { createDeleteCommand, createDeployCommand, createEnvCommand, createInitApplicationCommand, createListCommand, createLogsCommand, createScaleCommand, createStatusCommand, createWhoamiCommand, } from './commands/placeholders.js';
 import { printError } from './output.js';
-/** CLI version, kept in sync with `package.json`. */
-export const CLI_VERSION = '2.0.0';
+/**
+ * Resolve the package manifest from this module's location. The depth differs
+ * by layout — `src/cli.ts` (dev) sits one level below the package root,
+ * `dist/src/cli.js` (published) two — and `dist/` never contains a
+ * `package.json`, so the first existing candidate is always the right one.
+ */
+function readPackageVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.join(here, '..', 'package.json'),
+        path.join(here, '..', '..', 'package.json'),
+    ];
+    const manifest = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!manifest) {
+        throw new Error(`package.json not found near ${here}; cannot resolve the CLI version.`);
+    }
+    return JSON.parse(fs.readFileSync(manifest, 'utf-8')).version;
+}
+/**
+ * CLI version, read from `package.json` (the single source of truth) so the
+ * `--version` output can never drift from the published version.
+ */
+export const CLI_VERSION = readPackageVersion();
 /**
  * Build the `forgecart` commander program with the full command surface.
  *

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,4BAA4B,EAC5B,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,WAAW,CAAC;SACjB,WAAW,CAAC,iEAAiE,CAAC;SAC9E,OAAO,CAAC,WAAW,CAAC,CAAC;IAExB,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,4BAA4B,EAAE,CAAC,CAAC;IACnD,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACxC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC1C,OAAO,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACzC,OAAO,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC,CAAC;IACvC,OAAO,CAAC,UAAU,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAE1C,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,OAAiB,OAAO,CAAC,IAAI;IACrD,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;IAChC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,UAAU,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;QAChC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/commands/init.d.ts

@@ -1,6 +1,23 @@
 import { Command } from 'commander';
 /** Default shop API base. Overridable via `--api-url`. */
 export declare const DEFAULT_SHOP_API_URL = "https://api.forgecart.com";
+/**
+ * Environment variable naming a dependency-warmed storefront template — a copy
+ * of the bundled template with `node_modules` (and the generated
+ * `package-lock.json`) already installed. The workspace-pod image bakes one at
+ * build time (`docker/workspace-pod/Dockerfile`) and exports this variable so a
+ * pod scaffold copies warm dependencies instead of paying a cold `npm install`.
+ */
+export declare const WORKSPACE_TEMPLATE_DIR_ENV = "WORKSPACE_TEMPLATE_DIR";
+/**
+ * Marker file, relative to the scaffolded storefront root, recording that
+ * `node_modules` was copied fully installed from a warmed template whose
+ * manifest matches this CLI's bundled template. Orchestrators (the agent's
+ * `ChannelWorkspaceService`) skip their `npm install` step when the marker is
+ * present right after a fresh scaffold; its absence always falls back to a
+ * regular install, so older images and cold scaffolds keep working unchanged.
+ */
+export declare const DEPS_READY_MARKER_PATH = ".forgecart/deps-ready.json";
 /** Resolved options for `forgecart init`. */
 export interface InitOptions {
     /** Channel token (required). */
@@ -13,9 +30,11 @@ export interface InitOptions {
 /**
  * Run `forgecart init`.
  *
- * Resolves the target directory, copies the bundled storefront template into it,
- * writes the ForgeCart config and `.env.local`, then prints next steps. Throws a
- * clear Error on any failure (missing token, missing template, copy failure).
+ * Resolves the target directory, scaffolds the storefront from the warmed
+ * template when one is available (see {@link resolveScaffoldPlan}) or the
+ * bundled template otherwise, writes the ForgeCart config and `.env.local`, and
+ * prints next steps. Throws a clear Error on any failure (missing token,
+ * missing template, copy failure).
  */
 export declare function runInit(name: string | undefined, options: InitOptions): Promise<void>;
 /** Build the `init [name]` command. */

package/dist/src/commands/init.js

@@ -1,10 +1,27 @@
-import { mkdir, cp, writeFile, stat } from 'node:fs/promises';
+import { mkdir, cp, readFile, rm, writeFile, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import { print } from '../output.js';
 /** Default shop API base. Overridable via `--api-url`. */
 export const DEFAULT_SHOP_API_URL = 'https://api.forgecart.com';
+/**
+ * Environment variable naming a dependency-warmed storefront template — a copy
+ * of the bundled template with `node_modules` (and the generated
+ * `package-lock.json`) already installed. The workspace-pod image bakes one at
+ * build time (`docker/workspace-pod/Dockerfile`) and exports this variable so a
+ * pod scaffold copies warm dependencies instead of paying a cold `npm install`.
+ */
+export const WORKSPACE_TEMPLATE_DIR_ENV = 'WORKSPACE_TEMPLATE_DIR';
+/**
+ * Marker file, relative to the scaffolded storefront root, recording that
+ * `node_modules` was copied fully installed from a warmed template whose
+ * manifest matches this CLI's bundled template. Orchestrators (the agent's
+ * `ChannelWorkspaceService`) skip their `npm install` step when the marker is
+ * present right after a fresh scaffold; its absence always falls back to a
+ * regular install, so older images and cold scaffolds keep working unchanged.
+ */
+export const DEPS_READY_MARKER_PATH = '.forgecart/deps-ready.json';
 /**
  * Absolute path to the bundled storefront scaffold.
  *
@@ -25,6 +42,67 @@ async function isDirectory(path) {
         return false;
     }
 }
+/**
+ * Read a `package.json` and normalize it for content comparison. Returns null
+ * when the file is missing or not valid JSON — callers treat that as "manifests
+ * do not provably match", which always falls back to an install.
+ */
+async function readNormalizedManifest(manifestPath) {
+    try {
+        return JSON.stringify(JSON.parse(await readFile(manifestPath, 'utf8')));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide how to source the scaffold. The warmed template is used only when
+ * {@link WORKSPACE_TEMPLATE_DIR_ENV} points at a directory that actually
+ * contains an installed `node_modules`; full reuse (skipping the install)
+ * additionally requires its manifest to match the bundled template's, byte for
+ * semantic byte. Every failure mode degrades to the cold bundled path, so
+ * images without a warmed template — and machines where the variable is unset —
+ * behave exactly as before.
+ */
+async function resolveScaffoldPlan(bundledTemplateDir) {
+    const bundled = { source: 'bundled', templateDir: bundledTemplateDir };
+    const warmedDir = process.env[WORKSPACE_TEMPLATE_DIR_ENV];
+    if (!warmedDir)
+        return bundled;
+    if (!(await isDirectory(warmedDir)))
+        return bundled;
+    const warmedNodeModulesDir = join(warmedDir, 'node_modules');
+    if (!(await isDirectory(warmedNodeModulesDir)))
+        return bundled;
+    const warmedManifest = await readNormalizedManifest(join(warmedDir, 'package.json'));
+    const bundledManifest = await readNormalizedManifest(join(bundledTemplateDir, 'package.json'));
+    if (!warmedManifest || !bundledManifest || warmedManifest !== bundledManifest) {
+        return {
+            source: 'bundled-with-warmed-modules',
+            templateDir: bundledTemplateDir,
+            warmedNodeModulesDir,
+        };
+    }
+    return { source: 'warmed', templateDir: warmedDir };
+}
+/**
+ * Record — or clear — the dependencies-ready marker. It is written only for a
+ * full warmed scaffold; any other plan removes a marker a previous scaffold may
+ * have left in the same directory, so an orchestrator never skips its install
+ * based on stale state.
+ */
+async function writeDepsReadyMarker(targetDir, plan) {
+    const markerPath = join(targetDir, DEPS_READY_MARKER_PATH);
+    if (plan.source !== 'warmed') {
+        await rm(markerPath, { force: true });
+        return;
+    }
+    const marker = {
+        warmedFrom: plan.templateDir,
+        warmedAt: new Date().toISOString(),
+    };
+    await writeFile(markerPath, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+}
 /** Build the `.forgecart/config.json` payload. */
 function buildConfig(channelToken, options) {
     return {
@@ -44,13 +122,17 @@ function buildEnvLocal(channelToken, apiUrl) {
     ].join('\n');
 }
 /** Print the post-scaffold next steps. */
-function printNextSteps(targetDir, application) {
+function printNextSteps(targetDir, application, depsInstalled) {
     print('');
-    print('Storefront scaffolded successfully.');
+    print(depsInstalled
+        ? 'Storefront scaffolded successfully (dependencies pre-installed from the warmed template).'
+        : 'Storefront scaffolded successfully.');
     print('');
     print('Next steps:');
     print(`  cd ${targetDir}`);
-    print('  npm install');
+    if (!depsInstalled) {
+        print('  npm install');
+    }
     print('  npm run dev');
     print('');
     if (application) {
@@ -62,9 +144,11 @@ function printNextSteps(targetDir, application) {
 /**
  * Run `forgecart init`.
  *
- * Resolves the target directory, copies the bundled storefront template into it,
- * writes the ForgeCart config and `.env.local`, then prints next steps. Throws a
- * clear Error on any failure (missing token, missing template, copy failure).
+ * Resolves the target directory, scaffolds the storefront from the warmed
+ * template when one is available (see {@link resolveScaffoldPlan}) or the
+ * bundled template otherwise, writes the ForgeCart config and `.env.local`, and
+ * prints next steps. Throws a clear Error on any failure (missing token,
+ * missing template, copy failure).
  */
 export async function runInit(name, options) {
     const channelToken = options.token?.trim();
@@ -76,14 +160,21 @@ export async function runInit(name, options) {
     if (!(await isDirectory(templateDir))) {
         throw new Error(`Storefront template not found at ${templateDir}.`);
     }
+    const plan = await resolveScaffoldPlan(templateDir);
     await mkdir(targetDir, { recursive: true });
-    await cp(templateDir, targetDir, { recursive: true });
+    await cp(plan.templateDir, targetDir, { recursive: true });
+    if (plan.source === 'bundled-with-warmed-modules') {
+        await cp(plan.warmedNodeModulesDir, join(targetDir, 'node_modules'), {
+            recursive: true,
+        });
+    }
     const configDir = join(targetDir, '.forgecart');
     await mkdir(configDir, { recursive: true });
     const config = buildConfig(channelToken, options);
     await writeFile(join(configDir, 'config.json'), `${JSON.stringify(config, null, 2)}\n`, 'utf8');
     await writeFile(join(targetDir, '.env.local'), buildEnvLocal(channelToken, options.apiUrl), 'utf8');
-    printNextSteps(name ?? '.', config.hasApplication);
+    await writeDepsReadyMarker(targetDir, plan);
+    printNextSteps(name ?? '.', config.hasApplication, plan.source === 'warmed');
 }
 /** Build the `init [name]` command. */
 export function createInitCommand() {

package/dist/src/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/package.json

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

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

@@ -2,11 +2,12 @@
 
 import Link from 'next/link';
 
-import { formatPrice } from '../../lib/forgecart';
 import { useCart } from '../../lib/cart-context';
+import { formatPrice } from '../../lib/forgecart';
 
 export default function CartPage() {
-  const { lines, subtotal, itemCount, setQuantity, removeLine, clear } = useCart();
+  const { cart, itemCount, subtotal, setQuantity, remove, pending } = useCart();
+  const lines = cart?.lines ?? [];
 
   if (itemCount === 0) {
     return (
@@ -25,66 +26,52 @@ export default function CartPage() {
 
   return (
     <div className="space-y-6">
-      <div className="flex items-center justify-between">
-        <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
-        <button
-          type="button"
-          onClick={clear}
-          className="text-sm text-gray-500 hover:text-gray-900"
-        >
-          Clear cart
-        </button>
-      </div>
+      <h1 className="text-2xl font-bold tracking-tight text-gray-900">Your cart</h1>
 
       <ul className="divide-y divide-gray-200 rounded-lg border border-gray-200 bg-white">
         {lines.map((line) => (
-          <li key={line.variantId} className="flex items-center gap-4 p-4">
+          <li key={line.id} className="flex items-center gap-4 p-4">
             <div className="h-16 w-16 shrink-0 overflow-hidden rounded bg-gray-100">
-              {line.imageUrl ? (
+              {line.featuredAsset?.preview ? (
                 // eslint-disable-next-line @next/next/no-img-element
                 <img
-                  src={line.imageUrl}
-                  alt={line.name}
+                  src={line.featuredAsset.preview}
+                  alt={line.productVariant.name}
                   className="h-full w-full object-cover"
                 />
               ) : null}
             </div>
 
             <div className="min-w-0 flex-1">
-              <Link
-                href={`/products/${line.productSlug}`}
-                className="truncate font-medium text-gray-900 hover:underline"
-              >
-                {line.name}
-              </Link>
-              <p className="text-sm text-gray-500">{formatPrice(line.unitPrice)} each</p>
+              <p className="truncate font-medium text-gray-900">{line.productVariant.name}</p>
+              <p className="text-sm text-gray-500">{formatPrice(line.unitPriceWithTax)} each</p>
             </div>
 
             <div className="flex items-center gap-2">
-              <label className="sr-only" htmlFor={`qty-${line.variantId}`}>
+              <label className="sr-only" htmlFor={`qty-${line.id}`}>
                 Quantity
               </label>
               <input
-                id={`qty-${line.variantId}`}
+                id={`qty-${line.id}`}
                 type="number"
                 min={1}
                 value={line.quantity}
-                onChange={(e) =>
-                  setQuantity(line.variantId, Number.parseInt(e.target.value, 10) || 1)
-                }
-                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm"
+                disabled={pending}
+                onChange={(e) => setQuantity(line.id, Number.parseInt(e.target.value, 10) || 1)}
+                className="w-16 rounded border border-gray-300 px-2 py-1 text-sm disabled:opacity-50"
               />
             </div>
 
             <div className="w-24 text-right font-medium text-gray-900">
-              {formatPrice(line.unitPrice * line.quantity)}
+              {formatPrice(line.linePriceWithTax)}
             </div>
 
             <button
               type="button"
-              onClick={() => removeLine(line.variantId)}
-              className="text-sm text-gray-400 hover:text-red-600"
-              aria-label={`Remove ${line.name}`}
+              onClick={() => remove(line.id)}
+              disabled={pending}
+              className="text-sm text-gray-400 hover:text-red-600 disabled:opacity-50"
+              aria-label={`Remove ${line.productVariant.name}`}
             >
               Remove
             </button>
@@ -94,17 +81,8 @@ export default function CartPage() {
 
       <div className="flex items-center justify-between rounded-lg border border-gray-200 bg-white p-4">
         <span className="text-sm text-gray-600">Subtotal ({itemCount} items)</span>
-        <span className="text-lg font-semibold text-gray-900">
-          {formatPrice(subtotal)}
-        </span>
+        <span className="text-lg font-semibold text-gray-900">{formatPrice(subtotal)}</span>
       </div>
-
-      <p className="text-sm text-gray-500">
-        This is a starter cart with local state. Wire it to the ForgeCart{' '}
-        <code className="rounded bg-gray-100 px-1">cart</code> /{' '}
-        <code className="rounded bg-gray-100 px-1">checkout</code> APIs to take real
-        orders.
-      </p>
     </div>
   );
 }

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

@@ -2,6 +2,7 @@ import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
 
 import { Header } from '../components/Header';
+import { getCart } from '../lib/cart-actions';
 import { CartProvider } from '../lib/cart-context';
 
 import './globals.css';
@@ -11,11 +12,12 @@ export const metadata: Metadata = {
   description: 'A ForgeCart channel storefront.',
 };
 
-export default function RootLayout({ children }: { children: ReactNode }) {
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const initialCart = await getCart();
   return (
     <html lang="en">
       <body className="min-h-screen bg-gray-50 text-gray-900 antialiased">
-        <CartProvider>
+        <CartProvider initialCart={initialCart}>
           <Header />
           <main className="mx-auto max-w-6xl px-4 py-8">{children}</main>
           <footer className="border-t border-gray-200 bg-white">

package/templates/storefront/src/app/products/[slug]/page.tsx

@@ -1,8 +1,8 @@
 import Link from 'next/link';
 import { notFound } from 'next/navigation';
 
-import { AddToCartButton } from '../../../components/AddToCartButton';
-import { formatPrice, getProductBySlug } from '../../../lib/forgecart';
+import { ProductPurchase } from '../../../components/ProductPurchase';
+import { getProductBySlug } from '../../../lib/forgecart';
 
 export const dynamic = 'force-dynamic';
 
@@ -19,8 +19,6 @@ export default async function ProductDetailPage({
     notFound();
   }
 
-  const defaultVariant = product.variants[0] ?? null;
-
   return (
     <div className="space-y-6">
       <Link href="/products" className="text-sm text-gray-600 hover:text-gray-900">
@@ -44,15 +42,7 @@ export default async function ProductDetailPage({
         </div>
 
         <div className="space-y-4">
-          <h1 className="text-2xl font-bold tracking-tight text-gray-900">
-            {product.name}
-          </h1>
-
-          {defaultVariant && (
-            <p className="text-xl font-semibold text-gray-900">
-              {formatPrice(defaultVariant.priceWithTax)}
-            </p>
-          )}
+          <h1 className="text-2xl font-bold tracking-tight text-gray-900">{product.name}</h1>
 
           {product.description && (
             <div
@@ -62,33 +52,8 @@ export default async function ProductDetailPage({
             />
           )}
 
-          {defaultVariant ? (
-            <AddToCartButton
-              line={{
-                variantId: defaultVariant.id,
-                productSlug: product.slug,
-                name: product.name,
-                unitPrice: defaultVariant.priceWithTax,
-                imageUrl: product.featuredAsset?.preview ?? null,
-              }}
-            />
-          ) : (
-            <p className="text-sm text-gray-500">Currently unavailable.</p>
-          )}
-
-          {product.variants.length > 1 && (
-            <div className="pt-2">
-              <h2 className="mb-2 text-sm font-medium text-gray-700">Variants</h2>
-              <ul className="space-y-1 text-sm text-gray-600">
-                {product.variants.map((variant) => (
-                  <li key={variant.id} className="flex justify-between gap-4">
-                    <span>{variant.name}</span>
-                    <span>{formatPrice(variant.priceWithTax)}</span>
-                  </li>
-                ))}
-              </ul>
-            </div>
-          )}
+          {/* Pick a variant (Size/Color) -> price + add-to-cart. */}
+          <ProductPurchase product={product} />
         </div>
       </div>
     </div>

package/templates/storefront/src/components/Header.tsx

@@ -1,6 +1,7 @@
 'use client';
 
 import Link from 'next/link';
+import { useEffect, useState } from 'react';
 
 import { useCart } from '../lib/cart-context';
 
@@ -8,6 +9,16 @@ import { useCart } from '../lib/cart-context';
 export function Header() {
   const { itemCount } = useCart();
 
+  // The count is seeded from the server's `initialCart`, but a cookie set after
+  // that render can leave the client with a different count — rendering the
+  // badge on the server would then hydration-mismatch. Gate it on a
+  // post-hydration mount flag so the server emits no badge; it appears with the
+  // live count only once the client takes over.
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
   return (
     <header className="border-b border-gray-200 bg-white">
       <div className="mx-auto flex max-w-6xl items-center justify-between px-4 py-4">
@@ -23,7 +34,7 @@ export function Header() {
           </Link>
           <Link href="/cart" className="relative hover:text-gray-900">
             Cart
-            {itemCount > 0 && (
+            {mounted && itemCount > 0 && (
               <span className="ml-1 inline-flex h-5 min-w-5 items-center justify-center rounded-full bg-gray-900 px-1.5 text-xs font-semibold text-white">
                 {itemCount}
               </span>

package/templates/storefront/src/components/ProductCard.tsx

@@ -1,13 +1,10 @@
+import type { Product } from '@forgecart/sdk/shop';
 import Link from 'next/link';
 
-import {
-  formatPrice,
-  getStartingPrice,
-  type StorefrontProduct,
-} from '../lib/forgecart';
+import { formatPrice, getStartingPrice } from '../lib/forgecart';
 
 /** A product tile linking to its detail page. Used by the home and grid pages. */
-export function ProductCard({ product }: { product: StorefrontProduct }) {
+export function ProductCard({ product }: { product: Product }) {
   const startingPrice = getStartingPrice(product);
 
   return (

package/templates/storefront/src/components/ProductPurchase.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import type { Product, ProductVariant } from '@forgecart/sdk/shop';
+import { useMemo, useState } from 'react';
+
+import { useCart } from '../lib/cart-context';
+import { formatPrice } from '../lib/forgecart';
+
+/**
+ * Variant picker + add-to-cart for the product detail page.
+ *
+ * The customer picks one value per option group (Size, Color, …); the matching
+ * variant drives the displayed price and what gets added to the cart — you add a
+ * **variant**, never the product. Single-variant products skip the selectors.
+ */
+export function ProductPurchase({ product }: { product: Product }) {
+  const { add, pending } = useCart();
+  const [added, setAdded] = useState(false);
+
+  // Default selection = the first variant's option values, so a price shows
+  // immediately. Keyed by option group id -> selected option id.
+  const [selected, setSelected] = useState<Record<string, string>>(() => {
+    const sel: Record<string, string> = {};
+    for (const option of product.variants[0]?.options ?? []) {
+      sel[option.groupId] = option.id;
+    }
+    return sel;
+  });
+
+  const variant: ProductVariant | undefined = useMemo(() => {
+    if (product.variants.length <= 1) {
+      return product.variants[0];
+    }
+    return product.variants.find(
+      (v) => v.options.length > 0 && v.options.every((o) => selected[o.groupId] === o.id),
+    );
+  }, [product.variants, selected]);
+
+  const onAdd = () => {
+    if (!variant) {
+      return;
+    }
+    add(variant.id, 1);
+    setAdded(true);
+    window.setTimeout(() => setAdded(false), 1500);
+  };
+
+  return (
+    <div className="space-y-4">
+      {variant ? (
+        <p className="text-xl font-semibold text-gray-900">{formatPrice(variant.priceWithTax)}</p>
+      ) : (
+        <p className="text-sm text-gray-500">Select options to see the price.</p>
+      )}
+
+      {product.optionGroups.map((group) => (
+        <div key={group.id}>
+          <h3 className="mb-1 text-sm font-medium text-gray-700">{group.name}</h3>
+          <div className="flex flex-wrap gap-2">
+            {group.options.map((opt) => {
+              const active = selected[group.id] === opt.id;
+              return (
+                <button
+                  key={opt.id}
+                  type="button"
+                  onClick={() => setSelected((s) => ({ ...s, [group.id]: opt.id }))}
+                  className={`rounded-md border px-3 py-1.5 text-sm transition ${
+                    active
+                      ? 'border-gray-900 bg-gray-900 text-white'
+                      : 'border-gray-300 text-gray-700 hover:border-gray-900'
+                  }`}
+                >
+                  {opt.name}
+                </button>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+
+      <button
+        type="button"
+        onClick={onAdd}
+        disabled={!variant || pending}
+        className="rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700 disabled:cursor-not-allowed disabled:opacity-50"
+      >
+        {pending ? 'Adding…' : added ? 'Added!' : variant ? 'Add to cart' : 'Unavailable'}
+      </button>
+    </div>
+  );
+}

package/templates/storefront/src/lib/cart-actions.ts

@@ -0,0 +1,148 @@
+'use server';
+
+import type { Order } from '@forgecart/sdk/shop';
+import { cookies } from 'next/headers';
+
+/**
+ * Server-side cart, backed by the ForgeCart shop **order** API (the real cart),
+ * not browser storage. Every export here is a Server Action returning the live
+ * `Order` (the SDK type) so callers render straight off it.
+ *
+ * The anonymous active order is tracked by a session token: the shop API returns
+ * a fresh token in the `forgecart-auth-token` response header on the first
+ * mutation, which we persist into the httpOnly `forgecart-session` cookie and
+ * send back as a bearer token on every subsequent request. The channel token and
+ * the session never reach the browser — all cart calls run here, on the server.
+ */
+
+const SHOP_API_URL = process.env.FORGECART_SHOP_API_URL ?? '';
+const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
+const SESSION_COOKIE = 'forgecart-session';
+
+/** The order fields the storefront renders (a subset of the SDK `Order` type). */
+const ORDER_FIELDS = `
+  id
+  totalQuantity
+  subTotalWithTax
+  totalWithTax
+  currencyCode
+  lines {
+    id
+    quantity
+    unitPriceWithTax
+    linePriceWithTax
+    productVariant {
+      id
+      name
+    }
+    featuredAsset {
+      preview
+    }
+  }
+`;
+
+interface GraphQLResponse<T> {
+  data?: T;
+  errors?: { message: string }[];
+}
+
+/**
+ * Call the channel's shop API for a cart operation.
+ *
+ * `persist` MUST be `false` when called from a Server Component (the initial
+ * cart read): Server Components cannot set cookies — only Server Actions (the
+ * mutations) can, so they capture/refresh the session token.
+ */
+async function shopFetch<T>(
+  query: string,
+  variables: Record<string, unknown>,
+  persist: boolean,
+): Promise<GraphQLResponse<T>> {
+  const store = await cookies();
+  const session = store.get(SESSION_COOKIE)?.value;
+
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'forgecart-token': CHANNEL_TOKEN,
+  };
+  if (session) {
+    headers.authorization = `Bearer ${session}`;
+  }
+
+  const res = await fetch(SHOP_API_URL, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({ query, variables }),
+    cache: 'no-store',
+  });
+
+  if (persist) {
+    const token = res.headers.get('forgecart-auth-token');
+    if (token && token !== session) {
+      store.set(SESSION_COOKIE, token, {
+        httpOnly: true,
+        sameSite: 'lax',
+        path: '/',
+        maxAge: 60 * 60 * 24 * 30,
+      });
+    }
+  }
+
+  return (await res.json()) as GraphQLResponse<T>;
+}
+
+function unwrap<T>(res: GraphQLResponse<T>): T {
+  if (res.errors?.length) {
+    throw new Error(res.errors[0].message);
+  }
+  if (!res.data) {
+    throw new Error('Empty response from shop API');
+  }
+  return res.data;
+}
+
+/** Read the active order (cart). Safe to call from a Server Component. */
+export async function getCart(): Promise<Order | null> {
+  const res = await shopFetch<{ activeOrder: Order | null }>(
+    `query { activeOrder { ${ORDER_FIELDS} } }`,
+    {},
+    false,
+  );
+  return res.data?.activeOrder ?? null;
+}
+
+/** Add a variant to the cart (creates the order + session on first call). */
+export async function addToCart(variantId: string, quantity = 1): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ addItemToOrder: Order }>(
+      `mutation($input: ShopAddItemToOrderInput!) { addItemToOrder(input: $input) { ${ORDER_FIELDS} } }`,
+      { input: { variantId, quantity } },
+      true,
+    ),
+  );
+  return data.addItemToOrder;
+}
+
+/** Set the quantity of a cart line (0 removes it). */
+export async function updateLine(lineId: string, quantity: number): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ adjustOrderLine: Order }>(
+      `mutation($input: ShopAdjustOrderLineInput!) { adjustOrderLine(input: $input) { ${ORDER_FIELDS} } }`,
+      { input: { lineId, quantity } },
+      true,
+    ),
+  );
+  return data.adjustOrderLine;
+}
+
+/** Remove a line from the cart. */
+export async function removeLine(lineId: string): Promise<Order | null> {
+  const data = unwrap(
+    await shopFetch<{ removeOrderLine: Order }>(
+      `mutation($lineId: ID!) { removeOrderLine(lineId: $lineId) { ${ORDER_FIELDS} } }`,
+      { lineId },
+      true,
+    ),
+  );
+  return data.removeOrderLine;
+}

package/templates/storefront/src/lib/cart-context.tsx

@@ -1,107 +1,79 @@
 'use client';
 
+import type { Order } from '@forgecart/sdk/shop';
 import {
   createContext,
   useCallback,
   useContext,
-  useEffect,
   useMemo,
   useState,
+  useTransition,
   type ReactNode,
 } from 'react';
 
+import { addToCart, getCart, removeLine as removeLineAction, updateLine } from './cart-actions';
+
 /**
- * A line in the local cart. The MVP cart lives entirely in the browser
- * (localStorage); wiring it to the ForgeCart `cart` API is left as a follow-up.
- * `unitPrice` is in minor currency units (cents).
+ * Cart state backed by the ForgeCart shop order API (see `cart-actions.ts`).
+ *
+ * `cart` is the live `Order` (the SDK type). The provider is seeded with the
+ * server-fetched active order (`initialCart`) so the first paint is correct,
+ * then every mutation calls a Server Action and replaces it with the order the
+ * API returns. `pending` is true while a cart mutation is in flight.
  */
-export interface CartLine {
-  variantId: string;
-  productSlug: string;
-  name: string;
-  unitPrice: number;
-  quantity: number;
-  imageUrl: string | null;
-}
-
 interface CartContextValue {
-  lines: CartLine[];
+  cart: Order | null;
   itemCount: number;
   subtotal: number;
-  addLine: (line: Omit<CartLine, 'quantity'>, quantity?: number) => void;
-  setQuantity: (variantId: string, quantity: number) => void;
-  removeLine: (variantId: string) => void;
-  clear: () => void;
+  pending: boolean;
+  add: (variantId: string, quantity?: number) => void;
+  setQuantity: (lineId: string, quantity: number) => void;
+  remove: (lineId: string) => void;
+  refresh: () => void;
 }
 
-const STORAGE_KEY = 'forgecart.cart';
-
 const CartContext = createContext<CartContextValue | null>(null);
 
-function readStoredLines(): CartLine[] {
-  if (typeof window === 'undefined') {
-    return [];
-  }
-  try {
-    const raw = window.localStorage.getItem(STORAGE_KEY);
-    return raw ? (JSON.parse(raw) as CartLine[]) : [];
-  } catch {
-    return [];
-  }
-}
-
-export function CartProvider({ children }: { children: ReactNode }) {
-  const [lines, setLines] = useState<CartLine[]>([]);
-
-  // Hydrate from localStorage once on mount (avoids SSR hydration mismatch).
-  useEffect(() => {
-    setLines(readStoredLines());
+export function CartProvider({
+  initialCart,
+  children,
+}: {
+  initialCart: Order | null;
+  children: ReactNode;
+}) {
+  const [cart, setCart] = useState<Order | null>(initialCart);
+  const [pending, startTransition] = useTransition();
+
+  const run = useCallback((op: () => Promise<Order | null>) => {
+    startTransition(async () => {
+      setCart(await op());
+    });
   }, []);
 
-  // Persist on every change.
-  useEffect(() => {
-    if (typeof window === 'undefined') {
-      return;
-    }
-    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(lines));
-  }, [lines]);
-
-  const addLine = useCallback(
-    (line: Omit<CartLine, 'quantity'>, quantity = 1) => {
-      setLines((prev) => {
-        const existing = prev.find((l) => l.variantId === line.variantId);
-        if (existing) {
-          return prev.map((l) =>
-            l.variantId === line.variantId
-              ? { ...l, quantity: l.quantity + quantity }
-              : l,
-          );
-        }
-        return [...prev, { ...line, quantity }];
-      });
-    },
-    [],
+  const add = useCallback(
+    (variantId: string, quantity = 1) => run(() => addToCart(variantId, quantity)),
+    [run],
+  );
+  const setQuantity = useCallback(
+    (lineId: string, quantity: number) => run(() => updateLine(lineId, quantity)),
+    [run],
+  );
+  const remove = useCallback((lineId: string) => run(() => removeLineAction(lineId)), [run]);
+  const refresh = useCallback(() => run(() => getCart()), [run]);
+
+  const value = useMemo<CartContextValue>(
+    () => ({
+      cart,
+      itemCount: cart?.totalQuantity ?? 0,
+      subtotal: cart?.subTotalWithTax ?? 0,
+      pending,
+      add,
+      setQuantity,
+      remove,
+      refresh,
+    }),
+    [cart, pending, add, setQuantity, remove, refresh],
   );
-
-  const setQuantity = useCallback((variantId: string, quantity: number) => {
-    setLines((prev) =>
-      quantity <= 0
-        ? prev.filter((l) => l.variantId !== variantId)
-        : prev.map((l) => (l.variantId === variantId ? { ...l, quantity } : l)),
-    );
-  }, []);
-
-  const removeLine = useCallback((variantId: string) => {
-    setLines((prev) => prev.filter((l) => l.variantId !== variantId));
-  }, []);
-
-  const clear = useCallback(() => setLines([]), []);
-
-  const value = useMemo<CartContextValue>(() => {
-    const itemCount = lines.reduce((sum, l) => sum + l.quantity, 0);
-    const subtotal = lines.reduce((sum, l) => sum + l.unitPrice * l.quantity, 0);
-    return { lines, itemCount, subtotal, addLine, setQuantity, removeLine, clear };
-  }, [lines, addLine, setQuantity, removeLine, clear]);
 
   return <CartContext.Provider value={value}>{children}</CartContext.Provider>;
 }

package/templates/storefront/src/lib/forgecart.ts

@@ -1,4 +1,5 @@
 import { ForgeCartShopClient } from '@forgecart/sdk';
+import type { Product, ProductList } from '@forgecart/sdk/shop';
 
 /**
  * Server-side ForgeCart shop client.
@@ -60,39 +61,10 @@ export const shopClient = (): ForgeCartShopClient => getShopClient();
  * `.shopProduct`) only select `id` + `optionGroups`, which is not enough to
  * render a storefront. We therefore use the SDK's supported raw-query escape
  * hatch (`ForgeCartShopClient.query<T>(document, variables)`) with documents
- * that select the display fields. Every field below exists on the shop schema's
- * `Product` / `ProductVariant` / `Asset` / `ProductList` types (available via
- * `@forgecart/sdk/shop`).
+ * that select the display fields, typed against the SDK's own `Product` /
+ * `ProductList` types (`@forgecart/sdk/shop`).
  * ------------------------------------------------------------------ */
 
-/** A single purchasable variant of a product. Prices are minor units (cents). */
-export interface StorefrontVariant {
-  id: string;
-  name: string;
-  sku: string | null;
-  /** Price in minor currency units (e.g. cents). */
-  price: number;
-  /** Price including tax, in minor currency units. */
-  priceWithTax: number;
-}
-
-/** A product as the storefront renders it. */
-export interface StorefrontProduct {
-  id: string;
-  name: string;
-  slug: string;
-  description: string | null;
-  /** Preview URL of the featured image, if any. */
-  featuredAsset: { id: string; preview: string } | null;
-  variants: StorefrontVariant[];
-}
-
-/** A page of products plus the total count for pagination. */
-export interface StorefrontProductList {
-  items: StorefrontProduct[];
-  totalItems: number;
-}
-
 const PRODUCT_FIELDS = `
   id
   name
@@ -102,12 +74,28 @@ const PRODUCT_FIELDS = `
     id
     preview
   }
+  optionGroups {
+    id
+    name
+    code
+    options {
+      id
+      name
+      code
+    }
+  }
   variants {
     id
     name
     sku
     price
     priceWithTax
+    options {
+      id
+      name
+      code
+      groupId
+    }
   }
 `;
 
@@ -127,14 +115,11 @@ const PRODUCT_BY_ID_QUERY = `query StorefrontProductById($id: ID) {
 }`;
 
 interface ProductsQueryResult {
-  products: {
-    items: StorefrontProduct[];
-    totalItems: number;
-  };
+  products: Pick<ProductList, 'items' | 'totalItems'>;
 }
 
 interface ProductQueryResult {
-  product: StorefrontProduct | null;
+  product: Product | null;
 }
 
 /**
@@ -144,7 +129,7 @@ interface ProductQueryResult {
  */
 export async function getProducts(
   options: { take?: number; skip?: number } = {},
-): Promise<StorefrontProductList> {
+): Promise<{ items: Product[]; totalItems: number }> {
   const { take = 24, skip = 0 } = options;
   const result = await getShopClient().query<ProductsQueryResult>(PRODUCTS_QUERY, {
     options: { take, skip },
@@ -156,7 +141,7 @@ export async function getProducts(
 }
 
 /** Fetch a single product by its URL slug. Returns `null` if not found. */
-export async function getProductBySlug(slug: string): Promise<StorefrontProduct | null> {
+export async function getProductBySlug(slug: string): Promise<Product | null> {
   const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_SLUG_QUERY, {
     slug,
   });
@@ -164,7 +149,7 @@ export async function getProductBySlug(slug: string): Promise<StorefrontProduct
 }
 
 /** Fetch a single product by id. Returns `null` if not found. */
-export async function getProductById(id: string): Promise<StorefrontProduct | null> {
+export async function getProductById(id: string): Promise<Product | null> {
   const result = await getShopClient().query<ProductQueryResult>(PRODUCT_BY_ID_QUERY, {
     id,
   });
@@ -174,13 +159,13 @@ export async function getProductById(id: string): Promise<StorefrontProduct | nu
 /**
  * Convenience: fetch a small set of products to feature on the home page.
  */
-export async function getFeaturedProducts(count = 4): Promise<StorefrontProduct[]> {
+export async function getFeaturedProducts(count = 4): Promise<Product[]> {
   const { items } = await getProducts({ take: count });
   return items;
 }
 
 /** Lowest variant price for a product, in minor units, or `null` if none. */
-export function getStartingPrice(product: StorefrontProduct): number | null {
+export function getStartingPrice(product: Product): number | null {
   if (product.variants.length === 0) {
     return null;
   }

package/templates/storefront/src/components/AddToCartButton.tsx

@@ -1,30 +0,0 @@
-'use client';
-
-import { useState } from 'react';
-
-import { useCart, type CartLine } from '../lib/cart-context';
-
-/**
- * Adds a specific variant to the local cart. Rendered on the product detail
- * page (a Server Component) with the variant's display data passed in as props.
- */
-export function AddToCartButton({ line }: { line: Omit<CartLine, 'quantity'> }) {
-  const { addLine } = useCart();
-  const [added, setAdded] = useState(false);
-
-  const onClick = () => {
-    addLine(line, 1);
-    setAdded(true);
-    window.setTimeout(() => setAdded(false), 1500);
-  };
-
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      className="rounded-md bg-gray-900 px-5 py-2.5 text-sm font-medium text-white transition hover:bg-gray-700"
-    >
-      {added ? 'Added!' : 'Add to cart'}
-    </button>
-  );
-}