create-brainerce-store 1.72.0 → 1.74.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.72.0",
+      version: "1.74.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -235,7 +235,40 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // missing keys. 2.0 also stops forgotPassword sending `resetUrl`, which the
   // API rejects with 400 under forbidNonWhitelisted, so a scaffold on 1.x has
   // a broken password reset in the browser.
-  brainerce: "^2.0.0",
+  // 2.0.1 exports the three review-photo types (`ReviewPhotoUpload`,
+  // `ProductReviewImage`, `ProductReviewImageAdmin`). They were declared but
+  // never exported from 1.63.0 onwards, and the scaffolded review form imports
+  // `ReviewPhotoUpload` by name, so on any earlier 2.x every scaffolded store
+  // failed `tsc` outright. This is why the pin is ^2.0.1 and not ^2.0.0.
+  //
+  // RELEASE ORDER: npm must already carry a version satisfying this range
+  // before the CLI is published, or every scaffold dies at install on an
+  // unsatisfiable range. Publish the SDK first, then the CLI. That is what
+  // happened for 1.73.0 (brainerce 2.0.2 at 06:42:53Z, the CLI 26 seconds
+  // later), so this is a standing rule, not an open problem.
+  //
+  // Note that brainerce 2.0.1 was never published: the SDK went 2.0.0 ->
+  // 2.0.2. Do not "fix" any range here to an exact 2.0.1, which would resolve
+  // to nothing at all.
+  // 2.1.0 adds the gift-card redemption seam the scaffolded checkout now
+  // depends on: `applyGiftCard()` and `removeGiftCard()` on the client, and
+  // `tenders` + `providerAmountDue` on `Checkout`. The checkout page renders
+  // the applied cards and pays out `providerAmountDue` beside the total, and
+  // `gift-card-input.tsx` types its prop as `NonNullable<Checkout['tenders']>`,
+  // so on 2.0.2 every scaffolded store fails `tsc` on a missing method AND a
+  // missing property. That is why the floor moved off ^2.0.1.
+  //
+  // (The prop deliberately derives from `Checkout` rather than importing the
+  // exported `CheckoutTender`: that type is the APPLY response and carries a
+  // third field, `providerAmountDue`, which a checkout read reports once at the
+  // top level instead of per card. Typing the prop as `CheckoutTender[]` does
+  // not compile against `checkout.tenders`.)
+  //
+  // ⛔ 2.1.0 IS NOT PUBLISHED YET (npm latest is 2.0.2). Per the RELEASE ORDER
+  // rule above, publishing this CLI before the SDK makes the range
+  // unsatisfiable and kills every scaffold at install. Publish brainerce
+  // 2.1.0 first, confirm it on the registry, then publish the CLI.
+  brainerce: "^2.1.0",
   "isomorphic-dompurify": "^3.8.0"
 });
 
@@ -976,13 +1009,13 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     const channelSlug = storeInfo ? slugify(storeInfo.name) : "";
     const storeSlug = storeInfo ? slugify(storeInfo.storeName) : "";
     const projectNameSuggestion = channelSlug || storeSlug || void 0;
