@rezkam/browser-tools 0.2.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 +65 -0
- package/bin/browser-tools.mjs +71 -0
- package/package.json +41 -0
- package/scripts/browser-control.mjs +1450 -0
- package/scripts/browser-query-cache.mjs +154 -0
- package/scripts/config.mjs +142 -0
- package/scripts/eval.mjs +83 -0
- package/scripts/extract-article.mjs +69 -0
- package/scripts/nav.mjs +38 -0
- package/scripts/pick.mjs +213 -0
- package/scripts/resource-helper.mjs +143 -0
- package/scripts/scrape-page.mjs +127 -0
- package/scripts/screenshot.mjs +25 -0
- package/scripts/start.mjs +49 -0
- package/scripts/status.mjs +51 -0
- package/scripts/stop.mjs +71 -0
package/README.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# @rezkam/browser-tools
|
|
2
|
+
|
|
3
|
+
Sandboxed, owner-token-protected Chrome automation for AI agents: launch a managed Chrome with a copied profile, navigate, evaluate page JavaScript, screenshot, and stop it safely, all without touching your main Chrome.
|
|
4
|
+
|
|
5
|
+
This package is the npm-installable form of the `browser-tools` skill in [boring-but-good](https://github.com/rezkam/boring-but-good/tree/main/browser-tools). The skill itself now drives this package's CLI, so there is one supported way to run Browser Tools whether you got here through the skill or through npm directly.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
Two independent installs, pick what you need:
|
|
10
|
+
|
|
11
|
+
**The skill** (for an agent that should discover and use Browser Tools as a skill):
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npx skills add rezkam/boring-but-good --skill browser-tools
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
**The package/CLI** (what the skill depends on, and what any project can depend on directly):
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g @rezkam/browser-tools
|
|
21
|
+
```
|
|
22
|
+
|
|
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
|
+
|
|
25
|
+
## CLI
|
|
26
|
+
|
|
27
|
+
Each subcommand dispatches to the matching script unchanged; flags are the same as the underlying script.
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
browser-tools start --task <task> --headless # launch, prints an owner token on first start
|
|
31
|
+
export BROWSER_TOOLS_OWNER_TOKEN="<owner token from start output>"
|
|
32
|
+
browser-tools status --port <reported port> # report whether it's running
|
|
33
|
+
browser-tools nav https://example.com --port <reported port>
|
|
34
|
+
browser-tools eval 'document.title' --port <reported port>
|
|
35
|
+
browser-tools screenshot --full --port <reported port>
|
|
36
|
+
browser-tools pick "Click the price" --port <reported port>
|
|
37
|
+
browser-tools scrape-page --port <reported port>
|
|
38
|
+
browser-tools extract-article --chars 6000 --port <reported port>
|
|
39
|
+
browser-tools stop --clean --port <reported port>
|
|
40
|
+
browser-tools config task-profile set <task> --profile "<alias>"
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Run `browser-tools --help` for the full command list.
|
|
44
|
+
|
|
45
|
+
## Programmatic use
|
|
46
|
+
|
|
47
|
+
```js
|
|
48
|
+
import { connectBrowser, activePage, withBrowser } from '@rezkam/browser-tools';
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`@rezkam/browser-tools` and `@rezkam/browser-tools/browser-control.mjs` both resolve to the browser control module (launch, stop, profile sync, owner-token safety, CDP connect). `@rezkam/browser-tools/resource-helper.mjs` resolves to the shared generic-extractor lifecycle helper.
|
|
52
|
+
|
|
53
|
+
## Behavior notes
|
|
54
|
+
|
|
55
|
+
- 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
|
+
- 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
|
+
- 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.
|
|
58
|
+
- 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+.
|
|
60
|
+
|
|
61
|
+
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
|
+
|
|
63
|
+
## License
|
|
64
|
+
|
|
65
|
+
Apache-2.0
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* `browser-tools` CLI dispatcher.
|
|
4
|
+
*
|
|
5
|
+
* This is packaging only: it does not reimplement browser lifecycle, profile, or safety
|
|
6
|
+
* logic. It resolves a subcommand to the matching script under scripts/ and runs it exactly
|
|
7
|
+
* as it would run from the skill (`scripts/<name>.mjs [args]`), forwarding argv and exit code.
|
|
8
|
+
*
|
|
9
|
+
* Usage:
|
|
10
|
+
* browser-tools start [--task <task>] [--profile <name>] [--headless] [--sync] [--port <n>]
|
|
11
|
+
* browser-tools status [--port <n>] [--json]
|
|
12
|
+
* browser-tools stop [--clean] [--dry-run] [--prune]
|
|
13
|
+
* browser-tools nav <url> [--new] [--port <n>]
|
|
14
|
+
* browser-tools eval '<javascript>' [--port <n>]
|
|
15
|
+
* browser-tools screenshot [--full] [--port <n>]
|
|
16
|
+
* browser-tools pick "<instruction>" [--port <n>]
|
|
17
|
+
* browser-tools scrape-page [--port <n>]
|
|
18
|
+
* browser-tools extract-article [--chars <n>] [--port <n>]
|
|
19
|
+
* browser-tools config profiles|active-profiles|task-profile ...
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import { spawnSync } from 'node:child_process';
|
|
23
|
+
import { dirname, join } from 'node:path';
|
|
24
|
+
import { fileURLToPath } from 'node:url';
|
|
25
|
+
|
|
26
|
+
const SCRIPTS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'scripts');
|
|
27
|
+
|
|
28
|
+
// Maps each CLI subcommand to the existing script it dispatches to unchanged.
|
|
29
|
+
const COMMANDS = {
|
|
30
|
+
start: 'start.mjs',
|
|
31
|
+
status: 'status.mjs',
|
|
32
|
+
stop: 'stop.mjs',
|
|
33
|
+
nav: 'nav.mjs',
|
|
34
|
+
eval: 'eval.mjs',
|
|
35
|
+
screenshot: 'screenshot.mjs',
|
|
36
|
+
pick: 'pick.mjs',
|
|
37
|
+
'scrape-page': 'scrape-page.mjs',
|
|
38
|
+
'extract-article': 'extract-article.mjs',
|
|
39
|
+
config: 'config.mjs',
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
function printUsage() {
|
|
43
|
+
console.error(`Usage: browser-tools <command> [args]
|
|
44
|
+
|
|
45
|
+
Commands:
|
|
46
|
+
${Object.keys(COMMANDS).map((name) => ` ${name}`).join('\n')}
|
|
47
|
+
|
|
48
|
+
Each command forwards its arguments to the matching browser-tools script.
|
|
49
|
+
See the package README or SKILL.md for the full flag reference per command.`);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const [, , command, ...rest] = process.argv;
|
|
53
|
+
|
|
54
|
+
if (!command || command === '--help' || command === '-h') {
|
|
55
|
+
printUsage();
|
|
56
|
+
process.exit(command ? 0 : 1);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const scriptFile = COMMANDS[command];
|
|
60
|
+
if (!scriptFile) {
|
|
61
|
+
console.error(`✗ Unknown command: ${command}`);
|
|
62
|
+
printUsage();
|
|
63
|
+
process.exit(1);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const result = spawnSync(process.execPath, [join(SCRIPTS_DIR, scriptFile), ...rest], { stdio: 'inherit' });
|
|
67
|
+
if (result.error) {
|
|
68
|
+
console.error(`✗ Failed to run ${command}: ${result.error.message}`);
|
|
69
|
+
process.exit(1);
|
|
70
|
+
}
|
|
71
|
+
process.exit(result.status ?? 1);
|
package/package.json
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@rezkam/browser-tools",
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Sandboxed, owner-token-protected Chrome automation for AI agents: launch, navigate, evaluate, screenshot, and manage Chrome profiles from a CLI or programmatically.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/rezkam/boring-but-good.git",
|
|
10
|
+
"directory": "browser-tools"
|
|
11
|
+
},
|
|
12
|
+
"engines": {
|
|
13
|
+
"node": ">=20"
|
|
14
|
+
},
|
|
15
|
+
"bin": {
|
|
16
|
+
"browser-tools": "./bin/browser-tools.mjs"
|
|
17
|
+
},
|
|
18
|
+
"exports": {
|
|
19
|
+
".": "./scripts/browser-control.mjs",
|
|
20
|
+
"./browser-control.mjs": "./scripts/browser-control.mjs",
|
|
21
|
+
"./resource-helper.mjs": "./scripts/resource-helper.mjs",
|
|
22
|
+
"./package.json": "./package.json"
|
|
23
|
+
},
|
|
24
|
+
"files": [
|
|
25
|
+
"bin",
|
|
26
|
+
"scripts",
|
|
27
|
+
"README.md"
|
|
28
|
+
],
|
|
29
|
+
"publishConfig": {
|
|
30
|
+
"access": "public",
|
|
31
|
+
"provenance": true
|
|
32
|
+
},
|
|
33
|
+
"scripts": {
|
|
34
|
+
"test": "node --test test/*.mjs",
|
|
35
|
+
"coverage": "node --test --experimental-test-coverage test/*.mjs",
|
|
36
|
+
"validate": "npm test"
|
|
37
|
+
},
|
|
38
|
+
"dependencies": {
|
|
39
|
+
"puppeteer-core": "^24.42.0"
|
|
40
|
+
}
|
|
41
|
+
}
|