@btraut/browser-bridge 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -6,6 +6,37 @@ The format is based on "Keep a Changelog", and this project adheres to Semantic
 
 ## [Unreleased]
 
+## [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
+
+- Maintenance patch release for `0.13.2`.
+
+### Fixed
+
+- MCP adapter readiness tests now model POST/GET health probing correctly, preventing false failures when daemon auto-start is enabled.
+
 ## [0.13.1] - 2026-02-18
 
 ### Fixed

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,8 @@ 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.
+
 4. Try it:
 
 ```text
@@ -106,7 +112,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 +130,7 @@ 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.
+- `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>
 
@@ -206,8 +212,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 skills/browser-bridge ~/.agents/skills/browser-bridge
+# cp -R 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 +240,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 +255,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 +268,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 +281,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:
-
-```bash
-browser-bridge dev info --json
-```
-
-Use the `port`, `worktreeId`, `metadataPath`, and `logDir` from output.
-
-2. Activate isolated extension routing for this 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 activate --extension-id <id>
+browser-bridge dev enable-inspect
 ```
 
-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 +302,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 +313,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 +332,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: