create-brainerce-store 1.84.0 → 1.85.0

package/README.md

@@ -1,92 +1,130 @@
-# create-brainerce-store
-
-Scaffold a production-ready e-commerce storefront connected to [Brainerce](https://brainerce.com) — cart, checkout, variants, coupons, auth, SEO, and i18n wired out of the box.
-
-```bash
-npm create brainerce-store@latest my-store -- --connection-id vc_xxxxxxxx
-# or
-pnpm create brainerce-store my-store --connection-id vc_xxxxxxxx
-```
-
-Run it with no flags for a fully interactive setup. The CLI fetches your store's name, currency, language, and locales from the connection ID (`vc_*`, from your Brainerce dashboard), so the generated store matches the real channel from the first `dev` run.
-
-## The design
-
-Every scaffold ships **Atelier** — a complete, AI-built storefront look (not just a color theme): warm editorial gallery with soft washes + glass surfaces, a floating hero collage, near-full-bleed product grid, styled popover dropdowns, a mini-cart drawer that opens on add-to-cart, and an RTL-safe fly-to-cart micro-interaction. Fully de-branded — driven by your store's name, catalog and dashboard content.
-
-It's a starting point, not a lock-in: the entire look lives in `src/ui/` + `globals.css` and is designed to be rewritten (see below). The shipped texts are **example content** (a boutique voice, like any template's sample copy) — your catalog replaces the imagery automatically, and the copy lives in `messages/` ready to be rewritten by you or an AI session. On a brand-new store with no products yet, the homepage hero shows a designed placeholder that swaps for your first published products.
-
-## Blank-canvas mode
-
-```bash
-npm create brainerce-store@latest my-store -- --connection-id vc_xxx --canvas
-```
-
-`--canvas` ships `src/ui/` as bare, semantic, essentially-unstyled skeletons (`DESIGN ME` markers included) with zero aesthetic opinion — commerce stays fully wired. It's the starting point for designing a storefront from scratch with an AI session, and the authoring substrate for new gallery designs. Canvas mode skips the design pack entirely.
-
-## AI-first by default
-
-Every scaffolded store is ready to be redesigned by an AI coding session:
-
-- **`CLAUDE.md`** — auto-loaded by Claude Code; teaches the session the one rule (`core/` is the platform's, `ui/` is yours) before it touches anything.
-- **`AGENTS.md`** — the same context for other agentic tools.
-- **`/design <your art-direction brief>`** — a ready-made slash command that walks the full redesign: concept → implementation in `ui/` → verification (tsc, real browser, screenshots, RTL checks).
-- **`AI-GUIDE.md`** — the design contract: file map, per-page hook contracts, verification loop, and hard-won RTL/i18n gotchas from real agency builds.
-
-## Architecture (core/ui)
-
-- `src/core/` — platform-owned commerce: client, auth, providers, and data/behavior hooks that return state + handlers, never JSX. Don't modify.
-- `src/ui/` — 100% replaceable presentation. Delete-and-rebuild is encouraged; the store keeps working.
-- `src/app/` — thin routes composing the two (~10 lines each).
-- An ESLint boundary rule enforces the split in both directions.
-
-Full details: [TEMPLATE-ARCHITECTURE.md](./TEMPLATE-ARCHITECTURE.md).
-
-## Flags
-
-| Flag                   | Description                                            | Default            |
-| ---------------------- | ------------------------------------------------------ | ------------------ |
-| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`)            | prompted           |
-| `--canvas`             | Bare unstyled `src/ui/` skeletons for AI-driven design | off                |
-| `--language <lang>`    | Store language (`en`, `he`)                            | fetched from store |
-| `--pkg-manager <pm>`   | `npm`, `pnpm`, `yarn`, `bun`                           | auto-detected      |
-| `--framework <fw>`     | `nextjs` (Vite/Remix coming)                           | `nextjs`           |
-| `--api-url <url>`      | Brainerce API base URL (or `BRAINERCE_API_URL` env)    | auto-discovered    |
-| `--no-git`             | Skip git initialization                                | git on             |
-| `--no-install`         | Skip dependency installation                           | install on         |
-
-Pass `.` as the project name to scaffold into the current directory.
-
-## Reading the connection
-
-Before scaffolding, the CLI reads the channel from `/api/vc/<id>/info` so the
-generated project gets the real store name, currency and language rather than
-guesses. It walks production first, then staging, and stops at the first
-environment that answers. When it has to fall back, it says so and names the
-URL the project will be wired to.
-
-That endpoint checks the request's `Origin` against the channel's **Domain**
-and **Allowed Origins**, and the match counts the **port**. A Test channel with
-an empty Domain box accepts anything; one with `localhost:3000` recorded will
-refuse a bare `http://localhost`. The CLI therefore presents
-`http://localhost:3000` first and plain `http://localhost` second, and reports
-what every environment said rather than only the last one. A `403` from
-production must never surface as "not found on staging".
-
-A channel it cannot read is a hard stop, not a warning. Build-time
-`NEXT_PUBLIC_*` values are inlined into the client bundle and cannot be
-corrected at deploy time, so guessing `USD` / `en` here would ship a storefront
-quoting the wrong currency.
-
-## Requirements
-
-Node `^20.19.0 || ^22.13.0 || >=24.0.0`.
-
-## After scaffolding
-
-```bash
-cd my-store
-pnpm dev          # store at http://localhost:3000
-```
-
-Want a unique look? Open the folder in Claude Code and run `/design <your art-direction brief>`.
+# create-brainerce-store
+
+Scaffold a production-ready e-commerce storefront connected to [Brainerce](https://brainerce.com) — cart, checkout, variants, coupons, auth, SEO, and i18n wired out of the box.
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxxxxxxx
+# or
+pnpm create brainerce-store my-store --connection-id vc_xxxxxxxx
+```
+
+Run it with no flags for a fully interactive setup. The CLI fetches your store's name, currency, language, and locales from the connection ID (`vc_*`, from your Brainerce dashboard), so the generated store matches the real channel from the first `dev` run.
+
+## The design
+
+Every scaffold ships **Atelier** — a complete, AI-built storefront look (not just a color theme): warm editorial gallery with soft washes + glass surfaces, a floating hero collage, near-full-bleed product grid, styled popover dropdowns, a mini-cart drawer that opens on add-to-cart, and an RTL-safe fly-to-cart micro-interaction. Fully de-branded — driven by your store's name, catalog and dashboard content.
+
+It's a starting point, not a lock-in: the entire look lives in `src/ui/` + `globals.css` and is designed to be rewritten (see below). The shipped texts are **vertical-neutral placeholder content** (like any template's sample copy: they name no product category) — your catalog replaces the imagery automatically, and the copy (hero, story, footer tagline) lives in `messages/` ready to be rewritten in your own voice by you or an AI session. On a brand-new store with no products yet, the homepage hero shows a designed placeholder that swaps for your first published products.
+
+## Blank-canvas mode
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxx --canvas
+```
+
+`--canvas` ships `src/ui/` as bare, semantic, essentially-unstyled skeletons (`DESIGN ME` markers included) with zero aesthetic opinion — commerce stays fully wired. It's the starting point for designing a storefront from scratch with an AI session, and the authoring substrate for new gallery designs. Canvas mode skips the design pack entirely.
+
+## AI-first by default
+
+Every scaffolded store is ready to be redesigned by an AI coding session:
+
+- **`CLAUDE.md`** — auto-loaded by Claude Code; teaches the session the one rule (`core/` is the platform's, `ui/` is yours) before it touches anything.
+- **`AGENTS.md`** — the same context for other agentic tools.
+- **`/design <your art-direction brief>`** — a ready-made slash command that walks the full redesign: concept → implementation in `ui/` → verification (tsc, real browser, screenshots, RTL checks).
+- **`AI-GUIDE.md`** — the design contract: file map, per-page hook contracts, verification loop, and hard-won RTL/i18n gotchas from real agency builds.
+
+## Architecture (core/ui)
+
+- `src/core/` — platform-owned commerce: client, auth, providers, and data/behavior hooks that return state + handlers, never JSX. Don't modify.
+- `src/ui/` — 100% replaceable presentation. Delete-and-rebuild is encouraged; the store keeps working.
+- `src/app/` — thin routes composing the two (~10 lines each).
+- An ESLint boundary rule enforces the split in both directions.
+
+Full details: [TEMPLATE-ARCHITECTURE.md](./TEMPLATE-ARCHITECTURE.md).
+
+## Flags
+
+| Flag                   | Description                                            | Default            |
+| ---------------------- | ------------------------------------------------------ | ------------------ |
+| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`)            | prompted           |
+| `--defer-connection`   | Scaffold now, connect later with `npm run connect`     | off                |
+| `--canvas`             | Bare unstyled `src/ui/` skeletons for AI-driven design | off                |
+| `--language <lang>`    | Store language (`en`, `he`). **One-way** — see below   | fetched from store |
+| `--pkg-manager <pm>`   | `npm`, `pnpm`, `yarn`, `bun`                           | auto-detected      |
+| `--framework <fw>`     | `nextjs` (Vite/Remix coming)                           | `nextjs`           |
+| `--api-url <url>`      | Brainerce API base URL (or `BRAINERCE_API_URL` env)    | auto-discovered    |
+| `--no-git`             | Skip git initialization                                | git on             |
+| `--no-install`         | Skip dependency installation                           | install on         |
+
+Pass `.` as the project name to scaffold into the current directory.
+
+`--language` is the one decision that cannot be changed after scaffolding: it
+picks which `messages/` ship and the `<html lang>` / `dir` of every page.
+`npm run connect` and `npm run setup` refresh the store name and currency from
+the live channel, never the language — a store in the wrong language is
+re-scaffolded, not adjusted. Pass it explicitly when you know it (for example
+`--language he` for a Hebrew merchant); without a channel to read, a deferred
+scaffold assumes `en`.
+
+## Building first, connecting later
+
+```bash
+npm create brainerce-store@latest my-store -- --defer-connection --language he
+cd my-store
+npm run connect      # one browser approval; creates a store + channel if needed
+npm run build        # NEXT_PUBLIC_* values are baked at build time
+```
+
+`--defer-connection` writes a placeholder channel id and skips the approval,
+so an AI builder can construct the whole storefront without stopping. The
+scaffold then knows no store: the name it bakes is the project directory name
+and the currency is `USD`. `npm run connect` writes the real channel id and
+runs `npm run setup`, which fetches the real name and currency into
+`.env.local`. At runtime the storefront prefers the live store name and
+currency from the API (server components, `<title>`, JSON-LD, the Open Graph
+card) and falls back to those `.env.local` values, then to the scaffold
+literal, so a connected store is branded correctly on the first request
+without a rebuild. The `NEXT_PUBLIC_*` fallbacks the client bundle carries are
+inlined at build time, though, so **rebuild before deploying and restart a
+running dev server** after connecting — `connect` says so when it finishes.
+
+`npm run connect -- --seed-products '[{"name":"Burr Grinder","basePrice":389}]'`
+seeds a starter catalog in the same approval and reports, per product, whether
+it was created and whether it is published to this channel; a product that
+exists but is not published is named so you can publish it from the dashboard
+rather than add it twice. On PowerShell put the JSON in
+`BRAINERCE_SEED_PRODUCTS` instead of the flag.
+
+## Reading the connection
+
+Before scaffolding, the CLI reads the channel from `/api/vc/<id>/info` so the
+generated project gets the real store name, currency and language rather than
+guesses. It walks production first, then staging, and stops at the first
+environment that answers. When it has to fall back, it says so and names the
+URL the project will be wired to.
+
+That endpoint checks the request's `Origin` against the channel's **Domain**
+and **Allowed Origins**, and the match counts the **port**. A Test channel with
+an empty Domain box accepts anything; one with `localhost:3000` recorded will
+refuse a bare `http://localhost`. The CLI therefore presents
+`http://localhost:3000` first and plain `http://localhost` second, and reports
+what every environment said rather than only the last one. A `403` from
+production must never surface as "not found on staging".
+
+A channel it cannot read is a hard stop, not a warning. Build-time
+`NEXT_PUBLIC_*` values are inlined into the client bundle and cannot be
+corrected at deploy time, so guessing `USD` / `en` here would ship a storefront
+quoting the wrong currency.
+
+## Requirements
+
+Node `^20.19.0 || ^22.13.0 || >=24.0.0`.
+
+## After scaffolding
+
+```bash
+cd my-store
+pnpm dev          # store at http://localhost:3000
+```
+
+Want a unique look? Open the folder in Claude Code and run `/design <your art-direction brief>`.

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.84.0",
+      version: "1.85.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -629,8 +629,10 @@ function toJsStringLiteral(value) {
   return JSON.stringify(value);
 }
 function toEnvLiteral(value) {
-  const clean = stripControlChars(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "\\$");
-  return `"${clean}"`;
+  const clean = stripControlChars(value).replace(/\$/g, "\\$");
+  if (!clean.includes('"') && !/\\[nr]/.test(clean)) return `"${clean}"`;
+  if (!clean.includes("'")) return `'${clean}'`;
+  return `\`${clean.replace(/`/g, "")}\``;
 }
 function isValidLocale(locale) {
   return typeof locale === "string" && /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})?$/.test(locale);
