backend-manager 5.2.0 → 5.2.2

package/CHANGELOG.md

@@ -14,6 +14,21 @@ 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.2.2] - 2026-05-21
+
+### Added
+
+- **`consent` is now a protected user field.** `templates/firestore.rules` includes `consent` in `isWritingProtectedUserField()` so a logged-in user cannot retroactively forge their own consent record from the client — only the signup route + webhook processors can mutate it server-side. New rule test in `test/rules/user.js`.
+- **`BaseCommand.getLogsPath(name)` / `getTempPath(name)`** in `src/cli/commands/base-command.js`. Two explicit helpers so the folder convention is the SSOT and easy to change later. `getLogsPath()` writes human-readable logs (`serve.log`, `emulator.log`, `test.log`, `logs.log`) to `<projectDir>/functions/` alongside firebase-tools' own `*-debug.log` files. `getTempPath()` writes transient internal-only stuff (`*.log.reset` sentinels, `bem-reload-trigger.js`, `test-mode.json`) to `<projectDir>/.temp/`.
+- **`BaseCommand.sweepStaleLogs()`** wipes BEM's own `.log` files in `functions/` and `.reset` sentinels in `.temp/` on every emulator/serve boot and on `npx mgr setup`. Deliberately does NOT touch firebase-tools' debug logs (`firestore-debug.log`, `database-debug.log`, etc.) so users can grep them after a crash.
+- **`npx mgr setup` cleanup step.** `cleanupGeneratedArtifacts()` now removes the watch trigger file (existing behavior) plus calls `sweepStaleLogs()` to clean up old BEM-owned logs/sentinels from previous runs.
+
+# [5.2.1] - 2026-05-21
+
+### Added
+
+- **`BACKEND_MANAGER_WEBHOOK_KEY` in `templates/_.env`.** The `.env` scaffold the setup CLI copies into consumer projects now declares the webhook key alongside `BACKEND_MANAGER_KEY`. Required for the new `/marketing/webhook` + `/marketing/webhook/forward` routes shipped in 5.2.0. Existing consumers should add it to their own `.env` manually.
+
 # [5.2.0] - 2026-05-21
 
 ### Added

package/README.md

@@ -850,12 +850,13 @@ npx mgr test user/ admin/       # Multiple paths
 
 ### Log Files
 
-BEM CLI commands automatically save output to log files in the project directory:
-- **`emulator.log`** — Full emulator + Cloud Functions output (`npx mgr emulator`)
-- **`test.log`** — Test runner output (`npx mgr test`, when running against an existing emulator)
-- **`logs.log`** — Cloud Function logs (`npx mgr logs:read` or `npx mgr logs:tail`)
+BEM CLI commands automatically save output to log files in the project's `functions/` directory (alongside firebase-tools' own `*-debug.log` files so everything is grep-able from one place):
+- **`functions/serve.log`** — Output from `npx mgr serve`
+- **`functions/emulator.log`** — Full emulator + Cloud Functions output (`npx mgr emulator`)
+- **`functions/test.log`** — Test runner output (`npx mgr test`, when running against an existing emulator)
+- **`functions/logs.log`** — Cloud Function logs (`npx mgr logs:read` or `npx mgr logs:tail`)
 
-Logs are overwritten on each run. Use them to debug failing tests or review function output.
+Logs are overwritten on each run and gitignored via `*.log`. Use them to debug failing tests or review function output. Transient internal artifacts (reset sentinels, watch trigger, `test-mode.json`) live separately in `<projectDir>/.temp/`.
 
 ### Test Locations
 

package/docs/testing.md

@@ -94,7 +94,7 @@ npx mgr test ...                                 # ← this still flips it back
 
 ## Log Files
 
-BEM CLI commands automatically save all output to log files in `functions/` while still streaming to the console:
+BEM CLI commands automatically save all output to log files in `<projectDir>/functions/` while still streaming to the console — co-located with firebase-tools' own `*-debug.log` files so everything can be grepped from one directory:
 - **`functions/serve.log`** — Output from `npx mgr serve` (Firebase serve)
 - **`functions/emulator.log`** — Full emulator output (Firebase emulator + Cloud Functions logs)
 - **`functions/test.log`** — Test runner output (when running against an existing emulator)
@@ -102,7 +102,7 @@ BEM CLI commands automatically save all output to log files in `functions/` whil
 
 When `npx mgr test` starts its own emulator, logs go to `emulator.log` (since it delegates to the emulator command). When running against an already-running emulator, logs go to `test.log`.
 
