@jackwener/opencli 1.5.2 → 1.5.4

package/.agents/skills/cross-project-adapter-migration/SKILL.md

@@ -16,8 +16,8 @@ description: "Cross-project CLI command migration workflow for opencli. Use when
 
 ## Prerequisites
 
-- 熟悉 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md)（adapter 开发决策树）
-- 熟悉 [SKILL.md](file:///Users/jakevin/code/opencli/SKILL.md)（命令参考 & 模板）
+- 熟悉 [CLI-EXPLORER.md](../../../CLI-EXPLORER.md)（adapter 开发决策树）
+- 熟悉 [SKILL.md](../../../SKILL.md)（命令参考 & 模板）
 
 ---
 
@@ -82,7 +82,7 @@ opencli list | grep <site>  # 确认已注册命令
 ## Phase 3: 批量实现
 
 > [!IMPORTANT]
-> 实现前必须查阅 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md) 确认策略选择。
+> 实现前必须查阅 [CLI-EXPLORER.md](../../../CLI-EXPLORER.md) 确认策略选择。
 
 ### 3.1 选择实现方式
 

package/.github/workflows/ci.yml

@@ -39,13 +39,15 @@ jobs:
         run: npm run build
 
   # ── Unit tests (vitest shard) ──
+  # PR: ubuntu + Node 22 only (fast feedback, 2 jobs).
+  # Push to main/dev: full matrix for cross-platform/cross-version coverage (12 jobs).
   unit-test:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
-        node-version: ['20', '22']
+        os: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && fromJSON('["ubuntu-latest","macos-latest","windows-latest"]') || fromJSON('["ubuntu-latest"]') }}
+        node-version: ${{ (github.event_name == 'push' || github.event_name == 'schedule' || github.event_name == 'workflow_dispatch') && fromJSON('["20","22"]') || fromJSON('["22"]') }}
         shard: [1, 2]
     steps:
       - uses: actions/checkout@v6
@@ -82,12 +84,9 @@ jobs:
       - name: Run unit tests under Bun
         run: bun vitest run --project unit --reporter=verbose
 
+  # Adapter tests are pure unit tests — OS doesn't affect results.
   adapter-test:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ubuntu-latest
     needs: build
     steps:
       - uses: actions/checkout@v6

package/README.md

@@ -1,6 +1,6 @@
 # OpenCLI
 
-> **Make any website, Electron App, or Local Tool your CLI.**  
+> **Make any website, Electron App, or Local Tool your CLI.**
 > Zero risk · Reuse Chrome login · AI-powered discovery · Universal CLI Hub
 
 [![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-0F766E?style=flat-square)](./README.zh-CN.md)