-    const languageDefault = language || storeInfo?.language;
+    language = language || storeInfo?.language;
     if (!projectName || !connectionId || !language) {
       const answers = await runInteractive({
         projectName,
         projectNameSuggestion,
         connectionId,
-        language: languageDefault,
+        language,
         framework,
         design,
         pkgManager,

package/messages/en.json

@@ -19,6 +19,7 @@
     "pickup": "Pickup",
     "tax": "Tax",
     "taxIncl": "Tax (incl.)",
+    "inclSuffix": "incl.",
     "sale": "Sale",
     "remove": "Remove",
     "removing": "Removing...",
@@ -59,7 +60,9 @@
     "monthSeptember": "September",
     "monthOctober": "October",
     "monthNovember": "November",
-    "monthDecember": "December"
+    "monthDecember": "December",
+    "giftCard": "Gift card",
+    "amountDue": "Amount due"
   },
   "nav": {
     "products": "Products",
@@ -154,6 +157,9 @@
     "submitReview": "Submit review",
     "addPhotos": "Add photos",
     "removePhoto": "Remove photo",
+    "choosePhotos": "Choose photos",
+    "photoFormats": "JPG, PNG, WebP or GIF, up to {mb}MB each.",
+    "photoLimitReached": "That is all {max} photos. Remove one to add another.",
     "photoUploading": "Uploading…",
     "photoTooLarge": "That photo is too large. Please pick a smaller one.",
     "photoUploadFailed": "Could not upload that photo. Please try another.",
@@ -556,10 +562,33 @@
     "discountCode": "Your code: {code}",
     "genericError": "Something went wrong. Please try again."
   },
+  "loyalty": {
+    "title": "Rewards",
+    "pointsFallback": "points",
+    "readyToSpend": "Ready to spend. Points from a recent order become available after they clear.",
+    "earningPaused": "The rewards programme is paused, so orders are not earning right now. Points you already have can still be spent.",
+    "toNextTierPoints": "{amount} {pointsName} to {tier}",
+    "toNextTierSpend": "{amount} more spent to reach {tier}",
+    "rewardsTitle": "Redeem your points",
+    "pointsCost": "{points} {pointsName}",
+    "tierLocked": "Unlocks at a higher tier",
+    "redeem": "Redeem",
+    "redeeming": "Redeeming...",
+    "notEnoughPoints": "Not enough points",
+    "yourCode": "Your code",
+    "applyAtCheckout": "Enter it at checkout to get the discount.",
+    "redeemError": "We could not redeem that. Please try again."
+  },
   "content": {
     "faqTitle": "Frequently Asked Questions",
     "faqEmptyTitle": "FAQ coming soon",
     "faqEmptyBody": "We're still putting together answers to common questions. In the meantime, feel free to reach out.",
     "faqContactCta": "Contact us"
+  },
+  "giftCard": {
+    "placeholder": "Gift card code",
+    "invalidCode": "That gift card code cannot be used on this order.",
+    "removeFailed": "We could not remove that gift card.",
+    "applied": "Gift card applied — {amount}"
   }
 }

package/messages/he.json

@@ -19,6 +19,7 @@
     "pickup": "איסוף",
     "tax": "מע\"מ",
     "taxIncl": "כולל מע\"מ",
+    "inclSuffix": "כלול",
     "sale": "מבצע",
     "remove": "הסרה",
     "removing": "מסיר...",
@@ -59,7 +60,9 @@
     "monthSeptember": "ספטמבר",
     "monthOctober": "אוקטובר",
     "monthNovember": "נובמבר",
-    "monthDecember": "דצמבר"
+    "monthDecember": "דצמבר",
+    "giftCard": "כרטיס מתנה",
+    "amountDue": "לתשלום"
   },
   "nav": {
     "products": "מוצרים",
@@ -154,6 +157,9 @@
     "submitReview": "שליחת ביקורת",
     "addPhotos": "הוספת תמונות",
     "removePhoto": "הסרת תמונה",
+    "choosePhotos": "בחירת תמונות",
+    "photoFormats": "JPG, PNG, WebP או GIF, עד {mb}MB לכל תמונה.",
+    "photoLimitReached": "אלה כל {max} התמונות. הסר אחת כדי להוסיף אחרת.",
     "photoUploading": "מעלה...",
     "photoTooLarge": "התמונה הזו גדולה מדי. בחרו תמונה קטנה יותר.",
     "photoUploadFailed": "לא הצלחנו להעלות את התמונה. נסו תמונה אחרת.",
@@ -556,10 +562,33 @@
     "discountCode": "הקוד שלכם: {code}",
     "genericError": "משהו השתבש. נסו שוב."
   },
