Initial commit

skills/browser-tools/references/01-getting-started.md

@@ -0,0 +1,25 @@
+## Getting Started
+
+The browser-tools skill wraps a set of executable Node.js scripts located in `skills/browser-tools/scripts`. They expect an existing Chrome or Chromium build with remote debugging enabled on port 9222 by default.
+
+### Install dependencies
+
+```bash
+cd skills/browser-tools
+npm install
+```
+
+### Launch Chrome
+
+```bash
+# Start with a temporary profile
+node scripts/start.js
+
+# Reuse your default profile (copies it into a sandbox)
+node scripts/start.js --profile
+
+# Specify a custom Chrome executable
+node scripts/start.js --chrome-path /usr/bin/google-chrome-stable
+```
+
+After a successful start the script prints JSON describing the session (`port`, `userDataDir`, and chosen executable). All other tools assume the Chrome instance remains available on the same debugging endpoint.

skills/browser-tools/references/02-commands.md

@@ -0,0 +1,72 @@
+## Command Reference
+
+All scripts accept the shared flags `--json`, `--quiet`, `--port=<number>`, `--host=<host>`, `--ws=<endpoint>`, and `--timeout=<ms>`. Without `--json`, STDOUT still emits machine-readable JSON while human logs go to STDERR.
+
+### start.js
+
+```bash
+node scripts/start.js [--profile[=path]] [--chrome-path=<path>] [--user-data-dir=<path>]
+```
+
+- Detects Chrome/Chromium automatically across macOS, Linux, and Windows.
+- Copies the default browser profile when `--profile` is set, or from a custom path when supplied.
+- Returns `{ ok, port, userDataDir, chromePath, profile }`.
+
+### navigate.js
+
+```bash
+node scripts/navigate.js <url> [--new] [--wait=domcontentloaded|networkidle0|load|none]
+```
+
+- Reuses the active tab by default; `--new` opens a new page.
+- Emits `{ ok, url, newPage }`.
+
+### evaluate.js
+
+```bash
+node scripts/evaluate.js <expression>
+node scripts/evaluate.js --file snippet.js
+```
+
+- Supports inline, file-based, or piped expressions; structured clone results are returned under `result`.
+- When not in `--json` mode the evaluated value (truncated to 8 KB) is echoed to STDOUT.
+
+### screenshot.js
+
+```bash
+node scripts/screenshot.js [--element=<selector>] [--format=png|jpeg] [--quality=80] [--out=path]
+```
+
+- Saves to a temporary directory when `--out` is omitted and prints the absolute path.
+- Element captures rely on the supplied selector; full-page captures default to PNG.
+
+### element.js
+
+```bash
+node scripts/element.js <selector>
+node scripts/element.js --text "Buy now"
+node scripts/element.js             # interactive picker
+```
+
+- `--click` and `--scroll` act on the resolved element before returning metadata.
+- Interactive mode waits up to 60 s for a click inside Chrome and restores page styling afterwards.
+
+### cookies.js
+
+```bash
+node scripts/cookies.js --export [path] [--domain=example.com]
+node scripts/cookies.js --import cookies.json
+node scripts/cookies.js --clear [--domain=example.com]
+```
+
+- Uses Chrome DevTools `Network.*` commands for reliable cookie management.
+- Export payloads include metadata (`exportedAt`, `pageUrl`, `cookies[]`).
+
+### close.js
+
+```bash
+node scripts/close.js [--force]
+```
+
+- Attempts graceful shutdown first; falls back to process termination on failure.
+- Returns `{ ok, port, graceful, forced, closedTabs }`.

skills/browser-tools/references/03-troubleshooting.md

@@ -0,0 +1,29 @@
+## Troubleshooting
+
+### Chrome executable not found
+
+- Provide the path explicitly: `node scripts/start.js --chrome-path /path/to/chrome`.
+- On Linux ensure the binary is accessible (`/usr/bin/google-chrome`, `/usr/bin/chromium`).
+- On Windows set `CHROME_PATH="C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"`.
+
+### Port 9222 already in use
+
+- Run `node scripts/close.js` to recycle the existing session.
+- Override the debugging port: `node scripts/start.js --port 9333` then pass `--port 9333` to subsequent commands.
+
+### Element picker timeout
+
+- Bring the Chrome window to the foreground before running `element.js` with no arguments.
+- Click within 60 seconds; press `Ctrl+C` to abort the command if you need to restart.
+- Use `--selector` or `--text` when pages block pointer events.
+
+### Cookie import errors
+
+- Ensure the JSON file contains a `cookies[]` array with `name`, `value`, and `domain` fields.
+- Host-only cookies require a `domain` value (e.g., `example.com`); the script converts `sameSite` to the correct case automatically.
+- If the page reload fails, refresh manually—cookies are already written to the browser profile.
+
+### Headless or remote Chrome targets
+
+- When connecting to a remote browser, set `BROWSER_WS_URL=ws://host:port/devtools/browser/<id>` and omit the local port flag.
+- All scripts accept `--ws` to override the connection endpoint per invocation.

skills/browser-tools/references/04-security.md

@@ -0,0 +1,7 @@
+## Security Guidelines
+
+- **Profiles**: Using `--profile` clones your default Chrome profile into `~/.cache/browser-tools/profile-<port>`. Remove the directory after sensitive sessions or reuse `close.js` which leaves the copy on disk for next runs.
+- **Credentials**: Exported cookie JSON files may contain session tokens. Store them outside version control and delete when no longer needed.
+- **JavaScript execution**: Only evaluate trusted code. Prefer passing scripts via `--file` to keep complex payloads auditable.
+- **Remote endpoints**: When targeting remote Chrome instances with `--ws`, ensure the connection is tunneled (SSH, VPN) because the DevTools protocol provides full browser access.
+- **Force shutdown**: `close.js --force` uses process termination (`pkill`/`taskkill`). Verify no unrelated Chrome sessions share the same user data directory before invoking it.