browser-extension-manager 1.4.0 → 1.6.0

package/README.md

@@ -61,8 +61,14 @@ BXM ships a built-in four-layer test framework. Write tests under `test/<layer>/
 npx bxm test                   # all layers
 npx bxm test --layer build     # build layer only (plain Node, fast)
 npx bxm test --layer boot      # real-Chromium end-to-end test
+npx bxm test project:          # ONLY your project's tests (mgr: → only framework tests)
+npx bxm test --extended        # also run extended suites against REAL external services (Firebase, etc.)
 ```
 
+Tests run against the **real** harness — a real MV3 service worker, a real Chromium tab, the real packaged extension. **Never mock** (`chrome`, the Manager, contexts are all real); only pure, I/O-free functions are called directly. Real external APIs are gated behind **extended mode** — `--extended` or the shared, unprefixed `TEST_EXTENDED_MODE=true` env var (skipped in-source otherwise, never mocked).
+
+All CLI output also lands in `logs/` (ANSI-stripped, truncated each run) — `test.log` from `npx bxm test`, `dev.log` from `npm start`, `build.log` from `npm run build`. Details: [docs/logging.md](docs/logging.md).
+
 Test files use Jest-compatible matchers:
 
 ```js

package/dist/background.js

@@ -513,7 +513,8 @@ class Manager {
 
   // Setup livereload
   setupLiveReload() {
-    // Quit if not in dev mode
+    // Dev-only feature — skip in testing and production (environment is one of
+    // 'development' | 'testing' | 'production').
     if (this.environment !== 'development') return;
 
     // Get port from config or use default

package/dist/build.js

@@ -91,13 +91,8 @@ Manager.actLikeProduction = function () {
 }
 Manager.prototype.actLikeProduction = Manager.actLikeProduction;
 
-// getEnvironment: returns the environment based on the build mode
-Manager.getEnvironment = function () {
-  return Manager.isBuildMode()
-    ? 'production'
-    : 'development';
-}
-Manager.prototype.getEnvironment = Manager.getEnvironment;
+// getEnvironment() is the SSOT and lives in src/utils/mode-helpers.js (alongside the is*()
+// family). It's mixed onto the Manager via the attachTo() call below, same as in EM/UJM.
 
 // getManifest: requires and parses config.yml
 Manager.getManifest = function () {

package/dist/commands/install.js

@@ -17,7 +17,7 @@ module.exports = async function (options) {
 
   try {
     // Install production
-    if (['prod', 'p', 'production'].includes(type)) {
+    if (['live', 'prod', 'p', 'production'].includes(type)) {
       // Log
       logger.log('Installing production...');
 

package/dist/commands/test.js

@@ -4,15 +4,34 @@ const fs      = require('fs');
 const Manager = new (require('../build.js'));
 const logger  = Manager.logger('test');
 const { run } = require('../test/runner.js');
+const attachLogFile = require('../utils/attach-log-file.js');
+const { EXTENDED_MODE_WARNING } = require('../test/utils/extended-mode-warning.js');
 
 module.exports = async function (options) {
+  // Tee all test output to <projectRoot>/logs/test.log (ANSI-stripped) — mirrors
+  // EM's test.log and BEM's test.log pattern.
+  attachLogFile(path.join(process.cwd(), 'logs', 'test.log'));
+
   const layer       = options.layer    || 'all';
+  // Positional target: `npx mgr test <target>` where target supports source
+  // prefixes — `project:`, `project:<path>`, `mgr:`, `bxm:`, or a bare `<path>`.
+  const target      = (options._ && options._[1]) || null;
+  // `--filter` flag: substring match on test NAMES/descriptions (orthogonal to target).
   const filter      = options.filter   || null;
   const reporter    = options.reporter || 'pretty';
-  const integration = options.integration === true || options.integration === 'true';
+  // Extended mode — opt into tests that hit REAL external services (Firebase via web-manager,
+  // push, any network call) instead of skipping them. Off by default so `npx mgr test` stays
+  // fast and offline-safe. The canonical signal is the unprefixed `TEST_EXTENDED_MODE` env var
+  // — the SAME name across BEM/BXM/UJM/EM (cross-framework parity); `--extended` is the CLI
+  // shorthand. Once set on process.env it propagates to every spawned test environment (the
+  // in-process Node runner, and Puppeteer's Chromium which inherits process.env).
+  const extended    = options.extended === true
+    || options.extended === 'true'
+    || process.env.TEST_EXTENDED_MODE === 'true'
+    || process.env.TEST_EXTENDED_MODE === '1';
 
-  if (integration) {
-    process.env.BXM_TEST_INTEGRATION = '1';
+  if (extended) {
+    process.env.TEST_EXTENDED_MODE = 'true';
   }
 
   // Canonical signal — every Manager picks this up via isTesting().
@@ -32,10 +51,15 @@ module.exports = async function (options) {
   }
 
   if (reporter !== 'json') {
-    logger.log(`Running tests (layer=${layer}${filter ? ` filter="${filter}"` : ''}${integration ? ' +integration' : ''})`);
+    logger.log(`Running tests (layer=${layer}${target ? ` target="${target}"` : ''}${filter ? ` filter="${filter}"` : ''}${extended ? ' +extended' : ''})`);
+    logger.log(`Test mode: ${extended ? 'extended (real external APIs)' : 'normal (external APIs skipped)'}`);
+    if (extended) {
+      logger.warn(EXTENDED_MODE_WARNING[0]);
+      EXTENDED_MODE_WARNING.slice(1).forEach((line) => logger.warn(line));
+    }
   }
 
-  const result = await run({ layer, filter, reporter });
+  const result = await run({ layer, target, filter, reporter });
 
   if (reporter === 'json') {
     // Final machine-readable summary.
@@ -50,6 +74,11 @@ module.exports = async function (options) {
 
   if (result.failed > 0) {
     process.exitCode = 1;
+    await attachLogFile.detach();
     throw new Error(`${result.failed} test(s) failed`);
   }
+
+  // Flush test.log fully and restore stdout/stderr. Stream writes are async, so
+  // detach() resolves once the buffered tail (the Results block) is on disk.
+  await attachLogFile.detach();
 };

package/dist/defaults/CHANGELOG.md

@@ -0,0 +1,15 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## Changelog Categories
+
+- `BREAKING` for breaking changes.
+- `Added` for new features.
+- `Changed` for changes in existing functionality.
+- `Deprecated` for soon-to-be removed features.
+- `Removed` for now removed features.
+- `Fixed` for any bug fixes.
+- `Security` in case of vulnerabilities.

package/dist/defaults/CLAUDE.md

@@ -1,15 +1,25 @@
 # ========== Default Values ==========
 # Browser Extension Manager (BXM) — consumer project
 
-> **Auto-managed file.** Everything between `# ========== Default Values ==========` and `# ========== Custom Values ==========` is owned by `browser-extension-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 **Browser Extension Manager** (BXM) — a comprehensive framework for building modern cross-browser extensions (Chrome, Firefox, Edge, Opera, Brave). BXM provides one-line bootstrap per extension context, a component-based architecture (view + styles + script per context), a multi-browser build/release pipeline that produces store-uploadable zips, cross-context auth synchronization, and a built-in four-layer test framework.
 