-These files are overwritten on each run and are gitignored (`*.log`). Use them to search for errors, debug webhook pipelines, or review full function output after a test run.
+These files are overwritten on each run and are gitignored via `*.log`. Reset sentinels (`*.log.reset`), the watch trigger file, and `test-mode.json` live separately in `<projectDir>/.temp/` because they're transient internal signals with no debugging value.
 
 ## Filtering Tests
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backend-manager",
-  "version": "5.2.0",
+  "version": "5.2.2",
   "description": "Quick tools for developing Firebase functions",
   "main": "src/manager/index.js",
   "bin": {

package/src/cli/commands/base-command.js

@@ -16,6 +16,73 @@ class BaseCommand {
     throw new Error('Execute method must be implemented');
   }
 
+  /**
+   * Resolve a path inside the consumer project's `.temp/` directory. Used for
+   * TRULY internal artifacts that have no debugging value: reset sentinels
+   * (*.log.reset), the watch command's reload trigger, and `test-mode.json`.
+   *
+   * For human-readable log files, use `getLogsPath()` instead — those live in
+   * `functions/` next to firebase-tools' own *-debug.log files so all log
+   * output can be grepped from one directory.
+   *
+   * Ensures the directory exists.
+   * @param {string} [filename] - File name to append (omit to get the dir path).
+   * @returns {string} Absolute path.
+   */
+  getTempPath(filename) {
+    const projectDir = this.main.firebaseProjectPath;
+    const tempDir = path.join(projectDir, '.temp');
+    jetpack.dir(tempDir);
+    return filename ? path.join(tempDir, filename) : tempDir;
+  }
+
+  /**
+   * Resolve a path for a human-readable log file. BEM-owned logs (serve.log,
+   * emulator.log, test.log, logs.log) live in `functions/` alongside
+   * firebase-tools' own *-debug.log files so all log output is grep-able from
+   * one place. Reset sentinels and other internal-only artifacts use
+   * `getTempPath()` instead.
+   *
+   * @param {string} [filename] - File name to append (omit to get the dir path).
+   * @returns {string} Absolute path.
+   */
+  getLogsPath(filename) {
+    const projectDir = this.main.firebaseProjectPath;
+    const logsDir = path.join(projectDir, 'functions');
+    return filename ? path.join(logsDir, filename) : logsDir;
+  }
+
+  /**
+   * Sweep stale BEM-owned logs out of `functions/`. Catches `.log` files
+   * from previous runs so each emulator/serve/test boot starts with a clean
+   * slate. Also catches stale `.reset` sentinels in `.temp/` that a crashed
+   * process may have left behind.
+   *
+   * Firebase-tools writes its own debug logs (firestore-debug.log,
+   * database-debug.log, pubsub-debug.log, firebase-debug.log, ui-debug.log) to
+   * cwd and we can't redirect them — we deliberately do NOT touch those, so
+   * users can grep them after a crash.
+   */
+  sweepStaleLogs() {
+    const logFiles = [
+      'serve.log',
+      'emulator.log',
+      'test.log',
+      'logs.log',
+    ];
+    const resetSentinels = [
+      'serve.log.reset',
+      'emulator.log.reset',
+    ];
+
+    for (const name of logFiles) {
+      try { jetpack.remove(this.getLogsPath(name)); } catch (e) { /* best-effort */ }
+    }
+    for (const name of resetSentinels) {
+      try { jetpack.remove(this.getTempPath(name)); } catch (e) { /* best-effort */ }
+    }
+  }
+
   log(...args) {
     console.log(...args);
   }

package/src/cli/commands/emulator.js

@@ -73,6 +73,10 @@ class EmulatorCommand extends BaseCommand {
       throw new Error('Port conflicts could not be resolved');
     }
 
+    // Wipe stale firebase-tools debug logs + any leftover BEM logs from older
+    // versions. Keeps the project tree clean across runs.
+    this.sweepStaleLogs();
+
     // BEM_TESTING=true is passed so Functions skip external API calls (emails, SendGrid)
     // hosting is included so localhost:5002 rewrites work (e.g., /backend-manager -> bm_api)
     // pubsub is included so scheduled functions (bm_cronDaily) can be triggered in tests
@@ -87,8 +91,8 @@ class EmulatorCommand extends BaseCommand {
     // by touching emulator.log.reset — the watcher below detects it, closes the
     // current stream, reopens with flags: 'w' (truncating cleanly from our process'
     // perspective, no sparse-file issue), and deletes the sentinel.
-    const logPath = path.join(projectDir, 'functions', 'emulator.log');
-    const resetSentinelPath = `${logPath}.reset`;
+    const logPath = this.getLogsPath('emulator.log');
+    const resetSentinelPath = this.getTempPath('emulator.log.reset');
     const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
 
     let currentStream = fs.createWriteStream(logPath, { flags: 'w' });

package/src/cli/commands/logs.js

@@ -72,9 +72,8 @@ class LogsCommand extends BaseCommand {
       `--order=${order}`,
     ].filter(Boolean).join(' ');
 
-    // Set up log file in the project directory
-    const projectDir = this.main.firebaseProjectPath;
-    const logPath = path.join(projectDir, 'functions', 'logs.log');
+    // Set up log file in the project's functions/ directory
+    const logPath = this.getLogsPath('logs.log');
 
     this.log(chalk.gray(`  Filter: ${filter || '(none)'}`));
     this.log(chalk.gray(`  Limit: ${limit}`));
@@ -126,9 +125,8 @@ class LogsCommand extends BaseCommand {
     const seenIds = new Set();
     let stopped = false;
 
-    // Set up log file in the project directory
-    const projectDir = this.main.firebaseProjectPath;
-    const logPath = path.join(projectDir, 'functions', 'logs.log');
+    // Set up log file in the project's functions/ directory
+    const logPath = this.getLogsPath('logs.log');
     const logStream = fs.createWriteStream(logPath, { flags: 'w' });
 
     const filter = this.buildFilter(argv, { excludeTimestamp: true });

package/src/cli/commands/serve.js

@@ -18,6 +18,10 @@ class ServeCommand extends BaseCommand {
       throw new Error('Port conflicts could not be resolved');
     }
 
+    // Wipe stale firebase-tools debug logs + any leftover BEM logs from older
+    // versions. Keeps the project tree clean across runs.
+    this.sweepStaleLogs();
+
     // Start BEM watcher in background
     const watcher = new WatchCommand(self);
     watcher.startBackground();
@@ -40,8 +44,8 @@ class ServeCommand extends BaseCommand {
     //      lines on the first cycle (subsequent cycles route those elsewhere), so
     //      we'd end up with a near-empty log. Rolling at the START of the cycle
     //      lets us capture whatever firebase-tools does emit, complete-or-not.
-    const logPath = path.join(projectDir, 'functions', 'serve.log');
-    const resetSentinelPath = `${logPath}.reset`;
+    const logPath = this.getLogsPath('serve.log');
+    const resetSentinelPath = this.getTempPath('serve.log.reset');
     // Match any node version: "Using node@22 from host.", "Using node@20 from host.", etc.
     const RELOAD_MARKER = /Using node@\d+ from host\./;
     const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');

package/src/cli/commands/setup.js

@@ -104,8 +104,8 @@ class SetupCommand extends BaseCommand {
       throw new Error('Missing <engines.node> in package.json');
     }
 
-    // Clean up leftover trigger files from watch command
-    this.cleanupTriggerFiles();
+    // Clean up leftover trigger files + stale log files from older BEM versions
+    this.cleanupGeneratedArtifacts();
 
     // 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.
@@ -219,13 +219,19 @@ class SetupCommand extends BaseCommand {
     }
   }
 
-  cleanupTriggerFiles() {
+  cleanupGeneratedArtifacts() {
     const self = this.main;
-    const triggerFile = `${self.firebaseProjectPath}/functions/bem-reload-trigger.js`;
 
+    // Remove the BEM reload-trigger file (transient artifact from `npx mgr watch`)
+    const triggerFile = `${self.firebaseProjectPath}/functions/bem-reload-trigger.js`;
     if (jetpack.exists(triggerFile)) {
       jetpack.remove(triggerFile);
     }
+
+    // Sweep stale firebase-tools debug logs + leftover BEM logs from older
+    // versions (pre-5.2.2 they lived in functions/; now in .temp/). Shared
+    // implementation in base-command.js so emulator/serve boot also runs it.
+    this.sweepStaleLogs();
   }
 
   async runTests() {

package/src/cli/commands/test.js

@@ -199,8 +199,7 @@ class TestCommand extends BaseCommand {
    * log just won't be reset for this run.
    */
   async requestEmulatorLogReset(projectDir) {
-    const logPath = path.join(projectDir, 'functions', 'emulator.log');
-    const sentinelPath = `${logPath}.reset`;
+    const sentinelPath = this.getTempPath('emulator.log.reset');
 
     try {
       fs.writeFileSync(sentinelPath, '');
@@ -242,8 +241,8 @@ class TestCommand extends BaseCommand {
     this.log(chalk.gray(`  Auth: 127.0.0.1:${emulatorPorts.auth}`));
     this.log(chalk.gray(`  UI: http://127.0.0.1:${emulatorPorts.ui}`));
 
-    // Set up log file in the project directory
-    const logPath = path.join(projectDir, 'functions', 'test.log');
+    // Set up log file in the project's functions/ directory (alongside firebase-tools logs)
+    const logPath = this.getLogsPath('test.log');
     const logStream = fs.createWriteStream(logPath, { flags: 'w' });
     const stripAnsi = (str) => str.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, '');
 

package/src/cli/commands/watch.js

@@ -60,8 +60,8 @@ class WatchCommand extends BaseCommand {
     // command isn't watching, the file is harmless and gets cleaned up by the next
     // boot's stale-sentinel sweep.
     const triggerFile = config.triggerFile;
-    const serveLogResetPath = path.join(config.functionsDir, 'serve.log.reset');
-    const emulatorLogResetPath = path.join(config.functionsDir, 'emulator.log.reset');
+    const serveLogResetPath = this.getTempPath('serve.log.reset');
+    const emulatorLogResetPath = this.getTempPath('emulator.log.reset');
     const nodemon = spawn(nodemonPath, [
       '--on-change-only',
       '--delay', '1',
@@ -104,8 +104,8 @@ class WatchCommand extends BaseCommand {
     // Use nodemon to watch the BEM src directory and touch the trigger file on changes.
     // Also drop <log>.reset sentinels so any sibling serve/emulator command rolls its
     // log file on each reload (mirrors the test runner's log-roll pattern).
-    const serveLogResetPath = path.join(config.functionsDir, 'serve.log.reset');
-    const emulatorLogResetPath = path.join(config.functionsDir, 'emulator.log.reset');
+    const serveLogResetPath = this.getTempPath('serve.log.reset');
+    const emulatorLogResetPath = this.getTempPath('emulator.log.reset');
     const nodemon = spawn(nodemonPath, [
       '--watch', config.bemSrcDir,
       '--ext', 'js,json',

package/templates/_.env

@@ -1,6 +1,7 @@
 # ========== Default Values ==========
 # Backend Manager
 BACKEND_MANAGER_KEY=""
+BACKEND_MANAGER_WEBHOOK_KEY=""
 BACKEND_MANAGER_NAMESPACE=""
 BACKEND_MANAGER_OPENAI_API_KEY=""
 BACKEND_MANAGER_ANTHROPIC_API_KEY=""

package/templates/firestore.rules

@@ -69,7 +69,8 @@ service cloud.firestore {
         || isWritingField('affiliate')
         || isWritingField('api')
         || isWritingField('metadata')
-        || isWritingField('usage');
+        || isWritingField('usage')
+        || isWritingField('consent');
     }
 
     function isCreatingField(field) {

package/test/rules/user.js

@@ -6,7 +6,7 @@
  * - Users can read their own document
  * - Users can write to their own document (non-protected fields only)
  * - Users cannot read/write other users' documents
- * - Protected fields (auth, roles, flags, subscription, affiliate, api, usage) cannot be written by users
+ * - Protected fields (auth, roles, flags, subscription, affiliate, api, metadata, usage, consent) cannot be written by users
  *
  * @see templates/firestore.rules
  */
@@ -234,6 +234,28 @@ module.exports = {
       },
     },
 
+    // Test 11.5: User cannot write 'consent' field (protected - server-only)
+    {
+      name: 'user-cannot-write-consent-field',
+      auth: 'none',
+
+      async run({ rules, accounts }) {
+        const uid = accounts.basic.uid;
+        const db = rules.asAccount('basic');
+
+        // Should fail - consent is protected (only signup route + webhook
+        // processors can mutate it server-side; a client write would let a
+        // user retroactively forge their own consent record).
+        await rules.expectFailure(
+          db.doc(`users/${uid}`).set({
+            consent: {
+              marketing: { status: 'granted' },
+            },
+          }, { merge: true })
+        );
+      },
+    },
+
     // Test 12: User cannot write to another user's document
     {
       name: 'user-cannot-write-other-doc',