cdpilot 0.9.0 → 0.9.2

package/README.md

@@ -76,7 +76,7 @@ npx cdpilot <command>
 npm i -g cdpilot
 ```
 
-**Requirements:** Node.js 18+ and one of: Brave Browser, Google Chrome, or Chromium.
+**Requirements:** Node.js 18+, Python 3.10+, and one of: Brave Browser, Google Chrome, or Chromium. (The Python `websockets` module is auto-installed by the pre-flight wizard on first launch.)
 
 ### First-time setup
 
@@ -124,7 +124,7 @@ See [CHANGELOG.md](CHANGELOG.md) for the full list with rationale.
 ### Navigation & Content
 
 ```bash
-cdpilot go <url>              # Navigate to URL
+cdpilot go <url>              # Navigate to URL (alias: open <url>)
 cdpilot content               # Get page text content
 cdpilot html                  # Get page HTML
 cdpilot shot [file]           # Take screenshot (PNG)
@@ -537,11 +537,26 @@ cdpilot profile warm          # age the profile for reCAPTCHA v3 score
 which nudges reCAPTCHA v3's behavioral score upward over time. Slow by
 design — run it ahead of a session, not inline.
 
-Verified against public bot-detection panels:
-- **bot.sannysoft.com:** 24/24 PASS (WebDriver, Chrome obj, Plugins as PluginArray, WebGL, PHANTOM_*, HEADCHR_*, SELENIUM_DRIVER)
-- **bot.incolumitas.com** intoli: 6/6 OK — new-tests: 6/7 OK (one FAIL = pure CDP presence, cannot be JS-patched)
-- **nowsecure.nl** (Cloudflare full challenge): passed
-- **arh.antoinevastel.com/areyouheadless:** "You are not Chrome headless"
+Public bot-detection panels, measured 2026-09-27, **headless** Brave (Chrome 154)
+([method and raw results](.claude/docs/stealth-panel-olcumu-2026-09-27.md)):
+
+| `mode` | bot.sannysoft.com (31 rows) | incolumitas intoli | incolumitas fpscanner | incolumitas new-tests |
+|---|---|---|---|---|
+| `regular` (no patches, default) | 28 pass / 3 fail | 5/6 | 17 ok / 3 fail / 1 warn | all ok |
+| `stealth` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+| `undetected` | 31 pass | 6/6 | 19 ok / 1 fail / 1 warn | all ok |
+
+- The remaining fpscanner fail is `'webdriver' in navigator`, which is true in every modern
+  Chrome; faking it away would make cdpilot the odd one out.
+- `regular`'s fails all come from the `HeadlessChrome` user agent. `stealth`/`undetected`
+  rewrite it for the page load that `go` starts; a later, separate command in the same page
+  can still read `HeadlessChrome`.
+- new-tests: every key is ok; `connectionRTT` is reported as unknown in all tiers.
+- nowsecure.nl and areyouheadless could not be measured (a fixed always-interactive
+  Turnstile test key; HTTP 502).
+
+Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4.x in April
+2026; they are replaced by the table above.
 
 ### Reliability
 
@@ -559,23 +574,45 @@ until cdpilot health >/dev/null; do cdpilot launch; sleep 2; done
 Surfaces today's Brave crash count from `~/Library/Logs/DiagnosticReports/`
 on macOS — spot degradation before your automation silently stalls.
 
+**Auto-launch.** A page command (`go`, `content`, `click`, `shot`, …) that finds
+the browser not running starts it the same way `cdpilot launch` does (same
+profile, same headless/visible setting), then carries on, printing one line to
+stderr: `cdpilot: browser was not running — launched it (CDPILOT_NO_AUTOLAUNCH=1 to disable)`.
+Lifecycle, status and configuration commands (`launch`, `stop`, `close`,
+`close-tab`, `stop-all`, `project-stop`, `session-close`, `status`, `health`,
+`tabs`, `sessions`, `projects`, `headless`, `proxy`, `browser`, `extensions`,
+`mcp`, `serve`, …) never launch. `CDPILOT_NO_AUTOLAUNCH=1` restores the old
+"CDP connection error. Is the browser running?" error and exit code 1.
+
+**Timeouts.** Any command takes `--timeout <seconds>`, before or after the
+command name, or a default from `CDPILOT_TIMEOUT` (the flag wins; `0`
+disables). It bounds the whole command's wall-clock: on expiry cdpilot prints
+`cdpilot: timed out after <N>s (<command>)` to stderr, kills the child processes
+it started and exits with code **124** (like GNU `timeout`). A browser that was
+already up and registered is left running.
+
+```bash
+cdpilot --timeout 10 click "#submit"      # before the command...
+cdpilot shot page.png --timeout 30        # ...or after it
+CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each script line)
+```
+
+For `mcp` and `serve` the value is not applied to the long-running server
+itself; it is passed on to every tool call / request it runs.
+
 ### Scaling & Workstation Use
 
 ```bash
-CDPILOT_POOL_SIZE=4 cdpilot launch   # 4 separate browser processes
 CDPILOT_OFFSCREEN=1 cdpilot launch   # headed, but no window on your screen
 ```
 
