backend-manager 5.2.18 → 5.2.19

package/CHANGELOG.md

@@ -14,6 +14,22 @@ 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.19] - 2026-05-29
+
+### Added
+
+- **Shared CLI styling module (`src/cli/utils/ui.js`)** — the SSOT for BEM console output, matching the OMEGA Manager look: a `🚀` banner, 70-char `━` dividers, indented tree output, dimmed `Label:` fields, timestamps, a consistent set of status symbols (`→ ✓ ✗ ⊘ ⚠ ✅ + ↻`), and a `Summary` block (green `✅` / yellow `⚠`). Exposed on every command as `this.ui` (wired in `base-command.js`) and adoptable incrementally by `serve`/`deploy`/`test`/`emulator`. See `docs/cli-output.md`.
+- **Regression test for the `.env`/`.gitignore` merge** (`test/helpers/merge-line-files.js`). Covers key-based alignment when key order drifts (the original scramble), Custom→Default promotion when the template adopts a key, Default→Custom migration of unknown keys, value preservation, quote normalization, idempotency, and that the setup-test helper is the same function as the canonical impl (SSOT guard).
+
+### Changed
+
+- **`npx mgr setup` now renders in the OMEGA style.** The old `---- RUNNING SETUP ----` / `[1] name: passed` / bare missing-keys dump is replaced with a banner, a divider-wrapped project header (brand name + Firebase console URL + `Project`/`API` fields), and `[DEFAULTS]` / `[CHECKS]` / `[STATS]` sections. Each check prints `[N] ✓ name`, with `⚠ … — fixing…` → `✓ fixed` on auto-fix and `✗ Could not fix: …` on hard failure. The run ends with a `Summary` block (checks count, duration, passed/failed, and any failing checks with detail lines). The `bem-config` check lists the missing `backend-manager-config.json` keys as a bulleted list and surfaces a compact version in the summary.
+
+### Fixed
+
+- **No more `UnhandledPromiseRejection` crash on setup failure.** Previously an unfixable check (e.g. missing config keys) rejected a promise with no reason, which bubbled out of the un-`catch`'d `bin/backend-manager` IIFE as Node's raw `UnhandledPromiseRejection: undefined` dump (exit non-zero, lost message). Setup now exits cleanly via `haltSetup()` → `process.exit(1)` after printing the styled summary, and `bin/backend-manager` wraps the run in a `try/catch` that prints a one-line `✗ <message>` backstop. The early-exit guards (missing `functions/package.json`, wrong directory) now print styled errors and exit `1` instead of `0`.
+- **`.env` merge no longer scrambles keys under the wrong headers.** The `has correct .env file` / `has correct .gitignore` setup checks (`env-file.js`, `gitignore.js`) imported a SECOND, **positional** merge implementation in `src/cli/commands/setup-tests/helpers/merge-line-files.js` that zipped comment lines and value lines by index — so any drift between the consumer's key order and the template shifted every value down a slot (the last key of each group landed under the next group's header), dropped newly-added template keys, and duplicated keys. That duplicate is **deleted**; the helper is now a thin SSOT shim re-exporting the canonical key-based merge in `src/utils/merge-line-files.js`. The canonical merge also now **promotes** a key from the user's Custom section up into Default (with its value) when the framework template adopts that key, instead of emitting an empty Default line and leaving the value stranded in Custom.
+
 # [5.2.17] - 2026-05-29
 
 ### Added

package/CLAUDE.md