+  "loyalty": {
+    "title": "מועדון הטבות",
+    "pointsFallback": "נקודות",
+    "readyToSpend": "זמינות למימוש. נקודות מהזמנה אחרונה יהפכו לזמינות לאחר תקופת המתנה.",
+    "earningPaused": "תוכנית ההטבות מושהית, ולכן הזמנות לא צוברות נקודות כרגע. את הנקודות שכבר צברת ניתן לממש.",
+    "toNextTierPoints": "{amount} {pointsName} עד {tier}",
+    "toNextTierSpend": "עוד {amount} בקניות כדי להגיע ל-{tier}",
+    "rewardsTitle": "מימוש נקודות",
+    "pointsCost": "{points} {pointsName}",
+    "tierLocked": "נפתח בדרגה גבוהה יותר",
+    "redeem": "מימוש",
+    "redeeming": "מממש...",
+    "notEnoughPoints": "אין מספיק נקודות",
+    "yourCode": "הקוד שלך",
+    "applyAtCheckout": "הזינו אותו בצ׳קאאוט כדי לקבל את ההנחה.",
+    "redeemError": "לא הצלחנו לממש. נסו שוב."
+  },
   "content": {
     "faqTitle": "שאלות נפוצות",
     "faqEmptyTitle": "השאלות הנפוצות בדרך",
     "faqEmptyBody": "אנחנו עוד אוספים את התשובות לשאלות הנפוצות. בינתיים, אתם מוזמנים לפנות אלינו.",
     "faqContactCta": "צרו קשר"
+  },
+  "giftCard": {
+    "placeholder": "קוד כרטיס מתנה",
+    "invalidCode": "לא ניתן להשתמש בקוד הזה בהזמנה הזאת.",
+    "removeFailed": "לא הצלחנו להסיר את כרטיס המתנה.",
+    "applied": "כרטיס מתנה — {amount}"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.72.0",
+  "version": "1.74.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/AGENTS.md.ejs

@@ -20,11 +20,16 @@ Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
 
 ## MCP servers
 
-- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
-  A live SDK/docs oracle: current SDK method shapes, type definitions, code
-  examples, and this store's actual capabilities/config. Prefer it over
-  guessing or relying on training data — it reflects what's actually toggled
-  on for `<%- connectionId %>` right now.
+- **`brainerce-docs`** (already connected via `.mcp.json`, no auth needed).
+  Treat it as the build spec, not a lookup desk. `get-required-features` is
+  the functional checklist this store is measured against, and it is longer
+  than what any art-direction brief would make you think to build.
+  `get-critical-rules` and `get-business-flows` carry the sequences that cause
+  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
+  `get-code-example` give current method shapes instead of training-data
+  guesses, and `get-store-capabilities` reports what is actually toggled on
+  for `<%- connectionId %>` right now. Read the checklist before you start,
+  and again before you call the work done.
 - **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
   directly manage this store's *live* data (products, orders, discounts,
   shipping, …) instead of just reading docs. Only add it if the merchant
@@ -35,25 +40,59 @@ Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
   Treat it like handing the agent write access to production commerce data.
 
 **Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
+shipping zones, subscriptions, gift cards, donations, multi-currency, reviews,
 abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
 already has it as a platform capability (dashboard toggle + hook/SDK
 method) that only needs a UI in `src/ui/`, not a feature built from scratch.
 
-Your job here is almost always **design**.
+Your job here is almost always **design**. It is never *only* design: the
+coverage checklist in `get-required-features` applies to a redesign exactly as
+it applies to a build from scratch.
 
 ## The one rule
 
 **`src/core/` is the platform's. `src/ui/` is yours.**
 
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected.
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+The shipped `src/ui/` is a working reference, not a design to preserve: a full
+delete-and-rebuild of the *look* is encouraged and expected, and you can
+rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like. The store keeps working. Never modify `src/core/`, `src/app/api/`, or
 the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+`@/core/hooks/*` and `@/core/providers/store-provider`: hooks return state
 and handlers, never JSX. Never hardcode catalog content.
 
+### Rebuilding the look is free. Dropping a feature is not.
+
+Some files under `src/ui/` are the ONLY place a mandatory checklist entry
+exists in this project. Delete one and the capability leaves the store with
+nothing to notice it by: no type error, no console warning, and no visual hole
+either, because these components auto-hide while the merchant has the feature
+switched off, so a deleted one and an idle one look identical on the page.
+These are the usual casualties of a redesign, because no art-direction brief
+asks for them by name:
+
+```
+product/  back-in-stock-form · customization-fields · modifier-group-selector
+          review-form · reviews-section · frequently-bought-together
+          discount-badge · stock-badge
+cart/     reservation-countdown · coupon-input · cart-upgrade-banner
+          cart-bundle-offer · tax-estimate-line
+home/     discount-banner-strip
+layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
+          language-switcher<% } %> · faq-section · rich-text-block
+```
+
+Restyle them, re-lay them out, rename them, fold them into other components,
+split them in half: all fine. What has to survive a rebuild is the SDK call
+each one makes and the states it handles (loading, empty, failed, and the
+merchant-has-it-off state that renders nothing).
+
+The list is short on purpose and it is NOT the specification. It names the
+files people lose, not every mandatory entry. `get-required-features` is the
+specification, and step 1 of "Verify before declaring done" is what actually
+catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
+deleted: the scaffolder committed the tree before you touched it.
+
 **Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
 contracts, motion language, and hard-won RTL/i18n gotchas that will save you
 real debugging time.
