create-cartbase 0.1.13 → 0.1.15

package/README.md

@@ -19,3 +19,7 @@ app at a local or staging platform; without it the app talks to the
 platform. Deploy with the
 [`cartbase`](https://www.npmjs.com/package/cartbase) CLI: `cartbase login`,
 then `cartbase deploy`.
+
+Run it in a folder of its own. Inside an existing project, Next.js takes
+that project's folder as the workspace root; the scaffold notices and
+prints the one line to add to `next.config.ts` if that is what you meant.

package/dist/enclosing-project.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * WHERE THE SCAFFOLD LANDS MATTERS TO NEXT.JS, so the scaffold says so.
+ *
+ * Next infers the workspace root from the lockfiles it finds walking up from
+ * the app (`next/dist/lib/find-root.js`, Next 16.2.4): the highest lockfile
+ * wins, the walk stops at the Git repository that contains the app, and a
+ * lockfile at or above the home directory never counts. A store scaffolded
+ * INSIDE another project therefore gets that project's folder as its root,
+ * and once the store has its own lockfile Next warns on every start that it
+ * "inferred your workspace root". The scaffold cannot know whether the
+ * merchant meant a workspace member or a stray folder, so it names the
+ * situation and both ways out at the moment they can still choose
+ * (store-package card, finding 4).
+ */
+/** The lockfiles Next.js treats as workspace-root markers, its own list. */
+export const ROOT_MARKERS = [
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+];
+/** Is `dir` `of` itself, or one of its ancestors? */
+function isAncestorOrSelf(dir, of) {
+    const rel = path.relative(dir, of);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/** The nearest folder, from `start` upward, that is a Git repository or worktree. */
+function gitBoundary(start) {
+    let current = start;
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".git")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * The project the target folder would sit inside, by Next's own rule, or
+ * null when Next would take the app's own folder as the root. The target
+ * itself need not exist yet: the scaffold asks before it creates it.
+ */
+export function findEnclosingProject(target, options = {}) {
+    const home = options.homeDir === undefined ? os.homedir() : options.homeDir;
+    const parent = path.dirname(path.resolve(target));
+    const boundary = gitBoundary(parent);
+    let current = parent;
+    for (;;) {
+        // Never the home directory or above: Next ignores a marker there.
+        if (home && isAncestorOrSelf(current, home))
+            return null;
+        // Never above the repository that contains the app.
+        if (boundary && current !== boundary && isAncestorOrSelf(current, boundary))
+            return null;
+        for (const marker of ROOT_MARKERS) {
+            if (fs.existsSync(path.join(current, marker)))
+                return { dir: current, marker };
+        }
+        const next = path.dirname(current);
+        if (next === current)
+            return null;
+        current = next;
+    }
+}
+/** What the scaffold prints when the folder sits inside another project. */
+export function enclosingProjectNote(target, found) {
+    const app = path.basename(path.resolve(target));
+    return [
+        `Note: ${app}/ sits inside another project (${found.marker} in ${found.dir}).`,
+        `Next.js takes that folder as the workspace root and, once ${app}/ has its own`,
+        `lockfile, warns on every start that it inferred the root. Either it is a`,
+        `member of that workspace, so name the root in next.config.ts:`,
+        `  turbopack: { root: ${JSON.stringify(found.dir)} }`,
+        `or it is a project of its own, so create it outside that folder, or run`,
+        `git init inside it, which is where Next stops looking.`,
+    ].join("\n");
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { enclosingProjectNote, findEnclosingProject } from "./enclosing-project.js";
 function parseArgs(argv) {
     const flags = new Map();
     let dir;
@@ -82,6 +83,9 @@ Given as a flag it is written into .env.local; otherwise a placeholder is.
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     const key = flag(flags, "key");
     fs.writeFileSync(path.join(target, ".env.local"), envFile({ key, url: flag(flags, "url"), clientId: flag(flags, "client-id") }));
+    // A store scaffolded inside another project inherits that project's
+    // workspace root in Next's eyes; said once, here, while it is cheap to move.
+    const enclosing = findEnclosingProject(target);
     console.log(`
 Created ${path.basename(target)}/
 
@@ -97,6 +101,6 @@ Next steps:
 The complete storefront reference is in docs/ — hand CLAUDE.md (or
 AGENTS.md) to your coding agent and it has everything. Deploy with the
 Cartbase CLI: cartbase login, then cartbase deploy.
-`);
+${enclosing ? `\n${enclosingProjectNote(target, enclosing)}\n` : ""}`);
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -118,10 +118,14 @@ Fetch once at layout level, cache per the docs' cache headers:
 Order inside `<body>` matters (contracts in [components.md](components.md)
 and [consent.md](consent.md)):
 
-1. `<ConsentInit>` FIRST child of body — static and synchronous, never
-   awaits a fetch (first-hit consent race otherwise).
-2. Tracking mounts (`<MetaPixel>`, `<GA4>`, GTM) — gated on the consent
-   state and fed by the integrations tracking block, never by env vars.
+1. `<ConsentInit required={consent.enabled}>` FIRST child of body —
+   synchronous, never awaits a fetch in the browser (first-hit consent race
+   otherwise); the layout resolves the consent config on the server and
+   passes the switch. A store that collects consent starts visitors denied
+   until they choose; a store with the banner off starts them granted.
+2. `<StorefrontTags client={client}>` — every tag the store configured,
+   fed by the integrations tracking block, never by env vars, each gated by
+   the same switch (`tracking.consent_required`).
 3. Navigation from [menus.md](menus.md) — `main-menu` / `footer` handles;
    an unknown handle 404s and must render as "no nav", never crash.
 

package/template/app/docs/collections.md

@@ -1,167 +1,167 @@
-# Collections
-
-Curated product groupings (manual or smart). The membership listing —
-`/collections/:id/products` — is the collection page's data source: it reads
-the membership JOIN (multi-collection products appear in every collection
-they belong to), honors the collection's `default_sort`, and accepts a
-per-request `order` override. Money is EUR decimal major units.
-
-SDK module: `@cartbase/storefront/api/collections`.
-
-**Channel scope (Shopify publish-to-channel semantics):** a collection with
-sales-channel links is visible ONLY on those channels; a collection with no
-links is visible everywhere. Pass your channel as `sales_channel_id` — the
-list excludes scoped-away collections, and the membership listing 404s them.
-
----
-
-## GET /api/store/collections
-
-- **Purpose** — list collections (navigation, collection index pages).
-- **Auth** — anon: `x-client-id` required.
-- **Request**
-
-```jsonc
-// query (all optional)
-{
-  "q": "essen",                 // case-insensitive substring on title
-  "handle": "essentials",       // exact — THE handle lookup (no /:handle route)
-  "sales_channel_id": "sc_…",   // channel scope (see above)
-  "limit": 50,                  // 1–200, default 50
-  "offset": 0
-}
-```
-
-- **Response** — `{ collections, count, offset, limit }`, ordered by title:
-
-```jsonc
-{
-  "collections": [
-    {
-      "id": "pcol_01tst00000000000000000001",
-      "title": "Essentials",
-      "handle": "essentials",
-      "type": "manual",             // "manual" | "smart"
-      "description": null,
-      "image_url": null,
-      "default_sort": "manual",     // used by /products when no order override
-      "conditions": [],             // smart-collection rules (admin-authored)
-      "match": "all",               // smart matching: "all" | "any"
-      "seo_title": null,            // null = fall back to title
-      "seo_description": null,      // null = fall back to description
-      "metadata": null,
-      "created_at": "2026-07-01T00:00:00.000Z",
-      "updated_at": "2026-07-01T00:00:00.000Z"
-    }
-  ],
-  "count": 1, "offset": 0, "limit": 50
-}
-```
-
-- **Working curl** — the seeded catalog carries the `essentials` collection:
-
-```bash
-COLLECTIONS=$(curl -sf "$BASE/api/store/collections?handle=essentials" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$COLLECTIONS" | grep -q '"collections"'
-echo "$COLLECTIONS" | grep -q '"handle":"essentials"'
-COL_ID=$(echo "$COLLECTIONS" | grep -o '"id":"pcol_[^"]*"' | head -1 | cut -d'"' -f4)
-test -n "$COL_ID"
-```
-
-- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
-- **SDK** — `listCollections(client, query?)`.
-- **Components** — navigation, collection index grid.
-- **Settings** — collection channel links; smart-collection conditions
-  (membership recomputes on rule/product change).
-
----
-
-## GET /api/store/collections/:id
-
-- **Purpose** — retrieve one collection (header/SEO block of a collection
-  page). By-handle lookup goes through the list (`?handle=`).
-- **Auth** — anon: `x-client-id` required.
-- **Request** — no query. NOTE (code truth): the single read takes no
-  `sales_channel_id` — channel scope applies to the list and the membership
-  listing, not here.
-- **Response** — `{ "collection": { ...same shape as list rows... } }`
-- **Working curl**
-
-```bash
-COLLECTION=$(curl -sf "$BASE/api/store/collections/$COL_ID" -H "x-client-id: $CLIENT_ID")
-echo "$COLLECTION" | grep -q '"collection"'
-echo "$COLLECTION" | grep -q '"default_sort"'
-```
-
-- **Errors** — 404 `not_found`.
-
-```bash
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  "$BASE/api/store/collections/pcol_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
-test "$STATUS" = 404
-```
-
-- **SDK** — `retrieveCollection(client, collectionId)`.
-- **Components** — collection page header.
-- **Settings** — SEO overrides.
-
----
-
-## GET /api/store/collections/:id/products
-
-- **Purpose** — the collection page's product grid: membership join,
-  published products only, ordered by the collection's `default_sort` with
-  an optional `order` override.
-- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
-- **Request**
-
-```jsonc
-// query (all optional)
-{
-  "order": "price_asc",       // override: manual | title_asc | title_desc |
-                              //   price_asc | price_desc | newest | oldest |
-                              //   best_selling (90-day aggregate).
-                              //   Unknown values are IGNORED (default_sort used).
-  "sales_channel_id": "sc_…", // a collection scoped to OTHER channels 404s
-  "currency_code": "eur",     // pricing context → calculated_price
-  "region_id": "reg_…",
-  "limit": 50,                // 1–100, default 50
-  "offset": 0
-}
-```
-
-- **Response** — `{ products, count, offset, limit }` — products carry the
-  FULL canonical product shape (see products.md), incl. `calculated_price`
-  when a pricing context is given. `count` is the visible membership size.
-- **Working curl** — seeded membership (backfilled from
-  `products.collection_id`) contains the three fixture products:
-
-```bash
-MEMBERS=$(curl -sf "$BASE/api/store/collections/$COL_ID/products?currency_code=eur" \
-  -H "x-client-id: $CLIENT_ID")
-echo "$MEMBERS" | grep -q '"products"'
-echo "$MEMBERS" | grep -q '"handle":"linen-shirt"'
-echo "$MEMBERS" | grep -q '"calculated_price"'
-```
-
-```bash
-# Sort override: price_asc puts the Wool Beanie (EUR 23) before the Linen
-# Shirt (EUR 45) — asserted as RELATIVE order so unrelated rows can't break it.
-curl -sf "$BASE/api/store/collections/$COL_ID/products?order=price_asc" \
-  -H "x-client-id: $CLIENT_ID" | node -e "
-const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
-  const j=JSON.parse(Buffer.concat(c));
-  const h=j.products.map(p=>p.handle);
-  const a=h.indexOf('wool-beanie'), b=h.indexOf('linen-shirt');
-  if(a<0||b<0||a>b){console.error('price_asc order wrong: '+h.join(','));process.exit(1)}
-})"
-```
-
-- **Errors** — 404 `not_found` (unknown collection, or scoped away from the
-  given `sales_channel_id`), 400 `validation_failed`, 400 `invalid_region`.
-- **SDK** — `listCollectionProducts(client, collectionId, query?)`.
-- **Components** — product card grid + sort dropdown (emit the `order`
-  values above).
-- **Settings** — collection `default_sort` + manual position order
-  (drag-reorder in admin); price lists; channel links.
+# Collections
+
+Curated product groupings (manual or smart). The membership listing —
+`/collections/:id/products` — is the collection page's data source: it reads
+the membership JOIN (multi-collection products appear in every collection
+they belong to), honors the collection's `default_sort`, and accepts a
+per-request `order` override. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/collections`.
+
+**Channel scope (Shopify publish-to-channel semantics):** a collection with
+sales-channel links is visible ONLY on those channels; a collection with no
+links is visible everywhere. Pass your channel as `sales_channel_id` — the
+list excludes scoped-away collections, and the membership listing 404s them.
+
+---
+
+## GET /api/store/collections
+
+- **Purpose** — list collections (navigation, collection index pages).
+- **Auth** — anon: `x-client-id` required.
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "q": "essen",                 // case-insensitive substring on title
+  "handle": "essentials",       // exact — THE handle lookup (no /:handle route)
+  "sales_channel_id": "sc_…",   // channel scope (see above)
+  "limit": 50,                  // 1–200, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ collections, count, offset, limit }`, ordered by title:
+
+```jsonc
+{
+  "collections": [
+    {
+      "id": "pcol_01tst00000000000000000001",
+      "title": "Essentials",
+      "handle": "essentials",
+      "type": "manual",             // "manual" | "smart"
+      "description": null,
+      "image_url": null,
+      "default_sort": "manual",     // used by /products when no order override
+      "conditions": [],             // smart-collection rules (admin-authored)
+      "match": "all",               // smart matching: "all" | "any"
+      "seo_title": null,            // null = fall back to title
+      "seo_description": null,      // null = fall back to description
+      "metadata": null,
+      "created_at": "2026-07-01T00:00:00.000Z",
+      "updated_at": "2026-07-01T00:00:00.000Z"
+    }
+  ],
+  "count": 1, "offset": 0, "limit": 50
+}
+```
+
+- **Working curl** — the seeded catalog carries the `essentials` collection:
+
+```bash
+COLLECTIONS=$(curl -sf "$BASE/api/store/collections?handle=essentials" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$COLLECTIONS" | grep -q '"collections"'
+echo "$COLLECTIONS" | grep -q '"handle":"essentials"'
+COL_ID=$(echo "$COLLECTIONS" | grep -o '"id":"pcol_[^"]*"' | head -1 | cut -d'"' -f4)
+test -n "$COL_ID"
+```
+
+- **Errors** — 400 `missing_client_id`, 400 `validation_failed`.
+- **SDK** — `listCollections(client, query?)`.
+- **Components** — navigation, collection index grid.
+- **Settings** — collection channel links; smart-collection conditions
+  (membership recomputes on rule/product change).
+
+---
+
+## GET /api/store/collections/:id
+
+- **Purpose** — retrieve one collection (header/SEO block of a collection
+  page). By-handle lookup goes through the list (`?handle=`).
+- **Auth** — anon: `x-client-id` required.
+- **Request** — no query. NOTE (code truth): the single read takes no
+  `sales_channel_id` — channel scope applies to the list and the membership
+  listing, not here.
+- **Response** — `{ "collection": { ...same shape as list rows... } }`
+- **Working curl**
+
+```bash
+COLLECTION=$(curl -sf "$BASE/api/store/collections/$COL_ID" -H "x-client-id: $CLIENT_ID")
+echo "$COLLECTION" | grep -q '"collection"'
+echo "$COLLECTION" | grep -q '"default_sort"'
+```
+
+- **Errors** — 404 `not_found`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/collections/pcol_doesnotexist$RUN" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 404
+```
+
+- **SDK** — `retrieveCollection(client, collectionId)`.
+- **Components** — collection page header.
+- **Settings** — SEO overrides.
+
+---
+
+## GET /api/store/collections/:id/products
+
+- **Purpose** — the collection page's product grid: membership join,
+  published products only, ordered by the collection's `default_sort` with
+  an optional `order` override.
+- **Auth** — anon: `x-client-id`; optional Bearer JWT (group pricing).
+- **Request**
+
+```jsonc
+// query (all optional)
+{
+  "order": "price_asc",       // override: manual | title_asc | title_desc |
+                              //   price_asc | price_desc | newest | oldest |
+                              //   best_selling (90-day aggregate).
+                              //   Unknown values are IGNORED (default_sort used).
+  "sales_channel_id": "sc_…", // a collection scoped to OTHER channels 404s
+  "currency_code": "eur",     // pricing context → calculated_price
+  "region_id": "reg_…",
+  "limit": 50,                // 1–100, default 50
+  "offset": 0
+}
+```
+
+- **Response** — `{ products, count, offset, limit }` — products carry the
+  FULL canonical product shape (see products.md), incl. `calculated_price`
+  when a pricing context is given. `count` is the visible membership size.
+- **Working curl** — the seeded membership contains the three fixture
+  products:
+
+```bash
+MEMBERS=$(curl -sf "$BASE/api/store/collections/$COL_ID/products?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$MEMBERS" | grep -q '"products"'
+echo "$MEMBERS" | grep -q '"handle":"linen-shirt"'
+echo "$MEMBERS" | grep -q '"calculated_price"'
+```
+
+```bash
+# Sort override: price_asc puts the Wool Beanie (EUR 23) before the Linen
+# Shirt (EUR 45) — asserted as RELATIVE order so unrelated rows can't break it.
+curl -sf "$BASE/api/store/collections/$COL_ID/products?order=price_asc" \
+  -H "x-client-id: $CLIENT_ID" | node -e "
+const c=[];process.stdin.on('data',d=>c.push(d)).on('end',()=>{
+  const j=JSON.parse(Buffer.concat(c));
+  const h=j.products.map(p=>p.handle);
+  const a=h.indexOf('wool-beanie'), b=h.indexOf('linen-shirt');
+  if(a<0||b<0||a>b){console.error('price_asc order wrong: '+h.join(','));process.exit(1)}
+})"
+```
+
+- **Errors** — 404 `not_found` (unknown collection, or scoped away from the
+  given `sales_channel_id`), 400 `validation_failed`, 400 `invalid_region`.
+- **SDK** — `listCollectionProducts(client, collectionId, query?)`.
+- **Components** — product card grid + sort dropdown (emit the `order`
+  values above).
+- **Settings** — collection `default_sort` + manual position order
+  (drag-reorder in admin); price lists; channel links.