create-brainerce-store 1.81.0 → 1.82.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.81.0",
+      version: "1.82.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -330,6 +330,26 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // both to show the merchant's welcome offer beside the field. On an older
   // SDK a scaffolded store fails type-check at creation, exactly like the KIT
   // floor above — so this floor is load-bearing, not cosmetic.
+  //
+  // ⛔⛔ RAISING THIS FLOOR: the version you pin must already be at least SEVEN
+  // DAYS OLD on npm, and template code must not call an SDK API until the
+  // version carrying it has aged that long.
+  //
+  // `minimumReleaseAge` — a package-age cooldown that refuses any dependency
+  // published within the last week — is now a standard supply-chain defence.
+  // pnpm ships the setting (`minimumReleaseAge: 10080`), and ChatGPT Sites
+  // enforces seven days on publish. Our SDK cadence is close to daily, so a
+  // floor set the day a release lands is a floor that NO cooldown-enforcing
+  // environment can install. Measured 2026-09-10: of every 2.x release, only
+  // 2.0.2 was over seven days old, and it predates `getBenefit` — which is why
+  // a Sites publish against this pin is blocked outright with no same-day fix
+  // available on our side, and why lowering the pin would not have helped.
+  // The failure is invisible here: `pnpm install` in this repo is happy, and
+  // the refusal only appears in someone else's environment, at publish time.
+  //
+  // So the ordering is: ship the SDK, wait out the week, THEN adopt its API in
+  // `templates/` and raise this floor in the same change. A feature is not
+  // late for waiting seven days; a template nobody can publish is worse.
   brainerce: "^2.7.0",
   "isomorphic-dompurify": "^3.8.0"
 });
@@ -401,6 +421,106 @@ function detectInvokingPackageManager() {
   return "npm";
 }
 
+// ../cli-shared/src/seed-products.ts
+var SEED_MIN_PRODUCTS = 1;
+var SEED_MAX_PRODUCTS = 20;
+var SEED_MAX_NAME = 191;
+var SEED_MAX_DESCRIPTION = 5e3;
+var SEED_FIELDS = ["name", "basePrice", "description"];
+function parseSeedProducts(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") {
+    return {
+      error: "--seed-products was passed with no value. Give it a JSON array of products, quoted as one shell argument, or drop the flag entirely to connect without seeding."
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      error: `--seed-products is not valid JSON (${error instanceof Error ? error.message : String(error)}). Pass the array as a single quoted argument, or put it in BRAINERCE_SEED_PRODUCTS if your shell keeps breaking the quoting.`
+    };
+  }
+  const list = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.products) ? parsed.products : null;
+  if (!list) {
+    return {
+      error: '--seed-products must be a JSON array of products, or an object with a "products" array. A single product object on its own is not accepted; wrap it in an array.'
+    };
+  }
+  if (list.length < SEED_MIN_PRODUCTS) {
+    return {
+      error: "--seed-products was an empty list. Seeding needs at least one product; if the user has not described what they sell, leave the flag off and build against the empty catalog."
+    };
+  }
+  if (list.length > SEED_MAX_PRODUCTS) {
+    return {
+      error: `--seed-products carries ${list.length} products and the limit is ${SEED_MAX_PRODUCTS}. This is a starter catalog, not an import: pick the ${SEED_MAX_PRODUCTS} that best show the store, and point the merchant at the dashboard or Apps > Browse > Migration Tool for the rest.`
+    };
+  }
+  const products = [];
+  for (let i = 0; i < list.length; i += 1) {
+    const entry = list[i];
+    const at = `--seed-products product ${i + 1}`;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return {
+        error: `${at} is not an object. Each entry looks like {"name":"...","basePrice":0}.`
+      };
+    }
+    const unknown = Object.keys(entry).filter(
+      (k) => !SEED_FIELDS.includes(k)
+    );
+    if (unknown.length > 0) {
+      return {
+        error: `${at} carries ${unknown.map((k) => `"${k}"`).join(", ")}, which the seed route does not accept and will not ignore \u2014 one unknown key rejects the whole request. Only ${SEED_FIELDS.join(
+          ", "
+        )} are allowed: no sku, no type, no options or variants, no categories, no images. Every seeded product lands as a simple, active product.`
+      };
+    }
+    if (typeof entry.name !== "string" || entry.name.trim() === "") {
+      return { error: `${at} has no usable "name". It must be a non-empty string.` };
+    }
+    if (entry.name.length > SEED_MAX_NAME) {
+      return {
+        error: `${at} ("${entry.name.slice(0, 40)}...") has a name of ${entry.name.length} characters and the limit is ${SEED_MAX_NAME}.`
+      };
+    }
+    if (!("basePrice" in entry)) {
+      return {
+        error: `${at} ("${entry.name}") has no "basePrice". Every seeded product needs one, as a number: {"name":"${entry.name}","basePrice":0} is the minimum shape.`
+      };
+    }
+    if (typeof entry.basePrice === "string") {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" quoted as text. Send ${entry.basePrice.trim() === "" ? "149" : entry.basePrice} without the quotes \u2014 the API does not coerce a quoted price, it rejects it.`
+      };
+    }
+    if (typeof entry.basePrice !== "number" || !Number.isFinite(entry.basePrice)) {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" that is not a number. It must be a plain finite number, not null, not a string and not an expression.`
+      };
+    }
+    if (entry.basePrice < 0) {
+      return { error: `${at} ("${entry.name}") has a negative "basePrice".` };
+    }
+    if ("description" in entry) {
+      if (typeof entry.description !== "string") {
+        return {
+          error: `${at} ("${entry.name}") has a "description" that is not a string. Omit the key entirely rather than sending null.`
+        };
+      }
+      if (entry.description.length > SEED_MAX_DESCRIPTION) {
+        return {
+          error: `${at} ("${entry.name}") has a description of ${entry.description.length} characters and the limit is ${SEED_MAX_DESCRIPTION}.`
+        };
+      }
+    }
+    const product = { name: entry.name, basePrice: entry.basePrice };
+    if (typeof entry.description === "string") product.description = entry.description;
+    products.push(product);
+  }
+  return { products };
+}
+
 // src/cli.ts
 async function runInteractive(defaults) {
   const questions = [];
@@ -947,6 +1067,72 @@ function openBrowser(url) {
     return false;
   }
 }
