@docyrus/docyrus 0.0.58 → 0.0.60

package/resources/browser-tools/browser-tabs.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { ensureDaemon, cdp, evaluate, getMode, setSession } from "./browser-client.js";
+
+const args = process.argv.slice(2);
+const switchIdx = args.indexOf("--switch");
+const switchTo = switchIdx !== -1 ? parseInt(args[switchIdx + 1], 10) : null;
+
+await ensureDaemon();
+
+try {
+  const { targetInfos } = cdp("Target.getTargets");
+  const pages = targetInfos.filter((t) =>
+    t.type === "page" && !t.url.startsWith("chrome://") && !t.url.startsWith("chrome-extension://") && !t.url.startsWith("devtools://"),
+  );
+
+  if (switchTo !== null) {
+    if (switchTo < 0 || switchTo >= pages.length) {
+      console.error(`✗ Tab index ${switchTo} out of range (0-${pages.length - 1})`);
+      process.exit(1);
+    }
+    const target = pages[switchTo];
+    cdp("Target.activateTarget", { targetId: target.targetId });
+    const { sessionId } = cdp("Target.attachToTarget", { targetId: target.targetId, flatten: true });
+    setSession(sessionId);
+    // Enable domains on new session
+    for (const domain of ["Page", "DOM", "Runtime", "Network"]) {
+      try { cdp(`${domain}.enable`, {}, sessionId); } catch {}
+    }
+    console.log(JSON.stringify({ mode: getMode(), switched: switchTo, url: target.url, title: target.title }));
+  } else {
+    const tabs = pages.map((t, i) => ({ index: i, url: t.url, title: t.title }));
+    console.log(JSON.stringify({ mode: getMode(), count: tabs.length, tabs }));
+  }
+} catch (e) {
+  console.error(`✗ Tabs failed: ${e.message}`);
+  process.exit(1);
+}

package/resources/browser-tools/browser-wait.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { ensureDaemon, evaluate, waitForCondition, getMode, drainEvents } from "./browser-client.js";
+import { execFileSync } from "node:child_process";
+
+const args = process.argv.slice(2);
+const idle = args.includes("--idle");
+const selectorIdx = args.indexOf("--selector");
+const urlIdx = args.indexOf("--url");
+const timeoutIdx = args.indexOf("--timeout");
+const selector = selectorIdx !== -1 ? args[selectorIdx + 1] : null;
+const urlPattern = urlIdx !== -1 ? args[urlIdx + 1] : null;
+const timeout = timeoutIdx !== -1 ? parseInt(args[timeoutIdx + 1], 10) : 15000;
+const fixedDelay = args.find((a) => !a.startsWith("--") && /^\d+$/.test(a));
+
+if (!idle && !selector && !urlPattern && !fixedDelay) {
+  console.log("Usage: browser-wait.js [--idle] [--selector <css>] [--url <pattern>] [<ms>] [--timeout <ms>]");
+  process.exit(1);
+}
+
+await ensureDaemon();
+
+try {
+  if (fixedDelay) {
+    const ms = parseInt(fixedDelay, 10);
+    execFileSync(process.execPath, ["-e", `setTimeout(()=>{},${ms})`], { timeout: ms + 1000 });
+  } else if (idle) {
+    // Wait for network idle: no network events for 500ms
+    const deadline = Date.now() + timeout;
+    let lastActivity = Date.now();
+    while (Date.now() < deadline) {
+      const evts = drainEvents();
+      const networkEvts = evts.filter((e) => e.method.startsWith("Network."));
+      if (networkEvts.length > 0) { lastActivity = Date.now(); }
+      if (Date.now() - lastActivity > 500) { break; }
+      execFileSync(process.execPath, ["-e", "setTimeout(()=>{},100)"], { timeout: 1000 });
+    }
+  } else if (selector) {
+    waitForCondition(`!!document.querySelector(${JSON.stringify(selector)})`, timeout);
+  } else if (urlPattern) {
+    const regex = "^" + urlPattern.replace(/\*\*/g, ".*").replace(/(?<!\.\*)\*/g, "[^/]*") + "$";
+    waitForCondition(`new RegExp(${JSON.stringify(regex)}).test(window.location.href)`, timeout);
+  }
+
+  const url = evaluate("window.location.href");
+  console.log(JSON.stringify({ mode: getMode(), waited: true, url }));
+} catch (e) {
+  console.error(`✗ Wait failed: ${e.message}`);
+  process.exit(1);
+}

package/resources/pi-agent/skills/docyrus-chrome-devtools-cli/SKILL.md

@@ -1,97 +1,208 @@
 ---
 name: docyrus-browser-cli
