browser-extension-manager 1.7.0 → 1.7.2

package/CLAUDE.md

@@ -43,6 +43,8 @@ To load the unpacked extension in Chrome: point chrome://extensions → "Load un
 
 ### For Framework Development (This Repository)
 
+> **🚫 NEVER use `npx mgr ...` from the framework repo.** `npx mgr` is for CONSUMER projects only (where the bin is linked in `node_modules/.bin/`). From the framework repo, use `npm test`, `npm start`, etc. — the `scripts` in `package.json` call the local `bin/` directly. This applies to ALL four OMEGA frameworks (BEM/UJM/BXM/EM).
+
 1. `npm install`
 2. `npm start` — watch + compile `src/` → `dist/` via prepare-package
 3. Test in the **designated test consumer** — `../powertools-browser-extension` is BXM's consumer for validating framework changes end-to-end (exercise any consumer-level flow there freely: builds, tests, packaging, runtime). From inside it, run `npx mgr install dev` to swap BXM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/browser-extension-manager`). Reverse with `npx mgr install live`.
@@ -198,10 +200,11 @@ See [docs/cli.md](docs/cli.md).
 
 ## Development Workflow
 
-- **🚫 NEVER run `npm start`** — it's the user's long-running dev watcher. Assume it's already running; if it isn't, **instruct the user to run it** rather than running it yourself (running it again kills theirs). To see output, **read the `logs/*.log` files** (`dev.log`, `build.log`, `test.log`) — never tail/attach to the process. Running `npx mgr test` is fine.
+- **🚫 NEVER use `npx mgr ...` from the framework repo** — `npx mgr` is for CONSUMER projects only (where the bin lives in `node_modules/.bin/`). From the framework repo, use `npm test`, `npm start`, etc. — the `scripts` in `package.json` call `node bin/browser-extension-manager` directly. This applies to ALL four OMEGA frameworks (BEM/UJM/BXM/EM).
+- **🚫 NEVER run `npm start`** (consumer projects) — it's the user's long-running dev watcher. Assume it's already running; if it isn't, **instruct the user to run it** rather than running it yourself (running it again kills theirs). To see output, **read the `logs/*.log` files** (`dev.log`, `build.log`, `test.log`) — never tail/attach to the process. Running `npx mgr test` is fine.
 - **Where the output logs live:** the gulp pipeline tees all stdout/stderr to `<projectRoot>/logs/dev.log` (on `npm start`) or `logs/build.log` (on `npm run build`), truncated fresh each run, ANSI-stripped. `cat logs/dev.log` (or `grep` it) instead of scrolling scrollback. `npx mgr test` writes `logs/test.log`. See [docs/build-system.md](docs/build-system.md#log-files).
 - **After editing files**, verify the gulp watcher recompiled successfully. Check for webpack/sass errors in the console output. A change that breaks the build is not a completed change.
-- **Live-test UI changes via CDP.** After code changes compile, use the `chrome-devtools` MCP tools (screenshots, click, evaluate JS, console logs) to verify the change works in the running browser. This is the primary way to confirm UI changes — type-checking and test suites verify code correctness, not feature correctness. See `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
+- **Live-test the extension via CDP.** Use the `chrome-devtools-extension` MCP upstream — it launches a per-session Chrome for Testing with the unpacked extension pre-loaded (`BXM_EXTENSION_PATH="$(pwd)/packaged/chromium/raw" claude`, then `router__enable_upstream`; stable Chrome ignores `--load-extension`). Plain web pages (no extension needed): the regular `chrome-devtools` MCP tools — your session auto-launches its own private Chrome on the first tool call. This is the primary way to confirm UI changes — type-checking and test suites verify code correctness, not feature correctness. See [docs/cdp-debugging.md](docs/cdp-debugging.md) + `~/.claude/mcp-server/servers/chrome-devtools-extension/CLAUDE.md`.
 
 ## Supply-Chain Security
 
@@ -230,6 +233,8 @@ Whenever you make a behavioral change (new command, new flag, new pattern, remov
 
 Don't ship behavioral changes with stale docs. Validate first, then document — write docs that describe shipped reality, not intentions.
 
+**The OMEGA docs are structurally MIRRORED.** This file's section skeleton, the consumer template (`src/defaults/CLAUDE.md`), shared-concept `docs/*.md` filenames, and the `omega:*` skills are identical in structure and order across the sister frameworks (UJM / BEM / BXM / EM / MAM — WM mirrors the library subset). Never add, rename, or reorder a section here without making the SAME change in every sister repo in the same pass. The canonical skeletons + omission rules live in the `omega:main` skill's `mirror-spec.md` resource.
+
 ## Documentation
 
 API references for each subsystem live in `docs/`:

package/dist/defaults/CLAUDE.md

@@ -1,6 +1,8 @@
 # ========== Default Values ==========
 # Browser Extension Manager (BXM) — consumer project
 
+<!-- MAINTAINERS (framework repo): this consumer template is MIRRORED across UJM/BEM/BXM/EM/MAM — same sections, same order (framework-specific extras may be inserted; canonical sections are never reordered/renamed). Edit all five together. Canonical skeleton: omega:main skill → resources/mirror-spec.md -->
+
 ## 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.

package/dist/test/runner.js

@@ -402,6 +402,11 @@ function filterBySource(source, files, sourceFilter, pathPart) {
   });
 }
 
+// Glob ignore patterns implementing the "underscore = not a suite" convention:
+// `_`-prefixed FILES (e.g. test/_init.js) and everything under a `_`-prefixed
+// DIRECTORY at any depth (helpers, fixtures — e.g. test/_helpers/harness.js).
+const DISCOVERY_IGNORE = ['**/_*.js', '**/_*/**'];
+
 function discoverTestFiles(target) {
   const { source: sourceFilter, pathPart } = parseTarget(target);
   const framework = [];
@@ -425,7 +430,7 @@ function discoverTestFiles(target) {
   // Consumers write their own boot tests under <cwd>/test/boot/.
   const frameworkSuitesDir = path.join(__dirname, 'suites');
   if (jetpack.exists(frameworkSuitesDir)) {
-    const ignore = ['_**'];
+    const ignore = [...DISCOVERY_IGNORE];
     if (!isFrameworkSelfTest) ignore.push('boot/**');
     glob('**/*.js', { cwd: frameworkSuitesDir, ignore }).sort().forEach((rel) => {
       framework.push(path.join(frameworkSuitesDir, rel));
@@ -434,9 +439,10 @@ function discoverTestFiles(target) {
 
   // Consumer project suites — CWD/test/**/*.js. Skip when running from inside the
   // framework's own dist tree (where consumer-tests-dir === framework-tests-parent).
+  // Excludes `_`-prefixed files and directories (see DISCOVERY_IGNORE).
   const projectTestsDir = path.join(process.cwd(), 'test');
   if (jetpack.exists(projectTestsDir) && projectTestsDir !== path.dirname(frameworkSuitesDir)) {
-    glob('**/*.js', { cwd: projectTestsDir, ignore: ['_**'] }).sort().forEach((rel) => {
+    glob('**/*.js', { cwd: projectTestsDir, ignore: [...DISCOVERY_IGNORE] }).sort().forEach((rel) => {
       project.push(path.join(projectTestsDir, rel));
     });
   }
@@ -512,4 +518,4 @@ async function runInitSetups() {
   }
 }
 
-module.exports = { run, SkipError };
+module.exports = { run, SkipError, DISCOVERY_IGNORE };

package/dist/test/suites/build/test-discovery.test.js

@@ -0,0 +1,63 @@
+// Build-layer tests for test-suite discovery — specifically the
+// "underscore = not a suite" convention: `_`-prefixed files and everything
+// under `_`-prefixed directories (at ANY depth) must be excluded, so consumers
+// can keep helpers and fixture trees (e.g. test/_helpers/harness.js)
+// next to their suites.
+
+const path = require('path');
+
+module.exports = {
+  type: 'suite',
+  layer: 'build',
+  description: 'test discovery — underscore exclusion convention',
+  tests: [
+    {
+      name: 'runner exports DISCOVERY_IGNORE',
+      run: (ctx) => {
+        const runner = require(path.join(__dirname, '..', '..', 'runner.js'));
+        ctx.expect(Array.isArray(runner.DISCOVERY_IGNORE)).toBe(true);
+        ctx.expect(runner.DISCOVERY_IGNORE.length >= 2).toBe(true);
+      },
+    },
+    {
+      name: 'glob with DISCOVERY_IGNORE skips _ files and _ dirs at any depth',
+      run: (ctx) => {
+        const fs = require('fs');
+        const os = require('os');
+        const glob = require('glob').globSync;
+        const { DISCOVERY_IGNORE } = require(path.join(__dirname, '..', '..', 'runner.js'));
+
+        const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'bxm-discovery-test-'));
+        const write = (rel) => {
+          const file = path.join(tmp, rel);
+          fs.mkdirSync(path.dirname(file), { recursive: true });
+          fs.writeFileSync(file, 'module.exports = {};\n');
+        };
+
+        // Should be DISCOVERED:
+        write('build/config.test.js');
+        write('page/runner.test.js');
+        write('boot/nested/deep.test.js');
+
+        // Should be EXCLUDED:
+        write('_init.js');                                  // top-level _ file
+        write('page/_helper.js');                           // nested _ file
+        write('_helpers/harness.js');                       // file in top-level _ dir
+        write('_fixtures/packages/runner/mod/index.js');    // deep inside a _ dir
+        write('boot/_private/util.js');                     // _ dir below a layer dir
+
+        const found = glob('**/*.js', { cwd: tmp, ignore: [...DISCOVERY_IGNORE] }).sort();
+
+        try {
+          ctx.expect(found).toEqual([
+            'boot/nested/deep.test.js',
+            'build/config.test.js',
+            'page/runner.test.js',
+          ]);
+        } finally {
+          fs.rmSync(tmp, { recursive: true, force: true });
+        }
+      },
+    },
+  ],
+};

package/docs/cdp-debugging.md

@@ -1,45 +1,42 @@
 # CDP Debugging (driving a live browser)
 
-How to launch a browser you can CONTROL — see the extension live, screenshot it, click, type, read console logs, inspect network requests — for agents (Claude via MCP/CDP) and humans. For BXM this is THE dev surface: the extension only exists inside a running Chrome.
+How to drive a browser you can CONTROL — see the extension live, screenshot it, click, type, read console logs, inspect network requests — for agents (Claude via MCP/CDP) and humans. For BXM this is THE dev surface: the extension only exists inside a running browser.
 
-> Mirrored across the four sister frameworks (UJM / BEM / BXM / EM) — same core section, framework-flavored. Edit all four together.
+> Mirrored across the five sister frameworks (UJM / BEM / BXM / EM / WM) — same core section, framework-flavored. Edit all five together.
 
-## Launching a controllable Chrome (the canonical command)
+## The browser: your Claude session owns one
 
-```bash
-open -gna "Google Chrome" --args \
-  --remote-debugging-port=9223 \
-  --user-data-dir="$HOME/Library/Application Support/chrome-profiles/agent" \
-  --no-first-run --no-default-browser-check \
-  --disable-background-timer-throttling \
-  --disable-backgrounding-occluded-windows \
-  --disable-renderer-backgrounding
-```
+Browser work runs through the **`chrome-devtools` MCP** (via mcp-router). There is NO launch procedure anymore — no ports, no profile dirs, no curl checks:
 
-Verify it's up: `curl -s http://127.0.0.1:9223/json/version`
+- **Just call the tools** — `new_page`, `navigate_page`, `take_screenshot`, `click`, `fill`, `evaluate_script`, `list_console_messages`, `list_network_requests`. The browser auto-launches on the first call.
+- **Each Claude session gets its OWN private Chrome** (`--isolated`): temp profile, CDP over an internal pipe. Parallel sessions cannot see or touch each other's pages — open and close pages freely, the whole browser is yours.
+- **It dies with the session.** No orphans, no cleanup, nothing to kill.
+- **Ephemeral profile** — cookies/logins do NOT persist between sessions. If a flow needs auth, log in during the task.
+- **Self-signed HTTPS is pre-accepted** (`--acceptInsecureCerts` in the upstream) — dev servers load without certificate interstitials.
+- **NEVER quit/kill Chrome by app name** (`killall "Google Chrome"`, osascript) — that's the user's personal browser, not yours.
 
-The rules that make this work (each one learned the hard way):
+Humans: the agent's Chrome window is visible — you can watch it drive. Full reference: `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
 
-- **`open -gna` launches WITHOUT stealing focus.** `-g` = don't bring to foreground, `-n` = new instance (required — without it `open` just activates the already-running daily Chrome and the `--args` are ignored). Launching the Chrome binary directly ALWAYS activates the app and steals focus. Do NOT use `-j`/`--hide` — animations need a visible window; instead the three `--disable-*` flags keep timers/rAF/rendering at FULL speed while the window sits behind your work (verified: rAF at the display's native 120fps while backgrounded, focus never moved).
-- **`--user-data-dir` is REQUIRED, not optional.** Chrome 136+ **silently ignores** `--remote-debugging-port` on the default profile — no error, no port, nothing (verified on Chrome 149). This is the #1 "why isn't CDP up" trap.
-- **The profile dir IS the persistent state** — logins AND installed extensions. Cookies + localStorage survive relaunches (verified by round-trip), and so does an unpacked extension you've loaded (see below). Ecosystem convention: ONE shared profile at `~/Library/Application Support/chrome-profiles/agent` across all four frameworks, so setup is one-time.
-- **One Chrome instance per profile dir — but MANY agents per instance.** CDP is multi-client (verified: two concurrent clients driving different tabs of one instance): agents and sessions attach to the SAME port, each drives its own tab, and all share the profile's logins and extensions. One agent per tab is the only rule. A second launch with the same dir just opens a window in the existing instance and **ignores the new debug port** — attach to the running one instead. Reach for a second profile + port (`…/b` on 9224) only for a different IDENTITY (a different account = a different cookie jar) or hard isolation.
-- It runs **side-by-side with the daily Chrome** — a different `--user-data-dir` is a fully separate instance.
-- **Quit by profile match, never by app name**: `pkill -f "chrome-profiles/agent"`. (`osascript 'tell app "Google Chrome" to quit'` hits the daily browser too — same app name.)
+## Electron apps are the exception (attach, don't launch)
 