+async function readError(res) {
+  try {
+    const body = await res.json();
+    const message = body?.message;
+    return Array.isArray(message) ? message.join("; ") : message ?? `HTTP ${res.status}`;
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+}
+async function runSeed(apiBaseUrl, deviceCode, products) {
+  let res;
+  try {
+    res = await fetch(`${apiBaseUrl}/api/device-auth/seed`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ deviceCode, products })
+    });
+  } catch (error) {
+    logger.error(
+      `  Could not reach the seeding endpoint (${error instanceof Error ? error.message : String(error)}).
+  The request may or may not have landed, so do not claim either way: check the
+  catalog in the dashboard and add what is missing there.`
+    );
+    return;
+  }
+  if (!res.ok) {
+    const message = await readError(res);
+    if (message.startsWith("That seeding window has closed")) {
+      logger.error(
+        "  The seeding window is closed \u2014 the grant was already spent, or more than ten\n  minutes passed since the approval. The connection itself is fine; add the\n  products in the dashboard."
+      );
+    } else {
+      logger.error(
+        `  The seed request was refused before the grant was touched: ${message}
+  The store is connected and still empty. Report this message as written and
+  add the products in the dashboard rather than retrying.`
+      );
+    }
+    return;
+  }
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    logger.error(
+      "  The seed endpoint answered with something that is not JSON. Products may have\n  been created. Check the catalog in the dashboard rather than assuming either way."
+    );
+    return;
+  }
+  const created = Array.isArray(body.created) ? body.created : [];
+  const failed = Array.isArray(body.failed) ? body.failed : [];
+  if (created.length > 0) {
+    logger.success(
+      `  Seeded ${created.length} product(s): ${created.map((p) => p.name).join(", ")}`
+    );
+  }
+  for (const f of failed) {
+    logger.info(`  Not created: ${f.name} \u2014 ${f.reason}`);
+  }
+  if (failed.length > 0) {
+    logger.info(
+      `  ${created.length} of ${products.length} product(s) went in; ${failed.length} refused.`
+    );
+    logger.info("  The window is now spent, so add the refused ones in the dashboard.");
+  }
+}
 async function runDeviceFlow(apiBaseUrl, options = {}) {
   let start;
   try {
@@ -997,6 +1183,9 @@ async function runDeviceFlow(apiBaseUrl, options = {}) {
     }
     if (result.status === "approved" && result.connectionId) {
       logger.success("  Approved.");
+      if (options.seedProducts?.length) {
+        await runSeed(apiBaseUrl, start.deviceCode, options.seedProducts);
+      }
       return { connectionId: result.connectionId, storeId: result.storeId ?? null };
     }
     if (result.status === "denied") {
@@ -1091,6 +1280,9 @@ 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(
+  "--seed-products <json>",
+  "Starter catalog to create during the browser approval, as a JSON array of {name, basePrice, description?}. Only valid on the run that performs the approval: with --connection-id there is no grant, and with --defer-connection the approval happens later, in `npm run connect --seed-products`."
 ).option(
   "--api-url <url>",
   "Brainerce API base URL (overrides BRAINERCE_API_URL env, defaults to https://api.brainerce.com)"
@@ -1113,6 +1305,28 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       scaffoldInPlace = true;
     }
     let connectionId = options.connectionId;
+    let seedProducts;
+    const seedRaw = options.seedProducts ?? process.env.BRAINERCE_SEED_PRODUCTS;
+    if (seedRaw !== void 0) {
+      if (connectionId) {
+        logger.error(
+          "--seed-products needs a browser approval, and --connection-id skips it: a channel\nyou already have carries no seeding grant. Scaffold without --connection-id to\napprove and seed in one step, or add the products in the dashboard."
+        );
+        process.exit(1);
+      }
+      if (options.deferConnection === true) {
+        logger.error(
+          "--seed-products does not belong on a deferred scaffold: the approval happens later,\ninside the project, and that is where the seeding grant is opened. Scaffold as\nnormal, then finish with:\n  npm run connect -- --seed-products '[...]'"
+        );
+        process.exit(1);
+      }
+      const parsed = parseSeedProducts(seedRaw);
+      if (parsed.error) {
+        logger.error(parsed.error);
+        process.exit(1);
+      }
+      seedProducts = parsed.products;
+    }
     const explicitApiUrl = (options.apiUrl || process.env.BRAINERCE_API_URL || "").replace(/\/$/, "");
     const apiUrlError = validateApiUrl(explicitApiUrl);
     if (apiUrlError) {
@@ -1178,7 +1392,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         language: language || "en"
       };
     } else {
-      const approved = await runDeviceFlow(candidateApiUrls[0]);
+      const approved = await runDeviceFlow(candidateApiUrls[0], { seedProducts });
       if (!approved) {
         process.exit(1);
       }
@@ -1337,7 +1551,16 @@ Your store will be running at http://localhost:3000
           `
 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.`
+channel for you if you have neither.
+
+Know what this store sells? Seed the catalog in that same command \u2014 the
+approval opens a short window that needs no admin key, and it is the only
+moment it is open:
+
+  ${pkgManager}${pkgManager === "npm" ? " run" : ""} connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389}]'
+
+(PowerShell mangles that quoting: put the same JSON in BRAINERCE_SEED_PRODUCTS
+instead.) Without it the store starts empty and products come from the dashboard.`
         );
       }
       logger.info(`

package/messages/en.json

@@ -129,7 +129,7 @@
   },
   "reviews": {
     "title": "Reviews",
-    "noReviews": "No reviews yet — be the first to share your experience.",
+    "noReviews": "No reviews yet. Be the first to share your experience.",
     "verifiedPurchase": "Verified purchase",
     "loading": "Loading…",
     "signIn": "Sign in",
@@ -289,7 +289,7 @@
     "customFieldsApplying": "Updating…",
     "customFieldsFailed": "Failed to save selections",
     "customFieldsRequired": "Required",
-    "customFieldsSelectPlaceholder": "— Select —",
+    "customFieldsSelectPlaceholder": "Select an option",
     "customFieldsImageUpload": "Click to upload an image",
     "customFieldsImageRemove": "Remove",
     "customFieldsImageUploading": "Uploading...",
@@ -322,7 +322,7 @@
     "address": "Address",
     "streetAddress": "Street address",
     "searchingAddress": "Searching…",
-    "outsideDeliveryZone": "This address is outside our regular delivery zones. You can still continue — we'll confirm delivery by phone.",
+    "outsideDeliveryZone": "This address is outside our regular delivery zones. You can still continue, and we'll confirm delivery by phone.",
     "apartmentSuite": "Apartment, suite, etc.",
     "aptPlaceholder": "Apt, suite, unit, etc. (optional)",
     "city": "City",
@@ -574,7 +574,7 @@
     "placeholder": "your@email.com",
     "submit": "Subscribe",
     "submitting": "Sending...",
-    "checkEmailTitle": "Almost there — check your email",
+    "checkEmailTitle": "Almost there. Check your email",
     "checkEmailBody": "We've sent you a link to confirm. Look in your spam folder too; you won't get another copy for 24 hours.",
     "offerPercent": "{value}% off your first order",
     "offerAmount": "{value} off your first order",
@@ -618,6 +618,6 @@
     "locked": "Payment has already started, so this order can no longer take a gift card.",
     "lockedHint": "A gift card is added before the payment step.",
     "removeFailed": "We could not remove that gift card.",
-    "applied": "Gift card applied — {amount}"
+    "applied": "Gift card applied for {amount}"
   }
 }