@@ -99,11 +138,19 @@ development and on any host with nothing configured.
 
 ## Verify before declaring done
 
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+1. **Feature coverage, first and always.** Call `get-required-features` on the
+   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
+   every mandatory entry is still reachable in the running store. Do this
+   before the steps below, because if you rebuilt `src/ui/` a feature that
+   lived only in the shipped reference is now gone, and no other check can see
+   it: `tsc` cannot see a missing feature, and the component that used to
+   carry it auto-hid when the merchant had not switched it on, so the page
+   looks right either way.
+2. `pnpm exec tsc --noEmit` → 0 errors
+3. `pnpm dev` → drive the changed flow in a real browser (home → product →
    add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
+4. Screenshot desktop (1440px) and mobile (390px)
+5. RTL stores: check anchoring and arrow directions
 
 ## i18n
 

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

@@ -68,11 +68,20 @@ images, stock) comes from them — **never hardcode products**.
 
 ## Verification loop (before you declare anything done)
 
-1. `pnpm exec tsc --noEmit` → must be 0.
-2. `pnpm dev` → drive the real flow you changed: home → listing → product →
+1. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
+   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
+   every mandatory entry is still reachable. First step, not last: you were
+   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
+   the shipped reference is gone now with nothing to notice it by. `tsc`
+   cannot see a missing feature, and these components render nothing while the
+   merchant has the feature off, so a deleted one and an idle one look the
+   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
+   actual specification.
+2. `pnpm exec tsc --noEmit` → must be 0.
+3. `pnpm dev` → drive the real flow you changed: home → listing → product →
    add to cart → cart → checkout page renders.
-3. Screenshot desktop (1440) AND mobile (390), in the store's language.
-4. If the store is RTL: check nothing is left-anchored that should be
+4. Screenshot desktop (1440) AND mobile (390), in the store's language.
+5. If the store is RTL: check nothing is left-anchored that should be
    right-anchored, and directional arrows point with the reading direction.
 
 ## The quality bar (distilled from Lovable / v0 / Bolt system prompts)
@@ -163,6 +172,10 @@ attention, confirms an action, or rewards exploration. Rules:
 - Remove accessibility attributes (`aria-*`, `role`, `alt`, focus styles).
 - Hardcode catalog content, prices, or currency symbols.
 - Swallow the add-to-cart / checkout error states — restyle them, keep them.
+- Drop a `src/ui/` component that is the only place a mandatory feature
+  exists. Rebuilding the look is free; losing the SDK call inside it is not,
+  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
+  files people usually lose, and `get-required-features` for the real list.
 - Introduce new runtime dependencies without flagging it.
 
 ## Adding things

package/templates/nextjs/base/CLAUDE.md.ejs

@@ -20,11 +20,16 @@ Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
 
 ## MCP servers
 
-- **`brainerce-docs`** — already connected via `.mcp.json`, no auth needed.
-  A live SDK/docs oracle: current SDK method shapes, type definitions, code
-  examples, and this store's actual capabilities/config. Prefer it over
-  guessing or relying on training data — it reflects what's actually toggled
-  on for `<%- connectionId %>` right now.
+- **`brainerce-docs`** (already connected via `.mcp.json`, no auth needed).
+  Treat it as the build spec, not a lookup desk. `get-required-features` is
+  the functional checklist this store is measured against, and it is longer
+  than what any art-direction brief would make you think to build.
+  `get-critical-rules` and `get-business-flows` carry the sequences that cause
+  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
+  `get-code-example` give current method shapes instead of training-data
+  guesses, and `get-store-capabilities` reports what is actually toggled on
+  for `<%- connectionId %>` right now. Read the checklist before you start,
+  and again before you call the work done.
 - **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
   directly manage this store's *live* data (products, orders, discounts,
   shipping, …) instead of just reading docs. Only add it if the merchant
