@rezkam/browser-tools 1.0.3 → 1.1.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/CHANGELOG.md +14 -0
- package/README.md +95 -48
- package/bin/browser-tools.mjs +2 -0
- package/package.json +4 -2
- package/scripts/browser-control.mjs +265 -39
- package/scripts/browser-platform.mjs +96 -0
- package/scripts/serve.mjs +42 -0
- package/scripts/stop.mjs +3 -3
- package/scripts/tab-broker.mjs +351 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,19 @@
|
|
|
1
1
|
# @rezkam/browser-tools
|
|
2
2
|
|
|
3
|
+
## 1.1.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 0fcffe1: Support native Linux Chrome/Chromium discovery, profile locations, headless diagnostics and platform-correct user agents while retaining Puppeteer and owner-protected lifecycle contracts. Verify fixed-port endpoints against launch arguments, read Linux process identity through procfs, and add Linux/macOS browser smoke CI.
|
|
8
|
+
- e7a80e3: Add `browser-tools serve`, a tab broker that runs one lean Chrome for every client on a machine and hands out at most `--max-tabs` tabs at a time (default 4), each in its own browser context and taken back after `--tab-seconds` (default 120). A lease is an open HTTP request, so a client that exits gives its tab back. With `--proxy-server`, every request goes through the proxy, loopback and WebRTC included. The broker logs Chrome's memory by process type and every lease as JSON lines. `leaseTab` and `serveTabs` are exported from `@rezkam/browser-tools/tab-broker.mjs`, and `connectLeasedTab` connects to a leased tab.
|
|
9
|
+
|
|
10
|
+
## 1.0.4
|
|
11
|
+
|
|
12
|
+
### Patch Changes
|
|
13
|
+
|
|
14
|
+
- 2ef608b: Automatically reclaim managed Chrome sessions that have run for two hours after their recorded launcher exits. Record immutable launcher process identity to detect PID reuse, keep live launchers protected regardless of age, and run the fail-safe reap before enforcing the browser limit.
|
|
15
|
+
- e453b80: Skip local ports occupied by non-CDP processes during automatic managed Chrome allocation, and verify that the process responding after launch is the managed Chrome that was started.
|
|
16
|
+
|
|
3
17
|
## 1.0.3
|
|
4
18
|
|
|
5
19
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,97 +1,144 @@
|
|
|
1
1
|
# @rezkam/browser-tools
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Managed Chrome automation with isolated profiles and owner-protected sessions. Browser Tools can drive pages, inspect the DOM, capture visual and network evidence, and extract page content without connecting to or stopping your main Chrome.
|
|
4
4
|
|
|
5
|
-
This repository
|
|
5
|
+
This repository provides both the `browser-tools` skill and the `@rezkam/browser-tools` npm package. The skill uses the same CLI that the package installs.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## Features
|
|
8
|
+
|
|
9
|
+
- **Isolated browser sessions:** launch windowed or headless Chrome with a fresh profile or a copied Chrome profile, including existing site sessions and extensions.
|
|
10
|
+
- **Safe lifecycle management:** every managed browser has an owner token. Browser Tools verifies process identity before connecting or stopping, limits concurrent browsers, and automatically reclaims old sessions after their recorded launcher exits.
|
|
11
|
+
- **Page control and inspection:** navigate tabs, evaluate asynchronous JavaScript, take viewport or full-page screenshots, and interactively pick single or multiple DOM elements.
|
|
12
|
+
- **Page extraction:** collect article-like links and nearby timestamps, or extract readable article text from the active tab.
|
|
13
|
+
- **Visual evidence:** record an active-tab interaction as a GIF, then generate a sampled contact sheet and JSON metadata for review.
|
|
14
|
+
- **Network and protocol tooling:** capture filtered HAR 1.2 traffic, extract a chronological request recipe, record selected raw CDP events, and send guarded CDP calls to the active tab.
|
|
15
|
+
- **Local profile configuration:** discover Chrome profiles, create private aliases, and associate one or more profiles with a task.
|
|
8
16
|
|
|
9
|
-
|
|
17
|
+
## Install
|
|
10
18
|
|
|
11
|
-
|
|
19
|
+
Install the skill when Browser Tools should be discoverable as an automation skill:
|
|
12
20
|
|
|
13
21
|
```bash
|
|
14
22
|
npx skills add rezkam/browser-tools
|
|
15
23
|
```
|
|
16
24
|
|
|
17
|
-
|
|
25
|
+
Install the package for the global CLI and programmatic exports:
|
|
18
26
|
|
|
19
27
|
```bash
|
|
20
28
|
npm install -g @rezkam/browser-tools
|
|
21
29
|
```
|
|
22
30
|
|
|
23
|
-
|
|
31
|
+
Commands can also run without a global install:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx @rezkam/browser-tools <command>
|
|
35
|
+
```
|
|
24
36
|
|
|
25
|
-
GIF recording and review
|
|
37
|
+
Browser Tools requires macOS or Linux, installed Google Chrome or Chromium, and Node.js 20 or newer. GIF recording and review additionally require `ffmpeg` and `ffprobe`:
|
|
26
38
|
|
|
27
39
|
```bash
|
|
28
40
|
brew install ffmpeg
|
|
29
41
|
```
|
|
30
42
|
|
|
31
|
-
##
|
|
43
|
+
## Linux
|
|
32
44
|
|
|
33
|
-
|
|
45
|
+
Linux discovers executable Chrome/Chromium launchers on PATH and common distro locations, including the normal snap launcher. Explicit `BROWSER_TOOLS_CHROME_BIN` or `browser.chromeBin` config wins; no browser or OS packages are installed automatically. Use `browser-tools start --headless` without a display; headed mode needs a working X11 or Wayland session. Chromium sandboxing stays enabled. Root, containers, or restrictive AppArmor/user-namespace policies may need operator setup, never an automatic `--no-sandbox` fallback.
|
|
46
|
+
|
|
47
|
+
Profile discovery follows the selected browser family/channel under `${XDG_CONFIG_HOME:-~/.config}` (`google-chrome`, `google-chrome-beta`, `google-chrome-unstable`, or `chromium`); snap Chromium uses `~/snap/chromium/common/chromium`. Override with `BROWSER_TOOLS_CHROME_SOURCE_DIR` or `directories.chromeSourceDir`. `browser-tools config profiles` enumerates Local State into private local config.
|
|
48
|
+
|
|
49
|
+
Profile copying requires `rsync` and `sqlite3` (for default Google identity exclusion). Close the source browser before copying for a consistent snapshot; copying a live SQLite database is not an atomic backup. Copies stay private and source locks are never removed. Run as the same OS user, browser family, and unlocked desktop secret-store session: copied cookies may not decrypt without the original Libsecret/KWallet keyring or D-Bus session. Browser Tools never switches to basic password storage or promises portable logins. Extensions depend on Chromium build/policy and are not guaranteed merely because their files were copied.
|
|
50
|
+
|
|
51
|
+
Snap confinement may deny the default cache or artifact paths. Set `BROWSER_TOOLS_CACHE_DIR` and `BROWSER_TOOLS_ARTIFACT_DIR` to private locations permitted by the installed snap; do not bypass confinement by automatically invoking internal snap executables. Snap launcher discovery is supported, but distro-specific confinement/refresh/keyring behavior requires host validation. Flatpak, Windows, encrypted login migration across users/hosts, and extension execution are not covered by the native compatibility guarantee.
|
|
52
|
+
|
|
53
|
+
Local verification covers sandboxed Linux ARM64 Chromium navigation, eval, screenshots, ownership rejection, fixed-port endpoint identity and cleanup. CI runs unit/contracts and fresh-browser smoke on Linux and macOS (direct executable on hosted macOS); native NSWorkspace routing has a fixture contract, not a real desktop Dock/keychain validation. Real keyrings, headed Linux, snap confinement, and extensions require separate environment-specific verification. Puppeteer API and CLI contracts are retained; no Patchright migration is included.
|
|
54
|
+
|
|
55
|
+
## Quick start
|
|
34
56
|
|
|
35
57
|
```bash
|
|
36
|
-
browser-tools start --
|
|
58
|
+
browser-tools start --headless
|
|
37
59
|
export BROWSER_TOOLS_OWNER_TOKEN="<owner token from start output>"
|
|
38
|
-
|
|
60
|
+
|
|
39
61
|
browser-tools nav https://example.com --port <reported port>
|
|
40
62
|
browser-tools eval 'document.title' --port <reported port>
|
|
41
63
|
browser-tools screenshot --full --port <reported port>
|
|
42
|
-
|
|
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>
|
|
53
|
-
browser-tools pick "Click the price" --port <reported port>
|
|
54
|
-
browser-tools scrape-page --port <reported port>
|
|
55
|
-
browser-tools extract-article --chars 6000 --port <reported port>
|
|
64
|
+
|
|
56
65
|
browser-tools stop --clean --port <reported port>
|
|
57
|
-
browser-tools config task-profile set <task> --profile "<alias>"
|
|
58
66
|
```
|
|
59
67
|
|
|
60
|
-
|
|
68
|
+
Use `--profile "<profile or alias>"` when an existing login is needed, `--sync` to refresh the copied profile, or `--task <task>` to use configured task profiles.
|
|
69
|
+
|
|
70
|
+
## CLI capabilities
|
|
71
|
+
|
|
72
|
+
| Area | Commands | What they do |
|
|
73
|
+
| --- | --- | --- |
|
|
74
|
+
| Browser lifecycle | `start`, `status`, `stop` | Launch, inspect, stop, clean, reap, and prune managed Chrome sessions |
|
|
75
|
+
| Profile configuration | `config` | Discover profiles, list active profiles, and manage task-to-profile mappings |
|
|
76
|
+
| Page control | `nav`, `eval`, `screenshot` | Navigate the active tab or a new background tab, run page JavaScript, and capture PNG screenshots |
|
|
77
|
+
| DOM inspection | `pick` | Select one or more visible elements and return tag, id, class, text, HTML, and parent information |
|
|
78
|
+
| Page extraction | `scrape-page`, `extract-article` | Extract article-like links with timestamps or readable article text from the active tab |
|
|
79
|
+
| Visual recording | `record-gif`, `review-gif` | Record an interaction with pre-roll and post-roll frames, then create a contact sheet and metadata report |
|
|
80
|
+
| HTTP capture | `record-har`, `extract-har` | Capture filtered active-tab traffic and derive a compact, non-executable request recipe |
|
|
81
|
+
| Chrome DevTools Protocol | `record-cdp`, `cdp` | Record selected raw protocol events or send one guarded direct method call |
|
|
82
|
+
| Shared tabs | `serve` | Run one lean Chrome for every client on the machine and lease its tabs, a bounded number at a time, each for a bounded time |
|
|
83
|
+
|
|
84
|
+
Run `browser-tools --help` for the command list. Commands with detailed option references, such as `record-har`, `record-cdp`, and `review-gif`, also support command-level `--help`.
|
|
85
|
+
|
|
86
|
+
## Safety model
|
|
87
|
+
|
|
88
|
+
- Managed Chrome always uses a separate user data directory. Copied profiles are snapshots and never run against the live Chrome profile.
|
|
89
|
+
- Commands that connect to Chrome or stop an owned browser require the owner token printed by `start`. The token protects browser control, recordings, network capture, CDP access, and shutdown.
|
|
90
|
+
- Google identity data is removed from copied profiles by default to protect the source session. `--include-google` is an explicit opt-in for Google-backed workflows.
|
|
91
|
+
- Starting without an explicit port can reuse a browser already owned by the caller or allocate another available port. The default concurrent browser limit is five.
|
|
92
|
+
- A managed browser older than two hours becomes reclaimable after its recorded launcher exits. The next start reaps it before enforcing the concurrency limit, while browsers with live launchers remain protected regardless of age.
|
|
93
|
+
- HAR files, extracted recipes, raw CDP events, and GIF review artifacts are written as private local files. Network and protocol output preserves exact evidence by default, with `--redact` available when sensitive values are not needed.
|
|
94
|
+
- `extract-har` only describes captured requests. It does not execute or replay them. Known direct CDP methods that bypass managed-browser lifecycle controls are blocked.
|
|
95
|
+
|
|
96
|
+
Browser Tools stores local configuration under `~/.agents/browser-tools` and managed profiles under `~/.cache/pi-browser-tools`. Timestamped artifacts such as screenshots default to the system temporary directory, while derived outputs such as HAR recipes and GIF reviews stay beside their input files. The documented `BROWSER_TOOLS_*` environment variables override configurable locations.
|
|
97
|
+
|
|
98
|
+
For detailed ownership rules, profile behavior, capture filters, and command options, see the repository's [SKILL.md](https://github.com/rezkam/browser-tools/blob/main/SKILL.md) and [Browser Control reference](https://github.com/rezkam/browser-tools/blob/main/references/browser-control.md).
|
|
61
99
|
|
|
62
100
|
## Programmatic use
|
|
63
101
|
|
|
64
102
|
```js
|
|
65
|
-
import { connectBrowser,
|
|
103
|
+
import { activePage, connectBrowser, startChrome, stopChrome, withBrowser } from '@rezkam/browser-tools';
|
|
104
|
+
import { runBrowserResource } from '@rezkam/browser-tools/resource-helper.mjs';
|
|
66
105
|
```
|
|
67
106
|
|
|
68
|
-
|
|
107
|
+
The root package export and `@rezkam/browser-tools/browser-control.mjs` both expose the browser lifecycle and connection module. The resource helper export provides the shared lifecycle for generic extractors.
|
|
108
|
+
|
|
109
|
+
### Shared tabs
|
|
69
110
|
|
|
70
|
-
|
|
111
|
+
`browser-tools serve` starts a tab broker and prints `{"url": ...}` once it listens. Chrome starts with the first lease, without extensions, component apps, a startup window or background networking.
|
|
71
112
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
113
|
+
```js
|
|
114
|
+
import { connectLeasedTab } from '@rezkam/browser-tools';
|
|
115
|
+
import { leaseTab } from '@rezkam/browser-tools/tab-broker.mjs';
|
|
116
|
+
|
|
117
|
+
const lease = await leaseTab(brokerUrl, { client: 'quotes' });
|
|
118
|
+
const { browser, page } = await connectLeasedTab(lease);
|
|
119
|
+
try {
|
|
120
|
+
await page.goto('https://example.com/');
|
|
121
|
+
} finally {
|
|
122
|
+
await browser.disconnect();
|
|
123
|
+
lease.release();
|
|
124
|
+
}
|
|
125
|
+
```
|
|
82
126
|
|
|
83
|
-
|
|
127
|
+
- At most `--max-tabs` tabs (default 4) are leased at once; later leases wait in order.
|
|
128
|
+
- Each tab has a browser context of its own, so tabs share no cookies or storage, and downloads are refused.
|
|
129
|
+
- A tab is taken back after `--tab-seconds` (default 120), and `lease.ended` then settles with `'expired'`. A client that exits gives its tab back, because a lease is an open HTTP request.
|
|
130
|
+
- With `--proxy-server`, every request goes through the proxy, loopback addresses and WebRTC included.
|
|
131
|
+
- `--until-stdin-closes` stops the broker, and its Chrome, when the parent holding its stdin goes away.
|
|
132
|
+
- On Linux the broker logs Chrome's memory every 15 seconds as a `browser_memory` JSON line on stderr (proportional set size by process type), and each finished lease as a `tab_lease` line with its wait, hold time and how it ended.
|
|
84
133
|
|
|
85
|
-
##
|
|
134
|
+
## Development
|
|
86
135
|
|
|
87
136
|
```bash
|
|
88
|
-
npm test #
|
|
89
|
-
npm run test:e2e # Real
|
|
90
|
-
npm run validate #
|
|
137
|
+
npm test # Unit and CLI contract tests
|
|
138
|
+
npm run test:e2e # Real Chrome and ffmpeg integration tests
|
|
139
|
+
npm run validate # Full validation suite
|
|
91
140
|
```
|
|
92
141
|
|
|
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
|
-
|
|
95
142
|
## License
|
|
96
143
|
|
|
97
144
|
Apache-2.0
|
package/bin/browser-tools.mjs
CHANGED
|
@@ -23,6 +23,7 @@
|
|
|
23
23
|
* browser-tools scrape-page [--port <n>]
|
|
24
24
|
* browser-tools extract-article [--chars <n>] [--port <n>]
|
|
25
25
|
* browser-tools config profiles|active-profiles|task-profile ...
|
|
26
|
+
* browser-tools serve [--max-tabs <n>] [--tab-seconds <n>] [--headless] [--proxy-server <url>] [--until-stdin-closes]
|
|
26
27
|
*/
|
|
27
28
|
|
|
28
29
|
import { spawnSync } from 'node:child_process';
|
|
@@ -49,6 +50,7 @@ const COMMANDS = {
|
|
|
49
50
|
'scrape-page': 'scrape-page.mjs',
|
|
50
51
|
'extract-article': 'extract-article.mjs',
|
|
51
52
|
config: 'config.mjs',
|
|
53
|
+
serve: 'serve.mjs',
|
|
52
54
|
};
|
|
53
55
|
|
|
54
56
|
function printUsage() {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rezkam/browser-tools",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.1.0",
|
|
4
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",
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
".": "./scripts/browser-control.mjs",
|
|
23
23
|
"./browser-control.mjs": "./scripts/browser-control.mjs",
|
|
24
24
|
"./resource-helper.mjs": "./scripts/resource-helper.mjs",
|
|
25
|
+
"./tab-broker.mjs": "./scripts/tab-broker.mjs",
|
|
25
26
|
"./package.json": "./package.json"
|
|
26
27
|
},
|
|
27
28
|
"files": [
|
|
@@ -41,7 +42,8 @@
|
|
|
41
42
|
"validate": "npm test && npm run test:e2e"
|
|
42
43
|
},
|
|
43
44
|
"dependencies": {
|
|
44
|
-
"puppeteer-core": "^24.42.0"
|
|
45
|
+
"puppeteer-core": "^24.42.0",
|
|
46
|
+
"ws": "^8.22.0"
|
|
45
47
|
},
|
|
46
48
|
"devDependencies": {
|
|
47
49
|
"@changesets/cli": "^2.31.0"
|