-description: Use Docyrus CLI browser commands for browser automation (local Chrome or remote Cloudflare Browser Rendering). Use when you need to start a browser session, navigate pages, inspect DOM state, evaluate JavaScript, capture screenshots, pick elements interactively, inspect cookies, extract readable page content, or run CDP scripts.
+description: Use Docyrus CLI browser commands for browser automation (local Chrome or remote Cloudflare Browser Rendering). Use when you need to start a browser session, navigate pages, inspect page state, interact with elements, capture screenshots, evaluate JavaScript, read console output, inspect network requests, or run CDP scripts.
 ---
 
 # Docyrus Browser CLI
 
-Browser automation commands exposed through the `docyrus` CLI. Works in both local mode (Chrome on `:9222`) and remote sandbox mode (Cloudflare Browser Rendering via WSS).
+Browser automation via a persistent daemon that holds a raw CDP (Chrome DevTools Protocol) WebSocket connection. No Puppeteer/Playwright framework — direct CDP for speed and flexibility.
 
-All commands return JSON with a `mode` field (`"local"` or `"remote"`). In remote mode, responses include `devtoolsFrontendUrl` for live DevTools access.
+Works in both **local mode** (Chrome on `:9222`) and **remote sandbox mode** (Cloudflare Browser Rendering).
 
-## Commands
+## Architecture
+
+```
+docyrus browser <command>
+  → tool script (Node.js)
+    → HTTP request to daemon (localhost:9333)
+      → raw CDP WebSocket to Chrome/Cloudflare
+```
 
-Start a browser session:
+The daemon starts automatically on the first command and stays alive for 5 minutes of idle time. All commands share the same browser connection — no reconnection overhead.
+
+## Core Workflow for Self-Testing
 
 ```bash
+# 1. Start browser + daemon
 docyrus browser start
-docyrus browser start --profile
+
+# 2. Navigate to preview
+docyrus browser nav https://preview-url.example.com
+
+# 3. Wait for page to fully load
+docyrus browser wait --idle
+
+# 4. Discover interactive elements
+docyrus browser snapshot
+
+# 5. Interact using refs from snapshot
+docyrus browser fill @e2 "user@example.com"
+docyrus browser click @e3
+
+# 6. Verify results
+docyrus browser wait --selector ".success-message"
+docyrus browser screenshot
+docyrus browser console --level error
+docyrus browser network --method POST --status 2xx
 ```
 
-- Local mode: launches Chrome with remote debugging on `:9222`. `--profile` copies the user's default Chrome profile.
-- Sandbox mode: creates a Cloudflare Browser Rendering session and opens the app preview URL.
+## Commands
 
-Navigate tabs:
+### Session Management
 
 ```bash
-docyrus browser nav https://example.com
-docyrus browser nav https://example.com --new
-docyrus browser nav https://example.com --reload
+docyrus browser start                     # Start Chrome + daemon
+docyrus browser start --profile           # Start with user's Chrome profile (local only)
+docyrus browser close                     # Stop daemon and disconnect
 ```
 
-Run JavaScript in the active tab:
+### Navigation
+
+```bash
+docyrus browser nav <url>                 # Navigate active tab
+docyrus browser nav <url> --new           # Open in new tab
+docyrus browser nav <url> --reload        # Navigate and force reload
+```
+
+### Waiting
+
+```bash
+docyrus browser wait --idle               # Wait for network idle
+docyrus browser wait --selector "h1"      # Wait for element to appear
+docyrus browser wait --url "**/dashboard" # Wait for URL to match pattern
+docyrus browser wait 2000                 # Wait fixed milliseconds
+docyrus browser wait --idle --timeout 30000
+```
+
+### Page Snapshot (Element Discovery)
+
+```bash
+docyrus browser snapshot                  # Interactive elements with refs (@e1, @e2, ...)
+docyrus browser snapshot --all            # Include non-interactive elements
+docyrus browser snapshot --selector "#app" # Scope to a subtree
+```
+
+Returns:
+```json
+{
+  "snapshot": [
+    { "ref": "@e1", "tag": "input", "type": "email", "placeholder": "Email" },
+    { "ref": "@e2", "tag": "input", "type": "password" },
+    { "ref": "@e3", "tag": "button", "text": "Sign In" }
+  ]
+}
+```
+
+### Element Interaction
+
+Three targeting modes — refs, CSS selectors, or x,y coordinates:
+
+```bash
+docyrus browser click @e3                 # Click by snapshot ref
+docyrus browser click "button.submit"     # Click by CSS selector
+docyrus browser click 350 200             # Coordinate click (compositor-level)
+docyrus browser fill @e1 "user@test.com"  # Clear + type into input
+docyrus browser select @e4 "Option A"    # Select dropdown option
+```
+
+Coordinate clicks pass through iframes, shadow DOM, and cross-origin frames at the compositor level — no DOM piercing needed. Use `info` for viewport dimensions.
+
+### JavaScript Evaluation
 
 ```bash
 docyrus browser eval 'document.title'
-docyrus browser eval 'document.querySelectorAll("a").length'
+docyrus browser eval 'const rows = document.querySelectorAll("tr"); return rows.length'
+docyrus browser eval 'await fetch("/api/health").then(r => r.json())'
 ```
 