-## Loading the extension (BXM specifics)
+An Electron dev app is a running singleton — you ATTACH to it instead of launching a browser: the `chrome-devtools-electron` MCP upstream (reads `EM_CDP_PORT`, default 9222, expanded once at session start) or EM's per-invocation `npx mgr cdp`. See EM's `docs/cdp-debugging.md`.
 
-- **`--load-extension` does NOT work on stable Chrome** — silently ignored (verified on Chrome 149; support was removed from branded Chrome around v137). Do not build tooling on it.
-- Instead, load it ONCE through the UI: in the agent-profile Chrome, open `chrome://extensions` → enable **Developer mode** → **Load unpacked** → select the build output. **The persistent profile keeps it installed across every relaunch** — reload it from `chrome://extensions` (or the ⟳ button) after rebuilds.
-- The extension's surfaces appear as CDP targets: the background service worker (`type: "service_worker"`, `chrome-extension://<id>/…`), the popup while it's open, and content scripts inside the page targets they're injected into.
+## BXM specifics: testing the extension (`chrome-devtools-extension` upstream)
 
-## Driving it
+The plain `chrome-devtools` browser has NO extension in it — and `--load-extension` is silently ignored by branded stable Chrome (removed ~v137; verified on 149). The fix is the dedicated **`chrome-devtools-extension` MCP upstream**: the same per-session isolated model, but it launches **Chrome for Testing** (which still honors `--load-extension` — verified on CfT 150) with your unpacked extension pre-loaded into the ephemeral profile.
 