@@ -106,6 +106,7 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 - [docs/file-naming.md](docs/file-naming.md) — naming table for routes, schemas, API commands, events, cron jobs, hooks
 - [docs/common-mistakes.md](docs/common-mistakes.md) — anti-pattern checklist (don't modify Manager internals, always await, increment-before-update, etc.)
 - [docs/key-files.md](docs/key-files.md) — quick lookup for the most-touched files (Manager, helpers, auth events, cron, payment processors, CLI commands)
+- [docs/cli-output.md](docs/cli-output.md) — shared CLI styling module (`src/cli/utils/ui.js`): OMEGA-style banner/dividers/sections/status symbols + the `Summary` block; used by `setup`, adoptable by other commands
 - [docs/environment-detection.md](docs/environment-detection.md) — `assistant.isDevelopment/isProduction/isTesting()`
 - [docs/response-headers.md](docs/response-headers.md) — automatic `bm-properties` header
 
@@ -134,6 +135,6 @@ Deep references live in `docs/`. **Whenever you make a behavioral change, update
 
 ### Testing & CLI
 
-- [docs/testing.md](docs/testing.md) — running, filtering, log files, test types (standalone/suite/group), context object, assertions, auth levels. **All cleanup runs at the START of every run, never at the end.** If you add a test that writes Firestore data, register the collection/namespace in the runner's pre-test wipe list, don't add a trailing cleanup step. Marketing providers (SendGrid/Beehiiv) don't need a special exception — `_test.*` emails are blocked at the validation layer so test signups never reach providers. The `_test.allow_*` carve-out exists only for the live-provider lifecycle test (`test/marketing/consent-lifecycle.js`), which manages its own teardown.
+- [docs/testing.md](docs/testing.md) — running, filtering, log files, test types (standalone/suite/group), context object, assertions, auth levels. **Each test file `module.exports` a `{ description, type, tests }` object — NOT raw Mocha (`describe`/`it`/`beforeEach`); those globals are not injected and the file fails to load. Split tests one-file-per-concern under `test/<area>/`, never one giant `test/test.js`.** **All cleanup runs at the START of every run, never at the end.** If you add a test that writes Firestore data, register the collection/namespace in the runner's pre-test wipe list, don't add a trailing cleanup step. Marketing providers (SendGrid/Beehiiv) don't need a special exception — `_test.*` emails are blocked at the validation layer so test signups never reach providers. The `_test.allow_*` carve-out exists only for the live-provider lifecycle test (`test/marketing/consent-lifecycle.js`), which manages its own teardown.
 - [docs/cli-firestore-auth.md](docs/cli-firestore-auth.md) — `npx mgr firestore:*` and `auth:*` commands, shared flags, examples
 - [docs/cli-logs.md](docs/cli-logs.md) — `npx mgr logs:read` / `logs:tail` with full flag reference and built-in Cloud Function names

package/bin/backend-manager

@@ -2,5 +2,14 @@
 let Main = new (require('../src/cli/index.js'))(process.argv);
 (async function() {
   'use strict';
-  await Main.process(process.argv);
+  try {
+    await Main.process(process.argv);
+  } catch (e) {
+    // Print a clean one-line error instead of Node's raw UnhandledPromiseRejection
+    // dump. Commands that intend a hard stop should `process.exit(1)` themselves
+    // (e.g. setup's haltSetup); this is the catch-all backstop.
+    const chalk = require('chalk').default;
+    console.error(chalk.red(`\n✗ ${e && e.message ? e.message : e}`));
+    process.exit(1);
+  }
 }());

package/docs/cli-output.md

@@ -0,0 +1,122 @@
+# CLI Output Styling (`src/cli/utils/ui.js`)
+
+BEM's CLI shares a single styling module so every command renders with the same
+look as the **OMEGA Manager** (`omega-manager`): `🚀` banner, 70-char `━`
+dividers, indented tree output, dimmed labels, timestamps, and a consistent set
+of status symbols. This is the **SSOT for console output** — commands should pull
+helpers from here instead of hand-rolling `chalk` + `console.log`.
+
+The module is exposed on every command as `this.ui` (wired in
+[`src/cli/commands/base-command.js`](../src/cli/commands/base-command.js)) and can
+also be `require('../utils/ui')`'d directly (e.g. from setup-test files).
+
+## Conventions
+
+| Aspect | Value |
+|---|---|
+| Divider | `━` × 70 (`ui.RULE_WIDTH`, `ui.RULE_CHAR`) |
+| Indentation | 2 spaces per level (`ui.indent(level)`) |
+| Section label | `[UPPERCASE]` in bold magenta, at indent level 1 |
+| Section items | one level deeper than the label (level 2) |
+| Timestamp | `new Date().toLocaleTimeString()` (e.g. `7:47:12 PM`) |
+| Banner | bold cyan, prefixed with `🚀` |
+
+### Status symbols (`ui.SYMBOLS`)
+
+| Key | Symbol | Color | Meaning |
+|---|---|---|---|
+| `running` | `→` | dim | step in progress / hint |
+| `pass` | `✓` | green | success |
+| `fail` | `✗` | red | failure |
+| `skip` | `⊘` | dim | skipped / no-op |
+| `warn` | `⚠` | yellow | warning |
+| `done` | `✅` | green | final success (summary) |
+| `add` | `+` | green | created a file/record |
+| `change` | `↻` | yellow | modified a file/record |
+
+## API
+
+```js
+const ui = require('../utils/ui'); // or this.ui inside a command
+
+ui.banner('Backend Manager v5.2.18');          // 🚀 bold-cyan banner + blank lines
+ui.header('Somiibo', { subtitle: url });        // ━ divider / title @ time / ━ divider
+ui.section('Checks');                            // blank line + bold-magenta [CHECKS]
+ui.field('Project', 'somiibo-91d13', { pad: 9 });// dimmed "Label:" + value (pad aligns columns)
+ui.status('pass', 'Stats fetched', { level: 2 });// <symbol> <text> at an indent level
+ui.note('All defaults up to date', 2);           // dimmed line at a level
+ui.blank();                                      // blank line
+ui.rule();                                       // a bare 70-char rule string (cyan)
+```
+
+`ui.header(title, opts)`:
+- `opts.subtitle` — text after the title (default cyan), e.g. a URL.
+- `opts.subtitleColor` — chalk fn for the subtitle.
+- `opts.time` — append `@ <time>` (default `true`).
+- `opts.color` — chalk fn for the rules (default cyan).
+
+`ui.field(label, value, opts)`:
+- `opts.level` — indent level (default 1).
+- `opts.pad` — pad the label (incl. colon) to this width for column alignment.
+- `opts.valueColor` — chalk fn for the value.
+
+`ui.status(kind, text, opts)`:
+- `kind` — one of `running|pass|fail|skip|warn|add|change` (picks symbol + color).
+- `opts.level` — indent level (default 1).
+- `opts.detail` — dimmed trailing detail string.
+
+### `ui.Summary`
+
+Collects pass/fail outcomes and prints an OMEGA-style summary block (green `✅`
+when all passed, yellow `⚠` otherwise).
+
+```js
+const summary = new ui.Summary().start();
+summary.pass();                       // record a pass
+summary.fail('check name', detailsArr);// record a fail with pre-formatted detail lines
+summary.print({ hint: 'Fix the above, then run npx mgr setup again.' });
+```
+
+`fail()`'s second arg is an array of already-styled lines shown indented under the
+failing check in the summary block.
+
+## How `setup` uses it
+
+[`src/cli/commands/setup.js`](../src/cli/commands/setup.js) builds the whole run
+from these helpers:
+
+1. `ui.banner(...)` → `ui.header(brand, { subtitle: consoleUrl })` → `ui.field('Project'/'API', ...)`.
+2. `ui.section('Defaults')` then `ui.status('add'|'change', ...)` per scaffolded file.
+3. `ui.section('Checks')` then the per-check status lines (printed by the test
+   runner — see below), with `✓ fixed` / `✗ Could not fix` sub-lines.
+4. `ui.section('Stats')` then a pass/skip/warn line.
+5. `self.setupSummary.print()` on success.
+
+### Test runner (`Main.prototype.test` in `src/cli/index.js`)
+
+Each setup check prints `    [N] <symbol> <name>`. A check can:
+- **pass** → `✓` (recorded via `setupSummary.pass()`).
+- **fail then auto-fix** → `⚠ … — fixing…` then `✓ fixed`.
+- **fail unfixably** → `✗ Could not fix: <message>`, recorded via
+  `setupSummary.fail(name, details)`, then `haltSetup()` prints the summary and
+  `process.exit(1)`.
+
+A failing check's `fix()` may attach `error.summaryDetails` (an array of styled
+lines) to surface a compact version in the summary block — see
+[`setup-tests/bem-config.js`](../src/cli/commands/setup-tests/bem-config.js),
+which lists the missing `backend-manager-config.json` keys.
+
+`--continue` records the failure but keeps going instead of halting.
+
+> **No more `UnhandledPromiseRejection`.** Hard failures exit cleanly via
+> `haltSetup()` / `process.exit(1)`, and `bin/backend-manager` wraps the run in a
+> `try/catch` that prints a one-line `✗ <message>` instead of Node's raw rejection
+> dump.
+
+## Adopting it in other commands
+
+`serve`, `deploy`, `test`, `emulator`, etc. can migrate to the same look
+incrementally: replace ad-hoc `console.log(chalk...)` with `this.ui.section(...)`,
+`this.ui.status(...)`, and `this.ui.field(...)`. The legacy
+`log/logError/logSuccess/logWarning` helpers on `BaseCommand` still work for
+simple one-off lines.

