@generativereality/browser-automation 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json ADDED
@@ -0,0 +1,56 @@
1
+ {
2
+ "name": "@generativereality/browser-automation",
3
+ "version": "0.3.0",
4
+ "description": "Daemonless, per-tab-isolated browser automation CLI for Claude Code. Drives one shared headed Chrome (persistent profile + extensions) over per-target CDP — many parallel sessions, no focus stealing, nothing long-lived to crash.",
5
+ "type": "module",
6
+ "bin": {
7
+ "browser-automation": "dist/index.js"
8
+ },
9
+ "files": [
10
+ "dist",
11
+ ".claude-plugin",
12
+ "skills",
13
+ "scripts"
14
+ ],
15
+ "scripts": {
16
+ "dev": "bun run ./src/index.ts",
17
+ "build": "tsdown",
18
+ "typecheck": "tsc --noEmit",
19
+ "check": "npm run typecheck && npm run build",
20
+ "release": "bumpp && npm publish",
21
+ "sync-plugin": "bash scripts/sync-plugin.sh",
22
+ "prepack": "npm run build"
23
+ },
24
+ "keywords": [
25
+ "claude-code",
26
+ "browser-automation",
27
+ "cdp",
28
+ "chrome-devtools-protocol",
29
+ "playwright-alternative",
30
+ "ai-agents"
31
+ ],
32
+ "author": "motin",
33
+ "license": "MIT",
34
+ "repository": {
35
+ "type": "git",
36
+ "url": "git+https://github.com/generativereality/browser-automation.git"
37
+ },
38
+ "homepage": "https://github.com/generativereality/browser-automation",
39
+ "engines": {
40
+ "node": ">=22.0.0"
41
+ },
42
+ "publishConfig": {
43
+ "registry": "https://registry.npmjs.org",
44
+ "access": "public"
45
+ },
46
+ "dependencies": {
47
+ "consola": "^3.4.0",
48
+ "gunshi": "^0.23.0"
49
+ },
50
+ "devDependencies": {
51
+ "@types/node": "^22.0.0",
52
+ "bumpp": "^9.11.1",
53
+ "tsdown": "^0.12.0",
54
+ "typescript": "^5.8.0"
55
+ }
56
+ }
@@ -0,0 +1,79 @@
1
+ #!/usr/bin/env bash
2
+ # Launch the canonical long-running headed Chrome that the browser-automation CLI drives via per-target CDP.
3
+ #
4
+ # Usage:
5
+ # ./scripts/launch-chrome.sh # launch if not already running
6
+ # ./scripts/launch-chrome.sh --status # exit 0 if a CDP browser is listening on :9223, else 1
7
+ #
8
+ # Why this script exists:
9
+ # The `browser-automation` skill prefers to drive a real, persistent Chrome
10
+ # profile (so logins survive reboots) over a Playwright-managed one. The
11
+ # convention is: one Chrome listening on --remote-debugging-port=9223 with
12
+ # a dedicated user-data-dir. The browser-automation CLI then drives it over per-target CDP. This script is the single source of truth for how
13
+ # to start that Chrome.
14
+ set -euo pipefail
15
+
16
+ PORT=9223
17
+ PROFILE="${BROWSER_AUTOMATION_PROFILE:-$HOME/Library/Application Support/Google/Chrome/browser-automation}"
18
+ LOG="${BROWSER_AUTOMATION_LOG:-/tmp/chrome-9223.log}"
19
+
20
+ is_up() {
21
+ curl -fs -o /dev/null "http://localhost:${PORT}/json/version"
22
+ }
23
+
24
+ if [ "${1:-}" = "--status" ]; then
25
+ if is_up; then
26
+ echo "Chrome CDP on :${PORT} is up"
27
+ exit 0
28
+ fi
29
+ echo "Chrome CDP on :${PORT} is NOT running"
30
+ exit 1
31
+ fi
32
+
33
+ if is_up; then
34
+ echo "Already running on :${PORT} — nothing to do."
35
+ echo "Drive it with: browser-automation goto -s <session> <url>"
36
+ exit 0
37
+ fi
38
+
39
+ # Resolve Chrome binary across macOS / Linux.
40
+ case "$(uname -s)" in
41
+ Darwin)
42
+ CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
43
+ ;;
44
+ Linux)
45
+ CHROME="$(command -v google-chrome || command -v google-chrome-stable || command -v chromium || true)"
46
+ ;;
47
+ *)
48
+ echo "Error: unsupported OS $(uname -s). Launch Chrome manually with --remote-debugging-port=${PORT} --user-data-dir=\"${PROFILE}\"." >&2
49
+ exit 1
50
+ ;;
51
+ esac
52
+
53
+ if [ ! -x "$CHROME" ]; then
54
+ echo "Error: Chrome not found. Install it (or set CHROME=... if it lives elsewhere)." >&2
55
+ exit 1
56
+ fi
57
+
58
+ mkdir -p "$(dirname "$PROFILE")"
59
+
60
+ nohup "$CHROME" \
61
+ --remote-debugging-port="$PORT" \
62
+ --user-data-dir="$PROFILE" \
63
+ --no-first-run \
64
+ --no-default-browser-check \
65
+ 'about:blank' >"$LOG" 2>&1 &
66
+ disown
67
+
68
+ # Wait briefly for CDP to come up so the caller can attach immediately.
69
+ for _ in $(seq 1 20); do
70
+ if is_up; then
71
+ echo "Chrome launched on :${PORT} (profile: ${PROFILE}, log: ${LOG})"
72
+ echo "Drive it with: browser-automation goto -s <session> <url>"
73
+ exit 0
74
+ fi
75
+ sleep 0.25
76
+ done
77
+
78
+ echo "Error: Chrome did not start within 5s. Check ${LOG}." >&2
79
+ exit 1
@@ -0,0 +1,68 @@
1
+ #!/usr/bin/env bash
2
+ # Sync browser-automation plugin files to the generativereality/plugins marketplace repo.
3
+ #
4
+ # Usage:
5
+ # ./scripts/sync-plugin.sh # sync + commit + push
6
+ # ./scripts/sync-plugin.sh --check # just verify
7
+ #
8
+ # Expects the plugins repo at ../plugins (alongside this repo).
9
+ set -euo pipefail
10
+
11
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
12
+ REPO_ROOT="$(dirname "$SCRIPT_DIR")"
13
+ PLUGINS_DIR="$REPO_ROOT/../plugins"
14
+ CHECK_ONLY=false
15
+ [ "${1:-}" = "--check" ] && CHECK_ONLY=true
16
+
17
+ if [ ! -d "$PLUGINS_DIR/.git" ]; then
18
+ echo "Error: plugins repo not found at $PLUGINS_DIR"
19
+ echo "Clone it: git clone <plugins-repo-url> $(cd "$REPO_ROOT/.." && pwd)/plugins"
20
+ exit 1
21
+ fi
22
+
23
+ ERRORS=0
24
+
25
+ # Files that ship inside the plugin payload. Relative to repo root.
26
+ PAYLOAD_FILES=(
27
+ "skills/browser/SKILL.md"
28
+ ".claude-plugin/plugin.json"
29
+ "scripts/launch-chrome.sh"
30
+ )
31
+
32
+ for rel in "${PAYLOAD_FILES[@]}"; do
33
+ if ! diff -q "$REPO_ROOT/$rel" "$PLUGINS_DIR/plugins/browser-automation/$rel" >/dev/null 2>&1; then
34
+ echo "MISMATCH: $rel differs from plugins repo"
35
+ ERRORS=1
36
+ fi
37
+ done
38
+
39
+ if [ "$CHECK_ONLY" = true ]; then
40
+ if [ "$ERRORS" -ne 0 ]; then
41
+ echo ""
42
+ echo "Run: ./scripts/sync-plugin.sh"
43
+ exit 1
44
+ fi
45
+ echo "Plugins repo in sync"
46
+ exit 0
47
+ fi
48
+
49
+ # Sync files
50
+ for rel in "${PAYLOAD_FILES[@]}"; do
51
+ mkdir -p "$(dirname "$PLUGINS_DIR/plugins/browser-automation/$rel")"
52
+ cp -p "$REPO_ROOT/$rel" "$PLUGINS_DIR/plugins/browser-automation/$rel"
53
+ done
54
+
55
+ # Remove .mcp.json from plugins repo if it lingers from an older sync (the plugin no longer ships an MCP server).
56
+ rm -f "$PLUGINS_DIR/plugins/browser-automation/.mcp.json"
57
+
58
+ cd "$PLUGINS_DIR"
59
+ if git diff --quiet; then
60
+ echo "Plugins repo already up to date"
61
+ exit 0
62
+ fi
63
+
64
+ git add plugins/browser-automation
65
+ git commit -m "chore: sync browser-automation plugin"
66
+ git push
67
+
68
+ echo "Synced browser-automation to plugins repo"
@@ -0,0 +1,201 @@
1
+ ---
2
+ name: browser
3
+ description: Drive a real browser from the shell via the `browser-automation` CLI — open pages, click, type, fill forms, read text, capture snapshots, all against one shared headed Chrome with a persistent profile (cookies + extensions survive). Daemonless and per-tab isolated, so many parallel Claude Code sessions can each drive their own tab without interfering. Use whenever you need to interact with a web page (especially behind a login) and there's no CLI or API that already covers the task.
4
+ allowed-tools: Bash(browser-automation:*) Bash(npm:*)
5
+ ---
6
+
7
+ # Browser automation via `browser-automation`
8
+
9
+ A plain CLI — no MCP server, **no daemon, nothing long-lived to crash**. Every
10
+ command is a fresh process that opens a short-lived CDP connection to **one tab**,
11
+ acts, and exits. State that must survive between calls lives in two durable
12
+ places, neither of which is a process: the user's Chrome, and a tiny per-session
13
+ file under `~/.browser-automation/sessions/`.
14
+
15
+ ## The model — read this first
16
+
17
+ - **One shared headed Chrome** on `--remote-debugging-port=9223` with a
18
+ persistent profile (`browser-automation`). Cookies, logins, and **browser
19
+ extensions (password managers, etc.) all persist** across runs and across
20
+ Claude Code restarts. The user can watch and complete interactive auth in the
21
+ same window.
22
+ - **Per-target CDP, not whole-browser.** The CLI talks to a single tab's
23
+ `webSocketDebuggerUrl`. It never does Playwright-style "connect to the whole
24
+ browser and enumerate every target" — so a stuck iframe/worker or a pile of
25
+ open tabs can never wedge it (the failure that made `playwright-cli` time out).
26
+ - **Address any tab on demand.** Every page command picks its tab three ways
27
+ (precedence `-t` > `-m` > `-s`):
28
+ - `-m <substr>` — any open tab whose **URL or title** contains the substring
29
+ (errors if ambiguous; `--first` to take the first). This is how you drive
30
+ tabs the user or another flow already opened — no setup needed.
31
+ - `-t <targetId>` — an exact tab (from `browser-automation list`).
32
+ - `-s <name>` — a saved **session** bookmark.
33
+ - **Sessions are optional bookmarks, not locks.** `-s <name>` just remembers a
34
+ `targetId` so you don't retype a selector; there's no 1-session-1-tab rule.
35
+ Bind a name to an already-open tab with `bind -s name -m <substr>`. Parallel
36
+ Claude Code sessions stay isolated by *convention* — each drives its own tab
37
+ (its own `-s` name or `-m` match) — but any tab is reachable on demand.
38
+ - **No focus stealing.** New tabs are created in the background; the CLI never
39
+ calls `Target.activateTarget` / `Page.bringToFront`. Your foreground app and
40
+ sibling sessions are left alone.
41
+ - **Self-healing.** If the tab was closed (or Chrome restarted and reissued
42
+ targetIds), the next `goto` just opens a fresh background tab for that session.
43
+ - **Refs live in the DOM.** `snapshot` stamps `data-ba-ref="e7"` onto each
44
+ interactive element and returns the list. A later `click e7` finds it by that
45
+ attribute. Because each invocation is a fresh process, **re-snapshot after any
46
+ action that changes the DOM** — refs from an old snapshot go stale, exactly
47
+ like Playwright refs.
48
+ - **Clicks/fills are JS-dispatched** (`element.click()`, native value setter +
49
+ `input`/`change` events). This works on background tabs, which native CDP
50
+ mouse events do not reliably reach in headed Chrome. Trade-off: dispatched
51
+ events are not `isTrusted`, so a few hard anti-bot / payment flows may reject
52
+ them (see Gotchas).
53
+
54
+ ## Setup (per machine)
55
+
56
+ ```bash
57
+ npm install -g @generativereality/browser-automation
58
+ browser-automation launch # start the canonical Chrome on :9223 (idempotent)
59
+ browser-automation doctor # verify Node, Chrome, targets, sessions
60
+ ```
61
+
62
+ `launch` is idempotent — safe to call when Chrome is already up. Override the
63
+ profile path with `BROWSER_AUTOMATION_PROFILE=...` and the CDP host with
64
+ `BROWSER_AUTOMATION_CDP=http://localhost:PORT` if needed.
65
+
66
+ ## Commands
67
+
68
+ Page commands take a tab selector — `-s <session>` (default `$BAC_SESSION`, else
69
+ `default`), `-m <url/title substr>`, or `-t <targetId>`.
70
+
71
+ | Need | Command |
72
+ |---|---|
73
+ | Start/refresh the Chrome | `browser-automation launch` |
74
+ | Diagnose setup | `browser-automation doctor` |
75
+ | List sessions + every open tab (id, title, url) | `browser-automation list` |
76
+ | Open a background tab | `browser-automation new -s work [url]` |
77
+ | Navigate (session tab created if needed) | `browser-automation goto -s work https://example.com` |
78
+ | Drive a tab the user already opened | `browser-automation snapshot -m nordnet` |
79
+ | Adopt an open tab into a session | `browser-automation bind -s bank -m nordnet` |
80
+ | List interactive elements (refs) | `browser-automation snapshot -m op.fi` |
81
+ | Click by ref | `browser-automation click -m op.fi e7` |
82
+ | Type into a field by ref | `browser-automation fill -s work e3 "value" [--submit]` |
83
+ | Read page text (or a selector) | `browser-automation read -m op.fi ['.balance']` |
84
+ | Evaluate JS in the tab (escape hatch) | `browser-automation eval -m op.fi 'document.title'` |
85
+ | Download a file / CSV export | `browser-automation download -m bank --click e42` (or `--url <href>`) |
86
+ | Forget a session (tab stays open) | `browser-automation close -s work` |
87
+ | Forget **and** close the browser tab | `browser-automation close -s work --tab` |
88
+
89
+ Typical loop:
90
+
91
+ ```bash
92
+ browser-automation goto -s work https://app.example.com/login
93
+ browser-automation snapshot -s work # -> e1 input, e2 input, e3 button …
94
+ browser-automation fill -s work e1 "user@example.com"
95
+ browser-automation fill -s work e2 "secret" --submit
96
+ browser-automation snapshot -s work # re-snapshot: DOM changed after submit
97
+ browser-automation read -s work '.account-balance'
98
+ ```
99
+
100
+ ## Parallel sessions — one per Claude Code tab
101
+
102
+ Give each session a distinct `-s` name and they never interfere. Either pass
103
+ `-s` every call, or set it once for the shell:
104
+
105
+ ```bash
106
+ export BAC_SESSION="$(basename "$PWD")" # every command in this shell uses it
107
+ browser-automation goto https://app.example.com
108
+ ```
109
+
110
+ Each session drives its own background tab in the same Chrome. No shared
111
+ connection, no id collisions, no active-tab fighting — that's the whole point of
112
+ the per-target model.
113
+
114
+ ## Auth-persistence — log in once, reuse forever
115
+
116
+ The persistent profile carries cookies and extensions, so for most sites you log
117
+ in once (interactively, in the headed window) and every later run just works:
118
+
119
+ ```bash
120
+ browser-automation goto -s cf https://dash.cloudflare.com
121
+ # user completes login in the Chrome window; cookies land in the profile
122
+ browser-automation read -s cf # later runs: already authenticated
123
+ ```
124
+
125
+ There's no `state-save`/`state-load` to manage — the profile *is* the auth store.
126
+
127
+ ## Gotchas
128
+
129
+ - **Refs go stale after any DOM change**, not just navigation. Snapshot → use
130
+ those refs for one action → re-snapshot. "ref not found" means re-snapshot.
131
+ - **`isTrusted` / synthetic events.** Clicks and fills are JS-dispatched, so a
132
+ small number of hard anti-bot or payment widgets that demand trusted events
133
+ may ignore them. For those, escalate to a foregrounded native-input path
134
+ (future `--native` flag) or have the user do that one step manually.
135
+ - **Cross-origin iframes are separate CDP targets.** `read`/`snapshot` see the
136
+ page's own document and same-origin frames, not cross-origin iframes (common
137
+ for SSO bank login widgets and embedded captchas). If the content you need
138
+ lives in a cross-origin iframe, it has its own `webSocketDebuggerUrl` — the
139
+ per-page CDP escape hatch below can read it directly.
140
+ - **Downloads.** `download` arms the CDP browser download API and waits for
141
+ completion, then reports the saved path (default `~/.browser-automation/downloads/`).
142
+ Trigger it with `--click <ref>` on the export link/button, or `--url <href>`
143
+ for a direct CSV endpoint (e.g. OP's `a[href*=csv.do]`). **Caveat:** a button
144
+ whose JS handler builds a client-side **blob** and clicks it via a *nested*
145
+ synthetic click won't fire (Chrome activation quirk) — for those, grab the
146
+ underlying export URL/endpoint and use `--url`, or the site's API.
147
+ - **Page still loading.** `goto` waits for the load event, but SPAs render after.
148
+ If a `read`/`snapshot` looks empty, re-run after a moment, or snapshot again
149
+ once a known element should be present.
150
+ - **`launch` is macOS/Linux only** (resolves the Chrome binary per-OS). On other
151
+ setups, start Chrome manually with `--remote-debugging-port=9223
152
+ --user-data-dir="<profile>"`.
153
+
154
+ ## Escape hatch — raw per-page CDP for pure scraping
155
+
156
+ When you just need to read a value out of a specific tab (no clicks), a raw
157
+ WebSocket to that tab's `webSocketDebuggerUrl` + `Runtime.evaluate` is the most
158
+ robust thing possible — it's exactly what this CLI does internally, and it works
159
+ even on tabs the CLI doesn't own. `browser-automation read` covers the common
160
+ case; drop to raw CDP only for cross-origin-iframe reads or one-off probes.
161
+
162
+ ## Hit a shortcoming or bug? Fix it — it's open source
163
+
164
+ This CLI is `@generativereality/browser-automation` (repo:
165
+ `github.com/generativereality/browser-automation`). When you hit a missing
166
+ capability or a bug (a site needs something the CLI can't do yet, an export
167
+ won't trigger, a selector strategy fails), **fix it at the source rather than
168
+ working around it forever**:
169
+
170
+ 1. **Clone** next to your work: `gh repo clone generativereality/browser-automation`
171
+ (or `git clone https://github.com/generativereality/browser-automation`).
172
+ 2. **Fix** in `src/` — TypeScript. Commands live in `src/commands/<name>.ts`,
173
+ the daemonless CDP core in `src/core/` (`cdp.ts` connection/eval/navigate,
174
+ `dom.ts` injected snapshot/click/read JS, `download.ts`, `resolve.ts` tab
175
+ selection). Add a command by creating `src/commands/x.ts` and registering it
176
+ in `src/commands/index.ts`.
177
+ 3. **Validate locally** against the running Chrome:
178
+ `npm install && npm run typecheck && npm run build`, then `npm link` (so the
179
+ global `browser-automation` points at your build) — or run `node dist/index.js …`.
180
+ Reproduce the failure, confirm the fix, and re-test on a scratch tab you
181
+ created (read-only-safe; never disrupt the user's live tabs).
182
+ 4. **Propose a PR** for the user to review and contribute upstream — don't
183
+ publish yourself (the maintainer cuts releases):
184
+ ```bash
185
+ git checkout -b fix/<short-desc>
186
+ git commit -am "fix: <what and why>"
187
+ gh pr create --fill --repo generativereality/browser-automation
188
+ ```
189
+ Then tell the user the branch/PR link and what it changes, and ask them to
190
+ review and merge. After it's released, `npm install -g @generativereality/browser-automation@latest`.
191
+
192
+ ## Troubleshooting
193
+
194
+ - **`No CDP browser on http://localhost:9223`** → `browser-automation launch`.
195
+ - **`command not found: browser-automation`** → `npm install -g @generativereality/browser-automation`.
196
+ - **Chrome was restarted** → nothing to do; the next `goto` recreates the
197
+ session's tab automatically (sessions self-heal; `list` shows `stale`).
198
+ - **A login wall on a repeat run** → the profile lost cookies (rare) or the site
199
+ logged you out; just log in again in the headed window.
200
+ - **CAPTCHA / bot challenge** → expected on heavily-protected sites; pause for the
201
+ user, or fall back to a vendor API/CLI if one exists.