package/messages/he.json

@@ -129,7 +129,7 @@
   },
   "reviews": {
     "title": "ביקורות",
-    "noReviews": "אין עדיין ביקורות — היו הראשונים לשתף.",
+    "noReviews": "אין עדיין ביקורות. היו הראשונים לשתף.",
     "verifiedPurchase": "רכישה מאומתת",
     "loading": "טוען…",
     "signIn": "התחברו",
@@ -289,7 +289,7 @@
     "customFieldsApplying": "מעדכן…",
     "customFieldsFailed": "שגיאה בשמירת הבחירות",
     "customFieldsRequired": "חובה",
-    "customFieldsSelectPlaceholder": "— בחר —",
+    "customFieldsSelectPlaceholder": "בחר אפשרות",
     "customFieldsImageUpload": "לחץ להעלאת תמונה",
     "customFieldsImageRemove": "הסר",
     "customFieldsImageUploading": "...מעלה",
@@ -322,7 +322,7 @@
     "address": "כתובת",
     "streetAddress": "רחוב ומספר",
     "searchingAddress": "מחפש…",
-    "outsideDeliveryZone": "הכתובת הזו מחוץ לאזורי המשלוח הרגילים שלנו. ניתן להמשיך — ניצור איתך קשר טלפוני לתיאום המשלוח.",
+    "outsideDeliveryZone": "הכתובת הזו מחוץ לאזורי המשלוח הרגילים שלנו. ניתן להמשיך, וניצור איתך קשר טלפוני לתיאום המשלוח.",
     "apartmentSuite": "דירה, קומה וכו׳",
     "aptPlaceholder": "דירה, קומה, כניסה (אופציונלי)",
     "city": "עיר",
@@ -574,7 +574,7 @@
     "placeholder": "your@email.com",
     "submit": "הרשמה",
     "submitting": "שולח...",
-    "checkEmailTitle": "כמעט סיימנו — בדקו את המייל",
+    "checkEmailTitle": "כמעט סיימנו. בדקו את המייל",
     "checkEmailBody": "שלחנו לכם קישור לאישור. בדקו גם בתיקיית הספאם; עותק נוסף לא יישלח ב-24 השעות הקרובות.",
     "offerPercent": "{value}% הנחה על ההזמנה הראשונה",
     "offerAmount": "{value} הנחה על ההזמנה הראשונה",
@@ -618,6 +618,6 @@
     "locked": "התשלום כבר התחיל, אז אי אפשר להוסיף כרטיס מתנה להזמנה הזאת.",
     "lockedHint": "כרטיס מתנה מוסיפים לפני שלב התשלום.",
     "removeFailed": "לא הצלחנו להסיר את כרטיס המתנה.",
-    "applied": "כרטיס מתנה — {amount}"
+    "applied": "כרטיס מתנה בסך {amount}"
   }
 }