@@ -10,17 +10,19 @@
 
 A CLI tool that turns **any website**, **Electron app**, or **local CLI tool** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, `gh`, `docker`, and [many more](#built-in-commands) — powered by browser session reuse and AI-native discovery.
 
-**Built for AI Agents**: Simply configure an instruction in your global `AGENT.md` or `.cursorrules` guiding the AI to execute `opencli list` via Bash to discover available tools. Register your favorite local CLIs (`opencli register mycli`), and the AI will automatically learn how to invoke all your tools perfectly!
+**Built for AI Agents** — Configure an instruction in your `AGENT.md` or `.cursorrules` to run `opencli list` via Bash. The AI will automatically discover and invoke all available tools.
 
-**CLI All Electron Apps! The Most Powerful Update Has Arrived!**
-Turn ANY Electron application into a CLI tool! Recombine, script, and extend applications like Antigravity Ultra seamlessly. Now AI can control itself natively. Unlimited possibilities await!
+**CLI Hub** — Register any local CLI (`opencli register mycli`) so AI agents can discover and call it alongside built-in commands. Auto-installs missing tools via your package manager (e.g. if `gh` isn't installed, `opencli gh ...` runs `brew install gh` first then re-executes seamlessly).
+
+**CLI for Electron Apps** — Turn any Electron application into a CLI tool. Recombine, script, and extend apps like Antigravity Ultra from the terminal. AI agents can now control other AI apps natively.
 
 ---
 
 ## Highlights
 
-- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively using cc/openclaw!
+- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively.
 - **Account-safe** — Reuses Chrome's logged-in state; your credentials never leave the browser.
+- **Anti-detection built-in** — Patches `navigator.webdriver`, stubs `window.chrome`, fakes plugin lists, cleans ChromeDriver/Playwright globals, and strips CDP frames from Error stack traces. Extensive anti-fingerprinting and risk-control evasion measures baked in at every layer.
 - **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies.
 - **External CLI Hub** — Discover, auto-install, and passthrough commands to any external CLI (gh, obsidian, docker, etc). Zero setup.
 - **Self-healing setup** — `opencli doctor` diagnoses and auto-starts the daemon, extension, and live browser connectivity.
@@ -47,83 +49,38 @@ There are many great browser automation tools. Here's when opencli is the right
 
 > For a detailed comparison with Browser-Use, Crawl4AI, Firecrawl, and others, see the [Comparison Guide](./docs/comparison.md).
 
-## Prerequisites
-
-- **Node.js**: >= 20.0.0 (or **Bun** >= 1.0 — see [Runtime Support](#runtime-support) below)
-- **Chrome** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com).
-
-> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands. If you get empty data or errors, check your login status first.
-
-### Runtime Support
-
-OpenCLI works with both **Node.js** (≥ 20) and **Bun** (≥ 1.0). All commands and adapters are runtime-agnostic.
-
-```bash
-# Development with Bun (faster startup)
-npm run dev:bun
-
-# Run the built CLI with Bun
-npm run start:bun
-
-# Run unit tests under Bun
-npm run test:bun
-
-# Run E2E tests with Bun as the runtime
-OPENCLI_TEST_RUNTIME=bun npm run test:e2e
-```
-
-Use `opencli doctor` to check your current runtime — it displays the active engine (e.g. `node v22.13.0` or `bun 1.1.42`).
+---
 
-OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
+## Quick Start
 
-### Browser Bridge Extension Setup
+### 1. Install Browser Bridge Extension
 
-You can install the extension via either method:
+> OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
 
-**Method 1: Download Pre-built Release (Recommended)**
 1. Go to the GitHub [Releases page](https://github.com/jackwener/opencli/releases) and download the latest `opencli-extension.zip`.
 2. Unzip the file and open `chrome://extensions`, enable **Developer mode** (top-right toggle).
 3. Click **Load unpacked** and select the unzipped folder.
 
-**Method 2: Load Source (For Developers)**
-1. Open `chrome://extensions` and enable **Developer mode**.
-2. Click **Load unpacked** and select the `extension/` directory from this repository.
-
-That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.
-
-> **Tip**: Use `opencli doctor` for ongoing diagnosis:
-> ```bash
-> opencli doctor            # Check extension + daemon connectivity
-> ```
+### 2. Install OpenCLI
 
-## Quick Start
-
-### Install via npm (recommended)
+**Install via npm (recommended)**
 
 ```bash
 npm install -g @jackwener/opencli
 ```
 
-Then use directly:
+### 3. Verify & Try
 
 ```bash
-opencli list                              # See all commands
-opencli list -f yaml                      # List commands as YAML
-opencli hackernews top --limit 5          # Public API, no browser
-opencli bilibili hot --limit 5            # Browser command
-opencli zhihu hot -f json                 # JSON output
-opencli zhihu hot -f yaml                 # YAML output
+opencli doctor   # Check extension + daemon connectivity
 ```
 
-### Install from source (for developers)
+**Try it out:**
 
 ```bash
-git clone git@github.com:jackwener/opencli.git
-cd opencli 
-npm install
-npm run build
-npm link      # Link binary globally
-opencli list  # Now you can use it anywhere!
+opencli list                           # See all commands
+opencli hackernews top --limit 5       # Public API, no browser needed
+opencli bilibili hot --limit 5         # Browser command (requires Extension)
 ```
 
 ### Update
@@ -132,104 +89,63 @@ opencli list  # Now you can use it anywhere!
 npm install -g @jackwener/opencli@latest
 ```
 
+---
+
+### For Developers
+
+**Install from source**
+
+```bash
+git clone git@github.com:jackwener/opencli.git && cd opencli && npm install && npm run build && npm link
+```
+
+**Load Source Browser Bridge Extension**
+
+1. Open `chrome://extensions` and enable **Developer mode** (top-right toggle).
+2. Click **Load unpacked** and select the `extension/` directory from this repository.
+
+---
+
+## Prerequisites
+
+- **Node.js**: >= 20.0.0 (or **Bun** >= 1.0)
+- **Chrome** running **and logged into the target site** (e.g. bilibili.com, zhihu.com, xiaohongshu.com).
+
+> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands. If you get empty data or errors, check your login status first.
+
 ## Built-in Commands
 
-Run `opencli list` for the live registry.
-
-| Site | Commands | Mode |
-|------|----------|------|
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` `accept` `reply-dm` `block` `unblock` `hide-reply` | Browser |
-| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | Browser |
-| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` `ask` `screenshot` `history` `export` | Desktop |
-| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` `download` | Browser |
-| **codex** | `status` `send` `read` `new` `dump` `extract-diff` `model` `ask` `screenshot` `history` `export` | Desktop |
-| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | Desktop |
-| **doubao** | `status` `new` `send` `read` `ask` | Browser |
-| **doubao-app** | `status` `new` `send` `read` `ask` `screenshot` `dump` | Desktop |
-| **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | Desktop |
-| **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | Desktop |
-| **v2ex** | `hot` `latest` `topic` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | Public / Browser |
-| **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` `fund-holdings` `fund-snapshot` | Browser |
-| **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | Desktop |
-| **chatgpt** | `status` `new` `send` `read` `ask` `model` | Desktop |
-| **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | Browser |
-| **apple-podcasts** | `search` `episodes` `top` | Public |
-| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | Public |
-| **zhihu** | `hot` `search` `question` `download` | Browser |
-| **weixin** | `download` | Browser |
-| **youtube** | `search` `video` `transcript` | Browser |
-| **boss** | `search` `detail` `recommend` `joblist` `greet` `batchgreet` `send` `chatlist` `chatmsg` `invite` `mark` `exchange` `resume` `stats` | Browser |
-| **coupang** | `search` `add-to-cart` | Browser |
-| **bbc** | `news` | Public |
-| **bloomberg** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | Public / Browser |
-| **ctrip** | `search` | Browser |
-| **devto** | `top` `tag` `user` | Public |
-| **dictionary** | `search` `synonyms` `examples` | Public |
-| **arxiv** | `search` `paper` | Public |
-| **paperreview** | `submit` `review` `feedback` | Public |
-| **wikipedia** | `search` `summary` `random` `trending` | Public |
-| **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | Public |
-| **jd** | `item` | Browser |
-| **linkedin** | `search` `timeline` | Browser |
-| **reuters** | `search` | Browser |
-| **smzdm** | `search` | Browser |
-| **web** | `read` | Browser |
-| **weibo** | `hot` `search` | Browser |
-| **yahoo-finance** | `quote` | Browser |
-| **sinafinance** | `news` | 🌐 Public |
-| **barchart** | `quote` `options` `greeks` `flow` | Browser |
-| **chaoxing** | `assignments` `exams` | Browser |
-| **grok** | `ask` | Browser |
-| **hf** | `top` | Public |
-| **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | Browser |
-| **jimeng** | `generate` `history` | Browser |
-| **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | Browser |
-| **linux-do** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | Browser |
-| **stackoverflow** | `hot` `search` `bounties` `unanswered` | Public |
-| **steam** | `top-sellers` | Public |
-| **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | Browser |
-| **douban** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | Browser |
-| **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | Browser |
-| **google** | `news` `search` `suggest` `trends` | Public |
-| **36kr** | `news` `hot` `search` `article` | Public / Browser |
-| **imdb** | `search` `title` `top` `trending` `person` `reviews` | Public |
-| **producthunt** | `posts` `today` `hot` `browse` | Public / Browser |
-| **instagram** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | Browser |
-| **lobsters** | `hot` `newest` `active` `tag` | Public |
-| **medium** | `feed` `search` `user` | Browser |
-| **sinablog** | `hot` `search` `article` `user` | Browser |
-| **substack** | `feed` `search` `publication` | Browser |
-| **pixiv** | `ranking` `search` `user` `illusts` `detail` `download` | Browser |
-| **tiktok** | `explore` `search` `profile` `user` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `live` `notifications` `friends` | Browser |
-
-
-### External CLI Hub
-
-OpenCLI acts as a universal hub for your existing command-line tools. It provides unified discovery, automatic installation, and pure passthrough execution.
-
-| External CLI | Description | Commands Example |
-|--------------|-------------|------------------|
+| Site | Commands |
+|------|----------|
+| **xiaohongshu** | `search` `feed` `user` `download` `publish` `comments` `notifications` `creator-notes` `creator-notes-summary` `creator-note-detail` `creator-profile` `creator-stats` |
+| **bilibili** | `hot` `search` `history` `feed` `ranking` `download` `comments` `dynamic` `favorite` `following` `me` `subtitle` `user-videos` |
+| **twitter** | `trending` `search` `timeline` `bookmarks` `post` `download` `profile` `article` `like` `likes` `notifications` `reply` `reply-dm` `thread` `follow` `unfollow` `followers` `following` `block` `unblock` `bookmark` `unbookmark` `delete` `hide-reply` `accept` |
+| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `user` `user-posts` `user-comments` `read` `save` `saved` `subscribe` `upvote` `upvoted` `comment` |
+
+65+ adapters in total — **[→ see all supported sites & commands](./docs/adapters/index.md)**
+
+## CLI Hub
+
+OpenCLI acts as a universal hub for your existing command-line tools — unified discovery, pure passthrough execution, and auto-install (if a tool isn't installed, OpenCLI runs `brew install <tool>` automatically before re-running the command).
+
+| External CLI | Description | Example |
+|--------------|-------------|---------|
 | **gh** | GitHub CLI | `opencli gh pr list --limit 5` |
 | **obsidian** | Obsidian vault management | `opencli obsidian search query="AI"` |
-| **docker** | Docker command-line interface | `opencli docker ps` |
-| **readwise** | Readwise & Reader CLI | `opencli readwise login` |
-| **gws** | Google Workspace CLI — Docs, Sheets, Drive, Gmail, Calendar | `opencli gws docs list` |
-
-**Zero Configuration**: OpenCLI purely passes your inputs to the underlying binary via standard I/O streams. The external CLI works exactly as it naturally would, maintaining its standard output formats.
+| **docker** | Docker | `opencli docker ps` |
+| **gws** | Google Workspace CLI | `opencli gws docs list` |
+| **lark-cli** | Lark/Feishu — messages, docs, calendar, tasks, 200+ commands | `opencli lark-cli calendar +agenda` |
+| **vercel** | Vercel — deploy projects, manage domains, env vars, logs | `opencli vercel deploy --prod` |
 
-**Auto-Installation**: If you run `opencli gh ...` and `gh` is not installed on your system, OpenCLI will automatically try to install it using your system's package manager (e.g., `brew install gh`) before seamlessly re-running the command.
+**Register your own** — add any local CLI so AI agents can discover it via `opencli list`:
 
-**Register Your Own**:
-Add any local CLI to your OpenCLI registry so AI agents can automatically discover it via the `opencli list` command.
 ```bash
 opencli register mycli
 ```
 
 ### Desktop App Adapters
 
-Each desktop adapter has its own detailed documentation with commands reference, setup guide, and examples:
-
-If you want to add support for a new Electron desktop app, start with [docs/guide/electron-app-cli.md](./docs/guide/electron-app-cli.md) and the deeper [Electron guide](./docs/advanced/electron.md).
+Control Electron desktop apps directly from the terminal. Each adapter has its own detailed documentation:
 
 | App | Description | Doc |
 |-----|-------------|-----|
@@ -242,93 +158,51 @@ If you want to add support for a new Electron desktop app, start with [docs/guid
 | **Discord** | Discord Desktop — messages, channels, servers | [Doc](./docs/adapters/desktop/discord.md) |
 | **Doubao** | Control Doubao AI desktop app via CDP | [Doc](./docs/adapters/desktop/doubao-app.md) |
 
+To add a new Electron app, start with [docs/guide/electron-app-cli.md](./docs/guide/electron-app-cli.md).
+
 ## Download Support
 
 OpenCLI supports downloading images, videos, and articles from supported platforms.
 
-### Supported Platforms
-
 | Platform | Content Types | Notes |
 |----------|---------------|-------|
 | **xiaohongshu** | Images, Videos | Downloads all media from a note |
 | **bilibili** | Videos | Requires `yt-dlp` installed |
-| **twitter** | Images, Videos | Downloads from user media tab or single tweet |
-| **douban** | Images | Downloads poster / still image lists from movie subjects |
-| **pixiv** | Images | Downloads original-quality illustrations, supports multi-page works |
-| **zhihu** | Articles (Markdown) | Exports articles with optional image download |
-| **weixin** | Articles (Markdown) | Exports WeChat Official Account articles |
+| **twitter** | Images, Videos | From user media tab or single tweet |
+| **douban** | Images | Poster / still image lists |
+| **pixiv** | Images | Original-quality illustrations, multi-page |
+| **zhihu** | Articles (Markdown) | Exports with optional image download |
+| **weixin** | Articles (Markdown) | WeChat Official Account articles |
 
-### Prerequisites
-
-For video downloads from streaming platforms, you need to install `yt-dlp`:
+For video downloads, install `yt-dlp` first: `brew install yt-dlp`
 
 ```bash
-# Install yt-dlp
-pip install yt-dlp
-# or
-brew install yt-dlp
-```
-
-### Usage Examples
-
-```bash
-# Download images/videos from Xiaohongshu note
 opencli xiaohongshu download abc123 --output ./xhs
-
-# Download Bilibili video (requires yt-dlp)
 opencli bilibili download BV1xxx --output ./bilibili
-opencli bilibili download BV1xxx --quality 1080p  # Specify quality
-
-# Download Twitter media from user
 opencli twitter download elonmusk --limit 20 --output ./twitter
-
-# Download single tweet media
-opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
-
-# Download Douban posters / stills
-opencli douban download 30382501 --output ./douban
-
-# Export Zhihu article to Markdown
-opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
-
-# Export with local images
-opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
-
-# Export WeChat article to Markdown
-opencli weixin download --url "https://mp.weixin.qq.com/s/xxx" --output ./weixin
 ```
 
-
-
 ## Output Formats
 
-All built-in commands support `--format` / `-f` with `table`, `json`, `yaml`, `md`, and `csv`.
-The `list` command supports the same format options, and keeps `--json` for backward compatibility.
+All built-in commands support `--format` / `-f` with `table` (default), `json`, `yaml`, `md`, and `csv`.
 
 ```bash
-opencli list -f yaml            # Command registry as YAML
-opencli bilibili hot -f table   # Default: rich terminal table
-opencli bilibili hot -f json    # JSON (pipe to jq or LLMs)
-opencli bilibili hot -f yaml    # YAML (human-readable structured output)
-opencli bilibili hot -f md      # Markdown
-opencli bilibili hot -f csv     # CSV
+opencli bilibili hot -f json    # Pipe to jq or LLMs
+opencli bilibili hot -f csv     # Spreadsheet-friendly
 opencli bilibili hot -v         # Verbose: show pipeline debug steps
 ```
 
 ## Plugins
 
-Extend OpenCLI with community-contributed adapters. Plugins use the same YAML/TS format as built-in commands and are automatically discovered at startup.
+Extend OpenCLI with community-contributed adapters:
 
 ```bash
-opencli plugin install github:user/opencli-plugin-my-tool  # Install
-opencli plugin list                                         # List installed
-opencli plugin update my-tool                               # Update to latest
-opencli plugin update --all                                 # Update all installed plugins
-opencli plugin uninstall my-tool                            # Remove
+opencli plugin install github:user/opencli-plugin-my-tool
+opencli plugin list
+opencli plugin update --all
+opencli plugin uninstall my-tool
 ```
 
-`opencli plugin list` also shows the tracked short commit hash when a plugin version is recorded in `~/.opencli/plugins.lock.json`.
-
 | Plugin | Type | Description |
 |--------|------|-------------|
 | [opencli-plugin-github-trending](https://github.com/ByteYue/opencli-plugin-github-trending) | YAML | GitHub Trending repositories |
@@ -339,53 +213,33 @@ See [Plugins Guide](./docs/guide/plugins.md) for creating your own plugin.
 
 ## For AI Agents (Developer Guide)
 
-If you are an AI assistant tasked with creating a new command adapter for `opencli`, please follow the AI Agent workflow below:
-
 > **Quick mode**: To generate a single command for a specific page URL, see [CLI-ONESHOT.md](./CLI-ONESHOT.md) — just a URL + one-line goal, 4 steps done.
 
 > **Full mode**: Before writing any adapter code, read [CLI-EXPLORER.md](./CLI-EXPLORER.md). It contains the complete browser exploration workflow, the 5-tier authentication strategy decision tree, and debugging guide.
 
 ```bash
-# 1. Deep Explore — discover APIs, infer capabilities, detect framework
-opencli explore https://example.com --site mysite
-
-# 2. Synthesize — generate YAML adapters from explore artifacts
-opencli synthesize mysite
-
-# 3. Generate — one-shot: explore → synthesize → register
-opencli generate https://example.com --goal "hot"
-
-# 4. Strategy Cascade — auto-probe: PUBLIC → COOKIE → HEADER
-opencli cascade https://api.example.com/data
+opencli explore https://example.com --site mysite   # Discover APIs + capabilities
+opencli synthesize mysite                            # Generate YAML adapters
+opencli generate https://example.com --goal "hot"   # One-shot: explore → synthesize → register
+opencli cascade https://api.example.com/data         # Auto-probe: PUBLIC → COOKIE → HEADER
 ```
 
-Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, capabilities.json, auth.json).
-
 ## Testing
 
 See **[TESTING.md](./TESTING.md)** for how to run and write tests.
 
 ## Troubleshooting
 
-- **"Extension not connected"**
-  - Ensure the opencli Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
-- **"attach failed: Cannot access a chrome-extension:// URL"**
-  - Another Chrome extension (e.g. youmind, New Tab Override, or AI assistant extensions) may be interfering. Try **disabling other extensions** temporarily, then retry.
-- **Empty data returns or 'Unauthorized' error**
-  - Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page.
-- **Node API errors**
-  - Make sure you are using Node.js >= 20. Some dependencies require modern Node APIs.
-- **Daemon issues**
-  - Check daemon status: `curl localhost:19825/status`
-  - View extension logs: `curl localhost:19825/logs`
-
+- **"Extension not connected"** — Ensure the Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
+- **"attach failed: Cannot access a chrome-extension:// URL"** — Another extension may be interfering. Try disabling other extensions temporarily.
+- **Empty data or 'Unauthorized' error** — Your Chrome login session may have expired. Navigate to the target site and log in again.
+- **Node API errors** — Ensure Node.js >= 20. Some dependencies require modern Node APIs.
+- **Daemon issues** — Check status: `curl localhost:19825/status` · View logs: `curl localhost:19825/logs`
 
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=jackwener/opencli&type=Date)](https://star-history.com/#jackwener/opencli&Date)
 
-
-
 ## License
 
 [Apache-2.0](./LICENSE)

package/dist/browser/cdp.js

@@ -13,7 +13,7 @@ import { request as httpsRequest } from 'node:https';
 import { wrapForEval } from './utils.js';
 import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
 import { generateStealthJs } from './stealth.js';
-import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, waitForCaptureJs, waitForSelectorJs, } from './dom-helpers.js';
 import { isRecord, saveBase64ToFile } from '../utils.js';
 const CDP_SEND_TIMEOUT = 30_000;
 export class CDPBridge {
@@ -201,6 +201,16 @@ class CDPPage {
     }
     async wait(options) {
         if (typeof options === 'number') {
+            if (options >= 1) {
+                try {
+                    const maxMs = options * 1000;
+                    await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+                    return;
+                }
+                catch {
+                    // Fallback: fixed sleep
+                }
+            }
             await new Promise((resolve) => setTimeout(resolve, options * 1000));
             return;
         }
@@ -209,6 +219,11 @@ class CDPPage {
             await new Promise((resolve) => setTimeout(resolve, waitTime * 1000));
             return;
         }
+        if (options.selector) {
+            const timeout = (options.timeout ?? 10) * 1000;
+            await this.evaluate(waitForSelectorJs(options.selector, timeout));
+            return;
+        }
         if (options.text) {
             const timeout = (options.timeout ?? 30) * 1000;
             await this.evaluate(waitForTextJs(options.text, timeout));
@@ -268,6 +283,10 @@ class CDPPage {
         const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
         return Array.isArray(result) ? result : [];
     }
+    async waitForCapture(timeout = 10) {
+        const maxMs = timeout * 1000;
+        await this.evaluate(waitForCaptureJs(maxMs));
+    }
 }
 function isCookie(value) {
     return isRecord(value)

package/dist/browser/daemon-client.js

@@ -4,6 +4,7 @@
  * Provides a typed send() function that posts a Command and returns a Result.
  */
 import { DEFAULT_DAEMON_PORT } from '../constants.js';
+import { sleep } from '../utils.js';
 const DAEMON_PORT = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
 const DAEMON_URL = `http://127.0.0.1:${DAEMON_PORT}`;
 let _idCounter = 0;
@@ -80,7 +81,7 @@ export async function sendCommand(action, params = {}) {
                     || errMsg.includes('no longer exists');
                 if (isTransient && attempt < maxRetries) {
                     // Longer delay for extension recovery (service worker restart)
-                    await new Promise(r => setTimeout(r, 1500));
+                    await sleep(1500);
                     continue;
                 }
                 throw new Error(result.error ?? 'Daemon command failed');
@@ -91,7 +92,7 @@ export async function sendCommand(action, params = {}) {
             const isRetryable = err instanceof TypeError // fetch network error
                 || (err instanceof Error && err.name === 'AbortError');
             if (isRetryable && attempt < maxRetries) {
-                await new Promise(r => setTimeout(r, 500));
+                await sleep(500);
                 continue;
             }
             throw err;

package/dist/browser/dom-helpers.d.ts

@@ -26,3 +26,14 @@ export declare function networkRequestsJs(includeStatic: boolean): string;
  * If document.body is not available, falls back to a fixed sleep of maxMs.
  */
 export declare function waitForDomStableJs(maxMs: number, quietMs: number): string;
+/**
+ * Generate JS to wait until window.__opencli_xhr has ≥1 captured response.
+ * Polls every 100ms. Resolves 'captured' on success; rejects after maxMs.
+ * Used after installInterceptor() + goto() instead of a fixed sleep.
+ */
+export declare function waitForCaptureJs(maxMs: number): string;
+/**
+ * Generate JS to wait until document.querySelector(selector) returns a match.
+ * Uses MutationObserver for near-instant resolution; falls back to reject after timeoutMs.
+ */
+export declare function waitForSelectorJs(selector: string, timeoutMs: number): string;

package/dist/browser/dom-helpers.js

@@ -171,3 +171,45 @@ export function waitForDomStableJs(maxMs, quietMs) {
     })
   `;
 }
+/**
+ * Generate JS to wait until window.__opencli_xhr has ≥1 captured response.
+ * Polls every 100ms. Resolves 'captured' on success; rejects after maxMs.
+ * Used after installInterceptor() + goto() instead of a fixed sleep.
+ */
+export function waitForCaptureJs(maxMs) {
+    return `
+    new Promise((resolve, reject) => {
+      const deadline = Date.now() + ${maxMs};
+      const check = () => {
+        if ((window.__opencli_xhr || []).length > 0) return resolve('captured');
+        if (Date.now() > deadline) return reject(new Error('No network capture within ${maxMs / 1000}s'));
+        setTimeout(check, 100);
+      };
+      check();
+    })
+  `;
+}
+/**
+ * Generate JS to wait until document.querySelector(selector) returns a match.
+ * Uses MutationObserver for near-instant resolution; falls back to reject after timeoutMs.
+ */
+export function waitForSelectorJs(selector, timeoutMs) {
+    return `
+    new Promise((resolve, reject) => {
+      const sel = ${JSON.stringify(selector)};
+      if (document.querySelector(sel)) return resolve('found');
+      const cap = setTimeout(() => {
+        obs.disconnect();
+        reject(new Error('Selector not found: ' + sel));
+      }, ${timeoutMs});
+      const obs = new MutationObserver(() => {
+        if (document.querySelector(sel)) {
+          clearTimeout(cap);
+          obs.disconnect();
+          resolve('found');
+        }
+      });
+      obs.observe(document.body || document.documentElement, { childList: true, subtree: true });
+    })
+  `;
+}

package/dist/browser/dom-helpers.test.d.ts

@@ -0,0 +1 @@
+export {};