create-brainerce-store 1.80.0 → 1.81.0

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.80.0",
+      version: "1.81.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -914,6 +914,105 @@ var logger = {
   }
 };
 
+// src/device-flow.ts
+var import_node_child_process = require("child_process");
+function isOpenableUrl(value, apiBaseUrl) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return false;
+  const apiHost = (() => {
+    try {
+      return new URL(apiBaseUrl).hostname;
+    } catch {
+      return "";
+    }
+  })();
+  const base = apiHost.replace(/^api(-staging)?\./, "");
+  return url.hostname === base || url.hostname.endsWith(`.${base}`);
+}
+function openBrowser(url) {
+  const platform = process.platform;
+  const [cmd, args] = platform === "win32" ? ["cmd", ["/c", "start", "", url]] : platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    const child = (0, import_node_child_process.spawn)(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runDeviceFlow(apiBaseUrl, options = {}) {
+  let start;
+  try {
+    const res = await fetch(`${apiBaseUrl}/api/device-auth/start`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        clientName: options.clientName || process.env.BRAINERCE_CLIENT_NAME || "create-brainerce-store"
+      })
+    });
+    if (!res.ok) {
+      logger.error(
+        `Could not start the browser approval (HTTP ${res.status}).
+  Create a sales channel in the dashboard instead, then re-run with --connection-id vc_xxx.`
+      );
+      return null;
+    }
+    start = await res.json();
+  } catch (error) {
+    logger.error(
+      `Could not reach Brainerce to start the approval: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+  const opened = isOpenableUrl(start.verificationUriComplete, apiBaseUrl) && openBrowser(start.verificationUriComplete);
+  console.log();
+  logger.info(
+    opened ? "  Opened your browser to approve this connection." : "  Open this link to approve this connection:"
+  );
+  console.log(`  ${start.verificationUriComplete}`);
+  console.log(`  The page should show the code ${start.userCode} \u2014 check that it matches.`);
+  console.log();
+  logger.info("  Waiting for approval. A store and a sales channel are created if you have none.");
+  const deadline = Date.now() + start.expiresIn * 1e3;
+  let interval = (start.interval || 5) * 1e3;
+  while (Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, interval));
+    let result;
+    try {
+      const res = await fetch(`${apiBaseUrl}/api/device-auth/poll`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ deviceCode: start.deviceCode })
+      });
+      result = await res.json();
+    } catch {
+      continue;
+    }
+    if (result.status === "approved" && result.connectionId) {
+      logger.success("  Approved.");
+      return { connectionId: result.connectionId, storeId: result.storeId ?? null };
+    }
+    if (result.status === "denied") {
+      logger.error("  The connection request was declined. Nothing was created.");
+      return null;
+    }
+    if (result.status === "expired") {
+      logger.error("  The code expired before it was approved. Run the command again.");
+      return null;
+    }
+    if (result.status === "slow_down") interval += 1e3;
+  }
+  logger.error("  Timed out waiting for approval. Run the command again for a fresh code.");
+  return null;
+}
+
 // src/utils/spinner.ts
 var import_ora = __toESM(require("ora"));
 function createSpinner(text) {
@@ -959,6 +1058,7 @@ async function checkForUpdate(name, current) {
     return null;
   }
 }
+var DEFERRED_CONNECTION_ID = "vc_REPLACE_ME_RUN_npm_run_connect";
 async function resolveStoreInfoOrExit(connectionId, candidateApiUrls) {
   const spinner = createSpinner("Fetching store info...");
   spinner.start();
@@ -989,6 +1089,9 @@ async function resolveStoreInfoOrExit(connectionId, candidateApiUrls) {
 }
 var program = new import_commander.Command();
 program.name("create-brainerce-store").description("Scaffold a production-ready e-commerce storefront connected to Brainerce").version(pkg.version).argument("[project-name]", "Name for the project directory").option("--connection-id <id>", "Brainerce vibe-coded connection ID (vc_*)").option(
+  "--defer-connection",
+  "Scaffold now and connect later. Skips the browser approval and writes a placeholder id; finish with `npm run connect` inside the project."
+).option(
   "--api-url <url>",
   "Brainerce API base URL (overrides BRAINERCE_API_URL env, defaults to https://api.brainerce.com)"
 ).option("--language <lang>", "Store language (en, he)").addOption(new import_commander.Option("--framework <framework>", "Framework to use").default("nextjs").hideHelp()).addOption(new import_commander.Option("--design <design>", "Storefront design pack").hideHelp()).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
@@ -1058,11 +1161,28 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     let storeInfo = null;
     let resolvedApiUrl = candidateApiUrls[0];
     if (connectionId) {
-      const connError2 = validateConnectionId(connectionId);
-      if (connError2) {
-        logger.error(connError2);
+      const connError = validateConnectionId(connectionId);
+      if (connError) {
+        logger.error(connError);
+        process.exit(1);
+      }
+      const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
+      storeInfo = resolved.info;
+      resolvedApiUrl = resolved.apiBaseUrl;
+    } else if (options.deferConnection === true) {
+      connectionId = DEFERRED_CONNECTION_ID;
+      storeInfo = {
+        name: projectName || "My Store",
+        storeName: projectName || "My Store",
+        currency: "USD",
+        language: language || "en"
+      };
+    } else {
+      const approved = await runDeviceFlow(candidateApiUrls[0]);
+      if (!approved) {
         process.exit(1);
       }
+      connectionId = approved.connectionId;
       const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
       storeInfo = resolved.info;
       resolvedApiUrl = resolved.apiBaseUrl;
@@ -1072,6 +1192,16 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     const storeSlug = storeInfo ? slugify(storeInfo.storeName) : "";
     const projectNameSuggestion = channelSlug || storeSlug || void 0;
     language = language || storeInfo?.language;
+    if (!projectName && !process.stdin.isTTY) {
+      if (!projectNameSuggestion) {
+        logger.error(
+          "No project name given, and no terminal to ask on. Pass one: npm create brainerce-store@latest my-store"
+        );
+        process.exit(1);
+      }
+      projectName = projectNameSuggestion;
+      logger.info(`  No project name given. Using "${projectName}", from your store.`);
+    }
     if (!projectName || !connectionId || !language) {
       const answers = await runInteractive({
         projectName,
@@ -1095,12 +1225,14 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       logger.error(nameError);
       process.exit(1);
     }
-    const connError = validateConnectionId(connectionId);
-    if (connError) {
-      logger.error(connError);
-      process.exit(1);
+    if (connectionId !== DEFERRED_CONNECTION_ID) {
+      const connError = validateConnectionId(connectionId);
+      if (connError) {
+        logger.error(connError);
+        process.exit(1);
+      }
     }
-    if (!storeInfo) {
+    if (!storeInfo && connectionId !== DEFERRED_CONNECTION_ID) {
       const resolved = await resolveStoreInfoOrExit(connectionId, candidateApiUrls);
       storeInfo = resolved.info;
       resolvedApiUrl = resolved.apiBaseUrl;
@@ -1196,7 +1328,18 @@ Your store will be running at http://localhost:3000
       if (!scaffoldInPlace) {
         logger.step(`cd ${projectName}`);
       }
+      if (connectionId === DEFERRED_CONNECTION_ID) {
+        logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} connect`);
+      }
       logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} dev`);
+      if (connectionId === DEFERRED_CONNECTION_ID) {
+        logger.info(
+          `
+This store is not connected yet. \`connect\` opens one browser approval,
+writes the sales channel id into .env.local, and creates a store and a
+channel for you if you have neither. Until then the catalog is empty.`
+        );
+      }
       logger.info(`
 Your store will be running at http://localhost:3000`);
       logger.info(

package/messages/en.json

@@ -104,6 +104,8 @@
     "addToCart": "Add to Cart",
     "addingToCart": "Adding...",
     "addedToCart": "Added to Cart!",
+    "cartFull": "Your cart is full. Remove an item before adding this one.",
+    "addToCartFailed": "We could not add this to your cart. Please try again.",
     "outOfStock": "Out of Stock",
     "inStock": "In Stock",
     "unavailable": "Unavailable",
@@ -191,12 +193,17 @@
     "upgrade": "Upgrade",
     "upgrading": "Upgrading...",
     "dismissUpgrade": "Dismiss",
+    "upgradeOriginalNotRemoved": "We added the upgrade to your cart, but we could not remove the original item. Press Upgrade again to remove it.",
     "bundleOffers": "Bundle & Save",
     "addBundleItem": "Add & Save",
     "addingBundle": "Adding...",
     "selectOptions": "Select options",
     "outOfStock": "Out of stock",
-    "unavailableItemsHint": "Remove the items marked out of stock or unavailable to continue to checkout."
+    "unavailableItemsHint": "Remove the items marked out of stock or unavailable to continue to checkout.",
+    "notEnoughStock": "There is not enough stock left for that quantity.",
+    "itemUnavailable": "This item can no longer be bought. Remove it to continue.",
+    "quantityUpdateFailed": "We could not update the quantity. Please try again.",
+    "removeFailed": "We could not remove this item. Please try again."
   },
   "checkout": {
     "pageTitle": "Checkout",

package/messages/he.json

@@ -104,6 +104,8 @@
     "addToCart": "הוסף לעגלה",
     "addingToCart": "מוסיף...",
     "addedToCart": "נוסף לעגלה!",
+    "cartFull": "העגלה מלאה. הסירו מוצר אחד לפני הוספת המוצר הזה.",
+    "addToCartFailed": "לא הצלחנו להוסיף את המוצר לעגלה. נסו שוב.",
     "outOfStock": "אזל מהמלאי",
     "inStock": "במלאי",
     "unavailable": "לא זמין",
@@ -191,12 +193,17 @@
     "upgrade": "שדרג",
     "upgrading": "משדרג...",
     "dismissUpgrade": "סגור",
+    "upgradeOriginalNotRemoved": "הוספנו את השדרוג לעגלה, אבל לא הצלחנו להסיר את המוצר המקורי. לחצו שוב על שדרוג כדי להסיר אותו.",
     "bundleOffers": "חבילה וחיסכון",
     "addBundleItem": "הוסף וחסוך",
     "addingBundle": "מוסיף...",
     "selectOptions": "בחר אפשרויות",
     "outOfStock": "אזל מהמלאי",
-    "unavailableItemsHint": "הסירו את המוצרים שמסומנים כאזלו מהמלאי או כלא זמינים כדי להמשיך לתשלום."
+    "unavailableItemsHint": "הסירו את המוצרים שמסומנים כאזלו מהמלאי או כלא זמינים כדי להמשיך לתשלום.",
+    "notEnoughStock": "אין מספיק מלאי לכמות הזו.",
+    "itemUnavailable": "לא ניתן לרכוש את המוצר הזה יותר. הסירו אותו כדי להמשיך.",
+    "quantityUpdateFailed": "לא הצלחנו לעדכן את הכמות. נסו שוב.",
+    "removeFailed": "לא הצלחנו להסיר את המוצר. נסו שוב."
   },
   "checkout": {
     "pageTitle": "תשלום",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.80.0",
+  "version": "1.81.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "homepage": "https://brainerce.com",
   "repository": {

package/templates/nextjs/base/.eslintrc.json

@@ -17,6 +17,8 @@
                   "!@/core/lib/capabilities",
                   "!@/core/lib/display-price",
                   "!@/core/lib/image-hosts",
+                  "!@/core/lib/kit",
+                  "!@/core/lib/add-to-cart-error",
                   "!@/core/lib/navigation",
                   "!@/core/lib/product-options",
                   "!@/core/lib/sanitize",

package/templates/nextjs/base/AI-GUIDE.md

@@ -59,8 +59,38 @@ UI components get *everything* from `@/core/hooks/*` and
 - `useHomeData()` → `{ products, banners, loading }`
 - `useProductListing()` → products + filters/sort/facets/pagination + handlers
 - `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
-  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, customization
-  + modifier state and errors
+  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
+  customization + modifier state and errors
+  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
+    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
+    distinct products and the 51st add is refused, so a design that drops this
+    leaves the shopper tapping a button that resets and adds nothing. Copy lives
+    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
+  - Five more components hold the same message in their OWN local state, because
+    they add to the cart without this hook: `ui/product/product-card.tsx`,
+    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
+    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
+    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
+    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
+    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
+    calls only, so dropping one of these leaves a green build and a silent button.
+  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
+    in its own `lineError` state: a failed quantity change or a failed Remove
+    used to log to the console and leave the row looking untouched. It uses
+    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
+    cap cannot refuse a quantity change, and "we could not add this" would be a
+    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
+    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
+    The first two are for refusals a retry can never clear, so do not collapse
+    them into the generic one. Nothing checks that you kept any of this either.
+  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
+    another, and the ORDER of its two SDK calls is a correctness property, not a
+    style choice: it **adds the upgrade first and removes the original second**,
+    so a failed add leaves the cart untouched instead of losing the shopper's
+    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
+    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
+    where the add landed and the removal did not. If you rebuild that component,
+    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
 - `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`
 
 Hooks return data and handlers, never JSX. All catalog content (names, prices,

package/templates/nextjs/base/package.json.ejs

@@ -1,52 +1,53 @@
-{
-  "name": "<%= projectName %>",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "setup": "node scripts/fetch-store-info.mjs"
-  },
-  "dependencies": {
-    "brainerce": "<%= brainerceVersion %>",
-    "next": "^15.3.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "@radix-ui/react-accordion": "^1.2.0",
-    "@radix-ui/react-checkbox": "^1.1.1",
-    "@radix-ui/react-dialog": "^1.1.2",
-    "@radix-ui/react-label": "^2.1.0",
-    "@radix-ui/react-radio-group": "^1.2.0",
-    "@radix-ui/react-select": "^2.1.1",
-    "@radix-ui/react-separator": "^1.1.0",
-    "@radix-ui/react-slot": "^1.1.0",
-    "@radix-ui/react-tabs": "^1.1.0",
-    "@radix-ui/react-tooltip": "^1.1.4",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^0.462.0",
-    "tailwind-merge": "^2.5.2",
-    "tailwindcss-animate": "^1.0.7",
-    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
-    "sharp": "^0.35.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "autoprefixer": "^10.4.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "^15.3.4",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": ["sharp"]
-  }
-}
+{
+  "name": "<%= projectName %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "setup": "node scripts/fetch-store-info.mjs",
+    "connect": "node scripts/connect.mjs"
+  },
+  "dependencies": {
+    "brainerce": "<%= brainerceVersion %>",
+    "next": "^15.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@radix-ui/react-accordion": "^1.2.0",
+    "@radix-ui/react-checkbox": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.2",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-select": "^2.1.1",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-tabs": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.462.0",
+    "tailwind-merge": "^2.5.2",
+    "tailwindcss-animate": "^1.0.7",
+    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.3.4",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["sharp"]
+  }
+}

package/templates/nextjs/base/scripts/connect.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+/**
+ * Connect this storefront to a Brainerce sales channel.
+ *
+ * Run it when the build is finished, not before:
+ *
+ *   npm run connect
+ *
+ * WHY THIS IS A SEPARATE STEP. Nothing in a storefront's code depends on WHICH
+ * store it points at — the pages, the routing, the cart, the checkout and every
+ * SDK call are identical either way. Only one environment variable differs. So
+ * a run scaffolded with `--defer-connection` builds the whole storefront
+ * uninterrupted and comes here at the end, instead of stopping for an approval
+ * before a single file exists.
+ *
+ * One click in a browser, and this writes the id into `.env.local`. A store and
+ * a sales channel are created for you if you have neither.
+ *
+ * ⛔ NEVER PROMPTS. This is run by coding agents in shells with no TTY, where a
+ * prompt does not fail — it hangs. Everything is printed and polled.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(/\/$/, '');
+const ENV_PATH = resolve(process.cwd(), '.env.local');
+const KEYS = ['NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID', 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID'];
+
+/** Only ever hand the OS a URL on the host we asked. It arrives in a network
+ *  response, so it is untrusted input on the way to a process launch. */
+function openable(value) {
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') return false;
+    const base = new URL(API_BASE).hostname.replace(/^api(-staging)?\./, '');
+    return url.hostname === base || url.hostname.endsWith(`.${base}`);
+  } catch {
+    return false;
+  }
+}
+
+function openBrowser(url) {
+  const [cmd, args] =
+    process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : process.platform === 'darwin'
+        ? ['open', [url]]
+        : ['xdg-open', [url]];
+  try {
+    // No shell, argument array: the URL cannot become a command.
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Rewrite in place so hand-added variables survive. A blind overwrite here
+ *  would silently drop a payment key someone pasted in an hour earlier. */
+function writeEnv(connectionId) {
+  let body = existsSync(ENV_PATH) ? readFileSync(ENV_PATH, 'utf8') : '';
+  for (const key of KEYS) {
+    const line = `${key}=${connectionId}`;
+    const pattern = new RegExp(`^${key}=.*$`, 'm');
+    body = pattern.test(body) ? body.replace(pattern, line) : `${body.trimEnd()}\n${line}\n`;
+  }
+  writeFileSync(ENV_PATH, body.startsWith('\n') ? body.slice(1) : body);
+}
+
+async function main() {
+  if (process.env.BRAINERCE_CONNECTION_ID) {
+    // Already known (CI, or a channel someone created by hand). Nothing to approve.
+    writeEnv(process.env.BRAINERCE_CONNECTION_ID.trim());
+    console.log('Wrote BRAINERCE_CONNECTION_ID from the environment into .env.local.');
+    return;
+  }
+
+  let start;
+  try {
+    const res = await fetch(`${API_BASE}/api/device-auth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientName: process.env.BRAINERCE_CLIENT_NAME || 'this storefront' }),
+    });
+    if (!res.ok) {
+      console.error(`Could not start the approval (HTTP ${res.status}).`);
+      console.error('Create a sales channel in the dashboard, then set the id in .env.local.');
+      process.exit(1);
+    }
+    start = await res.json();
+  } catch (error) {
+    console.error(`Could not reach Brainerce: ${error?.message ?? error}`);
+    process.exit(1);
+  }
+
+  const opened = openable(start.verificationUriComplete) && openBrowser(start.verificationUriComplete);
+  console.log('');
+  console.log(opened ? 'Opened your browser to approve this connection.' : 'Open this link to approve:');
+  console.log(`  ${start.verificationUriComplete}`);
+  // The code is the only thing a person can actually check: it proves the
+  // request came from this run and not from someone else's.
+  console.log(`  The page should show the code ${start.userCode}. Check that it matches.`);
+  console.log('');
+  console.log('Waiting for approval. A store and a sales channel are created if you have none.');
+
+  const deadline = Date.now() + start.expiresIn * 1000;
+  let interval = (start.interval || 5) * 1000;
+
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, interval));
+    let result;
+    try {
+      const res = await fetch(`${API_BASE}/api/device-auth/poll`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ deviceCode: start.deviceCode }),
+      });
+      result = await res.json();
+    } catch {
+      continue; // A blip mid-poll is not fatal; the deadline is the real bound.
+    }
+    if (result.status === 'approved' && result.connectionId) {
+      writeEnv(result.connectionId);
+      console.log('');
+      console.log('Connected. The sales channel id is in .env.local.');
+      console.log('Start the storefront with: npm run dev');
+      return;
+    }
+    if (result.status === 'denied') {
+      console.error('The connection request was declined. Nothing was created.');
+      process.exit(1);
+    }
+    if (result.status === 'expired') {
+      console.error('The code expired before it was approved. Run this again.');
+      process.exit(1);
+    }
+    // Polled inside the interval: back off rather than hammering.
+    if (result.status === 'slow_down') interval += 1000;
+  }
+
+  console.error('Timed out waiting for approval. Run this again for a fresh code.');
+  process.exit(1);
+}
+
+main();

