browser-extension-manager 1.5.0 → 1.6.0

package/README.md

@@ -61,10 +61,13 @@ 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 --integration     # also run integration suites against REAL external services (Firebase, etc.)
+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 `--integration` (skipped in-source otherwise, never mocked).
+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:
 

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/CLAUDE.md

@@ -28,6 +28,13 @@ 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
 ```
@@ -75,6 +82,16 @@ After `initialize()`, every Manager exposes:
 
 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 ==========

package/dist/defaults/test/README.md

@@ -13,6 +13,12 @@ Match the framework's four layers — Browser Extension Manager's test runner di
 | `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

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,12 +39,13 @@ 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'));
@@ -360,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 = [];
 
@@ -398,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) {

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-extension-manager",
-  "version": "1.5.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": {