barebrowse 0.11.0 → 0.13.0

package/types/interact.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Click an element by its backendDOMNodeId.
+ * Scrolls into view, resolves coordinates, then dispatches mousePressed + mouseReleased.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ */
+export function click(session: object, backendNodeId: number): Promise<void>;
+/**
+ * Type text into an element by its backendDOMNodeId.
+ * Default: DOM.focus + Input.insertText (fast, no key events).
+ * With { keyEvents: true }: dispatches keyDown/keyUp per character (triggers handlers).
+ * With { clear: true }: selects all existing text and deletes it before typing.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ * @param {string} text - Text to type
+ * @param {object} [opts]
+ * @param {boolean} [opts.keyEvents=false] - Use char-by-char key events
+ * @param {boolean} [opts.clear=false] - Clear existing content before typing
+ */
+export function type(session: object, backendNodeId: number, text: string, opts?: {
+    keyEvents?: boolean | undefined;
+    clear?: boolean | undefined;
+}): Promise<void>;
+/**
+ * Press a special key (Enter, Tab, Escape, etc.).
+ * Dispatches keyDown + keyUp for the named key.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {string} key - Key name (e.g. 'Enter', 'Tab', 'Escape', 'ArrowDown')
+ */
+export function press(session: object, key: string): Promise<void>;
+/**
+ * Scroll the page via mouseWheel event.
+ * Dispatches at viewport center by default, or at given coordinates.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} deltaY - Pixels to scroll (positive = down, negative = up)
+ * @param {number} [x=400] - X coordinate for scroll event
+ * @param {number} [y=300] - Y coordinate for scroll event
+ */
+export function scroll(session: object, deltaY: number, x?: number, y?: number): Promise<void>;
+/**
+ * Hover over an element by its backendDOMNodeId.
+ * Scrolls into view, then dispatches mouseMoved at center.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID
+ */
+export function hover(session: object, backendNodeId: number): Promise<void>;
+/**
+ * Select a value in a <select> element or custom dropdown.
+ *
+ * Strategy 1: Native <select> — set .value + dispatch 'change' event.
+ * Strategy 2: Custom dropdown — click to open, find matching option, click it.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID of the select/combobox
+ * @param {string} value - Value or visible text to select
+ */
+export function select(session: object, backendNodeId: number, value: string): Promise<void>;
+/**
+ * Drag one element to another.
+ * Scrolls source into view, mouse down, move to target center, mouse up.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} fromNodeId - Source element backendDOMNodeId
+ * @param {number} toNodeId - Target element backendDOMNodeId
+ */
+export function drag(session: object, fromNodeId: number, toNodeId: number): Promise<void>;
+/**
+ * Upload files to a file input element.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ * @param {number} backendNodeId - Backend DOM node ID of the file input
+ * @param {string[]} files - Absolute paths to files to upload
+ */
+export function upload(session: object, backendNodeId: number, files: string[]): Promise<void>;

package/types/network-idle.d.ts

@@ -0,0 +1,19 @@
+/**
+ * network-idle.js — wait until the page's network has been idle for N ms.
+ *
+ * Tracks in-flight requests by requestId in a Set, so an orphan
+ * loadingFinished/Failed (event for a request whose requestWillBeSent
+ * arrived before our listener attached) is a harmless no-op instead of
+ * driving a counter negative and resolving prematurely.
+ */
+/**
+ * @param {object} session - CDP session-scoped handle with .on() returning unsub
+ * @param {object} [opts]
+ * @param {number} [opts.timeout=30000] - Max wait time before reject
+ * @param {number} [opts.idle=500] - Required idle duration before resolve
+ * @returns {Promise<void>}
+ */
+export function waitForNetworkIdle(session: object, opts?: {
+    timeout?: number | undefined;
+    idle?: number | undefined;
+}): Promise<void>;

package/types/prune.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Prune an ARIA tree for agent consumption.
+ *
+ * @param {object} tree - Root node from buildTree() (CDP format)
+ * @param {object} [options]
+ * @param {'act'|'browse'|'navigate'|'full'|'read'} [options.mode='act'] - Pruning mode ('read' is an alias for 'browse')
+ * @param {string} [options.context=''] - Search context for relevance filtering
+ * @returns {object|null} Pruned tree
+ */
+export function prune(tree: object, options?: {
+    mode?: "act" | "browse" | "navigate" | "full" | "read" | undefined;
+    context?: string | undefined;
+}): object | null;