-**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/browser-extension-manager/CLAUDE.md` (or `node_modules/browser-extension-manager/CLAUDE.md`)
-- Subsystem references: `/Users/ian/Developer/Repositories/ITW-Creative-Works/browser-extension-manager/docs/` (or `node_modules/browser-extension-manager/docs/`)
+## 🚨 READ THE FRAMEWORK DOCS FIRST
+
+**Before doing ANY work on this codebase, Claude MUST read the framework documentation — that is where the architecture, conventions, APIs, and gotchas live. Skipping these will result in solutions that conflict with framework patterns.**
+
+**Required reading:**
+- **`node_modules/browser-extension-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/browser-extension-manager/docs/`** — subsystem deep references (read the relevant ones for the task at hand)
+
+## 🚨 READ WEB-MANAGER TOO
+
+**BXM ships `web-manager` as a runtime singleton across every extension context** (background service worker, popup, options, sidepanel, content scripts) — it powers auth, Firebase, reactive `data-wm-bind` directives, analytics, error tracking, and utilities (`escapeHTML`, etc.). Any task that touches auth flows, Firestore reads/writes, subscription resolution, push notifications, or DOM bindings means you are working with web-manager as much as with BXM.
+
+**Required reading:**
+- **`node_modules/web-manager/CLAUDE.md`** — top-level overview + index
+- **`node_modules/web-manager/docs/`** — module deep references (Auth, Bindings, Firestore, Notifications, etc.)
 
 ## Quick start
 
@@ -18,8 +28,19 @@ npm start                   # dev with live reload (gulp → webpack → serve)
 npm run build               # production build → dist/ + packaged/<browser>/raw/ + .zip per browser
 BXM_IS_PUBLISH=true npm run build   # build + auto-upload to Chrome / Firefox / Edge stores
 npx mgr test                # run framework + project test suites
+npx mgr test build/config         # bare path: run tests matching a path in BOTH sources
+npx mgr test project:             # run ONLY your project tests (project:<path> to narrow)
+npx mgr test mgr:                 # run ONLY framework tests (bxm: / framework: are equivalent aliases)
+npx mgr test bxm:build/config     # run only framework tests matching a path
+# Positional target selects which test FILES run; --filter=<substring> matches test NAMES within them
+npx mgr test --extended           # also run tests that hit REAL external services (off by default; TEST_EXTENDED_MODE=true is the env equivalent — shared name across BEM/BXM/UJM/EM)
+# (output is teed to logs/ — dev.log on `npm start`, build.log on `npm run build`, test.log on `npx mgr test`; cat instead of scrolling scrollback)
+npx mgr install dev         # use LOCAL browser-extension-manager source (to test framework edits)
+npx mgr install live        # restore the published browser-extension-manager from npm
 ```
 
+> Editing the BXM framework source while working here? Run `npx mgr install dev` so this project picks up your uncommitted framework changes (it otherwise uses its installed `node_modules/browser-extension-manager`). Run `npx mgr install live` to switch back.
+
 Load the unpacked extension in Chrome: point chrome://extensions → "Load unpacked" at `packaged/chromium/raw/`.
 
 ## Where things live
@@ -57,10 +78,22 @@ After `initialize()`, every Manager exposes:
 - `manager.logger` — timestamped per-context logger
 - `manager.webManager` — Web Manager singleton (Firebase, auth, analytics, reactive `data-wm-bind` directives)
 - `manager.messenger` — `chrome.runtime.onMessage` listener wired automatically
-- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers
+- `manager.isDevelopment()` / `isProduction()` / `isTesting()` / `getVersion()` — cross-context helpers. `getEnvironment()` returns `'development' | 'testing' | 'production'` (mutually exclusive; testing wins). Gate side effects on the intentional check (`isProduction()` for prod-only; `isDevelopment() || isTesting()` for local-or-test) — never `!isDevelopment()`.
 
 Auth UI is declarative — add `.auth-signin-btn` / `.auth-signout-btn` / `.auth-account-btn` to buttons; BXM wires them. Show/hide based on auth state via `data-wm-bind="@show auth.user"`.
 
+## Dependency resolution
+
+- **Do NOT install framework dependencies directly** (`firebase`, `web-manager`, etc.). BXM's webpack config resolves them through the framework's own `node_modules/`. If something doesn't resolve, the issue is in BXM's webpack config — not your `package.json`.
+- **web-manager owns Firebase.** Never `import firebase from 'firebase/app'`. Use `import webManager from 'web-manager'` → `webManager.auth()`, `webManager.firestore()`.
+- **`Manager.require(name)`** resolves from BXM's module context at runtime for unbundled code (gulp tasks, test fixtures).
+
+## Testing
+
+Every feature ships with tests at every layer it has a surface in: **logic** (`test/build/`, `test/background/`), **UI** (`test/view/` — real events on the real DOM), and **end-to-end** (`test/boot/`). Skip a layer only when the feature genuinely has no surface there — "the logic test covers it" does not excuse the UI test. See `test/README.md` and `node_modules/browser-extension-manager/docs/test-framework.md`.
+
+<!-- Everything above this marker is owned by the framework and rewritten on every `npx mgr setup`. Add your project-specific notes below — they are preserved across setups. -->
+
 # ========== Custom Values ==========
 
 ## Project-specific notes

