@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/.claude-plugin/plugin.json +9 -0
- package/README.md +127 -0
- package/dist/index.js +916 -0
- package/package.json +56 -0
- package/scripts/launch-chrome.sh +79 -0
- package/scripts/sync-plugin.sh +68 -0
- package/skills/browser/SKILL.md +201 -0
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.
|