@btraut/browser-bridge 0.13.2 → 0.15.0

package/CHANGELOG.md

@@ -6,6 +6,57 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
+### Added
+
+### Changed
+
+### Fixed
+
+## [0.15.0] - 2026-03-21
+
+### Added
+
+- Added first-class `permissions.*` support across Core, CLI, and MCP for reading allowlist/mode state and requesting allowlist/mode changes through a human approval flow in Chrome.
+- Added a repo-local `dev:loop` helper plus a matching local `dev-loop` skill for Browser Bridge contributors, so extension rebuild/relaunch/bypass setup can run from one command instead of the usual Chrome nonsense.
+
+### Changed
+
+- The repo-local `bump-version` release skill and release doc now require a fresh `npm install` and `npm run build` before any version bumping, so releases start from a clean build instead of wishful thinking.
+- External permission changes are now approval-gated end to end: CLI/MCP can request them, but the extension applies them only after a human approves a dedicated prompt, with extra friction for bypass mode.
+
+### Fixed
+
+- Cold-start extension attach is less brittle: Core now waits briefly for the extension handshake before failing drive and permissions calls with `EXTENSION_DISCONNECTED`, which cuts down false startup misses right after Chrome/runtime reconnects.
+- `drive.click` now retries a few transient locator-resolution misses instead of giving up after one wobble, which makes toggle/action controls like ManaVault's `Edit list` less likely to fail during live rerenders.
+- Interactive AX snapshots now prune hover-hidden controls that fail live DOM visibility and pointer-event checks, so inspect stops advertising inert ManaVault-style quantity buttons as actionable.
+- `dev enable-inspect` now retries transient stale diagnostics before failing, which cuts down false "inspect unavailable" reports while the extension handshake and capability negotiation are still catching up.
+- Locator ranking now prefers directly hittable exact matches over merely visible duplicates, so drive clicks are less likely to land on ghost controls that share an `aria-label` but are occluded or inert.
+- Repo-local Codex skills now live under `.agents/skills`, and the CLI install/prepack flow now reads from that canonical repo path instead of the dead `skills/` directory.
+- Existing tabs now recover their content script on demand after extension updates, so `drive.wait_for` and other tab actions stop dying with `Receiving end does not exist` just because the tab predates the current build.
+- Inspect now evaluates in an isolated world on the top frame when available, which makes auth/passkey pages less likely to derail `extract_content`, `page_state`, and `evaluate` with extension-surface debugger context errors.
+- Inspect reads are less flaky and less noisy: `extract_content` now defaults to quiesced capture, `page_state` is summary-first with redacted values by default, and `console_list` filters stale pre-session history unless you ask for older entries explicitly.
+
+## [0.14.0] - 2026-03-13
+
+### Added
+
+- Added a project-local `bump-version` skill that walks an agent through the repo's release flow: explicit SemVer bump selection, changelog move, release commit/tag push, GitHub release verification, npm publish, and the final extension-update reminder.
+
+### Changed
+
+- Refactored the extension action path into smaller, clearer pieces: tab resolution, permission gating, debugger dispatch, click strategies, and locator scoring no longer all live inline in the same giant handlers.
+- Refactored inspect internals into explicit subsystems for target selection, content extraction policy, and snapshot-ref lifecycle management, which makes the core behavior easier to follow and safer to change.
+
+### Fixed
+
+- Clicks and locator resolution are much more reliable on real sites, especially for popup/menu triggers, duplicate controls, exact text matches, and visible-vs-hidden targets.
+- Inspect is more stable and useful on dynamic pages: AX snapshots keep the right interactive nodes, `extract_content` handles SPA layouts better, and snapshot refs recover more cleanly after rerenders.
+- Drive and inspect targeting are more predictable: session tab affinity is preserved by default, explicit `tab_id` targeting works end-to-end, and tab-activation failures degrade more gracefully when the right tab is already active.
+- The inspect/setup story is much cleaner: current builds treat inspect as always-on, `dev enable-inspect` behaves like a diagnostics/remediation command, and the docs/runtime guidance now match reality.
+- CLI and runtime plumbing got tougher around packaging and failure handling, including cleaner startup errors, better executable/shebang preservation, and less debugger coupling for screenshots.
+- Repo tooling and validation were cleaned up too, including hook fixes, docs cleanup, and follow-up CI/lint/typecheck regressions on `main`.
+- Plus 35 other bug fixes and polish items across diagnostics, docs, test coverage, and developer tooling.
+
 ## [0.13.2] - 2026-02-18
 
 ### Changed

package/README.md

@@ -19,6 +19,10 @@ npm i -g @btraut/browser-bridge
 browser-bridge --help
 ```
 
+zsh gotcha:
+
+- If `browser-bridge` is not installed or not on `PATH` and you run it from inside a directory also named `browser-bridge`, zsh can print a misleading `permission denied` by trying to execute the directory itself. Check `command -v browser-bridge` before treating that error as a packaging failure.
+
 2. Run the installer:
 
 ```bash
@@ -45,6 +49,16 @@ Then load the unpacked extension from `packages/extension/`.
 
 </details>
 
+Repo contributors: run `npm run hooks:install` once after clone. This repo expects `core.hooksPath=.githooks` so local `pre-commit` and `pre-push` block the same format/lint/typecheck failures that CI enforces.
+
+Repo contributors who are iterating on the extension should stop doing the manual delete/reinstall routine. Use:
+
+```bash
+npm run dev:loop -- --open-options
+```
+
+That rebuilds the workspace, uses macOS UI scripting to open `chrome://extensions` in your existing Chrome profile, clicks **Update** to reload unpacked extensions, waits for Browser Bridge to reconnect, and requests bypass mode if Chrome is still granular. Add `--install` only when dependencies changed.
+
 4. Try it:
 
 ```text
@@ -106,7 +120,7 @@ See `docs/cdp-input-model.md` for details and smoke verification.
 
 ## 🔒 Site Permissions (Drive Actions)
 
-Browser Bridge is intentionally safe: **drive actions** (`drive.navigate`, click, type, etc.) require **per-site approval**. `inspect.*` is additionally guarded behind an explicit debugger-capability toggle in extension options.
+Browser Bridge is intentionally safe: **drive actions** (`drive.navigate`, click, type, etc.) require **per-site approval**. `inspect.*` is always available in current builds; if diagnostics reports missing inspect capability, that is stale runtime drift, not a separate permission toggle.
 
 <details>
 <summary>How approvals work (click to expand)</summary>
@@ -124,7 +138,15 @@ Manage approvals (and bypass mode):
 - Switch **Permission mode** to **Bypass (dangerous)** to skip the allowlist and prompts entirely.
 - In bypass mode, the agent can take actions on any website without asking.
 - Restricted URLs (for example `chrome://` and `file://`) are still blocked.
-- `inspect.*` requires enabling **Debugger-based inspect** in extension options. If disabled, inspect calls fail with `ATTACH_DENIED` and a clear next step.
+- CLI and MCP can also inspect or request permission changes:
+  - Reads: `browser-bridge permissions list`, `browser-bridge permissions mode`, `browser-bridge permissions pending`
+  - Requests: `browser-bridge permissions allow-site --site example.com`, `revoke-site --site example.com`, `set-mode --mode granular|bypass`
+  - Equivalent MCP tools exist under `permissions.*`
+- External permission-change requests are still human-gated:
+  - CLI/MCP request calls open a dedicated Chrome approval prompt.
+  - Nothing is mutated silently from CLI or MCP.
+  - If the request times out, the command/tool returns `status: "timed_out"`; if the prompt is still open, a later human approval still applies the change.
+- `inspect.*` should already be enabled in current builds. Use `browser-bridge dev enable-inspect` as a diagnostics probe; if it reports missing inspect capability, treat that as stale runtime drift and reload or update the Browser Bridge extension.
 
 </details>
 