package/types/readable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Render a readable() result as a text block: a short header (title / byline /
+ * confidence, with the fall-back hint inline when present) then the body. On a
+ * failed extraction it returns the hint. Shared by the MCP, bareagent, and
+ * CLI/daemon surfaces so their output can't drift apart.
+ * @param {object} r - a readable() result.
+ * @returns {string}
+ */
+export function formatReadable(r: object): string;
+/**
+ * Extract the main article from the current page.
+ * @param {object} session - CDP session-scoped handle (.send()).
+ * @returns {Promise<object>} One of:
+ *   { ok: false, hint }                              — no article content found
+ *   { ok: true, title, byline, text, length,
+ *     confidence: 'high'|'low', readerable, hint? }  — extracted article
+ */
+export function readable(session: object): Promise<object>;

package/types/session-client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Read session.json from the output directory.
+ * @returns {{ port: number, pid: number, token?: string, startedAt: string } | null}
+ */
+export function readSession(outputDir: any): {
+    port: number;
+    pid: number;
+    token?: string;
+    startedAt: string;
+} | null;
+/**
+ * Check if the daemon is alive by hitting GET /status.
+ */
+export function isAlive(outputDir: any): Promise<boolean>;
+/**
+ * Send a command to the running daemon.
+ * @returns {Promise<object>} The daemon's response
+ */
+export function sendCommand(command: any, args: any, outputDir: any): Promise<object>;

package/types/stealth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Apply stealth patches to a CDP session.
+ * Must be called before any navigation.
+ *
+ * Splits into two layers:
+ *   1. Network.setUserAgentOverride strips "HeadlessChrome" from the UA
+ *      that ships in HTTP request headers AND that navigator.userAgent
+ *      reports — `--headless=new` leaves "HeadlessChrome" in there.
+ *   2. Page.addScriptToEvaluateOnNewDocument injects the JS-level patches
+ *      before any page script runs.
+ *
+ * @param {object} session - Session-scoped CDP handle
+ */
+export function applyStealth(session: object): Promise<void>;

package/types/url-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Throw if `url` is unsafe to navigate to under the given policy.
+ * @param {string} url
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowLocalUrls=false] - permit file:/chrome:/etc.
+ * @param {boolean} [opts.blockPrivateNetwork=false] - reject loopback/RFC-1918/metadata.
+ */
+export function assertNavigable(url: string, opts?: {
+    allowLocalUrls?: boolean | undefined;
+    blockPrivateNetwork?: boolean | undefined;
+}): void;
+/**
+ * Throw if any file in `files` resolves outside `uploadDir`. Both the base
+ * dir and each file are resolved through realpath, so symlinks (in either the
+ * base path — e.g. macOS /tmp → /private/tmp — or the file) can't be used to
+ * escape the sandbox or to false-reject a legitimate file.
+ * No-op when `uploadDir` is falsy (no restriction configured).
+ * @param {string|string[]} files
+ * @param {string|null} uploadDir
+ */
+export function assertUploadAllowed(files: string | string[], uploadDir: string | null): void;
+/**
+ * @param {string} host - hostname (no brackets for IPv6)
+ * @returns {boolean} true if it names a private/loopback/link-local/internal host
+ */
+export function isPrivateHost(host: string): boolean;

package/.github/workflows/publish.yml

@@ -1,26 +0,0 @@
-name: Publish to npm
-
-# Trusted publishing via OIDC — no NPM_TOKEN needed.
-# Configure the trusted publisher at npmjs.com first (see repo notes).
-on:
-  workflow_dispatch:        # manual "Run workflow" button
-  release:
-    types: [published]      # also publishes when you cut a GitHub release
-
-permissions:
-  contents: read
-  id-token: write           # required: lets npm mint OIDC credentials
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          registry-url: 'https://registry.npmjs.org'
-      - name: Upgrade npm (trusted publishing needs >= 11.5.1)
-        run: npm install -g npm@latest
-      - name: Publish
-        run: npm publish

package/commands/barebrowse/SKILL.md