-| Client | Good for | Port handoff |
-|---|---|---|
-| `chrome-devtools` MCP | rich interaction — click, fill, type, screenshots, network requests, console messages, performance traces | `CHROME_CDP_PORT` env var, **expanded ONCE when the Claude session spawns its MCP — set it BEFORE launching `claude`** (mid-session changes do nothing) |
-| Any CDP client — including EM's `npx mgr cdp` run from any EM project | quick JS eval, per-renderer screenshots | per invocation: `EM_CDP_PORT=9223 npx mgr cdp eval "<url-substring>" 'document.title'` |
+The recipe:
 
-Port conventions: **9222** = Electron apps (EM), **9223+** = Chrome instances.
+1. **Build the loadable output**: `npm run build` → `packaged/chromium/raw/` (strict-JSON manifest; `dist/` is NOT Chrome-loadable — its manifest is JSON5).
+2. **Launch the session with the extension path** (env is expanded ONCE at session start — set it BEFORE `claude`):
+   ```bash
+   BXM_EXTENSION_PATH="$(pwd)/packaged/chromium/raw" claude
+   ```
+3. **In the session, enable the upstream** (it's on-demand): `router__enable_upstream { name: "chrome-devtools-extension" }`. The first tool call launches CfT with the extension loaded. Tools are namespaced `chrome-devtools-extension__*` (34 tools — the base set + extension tools).
+4. **Rebuild loop**: after `npm run build`, `router__disable_upstream` + `router__enable_upstream` → fresh browser with the rebuilt extension (the profile is ephemeral; the extension loads at launch).
 
-Navigating to a brand's UJM dev site? BrowserSync serves over HTTPS (self-signed cert). Prefer `https://localhost:4000`; fall back to the machine's local network IP (e.g. `https://192.168.x.x:4000`) if localhost doesn't connect. Port 4000 by default, increments to 4001+ when multiple sites run. Read the exact URL from `.temp/_config_browsersync.yml` at the root of the WEBSITE project (the UJM consumer — e.g. `<brand>-website/.temp/_config_browsersync.yml`, NOT this extension repo).
+What you can reach: the popup and extension pages as page targets, content scripts inside the pages they're injected into, and the background service worker (`evaluate_script` takes a `serviceWorkerId`). Chrome for Testing binaries live in `~/.cache/puppeteer/chrome/` (the upstream auto-resolves the newest; update with `npu npx @puppeteer/browsers install chrome@stable`).
+
+Full recipe + gotchas: `~/.claude/mcp-server/servers/chrome-devtools-extension/CLAUDE.md`.
+
+Navigating to a brand's UJM dev site? **`https://localhost:4000` — NEVER the LAN IP** (`https://192.168.x.x:...`). Port 4000 by default, increments (4001, …) when multiple sites run; exact port in `.temp/_config_browsersync.yml` at the WEBSITE project root (the UJM consumer, NOT this extension repo).

package/docs/test-framework.md

@@ -157,7 +157,7 @@ Consumers writing their own tests get this automatically when running through `n
 - **Framework defaults**: `<BXM>/dist/test/suites/**/*.js`
 - **Consumer suites**: `<cwd>/test/**/*.js`
 
-Directories starting with `_` are ignored. Files load alphabetically.
+**The underscore convention** (`DISCOVERY_IGNORE` in `src/test/runner.js`): `_`-prefixed FILES (`test/_init.js`, `test/page/_helper.js`) and everything under a `_`-prefixed DIRECTORY at **any depth** (`test/_fixtures/**`, `test/boot/_private/**`) are excluded from suite discovery. Put shared helpers, fixture data, and non-test support files in `_`-prefixed paths — e.g. `test/_fixtures/`, `test/_helpers/`. The runner still specifically loads `test/_init.js` as the lifecycle hook. Matches the same convention in BEM/EM/UJM. Files load alphabetically.
 
 **Framework's boot suites are scoped to BXM self-test runs only.** When a consumer runs `npx bxm test`, the framework's `dist/test/suites/boot/**` is excluded from discovery (those tests assert on BXM's internal fixture extension). Consumers write their own boot tests under `<cwd>/test/boot/`. See [test-boot-layer.md](test-boot-layer.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-extension-manager",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "description": "Browser Extension Manager dependency manager",
   "main": "dist/index.js",
   "exports": {
@@ -34,8 +34,8 @@
     "mgr": "bin/browser-extension-manager"
   },
   "files": [
-    "dist/",
     "bin/",
+    "dist/",
     "docs/",
     "CLAUDE.md"
   ],