@@ -682,15 +684,19 @@ async function scaffold(options) {
     /** Raw store name for prose contexts (markdown docs) — JS/env contexts
      *  must keep using the escaped storeNameJs / storeNameEnv variants. */
     storeName: cleanStoreName,
+    /** The scaffold-time name as a JS literal. In the base template it lands
+     *  in ONE place, `src/core/lib/store-name.ts.ejs`, as the LAST fallback
+     *  behind live `storeInfo.name` and `NEXT_PUBLIC_STORE_NAME` — under
+     *  `--defer-connection` it is only the project directory name, so
+     *  nothing else may bake it. The atelier `app-overlay/layout.tsx.ejs`
+     *  resolves the name the same way and splices nothing. */
     storeNameJs: toJsStringLiteral(cleanStoreName),
-    /** Pre-escaped for splicing into a JSON string value (no wrapping
-     *  quotes) — used by the `{{storeName}}` token in messages-patch files. */
-    storeNameJsonEscaped: JSON.stringify(cleanStoreName).slice(1, -1),
     titleTemplateJs: toJsStringLiteral(`%s | ${cleanStoreName}`),
     storeNameEnv: toEnvLiteral(cleanStoreName),
     currencyEnv: toEnvLiteral(cleanCurrency),
     apiBaseUrlEnv: toEnvLiteral(cleanApiBaseUrl),
     language: options.language,
+    deferred: options.deferred === true,
     direction,
     fontImport: fontConfig.fontImport,
     fontVariable: fontConfig.fontVariable,
@@ -767,11 +773,7 @@ async function scaffold(options) {
         if (!await import_fs_extra.default.pathExists(patchFile)) continue;
         const targetFile = import_path.default.join(targetMessages, file);
         const base = await import_fs_extra.default.readJson(targetFile);
-        const patchText = (await import_fs_extra.default.readFile(patchFile, "utf-8")).replace(
-          /\{\{storeName\}\}/g,
-          templateVars.storeNameJsonEscaped
-        );
-        const patch = JSON.parse(patchText);
+        const patch = await import_fs_extra.default.readJson(patchFile);
         await import_fs_extra.default.writeJson(targetFile, deepMerge(base, patch), { spaces: 2 });
       }
     }
@@ -1127,10 +1129,25 @@ async function runSeed(apiBaseUrl, deviceCode, products) {
   }
   const created = Array.isArray(body.created) ? body.created : [];
   const failed = Array.isArray(body.failed) ? body.failed : [];
-  if (created.length > 0) {
+  const reportsPublish = created.some((p) => typeof p.published === "boolean");
+  const live = reportsPublish ? created.filter((p) => p.published !== false) : created;
+  const unpublished = reportsPublish ? created.filter((p) => p.published === false) : [];
+  if (live.length > 0) {
     logger.success(
-      `  Seeded ${created.length} product(s): ${created.map((p) => p.name).join(", ")}`
+      `  Seeded${reportsPublish ? " and published" : ""} ${live.length} product(s): ${live.map((p) => p.name).join(", ")}`
+    );
+  }
+  for (const p of unpublished) {
+    logger.info(
+      `  Created but NOT published to this sales channel: ${p.name} \u2014 ${p.publishError || "the publish did not land"}`
+    );
+  }
+  if (unpublished.length > 0) {
+    logger.info(
+      `  ${unpublished.length} product(s) exist in the store but will not show on the storefront.`
     );
+    logger.info("  Do NOT re-add them. Publish them from the dashboard: Products > the product >");
+    logger.info("  sales channels > toggle this channel on.");
   }
   for (const f of failed) {
     logger.info(`  Not created: ${f.name} \u2014 ${f.reason}`);
@@ -1475,6 +1492,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       language: language || storeInfo.language,
       i18n: storeInfo.i18n,
       scaffoldInPlace,
+      deferred: connectionId === DEFERRED_CONNECTION_ID,
       canvas,
       design: canvas ? void 0 : design || "atelier"
     });
@@ -1560,7 +1578,10 @@ 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.
+channel for you if you have neither. It then fetches the store's real name
+and currency into .env.local \u2014 until it runs, the storefront calls itself
+"${projectName}". Those values are baked in at build time, so build (or
+restart \`dev\`) AFTER connecting.
 
 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
@@ -1576,9 +1597,10 @@ instead.) Without it the store starts empty and products come from the dashboard
 Your store will be running at http://localhost:3000`);
       logger.info(
         `
-The storefront ships with example boutique copy as a starting point \u2014
-your real products replace the imagery automatically, and the texts
-live in messages/ (or let an AI session rewrite them).`
+The storefront ships with vertical-neutral placeholder copy (hero, story,
+footer tagline) \u2014 a starting point, not the merchant's voice. Your real
+products replace the imagery automatically; the texts live in messages/
+and should be rewritten in the store's own words (or let an AI session do it).`
       );
       logger.info(
         `

package/messages/en.json

@@ -247,6 +247,8 @@
     "payment": "Payment",
     "securePayment": "Secure payment",
     "preparingPayment": "Preparing payment...",
+    "paymentModalClosed": "The payment page was closed. Open it again when you are ready, or go back a step.",
+    "openPaymentModal": "Continue to payment",
     "loadingPaymentOptions": "Loading payment options...",
     "paymentNotConfigured": "Payment Not Configured",
     "paymentNotConfiguredDesc": "Payment has not been set up for this store yet. Please contact the store owner.",
@@ -371,6 +373,7 @@
     "lastNamePlaceholder": "Doe",
     "atLeastChars": "At least 8 characters",
     "orContinueWith": "or continue with",
+    "socialLoginUnavailable": "Sign-in with {provider} is not available right now. Please use your email and password.",
     "tooShort": "Too short",
     "weak": "Weak",
     "fair": "Fair",

package/messages/he.json

@@ -247,6 +247,8 @@
     "payment": "תשלום",
     "securePayment": "תשלום מאובטח",
     "preparingPayment": "מכין תשלום...",
+    "paymentModalClosed": "דף התשלום נסגר. כשתהיו מוכנים, פתחו אותו שוב או חזרו לשלב הקודם.",
+    "openPaymentModal": "המשך לתשלום",
     "loadingPaymentOptions": "טוען אפשרויות תשלום...",
     "paymentNotConfigured": "תשלום לא מוגדר",
     "paymentNotConfiguredDesc": "התשלום עדיין לא הוגדר לחנות זו. אנא פנו לבעל החנות.",
@@ -371,6 +373,7 @@
     "lastNamePlaceholder": "ישראלי",
     "atLeastChars": "לפחות 8 תווים",
     "orContinueWith": "או המשיכו עם",
+    "socialLoginUnavailable": "ההתחברות דרך {provider} אינה זמינה כרגע. אפשר להתחבר עם אימייל וסיסמה.",
     "tooShort": "קצרה מדי",
     "weak": "חלשה",
     "fair": "סבירה",

package/package.json

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

package/templates/nextjs/base/.env.local.ejs

@@ -4,7 +4,16 @@ NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID=<%= connectionId %>
 # @deprecated will be removed when SDK 2.0 ships.
 NEXT_PUBLIC_BRAINERCE_CONNECTION_ID=<%= connectionId %>
 
-# Store info (pre-fetched during setup to avoid flash on first load)
+# Store name and currency. The storefront prefers the LIVE values from the
+# Brainerce API wherever it can (server components, <title>, JSON-LD, the OG
+# card); these are the fallback the client bundle carries for the moments
+# before that data arrives, and what renders if the API is unreachable.
+# Refresh them with `npm run setup` (`npm run connect` runs it for you).
+#
+# ⛔ NEXT_PUBLIC_* values are inlined at BUILD time. Editing this file changes
+# nothing already built: run `npm run build` before deploying, and restart a
+# running dev server. Values are quoted the way Next.js's env loader reads
+# them; `setup` and `connect` write the same form (see scripts/env-file.mjs).
 NEXT_PUBLIC_STORE_NAME=<%- storeNameEnv %>
 NEXT_PUBLIC_STORE_CURRENCY=<%- currencyEnv %>