cdpilot 0.9.2 → 0.9.3

package/README.md

@@ -144,6 +144,76 @@ cdpilot scroll-to <selector>  # Scroll element into view
 cdpilot drag <from> <to>      # Drag and drop
 ```
 
+### Element targeting inside iframes
+
+Card forms (Stripe/iyzico-style), embedded login widgets and the reCAPTCHA
+checkbox live inside `<iframe>`s. Name the frame chain before the element
+selector with `>>>`, or pass `--frame`:
+
+```bash
+# Payment-style page: the card fields are inside <iframe id="card" title="Secure card payment">
+cdpilot fill  "iframe#card >>> input[name=cardnumber]" "4242424242424242"
+cdpilot type  --frame "#card" "input[name=cvc]" "123"
+cdpilot click "iframe[title='Secure card payment'] >>> button#pay-btn"
+
+# Nested frames: outermost first
+cdpilot click "iframe.checkout >>> iframe.card >>> button"
+
+# --frame <selector|index|url-substring>, nestable with >>>
+cdpilot click --frame 0 "button.submit"                   # first iframe (same order as `frame list`)
+cdpilot fill  --frame "url=js.stripe.com" "input[name=cardnumber]" "4242424242424242"
+cdpilot frame list --frame "#card"                        # iframes inside that frame
+cdpilot frame eval --frame "#card" "document.title"       # runs in the frame's own page context
+```
+
+- Works for `click`, `fill`, `type`, `submit`, `hover`, `dblclick`, `rightclick`,
+  `smart-click`, `smart-fill`, `smart-select` and `frame list|eval|shadow`.
+- A frame hop is a CSS selector, a 0-based index, a `name`/`id`, or
+  `url=<src substring>`. `--frame` also takes a bare `src` substring.
+  `>>>` inside quotes or `[...]` is literal. A selector that matches an
+  element *wrapping* an iframe (Stripe's `#card-element`) enters the iframe
+  inside it and says so on stderr:
+  `note: '#card-element' is not an iframe; using the iframe inside it`.
+- Selectors and texts that already contain `>>>` keep working: when the part
+  before the first `>>>` finds no iframe in the page, or a segment is empty
+  (`click "Next >>>"`), the whole string is used as written, exactly as
+  before. If that fails too, one stderr line explains:
+  `note: 'Home' matched no iframe; used the selector as written`.
+  `--frame` never falls back: a frame it cannot find is an error (exit 1).
+- For `smart-click` / `smart-fill` / `smart-select` the part before the first
+  `>>>` is a frame only if it looks like a selector (it has `#`, `.` or `[`,
+  or starts with an `iframe`/`frame` tag) or is `url=…`; words stay text.
+  `smart-click "Main >>> Settings"` clicks the page's "Main >>> Settings"
+  link even when a `<main>` element holds an iframe. For a frame index or a
+  bare name use `--frame`.
+- Same-origin **and cross-origin** frames work, including out-of-process
+  iframes (site isolation): cdpilot resolves each hop over CDP
+  (`DOM.describeNode` → frame id → the frame's execution context, or
+  `Target.attachToTarget` with a flat session for an out-of-process frame),
+  never through `contentDocument`, which the browser blocks cross-origin.
+- Real mouse input (`hover`, `dblclick`, `rightclick`, `--entropy=on` clicks)
+  is dispatched at page coordinates: the frame's offset in the page is added
+  automatically, so the browser hit-tests into the right frame.
+- `smart-click` / `smart-fill` / `smart-select` look in the page first and
+  compare texts with whitespace collapsed (`&nbsp;` and line breaks count as
+  one space). An enabled page element whose text or label contains the whole
+  query is used. If the page's only such elements are disabled, the command
+  fails as before (`no enabled element matches …`) without looking in frames.
+  Otherwise the visible frames are searched breadth-first for a whole-query
+  match (at most 20 frames, and 2 s for all of the search's CDP calls) and the
+  match is reported on stderr:
+  `smart-click: matched inside frame iframe#card (https://…)`. The search only
+  looks (no click, no typing); the command then acts once, in the chosen
+  frame. With no frame match, the page's partial (word) match is used as
+  before. When the 2 s run out:
+  `smart-click: frame search stopped after 2s (3 of 7 frames)`; a frame that
+  had not answered by then has not been touched.
+- `smart-fill` and `smart-select` search automatically only frames of the
+  page's own origin, so a typed value never lands in a third-party frame (an
+  ad, chat or payment widget) by accident; reach a cross-origin frame with
+  `>>>` or `--frame`. `smart-click` searches all visible frames.
+- `frame list` without `--frame` prints the same list as before.
+
 ### Debugging
 
 ```bash
@@ -308,7 +378,8 @@ cdpilot storage               # localStorage contents
 cdpilot upload <sel> <file>   # Upload file to input
 cdpilot multi-eval <js>       # Execute JS in all tabs
 cdpilot headless [on|off]     # Toggle headless mode
-cdpilot frame list            # List iframes
+cdpilot frame list            # List iframes (index = --frame <index>)
+cdpilot frame eval --frame <f> <js>  # Run JS inside an iframe (cross-origin too)
 cdpilot dialog auto-accept    # Auto-accept dialogs
 cdpilot permission grant geo  # Grant geolocation
 ```