@@ -142,6 +164,15 @@ The CLI mirrors the MCP tool surface.
 - `session.recover`
 - `session.close`
 
+**permissions**
+
+- `permissions.list`
+- `permissions.get_mode`
+- `permissions.list_pending_requests`
+- `permissions.request_allow_site`
+- `permissions.request_revoke_site`
+- `permissions.request_set_mode`
+
 **drive**
 
 - `drive.navigate`
@@ -206,8 +237,8 @@ Or copy the Browser Bridge skill into your agent skills directory (advanced):
 
 ```bash
 # From this repo:
-# cp -R docs/skills/browser-bridge ~/.agents/skills/browser-bridge
-# cp -R docs/skills/browser-bridge ~/.claude/skills/browser-bridge
+# cp -R .agents/skills/browser-bridge ~/.agents/skills/browser-bridge
+# cp -R .agents/skills/browser-bridge ~/.claude/skills/browser-bridge
 
 # From npm (global install):
 cp -R "$(npm root -g)/@btraut/browser-bridge/skills/browser-bridge" ~/.agents/skills/browser-bridge
@@ -234,12 +265,12 @@ Codex:
 codex mcp add browser-bridge -- browser-bridge mcp
 ```
 
-Optional custom host/port (use `browser-bridge dev info` to get the current worktree port):
+Optional custom host/port override (only if you intentionally run Core somewhere else):
 
 ```bash
 codex mcp add browser-bridge \
   --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
-  --env BROWSER_BRIDGE_CORE_PORT=<port-from-dev-info> \
+  --env BROWSER_BRIDGE_CORE_PORT=<custom-port> \
   -- browser-bridge mcp
 ```
 
@@ -249,12 +280,12 @@ Claude Code:
 claude mcp add --transport stdio browser-bridge -- browser-bridge mcp
 ```
 
-Optional custom host/port (use `browser-bridge dev info` to get the current worktree port):
+Optional custom host/port override (only if you intentionally run Core somewhere else):
 
 ```bash
 claude mcp add --transport stdio browser-bridge \
   --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
-  --env BROWSER_BRIDGE_CORE_PORT=<port-from-dev-info> \
+  --env BROWSER_BRIDGE_CORE_PORT=<custom-port> \
   -- browser-bridge mcp
 ```
 
@@ -262,13 +293,12 @@ claude mcp add --transport stdio browser-bridge \
 
 ## ✅ Default Runtime (Normal Usage)
 
-For normal usage, Browser Bridge is zero-setup:
+Browser Bridge is now a single-runtime setup by default:
 
-- Core and CLI default to `127.0.0.1:3210`.
-- The extension also defaults to `3210`.
-- You do not need `dev activate` unless you intentionally opt into isolated worktree routing.
+- Core, CLI, and extension target `127.0.0.1:3210`.
+- You do not need any activation or routing step for normal use.
 - After reboot/cold start, the first CLI or MCP request auto-starts Core (no manual daemon wake-up required).
-- If Core is idle/offline, the extension popup may show `disconnected` or `backoff`; this is expected until Core is reachable again.
+- If Core is idle/offline, the extension popup may show `disconnected` or `backoff`; that just means Core is not reachable yet.
 
 Optional status check:
 
@@ -276,32 +306,18 @@ Optional status check:
 browser-bridge dev info --json
 ```
 
-## 🔁 Isolated Multi-Worktree Dev Loop (Advanced)
-
-Use this loop when you intentionally run multiple worktree instances in parallel.
-
-1. Resolve runtime for the current worktree:
+Use `browser-bridge dev enable-inspect` only as a quick diagnostics probe when you want to sanity-check debugger-backed inspect on the live runtime:
 
 ```bash
-browser-bridge dev info --json
+browser-bridge dev enable-inspect
 ```
 
