@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 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
@@ -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.2.1",
4
- "description": "Sandboxed, owner-token-protected Chrome automation for AI agents: launch, navigate, evaluate, screenshot, and manage Chrome profiles from a CLI or programmatically.",
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"