@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 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
+ }