@@ -562,7 +633,7 @@ Earlier figures on this page (sannysoft 24/24, intoli 6/6) were measured on v0.4
 
 ```bash
 cdpilot browser [name|auto]   # workload-aware browser selection
-cdpilot health                # JSON: alive, port, tabs, browser, today's crashes
+cdpilot health                # JSON: alive, port, tabs, browser, today's crashes, idle close
 ```
 
 `cdpilot health` is designed for shell watchdogs:
@@ -584,6 +655,33 @@ Lifecycle, status and configuration commands (`launch`, `stop`, `close`,
 `mcp`, `serve`, …) never launch. `CDPILOT_NO_AUTOLAUNCH=1` restores the old
 "CDP connection error. Is the browser running?" error and exit code 1.
 
+**Idle auto-close.** A browser that a page command auto-launched, or that the
+MCP server launched (`browser_launch` included), closes itself after
+**15 minutes** without a cdpilot command or a visible page change, so a
+finished agent task does not leave it holding memory. An explicit CLI
+`cdpilot launch` stays open (you may be browsing in it by hand) unless you ask:
+`cdpilot launch --idle-close 30` or `CDPILOT_IDLE_CLOSE=30`. The env var also
+sets the auto-launch delay (read when the browser starts; fractions allowed);
+`0` turns idle close off. A browser you started yourself, or one cdpilot merely
+attached to, is never closed.
+
+What counts as use: any cdpilot command except the read-only checks (`status`,
+`health`, `projects`, `version` — a `cdpilot health` watchdog loop does not keep
+the browser alive), MCP tool calls, `serve` requests, a CDP client still
+attached to a page (a long-running command, `watch`, Playwright via
+`connectOverCDP`), and any change in the open pages' URLs or in the set of
+tabs (someone navigating, a tab opened or closed). Title changes do not count,
+so a page that rewrites its own title (a clock, an unread counter) cannot keep
+the browser alive. `cdpilot status` and
+`cdpilot health` show `idle close in 12m` or `idle close off`.
+
+How: every command stamps `~/.cdpilot/projects/<id>/last-activity`; the launch
+starts a small detached watcher (one per port, no console window on Windows)
+that checks every ≤30 s, stops the browser like `cdpilot stop`, marks it
+stopped in the registry and exits — it also exits as soon as the browser is
+gone for any other reason. Browsers started by `serve --api` are managed by the
+server and have no idle close.
+
 **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
@@ -600,6 +698,36 @@ CDPILOT_TIMEOUT=60 cdpilot run flow.cdp   # default for every command (and each
 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.
 
+### Session log
+
+Every command (and every MCP tool call) appends one JSON line to a local,
+per-project log, so when a browser task is done there is a record of what was
+done and found. Nothing leaves the machine.
+
+```bash
+cdpilot log                 # today's commands: time, exit, command, url, result
+cdpilot log --md            # Markdown report: pages visited, actions, errors, files produced
+cdpilot log --json          # raw lines (one JSON object per command)
+cdpilot log --days 3        # include the last 3 days
+cdpilot log --path          # where the files are
+```
+
+Each line has `ts`, `cmd`, `args`, `exit`, `duration_ms`, the page `url` and
+`title` after the command (when the command already had them), a ~200-char
+`summary` of its output, the `error` line, and `files` it wrote (screenshots,
+PDFs). Files live in `~/.cdpilot/projects/<project-id>/log/<YYYY-MM-DD>.jsonl`.
+
+Redaction happens before anything is written: values given to `fill`, `type`,
+`smart-fill`, `smart-select`, `assert-value` and `dialog prompt` become
+`«redacted:N chars»`; so do values of password/token/key/secret/cookie/auth
+flags and headers, token-shaped arguments, and URL query/fragment values whose
+names contain token, key, secret, password, auth, code or session. `cookies`
+and `storage` output is never logged; `eval` source is, with string literals
+over 40 chars cut and secret-looking ones replaced. Logging is best effort: it
+never changes a command's output or exit code, and a failed write costs one
+stderr line. `CDPILOT_LOG=0` turns it off; `CDPILOT_LOG_DAYS` (default 14)
+sets how many days are kept. The MCP server exposes it as `browser_log`.
+
 ### Scaling & Workstation Use
 
 ```bash
@@ -663,6 +791,9 @@ print(result.stdout)
 | `CDPILOT_OFFSCREEN` | `0` | Headed but render off-screen — no window steals focus |
 | `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 |
+| `CDPILOT_IDLE_CLOSE` | `15` | Minutes without a cdpilot command or page change before a browser cdpilot launched closes itself (fractions allowed, `0` = never; read at launch). Default applies to auto-launch and MCP launches; an explicit CLI `launch` is off unless this is set or `--idle-close <min>` is given |
+| `CDPILOT_LOG` | `1` | `0` = do not write the session log (`cdpilot log`) |
+| `CDPILOT_LOG_DAYS` | `14` | Days of session log to keep; older day files are deleted on the first write of a day (`0` keeps all) |
 
 ## How It Works
 