@@ -1,137 +0,0 @@
----
-name: barebrowse
-description: Browser automation using the user's real browser with real cookies. Handles consent walls, login sessions, and bot detection automatically.
-allowed-tools: Bash(barebrowse:*)
----
-
-# barebrowse CLI — Browser Automation for Agents
-
-Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, JS dialogs, and bot detection automatically.
-
-## Quick Start
-
-```bash
-barebrowse open https://example.com    # Start session + navigate
-barebrowse snapshot                    # Get ARIA snapshot → .barebrowse/page-*.yml
-barebrowse click 8                     # Click element with ref=8
-barebrowse snapshot                    # See result
-barebrowse close                       # End session
-```
-
-All output files go to `.barebrowse/` in the current directory. Read them with the Read tool when needed.
-
-## Commands
-
-### Session Lifecycle
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse open [url] [flags]` | Start browser session. Optionally navigate to URL. |
-| `barebrowse close` | Close session and kill browser. |
-| `barebrowse status` | Check if session is running. |
-
-**Open flags:**
-- `--mode=headless|headed|hybrid` — Browser mode (default: headless)
-- `--no-cookies` — Skip cookie injection
-- `--browser=firefox|chromium` — Cookie source
-- `--prune-mode=act|read` — Default pruning mode
-- `--timeout=N` — Navigation timeout in ms
-- `--proxy=URL` — HTTP/SOCKS proxy server
-- `--viewport=WxH` — Viewport size (e.g. 1280x720)
-- `--storage-state=FILE` — Load cookies/localStorage from JSON file
-- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
-- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
-
-> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
-
-### Navigation
-
-| Command | Output |
-|---------|--------|
-| `barebrowse goto <url>` | Navigates, waits for load, dismisses consent. Prints "ok". |
-| `barebrowse back` | Go back in browser history. |
-| `barebrowse forward` | Go forward in browser history. |
-| `barebrowse snapshot` | ARIA snapshot → `.barebrowse/page-<timestamp>.yml` |
-| `barebrowse snapshot --mode=read` | Read mode: keeps all text (for content extraction) |
-| `barebrowse screenshot` | Screenshot → `.barebrowse/screenshot-<timestamp>.png` |
-| `barebrowse pdf [--landscape]` | PDF export → `.barebrowse/page-<timestamp>.pdf` |
-
-### Interaction
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse click <ref>` | Click element (scrolls into view first) |
-| `barebrowse type <ref> <text>` | Type text into element |
-| `barebrowse fill <ref> <text>` | Clear existing content + type new text |
-| `barebrowse press <key>` | Press key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| `barebrowse scroll <deltaY>` | Scroll page (positive=down, negative=up) |
-| `barebrowse hover <ref>` | Hover over element (triggers tooltips) |
-| `barebrowse select <ref> <value>` | Select dropdown option |
-| `barebrowse drag <fromRef> <toRef>` | Drag element to another element |
-| `barebrowse upload <ref> <files..>` | Upload file(s) to a file input element |
-
-### Tabs
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse tabs` | List open tabs (index, url, title) |
-| `barebrowse tab <index>` | Switch to tab by index |
-
-### Debugging
-
-| Command | Output |
-|---------|--------|
-| `barebrowse eval <expression>` | Evaluate JS in page, print result |
-| `barebrowse wait-idle` | Wait for network idle (no requests for 500ms) |
-| `barebrowse wait-for [opts]` | Wait for content to appear on page |
-| `barebrowse console-logs` | Console logs → `.barebrowse/console-<timestamp>.json` |
-| `barebrowse network-log` | Network log → `.barebrowse/network-<timestamp>.json` |
-| `barebrowse network-log --failed` | Only failed/4xx/5xx requests |
-| `barebrowse dialog-log` | JS dialog log → `.barebrowse/dialogs-<timestamp>.json` |
-| `barebrowse save-state` | Cookies + localStorage → `.barebrowse/state-<timestamp>.json` |
-
-**wait-for flags:**
-- `--text=STRING` — Wait for text to appear in page body
-- `--selector=CSS` — Wait for CSS selector to match
-- `--timeout=N` — Max wait time in ms (default: 30000)
-
-## Snapshot Format
-
-The snapshot is a YAML-like ARIA tree. Each line is one node:
-
-```
-# https://example.com/
-# 379 chars → 45 chars (88% pruned)
-- heading "Example Domain" [level=1] [ref=3]
-```
-
-- `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload
-- Refs change on every snapshot — always take a fresh snapshot before interacting
-- **act mode** (default): interactive elements + labels — for clicking, typing, navigating
-- **read mode**: all text content — for reading articles, extracting data
-
-## Workflow Pattern
-
-1. `barebrowse open <url>` — start session
-2. `barebrowse snapshot` — observe page (read the .yml file)
-3. Decide action based on snapshot content
-4. `barebrowse click/type/fill/press/scroll/drag/upload <ref>` — act
-5. `barebrowse snapshot` — observe result (refs are now different!)
-6. Repeat 3-5 until goal achieved
-7. `barebrowse close` — clean up
-
-## Tips
-
-- **Always snapshot before interacting** — refs are ephemeral and change every time
-- **Use `fill` instead of `type`** when replacing existing text in input fields
-- **Use `--mode=read`** for snapshot when you need to extract article content or data
-- **Use `back`/`forward`** to navigate browser history instead of re-entering URLs
-- **Use `upload`** for file inputs — pass absolute paths to the files
-- **Use `wait-for`** when content loads asynchronously — more reliable than `wait-idle`
-- **Check `dialog-log`** if JS alerts/confirms were auto-dismissed during your session
-- **Use `save-state`** to persist cookies/localStorage for later sessions via `--storage-state`
-- **Check `console-logs`** when page behavior seems wrong — JS errors show up there
-- **Check `network-log --failed`** to debug missing content or broken API calls
-- **Use `eval`** as an escape hatch when ARIA tree doesn't show what you need
-- **One session per project** — `.barebrowse/` is project-scoped
-- For bot-detected sites, use `--mode=headed` (requires browser with `--remote-debugging-port=9222`)