package/docs/testing.md

@@ -118,13 +118,15 @@ npx mgr test user/ admin/       # Multiple paths
 
 ## Test Locations
 
-- **BEM core tests:** `test/`
-- **Project tests:** `functions/test/bem/`
+- **BEM core tests:** `test/` (in the framework repo)
+- **Project tests:** the consumer project's repo-root `test/` directory (NOT inside `functions/`)
 
-Use `bem:` or `project:` prefix to filter by source.
+Use `bem:` or `project:` prefix to filter by source. Mirror BEM's own per-area layout — **one file per concern** under `test/<area>/` (e.g. `test/article/allocation.js`, `test/article/markdown.js`, `test/article/generate.js`), never one giant `test/test.js`. The runner discovers files by directory, so the split is also what the `project:<path>` filter targets (`npx mgr test project:article`).
 
 ## Test Types
 
+> **The runner reads each file's `module.exports` object — it does NOT inject Mocha/Jest globals.** A test file that calls `describe`/`it`/`before`/`beforeEach`/`after` at top level throws `ReferenceError: beforeEach is not defined` and shows as `Failed to load`. There is no global `assert` either — use the `assert` passed into `run({ assert })`. Every test file MUST export one of the shapes below.
+
 | Type | Use When | Behavior |
 |------|----------|----------|
 | Standalone | Single logical test | Runs once |