package/dist/defaults/docs/README.md

@@ -0,0 +1,17 @@
+# Project docs
+
+Per-subsystem deep references live here. Keep `CLAUDE.md` short — it should read as a **table of contents** that points at files in this directory.
+
+## Pattern
+
+When you find yourself adding more than a paragraph to `CLAUDE.md`, create a new `docs/<topic>.md` instead and link to it from `CLAUDE.md`. Goal: the project's `CLAUDE.md` stays under ~250 lines.
+
+Examples of good `docs/*.md` topics:
+- Subsystem deep-dives (one per area of the codebase)
+- Architectural decisions / "why we built it this way"
+- Defaults tables, behavior matrices, edge cases
+- Setup walkthroughs that don't belong in `README.md`
+
+## See also
+
+The framework's own docs follow this same pattern — browse `node_modules/browser-extension-manager/docs/` for the canonical examples.

package/dist/defaults/test/README.md

@@ -0,0 +1,38 @@
+# Project tests
+
+Drop your project test suites here. The framework auto-runs them alongside its own when you run `npx mgr test`.
+
+## Layers
+
+Match the framework's four layers — Browser Extension Manager's test runner discovers files by the directory they sit in:
+
+| Directory | Runtime | Use for |
+|---|---|---|
+| `test/build/` | Plain Node | Build-time logic, manifest validation, pure utilities |
+| `test/background/` | MV3 service worker context | Background messaging, auth source-of-truth, alarms |
+| `test/view/` | Popup / options / sidepanel page | DOM, view-side controllers, `data-wm-bind` directives |
+| `test/boot/` | Consumer's actual built extension | End-to-end smoke tests (does the extension load, does the background register, do views render) |
+
+## Coverage
+
+Every feature ships with tests at every layer it has a surface in — logic (`build`/`background`), UI (`view`), end-to-end (`boot`). Skip a layer only when the feature genuinely has no surface there; "the logic test covers it" does not excuse the UI test.
+
+Tests that hit REAL external services (Firebase, push, network) are skipped by default — gate them on `process.env.TEST_EXTENDED_MODE` (`if (process.env.TEST_EXTENDED_MODE !== 'true') ctx.skip('extended mode off');`) and run them with `npx mgr test --extended` (or `TEST_EXTENDED_MODE=true`). `TEST_EXTENDED_MODE` is the shared, unprefixed name across BEM/BXM/UJM/EM. Never mock the external service — skip it in-source.
+
+## Quick example
+
+```js
+// test/build/my-feature.test.js
+const assert = require('browser-extension-manager/test/assert');
+
+module.exports = {
+  'my feature does the thing': async () => {
+    const result = await doTheThing();
+    assert.equal(result, 'expected');
+  },
+};
+```
+
+## See also
+
+`node_modules/browser-extension-manager/docs/test-framework.md` — full reference for the test framework (layers, assert API, fixtures, runner internals).

package/dist/defaults/test/_init.js

@@ -0,0 +1,10 @@
+/**
+ * Test lifecycle hook for this project. Runs once before any suite (not a test itself).
+ * See browser-extension-manager/docs/test-framework.md → "test/_init.js".
+ */
+
+module.exports = ({ projectRoot }) => ({
+  // Seed any fixture a suite needs before it runs.
+  async setup() {
+  },
+});

package/dist/gulp/main.js

@@ -14,6 +14,19 @@ const projectRoot = Manager.getRootPath('project');
 // Load .env file from project root
 require('dotenv').config({ path: path.join(projectRoot, '.env') });
 
+// Tee all stdout/stderr to <projectRoot>/logs/<dev|build>.log for easy `tail -f` / grep / Claude
+// inspection — captures gulp task output, webpack/serve output, console.log calls, the works.
+// build.log for production builds (BXM_BUILD_MODE=true), dev.log for `npm start`.
+// Disable via BXM_LOG_FILE=false. Override path via BXM_LOG_FILE=<path>.
+const attachLogFile = require('../utils/attach-log-file.js');
+const logFileEnv = process.env.BXM_LOG_FILE;
+if (logFileEnv !== 'false' && logFileEnv !== '0') {
+  const defaultName = Manager.isBuildMode() ? 'build.log' : 'dev.log';
+  const logPath = (logFileEnv && logFileEnv !== 'true') ? logFileEnv : path.join(projectRoot, 'logs', defaultName);
+  attachLogFile(logPath);
+  logger.log(`Logs tee'd to ${logPath}`);
+}
+
 // Log
 logger.log('Starting...', argv);
 

package/dist/test/runner.js