package/package.json

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

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

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 /**
- * Connect this storefront to a Brainerce sales channel.
+ * Connect this storefront to a Brainerce sales channel, and optionally fill it
+ * with a starter catalog.
  *
  * Run it when the build is finished, not before:
  *
  *   npm run connect
+ *   npm run connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389}]'
  *
  * 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
@@ -13,6 +15,14 @@
  * uninterrupted and comes here at the end, instead of stopping for an approval
  * before a single file exists.
  *
+ * ⛔ WHY SEEDING LIVES HERE TOO. The approval leaves a short single-use grant on
+ * /api/device-auth/seed keyed to the device code, and this script is the only
+ * thing that holds that code. Seeding from here is also strictly better than
+ * seeding at scaffold time: by now the storefront exists, so the products can
+ * match what was actually built rather than what was guessed before any file
+ * was written. Without this the deferred path could only ever produce an empty
+ * store, and the merchant's first look at their own site is a blank grid.
+ *
  * 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.
  *
@@ -28,6 +38,169 @@ const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').
 const ENV_PATH = resolve(process.cwd(), '.env.local');
 const KEYS = ['NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID', 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID'];
 
+// The seed route's own limits, mirrored here so a bad payload is refused before
+// the grant is touched.
+//
+// ⛔ THIS IS A HAND-KEPT COPY. The canonical one is
+// `packages/cli-shared/src/seed-products.ts`, which the scaffolder itself
+// imports; this file cannot, because it ships standalone into the user's
+// project where that package does not exist. When a limit moves, it moves
+// there first and this follows. All of it mirrors SeedDeviceAuthDto /
+// SeedProductDto in apps/backend/src/modules/device-auth/dto/device-auth.dto.ts,
+// which is what actually enforces them.
+const SEED_MIN_PRODUCTS = 1;
+const SEED_MAX_PRODUCTS = 20;
+const SEED_MAX_NAME = 191;
+const SEED_MAX_DESCRIPTION = 5000;
+const SEED_FIELDS = ['name', 'basePrice', 'description'];
+
+/**
+ * Read `--seed-products <json>` from argv, or `BRAINERCE_SEED_PRODUCTS`.
+ *
+ * The environment variable is not a nicety: `npm run connect -- --seed-products '[...]'`
+ * loses its quoting in PowerShell, which is the default shell for a large share
+ * of the agents that run this, and a JSON array mangled into eight arguments
+ * fails in a way nobody can read. The variable is the escape hatch for those.
+ */
+function readSeedArg(argv) {
+  const flag = argv.indexOf('--seed-products');
+  if (flag !== -1) return argv[flag + 1] ?? '';
+  const inline = argv.find((a) => a.startsWith('--seed-products='));
+  if (inline) return inline.slice('--seed-products='.length);
+  return process.env.BRAINERCE_SEED_PRODUCTS ?? null;
+}
+
+/**
+ * Parse and check the seed payload locally, before anything is sent.
+ *
+ * The seeding grant is single use and dies with the approval window, so a
+ * payload the API would reject must never reach it: there is no second attempt
+ * inside the run, and a second attempt would cost the user a second approval.
+ * Every rule here is one the backend enforces anyway — this only moves the
+ * refusal to a point where it is still free.
+ *
+ * The backend runs `forbidNonWhitelisted`, so ONE stray key (`sku`, `type`,
+ * `images` are the ones agents reach for) rejects the entire request rather
+ * than the row that carried it. That is why unknown keys are an error here and
+ * not something quietly dropped.
+ *
+ * Returns `{ products }` or `{ error }`. Pure: no I/O, no process state.
+ */
+function parseSeedProducts(raw) {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    return {
+      error:
+        '--seed-products was passed with no value. Give it a JSON array of products, quoted as one shell argument, or drop the flag entirely to connect without seeding.',
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return {
+      error: `--seed-products is not valid JSON (${error.message}). Pass the array as a single quoted argument, or put it in BRAINERCE_SEED_PRODUCTS if your shell keeps breaking the quoting.`,
+    };
+  }
+
+  // A bare array is the documented shape. An object with a `products` key is
+  // the body the seed route itself takes, and an agent copying from the route
+  // reference will send that, so accept it rather than refusing a payload that
+  // is right in every way that matters.
+  const list = Array.isArray(parsed)
+    ? parsed
+    : parsed && typeof parsed === 'object' && Array.isArray(parsed.products)
+      ? parsed.products
+      : null;
+
+  if (!list) {
+    return {
+      error:
+        '--seed-products must be a JSON array of products, or an object with a "products" array. A single product object on its own is not accepted; wrap it in an array.',
+    };
+  }
+  if (list.length < SEED_MIN_PRODUCTS) {
+    return {
+      error:
+        '--seed-products was an empty list. Seeding needs at least one product; if the user has not described what they sell, leave the flag off and build against the empty catalog.',
+    };
+  }
+  if (list.length > SEED_MAX_PRODUCTS) {
+    return {
+      error: `--seed-products carries ${list.length} products and the limit is ${SEED_MAX_PRODUCTS}. This is a starter catalog, not an import: pick the ${SEED_MAX_PRODUCTS} that best show the store, and point the merchant at the dashboard or Apps > Browse > Migration Tool for the rest.`,
+    };
+  }
+
+  const products = [];
+
+  for (let i = 0; i < list.length; i += 1) {
+    const entry = list[i];
+    const at = `--seed-products product ${i + 1}`;
+
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      return {
+        error: `${at} is not an object. Each entry looks like {"name":"...","basePrice":0}.`,
+      };
+    }
+
+    const unknown = Object.keys(entry).filter((k) => !SEED_FIELDS.includes(k));
+    if (unknown.length > 0) {
+      return {
+        error: `${at} carries ${unknown.map((k) => `"${k}"`).join(', ')}, which the seed route does not accept and will not ignore — one unknown key rejects the whole request. Only ${SEED_FIELDS.join(', ')} are allowed: no sku, no type, no options or variants, no categories, no images. Every seeded product lands as a simple, active product.`,
+      };
+    }
+
+    if (typeof entry.name !== 'string' || entry.name.trim() === '') {
+      return { error: `${at} has no usable "name". It must be a non-empty string.` };
+    }
+    if (entry.name.length > SEED_MAX_NAME) {
+      return {
+        error: `${at} ("${entry.name.slice(0, 40)}...") has a name of ${entry.name.length} characters and the limit is ${SEED_MAX_NAME}.`,
+      };
+    }
+
+    if (!('basePrice' in entry)) {
+      return {
+        error: `${at} ("${entry.name}") has no "basePrice". Every seeded product needs one, as a number: {"name":"${entry.name}","basePrice":0} is the minimum shape.`,
+      };
+    }
+    if (typeof entry.basePrice === 'string') {
+      // The failure that actually happens: a price quoted as a string. The API
+      // validates with @IsNumber(), which does not coerce, so "149" is refused.
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" quoted as text. Send ${entry.basePrice.trim() === '' ? '149' : entry.basePrice} without the quotes — the API does not coerce a quoted price, it rejects it.`,
+      };
+    }
+    if (typeof entry.basePrice !== 'number' || !Number.isFinite(entry.basePrice)) {
+      return {
+        error: `${at} ("${entry.name}") has a "basePrice" that is not a number. It must be a plain finite number, not null, not a string and not an expression.`,
+      };
+    }
+    if (entry.basePrice < 0) {
+      return { error: `${at} ("${entry.name}") has a negative "basePrice".` };
+    }
+
+    if ('description' in entry) {
+      if (typeof entry.description !== 'string') {
+        return {
+          error: `${at} ("${entry.name}") has a "description" that is not a string. Omit the key entirely rather than sending null.`,
+        };
+      }
+      if (entry.description.length > SEED_MAX_DESCRIPTION) {
+        return {
+          error: `${at} ("${entry.name}") has a description of ${entry.description.length} characters and the limit is ${SEED_MAX_DESCRIPTION}.`,
+        };
+      }
+    }
+
+    const product = { name: entry.name, basePrice: entry.basePrice };
+    if ('description' in entry) product.description = entry.description;
+    products.push(product);
+  }
+
+  return { products };
+}
+
 /** 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) {
@@ -71,11 +244,134 @@ function writeEnv(connectionId) {
   writeFileSync(ENV_PATH, body.startsWith('\n') ? body.slice(1) : body);
 }
 
+async function readError(res) {
+  try {
+    const body = await res.json();
+    const message = body?.message;
+    return Array.isArray(message) ? message.join('; ') : (message ?? `HTTP ${res.status}`);
+  } catch {
+    return `HTTP ${res.status}`;
+  }
+}
+
+/**
+ * Spend the seeding grant.
+ *
+ * ⛔ `deviceCode` is a 256-bit bearer credential and it stops here. It is the
+ * poll credential as well as the seed credential, so anything that put it on
+ * stdout or in a log would hand a reader inside the ten-minute window the
+ * ability to seed this store. It is never printed and never interpolated into
+ * an error string.
+ *
+ * Called once, with no retry. The route allows 5 requests a minute and the
+ * grant is single use, so a retry after an ambiguous failure would report "that
+ * window has closed" over a write that may well have landed.
+ */
+async function runSeed(deviceCode, products) {
+  let res;
+  try {
+    res = await fetch(`${API_BASE}/api/device-auth/seed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ deviceCode, products }),
+    });
+  } catch (error) {
+    console.error('');
+    console.error(`  Could not reach the seeding endpoint (${error.message}).`);
+    console.error(
+      '  The request may or may not have landed, so do not claim either way: check the catalog'
+    );
+    console.error(
+      '  in the dashboard and add what is missing there. Do not run connect again to retry.'
+    );
+    return;
+  }
+
+  if (!res.ok) {
+    const message = await readError(res);
+    // A 400 from the route's own guard means the grant is gone. A 400 from the
+    // validation pipe means the controller never ran and the grant is intact —
+    // different facts, and telling the user the window closed when it has not
+    // is its own kind of wrong.
+    const windowClosed = message.startsWith('That seeding window has closed');
+    console.error('');
+    if (windowClosed) {
+      console.error('  The seeding window is closed — the grant was already spent, or more than');
+      console.error('  ten minutes passed since the approval. The connection itself is fine.');
+      console.error('  Add products in the dashboard; do not run connect again just to seed.');
+    } else {
+      console.error(`  The seed request was refused before the grant was touched: ${message}`);
+      console.error('  The store is connected and still empty. Report this message as written and');
+      console.error('  add the products in the dashboard rather than retrying.');
+    }
+    return;
+  }
+
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    console.error('');
+    console.error('  The seed endpoint answered with something that is not JSON. Products may');
+    console.error('  have been created. Check the catalog in the dashboard rather than assuming');
+    console.error('  either outcome.');
+    return;
+  }
+
+  const created = Array.isArray(body.created) ? body.created : [];
+  const failed = Array.isArray(body.failed) ? body.failed : [];
+
+  // Both halves, always. A per-product failure does not abort the rest, so a
+  // partial write is a normal outcome — and reporting one as a clean win is how
+  // a merchant finds three of five products missing a week later.
+  console.log('');
+  if (created.length > 0) {
+    console.log(`  Seeded ${created.length} product(s): ${created.map((p) => p.name).join(', ')}`);
+  }
+  for (const f of failed) {
+    console.log(`  Not created: ${f.name} — ${f.reason}`);
+  }
+  if (failed.length > 0) {
+    console.log('');
+    console.log(
+      `  ${created.length} of ${products.length} product(s) went in; ${failed.length} refused.`
+    );
+    console.log(
+      '  Report BOTH halves by name. The window is now spent, so the refused ones have to be'
+    );
+    console.log('  added in the dashboard.');
+  } else if (created.length > 0) {
+    console.log('  Anything more comes from the dashboard, or Apps > Browse > Migration Tool.');
+  }
+}
+
 async function main() {
+  const seedRaw = readSeedArg(process.argv.slice(2));
+  let seedProducts = null;
+  if (seedRaw !== null) {
+    const parsed = parseSeedProducts(seedRaw);
+    if (parsed.error) {
+      // Refuse before the approval, not after: a payload rejected on the other
+      // side of a click has already cost the user the click.
+      console.error(parsed.error);
+      process.exit(1);
+    }
+    seedProducts = parsed.products;
+  }
+
   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.');
+    if (seedProducts) {
+      // ⛔ Seeding is authenticated by the device code from an approval. There is
+      // no approval on this path, so there is nothing to seed with — say so
+      // rather than connecting and silently dropping the catalog.
+      console.error('');
+      console.error('  Seeding needs a browser approval and this run already had a connection id,');
+      console.error('  so no products were created. Add them in the dashboard, or in an agent');
+      console.error('  session use the Brainerce MCP server to create products directly.');
+    }
     return;
   }
 
@@ -97,9 +393,12 @@ async function main() {
     process.exit(1);
   }
 
-  const opened = openable(start.verificationUriComplete) && openBrowser(start.verificationUriComplete);
+  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(
+    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.
@@ -124,9 +423,13 @@ async function main() {
       continue; // A blip mid-poll is not fatal; the deadline is the real bound.
     }
     if (result.status === 'approved' && result.connectionId) {
+      // Write the id BEFORE seeding. Seeding is the part that can fail, and a
+      // failed catalog must never cost the connection that already succeeded.
       writeEnv(result.connectionId);
       console.log('');
       console.log('Connected. The sales channel id is in .env.local.');
+      if (seedProducts) await runSeed(start.deviceCode, seedProducts);
+      console.log('');
       console.log('Start the storefront with: npm run dev');
       return;
     }

package/templates/nextjs/base/src/ui/cart/cart-item.tsx

@@ -74,7 +74,8 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
       // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
       // bought at all any more). Both get their own sentence; everything else
       // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
-      // at all, it only ever refuses a brand new line. Keep the log: the
+      // at all, it only ever refuses a brand new line. Both codes are part of
+      // the documented API error catalogue, not guesses. Keep the log: the
       // shopper gets the sentence, the developer still needs the detail.
       const code = getErrorCode(err);
       setLineError(

package/templates/nextjs/designs/atelier/messages-patch/en.json

@@ -9,7 +9,7 @@
   "home": {
     "heroEyebrow": "New collection · Handcrafted",
     "heroTitle": "Pieces that tell your story",
-    "heroLead": "Thoughtfully designed, handcrafted with love — made to be with you through the small moments and the big ones.",
+    "heroLead": "Thoughtfully designed and handcrafted with love, made to be with you through the small moments and the big ones.",
     "heroCtaSecondary": "Browse categories",
     "heroTrust": "Secure checkout on every order",
     "benefit1Title": "Delivery",
@@ -21,10 +21,10 @@
     "benefit4Title": "Returns",
     "benefit4Desc": "See our returns policy for details",
     "featuredEyebrow": "Our picks",
-    "featuredSubtitle": "The pieces our customers love most — hand-picked from the new collection.",
+    "featuredSubtitle": "The pieces our customers love most, hand-picked from the new collection.",
     "categoriesEyebrow": "Categories",
     "categoriesTitle": "Find the perfect piece",
-    "categoriesSubtitle": "From everyday favorites to statement pieces — there's something for everyone.",
+    "categoriesSubtitle": "From everyday favorites to statement pieces, there's something here for everyone.",
     "catRings": "Rings",
     "catNecklaces": "Necklaces",
     "catEarrings": "Earrings",
@@ -52,7 +52,7 @@
     "heroEmptyHint": "Your first published products will appear here"
   },
   "products": {
-    "listingSubtitle": "Our full collection — handmade, genuine materials and love for detail.",
+    "listingSubtitle": "Our full collection, handmade from genuine materials with love for detail.",
     "filtersLabel": "Filter",
     "emptyTitle": "No results found",
     "emptyBody": "Try clearing the filters or searching for something else.",
@@ -84,7 +84,7 @@
     "shippingAtCheckout": "Shipping calculated at checkout"
   },
   "footer": {
-    "tagline": "{{storeName}} — handcrafted with love in Israel.",
+    "tagline": "{{storeName}}, handcrafted with love in Israel.",
     "followUs": "Follow us",
     "quickLinksTitle": "Quick links",
     "linkProducts": "All products",

package/templates/nextjs/designs/atelier/messages-patch/he.json

@@ -9,7 +9,7 @@
   "home": {
     "heroEyebrow": "קולקציה חדשה · עבודת יד",
     "heroTitle": "פריטים שמספרים את הסיפור שלך",
-    "heroLead": "עיצובים עדינים, בעבודת יד ובאהבה — נוצרו ללוות אתכן ברגעים הקטנים והגדולים.",
+    "heroLead": "עיצובים עדינים, בעבודת יד ובאהבה, שנוצרו ללוות אתכן ברגעים הקטנים והגדולים.",
     "heroCtaSecondary": "לצפייה בקטגוריות",
     "heroTrust": "קופה מאובטחת בכל הזמנה",
     "benefit1Title": "משלוח",
@@ -21,10 +21,10 @@
     "benefit4Title": "החזרות",
     "benefit4Desc": "הפרטים במדיניות ההחזרות שלנו",
     "featuredEyebrow": "הנבחרים שלנו",
-    "featuredSubtitle": "הפריטים שהלקוחות שלנו הכי אוהבות — נבחרו בקפידה מהקולקציה החדשה.",
+    "featuredSubtitle": "הפריטים שהלקוחות שלנו הכי אוהבות, שנבחרו בקפידה מהקולקציה החדשה.",
     "categoriesEyebrow": "קטגוריות",
     "categoriesTitle": "מצאו את הפריט המושלם",
-    "categoriesSubtitle": "מהפריטים העדינים ועד הבולטים — לכל אחת יש את השפה שלה.",
+    "categoriesSubtitle": "מהפריטים העדינים ועד הבולטים, לכל אחת יש את השפה שלה.",
     "catRings": "טבעות",
     "catNecklaces": "שרשראות",
     "catEarrings": "עגילים",
@@ -52,7 +52,7 @@
     "heroEmptyHint": "המוצרים הראשונים שתפרסמו לחנות יופיעו כאן"
   },
   "products": {
-    "listingSubtitle": "הקולקציה המלאה שלנו — עבודת יד, חומרים אמיתיים ואהבה לפרטים.",
+    "listingSubtitle": "הקולקציה המלאה שלנו, בעבודת יד, מחומרים אמיתיים ומתוך אהבה לפרטים.",
     "filtersLabel": "סינון",
     "emptyTitle": "לא מצאנו תוצאות",
     "emptyBody": "נסו לנקות את הסינון או לחפש משהו אחר.",
@@ -84,7 +84,7 @@
     "shippingAtCheckout": "משלוח יחושב בקופה"
   },
   "footer": {
-    "tagline": "{{storeName}} — עבודת יד, מעוצב באהבה בישראל.",
+    "tagline": "{{storeName}}, עבודת יד ועיצוב באהבה בישראל.",
     "followUs": "עקבו אחרינו",
     "quickLinksTitle": "ניווט מהיר",
     "linkProducts": "כל המוצרים",

package/templates/nextjs/designs/atelier/ui/cart/cart-item.tsx

@@ -78,7 +78,8 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
       // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
       // bought at all any more). Both get their own sentence; everything else
       // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
-      // at all, it only ever refuses a brand new line. Keep the log: the
+      // at all, it only ever refuses a brand new line. Both codes are part of
+      // the documented API error catalogue, not guesses. Keep the log: the
       // shopper gets the sentence, the developer still needs the detail.
       const code = getErrorCode(err);
       setLineError(

package/templates/nextjs/ui-canvas/cart/cart-item.tsx

@@ -78,7 +78,8 @@ export function CartItem({ item, onUpdate, className }: CartItemProps) {
       // than the inventory left) and PRODUCT_UNAVAILABLE (the line cannot be
       // bought at all any more). Both get their own sentence; everything else
       // is a blip worth one more tap. The 50-line cart cap is NOT a cause here
-      // at all, it only ever refuses a brand new line. Keep the log: the
+      // at all, it only ever refuses a brand new line. Both codes are part of
+      // the documented API error catalogue, not guesses. Keep the log: the
       // shopper gets the sentence, the developer still needs the detail.
       const code = getErrorCode(err);
       setLineError(