@rezkam/browser-tools 0.2.1 → 1.0.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/README.md +33 -1
- package/bin/browser-tools.mjs +12 -0
- package/package.json +4 -3
- package/scripts/browser-control.mjs +774 -74
- package/scripts/cdp-common.mjs +309 -0
- package/scripts/cdp-event-capture.mjs +139 -0
- package/scripts/cdp-recording-state.mjs +160 -0
- package/scripts/cdp.mjs +111 -0
- package/scripts/extract-har.mjs +227 -0
- package/scripts/gif-recorder.mjs +451 -0
- package/scripts/har-capture.mjs +485 -0
- package/scripts/record-cdp.mjs +261 -0
- package/scripts/record-gif.mjs +234 -0
- package/scripts/record-har.mjs +270 -0
- package/scripts/review-gif.mjs +203 -0
- package/scripts/start.mjs +2 -2
- package/scripts/stop.mjs +60 -5
package/README.md
CHANGED
|
@@ -22,6 +22,12 @@ npm install -g @rezkam/browser-tools
|
|
|
22
22
|
|
|
23
23
|
This installs a global `browser-tools` command (via the package's `bin` entry) and, for programmatic use, exports the browser control module. If you would rather not install it globally, run any command through `npx @rezkam/browser-tools <subcommand>` instead.
|
|
24
24
|
|
|
25
|
+
GIF recording and review also require ffmpeg and its ffprobe tool:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
brew install ffmpeg
|
|
29
|
+
```
|
|
30
|
+
|
|
25
31
|
## CLI
|
|
26
32
|
|
|
27
33
|
Each subcommand dispatches to the matching script unchanged; flags are the same as the underlying script.
|
|
@@ -33,6 +39,17 @@ browser-tools status --port <reported port> # report whether it's running
|
|
|
33
39
|
browser-tools nav https://example.com --port <reported port>
|
|
34
40
|
browser-tools eval 'document.title' --port <reported port>
|
|
35
41
|
browser-tools screenshot --full --port <reported port>
|
|
42
|
+
browser-tools record-gif start --output "$PWD/login_process.gif" --port <reported port>
|
|
43
|
+
# Perform the multi-step interaction.
|
|
44
|
+
browser-tools record-gif stop --port <reported port>
|
|
45
|
+
browser-tools review-gif "$PWD/login_process.gif"
|
|
46
|
+
browser-tools record-har start --output "$PWD/checkout_api_network.har" --preset api --port <reported port>
|
|
47
|
+
# Perform the browser interaction, then stop and extract a non-executable recipe.
|
|
48
|
+
browser-tools record-har stop --port <reported port>
|
|
49
|
+
browser-tools extract-har "$PWD/checkout_api_network.har"
|
|
50
|
+
browser-tools record-cdp start --output "$PWD/checkout_network_events.jsonl" --domain Network --event 'Network.*' --port <reported port>
|
|
51
|
+
browser-tools record-cdp stop --port <reported port>
|
|
52
|
+
browser-tools cdp call Runtime.evaluate --params '{"expression":"document.title"}' --port <reported port>
|
|
36
53
|
browser-tools pick "Click the price" --port <reported port>
|
|
37
54
|
browser-tools scrape-page --port <reported port>
|
|
38
55
|
browser-tools extract-article --chars 6000 --port <reported port>
|
|
@@ -55,11 +72,26 @@ import { connectBrowser, activePage, withBrowser } from '@rezkam/browser-tools';
|
|
|
55
72
|
- Headless (`--headless`) runs full Chrome (`--headless=new`), not the legacy no-extensions engine, so profile, cookies, and extensions load the same as a windowed launch.
|
|
56
73
|
- Profile Sync excludes the Google identity from a copied profile by default, so a clone cannot log your main Chrome out of Google; pass `--include-google` only for Google-backed workflows.
|
|
57
74
|
- Every managed browser is owned by a token printed at `start`; `stop` refuses to kill a browser it does not own, another agent's browser, or your main Chrome.
|
|
75
|
+
- GIF recording requires an explicit action-specific output name. `start` captures pre-action frames before returning, and `stop` captures post-action frames before finalizing the GIF.
|
|
76
|
+
- `review-gif` probes frame count, duration, frame rate, and dimensions, then creates a sampled contact sheet and JSON report under the GIF's owner-only `.gif-review/` directory.
|
|
77
|
+
- `record-har` captures owner-protected filtered active-tab HTTP traffic as private HAR 1.2. `extract-har` derives a compact chronological recipe without executing requests. WebSocket handshakes and frames require `record-cdp`.
|
|
78
|
+
- `record-cdp` writes selected raw protocol events as private JSONL. `cdp call` sends one owner-protected active-tab method while blocking known managed-lifecycle bypasses.
|
|
79
|
+
- HAR, recipes, raw CDP events, and direct results preserve exact debugging evidence by default. Add `--redact` to filter sensitive-looking values. Capture files are owner-only `0600`, not encrypted.
|
|
58
80
|
- Config, cache, and artifact directories default to `~/.agents/browser-tools/config.json`, `~/.cache/pi-browser-tools`, and `/tmp`, overridable via `BROWSER_TOOLS_CONFIG_DIR`, `BROWSER_TOOLS_CACHE_DIR`, `BROWSER_TOOLS_ARTIFACT_DIR`, `BROWSER_TOOLS_CHROME_SOURCE_DIR`, and `BROWSER_TOOLS_CHROME_BIN`.
|
|
59
|
-
- Requires macOS Chrome and Node.js 20+.
|
|
81
|
+
- Requires macOS Chrome and Node.js 20+. GIF recording and review require ffmpeg and ffprobe.
|
|
60
82
|
|
|
61
83
|
For the full behavior reference (profile sync internals, ownership rules, stop safety checks, gotchas), see the skill docs in the source repository: [SKILL.md](https://github.com/rezkam/boring-but-good/blob/main/browser-tools/SKILL.md) and [references/browser-control.md](https://github.com/rezkam/boring-but-good/blob/main/browser-tools/references/browser-control.md).
|
|
62
84
|
|
|
85
|
+
## Testing
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
npm test # Fast unit and CLI contract tests
|
|
89
|
+
npm run test:e2e # Real headless Chrome and ffmpeg GIF interaction test
|
|
90
|
+
npm run validate # Both suites
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The E2E tests use real Chrome, ffmpeg, and ffprobe against local isolated fixtures. GIF tests validate recording, private output, and contact-sheet review. Network tests validate raw filtered HAR capture, optional recipe redaction, raw wildcard CDP events, direct CDP calls, owner-token refusal, private file modes, hard event limits, and lifecycle-method blocking. They do not use a live account or external server.
|
|
94
|
+
|
|
63
95
|
## License
|
|
64
96
|
|
|
65
97
|
Apache-2.0
|
package/bin/browser-tools.mjs
CHANGED
|
@@ -13,6 +13,12 @@
|
|
|
13
13
|
* browser-tools nav <url> [--new] [--port <n>]
|
|
14
14
|
* browser-tools eval '<javascript>' [--port <n>]
|
|
15
15
|
* browser-tools screenshot [--full] [--port <n>]
|
|
16
|
+
* browser-tools record-gif start|status|stop [options]
|
|
17
|
+
* browser-tools review-gif <meaningful.gif> [options]
|
|
18
|
+
* browser-tools record-har start|status|stop [options]
|
|
19
|
+
* browser-tools extract-har <capture.har> [options]
|
|
20
|
+
* browser-tools record-cdp start|status|stop [options]
|
|
21
|
+
* browser-tools cdp call <Domain.method> [options]
|
|
16
22
|
* browser-tools pick "<instruction>" [--port <n>]
|
|
17
23
|
* browser-tools scrape-page [--port <n>]
|
|
18
24
|
* browser-tools extract-article [--chars <n>] [--port <n>]
|
|
@@ -33,6 +39,12 @@ const COMMANDS = {
|
|
|
33
39
|
nav: 'nav.mjs',
|
|
34
40
|
eval: 'eval.mjs',
|
|
35
41
|
screenshot: 'screenshot.mjs',
|
|
42
|
+
'record-gif': 'record-gif.mjs',
|
|
43
|
+
'review-gif': 'review-gif.mjs',
|
|
44
|
+
'record-har': 'record-har.mjs',
|
|
45
|
+
'extract-har': 'extract-har.mjs',
|
|
46
|
+
'record-cdp': 'record-cdp.mjs',
|
|
47
|
+
cdp: 'cdp.mjs',
|
|
36
48
|
pick: 'pick.mjs',
|
|
37
49
|
'scrape-page': 'scrape-page.mjs',
|
|
38
50
|
'extract-article': 'extract-article.mjs',
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rezkam/browser-tools",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Sandboxed, owner-token-protected Chrome automation for AI agents:
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Sandboxed, owner-token-protected Chrome automation for AI agents: control pages, record and review GIFs, capture HAR and raw CDP events, send CDP calls, and manage Chrome profiles.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "Apache-2.0",
|
|
7
7
|
"repository": {
|
|
@@ -32,8 +32,9 @@
|
|
|
32
32
|
},
|
|
33
33
|
"scripts": {
|
|
34
34
|
"test": "node --test test/*.mjs",
|
|
35
|
+
"test:e2e": "node --test --test-concurrency=1 test/e2e/*.test.mjs",
|
|
35
36
|
"coverage": "node --test --experimental-test-coverage test/*.mjs",
|
|
36
|
-
"validate": "npm test"
|
|
37
|
+
"validate": "npm test && npm run test:e2e"
|
|
37
38
|
},
|
|
38
39
|
"dependencies": {
|
|
39
40
|
"puppeteer-core": "^24.42.0"
|