@everydaydevopsio/pilot 0.5.2 → 0.6.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 +64 -0
- package/CLAUDE.md +7 -7
- package/README.md +108 -53
- package/dist/browser/browser-manager.d.ts +60 -0
- package/dist/browser/browser-manager.d.ts.map +1 -0
- package/dist/browser/browser-manager.js +348 -0
- package/dist/browser/browser-manager.js.map +1 -0
- package/dist/browser/chrome-launcher.d.ts +30 -0
- package/dist/browser/chrome-launcher.d.ts.map +1 -0
- package/dist/browser/chrome-launcher.js +217 -0
- package/dist/browser/chrome-launcher.js.map +1 -0
- package/dist/browser/connection.d.ts +23 -0
- package/dist/browser/connection.d.ts.map +1 -0
- package/dist/browser/connection.js +53 -0
- package/dist/browser/connection.js.map +1 -0
- package/dist/browser/events.d.ts +9 -0
- package/dist/browser/events.d.ts.map +1 -0
- package/dist/browser/events.js +99 -0
- package/dist/browser/events.js.map +1 -0
- package/dist/browser/index.d.ts +4 -0
- package/dist/browser/index.d.ts.map +1 -0
- package/dist/browser/index.js +4 -0
- package/dist/browser/index.js.map +1 -0
- package/dist/browser/inspect/element-ref.d.ts +23 -0
- package/dist/browser/inspect/element-ref.d.ts.map +1 -0
- package/dist/browser/inspect/element-ref.js +52 -0
- package/dist/browser/inspect/element-ref.js.map +1 -0
- package/dist/browser/inspect/snapshot.d.ts +11 -0
- package/dist/browser/inspect/snapshot.d.ts.map +1 -0
- package/dist/browser/inspect/snapshot.js +282 -0
- package/dist/browser/inspect/snapshot.js.map +1 -0
- package/dist/browser/inspect/styles.d.ts +45 -0
- package/dist/browser/inspect/styles.d.ts.map +1 -0
- package/dist/browser/inspect/styles.js +190 -0
- package/dist/browser/inspect/styles.js.map +1 -0
- package/dist/browser/inspect/types.d.ts +35 -0
- package/dist/browser/inspect/types.d.ts.map +1 -0
- package/dist/browser/inspect/types.js +2 -0
- package/dist/browser/inspect/types.js.map +1 -0
- package/dist/browser/interaction/dialogs.d.ts +18 -0
- package/dist/browser/interaction/dialogs.d.ts.map +1 -0
- package/dist/browser/interaction/dialogs.js +35 -0
- package/dist/browser/interaction/dialogs.js.map +1 -0
- package/dist/browser/interaction/downloads.d.ts +23 -0
- package/dist/browser/interaction/downloads.d.ts.map +1 -0
- package/dist/browser/interaction/downloads.js +87 -0
- package/dist/browser/interaction/downloads.js.map +1 -0
- package/dist/browser/interaction/events.d.ts +17 -0
- package/dist/browser/interaction/events.d.ts.map +1 -0
- package/dist/browser/interaction/events.js +66 -0
- package/dist/browser/interaction/events.js.map +1 -0
- package/dist/browser/interaction/ref-resolver.d.ts +18 -0
- package/dist/browser/interaction/ref-resolver.d.ts.map +1 -0
- package/dist/browser/interaction/ref-resolver.js +32 -0
- package/dist/browser/interaction/ref-resolver.js.map +1 -0
- package/dist/browser/interaction/uploads.d.ts +4 -0
- package/dist/browser/interaction/uploads.d.ts.map +1 -0
- package/dist/browser/interaction/uploads.js +43 -0
- package/dist/browser/interaction/uploads.js.map +1 -0
- package/dist/browser/network/network-buffer.d.ts +19 -0
- package/dist/browser/network/network-buffer.d.ts.map +1 -0
- package/dist/browser/network/network-buffer.js +118 -0
- package/dist/browser/network/network-buffer.js.map +1 -0
- package/dist/browser/network/network-monitor.d.ts +8 -0
- package/dist/browser/network/network-monitor.d.ts.map +1 -0
- package/dist/browser/network/network-monitor.js +85 -0
- package/dist/browser/network/network-monitor.js.map +1 -0
- package/dist/browser/network/redaction.d.ts +3 -0
- package/dist/browser/network/redaction.d.ts.map +1 -0
- package/dist/browser/network/redaction.js +36 -0
- package/dist/browser/network/redaction.js.map +1 -0
- package/dist/browser/network/types.d.ts +45 -0
- package/dist/browser/network/types.d.ts.map +1 -0
- package/dist/browser/network/types.js +2 -0
- package/dist/browser/network/types.js.map +1 -0
- package/dist/browser/performance/analyze.d.ts +5 -0
- package/dist/browser/performance/analyze.d.ts.map +1 -0
- package/dist/browser/performance/analyze.js +230 -0
- package/dist/browser/performance/analyze.js.map +1 -0
- package/dist/browser/performance/trace.d.ts +10 -0
- package/dist/browser/performance/trace.d.ts.map +1 -0
- package/dist/browser/performance/trace.js +38 -0
- package/dist/browser/performance/trace.js.map +1 -0
- package/dist/browser/performance/types.d.ts +31 -0
- package/dist/browser/performance/types.d.ts.map +1 -0
- package/dist/browser/performance/types.js +2 -0
- package/dist/browser/performance/types.js.map +1 -0
- package/dist/browser/security/origins.d.ts +18 -0
- package/dist/browser/security/origins.d.ts.map +1 -0
- package/dist/browser/security/origins.js +84 -0
- package/dist/browser/security/origins.js.map +1 -0
- package/dist/browser/tabs.d.ts +15 -0
- package/dist/browser/tabs.d.ts.map +1 -0
- package/dist/browser/tabs.js +71 -0
- package/dist/browser/tabs.js.map +1 -0
- package/dist/browser/types.d.ts +31 -0
- package/dist/browser/types.d.ts.map +1 -0
- package/dist/browser/types.js +2 -0
- package/dist/browser/types.js.map +1 -0
- package/dist/browser.d.ts +2 -99
- package/dist/browser.d.ts.map +1 -1
- package/dist/browser.js +3 -653
- package/dist/browser.js.map +1 -1
- package/dist/commands/check.d.ts +17 -0
- package/dist/commands/check.d.ts.map +1 -0
- package/dist/commands/check.js +38 -0
- package/dist/commands/check.js.map +1 -0
- package/dist/commands/click.d.ts +3 -1
- package/dist/commands/click.d.ts.map +1 -1
- package/dist/commands/click.js +16 -4
- package/dist/commands/click.js.map +1 -1
- package/dist/commands/connect.d.ts +14 -0
- package/dist/commands/connect.d.ts.map +1 -0
- package/dist/commands/connect.js +19 -0
- package/dist/commands/connect.js.map +1 -0
- package/dist/commands/dialog.d.ts +19 -0
- package/dist/commands/dialog.d.ts.map +1 -0
- package/dist/commands/dialog.js +51 -0
- package/dist/commands/dialog.js.map +1 -0
- package/dist/commands/downloads.d.ts +30 -0
- package/dist/commands/downloads.d.ts.map +1 -0
- package/dist/commands/downloads.js +66 -0
- package/dist/commands/downloads.js.map +1 -0
- package/dist/commands/fill.d.ts +16 -0
- package/dist/commands/fill.d.ts.map +1 -0
- package/dist/commands/fill.js +15 -0
- package/dist/commands/fill.js.map +1 -0
- package/dist/commands/find.d.ts +14 -0
- package/dist/commands/find.d.ts.map +1 -0
- package/dist/commands/find.js +26 -0
- package/dist/commands/find.js.map +1 -0
- package/dist/commands/hover.d.ts +13 -0
- package/dist/commands/hover.d.ts.map +1 -0
- package/dist/commands/hover.js +24 -0
- package/dist/commands/hover.js.map +1 -0
- package/dist/commands/navigate.d.ts.map +1 -1
- package/dist/commands/navigate.js +13 -0
- package/dist/commands/navigate.js.map +1 -1
- package/dist/commands/network.d.ts +33 -0
- package/dist/commands/network.d.ts.map +1 -0
- package/dist/commands/network.js +84 -0
- package/dist/commands/network.js.map +1 -0
- package/dist/commands/performance.d.ts +12 -0
- package/dist/commands/performance.d.ts.map +1 -0
- package/dist/commands/performance.js +26 -0
- package/dist/commands/performance.js.map +1 -0
- package/dist/commands/press_key.d.ts +10 -0
- package/dist/commands/press_key.d.ts.map +1 -0
- package/dist/commands/press_key.js +103 -0
- package/dist/commands/press_key.js.map +1 -0
- package/dist/commands/scroll.d.ts +21 -0
- package/dist/commands/scroll.d.ts.map +1 -0
- package/dist/commands/scroll.js +54 -0
- package/dist/commands/scroll.js.map +1 -0
- package/dist/commands/select.d.ts +18 -0
- package/dist/commands/select.d.ts.map +1 -0
- package/dist/commands/select.js +53 -0
- package/dist/commands/select.js.map +1 -0
- package/dist/commands/snapshot.d.ts +9 -0
- package/dist/commands/snapshot.d.ts.map +1 -0
- package/dist/commands/snapshot.js +7 -0
- package/dist/commands/snapshot.js.map +1 -0
- package/dist/commands/styles.d.ts +13 -0
- package/dist/commands/styles.d.ts.map +1 -0
- package/dist/commands/styles.js +7 -0
- package/dist/commands/styles.js.map +1 -0
- package/dist/commands/type.d.ts +3 -1
- package/dist/commands/type.d.ts.map +1 -1
- package/dist/commands/type.js +11 -2
- package/dist/commands/type.js.map +1 -1
- package/dist/commands/upload.d.ts +12 -0
- package/dist/commands/upload.d.ts.map +1 -0
- package/dist/commands/upload.js +13 -0
- package/dist/commands/upload.js.map +1 -0
- package/dist/mcp/console-buffer.d.ts +9 -0
- package/dist/mcp/console-buffer.d.ts.map +1 -1
- package/dist/mcp/console-buffer.js.map +1 -1
- package/dist/mcp/server.d.ts +10 -0
- package/dist/mcp/server.d.ts.map +1 -1
- package/dist/mcp/server.js +63 -2
- package/dist/mcp/server.js.map +1 -1
- package/dist/mcp/tools/browser.d.ts.map +1 -1
- package/dist/mcp/tools/browser.js +99 -8
- package/dist/mcp/tools/browser.js.map +1 -1
- package/dist/mcp/tools/connect.d.ts +5 -0
- package/dist/mcp/tools/connect.d.ts.map +1 -0
- package/dist/mcp/tools/connect.js +48 -0
- package/dist/mcp/tools/connect.js.map +1 -0
- package/dist/mcp/tools/files.d.ts +4 -0
- package/dist/mcp/tools/files.d.ts.map +1 -0
- package/dist/mcp/tools/files.js +85 -0
- package/dist/mcp/tools/files.js.map +1 -0
- package/dist/mcp/tools/interaction.d.ts +4 -0
- package/dist/mcp/tools/interaction.d.ts.map +1 -0
- package/dist/mcp/tools/interaction.js +176 -0
- package/dist/mcp/tools/interaction.js.map +1 -0
- package/dist/mcp/tools/names.d.ts +1 -1
- package/dist/mcp/tools/names.d.ts.map +1 -1
- package/dist/mcp/tools/names.js +19 -1
- package/dist/mcp/tools/names.js.map +1 -1
- package/dist/mcp/tools/network.d.ts +4 -0
- package/dist/mcp/tools/network.d.ts.map +1 -0
- package/dist/mcp/tools/network.js +68 -0
- package/dist/mcp/tools/network.js.map +1 -0
- package/dist/mcp/tools/performance.d.ts +4 -0
- package/dist/mcp/tools/performance.d.ts.map +1 -0
- package/dist/mcp/tools/performance.js +26 -0
- package/dist/mcp/tools/performance.js.map +1 -0
- package/dist/mcp/tools/runtime.d.ts +4 -0
- package/dist/mcp/tools/runtime.d.ts.map +1 -0
- package/dist/mcp/tools/runtime.js +128 -0
- package/dist/mcp/tools/runtime.js.map +1 -0
- package/dist/mcp/tools/snapshot.d.ts +4 -0
- package/dist/mcp/tools/snapshot.d.ts.map +1 -0
- package/dist/mcp/tools/snapshot.js +42 -0
- package/dist/mcp/tools/snapshot.js.map +1 -0
- package/dist/mcp/tools/styles.d.ts +4 -0
- package/dist/mcp/tools/styles.d.ts.map +1 -0
- package/dist/mcp/tools/styles.js +27 -0
- package/dist/mcp/tools/styles.js.map +1 -0
- package/dist/util/config.d.ts.map +1 -1
- package/dist/util/config.js +3 -2
- package/dist/util/config.js.map +1 -1
- package/package.json +3 -3
- package/src/browser/browser-manager.ts +457 -0
- package/src/browser/chrome-launcher.ts +271 -0
- package/src/browser/connection.ts +84 -0
- package/src/browser/events.ts +121 -0
- package/src/browser/index.ts +20 -0
- package/src/browser/inspect/element-ref.ts +68 -0
- package/src/browser/inspect/snapshot.ts +348 -0
- package/src/browser/inspect/styles.ts +258 -0
- package/src/browser/inspect/types.ts +37 -0
- package/src/browser/interaction/dialogs.ts +54 -0
- package/src/browser/interaction/downloads.ts +116 -0
- package/src/browser/interaction/events.ts +79 -0
- package/src/browser/interaction/ref-resolver.ts +53 -0
- package/src/browser/interaction/uploads.ts +60 -0
- package/src/browser/network/network-buffer.ts +133 -0
- package/src/browser/network/network-monitor.ts +107 -0
- package/src/browser/network/redaction.ts +42 -0
- package/src/browser/network/types.ts +47 -0
- package/src/browser/performance/analyze.ts +298 -0
- package/src/browser/performance/trace.ts +60 -0
- package/src/browser/performance/types.ts +34 -0
- package/src/browser/security/origins.ts +102 -0
- package/src/browser/tabs.ts +110 -0
- package/src/browser/types.ts +31 -0
- package/src/browser.ts +22 -798
- package/src/commands/check.ts +59 -0
- package/src/commands/click.ts +18 -4
- package/src/commands/connect.ts +40 -0
- package/src/commands/dialog.ts +79 -0
- package/src/commands/downloads.ts +111 -0
- package/src/commands/fill.ts +34 -0
- package/src/commands/find.ts +52 -0
- package/src/commands/hover.ts +42 -0
- package/src/commands/navigate.ts +20 -0
- package/src/commands/network.ts +141 -0
- package/src/commands/performance.ts +51 -0
- package/src/commands/press_key.ts +134 -0
- package/src/commands/scroll.ts +79 -0
- package/src/commands/select.ts +78 -0
- package/src/commands/snapshot.ts +18 -0
- package/src/commands/styles.ts +24 -0
- package/src/commands/type.ts +12 -2
- package/src/commands/upload.ts +36 -0
- package/src/mcp/console-buffer.ts +10 -0
- package/src/mcp/server.ts +74 -2
- package/src/mcp/tools/browser.ts +113 -7
- package/src/mcp/tools/connect.ts +62 -0
- package/src/mcp/tools/files.ts +120 -0
- package/src/mcp/tools/interaction.ts +232 -0
- package/src/mcp/tools/names.ts +19 -1
- package/src/mcp/tools/network.ts +86 -0
- package/src/mcp/tools/performance.ts +40 -0
- package/src/mcp/tools/runtime.ts +164 -0
- package/src/mcp/tools/snapshot.ts +64 -0
- package/src/mcp/tools/styles.ts +41 -0
- package/src/util/config.ts +3 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.6.0
|
|
4
|
+
|
|
5
|
+
Agent-oriented browser debugging and interaction release. Adds structured accessibility snapshots, element ref-based interaction, network/console/CSS inspection, file operations, performance tracing, security controls, and existing Chrome connection support.
|
|
6
|
+
|
|
7
|
+
### New Tools (18)
|
|
8
|
+
|
|
9
|
+
- **`browser_snapshot`** — Structured accessibility snapshot with element refs (e1, e2, ...)
|
|
10
|
+
- **`browser_find`** — Find elements by role, name, or text
|
|
11
|
+
- **`browser_fill`** — Replace form field value (React/Vue/Svelte compatible)
|
|
12
|
+
- **`browser_hover`** — Hover over element by ref or coordinates
|
|
13
|
+
- **`browser_press_key`** — Press key or combo (Enter, Tab, Control+a, Meta+c)
|
|
14
|
+
- **`browser_select`** — Select option by value, label, or index
|
|
15
|
+
- **`browser_check`** — Toggle checkbox/radio
|
|
16
|
+
- **`browser_scroll`** — Scroll element into view, by direction, or absolute
|
|
17
|
+
- **`browser_network`** — List/get/clear captured network requests with header redaction
|
|
18
|
+
- **`browser_console`** — List/clear console messages with stack traces
|
|
19
|
+
- **`browser_errors`** — List/clear runtime errors and exceptions
|
|
20
|
+
- **`browser_styles`** — Inspect computed styles, CSS rules, and box model
|
|
21
|
+
- **`browser_dialog`** — Handle alert/confirm/prompt dialogs
|
|
22
|
+
- **`browser_upload`** — Upload files with path validation
|
|
23
|
+
- **`browser_downloads`** — Track file downloads (list/wait/clear)
|
|
24
|
+
- **`browser_performance`** — Start/stop tracing; analyze navigation timing, long tasks
|
|
25
|
+
- **`browser_connect`** — Connect to existing Chrome with remote debugging
|
|
26
|
+
- **`browser_tabs`** — Consolidated tab management (list/new/select/close)
|
|
27
|
+
|
|
28
|
+
### Enhanced Tools
|
|
29
|
+
|
|
30
|
+
- **`browser_click`** — Now accepts `ref` parameter alongside selector/coordinates
|
|
31
|
+
- **`browser_type`** — Now accepts `ref` parameter alongside selector
|
|
32
|
+
- **`browser_navigate`** — Origin security check before and after navigation (redirect protection)
|
|
33
|
+
|
|
34
|
+
### Architecture
|
|
35
|
+
|
|
36
|
+
- Split `src/browser.ts` (799 lines) into cohesive modules under `src/browser/`
|
|
37
|
+
- Element ref system: `ElementRefMap` with generation tracking, `STALE_ELEMENT_REFERENCE` errors
|
|
38
|
+
- Network buffer: ring buffer (~1000 records) with lazy body retrieval and header redaction
|
|
39
|
+
- Runtime exceptions: `Runtime.exceptionThrown` capture with full stack frames
|
|
40
|
+
- CSS inspection: lazy `CSS.enable()` per client via `WeakRef` tracking
|
|
41
|
+
- Dialog queue, download tracker, upload validation with allowed-root security
|
|
42
|
+
- Performance tracing: CDP Tracing + Performance.getMetrics with bounded analysis
|
|
43
|
+
- External Chrome lifecycle: `browser_stop` disconnects without killing external Chrome
|
|
44
|
+
|
|
45
|
+
### Security
|
|
46
|
+
|
|
47
|
+
- `PILOT_ALLOWED_ORIGINS` / `PILOT_BLOCKED_ORIGINS` — origin allow/block lists with wildcard support
|
|
48
|
+
- Block wins over allow; scheme-less patterns match host only
|
|
49
|
+
- Post-navigation redirect check — navigate to `about:blank` on violation
|
|
50
|
+
- `PILOT_REDACT_HEADERS` — configurable header redaction (default: Authorization, Cookie, Set-Cookie, X-Api-Key, Proxy-Authorization)
|
|
51
|
+
- `PILOT_UPLOAD_ROOTS` — allowed directories for file uploads
|
|
52
|
+
|
|
53
|
+
### Backward Compatibility
|
|
54
|
+
|
|
55
|
+
All 17 original 0.5.x tools remain working unchanged. Legacy tab tools (`browser_list_tabs`, `browser_new_tab`, `browser_close_tab`, `browser_switch_tab`) and error tools (`browser_get_console_logs`, `browser_get_errors`, `browser_clear_errors`) are preserved.
|
|
56
|
+
|
|
57
|
+
## 0.5.2
|
|
58
|
+
|
|
59
|
+
- Upgraded Ballast to v5.17.2
|
|
60
|
+
- Fixed headless default behavior
|
|
61
|
+
|
|
62
|
+
## 0.5.1
|
|
63
|
+
|
|
64
|
+
- Initial public release
|
package/CLAUDE.md
CHANGED
|
@@ -25,7 +25,7 @@ This repository publishes to **npmjs** under the `@everydaydevopsio` scope.
|
|
|
25
25
|
|
|
26
26
|
## Installed agent rules
|
|
27
27
|
|
|
28
|
-
Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.
|
|
28
|
+
Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.17.2. Do not edit this section.
|
|
29
29
|
|
|
30
30
|
Read and follow these rule files in `.claude/rules/` when they apply:
|
|
31
31
|
|
|
@@ -36,24 +36,24 @@ Read and follow these rule files in `.claude/rules/` when they apply:
|
|
|
36
36
|
- `.claude/rules/docs.md` — Documentation specialist - GitHub Markdown docs by default, or maintain existing Docusaurus sites with publish-docs automation
|
|
37
37
|
- `.claude/rules/cicd.md` — CI/CD specialist - pipeline design, quality gates, and deployment
|
|
38
38
|
- `.claude/rules/observability.md` — Observability specialist - logging, tracing, metrics, and SLOs
|
|
39
|
-
- `.claude/rules/publishing-api.md` — REST API publishing specialist - Docker CD with
|
|
39
|
+
- `.claude/rules/publishing-api.md` — REST API publishing specialist - Docker or platform service CD with runtime health checks
|
|
40
40
|
- `.claude/rules/publishing-apps.md` — App publishing specialist - npmjs for Node apps, PyPI for Python apps, GitHub Releases for Go apps
|
|
41
41
|
- `.claude/rules/publishing-apt.md` — APT/deb package publishing specialist - GoReleaser nfpms and GitHub Releases
|
|
42
42
|
- `.claude/rules/publishing-brew.md` — Homebrew tap publishing specialist - GoReleaser brews block and tap repo setup
|
|
43
43
|
- `.claude/rules/publishing-cli.md` — CLI publishing specialist - GoReleaser for Go, npmjs for Node, PyPI for Python
|
|
44
44
|
- `.claude/rules/publishing-libraries.md` — Library publishing specialist - npmjs for TypeScript, PyPI for Python, GitHub tags/releases for Go
|
|
45
45
|
- `.claude/rules/publishing-sdks.md` — SDK publishing specialist - npmjs for TypeScript SDKs, PyPI for Python SDKs, GitHub tags/releases for Go SDKs
|
|
46
|
-
- `.claude/rules/publishing-web.md` — Web app publishing specialist - Docker
|
|
46
|
+
- `.claude/rules/publishing-web.md` — Web app publishing specialist - Docker or platform app CD on push to main
|
|
47
47
|
- `.claude/rules/typescript-linting.md` — TypeScript linting specialist - implements comprehensive linting and code formatting for TypeScript/JavaScript projects
|
|
48
48
|
- `.claude/rules/typescript-logging.md` — Centralized logging specialist - configures Pino with Fluentd for Node/Next.js, and pino-browser to /api/logs
|
|
49
49
|
- `.claude/rules/typescript-testing.md` — Testing specialist - sets up Jest (default) or Vitest for Vite projects, 50% coverage, and test step in build GitHub Action
|
|
50
|
-
- `.claude/rules/git-hooks.md` —
|
|
51
|
-
- `.claude/rules/tasks-task-system.md` — Task system integration - use
|
|
52
|
-
- `.claude/rules/tasks-todo.md` — Branch-local TODO tracking - manage tasks/
|
|
50
|
+
- `.claude/rules/git-hooks.md` — Rules for git-hooks
|
|
51
|
+
- `.claude/rules/tasks-task-system.md` — Task system integration - use the configured work item system and configure MCP when active
|
|
52
|
+
- `.claude/rules/tasks-todo.md` — Branch-local TODO tracking - manage tasks/todo.md and triage before PR
|
|
53
53
|
|
|
54
54
|
## Installed skills
|
|
55
55
|
|
|
56
|
-
Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.
|
|
56
|
+
Created by [Ballast](https://github.com/everydaydevopsio/ballast) v5.17.2. Do not edit this section.
|
|
57
57
|
|
|
58
58
|
Read and use these skill files in `.claude/skills/` when they are relevant:
|
|
59
59
|
|
package/README.md
CHANGED
|
@@ -7,9 +7,9 @@
|
|
|
7
7
|
[](https://github.com/everydaydevopsio/pilot/releases)
|
|
8
8
|
[](https://www.npmjs.com/package/@everydaydevopsio/pilot)
|
|
9
9
|
|
|
10
|
-
A lightweight Node.js/TypeScript MCP server that gives AI agents DevTools-grade control over a running Chrome instance. Connects to Chrome via the Chrome DevTools Protocol (CDP) and exposes MCP tools for
|
|
10
|
+
A lightweight Node.js/TypeScript MCP server that gives AI agents DevTools-grade control over a running Chrome instance. Connects to Chrome via the Chrome DevTools Protocol (CDP) and exposes 35 MCP tools for browser automation, inspection, and debugging — including structured accessibility snapshots, element ref-based interaction, network/console/CSS inspection, file operations, performance tracing, and security controls.
|
|
11
11
|
|
|
12
|
-
Use pilot to open a URL and watch for errors — from any AI agent that speaks MCP.
|
|
12
|
+
Use pilot to open a URL, interact with it using semantic element refs, inspect network traffic, diagnose CSS issues, and watch for errors — all from any AI agent that speaks MCP.
|
|
13
13
|
|
|
14
14
|
## Prerequisites
|
|
15
15
|
|
|
@@ -94,49 +94,109 @@ Or add to `.mcp.json` in your project:
|
|
|
94
94
|
|
|
95
95
|
**Browser Lifecycle:**
|
|
96
96
|
|
|
97
|
-
| Tool
|
|
98
|
-
|
|
|
99
|
-
| `browser_start`
|
|
100
|
-
| `browser_stop`
|
|
97
|
+
| Tool | Description |
|
|
98
|
+
| ----------------- | --------------------------------------------------- |
|
|
99
|
+
| `browser_start` | Launch Chrome |
|
|
100
|
+
| `browser_stop` | Stop Chrome (or disconnect from external Chrome) |
|
|
101
|
+
| `browser_connect` | Connect to an existing Chrome with remote debugging |
|
|
101
102
|
|
|
102
|
-
**
|
|
103
|
+
**Snapshot & Find:**
|
|
103
104
|
|
|
104
|
-
| Tool
|
|
105
|
-
|
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `browser_click` | Click element by CSS selector or coordinates |
|
|
109
|
-
| `browser_type` | Type text into focused element or selector |
|
|
110
|
-
| `browser_evaluate` | Execute JavaScript and return result |
|
|
111
|
-
| `browser_wait` | Wait for selector, network idle, or fixed delay |
|
|
112
|
-
| `browser_page_info` | Get current URL, title, and ready state |
|
|
113
|
-
| `browser_viewport_resize` | Resize the viewport to new dimensions at runtime |
|
|
105
|
+
| Tool | Description |
|
|
106
|
+
| ------------------ | ------------------------------------------------------ |
|
|
107
|
+
| `browser_snapshot` | Accessibility snapshot with element refs (e1, e2, ...) |
|
|
108
|
+
| `browser_find` | Find elements by role, name, or text |
|
|
114
109
|
|
|
115
|
-
**
|
|
110
|
+
**Interaction (ref-based):**
|
|
111
|
+
|
|
112
|
+
| Tool | Description |
|
|
113
|
+
| ------------------- | --------------------------------------------------- |
|
|
114
|
+
| `browser_click` | Click by ref, CSS selector, or coordinates |
|
|
115
|
+
| `browser_type` | Type text into ref, selector, or focused element |
|
|
116
|
+
| `browser_fill` | Replace field value (React/Vue/Svelte compatible) |
|
|
117
|
+
| `browser_hover` | Hover over element by ref or coordinates |
|
|
118
|
+
| `browser_press_key` | Press key or combo (Enter, Tab, Control+a, etc.) |
|
|
119
|
+
| `browser_select` | Select option by value, label, or index |
|
|
120
|
+
| `browser_check` | Toggle checkbox/radio |
|
|
121
|
+
| `browser_scroll` | Scroll element into view, by direction, or absolute |
|
|
122
|
+
|
|
123
|
+
**Inspection:**
|
|
124
|
+
|
|
125
|
+
| Tool | Description |
|
|
126
|
+
| ------------------------- | ------------------------------------------------- |
|
|
127
|
+
| `browser_screenshot` | Capture viewport or full page screenshot |
|
|
128
|
+
| `browser_navigate` | Navigate to URL (with origin security check) |
|
|
129
|
+
| `browser_evaluate` | Execute JavaScript and return result |
|
|
130
|
+
| `browser_wait` | Wait for selector, network idle, or fixed delay |
|
|
131
|
+
| `browser_page_info` | Get current URL, title, and ready state |
|
|
132
|
+
| `browser_viewport_resize` | Resize the viewport to new dimensions |
|
|
133
|
+
| `browser_styles` | Inspect computed styles, CSS rules, and box model |
|
|
134
|
+
|
|
135
|
+
**Network & Console:**
|
|
136
|
+
|
|
137
|
+
| Tool | Description |
|
|
138
|
+
| ----------------- | --------------------------------------------- |
|
|
139
|
+
| `browser_network` | List/get/clear captured network requests |
|
|
140
|
+
| `browser_console` | List/clear console messages with stack traces |
|
|
141
|
+
| `browser_errors` | List/clear runtime errors and exceptions |
|
|
142
|
+
|
|
143
|
+
**Files & Dialogs:**
|
|
144
|
+
|
|
145
|
+
| Tool | Description |
|
|
146
|
+
| ------------------- | -------------------------------------- |
|
|
147
|
+
| `browser_dialog` | Handle alert/confirm/prompt dialogs |
|
|
148
|
+
| `browser_upload` | Upload files to file input elements |
|
|
149
|
+
| `browser_downloads` | Track file downloads (list/wait/clear) |
|
|
150
|
+
|
|
151
|
+
**Performance:**
|
|
152
|
+
|
|
153
|
+
| Tool | Description |
|
|
154
|
+
| --------------------- | ------------------------------------------------------------------------ |
|
|
155
|
+
| `browser_performance` | Start/stop tracing; analyze navigation timing, long tasks, slow requests |
|
|
156
|
+
|
|
157
|
+
**Tab Management:**
|
|
158
|
+
|
|
159
|
+
| Tool | Description |
|
|
160
|
+
| -------------- | ----------------------------------------- |
|
|
161
|
+
| `browser_tabs` | List/new/select/close tabs (consolidated) |
|
|
162
|
+
|
|
163
|
+
<details>
|
|
164
|
+
<summary>Legacy tools (backward compatible)</summary>
|
|
116
165
|
|
|
117
166
|
| Tool | Description |
|
|
118
167
|
| -------------------------- | -------------------------------------------- |
|
|
168
|
+
| `browser_list_tabs` | List all open tabs |
|
|
169
|
+
| `browser_new_tab` | Open a new tab |
|
|
170
|
+
| `browser_close_tab` | Close a tab |
|
|
171
|
+
| `browser_switch_tab` | Switch to a tab |
|
|
119
172
|
| `browser_get_console_logs` | Get buffered console messages with filters |
|
|
120
173
|
| `browser_get_errors` | Get console errors (and optionally warnings) |
|
|
121
174
|
| `browser_clear_errors` | Clear the console message buffer |
|
|
122
175
|
|
|
176
|
+
</details>
|
|
177
|
+
|
|
123
178
|
## Configuration
|
|
124
179
|
|
|
125
180
|
All configuration via environment variables.
|
|
126
181
|
|
|
127
|
-
| Env var | Default
|
|
128
|
-
| ------------------------- |
|
|
129
|
-
| `PILOT_CDP_PORT` | `9222`
|
|
130
|
-
| `PILOT_CDP_HOST` | `127.0.0.1`
|
|
131
|
-
| `PILOT_LOG_LEVEL` | `info`
|
|
132
|
-
| `PILOT_CHROME_PATH` | (auto)
|
|
133
|
-
| `PILOT_HEADLESS` | `
|
|
134
|
-
| `PILOT_MCP_BUFFER_SIZE` | `1000`
|
|
135
|
-
| `PILOT_PROFILE_NAME` | `profile1`
|
|
136
|
-
| `PILOT_RESPONSIVE` | (preset)
|
|
137
|
-
| `PILOT_CHROME_NO_SANDBOX` | (auto)
|
|
138
|
-
|
|
139
|
-
|
|
182
|
+
| Env var | Default | Description |
|
|
183
|
+
| ------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
184
|
+
| `PILOT_CDP_PORT` | `9222` | CDP port when connecting to an existing Chrome (ignored when `browser_start` launches Chrome) |
|
|
185
|
+
| `PILOT_CDP_HOST` | `127.0.0.1` | CDP host when connecting to an existing Chrome (ignored when `browser_start` launches Chrome) |
|
|
186
|
+
| `PILOT_LOG_LEVEL` | `info` | Pino log level |
|
|
187
|
+
| `PILOT_CHROME_PATH` | (auto) | Path to Chrome executable |
|
|
188
|
+
| `PILOT_HEADLESS` | `false` | Run Chrome headless. Accepts `true`/`1` or `false`/`0`. |
|
|
189
|
+
| `PILOT_MCP_BUFFER_SIZE` | `1000` | Console message buffer size |
|
|
190
|
+
| `PILOT_PROFILE_NAME` | `profile1` | Persistent browser profile name. Profiles are stored under `$XDG_DATA_HOME/pilot/<name>` (default `~/.local/share/pilot/<name>`). |
|
|
191
|
+
| `PILOT_RESPONSIVE` | (preset) | Responsive viewport mode. When `true`, the page uses real window dimensions and reflows on resize. Desktop presets default to `true`; mobile/tablet presets leave this unset (locked viewport). Set to `false` to lock the viewport with `setDeviceMetricsOverride`. |
|
|
192
|
+
| `PILOT_CHROME_NO_SANDBOX` | (auto) | Force `--no-sandbox` on/off. Accepts `true`/`1` or `false`/`0`. When unset, the flag is auto-applied only when running as root on Linux. See [Chrome sandbox](#chrome-sandbox) below. |
|
|
193
|
+
| `PILOT_ALLOWED_ORIGINS` | (none) | Comma-separated origin allow list. Supports wildcards (`*.example.com`). When set, only matching origins can be navigated to. |
|
|
194
|
+
| `PILOT_BLOCKED_ORIGINS` | (none) | Comma-separated origin block list. Block wins over allow. Supports wildcards. |
|
|
195
|
+
| `PILOT_REDACT_HEADERS` | (defaults) | Additional headers to redact in network inspection. Default: Authorization, Cookie, Set-Cookie, X-Api-Key, Proxy-Authorization. |
|
|
196
|
+
| `PILOT_UPLOAD_ROOTS` | (cwd) | Comma-separated allowed directories for file uploads. |
|
|
197
|
+
| `PILOT_DOWNLOAD_DIR` | `<tmpdir>/pilot-downloads` | Directory for tracked downloads. Defaults to a `pilot-downloads` subdirectory under the OS temp dir. |
|
|
198
|
+
|
|
199
|
+
> **Tip — running headless:** By default Chrome opens a visible browser window. To run headless (no visible window), set `PILOT_HEADLESS=true` or ask the AI agent: _"set headless to true"_ (or _"run Chrome headless"_). The agent will set `PILOT_HEADLESS=true` before calling `browser_start`.
|
|
140
200
|
|
|
141
201
|
### Responsive viewport mode
|
|
142
202
|
|
|
@@ -189,28 +249,23 @@ pnpm run test:e2e:mcp:docker
|
|
|
189
249
|
|
|
190
250
|
```
|
|
191
251
|
src/
|
|
192
|
-
├── browser.ts
|
|
193
|
-
├──
|
|
194
|
-
│ ├──
|
|
195
|
-
│
|
|
196
|
-
├──
|
|
197
|
-
│ ├──
|
|
198
|
-
│ ├──
|
|
199
|
-
│ ├──
|
|
200
|
-
│ ├──
|
|
201
|
-
│ ├──
|
|
202
|
-
│ ├──
|
|
203
|
-
│
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
│ ├── browser.ts # Browser control tools
|
|
210
|
-
│ └── errors.ts # Error monitoring tools
|
|
211
|
-
└── util/
|
|
212
|
-
├── config.ts # Configuration loading
|
|
213
|
-
└── logger.ts # Pino logger setup
|
|
252
|
+
├── browser.ts # Backward-compatible re-export barrel
|
|
253
|
+
├── browser/ # Core browser modules
|
|
254
|
+
│ ├── browser-manager.ts # BrowserManager orchestrator
|
|
255
|
+
│ ├── chrome-launcher.ts # Chrome process management
|
|
256
|
+
│ ├── connection.ts # CDP connection + reconnect
|
|
257
|
+
│ ├── events.ts # CDP event listeners
|
|
258
|
+
│ ├── tabs.ts # Tab management
|
|
259
|
+
│ ├── types.ts # Shared types
|
|
260
|
+
│ ├── inspect/ # Snapshot, styles, element refs
|
|
261
|
+
│ ├── interaction/ # Dialogs, uploads, downloads, ref resolver
|
|
262
|
+
│ ├── network/ # Network buffer, monitor, header redaction
|
|
263
|
+
│ ├── performance/ # Tracing + analysis
|
|
264
|
+
│ └── security/ # Origin allow/block lists
|
|
265
|
+
├── cli/ # CLI commands (init)
|
|
266
|
+
├── commands/ # Tool command implementations
|
|
267
|
+
├── mcp/ # MCP server + tool registrations
|
|
268
|
+
└── util/ # Config, logger
|
|
214
269
|
```
|
|
215
270
|
|
|
216
271
|
## Claude Code Skill
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
import type { Client } from 'chrome-remote-interface';
|
|
2
|
+
import type { Config } from '../util/config.js';
|
|
3
|
+
import type { ViewportConfig } from '../viewport.js';
|
|
4
|
+
import type { BrowserEventCallback, BrowserState, LaunchOptions, TabInfo } from './types.js';
|
|
5
|
+
export declare class BrowserManager {
|
|
6
|
+
private readonly config;
|
|
7
|
+
private client;
|
|
8
|
+
private targetId;
|
|
9
|
+
private currentUrl;
|
|
10
|
+
private retryTimer;
|
|
11
|
+
private retryMs;
|
|
12
|
+
private destroyed;
|
|
13
|
+
private intentionalClose;
|
|
14
|
+
private eventCallback;
|
|
15
|
+
private pendingNetworkRequests;
|
|
16
|
+
private networkIdleTimer;
|
|
17
|
+
private networkIdleResolvers;
|
|
18
|
+
private chromeProcess;
|
|
19
|
+
private launchedCdpPort;
|
|
20
|
+
private viewportConfig;
|
|
21
|
+
private launchedUserDataDir;
|
|
22
|
+
private external;
|
|
23
|
+
private externalHost;
|
|
24
|
+
private externalPort;
|
|
25
|
+
constructor(config: Config);
|
|
26
|
+
setEventCallback(cb: BrowserEventCallback): void;
|
|
27
|
+
private emit;
|
|
28
|
+
getState(): BrowserState;
|
|
29
|
+
getClient(): Client | null;
|
|
30
|
+
isConnected(): boolean;
|
|
31
|
+
isLaunched(): boolean;
|
|
32
|
+
isExternalChrome(): boolean;
|
|
33
|
+
getViewportConfig(): ViewportConfig | null;
|
|
34
|
+
setViewportConfig(config: ViewportConfig): void;
|
|
35
|
+
static findChromeExecutable(override?: string): string;
|
|
36
|
+
static findFreePort(): Promise<number>;
|
|
37
|
+
private getConnectionInfo;
|
|
38
|
+
private makeEventListenerOpts;
|
|
39
|
+
launch(opts?: LaunchOptions): Promise<{
|
|
40
|
+
headless: boolean;
|
|
41
|
+
viewport: string;
|
|
42
|
+
}>;
|
|
43
|
+
connect(): Promise<void>;
|
|
44
|
+
connectExisting(opts: {
|
|
45
|
+
host?: string;
|
|
46
|
+
port?: number;
|
|
47
|
+
}): Promise<{
|
|
48
|
+
tabs: TabInfo[];
|
|
49
|
+
}>;
|
|
50
|
+
private checkNetworkIdle;
|
|
51
|
+
waitForNetworkIdle(timeoutMs?: number): Promise<void>;
|
|
52
|
+
listTabs(): Promise<TabInfo[]>;
|
|
53
|
+
createTab(url?: string): Promise<TabInfo>;
|
|
54
|
+
closeTab(targetId: string): Promise<void>;
|
|
55
|
+
switchTab(targetId: string): Promise<void>;
|
|
56
|
+
private scheduleReconnect;
|
|
57
|
+
private cleanupUserDataDir;
|
|
58
|
+
destroy(): Promise<void>;
|
|
59
|
+
}
|
|
60
|
+
//# sourceMappingURL=browser-manager.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"browser-manager.d.ts","sourceRoot":"","sources":["../../src/browser/browser-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EACV,oBAAoB,EACpB,YAAY,EACZ,aAAa,EACb,OAAO,EACR,MAAM,YAAY,CAAC;AAwBpB,qBAAa,cAAc;IAoBb,OAAO,CAAC,QAAQ,CAAC,MAAM;IAnBnC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,sBAAsB,CAAqB;IACnD,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,oBAAoB,CAAyB;IACrD,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,YAAY,CAAuB;gBAEd,MAAM,EAAE,MAAM;IAI3C,gBAAgB,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAIhD,OAAO,CAAC,IAAI;IAIZ,QAAQ,IAAI,YAAY;IASxB,SAAS,IAAI,MAAM,GAAG,IAAI;IAI1B,WAAW,IAAI,OAAO;IAItB,UAAU,IAAI,OAAO;IAIrB,gBAAgB,IAAI,OAAO;IAI3B,iBAAiB,IAAI,cAAc,GAAG,IAAI;IAI1C,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI/C,MAAM,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;WAIzC,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5C,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,qBAAqB;IA6BvB,MAAM,CACV,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAgF7C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCxB,eAAe,CAAC,IAAI,EAAE;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;IAyDhC,OAAO,CAAC,gBAAgB;IAWxB,kBAAkB,CAAC,SAAS,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAI9B,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzC,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BhD,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,kBAAkB;IAOpB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAmD/B"}
|