@@ -39,16 +39,21 @@ class SkipError extends Error {
 
 async function run(options = {}) {
   options.layer    = options.layer    || 'all';
+  options.target   = options.target   || null;
   options.filter   = options.filter   || null;
   options.reporter = options.reporter || 'pretty';
 
   const startTime = Date.now();
 
-  const sources = discoverTestFiles();
+  const sources = discoverTestFiles(options.target);
 
   console.log('');
   console.log(chalk.bold('  Browser Extension Manager Tests'));
 
+  // Run the optional test/_init.js setup() hooks (framework + consumer) ONCE,
+  // before any suite. There is no cleanup hook — tests clean up after themselves.
+  await runInitSetups();
+
   const results = { passed: 0, failed: 0, skipped: 0, tests: [] };
 
   if (sources.framework.length > 0) {
@@ -356,7 +361,49 @@ function reportResults(results, durationMs) {
   console.log(chalk.gray(`\n    Total: ${total} tests in ${durationMs}ms\n`));
 }
 
-function discoverTestFiles() {
+// Parse a positional test target into a source filter + path part.
+// Source prefixes (standardized across all OMEGA frameworks):
+//   'mgr:' / 'bxm:' / 'framework:' → framework tests  ('mgr:' is the universal alias)
+//   'project:'                     → project tests
+//   no prefix                      → both sources, matched by path
+function parseTarget(target) {
+  if (!target) {
+    return { source: null, pathPart: null };
+  }
+
+  const m = String(target).match(/^(project|mgr|bxm|framework):(.*)$/);
+  if (m) {
+    const source = m[1] === 'project' ? 'project' : 'framework';
+    return { source, pathPart: m[2] || null };
+  }
+
+  return { source: null, pathPart: target };
+}
+
+// Narrow a source's file list by the parsed target. A source-prefixed target
+// excludes the other source entirely; the path part (if any) matches by
+// relative path prefix.
+function filterBySource(source, files, sourceFilter, pathPart) {
+  if (sourceFilter && sourceFilter !== source) {
+    return [];
+  }
+  if (!pathPart) {
+    return files;
+  }
+
+  return files.filter((file) => {
+    const rel = relativizePath(file, source);
+    const relNoExt = rel.replace(/\.js$/, '').replace(/\.test$/, '');
+    const partNoExt = pathPart.replace(/\.js$/, '').replace(/\.test$/, '');
+    return rel.startsWith(pathPart)
+      || relNoExt === partNoExt
+      || relNoExt.startsWith(partNoExt + '/')
+      || rel.includes(pathPart);
+  });
+}
+
+function discoverTestFiles(target) {
+  const { source: sourceFilter, pathPart } = parseTarget(target);
   const framework = [];
   const project = [];
 
@@ -394,7 +441,10 @@ function discoverTestFiles() {
     });
   }
 
-  return { framework, project };
+  return {
+    framework: filterBySource('framework', framework, sourceFilter, pathPart),
+    project:   filterBySource('project',   project,   sourceFilter, pathPart),
+  };
 }
 
 function relativizePath(file, source) {
@@ -404,4 +454,62 @@ function relativizePath(file, source) {
   return path.relative(path.join(process.cwd(), 'test'), file);
 }
 
+// ---------------------------------------------------------------------------
+// test/_init.js — pre-test lifecycle hook (setup only)
+//
+// Mirrors the backend framework's hook so all four frameworks share one shape.
+// A project may add `<cwd>/test/_init.js` exporting a FUNCTION —
+// `module.exports = (ctx) => ({ setup })` — called with `{ projectRoot }` and
+// returning an object with an async `setup({ projectRoot })` that runs ONCE
+// before any suite (e.g. to scaffold a fixture file the boot layer needs).
+// There is no `cleanup` hook: tests clean up after themselves. Unlike the
+// backend framework, there is no `accounts` field here — these frameworks have
+// no auth/user system.
+// ---------------------------------------------------------------------------
+
+function loadInit(testDir, label) {
+  const initPath = path.join(testDir, '_init.js');
+
+  if (!jetpack.exists(initPath)) {
+    return {};
+  }
+
+  try {
+    const fn = require(initPath);
+
+    if (typeof fn !== 'function') {
+      console.log(chalk.red(`  ✗ ${label} test/_init.js must export a function: module.exports = (ctx) => ({ ... })`));
+      return {};
+    }
+
+    const mod = fn({ projectRoot: process.cwd() });
+    return mod && typeof mod === 'object' ? mod : {};
+  } catch (e) {
+    console.log(chalk.red(`  ✗ Failed to load ${label} test/_init.js: ${e.message}`));
+    return {};
+  }
+}
+
+async function runInitSetups() {
+  const frameworkTestsDir = path.resolve(__dirname, '../../test');
+  const projectTestsDir = path.join(process.cwd(), 'test');
+
+  const hooks = [
+    loadInit(frameworkTestsDir, 'framework'),
+    loadInit(projectTestsDir, 'project'),
+  ];
+
+  const setups = hooks.filter((h) => typeof h.setup === 'function').map((h) => h.setup);
+
+  for (const setup of setups) {
+    process.stdout.write(chalk.gray('  Running test/_init.js setup... '));
+    try {
+      await setup({ projectRoot: process.cwd() });
+      console.log(chalk.green('✓'));
+    } catch (e) {
+      console.log(chalk.red(`✗ (${e.message})`));
+    }
+  }
+}
+
 module.exports = { run, SkipError };

package/dist/test/suites/build/attach-log-file.test.js

@@ -0,0 +1,90 @@
+// Build-layer tests for src/utils/attach-log-file.js — tee process.stdout/stderr to a file
+// with ANSI stripping. Each test attaches, writes, detaches, then inspects the file.
+//
+// CRITICAL: these tests run INSIDE a live `npx mgr test` process whose own output is being
+// teed to logs/test.log by the singleton. So they must NOT touch the singleton — exercising
+// attach()/detach() on it would detach the live tee mid-run and truncate logs/test.log. Each
+// test uses its OWN `createTee()` instance, which stacks under the live singleton tee and
+// restores it cleanly on detach.
+
+const path = require('path');
+const fs   = require('fs');
+const os   = require('os');
+
+module.exports = {
+  type: 'suite',
+  layer: 'build',
+  description: 'attach-log-file — tee stdout/stderr to a file',
+  tests: [
+    {
+      name: 'exports the expected surface',
+      run: (ctx) => {
+        const mod = require(path.join(__dirname, '..', '..', '..', 'utils', 'attach-log-file.js'));
+        ctx.expect(typeof mod).toBe('function');
+        ctx.expect(typeof mod.detach).toBe('function');
+        ctx.expect(typeof mod.stripAnsi).toBe('function');
+        ctx.expect(typeof mod.createTee).toBe('function');
+      },
+    },
+    {
+      name: 'stripAnsi removes color escape codes',
+      run: (ctx) => {
+        const { stripAnsi } = require(path.join(__dirname, '..', '..', '..', 'utils', 'attach-log-file.js'));
+        const colored = '\x1B[31mred\x1B[0m and \x1B[32mgreen\x1B[0m';
+        ctx.expect(stripAnsi(colored)).toBe('red and green');
+      },
+    },
+    {
+      name: 'attach + stdout.write + detach: file contains the writes',
+      run: async (ctx) => {
+        const attach = require(path.join(__dirname, '..', '..', '..', 'utils', 'attach-log-file.js'));
+        // Isolated instance — stacks under the live test.log tee, never clobbers it.
+        const tee = attach.createTee();
+        const tmpPath = path.join(os.tmpdir(), `bxm-log-${Date.now()}.log`);
+        try {
+          const stream = tee.attach(tmpPath);
+          process.stdout.write('hello world\n');
+          process.stdout.write('\x1B[31mcolored\x1B[0m line\n');
+          // Wait for stream to flush before detaching + reading.
+          await new Promise((resolve) => stream.write('', resolve));
+          tee.detach();
+          // detach() ends the stream; wait for the close event.
+          await new Promise((resolve) => stream.on('close', resolve));
+
+          const contents = fs.readFileSync(tmpPath, 'utf8');
+          ctx.expect(contents).toContain('hello world');
+          ctx.expect(contents).toContain('colored line');
+          ctx.expect(contents).not.toContain('\x1B[');
+        } finally {
+          tee.detach();
+          try { fs.unlinkSync(tmpPath); } catch (e) {}
+        }
+      },
+    },
+    {
+      name: 'idempotent: attaching twice with same path returns same stream',
+      run: (ctx) => {
+        const attach = require(path.join(__dirname, '..', '..', '..', 'utils', 'attach-log-file.js'));
+        const tee = attach.createTee();
+        const tmpPath = path.join(os.tmpdir(), `bxm-log-idem-${Date.now()}.log`);
+        try {
+          const s1 = tee.attach(tmpPath);
+          const s2 = tee.attach(tmpPath);
+          ctx.expect(s1).toBe(s2);
+        } finally {
+          tee.detach();
+          try { fs.unlinkSync(tmpPath); } catch (e) {}
+        }
+      },
+    },
+    {
+      name: 'attach with falsy path returns null and does nothing',
+      run: (ctx) => {
+        const attach = require(path.join(__dirname, '..', '..', '..', 'utils', 'attach-log-file.js'));
+        const tee = attach.createTee();
+        ctx.expect(tee.attach(null)).toBe(null);
+        ctx.expect(tee.attach('')).toBe(null);
+      },
+    },
+  ],
+};

package/dist/test/suites/build/manager.test.js

@@ -111,29 +111,51 @@ module.exports = {
       },
     },
     {
-      name: 'getEnvironment returns "development" when BXM_BUILD_MODE !== "true"',
+      name: 'getEnvironment returns "testing" when BXM_TEST_MODE === "true" (takes precedence)',
+      run: (ctx) => {
+        const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
+        const origTest = process.env.BXM_TEST_MODE;
+        const origBuild = process.env.BXM_BUILD_MODE;
+        process.env.BXM_TEST_MODE = 'true';
+        process.env.BXM_BUILD_MODE = 'true'; // even with build mode set, testing wins
+        try {
+          ctx.expect(Manager.getEnvironment()).toBe('testing');
+        } finally {
+          if (origTest === undefined) delete process.env.BXM_TEST_MODE; else process.env.BXM_TEST_MODE = origTest;
+          if (origBuild === undefined) delete process.env.BXM_BUILD_MODE; else process.env.BXM_BUILD_MODE = origBuild;
+        }
+      },
+    },
+    {
+      name: 'getEnvironment returns "development" when BXM_BUILD_MODE !== "true" (and not testing)',
       run: (ctx) => {
         const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
         const original = process.env.BXM_BUILD_MODE;
+        const origTest = process.env.BXM_TEST_MODE;
         delete process.env.BXM_BUILD_MODE;
+        delete process.env.BXM_TEST_MODE;
         try {
           ctx.expect(Manager.getEnvironment()).toBe('development');
         } finally {
           if (original !== undefined) process.env.BXM_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.BXM_TEST_MODE = origTest;
         }
       },
     },
     {
-      name: 'getEnvironment returns "production" when BXM_BUILD_MODE === "true"',
+      name: 'getEnvironment returns "production" when BXM_BUILD_MODE === "true" (and not testing)',
       run: (ctx) => {
         const Manager = require(path.join(__dirname, '..', '..', '..', 'build.js'));
         const original = process.env.BXM_BUILD_MODE;
+        const origTest = process.env.BXM_TEST_MODE;
+        delete process.env.BXM_TEST_MODE;
         process.env.BXM_BUILD_MODE = 'true';
         try {
           ctx.expect(Manager.getEnvironment()).toBe('production');
         } finally {
           if (original === undefined) delete process.env.BXM_BUILD_MODE;
           else                        process.env.BXM_BUILD_MODE = original;
+          if (origTest !== undefined) process.env.BXM_TEST_MODE = origTest;
         }
       },
     },

package/dist/test/suites/build/mode-helpers.test.js

@@ -29,9 +29,10 @@ module.exports = {
   description: 'utils/mode-helpers — cross-context isDevelopment/isTesting/getVersion',
   tests: [
     {
-      name: 'exports { attachTo, isDevelopment, isProduction, isTesting, getVersion }',
+      name: 'exports { attachTo, getEnvironment, isDevelopment, isProduction, isTesting, getVersion }',
       run: (ctx) => {
         ctx.expect(typeof helpers.attachTo).toBe('function');
+        ctx.expect(typeof helpers.getEnvironment).toBe('function');
         ctx.expect(typeof helpers.isDevelopment).toBe('function');
         ctx.expect(typeof helpers.isProduction).toBe('function');
         ctx.expect(typeof helpers.isTesting).toBe('function');
@@ -50,18 +51,29 @@ module.exports = {
       },
     },
     {
-      name: 'isDevelopment() is true under NODE_ENV=development',
+      name: 'isDevelopment() is true under NODE_ENV=development (and not testing)',
       run: (ctx) => {
-        withEnv({ NODE_ENV: 'development', BXM_BUILD_MODE: null }, () => {
+        withEnv({ NODE_ENV: 'development', BXM_BUILD_MODE: null, BXM_TEST_MODE: null }, () => {
           ctx.expect(helpers.isDevelopment()).toBe(true);
         });
       },
     },
     {
-      name: 'isDevelopment() is false when BXM_BUILD_MODE=true',
+      name: 'isDevelopment() is false / isProduction() true when BXM_BUILD_MODE=true (and not testing)',
       run: (ctx) => {
-        withEnv({ NODE_ENV: null, BXM_BUILD_MODE: 'true' }, () => {
+        withEnv({ NODE_ENV: null, BXM_BUILD_MODE: 'true', BXM_TEST_MODE: null }, () => {
           ctx.expect(helpers.isDevelopment()).toBe(false);
+          ctx.expect(helpers.isProduction()).toBe(true);
+        });
+      },
+    },
+    {
+      name: 'testing takes precedence — is* are mutually exclusive (exactly one true)',
+      run: (ctx) => {
+        withEnv({ BXM_TEST_MODE: 'true', BXM_BUILD_MODE: 'true' }, () => {
+          ctx.expect(helpers.isTesting()).toBe(true);
+          ctx.expect(helpers.isDevelopment()).toBe(false);
+          ctx.expect(helpers.isProduction()).toBe(false);
         });
       },
     },
@@ -70,6 +82,8 @@ module.exports = {
       run: (ctx) => {
         function FakeManager() {}
         helpers.attachTo(FakeManager);
+        ctx.expect(typeof FakeManager.getEnvironment).toBe('function');
+        ctx.expect(typeof FakeManager.prototype.getEnvironment).toBe('function');
         ctx.expect(typeof FakeManager.isDevelopment).toBe('function');
         ctx.expect(typeof FakeManager.prototype.isDevelopment).toBe('function');
         ctx.expect(typeof FakeManager.isTesting).toBe('function');
@@ -77,6 +91,31 @@ module.exports = {
         ctx.expect(typeof FakeManager.getVersion).toBe('function');
       },
     },
+    {
+      // The core invariant of the SSOT refactor: is*() DERIVE from getEnvironment(), so they
+      // can NEVER disagree with it, and exactly one is always true. (In build-time Node `chrome`
+      // is undefined, so getEnvironment() resolves via the env-var fallback.)
+      name: 'invariant: is*() exactly matches getEnvironment() + mutually exclusive (every scenario)',
+      run: (ctx) => {
+        const scenarios = [
+          { env: { BXM_TEST_MODE: 'true', BXM_BUILD_MODE: 'true', NODE_ENV: null }, expect: 'testing' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: 'true', NODE_ENV: null },    expect: 'production' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: null, NODE_ENV: 'development' }, expect: 'development' },
+          { env: { BXM_TEST_MODE: null, BXM_BUILD_MODE: null, NODE_ENV: null },       expect: 'development' }, // BXM defaults dev (unpacked)
+        ];
+        for (const s of scenarios) {
+          withEnv(s.env, () => {
+            const e = helpers.getEnvironment();
+            ctx.expect(e).toBe(s.expect);
+            ctx.expect(helpers.isDevelopment()).toBe(e === 'development');
+            ctx.expect(helpers.isTesting()).toBe(e === 'testing');
+            ctx.expect(helpers.isProduction()).toBe(e === 'production');
+            const trueCount = [helpers.isDevelopment(), helpers.isTesting(), helpers.isProduction()].filter(Boolean).length;
+            ctx.expect(trueCount).toBe(1);
+          });
+        }
+      },
+    },
     {
       name: 'getVersion() reads cwd package.json#version in Node context',
       run: (ctx) => {

package/dist/test/utils/extended-mode-warning.js

@@ -0,0 +1,13 @@
+// TEST_EXTENDED_MODE warning — SSOT for consistent messaging.
+//
+// Mirrors BEM/EM/UJM: `TEST_EXTENDED_MODE` is the shared, unprefixed env var that opts a
+// test run into hitting REAL external services instead of skipping/stubbing them. Off by
+// default so `npx mgr test` stays fast and offline-safe. Used by the test command (printed to
+// console + teed to logs/test.log).
+const EXTENDED_MODE_WARNING = [
+  '⚠️⚠️⚠️  WARNING: TEST_EXTENDED_MODE IS TRUE  ⚠️⚠️⚠️',
+  'Tests that hit real external services (Firebase via web-manager, push, any network call) are ENABLED!',
+  'This makes real network calls from the background service worker, popup, and content scripts against live backends.',
+];
+
+module.exports = { EXTENDED_MODE_WARNING };

package/dist/utils/attach-log-file.js

@@ -0,0 +1,105 @@
+// attachLogFile(filePath) — duplicate process.stdout + process.stderr writes to a log file.
+//
+// Inspired by BEM's per-command log pattern, mirrored from EM. Lets devs (and Claude) `tail -f` a
+// log file to see every line of output a process produces — test runner output, child process
+// stdout/stderr, console.log calls, the works.
+//
+// ANSI color codes are stripped from the file output so it's grep-friendly. The console
+// continues to receive the original colored output unchanged.
+//
+// The default export is a process-wide SINGLETON (the common case: a CLI command tees its
+// whole run to one file). `attachLogFile.createTee()` returns an INDEPENDENT tee with its own
+// state. Tees STACK: a later attach() captures the CURRENT `process.stdout.write` (which may
+// already be an outer tee) as its "original", so writes fan out through every layer and
+// detach() restores the exact prior writer in LIFO order. That stacking is what lets the
+// attach-log-file unit tests exercise attach/detach on a throwaway instance WITHOUT killing
+// the live singleton tee that's capturing the actual test run — the bug that previously
+// truncated `logs/test.log` to ~9 lines (the test detached the live tee mid-run).
+//
+// Idempotent: calling attach() twice with the same path on one tee returns the existing handle.
+
+const fs = require('fs');
+const path = require('path');
+
+const ANSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
+
+function stripAnsi(s) {
+  return String(s).replace(ANSI_PATTERN, '');
+}
+
+// Factory — each call returns an independent tee with its own closure state.
+function createTee() {
+  let activeStream = null;
+  let activePath   = null;
+  let originalStdoutWrite = null;
+  let originalStderrWrite = null;
+
+  function attach(filePath) {
+    if (!filePath) return null;
+    const abs = path.resolve(filePath);
+
+    if (activeStream && activePath === abs) return activeStream;
+    if (activeStream) detach();
+
+    // Truncate fresh on each invocation — same as BEM's `flags: 'w'`. Devs running multiple
+    // sessions back to back don't want stale lines from the previous run mixed in.
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const stream = fs.createWriteStream(abs, { flags: 'w' });
+
+    // Header so the file is self-documenting.
+    stream.write(`# bxm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
+
+    // Capture whatever the CURRENT writer is — could be the raw stream OR an outer tee.
+    // Restoring this exact reference on detach() is what makes stacked tees safe.
+    originalStdoutWrite = process.stdout.write.bind(process.stdout);
+    originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+    process.stdout.write = function (chunk, ...rest) {
+      try { stream.write(stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStdoutWrite(chunk, ...rest);
+    };
+    process.stderr.write = function (chunk, ...rest) {
+      try { stream.write(stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStderrWrite(chunk, ...rest);
+    };
+
+    activeStream = stream;
+    activePath   = abs;
+
+    return stream;
+  }
+
+  // Restores stdout/stderr and ends the stream. Returns a Promise that resolves once all
+  // buffered writes have been flushed to disk — await it before process.exit(), otherwise the
+  // tail of the log is silently dropped.
+  function detach() {
+    if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
+    if (originalStderrWrite) process.stderr.write = originalStderrWrite;
+    const stream = activeStream;
+    activeStream = null;
+    activePath   = null;
+    originalStdoutWrite = null;
+    originalStderrWrite = null;
+
+    return new Promise((resolve) => {
+      if (!stream) {
+        return resolve();
+      }
+      stream.end(resolve);
+    });
+  }
+
+  return { attach, detach };
+}
+
+// Process-wide singleton — the production entry point.
+const singleton = createTee();
+
+function attachLogFile(filePath) {
+  return singleton.attach(filePath);
+}
+
+module.exports = attachLogFile;
+module.exports.detach    = singleton.detach;
+module.exports.stripAnsi = stripAnsi;
+module.exports.createTee = createTee;

package/dist/utils/mode-helpers.js

@@ -1,54 +1,75 @@
-// Runtime mode helpers (BEM/EM-pattern), shared across BXM's eight context Managers
+// Runtime mode helpers (BEM/EM/UJM-pattern), shared across BXM's eight context Managers
 // (build / background / popup / options / content / sidepanel / page / offscreen).
 //
-// Three orthogonal concepts:
-//   isDevelopment() — true when running unpacked from disk (an unpacked extension
-//                     loaded via chrome://extensions or a dev build of the framework).
-//                     Browser detection uses `chrome.runtime.getManifest().update_url`
-//                     — packed extensions from the Web Store have one, unpacked ones
-//                     do not. Falls back to NODE_ENV in Node contexts.
-//   isProduction()  — inverse. Running from a packed .crx / store-installed extension.
-//   isTesting()     — true when BXM's test framework is running this process. Set by
-//                     BXM's test runners (BXM_TEST_MODE=true) and consumer test setups
-//                     that want the same signal.
+// `getEnvironment()` is the SINGLE SOURCE OF TRUTH: it is the ONLY function that reads the
+// raw signals (BXM_TEST_MODE / manifest.update_url / BXM_BUILD_MODE / NODE_ENV /
+// config.bxm.environment) and resolves them to exactly ONE of three mutually-exclusive
+// values. The three is*() checks DERIVE from it — they never read raw signals themselves,
+// so they can never disagree with getEnvironment().
 //
-// Use these whenever behavior should differ by *what kind of process* you're in —
-// shorter timeouts in tests, DevTools menu items only in dev, prompts suppressed in
-// tests. Don't use them for "should we hit dev or prod backends" — that's a config
-// concern; use `getEnvironment()` for that (in build.js).
+//   isDevelopment() — `getEnvironment() === 'development'`: running unpacked from disk (an
+//                     unpacked extension via chrome://extensions or a dev build), and NOT
+//                     testing.
+//   isTesting()     — `getEnvironment() === 'testing'`: BXM's test framework is running this
+//                     process (BXM_TEST_MODE=true). TAKES PRECEDENCE — a test run is not dev.
+//   isProduction()  — `getEnvironment() === 'production'`: running from a packed .crx /
+//                     store-installed extension, and NOT testing. A real positive check —
+//                     NOT `!isDevelopment()`.
 //
-// Context caveat: in build-time Node (gulp / CLI), `chrome` is undefined. We detect
-// via `typeof chrome` so the same code works in every context. In test mode the
-// browser-side check is short-circuited via BXM_TEST_MODE so `isDevelopment()`
-// returns a stable value regardless of which test layer is running.
+// To gate "anything non-production" use `!isProduction()` or `isDevelopment() ||
+// isTesting()` intentionally — never assume two values.
+//
+// Context caveat: in build-time Node (gulp / CLI), `chrome` is undefined. getEnvironment()
+// detects via `typeof chrome` so the same code works in every context. Browser detection
+// uses `chrome.runtime.getManifest().update_url` — packed store extensions have one,
+// unpacked ones do not.
 
-function isDevelopment() {
-  // Browser-side: rely on `update_url` being absent for unpacked extensions.
-  // (Store-installed extensions have `update_url` set to clients2.google.com / similar.)
+// getEnvironment() — the SINGLE SOURCE OF TRUTH. Reads every raw signal and resolves to
+// exactly ONE of 'development' | 'testing' | 'production' (mutually exclusive; testing wins).
+// Precedence: testing → production → development.
+function getEnvironment() {
+  // 1. Testing wins — set by BXM's test runners / harness, or a testing-baked build.
+  //    Works in Node (process.env), extension contexts (globalThis set before consumer JS),
+  //    and config-baked builds (config.bxm.environment === 'testing').
+  if (typeof process !== 'undefined' && process.env && process.env.BXM_TEST_MODE === 'true') return 'testing';
+  if (typeof globalThis !== 'undefined' && globalThis.BXM_TEST_MODE === true) return 'testing';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'testing') return 'testing';
+
+  // 2. Browser-side: packed/store extensions have `update_url`; unpacked ones do not.
+  //    This is the authoritative runtime signal in an extension context.
   if (typeof chrome !== 'undefined' && chrome.runtime && typeof chrome.runtime.getManifest === 'function') {
     try {
-      const manifest = chrome.runtime.getManifest();
-      return !manifest.update_url;
-    } catch (_) { /* fall through */ }
+      return chrome.runtime.getManifest().update_url ? 'production' : 'development';
+    } catch (_) { /* fall through to Node/config signals */ }
   }
-  // Node / build-time fallback.
-  if (process.env.NODE_ENV === 'development') return true;
-  if (process.env.BXM_BUILD_MODE === 'true') return false;
-  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'development') return true;
-  return false;
+
+  // 3. Node / build-time + config signals.
+  if (process.env.BXM_BUILD_MODE === 'true') return 'production';
+  if (process.env.NODE_ENV === 'development') return 'development';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'development') return 'development';
+  if (this && this.config && this.config.bxm && this.config.bxm.environment === 'production') return 'production';
+
+  // 4. Default: development. BXM's deployed artifacts ALWAYS carry their signal — a packed /
+  //    store extension has `manifest.update_url`, and build-time Node sets BXM_BUILD_MODE. So
+  //    reaching here means a bare tooling / unpacked context, where development is the sensible
+  //    answer. (Contrast BEM/EM, whose deployed RUNTIME can legitimately lack a signal, so they
+  //    default to production.)
+  return 'development';
+}
+
+// The three checks DERIVE from getEnvironment() — they never read raw signals, so they can
+// never disagree with it. isDevelopment() is NOT true in testing; isProduction() is a real
+// positive check (never `!isDevelopment()`).
+function isDevelopment() {
+  return getEnvironment.call(this) === 'development';
 }
 
 function isProduction() {
-  return !this.isDevelopment();
+  return getEnvironment.call(this) === 'production';
 }
 
 function isTesting() {
-  // Canonical signal — set by BXM's test runners and consumer test setups alike.
-  // Works in Node (process.env) AND in extension contexts (the harness extension
-  // sets globalThis.BXM_TEST_MODE before any consumer code runs).
-  if (typeof process !== 'undefined' && process.env && process.env.BXM_TEST_MODE === 'true') return true;
-  if (typeof globalThis !== 'undefined' && globalThis.BXM_TEST_MODE === true) return true;
-  return false;
+  return getEnvironment.call(this) === 'testing';
 }
 
 // `getVersion()` — returns the extension's version string.
@@ -71,20 +92,24 @@ function getVersion() {
 }
 
 // Mix the helpers into a Manager constructor's prototype + the constructor itself
-// (so `Manager.isTesting()` works statically too, matching BEM/EM pattern).
+// (so `Manager.isTesting()` works statically too, matching BEM/EM/UJM pattern).
+// getEnvironment() is the SSOT and is attached here too — build.js no longer defines it.
 function attachTo(Manager) {
-  Manager.prototype.isDevelopment = isDevelopment;
-  Manager.prototype.isProduction  = isProduction;
-  Manager.prototype.isTesting     = isTesting;
-  Manager.prototype.getVersion    = getVersion;
-  Manager.isDevelopment = isDevelopment;
-  Manager.isProduction  = isProduction;
-  Manager.isTesting     = isTesting;
-  Manager.getVersion    = getVersion;
+  Manager.prototype.getEnvironment = getEnvironment;
+  Manager.prototype.isDevelopment  = isDevelopment;
+  Manager.prototype.isProduction   = isProduction;
+  Manager.prototype.isTesting      = isTesting;
+  Manager.prototype.getVersion     = getVersion;
+  Manager.getEnvironment = getEnvironment;
+  Manager.isDevelopment  = isDevelopment;
+  Manager.isProduction   = isProduction;
+  Manager.isTesting      = isTesting;
+  Manager.getVersion     = getVersion;
 }
 
 module.exports = {
   attachTo,
+  getEnvironment,
   isDevelopment,
   isProduction,
   isTesting,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-extension-manager",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Browser Extension Manager dependency manager",
   "main": "dist/index.js",
   "exports": {
@@ -76,8 +76,8 @@
   "homepage": "https://template.itwcreativeworks.com",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.138",
-    "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.5",
+    "@babel/core": "^7.29.7",
+    "@babel/preset-env": "^7.29.7",
     "@popperjs/core": "^2.11.8",
     "babel-loader": "^10.1.1",
     "chalk": "^5.6.2",
@@ -95,12 +95,12 @@
     "minimatch": "^10.2.5",
     "node-powertools": "^3.0.0",
     "npm-api": "^1.0.1",
-    "sass": "^1.99.0",
-    "web-manager": "^4.1.42",
-    "webpack": "^5.106.2",
+    "sass": "^1.100.0",
+    "web-manager": "^4.2.0",
+    "webpack": "^5.107.2",
     "wonderful-fetch": "^2.0.5",
     "wonderful-version": "^1.3.2",
-    "ws": "^8.20.0",
+    "ws": "^8.21.0",
     "yargs": "^18.0.0"
   },
   "peerDependencies": {