package/package.json

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

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

@@ -3,6 +3,7 @@ const { confirm } = require('@inquirer/prompts');
 const { execSync, spawn } = require('child_process');
 const path = require('path');
 const jetpack = require('fs-jetpack');
+const ui = require('../utils/ui');
 
 class BaseCommand {
   constructor(main) {
@@ -10,6 +11,9 @@ class BaseCommand {
     this.firebaseProjectPath = main.firebaseProjectPath;
     this.argv = main.argv;
     this.options = main.options;
+    // Shared OMEGA-style CLI styling helpers (dividers, headers, status lines).
+    // See src/cli/utils/ui.js. Use `this.ui.*` in any command for consistent output.
+    this.ui = ui;
   }
 
   async execute() {

package/src/cli/commands/setup-tests/bem-config.js

@@ -38,31 +38,44 @@ class BemConfigTest extends BaseTest {
   }
 
   async fix() {
-    console.log(chalk.red(`There is no automatic fix for this check.`));
-    console.log(chalk.red(`You need to open backend-manager-config.json and set each of these keys:`));
+    const ui = require('../../utils/ui');
 
     // Write if it doesn't exist
     if (!this.context.hasContent(this.self.bemConfigJSON)) {
       jetpack.write(`${this.self.firebaseProjectPath}/functions/backend-manager-config.json`, {});
     }
 
-    // Log what keys are missing
+    // Collect the keys that are still missing (these are what the user must fill in).
+    const missing = [];
     powertools.getKeys(bemConfigTemplate).forEach((key) => {
       // Skip if an ancestor is explicitly set to a non-object value (e.g. stripe: false)
       if (this._isAncestorDisabled(key)) {
         return;
       }
-
       const userValue = _.get(this.self.bemConfigJSON, key, undefined);
-
       if (typeof userValue === 'undefined') {
-        console.log(chalk.red.bold(`${key}`));
-      } else {
-        console.log(chalk.red(`${key} (${userValue})`));
+        missing.push(key);
       }
     });
 
-    throw new Error('Missing required backend-manager-config.json keys');
+    ui.note(`Open ${chalk.bold('backend-manager-config.json')} and set the missing keys below:`, 3);
+    for (const key of missing) {
+      console.log(`${ui.indent(4)}${chalk.red('•')} ${key}`);
+    }
+
+    // Surface a compact version in the summary block (the full list printed above).
+    const preview = missing.slice(0, 8);
+    const summaryDetails = [
+      chalk.dim(`Set ${chalk.bold(missing.length)} missing key(s) in backend-manager-config.json:`),
+      ...preview.map((key) => `${chalk.red('•')} ${key}`),
+    ];
+    if (missing.length > preview.length) {
+      summaryDetails.push(chalk.dim(`…and ${missing.length - preview.length} more (see list above)`));
+    }
+
+    const error = new Error('Missing required backend-manager-config.json keys');
+    error.summaryDetails = summaryDetails;
+    throw error;
   }
   /**
    * Check if any ancestor of a dot-notation key is a non-object value (e.g. false)

package/src/cli/commands/setup-tests/helpers/merge-line-files.js

@@ -1,181 +1,35 @@
 /**
- * Smart merge for line-based files (.gitignore, .env)
- * Preserves custom values while updating defaults
+ * SSOT shim for line-based file merging (.env / .gitignore / CLAUDE.md).
+ *
+ * The real merge logic lives in `src/utils/merge-line-files.js` — a key-based
+ * merge that keeps each KEY under its template header and promotes/migrates keys
+ * between the Default/Custom sections correctly. This file used to contain a
+ * SECOND, positional implementation that zipped comment lines and value lines by
+ * index; an off-by-one there is what historically scrambled consumers' `.env`
+ * files. That duplicate is gone — this module now just re-exports the canonical
+ * impl and adds the marker-name aliases + `hasSectionMarkers()` the setup tests
+ * (`env-file.js`, `gitignore.js`) consume.
  */
 
-const DEFAULT_SECTION_MARKER = '# ========== Default Values ==========';
-const CUSTOM_SECTION_MARKER = '# ========== Custom Values ==========';
-
-/**
- * Merge line-based files with smart Default/Custom section handling
- * @param {string} existingContent - Current file content
- * @param {string} newContent - New template content
- * @param {string} fileName - File name (.env or .gitignore)
- * @returns {string} Merged content
- */
-function mergeLineBasedFiles(existingContent, newContent, fileName) {
-  const existingLines = existingContent.split('\n');
-  const newLines = newContent.split('\n');
-
-  const isEnvFile = fileName === '.env';
-
-  // Parse existing file into default section and custom section
-  let defaultSection = [];
-  let customSection = [];
-  let inCustomSection = false;
-  let inDefaultSection = false;
-
-  const existingDefaultKeys = new Set();
-  const existingCustomKeys = new Set();
-
-  for (const line of existingLines) {
-    const trimmed = line.trim();
-
-    if (trimmed === DEFAULT_SECTION_MARKER) {
-      inDefaultSection = true;
-      inCustomSection = false;
-      continue;
-    }
-    if (trimmed === CUSTOM_SECTION_MARKER) {
-      inCustomSection = true;
-      inDefaultSection = false;
-      continue;
-    }
-
-    if (inCustomSection) {
-      customSection.push(line);
-      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
-        const key = trimmed.split('=')[0].trim();
-        if (key) {
-          existingCustomKeys.add(key);
-        }
-      }
-    } else if (inDefaultSection) {
-      defaultSection.push(line);
-      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
-        const key = trimmed.split('=')[0].trim();
-        if (key) {
-          existingDefaultKeys.add(key);
-        }
-      }
-    }
-  }
-
-  // Parse new content to build complete default section
-  const newDefaultSection = [];
-  const newDefaultKeys = new Set();
-
-  let inNewDefaultSection = false;
-  let inNewCustomSection = false;
-
-  for (const line of newLines) {
-    const trimmed = line.trim();
-
-    if (trimmed === DEFAULT_SECTION_MARKER) {
-      inNewDefaultSection = true;
-      inNewCustomSection = false;
-      continue;
-    }
-    if (trimmed === CUSTOM_SECTION_MARKER) {
-      inNewCustomSection = true;
-      inNewDefaultSection = false;
-      continue;
-    }
-
-    if (inNewDefaultSection) {
-      if (isEnvFile && trimmed && !trimmed.startsWith('#')) {
-        const key = trimmed.split('=')[0].trim();
-        if (key) {
-          newDefaultKeys.add(key);
-          if (!existingDefaultKeys.has(key) && !existingCustomKeys.has(key)) {
-            newDefaultSection.push(line);
-          } else {
-            newDefaultSection.push(null); // Placeholder
-          }
-        } else {
-          newDefaultSection.push(line);
-        }
-      } else {
-        newDefaultSection.push(line);
-      }
-    }
-  }
-
-  // Merge user's existing default values in the correct order
-  const mergedDefaultSection = [];
-  let defaultSectionIndex = 0;
-
-  for (const line of newDefaultSection) {
-    if (line === null) {
-      while (defaultSectionIndex < defaultSection.length) {
-        const userLine = defaultSection[defaultSectionIndex++];
-        const trimmed = userLine.trim();
-        if (trimmed && !trimmed.startsWith('#')) {
-          mergedDefaultSection.push(userLine);
-          break;
-        }
-      }
-    } else {
-      mergedDefaultSection.push(line);
-    }
-  }
-
-  // Find user-added lines in default section that aren't in new defaults
-  const userAddedToDefaults = [];
-
-  for (const line of defaultSection) {
-    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)) {
-        userAddedToDefaults.push(line);
-      }
-    } else {
-      const lineExistsInNewDefaults = newLines.some(newLine => {
-        return newLine.trim() === trimmed;
-      });
-
-      if (!lineExistsInNewDefaults) {
-        userAddedToDefaults.push(line);
-      }
-    }
-  }
-
-  // Build final result
-  const result = [];
-
-  result.push(DEFAULT_SECTION_MARKER);
-  result.push(...mergedDefaultSection);
-
-  result.push('');
-  result.push(CUSTOM_SECTION_MARKER);
-
-  if (userAddedToDefaults.length > 0) {
-    result.push(...userAddedToDefaults);
-  }
-
-  result.push(...customSection);
-
-  return result.join('\n');
-}
+const {
+  mergeLineBasedFiles,
+  DEFAULT_MARKER,
+  CUSTOM_MARKER,
+} = require('../../../../utils/merge-line-files.js');
 
 /**
- * Check if file has proper section markers
- * @param {string} content - File content
+ * Check if a file already has the Default/Custom section markers.
+ * @param {string} content
  * @returns {boolean}
  */
 function hasSectionMarkers(content) {
-  return content.includes(DEFAULT_SECTION_MARKER) && content.includes(CUSTOM_SECTION_MARKER);
+  return content.includes(DEFAULT_MARKER) && content.includes(CUSTOM_MARKER);
 }
 
 module.exports = {
   mergeLineBasedFiles,
   hasSectionMarkers,
-  DEFAULT_SECTION_MARKER,
-  CUSTOM_SECTION_MARKER,
-};
+  // Names the setup tests import (aliases of the canonical markers).
+  DEFAULT_SECTION_MARKER: DEFAULT_MARKER,
+  CUSTOM_SECTION_MARKER: CUSTOM_MARKER,
+};