-- **Multi-instance pool** (`CDPILOT_POOL_SIZE=N`) starts N independent browser
-  processes and dispatches work to the least-loaded one, for `N × per-instance`
-  parallelism. Default is `1` — single instance, no change for existing users.
 - **Off-screen mode** (`CDPILOT_OFFSCREEN=1`) keeps the browser headed (real
   rendering, no headless fingerprint) but positions the window where it can't
   steal focus — meant for automating on a workstation you're also using.
-- **Docker + Xvfb harness** (`cdpilot-bench/docker/`) runs headed-in-Xvfb so
-  bench/automation runs never pop a window on the host display. CI-ready. Note
-  that software rendering (no GPU) lowers anti-bot scores versus native — it's
-  an isolated environment for reproducibility, not the headline configuration.
+- **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — planned, not shipped yet.
+  See [Roadmap](#coming-soon).
+- **Docker + Xvfb harness** — used in a separate, private benchmark
+  repo (`cdpilot-bench`), not part of this package.
 
 ## Use with AI Agents
 
@@ -624,7 +661,8 @@ print(result.stdout)
 | `BROWSER_SESSION` | Auto | Session identifier |
 | `CDPILOT_MODE` | `regular` | Stealth tier override (`regular`/`stealth`/`undetected`) |
 | `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
-| `CDPILOT_POOL_SIZE` | `1` | N separate browser processes, least-loaded dispatch |
+| `CDPILOT_TIMEOUT` | unset | Default `--timeout` in seconds for every command (flag wins, `0` disables); expiry exits 124 |
+| `CDPILOT_NO_AUTOLAUNCH` | `0` | `1` = page commands fail with the old "Is the browser running?" error instead of launching the browser |
 
 ## How It Works
 
@@ -636,7 +674,7 @@ print(result.stdout)
        │                                        │
        │  Zero dependencies                     │  Isolated profile
        │  Pure HTTP + WebSocket                 │  Separate from your
-       │  ~2500 lines, single file              │  personal browser
+       │  single file, stdlib + websockets      │  personal browser
        └────────────────────────────────────────┘
 ```
 
@@ -694,8 +732,8 @@ The full adaptive layer is bench-neutral vs baseline (30/80 vs 30/80) for Stealt
 
 | Feature | cdpilot | Puppeteer | Playwright | Selenium |
 |---------|-----------|-----------|------------|----------|
-| Install size | **~50KB** | 400MB+ | 200MB+ | 100MB+ |
-| Dependencies | **0** | 50+ | 30+ | Java + drivers |
+| Install size | **one Python file + a small Node launcher, no node_modules** | 400MB+ | 200MB+ | 100MB+ |
+| Dependencies | **0 npm** (Python: `websockets`, auto-installed) | 50+ | 30+ | Java + drivers |
 | Setup time | **instant** | minutes | minutes | painful |
 | AI-agent ready | **yes** | manual | manual | manual |
 | Browser download | **no** | yes (Chromium) | yes (3 browsers) | no |
@@ -753,7 +791,8 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [x] 70+ CLI commands (navigate, click, fill, screenshot, PDF, console, network, video understanding, friction ladder...)
 - [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
 - [x] **10 built-in test assertions** — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff
-- [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured data with @ref references, 500x fewer tokens than screenshots
+- [x] **`test` runner + `trace` viewer** — `cdpilot test [--watch]` runs `*.cdpt.js` files; `cdpilot trace open <run>` opens a time-travel trace viewer for a run
+- [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured text with @ref handles the agent can act on directly, no vision model needed; 1.4–42× smaller than the page's raw HTML on the four pages we measured (2026-09-27). Not always cheaper than a screenshot: link-heavy pages produce more text than a small screenshot costs
 - [x] **Token-efficient screenshots** — element-level crop (13x smaller), JPEG quality control, format selection
 - [x] **Vision fallback** (`describe`) — a11y + screenshot + text in one call
 - [x] **Annotated screenshots** — @N badge overlays on interactive elements
@@ -780,7 +819,7 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [x] **Three-tier stealth mode** (`mode regular|stealth|undetected`) — single switch over fingerprint surface, with per-host adaptive tier learning
 - [x] **Press-and-hold solver** (`press-hold`) — humanized press → hold → release gesture (Gaussian 3–7s + micro-jitter) for PerimeterX/HUMAN behavioral challenges; `captcha-solve` auto-routes here
 - [x] **Image CAPTCHA + profile warming** — offline Amazon image OCR (optional `amazoncaptcha` lib) + BYOK image-to-text (capsolver/2captcha); `profile warm` ages the profile for reCAPTCHA v3 score
-- [x] **Multi-instance pool + off-screen mode** (`CDPILOT_POOL_SIZE`, `CDPILOT_OFFSCREEN`) — N parallel browser processes; headed rendering without stealing window focus
+- [x] **Off-screen mode** (`CDPILOT_OFFSCREEN`) — headed rendering without stealing window focus
 - [x] **Data extraction** (`extract`) — structured DOM data in text, JSON, or list format
 - [x] **Page observation** (`observe`) — list all interactive elements with available actions
 - [x] **Script runner** (`run`) — execute `.cdp` script files with pass/fail reporting
@@ -788,6 +827,7 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 ### Coming Soon
 
 - [ ] **iframe** support — interact with elements inside iframes (Shadow DOM traversal already shipped in smart commands)
+- [ ] **Multi-instance pool** (`CDPILOT_POOL_SIZE`) — N independent browser processes with least-loaded dispatch
 - [ ] **Session recording & replay** — record browser sessions and replay them deterministically
 - [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
 - [ ] **cdpilot Cloud** — hosted browser sessions API, REST + WebSocket MCP endpoint

package/bin/cdpilot.js

@@ -321,7 +321,14 @@ function showHelp() {
   cdpilot v${VERSION} — Zero-dependency browser automation
 
   USAGE
-    cdpilot <command> [args]
+    cdpilot [--timeout <s>] <command> [args]
+
+  GLOBAL OPTIONS
+    --timeout <s>      Abort the command after <s> seconds (exit 124). Before or
+                       after the command; env CDPILOT_TIMEOUT sets a default
+                       (the flag wins, 0 disables).
+    Page commands start the browser if it is not running
+                       (set CDPILOT_NO_AUTOLAUNCH=1 to get an error instead).
 
   SETUP
     setup              Auto-detect browser, create isolated profile
@@ -332,7 +339,7 @@ function showHelp() {
                        if no user tabs remain (--force quits anyway, --keep never quits)
 
   NAVIGATION
-    go <url>           Navigate to URL
+    go <url>           Navigate to URL (alias: open)
     content            Get page text content
     html               Get page HTML
     shot [file]        Take screenshot
@@ -590,8 +597,23 @@ if (process.argv.includes('--internal-test-runner')) {
   return; // runAll() is async, this exits via process.exit
 }
 
+// Global flags may precede the command name (`cdpilot --timeout 10 click "#x"`).
+// src/cdpilot.py parses and validates them (it is also run directly, without
+// this launcher); here they only have to be skipped to find the command that
+// the launcher answers itself (help / --version / setup / status). args are
+// passed to Python unchanged.
+function commandIndex(argv) {
+  let i = 0;
+  while (i < argv.length) {
+    if (argv[i] === '--timeout') { i += 2; continue; }
+    if (argv[i].startsWith('--timeout=')) { i += 1; continue; }
+    break;
+  }
+  return i;
+}
+
 const args = process.argv.slice(2);
-const cmd = args[0];
+const cmd = args[commandIndex(args)];
 
 if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showHelp();
@@ -620,7 +642,7 @@ if (cmd === 'status') {
   // Delegate to Python
   const python = findPython();
   if (!python) {
-    console.error('Error: Python 3.8+ required. Install: https://www.python.org/downloads/');
+    console.error('Error: Python 3.10+ required. Install: https://www.python.org/downloads/');
     process.exit(1);
   }
 
@@ -650,7 +672,14 @@ if (cmd === 'status') {
     env,
   });
 
-  child.on('close', (code) => {
-    process.exit(code || 0);
+  // A child killed by a signal reports code === null. `code || 0` turned that
+  // into success, so an OOM-killed or SIGKILLed run looked fine to scripts
+  // and agents. Use the shell convention 128 + signal number instead.
+  child.on('close', (code, signal) => {
+    if (code === null && signal) {
+      console.error(`cdpilot: python was terminated by ${signal}`);
+      process.exit(128 + (os.constants.signals[signal] || 0));
+    }
+    process.exit(code ?? 0);
   });
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "cdpilot",
-  "version": "0.9.0",
+  "version": "0.9.2",
+  "mcpName": "io.github.mehmetnadir/cdpilot",
   "description": "Zero-dependency browser automation CLI. Raw CDP, 70+ commands, friction ladder, 3-tier stealth, CAPTCHA + press-and-hold solvers, proxy pools, MCP server. No Puppeteer/Playwright/Selenium.",
   "bin": {
     "cdpilot": "./bin/cdpilot.js",
@@ -48,15 +49,18 @@
     "shadow-dom",
     "perimeterx",
     "press-and-hold",
-    "progressive-resilience",
-    "multi-instance"
+    "progressive-resilience"
   ],
   "author": "Mehmet Nadir",
   "license": "MIT",
+  "homepage": "https://cdpilot.ndr.ist",
   "repository": {
     "type": "git",
     "url": "https://github.com/mehmetnadir/cdpilot"
   },
+  "bugs": {
+    "url": "https://github.com/mehmetnadir/cdpilot/issues"
+  },
   "engines": {
     "node": ">=18.0.0"
   },