-Capture a screenshot of the active tab:
+Supports expressions and multi-statement code. Uses CDP `Runtime.evaluate` with `awaitPromise: true`.
+
+### Screenshots
 
 ```bash
-docyrus browser screenshot
+docyrus browser screenshot               # Viewport screenshot → /tmp
+docyrus browser screenshot --full         # Full page
+docyrus browser screenshot --base64       # Base64 in JSON (for remote/sandbox mode)
+```
+
+### Console Messages
+
+```bash
+docyrus browser console                   # Captured logs (last 50)
+docyrus browser console --level error     # Only errors
+docyrus browser console --listen 5000     # Listen for 5 seconds via CDP events
 ```
 
-Interactively pick DOM elements in the visible browser:
+Run `console` once early to install the interceptor.
+
+### Network Inspection
 
 ```bash
-docyrus browser pick "Click the submit button"
+docyrus browser network                   # All captured requests
+docyrus browser network --method POST     # Only POST requests
+docyrus browser network --status 4xx      # Only 4xx responses
+docyrus browser network --url "/api/"     # URL substring filter
+docyrus browser network --listen 5000     # Listen for 5 seconds
 ```
 
-Inspect cookies for the active tab:
+Network events are captured automatically by the daemon (CDP `Network.enable`).
+
+### Docyrus Devtools
+
+Read runtime diagnostics from `@docyrus/devtools` (must be loaded on the page):
 
 ```bash
-docyrus browser cookies
+docyrus browser devtools state              # Full devtools state
+docyrus browser devtools errors             # Collected API errors
+docyrus browser devtools issues             # Detected API usage issues (e.g. missing fields, bad queries)
+docyrus browser devtools console            # Console entries captured by devtools
+docyrus browser devtools console --level error  # Filtered by level
 ```
 
-Extract readable content as markdown:
+Use after interacting with a Docyrus-backed app to catch API misuse, failed requests, and runtime issues that `console --level error` alone would miss.
+
+### Content Extraction
 
 ```bash
-docyrus browser content https://example.com
+docyrus browser content <url>             # Extract readable markdown from URL
 ```
 
-Run a CDP script on the active browser session:
+### Cookies
 
 ```bash
-docyrus browser run-script my-script.js
-docyrus browser run-script my-script.js --appId <appId>
-docyrus browser run-script my-script.js --appSlug my-app
+docyrus browser cookies                   # All cookies (via CDP Network.getCookies)
+docyrus browser cookies --name "session"
+docyrus browser cookies --domain ".app.com"
 ```
 
-- The script receives `browser` (Puppeteer Browser) and `page` (a new Page) as function arguments.
-- Whatever the script returns is printed as JSON to stdout.
+### Page Info
+
+```bash
+docyrus browser info                      # URL, title, viewport, scroll, page dimensions
+```
 
-Example script (`scrape-title.js`):
+### Tab Management
 
-```js
-await page.goto("https://example.com");
-const title = await page.title();
-return { title };
+```bash
+docyrus browser tabs                      # List all tabs
+docyrus browser tabs --switch 1           # Switch to tab by index
 ```
 
-## When To Use
+### CDP Scripts
+
+```bash
+docyrus browser run-script script.js
+```
 
-- Visible browser automation is required.
-- A page needs JavaScript execution before content is available.
-- You need to inspect DOM state without guessing selectors.
-- You want the user to click elements directly through an interactive picker.
-- You need quick page extraction or screenshot capture from a real browser session.
-- You need to run CDP scripts against a remote headless browser from within a sandbox.
+The script receives raw CDP helpers: `cdp`, `evaluate`, `navigate`, `captureScreenshot`, `clickAt`, `typeText`, `pressKey`, `pageInfo`, `drainEvents`, `waitForCondition`.
 
-## Working Style
+## Tips for AI Agents
 
-- Start a session first with `docyrus browser start` if the browser is not already available.
-- Prefer `docyrus browser eval` for DOM inspection and structured page state.
-- Use `docyrus browser pick` when element targeting is ambiguous or user choice matters.
-- Use `docyrus browser content` for readable markdown extraction from article-like pages.
-- Use `docyrus browser run-script` to run full Puppeteer scripts on the active browser session.
+1. `start` auto-launches the daemon — subsequent commands are fast (no reconnection)
+2. Always `wait --idle` after `nav` before taking snapshots or screenshots
+3. Use `snapshot` → refs → `click`/`fill` for reliable element targeting
+4. Re-snapshot after interactions to get fresh refs
+5. Use coordinate `click 350 200` for elements inside iframes or shadow DOM
+6. Check `console --level error` and `network --status 5xx` to catch runtime issues
+7. Use `screenshot --base64` in remote/sandbox mode
+8. `close` stops the daemon; it auto-stops after 5 minutes idle anyway