package/commands/barebrowse.md

@@ -1,136 +0,0 @@
----
-name: barebrowse
-description: Browser automation using the user's real browser with real cookies. Handles consent walls, login sessions, and bot detection automatically.
-allowed-tools: Bash(barebrowse:*)
----
-# barebrowse CLI — Browser Automation for Agents
-
-Browse any URL using the user's real browser with real cookies. Returns pruned ARIA snapshots (40-90% smaller than raw) with `[ref=N]` markers for interaction. Handles cookie consent, login sessions, JS dialogs, and bot detection automatically.
-
-## Quick Start
-
-```bash
-barebrowse open https://example.com    # Start session + navigate
-barebrowse snapshot                    # Get ARIA snapshot → .barebrowse/page-*.yml
-barebrowse click 8                     # Click element with ref=8
-barebrowse snapshot                    # See result
-barebrowse close                       # End session
-```
-
-All output files go to `.barebrowse/` in the current directory. Read them with the Read tool when needed.
-
-## Commands
-
-### Session Lifecycle
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse open [url] [flags]` | Start browser session. Optionally navigate to URL. |
-| `barebrowse close` | Close session and kill browser. |
-| `barebrowse status` | Check if session is running. |
-
-**Open flags:**
-- `--mode=headless|headed|hybrid` — Browser mode (default: headless)
-- `--no-cookies` — Skip cookie injection
-- `--browser=firefox|chromium` — Cookie source
-- `--prune-mode=act|read` — Default pruning mode
-- `--timeout=N` — Navigation timeout in ms
-- `--proxy=URL` — HTTP/SOCKS proxy server
-- `--viewport=WxH` — Viewport size (e.g. 1280x720)
-- `--storage-state=FILE` — Load cookies/localStorage from JSON file
-- `--block-private-network` — SSRF guard: refuse loopback / RFC-1918 / link-local / cloud-metadata hosts (v0.11.0)
-- `--upload-dir=DIR` — Sandbox uploads to DIR; reject files outside it (v0.11.0)
-
-> Security (v0.11.0): `file:`/`chrome:`/etc. navigation is blocked by default, and the daemon requires a per-session token (handled transparently by the CLI). Snapshots and saved state are written owner-only (`0600`).
-
-### Navigation
-
-| Command | Output |
-|---------|--------|
-| `barebrowse goto <url>` | Navigates, waits for load, dismisses consent. Prints "ok". |
-| `barebrowse back` | Go back in browser history. |
-| `barebrowse forward` | Go forward in browser history. |
-| `barebrowse snapshot` | ARIA snapshot → `.barebrowse/page-<timestamp>.yml` |
-| `barebrowse snapshot --mode=read` | Read mode: keeps all text (for content extraction) |
-| `barebrowse screenshot` | Screenshot → `.barebrowse/screenshot-<timestamp>.png` |
-| `barebrowse pdf [--landscape]` | PDF export → `.barebrowse/page-<timestamp>.pdf` |
-
-### Interaction
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse click <ref>` | Click element (scrolls into view first) |
-| `barebrowse type <ref> <text>` | Type text into element |
-| `barebrowse fill <ref> <text>` | Clear existing content + type new text |
-| `barebrowse press <key>` | Press key: Enter, Tab, Escape, Backspace, Delete, arrows, Space |
-| `barebrowse scroll <deltaY>` | Scroll page (positive=down, negative=up) |
-| `barebrowse hover <ref>` | Hover over element (triggers tooltips) |
-| `barebrowse select <ref> <value>` | Select dropdown option |
-| `barebrowse drag <fromRef> <toRef>` | Drag element to another element |
-| `barebrowse upload <ref> <files..>` | Upload file(s) to a file input element |
-
-### Tabs
-
-| Command | Description |
-|---------|-------------|
-| `barebrowse tabs` | List open tabs (index, url, title) |
-| `barebrowse tab <index>` | Switch to tab by index |
-
-### Debugging
-
-| Command | Output |
-|---------|--------|
-| `barebrowse eval <expression>` | Evaluate JS in page, print result |
-| `barebrowse wait-idle` | Wait for network idle (no requests for 500ms) |
-| `barebrowse wait-for [opts]` | Wait for content to appear on page |
-| `barebrowse console-logs` | Console logs → `.barebrowse/console-<timestamp>.json` |
-| `barebrowse network-log` | Network log → `.barebrowse/network-<timestamp>.json` |
-| `barebrowse network-log --failed` | Only failed/4xx/5xx requests |
-| `barebrowse dialog-log` | JS dialog log → `.barebrowse/dialogs-<timestamp>.json` |
-| `barebrowse save-state` | Cookies + localStorage → `.barebrowse/state-<timestamp>.json` |
-
-**wait-for flags:**
-- `--text=STRING` — Wait for text to appear in page body
-- `--selector=CSS` — Wait for CSS selector to match
-- `--timeout=N` — Max wait time in ms (default: 30000)
-
-## Snapshot Format
-
-The snapshot is a YAML-like ARIA tree. Each line is one node:
-
-```
-# https://example.com/
-# 379 chars → 45 chars (88% pruned)
-- heading "Example Domain" [level=1] [ref=3]
-```
-
-- `[ref=N]` — Use this number with click, type, fill, hover, select, drag, upload
-- Refs change on every snapshot — always take a fresh snapshot before interacting
-- **act mode** (default): interactive elements + labels — for clicking, typing, navigating
-- **read mode**: all text content — for reading articles, extracting data
-
-## Workflow Pattern
-
-1. `barebrowse open <url>` — start session
-2. `barebrowse snapshot` — observe page (read the .yml file)
-3. Decide action based on snapshot content
-4. `barebrowse click/type/fill/press/scroll/drag/upload <ref>` — act
-5. `barebrowse snapshot` — observe result (refs are now different!)
-6. Repeat 3-5 until goal achieved
-7. `barebrowse close` — clean up
-
-## Tips
-
-- **Always snapshot before interacting** — refs are ephemeral and change every time
-- **Use `fill` instead of `type`** when replacing existing text in input fields
-- **Use `--mode=read`** for snapshot when you need to extract article content or data
-- **Use `back`/`forward`** to navigate browser history instead of re-entering URLs
-- **Use `upload`** for file inputs — pass absolute paths to the files
-- **Use `wait-for`** when content loads asynchronously — more reliable than `wait-idle`
-- **Check `dialog-log`** if JS alerts/confirms were auto-dismissed during your session
-- **Use `save-state`** to persist cookies/localStorage for later sessions via `--storage-state`
-- **Check `console-logs`** when page behavior seems wrong — JS errors show up there
-- **Check `network-log --failed`** to debug missing content or broken API calls
-- **Use `eval`** as an escape hatch when ARIA tree doesn't show what you need
-- **One session per project** — `.barebrowse/` is project-scoped
-- For bot-detected sites, use `--mode=headed` (requires browser with `--remote-debugging-port=9222`)