package/templates/nextjs/base/src/app/checkout/page.tsx

@@ -31,6 +31,7 @@ import { GiftCardInput } from '@/ui/cart/gift-card-input';
 import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
 import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { useTranslations } from '@/core/lib/translations';
+import { toAddToCartError, type AddToCartError } from '@/core/lib/add-to-cart-error';
 import { cn } from '@/core/lib/utils';
 import { isValidCheckoutId } from '@/core/lib/safe-redirect';
 import { trackBeginCheckout } from '@/core/lib/tracking';
@@ -52,6 +53,7 @@ function CheckoutContent() {
   const t = useTranslations('checkout');
   const tc = useTranslations('common');
   const tr = useTranslations('reservation');
+  const tp = useTranslations('productDetail');
 
   const [step, setStep] = useState<CheckoutStep>('address');
   const [checkout, setCheckout] = useState<Checkout | null>(null);
@@ -77,6 +79,7 @@ function CheckoutContent() {
   const [orderBumps, setOrderBumps] = useState<CheckoutBumpsResponse | null>(null);
   const [addedBumpIds, setAddedBumpIds] = useState<Set<string>>(new Set());
   const [bumpLoading, setBumpLoading] = useState<string | null>(null);
+  const [bumpError, setBumpError] = useState<AddToCartError | null>(null);
   const [customFields, setCustomFields] = useState<CheckoutCustomFieldDefinition[]>([]);
   const [customFieldValues, setCustomFieldValues] = useState<Record<string, unknown>>({});
   const [customFieldsLoading, setCustomFieldsLoading] = useState(false);
@@ -354,6 +357,7 @@ function CheckoutContent() {
   // Handle bump toggle
   async function handleBumpToggle(bumpId: string, add: boolean, variantId?: string) {
     if (!cart?.id || bumpLoading) return;
+    setBumpError(null);
     try {
       setBumpLoading(bumpId);
       const client = getClient();
@@ -370,6 +374,10 @@ function CheckoutContent() {
       }
       await refreshCart();
     } catch (err) {
+      // A bump is an extra cart line, so it can be refused by the 50-line cap
+      // like any other add. Logging alone left the checkbox springing back with
+      // no explanation, at the least forgiving point in the flow.
+      setBumpError(toAddToCartError(err));
       console.error('Failed to toggle order bump:', err);
     } finally {
       setBumpLoading(null);
@@ -1044,6 +1052,16 @@ function CheckoutContent() {
                     loading={bumpLoading === bump.id}
                   />
                 ))}
+
+                {/*
+                  Why the bump was refused. Without it the checkbox just springs
+                  back and the shopper is left guessing at checkout.
+                */}
+                {bumpError && (
+                  <p className="text-destructive text-xs" role="alert">
+                    {bumpError === 'CART_FULL' ? tp('cartFull') : tp('addToCartFailed')}
+                  </p>
+                )}
               </div>
             )}