@@ -823,10 +954,10 @@ The only browser MCP with built-in test assertions. Here's what we've shipped an
 - [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
+- [x] **iframe targeting** — `"iframe#card >>> input"` / `--frame` for element commands, same-origin and cross-origin (out-of-process) frames; smart commands search frames automatically
 
 ### 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

package/bin/cdpilot.js

@@ -242,7 +242,8 @@ function runStatus() {
           console.log(`  ✓ Connected`);
           console.log(`  Browser: ${info.Browser || 'Unknown'}`);
           console.log(`  Protocol: ${info['Protocol-Version'] || 'Unknown'}`);
-          console.log(`  WebSocket: ${info.webSocketDebuggerUrl || 'N/A'}\n`);
+          console.log(`  WebSocket: ${info.webSocketDebuggerUrl || 'N/A'}`);
+          console.log(`  ${idleCloseLabel(port)}\n`);
         } catch {
           console.log('  ✓ CDP responding but version info unavailable\n');
         }
@@ -262,6 +263,33 @@ function runStatus() {
   }
 }
 
+// Idle auto-close countdown, from the files src/cdpilot.py keeps (see
+// _idle_status there): CDPILOT_HOME/idle/<port>.json names the watcher and its
+// minutes, CDPILOT_HOME/projects/<id>/last-activity the last command.
+function idleCloseLabel(port) {
+  const home = process.env.CDPILOT_HOME || path.join(os.homedir(), '.cdpilot');
+  try {
+    const st = JSON.parse(fs.readFileSync(path.join(home, 'idle', `${port}.json`), 'utf-8'));
+    const minutes = Number(st.minutes) || 0;
+    if (minutes <= 0 || !st.pid) return 'idle close off';
+    try {
+      process.kill(st.pid, 0); // existence probe; safe on Windows in Node
+    } catch (e) {
+      if (e.code !== 'EPERM') return 'idle close off';
+    }
+    let last = Number(st.started) || Date.now() / 1000;
+    try {
+      const file = path.join(home, 'projects', String(st.project_id), 'last-activity');
+      const t = parseFloat(fs.readFileSync(file, 'utf-8'));
+      if (t > last) last = t;
+    } catch {}
+    const left = Math.max(0, Math.floor(minutes * 60 - (Date.now() / 1000 - last)));
+    return `idle close in ${Math.ceil(left / 60)}m`;
+  } catch {
+    return 'idle close off';
+  }
+}
+
 // ── Version ──
 
 function showVersion() {
@@ -329,10 +357,14 @@ function showHelp() {
                        (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).
+    An auto-launched (or MCP-launched) browser closes after 15 min without a
+                       cdpilot command or page change (CDPILOT_IDLE_CLOSE=<minutes>,
+                       0 = never); an explicit launch stays open unless asked (below).
 
   SETUP
     setup              Auto-detect browser, create isolated profile
-    launch             Start browser with CDP enabled
+    launch [--idle-close <min>]  Start browser with CDP enabled (--idle-close or
+                       CDPILOT_IDLE_CLOSE: close it after <min> idle minutes)
     status             Check browser connection
     stop [--smart]     Stop browser (--smart = close owned tabs, quit if empty)
     close [--force|--keep]  Smart close: close cdpilot's tabs; quit browser only
@@ -352,6 +384,14 @@ function showHelp() {
     submit <form>      Submit form
     hover <sel>        Hover element
     keys <combo>       Keyboard shortcut
+    Inside an iframe:  click "iframe#card >>> input[name=cardnumber]"
+                       (nest: "iframe.a >>> iframe.b >>> button") or
+                       --frame <selector|index|url-substring>; same-origin and
+                       cross-origin frames. With no match in the page,
+                       smart-click searches all frames, smart-fill and
+                       smart-select only frames of the page's origin.
+    frame list|eval [--frame <f>]
+                       List iframes / run JS inside a frame
 
   DEBUGGING
     console [url]      Capture console logs
@@ -430,6 +470,16 @@ function showHelp() {
   AI AGENT
     mcp                Start MCP server (stdin/stdout JSON-RPC)
 
+  SESSION LOG (always on, local, redacted)
+    log                Today's commands for this project: time, exit, command,
+                       url, result
+    log --md           Markdown report (pages visited, actions, errors, files
+                       produced) to paste into an issue or PR
+    log --json         Raw JSON lines · log --days N · log --path (log directory)
+                       Typed values, secret-looking args and token/key/secret URL
+                       params are redacted. CDPILOT_LOG=0 turns it off;
+                       CDPILOT_LOG_DAYS (default 14) sets how many days are kept.
+
   WATCH (continuous screencast for AI video understanding)
     watch start <url>  Begin JPEG screencast at N fps to a disk ring buffer
                        (default 10fps, 5min retention, 100MB cap). Background

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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": {