@@ -35,26 +40,60 @@ Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
   Treat it like handing the agent write access to production commerce data.
 
 **Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, multi-currency, reviews,
+shipping zones, subscriptions, gift cards, donations, multi-currency, reviews,
 abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
 already has it as a platform capability (dashboard toggle + hook/SDK
 method) that only needs a UI in `src/ui/`, not a feature built from scratch.
 
-Your job here is almost always **design**.
+Your job here is almost always **design**. It is never *only* design: the
+coverage checklist in `get-required-features` applies to a redesign exactly as
+it applies to a build from scratch.
 
 ## The one rule
 
 **`src/core/` is the platform's. `src/ui/` is yours.**
 
-The shipped `src/ui/` is a working reference, not a design to preserve —
-full delete-and-rebuild of ui files is encouraged and expected. (Stores
-scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
-there is no reference look at all; the design is entirely yours to create.)
-Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
-the checkout/auth/account components. Data and behavior come exclusively from
-`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
-and handlers, never JSX. Never hardcode catalog content.
+The shipped `src/ui/` is a working reference, not a design to preserve: a full
+delete-and-rebuild of the *look* is encouraged and expected, and you can
+rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like. The store keeps working. (Stores scaffolded with `--canvas` ship
+`src/ui/` as bare unstyled skeletons, so there is no reference look at all and
+the design is entirely yours to create.) Never modify `src/core/`,
+`src/app/api/`, or the checkout/auth/account components. Data and behavior come
+exclusively from `@/core/hooks/*` and `@/core/providers/store-provider`: hooks
+return state and handlers, never JSX. Never hardcode catalog content.
+
+### Rebuilding the look is free. Dropping a feature is not.
+
+Some files under `src/ui/` are the ONLY place a mandatory checklist entry
+exists in this project. Delete one and the capability leaves the store with
+nothing to notice it by: no type error, no console warning, and no visual hole
+either, because these components auto-hide while the merchant has the feature
+switched off, so a deleted one and an idle one look identical on the page.
+These are the usual casualties of a redesign, because no art-direction brief
+asks for them by name:
+
+```
+product/  back-in-stock-form · customization-fields · modifier-group-selector
+          review-form · reviews-section · frequently-bought-together
+          discount-badge · stock-badge
+cart/     reservation-countdown · coupon-input · cart-upgrade-banner
+          cart-bundle-offer · tax-estimate-line
+home/     discount-banner-strip
+layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
+          language-switcher<% } %> · faq-section · rich-text-block
+```
+
+Restyle them, re-lay them out, rename them, fold them into other components,
+split them in half: all fine. What has to survive a rebuild is the SDK call
+each one makes and the states it handles (loading, empty, failed, and the
+merchant-has-it-off state that renders nothing).
+
+The list is short on purpose and it is NOT the specification. It names the
+files people lose, not every mandatory entry. `get-required-features` is the
+specification, and step 1 of "Verify before declaring done" is what actually
+catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
+deleted: the scaffolder committed the tree before you touched it.
 
 **Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
 contracts, motion language, and hard-won RTL/i18n gotchas that will save you
@@ -110,11 +149,19 @@ development and on any host with nothing configured.
 
 ## Verify before declaring done
 
-1. `pnpm exec tsc --noEmit` → 0 errors
-2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+1. **Feature coverage, first and always.** Call `get-required-features` on the
+   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
+   every mandatory entry is still reachable in the running store. Do this
+   before the steps below, because if you rebuilt `src/ui/` a feature that
+   lived only in the shipped reference is now gone, and no other check can see
+   it: `tsc` cannot see a missing feature, and the component that used to
+   carry it auto-hid when the merchant had not switched it on, so the page
+   looks right either way.
+2. `pnpm exec tsc --noEmit` → 0 errors
+3. `pnpm dev` → drive the changed flow in a real browser (home → product →
    add to cart → cart)
-3. Screenshot desktop (1440px) and mobile (390px)
-4. RTL stores: check anchoring and arrow directions
+4. Screenshot desktop (1440px) and mobile (390px)
+5. RTL stores: check anchoring and arrow directions
 
 ## i18n