backend-manager 5.2.18 → 5.3.0

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,
+};

package/src/cli/commands/setup.js

@@ -11,6 +11,7 @@ const bem_allRulesRegex = /(\/\/\/---backend-manager---\/\/\/)(.*?)(\/\/\/------
 class SetupCommand extends BaseCommand {
   async execute() {
     const self = this.main;
+    const ui = this.ui;
 
     // Load config
     await this.loadConfig();
@@ -24,7 +25,7 @@ class SetupCommand extends BaseCommand {
       attempt++;
 
       if (maxAttempts > 1) {
-        this.logSuccess(`\n==== SETUP ATTEMPT ${attempt}/${maxAttempts} ====`);
+        ui.section(`Attempt ${attempt}/${maxAttempts}`);
       }
 
       // Reset counters so each attempt starts fresh
@@ -35,16 +36,13 @@ class SetupCommand extends BaseCommand {
 
       const allPassed = self.testCount === self.testTotal;
       if (allPassed) {
-        if (maxAttempts > 1 && attempt > 1) {
-          this.logSuccess(`\nAll checks passed on attempt ${attempt}/${maxAttempts}.`);
-        }
         return;
       }
 
       if (attempt < maxAttempts) {
-        this.logWarning(`\nAttempt ${attempt}/${maxAttempts} had failures. Retrying...`);
+        ui.status('warn', `Attempt ${attempt}/${maxAttempts} had failures — retrying…`);
       } else if (maxAttempts > 1) {
-        this.logWarning(`\nReached retry limit (${maxAttempts}). Some checks still failing.`);
+        ui.status('warn', `Reached retry limit (${maxAttempts}) — some checks still failing`);
       }
     }
   }
@@ -61,9 +59,15 @@ class SetupCommand extends BaseCommand {
 
   async runSetup() {
     const self = this.main;
+    const ui = this.ui;
     let cwd = jetpack.cwd();
 
-    this.logSuccess(`\n---- RUNNING SETUP v${self.default.version} ----`);
+    // OMEGA-style banner. Replaces the old `---- RUNNING SETUP ---- ` line.
+    ui.banner(`Backend Manager ${chalk.dim(`v${self.default.version}`)}`);
+
+    // Fresh summary collector for this run (the test runner records into it and
+    // prints it on a hard failure; we print it here on success).
+    self.setupSummary = new ui.Summary().start();
 
     // Load files
     self.package = loadJSON(`${self.firebaseProjectPath}/functions/package.json`);
@@ -76,14 +80,16 @@ class SetupCommand extends BaseCommand {
 
     // Check if package exists
     if (!hasContent(self.package)) {
-      this.logError(`Missing functions/package.json :(`);
-      return;
+      ui.status('fail', `Missing ${chalk.bold('functions/package.json')}`);
+      ui.note(`Run ${chalk.bold('npx mgr setup')} from inside the ${chalk.bold('functions')} folder of a Firebase project.`);
+      process.exit(1);
     }
 
     // Check if we're running from the functions folder
     if (!cwd.endsWith('functions') && !cwd.endsWith('functions/')) {
-      this.logError(`Please run ${chalk.bold('npx bm setup')} from the ${chalk.bold('functions')} folder. Run ${chalk.bold('cd functions')}.`);
-      return;
+      ui.status('fail', `Wrong directory`);
+      ui.note(`Run ${chalk.bold('npx mgr setup')} from the ${chalk.bold('functions')} folder. Try ${chalk.bold('cd functions')} first.`);
+      process.exit(1);
     }
 
     // Load the rules files
@@ -96,9 +102,12 @@ class SetupCommand extends BaseCommand {
     self.projectUrl = `https://console.firebase.google.com/project/${self.projectId}`;
     self.apiUrl = `https://api.${(self.bemConfigJSON.brand?.url || '').replace(/^https?:\/\//, '')}`;
 
-    // Log
-    this.log(`ID: `, chalk.bold(`${self.projectId}`));
-    this.log(`URL:`, chalk.bold(`${self.projectUrl}`));
+    // Divider-wrapped header with the project name + Firebase console link.
+    const brandName = self.bemConfigJSON.brand?.name || self.projectId;
+    ui.header(brandName, { subtitle: self.projectUrl });
+    ui.blank();
+    ui.field('Project', self.projectId, { pad: 9 });
+    ui.field('API', self.apiUrl, { pad: 9, valueColor: chalk.cyan });
 
     if (!self.package || !self.package.engines || !self.package.engines.node) {
       throw new Error('Missing <engines.node> in package.json');
@@ -109,26 +118,26 @@ class SetupCommand extends BaseCommand {
 
     // 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.
+    ui.section('Defaults');
     this.copyDefaults();
 
     // Run all tests
+    ui.section('Checks');
     await this.runTests();
 
-    // Log if using local backend-manager
+    // Warn if using local backend-manager
     if (self.package.dependencies['backend-manager'].includes('file:')) {
-      this.log('\n' + chalk.yellow(chalk.bold('Warning: ') + 'You are using the local ' + chalk.bold('backend-manager')));
-    } else {
-      this.log('\n');
+      ui.section('Notices');
+      ui.status('warn', `Using the local ${chalk.bold('backend-manager')} source (file: dependency)`, { level: 2 });
     }
 
     // Fetch stats
+    ui.section('Stats');
     await this.fetchStats();
 
-    // Log results
-    this.logSuccess(`Checks finished. Passed ${self.testCount}/${self.testTotal} tests.`);
-    if (self.testCount !== self.testTotal) {
-      this.logWarning(`You should continue to run ${chalk.bold('npx bm setup')} until you pass all tests and fix all errors.`);
-    }
+    // Everything passed (a hard failure would have exited via haltSetup). Print
+    // the OMEGA-style summary block.
+    self.setupSummary.print();
 
     // Notify parent if exists
     if (process.send) {
@@ -162,10 +171,12 @@ class SetupCommand extends BaseCommand {
   //   # ========== Custom Values ==========    (consumer-owned)
   copyDefaults() {
     const self = this.main;
+    const ui = this.ui;
     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.
+      ui.note('No defaults to scaffold', 2);
       return;
     }
 
@@ -175,16 +186,23 @@ class SetupCommand extends BaseCommand {
     // matches the EM/BXM/UJM contract if we ever add them.
     const MERGEABLE_BASENAMES = new Set(['.env', '.gitignore', 'CLAUDE.md']);
 
+    // Track whether we emitted any line so we can show an "up to date" note when nothing changed.
+    let touched = 0;
+
     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('_.'))) {
+      // Skip "archive" DIRECTORIES — any non-final path segment starting with `_` and
+      // followed by a non-`.` character (e.g. `_legacy/`). Matches EM/BXM/UJM convention.
+      // The check is restricted to directory segments (all but the last) so a `_`-prefixed
+      // FILENAME still ships — e.g. `test/_init.js` copies verbatim (the test runner skips
+      // it from discovery on its own). The `_.env` / `_.gitignore` files are likewise not
+      // skipped; their leading `_` strips on copy below.
+      const dirSegments = segments.slice(0, -1);
+      if (dirSegments.some((s) => s.startsWith('_') && !s.startsWith('_.'))) {
         continue;
       }
 
@@ -201,10 +219,12 @@ class SetupCommand extends BaseCommand {
             const merged   = mergeLineBasedFiles(existing, incoming, basename);
             if (merged !== existing) {
               jetpack.write(dest, merged);
-              this.logSuccess(`Merged default → ${target}`);
+              ui.status('change', `Merged ${chalk.cyan(target)}`, { level: 2 });
+              touched++;
             }
           } catch (e) {
-            this.logWarning(`Failed to merge ${target}: ${e.message}`);
+            ui.status('warn', `Failed to merge ${chalk.cyan(target)}`, { detail: e.message, level: 2 });
+            touched++;
           }
           continue;
         }
@@ -215,7 +235,12 @@ class SetupCommand extends BaseCommand {
 
       // First time: copy as-is.
       jetpack.copy(src, dest);
-      this.logSuccess(`Copied default → ${target}`);
+      ui.status('add', `Copied ${chalk.cyan(target)}`, { level: 2 });
+      touched++;
+    }
+
+    if (touched === 0) {
+      ui.note('All defaults up to date', 2);
     }
   }
 
@@ -253,6 +278,10 @@ class SetupCommand extends BaseCommand {
     // Get all tests
     const tests = testRegistry.getTests(testContext);
 
+    // Expose the total count so the per-check `[N]` prefix can right-align its
+    // width (single- vs double-digit indices stay aligned).
+    self.testTotalExpected = tests.length;
+
     // Run each test
     for (const test of tests) {
       await self.test(
@@ -281,12 +310,15 @@ class SetupCommand extends BaseCommand {
     .then(json => json)
     .catch(e => e);
 
+    const ui = this.ui;
     if (statsFetchResult instanceof Error) {
-      if (!statsFetchResult.message.includes('network timeout')) {
-        this.logWarning(`Ran into error while fetching stats endpoint (${url})`, statsFetchResult);
+      if (statsFetchResult.message.includes('network timeout')) {
+        ui.status('skip', 'Skipped stats fetch', { detail: 'network timeout', level: 2 });
+      } else {
+        ui.status('warn', 'Could not fetch stats endpoint', { detail: statsFetchResult.message, level: 2 });
       }
     } else {
-      this.logSuccess(`Stats fetched/created properly.`);
+      ui.status('pass', 'Stats fetched/created', { level: 2 });
     }
   }
 }

package/src/cli/commands/test.js

@@ -36,7 +36,7 @@ class TestCommand extends BaseCommand {
       const envSubset = captureSyncedEnv(process.env);
       writeTestMode(projectDir, envSubset);
       const extended = !!process.env.TEST_EXTENDED_MODE;
-      this.log(chalk.gray(`  Test mode: ${extended ? 'EXTENDED (real APIs)' : 'normal (mocked)'}`));
+      this.log(chalk.gray(`  Test mode: ${extended ? 'extended (real external APIs)' : 'normal (external APIs skipped)'}`));
     }
 
     // Load emulator ports from firebase.json

package/src/cli/index.js

@@ -164,47 +164,80 @@ Main.prototype.process = async function (args) {
 // Test method for setup command
 Main.prototype.test = async function(name, fn, fix, args) {
   const self = this;
-  let status;
   const chalk = require('chalk').default;
-
-  return new Promise(async function(resolve, reject) {
-    let passed = await fn();
-
-    if (passed instanceof Error) {
-      console.log(chalk.red(passed));
-      process.exit(0);
-    } else if (passed) {
-      status = chalk.green('passed');
-      self.testCount++;
-      self.testTotal++;
-    } else {
-      status = chalk.red('failed');
-      self.testTotal++;
-    }
-    console.log(chalk.bold(`[${self.testTotal}]`), `${name}:`, status);
-    if (!passed) {
-      console.log(chalk.yellow(`Fixing...`));
-      fix(self, args)
-      .then((r) => {
-        console.log(chalk.green(`...done~!`));
-        resolve();
-      })
-      .catch((e) => {
-        console.log(chalk.red(`Failed to fix: ${e}`));
-        if (self.options['--continue']) {
-          console.log(chalk.yellow('⚠️ Continuing despite error because of --continue flag\n'));
-          setTimeout(function () {
-            resolve();
-          }, 5000);
-        } else {
-          console.log(chalk.yellow('To force the setup to continue, run with the --continue flag\n'));
-          reject();
-        }
-      });
-    } else {
-      resolve();
+  const ui = require('./utils/ui');
+
+  // Prints `    [N] <symbol> <name>` — the OMEGA-style per-check status line
+  // (indented one level under the `[CHECKS]` section label). The `[N]` bracket
+  // is padded to the width of the total check count so single- and double-digit
+  // numbers (`[1] ` … `[13]`) keep the symbols/names aligned.
+  const indexWidth = String(self.testTotalExpected || 99).length;
+  const printLine = (index, kind, label) => {
+    const colorByKind = { pass: chalk.green, fail: chalk.red, warn: chalk.yellow };
+    const color = colorByKind[kind] || chalk.white;
+    const suffix = label ? ` ${chalk.dim(label)}` : '';
+    const bracket = `[${index}]`.padEnd(indexWidth + 2, ' ');
+    console.log(`${ui.indent(2)}${chalk.dim(bracket)} ${color(ui.SYMBOLS[kind])} ${name}${suffix}`);
+  };
+
+  let passed = await fn();
+
+  // A check that returns an Error is a hard, unrecoverable failure (e.g. wrong
+  // Node version). Print it cleanly and stop — no auto-fix is possible.
+  if (passed instanceof Error) {
+    self.testTotal++;
+    printLine(self.testTotal, 'fail', '');
+    const message = passed.message || String(passed);
+    ui.status('fail', chalk.red(message), { level: 3 });
+    if (self.setupSummary) { self.setupSummary.fail(name, [chalk.red(message)]); }
+    self.haltSetup();
+    return;
+  }
+
+  if (passed) {
+    self.testCount++;
+    self.testTotal++;
+    if (self.setupSummary) { self.setupSummary.pass(); }
+    printLine(self.testTotal, 'pass', '');
+    return;
+  }
+
+  // Failed → attempt a fix.
+  self.testTotal++;
+  printLine(self.testTotal, 'warn', '— fixing…');
+
+  try {
+    await fix(self, args);
+    self.testCount++;
+    if (self.setupSummary) { self.setupSummary.pass(); }
+    ui.status('pass', chalk.green('fixed'), { level: 3 });
+  } catch (e) {
+    // The fix couldn't complete. `e.summaryDetails` (if present) is an array of
+    // pre-formatted detail lines the failing check wants surfaced in the summary.
+    const message = e && e.message ? e.message : String(e);
+    const details = (e && Array.isArray(e.summaryDetails)) ? e.summaryDetails : [chalk.red(message)];
+    ui.status('fail', chalk.red(`Could not fix: ${message}`), { level: 3 });
+    if (self.setupSummary) { self.setupSummary.fail(name, details); }
+
+    if (self.options['--continue']) {
+      ui.status('warn', chalk.yellow('Continuing despite error (--continue flag)'), { level: 3 });
+      return;
     }
-  });
+
+    self.haltSetup();
+  }
+};
+
+// Halt the setup run on an unfixable failure. The failing check must already be
+// recorded via `setupSummary.fail(...)` by the caller; this prints the summary
+// block + a re-run hint and exits with code 1 — instead of rejecting a promise
+// with no reason (which surfaced as an ugly `UnhandledPromiseRejection: undefined`).
+Main.prototype.haltSetup = function() {
+  if (this.setupSummary) {
+    this.setupSummary.print({ hint: `Fix the above, then run ${require('chalk').default.bold('npx mgr setup')} again.` });
+  }
+
+  process.exit(1);
 };
 
 module.exports = Main;