create-brainerce-store 1.84.0 → 1.85.0

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

@@ -32,11 +32,16 @@
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setVar } from './env-file.mjs';
 
 const API_BASE = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(/\/$/, '');
 const ENV_PATH = resolve(process.cwd(), '.env.local');
 const KEYS = ['NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID', 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID'];
+/** `setup`, resolved next to THIS file rather than from cwd, so it is found
+ *  however the script was invoked. */
+const FETCH_STORE_INFO = resolve(dirname(fileURLToPath(import.meta.url)), 'fetch-store-info.mjs');
 
 // The seed route's own limits, mirrored here so a bad payload is refused before
 // the grant is touched.
@@ -233,15 +238,68 @@ function openBrowser(url) {
 }
 
 /** Rewrite in place so hand-added variables survive. A blind overwrite here
- *  would silently drop a payment key someone pasted in an hour earlier. */
+ *  would silently drop a payment key someone pasted in an hour earlier.
+ *
+ *  Written through the same `setVar` as `setup`, so every line this project's
+ *  scripts produce has one shape. A `vc_*` id is plain ASCII and would be safe
+ *  bare, but two writers with two formats is how `setup` came to read the
+ *  scaffolder's quotes as part of the URL. */
 function writeEnv(connectionId) {
   let body = existsSync(ENV_PATH) ? readFileSync(ENV_PATH, 'utf8') : '';
-  for (const key of KEYS) {
-    const line = `${key}=${connectionId}`;
-    const pattern = new RegExp(`^${key}=.*$`, 'm');
-    body = pattern.test(body) ? body.replace(pattern, line) : `${body.trimEnd()}\n${line}\n`;
+  for (const key of KEYS) body = setVar(body, key, connectionId);
+  writeFileSync(ENV_PATH, body);
+}
+
+/**
+ * Pull the store's real name and currency into .env.local — the same thing
+ * `npm run setup` does, run as a child so a failure there cannot take this
+ * process (and the connection it just wrote) down with it. The script prints
+ * its own diagnostics; only the outcome is needed here.
+ *
+ * Resolves to true when the values were written. Never throws, never hangs:
+ * the child's one network call carries its own timeout.
+ */
+function refreshStoreInfo() {
+  return new Promise((done) => {
+    let child;
+    try {
+      child = spawn(process.execPath, [FETCH_STORE_INFO], { stdio: 'inherit' });
+    } catch {
+      done(false);
+      return;
+    }
+    child.on('error', () => done(false));
+    child.on('exit', (code) => done(code === 0));
+  });
+}
+
+/**
+ * The part people miss. NEXT_PUBLIC_* values are inlined into the bundle when
+ * `next build` runs, so a build made before this connection carries the
+ * placeholder name and USD for good, whatever .env.local says now. A store
+ * scaffolded with `--defer-connection` shipped as "storefront" — the directory
+ * name, in the title, the Open Graph card and Google's Organization entity —
+ * for exactly this reason. Said unmissably, every time, on both outcomes.
+ */
+function printRebuildNotice(refreshed) {
+  console.log('');
+  if (refreshed) {
+    console.log('  The store name and currency are now in .env.local.');
+  } else {
+    console.error('  ⛔ The store name and currency could NOT be fetched (see above). The connection');
+    console.error('     id itself is written. Until this succeeds the storefront calls itself');
+    console.error('     by its scaffold-time placeholder name. Run this once the API is reachable:');
+    console.error('');
+    console.error('       npm run setup');
   }
-  writeFileSync(ENV_PATH, body.startsWith('\n') ? body.slice(1) : body);
+  console.log('');
+  console.log('  ⛔ REBUILD REQUIRED. NEXT_PUBLIC_* values are baked into the bundle at build');
+  console.log('     time, so anything built before this point still carries the placeholder');
+  console.log('     name and currency. Before deploying run:');
+  console.log('');
+  console.log('       npm run build');
+  console.log('');
+  console.log('     and restart any running `npm run dev` so it re-reads .env.local.');
 }
 
 async function readError(res) {
@@ -321,12 +379,41 @@ async function runSeed(deviceCode, products) {
   const created = Array.isArray(body.created) ? body.created : [];
   const failed = Array.isArray(body.failed) ? body.failed : [];
 
+  // Three outcomes, not two. `created` is every product that EXISTS; since the
+  // seed route started publishing to the channel it also says, per product,
+  // whether that publish landed (`published: boolean`, with `publishError`
+  // when it did not). A product that exists but is not on this channel is
+  // invisible on the storefront and equally invisible in a "Seeded N" line,
+  // which is the same false success the created/failed split already guards
+  // against. Older backends omit `published`; then only the two halves exist.
+  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) : [];
+
   // 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(', ')}`);
+  if (live.length > 0) {
+    console.log(
+      `  Seeded${reportsPublish ? ' and published' : ''} ${live.length} product(s): ${live
+        .map((p) => p.name)
+        .join(', ')}`
+    );
+  }
+  for (const p of unpublished) {
+    console.log(
+      `  Created but NOT published to this sales channel: ${p.name} — ${
+        p.publishError || 'the publish did not land'
+      }`
+    );
+  }
+  if (unpublished.length > 0) {
+    console.log(
+      `  ${unpublished.length} product(s) exist in the store but will not show on the storefront.`
+    );
+    console.log('  Do NOT re-add them. Publish them from the dashboard: Products > the product >');
+    console.log('  sales channels > toggle this channel on.');
   }
   for (const f of failed) {
     console.log(`  Not created: ${f.name} — ${f.reason}`);
@@ -345,6 +432,7 @@ async function runSeed(deviceCode, products) {
   }
 }
 
+/** Returns the process exit code. */
 async function main() {
   const seedRaw = readSeedArg(process.argv.slice(2));
   let seedProducts = null;
@@ -354,7 +442,7 @@ async function main() {
       // 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);
+      return 1;
     }
     seedProducts = parsed.products;
   }
@@ -372,7 +460,8 @@ async function main() {
       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;
+    printRebuildNotice(await refreshStoreInfo());
+    return 0;
   }
 
   let start;
@@ -385,12 +474,12 @@ async function main() {
     if (!res.ok) {
       console.error(`Could not start the approval (HTTP ${res.status}).`);
       console.error('Create a sales channel in the dashboard, then set the id in .env.local.');
-      process.exit(1);
+      return 1;
     }
     start = await res.json();
   } catch (error) {
     console.error(`Could not reach Brainerce: ${error?.message ?? error}`);
-    process.exit(1);
+    return 1;
   }
 
   const opened =
@@ -429,24 +518,32 @@ async function main() {
       console.log('');
       console.log('Connected. The sales channel id is in .env.local.');
       if (seedProducts) await runSeed(start.deviceCode, seedProducts);
+      // The scaffold guessed the name (the directory) and the currency (USD);
+      // this is where the real ones arrive. Runs AFTER seeding so a slow or
+      // failed fetch cannot eat the ten-minute seeding window.
+      console.log('');
+      printRebuildNotice(await refreshStoreInfo());
       console.log('');
       console.log('Start the storefront with: npm run dev');
-      return;
+      return 0;
     }
     if (result.status === 'denied') {
       console.error('The connection request was declined. Nothing was created.');
-      process.exit(1);
+      return 1;
     }
     if (result.status === 'expired') {
       console.error('The code expired before it was approved. Run this again.');
-      process.exit(1);
+      return 1;
     }
     // Polled inside the interval: back off rather than hammering.
     if (result.status === 'slow_down') interval += 1000;
   }
 
   console.error('Timed out waiting for approval. Run this again for a fresh code.');
-  process.exit(1);
+  return 1;
 }
 
-main();
+// `process.exitCode`, never `process.exit()`: on Node 24 / Windows an exit
+// called right after a `fetch` response trips a libuv assertion
+// (`UV_HANDLE_CLOSING`, exit 127) in place of the intended code.
+process.exitCode = await main();

package/templates/nextjs/base/scripts/env-file.mjs

@@ -0,0 +1,93 @@
+/**
+ * Read and write single values in `.env.local` the way Next.js reads them.
+ *
+ * ⛔ `toEnvLiteral` MIRRORS `toEnvLiteral` in the scaffolder
+ * (`packages/create-brainerce-store/src/scaffold.ts`), which writes the
+ * initial `.env.local`, and `parseEnvLiteral` is its exact inverse. The three
+ * must move together: the scaffolder, `npm run setup` and `npm run connect`
+ * all write this file, and Next.js reads it, so they have to agree on what a
+ * value looks like. This used to be broken in both directions — the scaffold
+ * wrote `KEY="value"` and `setup` read the quotes as part of the value
+ * (`"https://api.brainerce.com"/api/vc/...` → "Failed to parse URL"), while
+ * `setup` wrote values bare, so a name with a `#` or a `$` in it was cut off
+ * or expanded.
+ *
+ * What the decoder actually does. Next.js loads `.env.local` through the
+ * dotenv 16 bundled inside `@next/env`, plus dotenv-expand, and that parser
+ * does LESS than people assume (verified against the bundled source and by
+ * loading a probe file through `loadEnvConfig`):
+ *   - one layer of matching quotes (`"…"`, `'…'`, `` `…` ``) is stripped;
+ *   - inside DOUBLE quotes only `\n` and `\r` are unescaped;
+ *   - `\"` and `\\` are NOT unescaped in any form — the backslash stays;
+ *   - dotenv-expand turns `\$` into `$` in every form and expands a bare
+ *     `$VAR`, so `$` is the one character that must always be escaped;
+ *   - an unquoted value ends at the first `#` and is trimmed.
+ */
+
+/** Control chars never belong in a store name and would break the
+ *  KEY=VALUE line structure even inside quotes. */
+function stripControlChars(value) {
+  return String(value).replace(/\p{Cc}/gu, '');
+}
+
+/**
+ * Encode `value` so that Next.js reads back exactly `value`.
+ *
+ * Escape `$`, then pick the quote character the value does not contain:
+ * double quotes by default (refused when the value carries a literal `\n` /
+ * `\r` sequence, which double quotes would turn into a real newline), single
+ * quotes next, backticks last. A value containing all three quote characters
+ * cannot be represented losslessly; its backticks are dropped rather than
+ * failing the whole setup on a store name.
+ */
+export function toEnvLiteral(value) {
+  const clean = stripControlChars(value).replace(/\$/g, '\\$');
+  if (!clean.includes('"') && !/\\[nr]/.test(clean)) return `"${clean}"`;
+  if (!clean.includes("'")) return `'${clean}'`;
+  return `\`${clean.replace(/`/g, '')}\``;
+}
+
+/**
+ * Decode the right-hand side of a `KEY=...` line exactly as `@next/env` does.
+ *
+ * The regex is dotenv's own value group: a quoted form is only accepted when
+ * nothing but whitespace or a `# comment` follows the closing quote, otherwise
+ * the whole thing is an unquoted value that ends at the first `#`. Then the
+ * same post-processing: trim, strip one layer of matching quotes, unescape
+ * `\n` / `\r` for double quotes only, and turn `\$` back into `$`.
+ * `$VAR` expansion itself is not replicated: `toEnvLiteral` escapes every `$`,
+ * so nothing these scripts write ever expands.
+ */
+export function parseEnvLiteral(raw) {
+  const match = String(raw).match(
+    /^(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?$/
+  );
+  let value = ((match && match[1]) || '').trim();
+  const quote = value[0];
+  value = value.replace(/^(['"`])([\s\S]*)\1$/, '$2');
+  if (quote === '"') value = value.replace(/\\n/g, '\n').replace(/\\r/g, '\r');
+  return value.replace(/\\\$/g, '$');
+}
+
+/** The decoded value of `key` in `content`, or `null` when the line is absent. */
+export function getVar(content, key) {
+  const match = content.match(new RegExp(`^${key}=(.*)$`, 'm'));
+  return match ? parseEnvLiteral(match[1]) : null;
+}
+
+/**
+ * Set `key` to `value` in `content`, rewriting the existing line in place so
+ * hand-added variables and comments around it survive, or appending it. The
+ * value is always written through `toEnvLiteral`.
+ */
+export function setVar(content, key, value) {
+  const line = `${key}=${toEnvLiteral(value)}`;
+  const regex = new RegExp(`^${key}=.*$`, 'm');
+  if (regex.test(content)) {
+    // Replacer FUNCTION, not string: a store name containing `$&` or `$1`
+    // would otherwise be interpreted as a replacement pattern.
+    return content.replace(regex, () => line);
+  }
+  const body = content.trimEnd();
+  return body ? `${body}\n${line}\n` : `${line}\n`;
+}

package/templates/nextjs/base/scripts/fetch-store-info.mjs

@@ -1,104 +1,130 @@
 /* eslint-disable no-console */
 /**
- * Setup script: fetches store info from Brainerce using the connection ID
- * and saves NEXT_PUBLIC_STORE_NAME (and other public fields) to .env.local.
+ * Setup script: fetches store info from Brainerce using the sales channel id
+ * and saves NEXT_PUBLIC_STORE_NAME and NEXT_PUBLIC_STORE_CURRENCY to .env.local.
  *
- * Run: node scripts/fetch-store-info.mjs
+ * Run: node scripts/fetch-store-info.mjs   (npm run setup)
+ *
+ * `npm run connect` runs this automatically after writing the channel id, so
+ * a store scaffolded with `--defer-connection` stops calling itself by its
+ * directory name the moment it is connected. Run it again whenever the store
+ * is renamed or changes currency in the dashboard.
+ *
+ * ⛔ NEXT_PUBLIC_* values are inlined into the bundle at BUILD time. Writing
+ * them here changes nothing that is already built: rebuild (`npm run build`)
+ * before deploying, and restart a running dev server. The storefront prefers
+ * the live store name and currency from the API wherever it can (server
+ * components, metadata, JSON-LD); these values are the fallback the client
+ * bundle carries for the moments before that data arrives.
+ *
+ * Values are read and written through ./env-file.mjs, which mirrors the
+ * scaffolder's own encoding — see that file before changing how a line looks.
+ *
+ * Exits through `process.exitCode`, never `process.exit()`: on Node 24 /
+ * Windows an exit called right after a `fetch` response trips a libuv
+ * assertion (`UV_HANDLE_CLOSING`, exit 127) instead of the intended code.
  */
 
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getVar, setVar } from './env-file.mjs';
 
 const envPath = join(process.cwd(), '.env.local');
 
-if (!existsSync(envPath)) {
-  console.error(
-    '❌  .env.local not found. Create it first with NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID set.'
-  );
-  process.exit(1);
-}
+/** Returns the process exit code. */
+async function main() {
+  if (!existsSync(envPath)) {
+    console.error(
+      '❌  .env.local not found. Create it first with NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID set.'
+    );
+    return 1;
+  }
 
-const envContent = readFileSync(envPath, 'utf-8');
+  const envContent = readFileSync(envPath, 'utf-8');
 
-function getVar(content, key) {
-  const match = content.match(new RegExp(`^${key}=(.*)$`, 'm'));
-  return match ? match[1].trim() : null;
-}
+  // Read either env var name. The new one is preferred; the old one is a soft
+  // alias kept for backwards compatibility — the SDK accepts both.
+  const connectionId =
+    getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID') ||
+    getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID');
+  const apiUrl = (
+    process.env.BRAINERCE_API_URL ||
+    getVar(envContent, 'BRAINERCE_API_URL') ||
+    'https://api.brainerce.com'
+  ).replace(/\/$/, '');
 
-function setVar(content, key, value) {
-  const regex = new RegExp(`^${key}=.*$`, 'm');
-  if (regex.test(content)) {
-    return content.replace(regex, `${key}=${value}`);
+  if (!connectionId) {
+    console.error('❌  NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID is not set in .env.local');
+    return 1;
+  }
+  if (connectionId.startsWith('vc_REPLACE_ME')) {
+    console.error(
+      '❌  .env.local still holds the placeholder id from --defer-connection. Run `npm run connect` first.'
+    );
+    return 1;
   }
-  return content.trimEnd() + `\n${key}=${value}\n`;
-}
 
-// Read either env var name. The new one is preferred; the old one is a soft
-// alias kept for backwards compatibility — the SDK accepts both.
-const connectionId =
-  getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID') ||
-  getVar(envContent, 'NEXT_PUBLIC_BRAINERCE_CONNECTION_ID');
-const apiUrl = (getVar(envContent, 'BRAINERCE_API_URL') || 'https://api.brainerce.com').replace(
-  /\/$/,
-  ''
-);
+  console.log(`Fetching store info for sales channel: ${connectionId} ...`);
 
-if (!connectionId) {
-  console.error('❌  NEXT_PUBLIC_BRAINERCE_SALES_CHANNEL_ID is not set in .env.local');
-  process.exit(1);
-}
+  let storeInfo;
+  try {
+    // /api/vc/* enforces an Origin check: TEST channels accept local/tunnel
+    // hosts, LIVE channels require the configured domain. Prefer an explicitly
+    // configured site URL (the real domain for a LIVE store); localhost is only
+    // a last resort, and it is correct here in a way it is NOT correct at
+    // runtime — this script runs on the developer's own machine, not on the
+    // host the storefront is deployed to.
+    const siteUrl =
+      process.env.SITE_URL ||
+      getVar(envContent, 'SITE_URL') ||
+      process.env.NEXT_PUBLIC_SITE_URL ||
+      getVar(envContent, 'NEXT_PUBLIC_SITE_URL') ||
+      'http://localhost:3000';
+    // Bounded: `npm run connect` runs this in agent shells with no TTY, where a
+    // hung request never gets a Ctrl-C.
+    const res = await fetch(`${apiUrl}/api/vc/${encodeURIComponent(connectionId)}/info`, {
+      headers: { Origin: siteUrl },
+      signal: AbortSignal.timeout(20_000),
+    });
+    if (!res.ok) {
+      console.error(`❌  API returned ${res.status}: ${await res.text()}`);
+      return 1;
+    }
+    storeInfo = await res.json();
+  } catch (err) {
+    console.error(`❌  Failed to reach ${apiUrl}: ${err.message}`);
+    return 1;
+  }
 
-console.log(`Fetching store info for sales channel: ${connectionId} ...`);
+  const name = storeInfo.name;
+  const currency = storeInfo.currency;
 
-let storeInfo;
-try {
-  // /api/vc/* enforces an Origin check: TEST channels accept local/tunnel
-  // hosts, LIVE channels require the configured domain. Prefer an explicitly
-  // configured site URL (the real domain for a LIVE store); localhost is only
-  // a last resort, and it is correct here in a way it is NOT correct at
-  // runtime — this script runs on the developer's own machine, not on the
-  // host the storefront is deployed to.
-  const siteUrl =
-    process.env.SITE_URL ||
-    getVar(envContent, 'SITE_URL') ||
-    process.env.NEXT_PUBLIC_SITE_URL ||
-    getVar(envContent, 'NEXT_PUBLIC_SITE_URL') ||
-    'http://localhost:3000';
-  const res = await fetch(`${apiUrl}/api/vc/${connectionId}/info`, {
-    headers: { Origin: siteUrl },
-  });
-  if (!res.ok) {
-    console.error(`❌  API returned ${res.status}: ${await res.text()}`);
-    process.exit(1);
+  if (!name) {
+    console.error('❌  Store info response has no `name` field:', storeInfo);
+    return 1;
+  }
+  // Currency is NOT NULL in the backend schema — a response without it
+  // is a real backend bug, not a "use the default" signal. Fail loud rather
+  // than silently leaving the env stale (which would bake the previous
+  // value into the next client bundle build).
+  if (!currency) {
+    console.error('❌  Store info response has no `currency` field:', storeInfo);
+    return 1;
   }
-  storeInfo = await res.json();
-} catch (err) {
-  console.error(`❌  Failed to reach ${apiUrl}: ${err.message}`);
-  process.exit(1);
-}
-
-const name = storeInfo.name;
-const currency = storeInfo.currency;
 
-if (!name) {
-  console.error('❌  Store info response has no `name` field:', storeInfo);
-  process.exit(1);
-}
-// Currency is NOT NULL in the backend schema — a response without it
-// is a real backend bug, not a "use the default" signal. Fail loud rather
-// than silently leaving the env stale (which would bake the previous
-// value into the next client bundle build).
-if (!currency) {
-  console.error('❌  Store info response has no `currency` field:', storeInfo);
-  process.exit(1);
-}
+  let updated = envContent;
+  updated = setVar(updated, 'NEXT_PUBLIC_STORE_NAME', name);
+  updated = setVar(updated, 'NEXT_PUBLIC_STORE_CURRENCY', currency);
 
-let updated = envContent;
-updated = setVar(updated, 'NEXT_PUBLIC_STORE_NAME', name);
-updated = setVar(updated, 'NEXT_PUBLIC_STORE_CURRENCY', currency);
+  writeFileSync(envPath, updated, 'utf-8');
 
-writeFileSync(envPath, updated, 'utf-8');
+  console.log(`✓ NEXT_PUBLIC_STORE_NAME=${name}`);
+  console.log(`✓ NEXT_PUBLIC_STORE_CURRENCY=${currency}`);
+  console.log('');
+  console.log('Done. These are NEXT_PUBLIC_* values, inlined at build time:');
+  console.log('  - restart the dev server (`npm run dev`) to see them locally;');
+  console.log('  - run `npm run build` before deploying, or the deployed bundle keeps the old ones.');
+  return 0;
+}
 
-console.log(`✓ NEXT_PUBLIC_STORE_NAME=${name}`);
-console.log(`✓ NEXT_PUBLIC_STORE_CURRENCY=${currency}`);
-console.log('Done. Restart the dev server for changes to take effect.');
+process.exitCode = await main();

package/templates/nextjs/base/src/app/api/auth/reset-callback/route.ts

@@ -9,7 +9,8 @@ function isSecure(): boolean {
 
 /**
  * Password-reset callback handler.
- * The email link redirects here with ?token=... from the backend.
+ * The email link lands on /reset-password?token=..., whose server component
+ * redirects here so the token can be moved into a cookie.
  * We store the token in an httpOnly cookie and redirect to /reset-password (clean URL).
  * This mirrors the OAuth callback pattern — the token never reaches client JS.
  */

package/templates/nextjs/base/src/app/forgot-password/page.tsx

@@ -21,8 +21,9 @@ export default function ForgotPasswordPage() {
       setLoading(true);
       setError(null);
       const client = getClient();
-      const resetUrl = `${window.location.origin}/api/auth/reset-callback`;
-      await client.forgotPassword(email, { resetUrl });
+      // The reset link's host is chosen by the server (the channel's domain),
+      // never by this page; the email lands on /reset-password?token=...
+      await client.forgotPassword(email);
       setSent(true);
     } catch (err) {
       const message =