-Use the `port`, `worktreeId`, `metadataPath`, and `logDir` from output.
-
-2. Activate isolated extension routing for this worktree:
-
-```bash
-browser-bridge dev activate --extension-id <id>
-```
-
-After the first run, you can usually omit `--extension-id` because it is saved in `.context/browser-bridge/dev.json`.
-
-3. Run your CLI/MCP workflow in this worktree.
+The helper verifies inspect capability against the live runtime and can also sanity-check a specific connected extension via `--extension-id <id>`. It does not flip inspect on through Core. The extension id may be cached in `.context/browser-bridge/dev.json` after a successful run, but that metadata is no longer a routing switch.
 
-## 🧯 Worktree Troubleshooting
+## 🧯 Runtime Troubleshooting
 
-- Missing extension id: Run `browser-bridge dev activate --extension-id <id>`. Or set `BROWSER_BRIDGE_EXTENSION_ID=<id>`. You can copy the id from `chrome://extensions` (enable Developer mode to see ids).
-- Activation URL did not open in Chrome: Run `browser-bridge dev activate --json`, copy `result.activationUrl`, and open it directly in Chrome. `dev activate` uses the OS URL opener, so your default browser setting matters.
+- Inspect capability still unavailable: restart the Browser Bridge core daemon, then reload or update the Browser Bridge extension and rerun `browser-bridge diagnostics doctor` plus `browser-bridge dev enable-inspect`.
+- Extension id mismatch while verifying inspect: rerun with the correct `--extension-id <id>` or clear `BROWSER_BRIDGE_EXTENSION_ID` if you pinned the wrong unpacked install. You can copy the id from `chrome://extensions` (enable Developer mode to see ids).
 - Logs and per-stream JSONL inspection: Logs are under `.context/logs/browser-bridge/`. Common streams: `cli.jsonl`, `core.jsonl`, `mcp-adapter.jsonl` (plus rotated files like `core.1.jsonl`).
 
 ```bash
@@ -311,7 +327,7 @@ tail -n 80 .context/logs/browser-bridge/core.jsonl
 tail -n 80 .context/logs/browser-bridge/mcp-adapter.jsonl
 ```
 
-- Default mode port is `3210`. In isolated mode, port is worktree-specific. Use `browser-bridge dev info` if you are unsure (or pass explicit `--port` / `BROWSER_BRIDGE_CORE_PORT`).
+- Default runtime is `127.0.0.1:3210`. If you are unsure, run `browser-bridge dev info` or pass explicit `--host` / `--port` overrides.
 
 ## 🩺 Diagnostics
 
@@ -322,7 +338,7 @@ tail -n 80 .context/logs/browser-bridge/mcp-adapter.jsonl
 
 ### End-to-End Connection Troubleshooting Flow
 
-Use this exact flow when commands fail after reboot, runtime changes, or worktree switching:
+Use this exact flow when commands fail after reboot or runtime changes:
 
 1. Check runtime resolution:
 
@@ -341,8 +357,8 @@ browser-bridge diagnostics doctor --json
    - Red dot: extension is disconnected or reconnecting.
 
 4. If caller/core/extension endpoints differ in the diagnostics report:
-   - Default mode: remove custom host/port env overrides and retry (`BROWSER_BRIDGE_CORE_HOST`, `BROWSER_BRIDGE_CORE_PORT`).
-   - Isolated mode: re-run `browser-bridge dev activate --extension-id <id>` for the intended worktree.
+   - Remove custom host/port env overrides and retry (`BROWSER_BRIDGE_CORE_HOST`, `BROWSER_BRIDGE_CORE_PORT`).
+   - If inspect capability is the missing piece, run `browser-bridge dev enable-inspect --extension-id <id>`.
 
 5. If the popup stays red and failures continue:
    - Inspect logs: