backend-manager 5.0.200 → 5.0.202

package/CHANGELOG.md

@@ -14,6 +14,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+# [5.0.202] - 2026-05-12
+### Added
+- **`src/defaults/CLAUDE.md`** — new file shipped to consumer projects, marker-wrapped with `# ========== Default Values ==========` / `# ========== Custom Values ==========`. Framework section stays live-synced across `npx mgr setup` while the Custom section is preserved verbatim. Aligns BEM with EM/BXM/UJM, which already ship a consumer-facing default CLAUDE.md.
+- **`src/utils/merge-line-files.js`** — new file. Implements the line-based merge for the marker-wrapped Default/Custom sections (copied verbatim from `electron-manager`'s utility). Reusable across `.env`, `.gitignore`, `CLAUDE.md`, and any other line-based files BEM might ship in the future.
+- **`copyDefaults()` method** in `src/cli/commands/setup.js`. New defaults-shipping mechanism for BEM (which previously had no `src/defaults/` directory at all). Mirrors EM's `copyDefaults` pattern: iterates `src/defaults/**`, renames `_.foo` → `.foo`, routes files matching `MERGEABLE_BASENAMES` (`['.env', '.gitignore', 'CLAUDE.md']`) through `mergeLineBasedFiles`, copies non-mergeable files only if they don't already exist. Wired into `runSetup()` BEFORE `runTests()` so test inspections see the merged state.
+
+# [5.0.201] - 2026-05-08
+### Changed
+- Account deletion confirmation email now includes a "Deletion details:" block with the user's account email, UID, and deletion timestamp (UTC) — matching the pattern used in the data-request download email.
+
 # [5.0.200] - 2026-05-05
 ### Changed
 - Bumped `uuid` from `^13.0.2` to `^14.0.0`. uuid v14 is ESM-only, but Node 22+'s native `require(esm)` support means existing CommonJS call sites (`require('uuid').v4`, `.v5`, etc.) work unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.0.200",
+  "version": "5.0.202",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {
@@ -49,7 +49,7 @@
     }
   },
   "dependencies": {
-    "@firebase/rules-unit-testing": "^5.0.0",
+    "@firebase/rules-unit-testing": "^5.0.1",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/pubsub": "^5.3.0",
     "@google-cloud/storage": "^7.19.0",
@@ -57,7 +57,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@octokit/rest": "^22.0.1",
     "@sendgrid/mail": "^8.1.6",
-    "@sentry/node": "^10.51.0",
+    "@sentry/node": "^10.52.0",
     "body-parser": "^2.2.2",
     "busboy": "^1.6.0",
     "chalk": "^5.6.2",
@@ -81,7 +81,7 @@
     "npm-api": "^1.0.1",
     "pushid": "^1.0.0",
     "sanitize-html": "^2.17.3",
-    "stripe": "^22.1.0",
+    "stripe": "^22.1.1",
     "uid-generator": "^2.0.0",
     "uuid": "^14.0.0",
     "wonderful-fetch": "^2.0.5",
@@ -94,7 +94,7 @@
     "prepare-package": "^2.1.0"
   },
   "peerDependencies": {
-    "firebase-admin": "^13.8.0",
+    "firebase-admin": "^13.9.0",
     "firebase-functions": "^7.2.5"
   }
 }

package/src/cli/commands/setup.js

@@ -107,6 +107,10 @@ class SetupCommand extends BaseCommand {
     // Clean up leftover trigger files from watch command
     this.cleanupTriggerFiles();
 
+    // Copy / merge defaults into consumer project root (matches EM/BXM/UJM pattern).
+    // Runs BEFORE tests so any test that inspects scaffolded files sees the merged state.
+    this.copyDefaults();
+
     // Run all tests
     await this.runTests();
 
@@ -147,6 +151,74 @@ class SetupCommand extends BaseCommand {
     self.default.databaseRulesCore = self.default.databaseRulesWhole.match(bem_allRulesRegex)[0];
   }
 
+  // Copy default files (src/defaults/**) into the consumer project root.
+  // For files in MERGEABLE_BASENAMES, route through `mergeLineBasedFiles` so the
+  // framework's section stays live-synced while the consumer's Custom section is
+  // preserved verbatim. For non-mergeable files: copy on first setup, skip if exists.
+  //
+  // Mirrors EM's copyDefaults pattern (src/commands/setup.js in electron-manager).
+  // Same marker convention as .env/.gitignore in EM/BXM/UJM:
+  //   # ========== Default Values ==========   (framework-owned)
+  //   # ========== Custom Values ==========    (consumer-owned)
+  copyDefaults() {
+    const self = this.main;
+    const defaultsDir = path.resolve(`${__dirname}/../../defaults`);
+
+    if (!jetpack.exists(defaultsDir)) {
+      // Defaults dir is optional — older BEM versions didn't have one. If missing, skip silently.
+      return;
+    }
+
+    const { mergeLineBasedFiles } = require('../../utils/merge-line-files.js');
+    // Files routed through the marker-based merge (vs verbatim copy / skip-if-exists).
+    // .env / .gitignore aren't currently shipped by BEM but are included here so this
+    // matches the EM/BXM/UJM contract if we ever add them.
+    const MERGEABLE_BASENAMES = new Set(['.env', '.gitignore', 'CLAUDE.md']);
+
+    const files = jetpack.find(defaultsDir, { matching: '**/*', recursive: true, files: true, directories: false });
+
+    for (const src of files) {
+      const rel = path.relative(defaultsDir, src);
+      const segments = rel.split(path.sep);
+
+      // Skip "archive" directories — anything under a path segment starting with `_` and
+      // followed by a non-`.` character. Matches EM/BXM/UJM convention. The `_.env` /
+      // `_.gitignore` files are NOT skipped; their leading `_` strips on copy below.
+      if (segments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
+        continue;
+      }
+
+      // Convert leading `_.` to `.` so dotfiles ship past npm's filter.
+      const target = segments.map((part) => part.startsWith('_.') ? part.slice(1) : part).join(path.sep);
+      const dest = path.join(self.firebaseProjectPath, target);
+      const basename = path.basename(target);
+
+      if (jetpack.exists(dest)) {
+        if (MERGEABLE_BASENAMES.has(basename)) {
+          try {
+            const existing = jetpack.read(dest, 'utf8');
+            const incoming = jetpack.read(src, 'utf8');
+            const merged   = mergeLineBasedFiles(existing, incoming, basename);
+            if (merged !== existing) {
+              jetpack.write(dest, merged);
+              this.logSuccess(`Merged default → ${target}`);
+            }
+          } catch (e) {
+            this.logWarning(`Failed to merge ${target}: ${e.message}`);
+          }
+          continue;
+        }
+
+        // Non-mergeable, already exists → preserve consumer's version.
+        continue;
+      }
+
+      // First time: copy as-is.
+      jetpack.copy(src, dest);
+      this.logSuccess(`Copied default → ${target}`);
+    }
+  }
+
   cleanupTriggerFiles() {
     const self = this.main;
     const triggerFile = `${self.firebaseProjectPath}/functions/bem-reload-trigger.js`;

package/src/defaults/CLAUDE.md

@@ -0,0 +1,73 @@
+# ========== Default Values ==========
+# Backend Manager (BEM) — consumer project
+
+> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `backend-manager` and rewritten on every `npx mgr setup`. Put your own project-specific notes BELOW the `Custom Values` marker — that section is preserved verbatim across setups.
+
+## Framework
+
+This project consumes **Backend Manager** (BEM) — a comprehensive framework for building modern Firebase Cloud Functions backends. BEM provides a single `Manager.init(exports, {...})` bootstrap that wires built-in functions (`bm_api`, auth events, cron jobs), helper classes (Assistant, User, Analytics, Usage, Middleware, Settings, Utilities, Metadata), payment processor integrations (Stripe / PayPal), Firestore-trigger pipelines, and a deploy/emulator/watch tooling pipeline.
+
+**Framework's own docs** (read these for deep-dives; both paths point to the same files, the absolute path works regardless of working directory):
+- Top-level overview: `/Users/ian/Developer/Repositories/ITW-Creative-Works/backend-manager/CLAUDE.md` (or `node_modules/backend-manager/CLAUDE.md`)
+
+## Quick start
+
+```bash
+cd functions
+npx mgr setup       # validate config + scaffold defaults + run checks
+npx mgr emulator    # start Firebase emulators (auth/firestore/functions/database/storage)
+npx mgr watch       # auto-reload functions on file change
+npx mgr deploy      # deploy to Firebase
+npx mgr logs        # tail Cloud Functions logs
+```
+
+All `npx mgr <cmd>` aliases — `npx bm <cmd>`, `npx bem <cmd>`, `npx backend-manager <cmd>` work too.
+
+## Where things live
+
+- `functions/index.js` — entry point. Must call `Manager.init(exports, { ... })` to register all built-in + custom endpoints.
+- `functions/backend-manager-config.json` — BEM config: brand, projectType (`firebase` or `custom`), feature flags, rate limits, hooks.
+- `functions/.env` — secrets (BACKEND_MANAGER_KEY, third-party API keys). Gitignored.
+- `functions/service-account.json` — Firebase Admin credentials. Gitignored.
+- `functions/routes/<verb>/<path>.js` — custom routes mounted at runtime (e.g. `routes/get/hello.js` → `GET /hello`).
+- `functions/schemas/<name>.js` — schema definitions for `Manager.Settings()` validation.
+- `firebase.json` — Firebase config (hosting, rewrites, emulator ports). Some fields managed by `npx mgr setup`.
+- `.firebaserc` — Firebase project ID alias.
+- `firestore.rules` / `database.rules.json` — security rules. BEM owns a `///---backend-manager---///` block inside each; everything outside is yours.
+
+## Per-context imports
+
+```js
+// functions/index.js — the entire backend bootstrap
+const Manager = require('backend-manager');
+Manager.init(exports, {
+  projectType: 'firebase',
+  // ...your config
+});
+
+// In a custom route (functions/routes/get/hello.js):
+module.exports = async function(Manager, assistant) {
+  // assistant.req, assistant.res, assistant.user, etc.
+};
+```
+
+## Available APIs at runtime
+
+After `Manager.init()`, the Manager instance exposes factory methods:
+- `Manager.Assistant({ req, res })` — request handler with user + analytics + utility access
+- `Manager.User(data)` — user property structure + schema
+- `Manager.Analytics({ assistant })` — GA4 event tracking
+- `Manager.Usage()` — rate-limiting
+- `Manager.Middleware(req, res)` — request pipeline
+- `Manager.Settings()` — schema validation against `functions/schemas/*`
+- `Manager.Utilities()` — batch operations + helpers
+- `Manager.Metadata(doc)` — timestamps + tag helpers
+- `Manager.storage({ name })` — local JSON storage (lowdb)
+
+Auth events, payment-webhook transitions, and cron jobs are wired automatically — hook into them by exporting from `functions/hooks/<area>/<event>.js`.
+
+# ========== Custom Values ==========
+
+## Project-specific notes
+
+Add anything specific to THIS project here. Edits below this line are preserved across `npx mgr setup` runs.

package/src/manager/libraries/disposable-domains.json

@@ -1109,6 +1109,7 @@
   "dealja.com",
   "deallabs.org",
   "dealrek.com",
+  "deapad.com",
   "decep.com",
   "decodewp.com",
   "dede.infos.st",
@@ -1376,6 +1377,9 @@
   "edudingy.cfd",
   "edumail.edu.pl",
   "edumail.edu.rs",
+  "edumaili.com",
+  "edumaili.edu.pl",
+  "edumaill.edu.pl",
   "edupolska.edu.pl",
   "edv.to",
   "ee1.pl",
@@ -2460,6 +2464,7 @@
   "javadmin.com",
   "javaemail.com",
   "jbsze.com",
+  "jbsze.ne",
   "jcnorris.com",
   "jdmadventures.com",
   "jdz.ro",
@@ -2908,6 +2913,7 @@
   "maileater.com",
   "mailed.in",
   "mailed.ro",
+  "mailedu.edu.pl",
   "maileimer.de",
   "maileme101.com",
   "mailer.edu.pl",
@@ -3171,6 +3177,7 @@
   "mliok.com",
   "mm.my",
   "mm5.se",
+  "mmaily.com",
   "mnode.me",
   "moakt.cc",
   "moakt.co",

package/src/manager/routes/user/delete.js

@@ -81,7 +81,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
   // Send confirmation email (fire-and-forget)
   const shouldSend = !assistant.isTesting() || process.env.TEST_EXTENDED_MODE;
   if (email && shouldSend) {
-    sendConfirmationEmail(assistant, email, reason, userData?.personal?.name?.first);
+    sendConfirmationEmail(assistant, email, uid, reason, userData?.personal?.name?.first);
   }
 
   return assistant.respond({ success: true });
@@ -90,7 +90,7 @@ module.exports = async ({ assistant, Manager, user, settings, libraries }) => {
 /**
  * Send account deletion confirmation email (fire-and-forget)
  */
-function sendConfirmationEmail(assistant, email, reason, firstName) {
+function sendConfirmationEmail(assistant, email, uid, reason, firstName) {
   const Manager = assistant.Manager;
   const brandName = Manager.config.brand.name;
   const mailer = Manager.Email(assistant);
@@ -98,6 +98,7 @@ function sendConfirmationEmail(assistant, email, reason, firstName) {
   const reasonLine = reason
     ? `\n\n**Reason provided:** ${reason}`
     : '';
+  const deletionDate = new Date().toUTCString();
 
   mailer.send({
     to: email,
@@ -114,6 +115,12 @@ function sendConfirmationEmail(assistant, email, reason, firstName) {
         title: 'Account Deleted',
         message: `${greeting} **${brandName}** account and all associated personal data have been permanently deleted from our systems. This action is irreversible.${reasonLine}
 
+**Deletion details:**
+
+- **Account email:** ${email}
+- **Account UID:** ${uid}
+- **Deletion date:** ${deletionDate}
+
 **What this means:**
 
 - Your account credentials and profile information have been removed.

package/src/utils/merge-line-files.js

@@ -0,0 +1,211 @@
+// Merge line-based files (.env, .gitignore, CLAUDE.md) on `npx mgr setup`.
+//
+// Convention (matches EM/BXM/UJM):
+//
+//   # ========== Default Values ==========
+//   # framework-managed; overwritten on every setup
+//   KEY1=
+//   KEY2="value with spaces"
+//
+//   # ========== Custom Values ==========
+//   # user's section; preserved verbatim across setups
+//   USER_SECRET="my-secret"
+//
+// Behavior:
+//   - The Default section is replaced with the new framework's defaults.
+//   - Keys that already had values (in either Default or Custom) keep those values
+//     in the same section they were in.
+//   - Keys the user added to the Default section that are NOT in the new framework's
+//     defaults migrate to the Custom section (so framework cleanups don't lose user data).
+//   - .env values are normalized to **double-quoted** form on every merge:
+//       KEY=raw-value         →   KEY="raw-value"
+//       KEY="already-quoted"  →   KEY="already-quoted"  (left alone)
+//       KEY=                  →   KEY=                  (empty stays empty/unquoted)
+//     This protects values containing spaces, #, $, or other shell-meaningful chars.
+//   - .gitignore: same logic, line-based instead of key-based (no quoting).
+//   - CLAUDE.md: same logic as .gitignore (line-based, no quoting). The markers
+//     render as visible H1 headings in markdown — that's intentional UX.
+//   - First setup (no existing file): the framework template lands as-is.
+
+const DEFAULT_MARKER = '# ========== Default Values ==========';
+const CUSTOM_MARKER  = '# ========== Custom Values ==========';
+
+function mergeLineBasedFiles(existingContent, newContent, fileName) {
+  const isEnvFile = fileName === '.env';
+
+  const existingLines = existingContent.split('\n');
+  const newLines      = newContent.split('\n');
+
+  // Parse existing into default + custom sections.
+  const { defaultLines: existingDefault, customLines: existingCustom, existingDefaultKeys, existingCustomKeys }
+    = splitSections(existingLines, isEnvFile);
+
+  // Parse new content. We only use its default section (custom is the user's domain).
+  const { defaultLines: newDefault, customLines: newCustom } = splitSections(newLines, isEnvFile);
+
+  // Build the merged default section: walk new defaults in order, substituting the
+  // user's existing value for any key they had set in either section.
+  const newDefaultKeys = new Set();
+  const mergedDefault  = [];
+  const emit = (line) => mergedDefault.push(isEnvFile ? normalizeEnvLine(line) : line);
+
+  for (const line of newDefault) {
+    const trimmed = line.trim();
+
+    if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      const key = trimmed.split('=')[0].trim();
+      if (key) {
+        newDefaultKeys.add(key);
+        if (existingDefaultKeys.has(key)) {
+          emit(findKeyLine(existingDefault, key));
+          continue;
+        }
+        if (existingCustomKeys.has(key)) {
+          // Key the user moved to custom — leave it in custom; emit empty default value.
+          emit(line);
+          continue;
+        }
+      }
+      emit(line);
+    } else if (!isEnvFile && trimmed && !trimmed.startsWith('#')) {
+      // .gitignore / CLAUDE.md: just keep the new line.
+      mergedDefault.push(line);
+    } else {
+      // Comment / blank.
+      mergedDefault.push(line);
+    }
+  }
+
+  // User-added stuff in their Default section that the new framework doesn't know about
+  // → migrate to Custom so it's preserved without being clobbered next setup.
+  const migratedToCustom = [];
+  for (const line of existingDefault) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    if (isEnvFile) {
+      const key = trimmed.split('=')[0].trim();
+      if (key && !newDefaultKeys.has(key) && !existingCustomKeys.has(key)) {
+        migratedToCustom.push(normalizeEnvLine(line));
+      }
+    } else {
+      // .gitignore / CLAUDE.md: line not in new defaults → migrate.
+      const inNew = newLines.some((nl) => nl.trim() === trimmed);
+      if (!inNew) {
+        migratedToCustom.push(line);
+      }
+    }
+  }
+
+  // The user's Custom section is preserved verbatim — except .env values get
+  // normalized to double-quoted form so the file's quoting style is consistent.
+  const finalCustom = isEnvFile
+    ? existingCustom.map((line) => normalizeEnvLine(line))
+    : existingCustom;
+
+  const result = [];
+  result.push(DEFAULT_MARKER);
+  result.push(...mergedDefault);
+  // Insert a single blank line before CUSTOM_MARKER, but only if the merged default
+  // doesn't already end with one (otherwise we'd accumulate an extra blank line on
+  // every merge — breaking idempotency on the first re-run after a fresh `jetpack.copy`).
+  if (mergedDefault.length === 0 || mergedDefault[mergedDefault.length - 1].trim() !== '') {
+    result.push('');
+  }
+  result.push(CUSTOM_MARKER);
+  if (migratedToCustom.length > 0) {
+    result.push(...migratedToCustom);
+  }
+  result.push(...finalCustom);
+
+  return result.join('\n');
+}
+
+// Normalize a single .env line:
+//   - Comments / blanks unchanged
+//   - KEY=  (empty value) unchanged
+//   - KEY="..." (already double-quoted) unchanged
+//   - KEY=raw-value → KEY="raw-value" (with embedded " and \ escaped)
+//   - KEY='single' → KEY="single"  (canonicalize single → double)
+function normalizeEnvLine(line) {
+  if (typeof line !== 'string') return line;
+
+  // Preserve comments and blank lines verbatim.
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return line;
+
+  // Capture leading whitespace so we don't lose indentation.
+  const leadingMatch = line.match(/^(\s*)/);
+  const leading = leadingMatch ? leadingMatch[1] : '';
+
+  const eqIdx = trimmed.indexOf('=');
+  if (eqIdx < 0) return line; // no `=` — not a KEY=VALUE line
+
+  const key = trimmed.slice(0, eqIdx).trim();
+  let value = trimmed.slice(eqIdx + 1);
+
+  // Strip trailing whitespace + inline comment-after-value (rare; we only strip a # that follows a space).
+  // We do NOT strip # inside quoted values. Detect that by checking if value starts with a quote.
+  if (value.length === 0) {
+    return `${leading}${key}=`;
+  }
+
+  // Already double-quoted? Leave alone (preserves user's exact contents).
+  if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+    return `${leading}${key}=${value}`;
+  }
+
+  // Single-quoted → canonicalize to double-quoted.
+  if (value.startsWith("'") && value.endsWith("'") && value.length >= 2) {
+    const inner = value.slice(1, -1);
+    return `${leading}${key}="${escapeForDoubleQuote(inner)}"`;
+  }
+
+  // Raw value → wrap.
+  return `${leading}${key}="${escapeForDoubleQuote(value)}"`;
+}
+
+function escapeForDoubleQuote(s) {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+function splitSections(lines, isEnvFile) {
+  const defaultLines = [];
+  const customLines  = [];
+  const existingDefaultKeys = new Set();
+  const existingCustomKeys  = new Set();
+
+  let mode = null; // null | 'default' | 'custom'
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === DEFAULT_MARKER) { mode = 'default'; continue; }
+    if (trimmed === CUSTOM_MARKER)  { mode = 'custom';  continue; }
+
+    // Lines before any marker are treated as default (legacy / fresh files).
+    if (mode === 'custom') {
+      customLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingCustomKeys.add(key);
+      }
+    } else {
+      defaultLines.push(line);
+      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
+        const key = trimmed.split('=')[0].trim();
+        if (key) existingDefaultKeys.add(key);
+      }
+    }
+  }
+
+  return { defaultLines, customLines, existingDefaultKeys, existingCustomKeys };
+}
+
+function findKeyLine(lines, key) {
+  const re = new RegExp(`^\\s*${key}\\s*=`);
+  for (const line of lines) {
+    if (re.test(line)) return line;
+  }
+  return `${key}=`;
+}
+
+module.exports = { mergeLineBasedFiles, normalizeEnvLine, DEFAULT_MARKER, CUSTOM_MARKER };