0.9.8

When using CDP mode (OPENCLI_CDP_ENDPOINT), the browser page context is
the user's active tab which may be on an unrelated domain. Cookie/header
strategy commands that use fetch() with credentials: 'include' then fail
with "Failed to fetch" due to the browser's same-origin policy.

Fix: before executing cookie/header strategy commands, navigate to the
command's declared domain so the fetch runs in same-origin context.
This mirrors the pre-navigation already done in the cascade command.

Affects all cookie-strategy adapters (bilibili, twitter, zhihu, xueqiu,
etc.) when OPENCLI_CDP_ENDPOINT is enabled and the active Chrome tab is
on a different site.

Co-authored-by: kensei <backtime1993@gmail.com>

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

@@ -0,0 +1,249 @@
+---
+name: cross-project-adapter-migration
+description: "Cross-project CLI command migration workflow for opencli. Use when importing commands from external CLI projects (python/node) like rdt-cli, twitter-cli, etc. Covers: source analysis → gap matrix → batch migration → README/SKILL.md update."
+---
+
+# Cross-Project Adapter Migration
+
+> 从外部 CLI 项目（Python/Node/Go 等）批量迁移命令到 opencli 的标准化流程。
+
+## When to Use
+
+- 用户说"把 xxx-cli 的命令迁移过来"
+- 用户说"看看 xxx 项目有什么可以借鉴的"
+- 用户说"对齐 xxx-cli 的功能"
+- 在为新平台扩展 opencli 时，发现已有第三方 CLI 工具
+
+## Prerequisites
+
+- 熟悉 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md)（adapter 开发决策树）
+- 熟悉 [SKILL.md](file:///Users/jakevin/code/opencli/SKILL.md)（命令参考 & 模板）
+
+---
+
+## Phase 1: 源项目分析
+
+### 1.1 克隆 & 理解源项目
+
+```bash
+# 克隆源项目到 /tmp 做分析
+git clone <source_repo_url> /tmp/<source-cli>
+```
+
+分析重点：
+- **命令列表**：找到所有可用命令（查看 CLI 入口文件、help 输出或 README）
+- **认证方式**：Cookie？API Key？OAuth？浏览器自动化？
+- **数据源**：公开 API？GraphQL？页面抓取？
+- **输出字段**：每个命令返回哪些数据字段
+
+### 1.2 生成命令清单
+
+列出源项目所有命令，包括：
+
+| 命令 | 类型 | API/方法 | 输出字段 |
+|------|------|---------|---------|
+| `xxx feed` | Read | `GET /api/feed` | title, author, time |
+| `xxx post` | Write | `POST /api/tweet` | status, id |
+
+---
+
+## Phase 2: 功能对比矩阵
+
+### 2.1 查看 opencli 现有命令
+
+```bash
+ls src/clis/<site>/     # 查看已有适配器
+opencli list | grep <site>  # 确认已注册命令
+```
+
+### 2.2 生成对比矩阵
+
+对每个源项目命令，标注三种状态：
+
+| 功能 | 源项目 | opencli 现有 | 行动 |
+|------|--------|-------------|------|
+| feed | ✅ `xxx feed` | ❌ 无 | ✅ **新增** |
+| search | ✅ `xxx search` | ✅ `search.ts` | ❌ 已有，跳过 |
+| hot | ✅ `xxx hot` | ⚠️ `hot.yaml`（不完整） | ✅ **增强** |
+| like | ✅ `xxx like` | ✅ `like.ts` | ❌ 已有，跳过 |
+
+### 2.3 筛选迁移目标
+
+去掉已有的、低价值的，保留高价值缺失命令，按 Read/Write 分类：
+
+**筛选原则**：
+- ✅ 高使用频率的命令优先
+- ✅ 已有但不完整的命令标记为"增强"
+- ❌ 源项目特有但 opencli 架构不支持的功能（如需要持久化存储的）跳过
+- ❌ 与现有功能完全重复的跳过
+
+---
+
+## Phase 3: 批量实现
+
+> [!IMPORTANT]
+> 实现前必须查阅 [CLI-EXPLORER.md](file:///Users/jakevin/code/opencli/CLI-EXPLORER.md) 确认策略选择。
+
+### 3.1 选择实现方式
+
+基于决策树分类：
+
+| 类别 | 方式 | 适用条件 |
+|------|------|---------|
+| **Read + 简单 API** | YAML pipeline | 纯 fetch/select/map，无复杂 JS |
+| **Read + GraphQL/分页/签名** | TypeScript adapter | 需要 JS 逻辑 |
+| **Write 操作** | TypeScript + `Strategy.UI` | 点击/输入等 DOM 操作 |
+| **Write + API** | TypeScript + `Strategy.COOKIE/HEADER` | 直接 POST API |
+
+### 3.2 实现顺序
+
+**先 Read 后 Write，先 YAML 后 TS**：
+
+1. **Phase A**: YAML Read 适配器（最快，通常每个 10-20 行）
+2. **Phase B**: TS Read 适配器（需要 evaluate/intercept 的）
+3. **Phase C**: TS Write 适配器（需 UI 自动化或 POST API）
+
+### 3.3 实现模板
+
+#### YAML Read 适配器模板（Cookie 策略）
+
+```yaml
+site: <site>
+name: <command>
+description: <描述>
+domain: www.<site>.com
+strategy: cookie
+browser: true
+
+args:
+  limit:
+    type: int
+    default: 20
+
+pipeline:
+  - navigate: https://www.<site>.com
+  - evaluate: |
+      (async () => {
+        const res = await fetch('<api_endpoint>', { credentials: 'include' });
+        const d = await res.json();
+        return (d.data?.items || []).map(item => ({
+          title: item.title,
+          // ... map source fields
+        }));
+      })()
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+  - limit: ${{ args.limit }}
+
+columns: [rank, title]
+```
+
+#### TS Write 适配器模板（UI 策略）
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: '<site>',
+  name: '<command>',
+  description: '<描述>',
+  strategy: Strategy.UI,
+  args: [{ name: 'target', required: true, help: '<参数说明>' }],
+  columns: ['status', 'message'],
+  func: async (page, kwargs) => {
+    await page.goto(`https://www.<site>.com/${kwargs.target}`);
+    await page.wait({ text: '<expected_text>', timeout: 10 });
+
+    // 获取 snapshot 找到目标按钮
+    const snapshot = await page.accessibility.snapshot();
+    // 点击按钮 ...
+
+    return [{ status: 'success', message: '<action> completed' }];
+  },
+});
+```
+
+### 3.4 公共模式复用
+
+迁移过程中如果发现多个适配器共享逻辑，考虑提取到 `src/<site>.ts` 工具文件：
+
+```typescript
+// src/<site>.ts
+export async function fetchWithAuth(page, url) { ... }
+export function parseItem(raw) { ... }
+```
+
+---
+
+## Phase 4: 验证 & 发布
+
+### 4.1 构建验证
+
+```bash
+npx tsc --noEmit                    # TypeScript 编译检查
+opencli list | grep <site>          # 确认所有命令已注册
+```
+
+### 4.2 运行验证（关键！）
+
+每个新命令必须实际运行：
+
+```bash
+# Read 命令
+opencli <site> <command> --limit 3 -f json
+opencli <site> <command> --limit 3 -v   # verbose 查看 pipeline
+
+# Write 命令（谨慎！会实际操作）
+opencli <site> <command> <test_target>
+```
+
+### 4.3 更新文档
+
+迁移完成后必须更新以下文件：
+
+1. **README.md** — 在对应平台区域添加新命令示例
+2. **SKILL.md** — 在 Commands Reference 中添加新命令
+
+### 4.4 提交 & 推送
+
+```bash
+git add -A
+git commit -m "feat(<site>): migrate <N> commands from <source-cli>
+
+- Phase A: <N> YAML adapters (read operations)
+- Phase B: <N> TS adapters (write operations)
+- Source: <source_repo_url>"
+git push
+```
+
+---
+
+## Checklist
+
+- [ ] 源项目命令清单已生成
+- [ ] 对比矩阵已确认，高价值缺失命令已筛选
+- [ ] 用户确认迁移范围
+- [ ] Phase A: YAML Read 适配器已完成
+- [ ] Phase B: TS Read 适配器已完成
+- [ ] Phase C: TS Write 适配器已完成
+- [ ] `npx tsc --noEmit` 编译通过
+- [ ] 所有新命令已实际运行验证
+- [ ] README.md 已更新
+- [ ] SKILL.md 已更新
+- [ ] 已 commit + push
+
+## 实战案例参考
+
+### rdt-cli → opencli Reddit（2026-03-16）
+
+- **源项目**: `rdt-cli`（25 个 Python 命令）
+- **筛选结果**: 13 个高价值命令
+- **实现**: 7 个 YAML（read） + 6 个 TS（write）
+- **产出**: +11 文件，+767 行代码，Reddit 适配器从 4 → 15（+275%）
+
+### twitter-cli → opencli Twitter（2026-03-16）
+
+- **源项目**: `twitter-cli`（20+ Python 命令）
+- **筛选结果**: 11 个待实现
+- **策略**: Read 用 `Strategy.COOKIE` + GraphQL fetch，Write 用 `Strategy.UI`

.agents/workflows/cross-project-adapter-migration.md

@@ -0,0 +1,54 @@
+---
+description: Migrate commands from an external CLI project into opencli adapters
+---
+
+// turbo-all
+
+## Steps
+
+1. Clone the source CLI project for analysis:
+```bash
+git clone <source_repo_url> /tmp/<source-cli>
+```
+
+2. Analyze source project: list all commands, auth method, API endpoints, and output fields.
+
+3. Check existing opencli adapters for the target site:
+```bash
+ls src/clis/<site>/
+opencli list | grep <site>
+```
+
+4. Generate a comparison matrix table (source commands vs opencli existing). Mark each as: ✅ **New** / ✅ **Enhance** / ❌ **Skip**. Ask user to confirm which commands to migrate.
+
+5. Implement YAML Read adapters first (highest ROI, 10-20 lines each). Place files in `src/clis/<site>/<name>.yaml`.
+
+6. Implement TS Read adapters for complex cases (GraphQL, pagination, signing). Place files in `src/clis/<site>/<name>.ts`.
+
+7. Implement TS Write adapters using `Strategy.UI` or `Strategy.COOKIE`. Place files in `src/clis/<site>/<name>.ts`.
+
+8. Verify build:
+```bash
+npx tsc --noEmit
+```
+
+9. Verify all commands are registered:
+```bash
+opencli list | grep <site>
+```
+
+10. Run each new command to verify it works:
+```bash
+opencli <site> <command> --limit 3 -f json
+```
+
+11. Update README.md with new command examples in the appropriate platform section.
+
+12. Update SKILL.md Commands Reference with new commands.
+
+13. Commit and push:
+```bash
+git add -A
+git commit -m "feat(<site>): migrate <N> commands from <source-cli>"
+git push
+```

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: "🐛 Bug Report"
+description: Report a bug or unexpected behavior in OpenCLI
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. A short reproduction and any error output are usually enough.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this behavior?
+      value: |
+        1. Run `opencli ...`
+        2. ...
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: OpenCLI Version
+      description: "Run `opencli --version` to find out."
+      placeholder: "0.8.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: node-version
+    attributes:
+      label: Node.js Version
+      options:
+        - "20.x"
+        - "22.x"
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: |
+        Paste any relevant error output. Run with `-v` for verbose logs:
+        ```
+        opencli <command> -v
+        ```
+      render: shell
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/jackwener/opencli#readme
+    about: Check the README and docs before opening an issue.
+  - name: 🧪 Testing Guide
+    url: https://github.com/jackwener/opencli/blob/main/TESTING.md
+    about: How to run and write tests for OpenCLI.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: "✨ Feature Request"
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make OpenCLI better? We'd love to hear it!
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description
+      description: A clear and concise description of the feature you'd like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: What problem does this solve? Who benefits from this feature?
+      placeholder: "As a user, I want to ... so that ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: If you have a specific implementation in mind, describe it here.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches you've thought about?
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/new_site_adapter.yml

@@ -0,0 +1,57 @@
+name: "🌐 New Site Adapter Request"
+description: Request support for a new website
+title: "[Site]: "
+labels: ["new-adapter"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Want OpenCLI to support a new site? Tell us about it!
+
+  - type: input
+    id: site-name
+    attributes:
+      label: Site Name
+      description: The name of the website.
+      placeholder: "e.g. Product Hunt"
+    validations:
+      required: true
+
+  - type: input
+    id: site-url
+    attributes:
+      label: Site URL
+      description: The main URL of the website.
+      placeholder: "https://www.producthunt.com"
+    validations:
+      required: true
+
+  - type: textarea
+    id: commands
+    attributes:
+      label: Desired Commands
+      description: What commands would you like? List them with a brief description.
+      value: |
+        - `hot` — trending / popular items
+        - `search` — search the site
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-examples
+    attributes:
+      label: Example Links or API Endpoints
+      description: Share any example page URLs or API endpoints if you have them (optional).
+      placeholder: |
+        Example page: https://www.producthunt.com/posts/example
+        GET https://api.producthunt.com/v2/posts?order=votes
+        Response: { "posts": [{ "name": "...", "tagline": "..." }] }
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Willing to Contribute?
+      options:
+        - label: I'm willing to submit a PR for this adapter

.github/actions/setup-chrome/action.yml

@@ -0,0 +1,26 @@
+name: Setup Chrome + xvfb
+description: Install real Chrome and xvfb virtual display for headed browser testing
+
+outputs:
+  chrome-path:
+    description: Path to the installed Chrome binary
+    value: ${{ steps.setup-chrome.outputs.chrome-path }}
+
+runs:
+  using: composite
+  steps:
+    - name: Install real Chrome (stable)
+      uses: browser-actions/setup-chrome@v1
+      id: setup-chrome
+      with:
+        chrome-version: stable
+
+    - name: Verify Chrome installation
+      shell: bash
+      run: |
+        echo "Chrome path: ${{ steps.setup-chrome.outputs.chrome-path }}"
+        ${{ steps.setup-chrome.outputs.chrome-path }} --version
+
+    - name: Install xvfb for headed mode
+      shell: bash
+      run: sudo apt-get install -y xvfb

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci)"

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- Briefly describe your changes and link to any related issues. -->
+
+Related issue:
+
+## Type of Change
+
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 🌐 New site adapter
+- [ ] 📝 Documentation
+- [ ] ♻️ Refactor
+- [ ] 🔧 CI / build / tooling
+
+## Checklist
+
+- [ ] I ran the checks relevant to this PR
+- [ ] I updated tests or docs if needed
+- [ ] I included output or screenshots when useful
+
+## Screenshots / Output
+
+<!-- If applicable, paste CLI output or screenshots here. -->

.github/workflows/ci.yml

@@ -2,19 +2,28 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, dev]
   pull_request:
-    branches: [main]
+    branches: [main, dev]
+  schedule:
+    - cron: '0 8 * * 1'  # Weekly Monday 08:00 UTC — smoke tests
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
-  check:
+  # ── Fast gate: typecheck + build ──
+  build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
+          cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
@@ -24,3 +33,56 @@ jobs:
 
       - name: Build
         run: npm run build
+
+  # ── Unit tests (vitest shard) ──
+  unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version: ['20', '22']
+        shard: [1, 2]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests (Node ${{ matrix.node-version }}, shard ${{ matrix.shard }}/2)
+        run: npx vitest run src/ --reporter=verbose --shard=${{ matrix.shard }}/2
+
+  # ── Smoke tests (scheduled / manual only) ──
+  smoke-test:
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Chrome + xvfb
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Run smoke tests
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/smoke/ --reporter=verbose
+        env:
+          OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+    timeout-minutes: 15

.github/workflows/e2e-headed.yml

@@ -0,0 +1,41 @@
+name: E2E Headed Chrome
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  workflow_dispatch:
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e-headed:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Setup Chrome + xvfb
+        uses: ./.github/actions/setup-chrome
+        id: setup-chrome
+
+      - name: Build
+        run: npm run build
+
+      - name: Run E2E tests (headed Chrome + xvfb)
+        run: |
+          xvfb-run --auto-servernum --server-args="-screen 0 1280x720x24" \
+            npx vitest run tests/e2e/ --reporter=verbose
+        env:
+          OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}

.github/workflows/pkg-pr-new.yml

@@ -0,0 +1,30 @@
+name: Publish Any Commit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+permissions: {}
+
+jobs:
+  publish:
+    if: ${{ vars.PKG_PR_NEW_ENABLED == 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to pkg.pr.new
+        run: npx pkg-pr-new publish

.github/workflows/release-please.yml

@@ -0,0 +1,25 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ensure release-please token is configured
+        run: |
+          if [ -z "${{ secrets.RELEASE_PLEASE_TOKEN }}" ]; then
+            echo "RELEASE_PLEASE_TOKEN secret is required so release PRs can trigger downstream CI workflows." >&2
+            exit 1
+          fi
+
+      - uses: googleapis/release-please-action@v4
+        with:
+          release-type: node
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}

.github/workflows/release.yml

@@ -13,9 +13,9 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'

.github/workflows/security.yml

@@ -0,0 +1,36 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly Monday 09:00 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: npm audit (production)
+        run: npm audit --omit=dev --audit-level=high
+
+      - name: Check for known vulnerabilities
+        run: npx --yes audit-ci@^7 --high --skip-dev

.gitignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 *.tsbuildinfo
 .opencli/
+.mcp.json
+*.log

CDP.md

@@ -0,0 +1,103 @@
+# Connecting OpenCLI via CDP (Remote/Headless Servers)
+
+If you cannot use the Playwright MCP Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**.
+
+Because CDP binds to `localhost` by default for security reasons, accessing it from a remote server requires an additional networking tunnel.
+
+This guide is broken down into three phases:
+1. **Preparation**: Start Chrome with CDP enabled locally.
+2. **Network Tunnels**: Expose that CDP port to your remote server using either **SSH Tunnels** or **Reverse Proxies**.
+3. **Execution**: Run OpenCLI on your server.
+
+---
+
+## Phase 1: Preparation (Local Machine)
+
+First, you need to start a Chrome browser on your local machine with remote debugging enabled.
+
+**macOS:**
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Linux:**
+```bash
+google-chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Windows:**
+```cmd
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
+  --remote-allow-origins="*"
+```
+
+> **Note**: The `--remote-allow-origins="*"` flag is often required for modern Chrome versions to accept cross-origin CDP WebSocket connections (e.g. from reverse proxies like ngrok).
+
+Once this browser instance opens, **log into the target websites you want to use** (e.g., bilibili.com, zhihu.com) so that the session contains the correct cookies.
+
+---
+
+## Phase 2: Remote Access Methods
+
+Once CDP is running locally on port `9222`, you must securely expose this port to your remote server. Choose one of the two methods below depending on your network conditions.
+
+### Method A: SSH Tunnel (Recommended)
+
+If your local machine has SSH access to the remote server, this is the most secure and straightforward method.
+
+Run this command on your **Local Machine** to forward the remote server's port `9222` back to your local port `9222`:
+
+```bash
+ssh -R 9222:localhost:9222 your-server-user@your-server-ip
+```
+
+Leave this SSH session running in the background.
+
+### Method B: Reverse Proxy (ngrok / frp / socat)
+
+If you cannot establish a direct SSH connection (e.g., due to NAT or firewalls), you can use an intranet penetration tool like `ngrok`.
+
+Run this command on your **Local Machine** to expose your local port `9222` to the public internet securely via ngrok:
+
+```bash
+ngrok http 9222
+```
+
+This will print a forwarding URL, such as `https://abcdef.ngrok.app`. **Copy this URL**.
+
+---
+
+## Phase 3: Execution (Remote Server)
+
+Now switch to your **Remote Server** where OpenCLI is installed. 
+
+Depending on the network tunnel method you chose in Phase 2, set the `OPENCLI_CDP_ENDPOINT` environment variable and run your commands.
+
+### If you used Method A (SSH Tunnel):
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
+opencli doctor                    # Verify connection
+opencli bilibili hot --limit 5    # Test a command
+```
+
+### If you used Method B (Reverse Proxy like ngrok):
+
+```bash
+# Use the URL you copied from ngrok earlier
+export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
+opencli doctor                    # Verify connection
+opencli bilibili hot --limit 5    # Test a command
+```
+
+> *Tip: OpenCLI automatically requests the `/json/version` HTTP endpoint to discover the underlying WebSocket URL if you provide a standard HTTP/HTTPS address.*
+
+If you plan to use this setup frequently, you can persist the environment variable by adding the `export` line to your `~/.bashrc` or `~/.zshrc` on the server.

CDP.zh-CN.md

@@ -0,0 +1,103 @@
+# 通过 CDP 远程连接 OpenCLI (服务器/无头环境)
+
+如果你无法使用 Playwright MCP Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。
+
+出于安全考虑，CDP 默认仅绑定在 `localhost` 的本地端口。所以，若是想让**远程服务器**调用本地的 CDP 服务，我们需要依靠一层额外的网络隧道。
+
+本指南将整个过程拆分为三个阶段：
+1. **阶段一：准备工作**（在本地启动允许 CDP 调试的 Chrome）。
+2. **阶段二：建立网络隧道**（通过 **SSH反向隧道** 或 **反向代理工具**，将本地的 CDP 端口暴露给服务器）。
+3. **阶段三：执行命令**（在服务器端运行 OpenCLI）。
+
+---
+
+## 阶段一：准备工作 (本地电脑)
+
+首先，你需要在你的本地电脑上，通过命令行参数启动一个开启了远程调试端口的 Chrome 实例。
+
+**macOS:**
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Linux:**
+```bash
+google-chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir="$HOME/chrome-debug-profile" \
+  --remote-allow-origins="*"
+```
+
+**Windows:**
+```cmd
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
+  --remote-allow-origins="*"
+```
+
+> **注意**：此处增加的 `--remote-allow-origins="*"` 参数对于较新版本的 Chrome 来说通常是[必需的]，以允许来自反向代理（如 ngrok）的跨域 WebSocket 连接请求。
+
+待这个新的浏览器实例打开后，**手工登录那些你打算使用的网站**（如 bilibili.com、zhihu.com 等），这可以让该浏览器的运行资料（Profile）保留上这些网站登录用的 Cookie。
+
+---
+
+## 阶段二：建立网络隧道
+
+现在你的本地已经有了一个监听在 `9222` 端口的 CDP 服务，接下来，选择以下任意一种方式将其实际暴露给你的远端服务器。
+
+### 方法 A：SSH 反向端口转发 (推荐)
+
+如果你的本地电脑可以直连远程服务器的 SSH，那么这是最简单且最安全的做法。
+
+在你的 **本地电脑** 终端上直接运行这条 ssh 命令，将远程服务器的 `9222` 端口反向映射回本地的 `9222` 端口：
+
+```bash
+ssh -R 9222:localhost:9222 your-server-user@your-server-ip
+```
+
+保持此 SSH 会话在后台运行即可。
+
+### 方法 B：反向代理 / 内网穿透 (ngrok / frp / socat)
+
+如果因为 NAT 或防火墙等因素导致无法直连 SSH 服务器，你可以使用 `ngrok` 等内网穿透工具。
+
+在 **本地电脑** 运行 ngrok 将本地的 `9222` 端口暴露到公网：
+
+```bash
+ngrok http 9222
+```
+
+此时终端里会打印出一段专属的转发 URL 地址（如：`https://abcdef.ngrok.app`）。**复制这一段 URL 地址备用**。
+
+---
+
+## 阶段三：执行命令 (远程服务器)
+
+现在，所有的准备工作已结束。请切换到你已安装好 OpenCLI 的 **远程服务器** 终端上。
+
+根据你在上方阶段二所选择的隧道方案，在终端中配置对应的 `OPENCLI_CDP_ENDPOINT` 环境变量：
+
+### 若使用 方法 A (SSH 反向隧道)：
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
+opencli doctor                    # 查看并验证连接是否通畅
+opencli bilibili hot --limit 5    # 执行目标命令
+```
+
+### 若使用 方法 B (Ngrok 等反向代理)：
+
+```bash
+# 将刚刚使用 ngrok 得到的地址填入这里
+export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
+opencli doctor                    # 查看并验证连接是否通畅
+opencli bilibili hot --limit 5    # 执行目标命令
+```
+
+> *Tip: 如果你填写的是一个普通 HTTP/HTTPS 的 URL 地址，OpenCLI 会自动尝试抓取该地址下的 `/json/version` 节点，来动态解析并连接真正底层依赖的 WebSocket 地址。*
+
+如果你想在此服务器上永久启用该配置，可以将对应的 `export` 语句追加进入你的 `~/.bashrc` 或 `~/.zshrc` 配置文件中。

CLI-ELECTRON.md

@@ -0,0 +1,125 @@
+---
+description: How to CLI-ify and automate any Electron Desktop Application via CDP
+---
+
+# CLI-ifying Electron Applications (Skill Guide)
+
+Based on the successful automation of **Cursor**, **Codex**, **Antigravity**, **ChatWise**, **Notion**, and **Discord** desktop apps, this guide serves as the standard operating procedure (SOP) for adapting ANY Electron-based application into an OpenCLI adapter.
+
+## Core Concept
+
+Electron apps are essentially local Chromium browser instances. By exposing a debugging port (CDP — Chrome DevTools Protocol) at launch time, we can use Playwright to pierce through the UI layer, accessing and controlling all underlying state including React/Vue components and Shadow DOM.
+
+> **Note:** Not all desktop apps are Electron. WeChat (native Cocoa) and Feishu/Lark (custom Lark Framework) embed Chromium but do NOT expose CDP. For those apps, use the AppleScript + clipboard approach instead (see [Non-Electron Pattern](#non-electron-pattern-applescript)).
+
+### Launching the Target App
+```bash
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+```
+
+### Verifying Electron
+```bash
+# Check for Electron Framework in the app bundle
+ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
+# If this directory exists → Electron → CDP works
+# If not → check for libEGL.dylib (embedded Chromium/CEF, CDP may not work)
+```
+
+## The 5-Command Pattern (CDP / Electron)
+
+Every new Electron adapter should implement these 5 commands in `src/clis/<app_name>/`:
+
+### 1. `status.ts` — Connection Test
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  name: 'status',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,       // Requires CDP connection
+  args: [],
+  columns: ['Status', 'Url', 'Title'],
+  func: async (page: IPage) => {
+    const url = await page.evaluate('window.location.href');
+    const title = await page.evaluate('document.title');
+    return [{ Status: 'Connected', Url: url, Title: title }];
+  },
+});
+```
+
+### 2. `dump.ts` — Reverse Engineering Core
+Modern app DOMs are huge and obfuscated. **Never guess selectors.** Dump first, then extract precise class names with AI or `grep`:
+```typescript
+const dom = await page.evaluate('document.body.innerHTML');
+fs.writeFileSync('/tmp/app-dom.html', dom);
+const snap = await page.snapshot({ interactive: false });
+fs.writeFileSync('/tmp/app-snapshot.json', JSON.stringify(snap, null, 2));
+```
+
+### 3. `send.ts` — Advanced Text Injection
+Electron apps often use complex rich-text editors (Monaco, Lexical, ProseMirror). Setting `.value` directly is ignored by React state.
+
+**Best practice:** Use `document.execCommand('insertText')` to perfectly simulate real user input, fully piercing React state:
+```javascript
+const composer = document.querySelector('[contenteditable="true"]');
+composer.focus();
+document.execCommand('insertText', false, 'Hello');
+```
+Then submit with `await page.pressKey('Enter')`.
+
+### 4. `read.ts` — Context Extraction
+Don't extract the entire page text. Use `dump.ts` output to find the real "conversation container":
+- Look for semantic selectors: `[role="log"]`, `[data-testid="conversation"]`, `[data-content-search-turn-key]`
+- Format output as Markdown — readable by both humans and LLMs
+
+### 5. `new.ts` — Keyboard Shortcuts
+Many GUI actions respond to native shortcuts rather than button clicks:
+```typescript
+const isMac = process.platform === 'darwin';
+await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
+await page.wait(1); // Wait for re-render
+```
+
+## Environment Variable
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+## Non-Electron Pattern (AppleScript)
+
+For native macOS apps (WeChat, Feishu) that don't expose CDP:
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  strategy: Strategy.PUBLIC,
+  browser: false,       // No browser needed
+  func: async (page: IPage | null) => {
+    const output = execSync("osascript -e 'application \"MyApp\" is running'", { encoding: 'utf-8' }).trim();
+    return [{ Status: output === 'true' ? 'Running' : 'Stopped' }];
+  },
+});
+```
+
+Core techniques:
+- **status**: `osascript -e 'application "AppName" is running'`
+- **send**: `pbcopy` → activate window → `Cmd+V` → `Enter`
+- **read**: `Cmd+A` → `Cmd+C` → `pbpaste`
+- **search**: Activate → `Cmd+F`/`Cmd+K` → `keystroke "query"`
+
+## Pitfalls & Gotchas
+
+1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports: Codex=9222, ChatGPT=9224, Cursor=9226, ChatWise=9228, Notion=9230, Discord=9232
+2. **IPage abstraction**: OpenCLI wraps Playwright Page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT `page.keyboard.press()`
+3. **Timing**: Always add `await page.wait(0.5)` to `1.0` after DOM mutations. Returning too early disconnects prematurely
+4. **AppleScript requires Accessibility**: Terminal app must be granted permission in System Settings → Privacy & Security → Accessibility
+
+## Port Assignment Table
+
+| App | Port | Mode |
+|-----|------|------|
+| Codex | 9222 | CDP |
+| ChatGPT | 9224 | CDP / AppleScript |
+| Cursor | 9226 | CDP |
+| ChatWise | 9228 | CDP |
+| Notion | 9230 | CDP |
+| Discord App | 9232 | CDP |

CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to OpenCLI
+
+Thanks for your interest in contributing to OpenCLI.
+
+## Quick Start
+
+```bash
+# 1. Fork & clone
+git clone git@github.com:<your-username>/opencli.git
+cd opencli
+
+# 2. Install dependencies
+npm install
+
+# 3. Build
+npm run build
+
+# 4. Run a few checks
+npx tsc --noEmit
+npx vitest run src/
+
+# 5. Link globally (optional, for testing `opencli` command)
+npm link
+```
+
+## Adding a New Site Adapter
+
+This is the most common type of contribution. Start with YAML when possible, and use TypeScript only when you need browser-side logic or multi-step flows.
+
+### YAML Adapter (Recommended for data-fetching commands)
+
+Create a file like `src/clis/<site>/<command>.yaml`:
+
+```yaml
+site: mysite
+name: trending
+description: Trending posts on MySite
+domain: www.mysite.com
+strategy: public      # public | cookie | header
+browser: false        # true if browser session is needed
+
+args:
+  limit:
+    type: int
+    default: 20
+    description: Number of items
+
+pipeline:
+  - fetch:
+      url: https://api.mysite.com/trending
+
+  - map:
+      rank: ${{ index + 1 }}
+      title: ${{ item.title }}
+      score: ${{ item.score }}
+      url: ${{ item.url }}
+
+  - limit: ${{ args.limit }}
+
+columns: [rank, title, score, url]
+```
+
+See [`hackernews/top.yaml`](src/clis/hackernews/top.yaml) for a real example.
+
+### TypeScript Adapter (For complex browser interactions)
+
+Create a file like `src/clis/<site>/<command>.ts`:
+
+```typescript
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'mysite',
+  name: 'search',
+  description: 'Search MySite',
+  domain: 'www.mysite.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'query', required: true, help: 'Search query' },
+    { name: 'limit', type: 'int', default: 10, help: 'Max results' },
+  ],
+  columns: ['title', 'url', 'date'],
+
+  func: async (page, kwargs) => {
+    const { query, limit = 10 } = kwargs;
+    await page.goto('https://www.mysite.com');
+
+    const data = await page.evaluate(`
+      (async () => {
+        const res = await fetch('/api/search?q=${encodeURIComponent(query)}', {
+          credentials: 'include'
+        });
+        return (await res.json()).results;
+      })()
+    `);
+
+    return data.slice(0, Number(limit)).map((item: any) => ({
+      title: item.title,
+      url: item.url,
+      date: item.created_at,
+    }));
+  },
+});
+```
+
+Use `opencli explore <url>` to discover APIs and see [CLI-EXPLORER.md](./CLI-EXPLORER.md) if you need the full adapter workflow.
+
+### Validate Your Adapter
+
+```bash
+# Validate YAML syntax and schema
+opencli validate
+
+# Test your command
+opencli <site> <command> --limit 3 -f json
+
+# Verbose mode for debugging
+opencli <site> <command> -v
+```
+
+## Testing
+
+See [TESTING.md](./TESTING.md) for the full guide and exact test locations.
+
+```bash
+npx vitest run src/           # Unit tests
+npx vitest run tests/e2e/     # E2E tests
+npx vitest run                # All tests
+```
+
+## Code Style
+
+- **TypeScript strict mode** — avoid `any` where possible.
+- **ES Modules** — use `.js` extensions in imports (TypeScript output).
+- **Naming**: `kebab-case` for files, `camelCase` for variables/functions, `PascalCase` for types/classes.
+- **No default exports** — use named exports.
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat(twitter): add thread command
+fix(browser): handle CDP timeout gracefully
+docs: update CONTRIBUTING.md
+test(reddit): add e2e test for save command
+chore: bump vitest to v4
+```
+
+Common scopes: site name (`twitter`, `reddit`) or module name (`browser`, `pipeline`, `engine`).
+
+## Submitting a Pull Request
+
+1. Create a feature branch: `git checkout -b feat/mysite-trending`
+2. Make your changes and add tests when relevant
+3. Run the checks that apply:
+   ```bash
+   npx tsc --noEmit           # Type check
+   npx vitest run src/        # Unit tests
+   opencli validate           # YAML validation (if applicable)
+   ```
+4. Commit using conventional commit format
+5. Push and open a PR
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](./LICENSE).

LICENSE

@@ -1,28 +1,190 @@
-BSD 3-Clause License
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
 
-Copyright (c) 2025, jackwener
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
+   1. Definitions.
 
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
 
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
 
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 jackwener
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,7 +1,7 @@
 # OpenCLI
 
-> **Make any website your CLI.**  
-> Zero risk · Reuse Chrome login · AI-powered discovery
+> **Make any website or Electron App your CLI.**  
+> Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
 
 [中文文档](./README.zh-CN.md)
 
@@ -9,7 +9,10 @@
 [![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-A CLI tool that turns **any website** into a command-line interface. **59 commands** across **18 sites** — bilibili, zhihu, xiaohongshu, twitter, reddit, xueqiu, github, v2ex, hackernews, bbc, weibo, boss, yahoo-finance, reuters, smzdm, ctrip, youtube, coupang — powered by browser session reuse and AI-native discovery.
+A CLI tool that turns **any website** or **Electron app** into a command-line interface — Bilibili, Zhihu, 小红书, Twitter/X, Reddit, YouTube, Antigravity, and [many more](#built-in-commands) — powered by browser session reuse and AI-native discovery.
+
+🔥 **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!
 
 ---
 
@@ -19,8 +22,11 @@ A CLI tool that turns **any website** into a command-line interface. **59 comman
 - [Prerequisites](#prerequisites)
 - [Quick Start](#quick-start)
 - [Built-in Commands](#built-in-commands)
+- [Download Support](#download-support)
 - [Output Formats](#output-formats)
 - [For AI Agents (Developer Guide)](#for-ai-agents-developer-guide)
+- [Remote Chrome (Server/Headless)](#remote-chrome-serverheadless)
+- [Testing](#testing)
 - [Troubleshooting](#troubleshooting)
 - [Releasing New Versions](#releasing-new-versions)
 - [License](#license)
@@ -29,28 +35,53 @@ A CLI tool that turns **any website** into a command-line interface. **59 comman
 
 ## Highlights
 
+- **CLI All Electron** — CLI-ify apps like Antigravity Ultra! Now AI can control itself natively using cc/openclaw!
 - **Account-safe** — Reuses Chrome's logged-in state; your credentials never leave the browser.
 - **AI Agent ready** — `explore` discovers APIs, `synthesize` generates adapters, `cascade` finds auth strategies.
+- **Self-healing setup** — `opencli setup` auto-discovers tokens; `opencli doctor` diagnoses config across 10+ tools; `--fix` repairs them all.
 - **Dynamic Loader** — Simply drop `.ts` or `.yaml` adapters into the `clis/` folder for auto-registration.
-- **Dual-Engine Architecture** — Supports both YAML declarative data pipelines and robust browser runtime typescript injections.
+- **Dual-Engine Architecture** — Supports both YAML declarative data pipelines and robust browser runtime TypeScript injections.
 
 ## Prerequisites
 
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 20.0.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.
 
 OpenCLI connects to your browser through the Playwright MCP Bridge extension.
+It prefers an existing local/global `@playwright/mcp` install and falls back to `npx -y @playwright/mcp@latest` automatically when no local MCP server is found.
 
 ### Playwright MCP Bridge Extension Setup
 
 1. Install **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** extension in Chrome.
-2. Obtain your token by clicking the extension icon in the browser toolbar or from the extension settings page.
+2. Run `opencli setup` — discovers the token, distributes it to your tools, and verifies connectivity:
 
-**You must configure this token in BOTH your MCP configuration AND system environment variables.**
+```bash
+opencli setup
+```
 
-First, add it to your MCP client config (e.g. Claude/Cursor):
+The interactive TUI will:
+- 🔍 Auto-discover `PLAYWRIGHT_MCP_EXTENSION_TOKEN` from Chrome (no manual copy needed)
+- ☑️ Show all detected tools (Codex, Cursor, Claude Code, Gemini CLI, etc.)
+- ✏️ Update only the files you select (Space to toggle, Enter to confirm)
+- 🔌 Auto-verify browser connectivity after writing configs
+
+> **Tip**: Use `opencli doctor` for ongoing diagnosis and maintenance:
+> ```bash
+> opencli doctor            # Read-only token & config diagnosis
+> opencli doctor --live     # Also test live browser connectivity
+> opencli doctor --fix      # Fix mismatched configs (interactive)
+> opencli doctor --fix -y   # Fix all configs non-interactively
+> ```
+
+**Alternative: CDP Mode (For Servers/Headless)**
+If you cannot install the browser extension (e.g. running OpenCLI on a remote headless server), you can connect OpenCLI to your local Chrome via CDP using SSH tunnels or reverse proxies. See the [CDP Connection Guide](./CDP.md) for detailed instructions.
+
+<details>
+<summary>Manual setup (alternative)</summary>
+
+Add token to your MCP client config (e.g. Claude/Cursor):
 
 ```json
 {
@@ -66,17 +97,13 @@ First, add it to your MCP client config (e.g. Claude/Cursor):
 }
 ```
 
-And, so that `opencli` commands can use it directly in the terminal, export it in your shell environment (e.g. `~/.zshrc`):
+Export in shell (e.g. `~/.zshrc`):
 
 ```bash
 export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<your-token-here>"
 ```
 
-After configuring, run `opencli doctor` to verify your token is correctly set up across all locations:
-
-```bash
-opencli doctor
-```
+</details>
 
 ## Quick Start
 
@@ -84,6 +111,7 @@ opencli doctor
 
 ```bash
 npm install -g @jackwener/opencli
+opencli setup   # One-time: configure Playwright MCP token
 ```
 
 Then use directly:
@@ -116,26 +144,99 @@ npm install -g @jackwener/opencli@latest
 
 ## Built-in Commands
 
+Run `opencli list` for the live registry.
+
 | Site | Commands | Mode |
 |------|----------|------|
-| **bilibili** | `hot` `search` `me` `favorite` ... (11 commands) | 🔐 Browser |
-| **zhihu** | `hot` `search` `question` | 🔐 Browser |
-| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 Browser |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` | 🔐 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` `extract-diff` `model` `ask` `screenshot` `history` `export` | 🖥️ Desktop |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | 🖥️ 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` `daily` `me` `notifications` | 🌐 / 🔐 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `following` `followers` `notifications` `post` `reply` `delete` `like` | 🔐 Browser |
-| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 Browser |
-| **weibo** | `hot` | 🔐 Browser |
-| **boss** | `search` | 🔐 Browser |
+| **antigravity** | `status` `send` `read` `new` `evaluate` | 🖥️ Desktop |
+| **chatgpt** | `status` `new` `send` `read` `ask` | 🖥️ Desktop |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` `download` | 🔐 Browser |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
+| **zhihu** | `hot` `search` `question` `download` | 🔐 Browser |
+| **youtube** | `search` `video` `transcript` | 🔐 Browser |
+| **boss** | `search` `detail` | 🔐 Browser |
 | **coupang** | `search` `add-to-cart` | 🔐 Browser |
-| **youtube** | `search` | 🔐 Browser |
-| **yahoo-finance** | `quote` | 🔐 Browser |
-| **reuters** | `search` | 🔐 Browser |
-| **smzdm** | `search` | 🔐 Browser |
+| **bbc** | `news` | 🌐 Public |
 | **ctrip** | `search` | 🔐 Browser |
 | **github** | `search` | 🌐 Public |
-| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 Public / 🔐 Browser |
 | **hackernews** | `top` | 🌐 Public |
-| **bbc** | `news` | 🌐 Public |
+| **linkedin** | `search` | 🔐 Browser |
+| **reuters** | `search` | 🔐 Browser |
+| **smzdm** | `search` | 🔐 Browser |
+| **weibo** | `hot` | 🔐 Browser |
+| **yahoo-finance** | `quote` | 🔐 Browser |
+
+## 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 |
+| **zhihu** | Articles (Markdown) | Exports articles with optional image download |
+
+### Prerequisites
+
+For video downloads from streaming platforms, you need to 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 --note-id abc123 --output ./xhs
+
+# Download Bilibili video (requires yt-dlp)
+opencli bilibili download --bvid BV1xxx --output ./bilibili
+opencli bilibili download --bvid BV1xxx --quality 1080p  # Specify quality
+
+# Download Twitter media from user
+opencli twitter download --username elonmusk --limit 20 --output ./twitter
+
+# Download single tweet media
+opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
+
+# Export Zhihu article to Markdown
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# Export with local images
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --download-images
+```
+
+### Pipeline Step (for YAML adapters)
+
+The `download` step can be used in YAML pipelines:
+
+```yaml
+pipeline:
+  - fetch: https://api.example.com/media
+  - download:
+      url: ${{ item.imageUrl }}
+      dir: ./downloads
+      filename: ${{ item.title | sanitize }}.jpg
+      concurrency: 5
+      skip_existing: true
+```
 
 ## Output Formats
 
@@ -176,6 +277,24 @@ opencli cascade https://api.example.com/data
 
 Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, capabilities.json, auth.json).
 
+## Testing
+
+See **[TESTING.md](./TESTING.md)** for the full testing guide, including:
+
+- Current test coverage (unit + E2E tests across browser and desktop adapters)
+- How to run tests locally
+- How to add tests when creating new adapters
+- CI/CD pipeline with sharding
+- Headless browser mode (`OPENCLI_HEADLESS=1`)
+
+```bash
+# Quick start
+npm run build
+npx vitest run                              # All tests
+npx vitest run src/                          # Unit tests only
+npx vitest run tests/e2e/                    # E2E tests
+```
+
 ## Troubleshooting
 
 - **"Failed to connect to Playwright MCP Bridge"**
@@ -184,7 +303,9 @@ Explore outputs to `.opencli/explore/<site>/` (manifest.json, endpoints.json, ca
 - **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 to prove you are human.
 - **Node API errors**
-  - Make sure you are using Node.js >= 18. Some dependencies require modern Node APIs.
+  - Make sure you are using Node.js >= 20. Some dependencies require modern Node APIs.
+- **Token issues**
+  - Run `opencli doctor` to diagnose token configuration across all tools.
 
 ## Releasing New Versions
 
@@ -198,4 +319,4 @@ The CI will automatically build, create a GitHub release, and publish to npm.
 
 ## License
 
-[BSD-3-Clause](./LICENSE)
+[Apache-2.0](./LICENSE)

README.zh-CN.md

@@ -1,7 +1,7 @@
 # OpenCLI
 
-> **把任何网站变成你的命令行工具。**  
-> 零风控 · 复用 Chrome 登录 · AI 自动发现接口
+> **把任何网站或 Electron 应用变成你的命令行工具。**  
+> 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 浏览器与桌面端自动化
 
 [English](./README.md)
 
@@ -9,7 +9,12 @@
 [![Node.js Version](https://img.shields.io/node/v/@jackwener/opencli?style=flat-square)](https://nodejs.org)
 [![License](https://img.shields.io/npm/l/@jackwener/opencli?style=flat-square)](./LICENSE)
 
-OpenCLI 将任何网站变成命令行工具。**59 个命令**覆盖 **18 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube、Coupang — 复用浏览器登录态，AI 驱动探索。
+OpenCLI 将任何网站或 Electron 应用（如 Antigravity）变成命令行工具 — B站、知乎、小红书、Twitter/X、Reddit、YouTube 等[多种站点与应用](#内置命令) — 复用浏览器登录态，AI 驱动探索。
+
+🔥 **opencli 支持 CLI 化所有 electron 应用！最强大更新来袭！** 🔥
+CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合出各种神奇的能力。
+如果你在使用诸如 Antigravity Ultra 等工具时觉得不够灵活或难以扩展，现在通过 OpenCLI 把他 CLI 化，轻松打破界限。
+现在，**AI 可以自己控制自己**！结合 cc/openclaw 就可以远程控制任何 electron 应用！无限玩法！！
 
 ---
 
@@ -19,8 +24,10 @@ OpenCLI 将任何网站变成命令行工具。**59 个命令**覆盖 **18 个
 - [前置要求](#前置要求)
 - [快速开始](#快速开始)
 - [内置命令](#内置命令)
+- [下载支持](#下载支持)
 - [输出格式](#输出格式)
 - [致 AI Agent（开发者指南）](#致-ai-agent开发者指南)
+- [远程 Chrome（服务器/无头环境）](#远程-chrome服务器无头环境)
 - [常见问题排查](#常见问题排查)
 - [版本发布](#版本发布)
 - [License](#license)
@@ -29,28 +36,53 @@ OpenCLI 将任何网站变成命令行工具。**59 个命令**覆盖 **18 个
 
 ## 亮点
 
-- **59 个命令，18 个站点** — B站、知乎、小红书、Twitter、Reddit、雪球(xueqiu)、GitHub、V2EX、Hacker News、BBC、微博、BOSS直聘、Yahoo Finance、路透社、什么值得买、携程、YouTube、Coupang
+- **CLI All Electron** — 支持把所有 electron 应用（如 Antigravity Ultra）CLI 化，让 AI 控制自己！
+- **多站点覆盖** — 覆盖 B站、知乎、小红书、Twitter、Reddit，以及多种桌面应用
 - **零风控** — 复用 Chrome 登录态，无需存储任何凭证
+- **自修复配置** — `opencli setup` 自动发现 Token；`opencli doctor` 诊断 10+ 工具配置；`--fix` 一键修复
 - **AI 原生** — `explore` 自动发现 API，`synthesize` 生成适配器，`cascade` 探测认证策略
 - **动态加载引擎** — 声明式的 `.yaml` 或者底层定制的 `.ts` 适配器，放入 `clis/` 文件夹即可自动注册生效
 
 ## 前置要求
 
-- **Node.js**: >= 18.0.0
+- **Node.js**: >= 20.0.0
 - **Chrome** 浏览器正在运行，且**已登录目标网站**（如 bilibili.com、zhihu.com、xiaohongshu.com）
 
 > **⚠️ 重要**：大多数命令复用你的 Chrome 登录状态。运行命令前，你必须已在 Chrome 中打开目标网站并完成登录。如果获取到空数据或报错，请先检查你的浏览器登录状态。
 
 OpenCLI 通过 Playwright MCP Bridge 扩展与你的浏览器通信。
+它会优先复用本地或全局已安装的 `@playwright/mcp`，如果没有嗅探到可用 MCP server，则会自动回退到 `npx -y @playwright/mcp@latest` 启动。
 
 ### Playwright MCP Bridge 扩展配置
 
 1. 安装 **[Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm)** 扩展
-2. 在浏览器插件栏点击该插件，或者在插件设置页获取你的 Extension Token。
+2. 运行 `opencli setup` — 自动发现 Token、分发到各工具、验证连通性：
 
-**你必须将这个 Token 同时配置到你的 MCP 配置文件 AND 环境变量中。**
+```bash
+opencli setup
+```
 
-首先，配置你的 MCP 客户端（如 Claude/Cursor 等）：
+交互式 TUI 会：
+- 🔍 从 Chrome 自动发现 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`（无需手动复制）
+- ☑️ 显示所有支持的工具（Codex、Cursor、Claude Code、Gemini CLI 等）
+- ✏️ 只更新你选中的文件（空格切换，回车确认）
+- 🔌 完成后自动验证浏览器连通性
+
+> **Tip**：后续诊断和维护用 `opencli doctor`：
+> ```bash
+> opencli doctor            # 只读 Token 与配置诊断
+> opencli doctor --live     # 额外测试浏览器连通性
+> opencli doctor --fix      # 修复不一致的配置（交互确认）
+> opencli doctor --fix -y   # 无交互直接修复所有配置
+> ```
+
+**备选方案：CDP 模式 (适用于服务器/无头环境)**
+如果你无法安装浏览器扩展（比如在远程无头服务器上运行 OpenCLI），你可以通过 SSH 隧道或反向代理，利用 CDP (Chrome DevTools Protocol) 连接到本地的 Chrome 浏览器。详细指南请参考 [CDP 连接教程](./CDP.zh-CN.md)。
+
+<details>
+<summary>手动配置（备选方案）</summary>
+
+配置你的 MCP 客户端（如 Claude/Cursor 等）：
 
 ```json
 {
@@ -66,17 +98,13 @@ OpenCLI 通过 Playwright MCP Bridge 扩展与你的浏览器通信。
 }
 ```
 
-并且，为了让 `opencli` 命令行也能直接使用它，你必须在你的终端系统环境变量中导出它（建议写进 `~/.zshrc` 或 `~/.bashrc`）：
+在终端环境变量中导出（建议写进 `~/.zshrc`）：
 
 ```bash
 export PLAYWRIGHT_MCP_EXTENSION_TOKEN="<你的-token>"
 ```
 
-配置完成后，运行 `opencli doctor` 检测你的 Token 是否在所有位置都正确配置：
-
-```bash
-opencli doctor
-```
+</details>
 
 ## 快速开始
 
@@ -84,6 +112,7 @@ opencli doctor
 
 ```bash
 npm install -g @jackwener/opencli
+opencli setup   # 首次使用：配置 Playwright MCP token
 ```
 
 直接使用：
@@ -116,26 +145,99 @@ npm install -g @jackwener/opencli@latest
 
 ## 内置命令
 
+运行 `opencli list` 查看完整注册表。
+
 | 站点 | 命令 | 模式 |
 |------|------|------|
-| **bilibili** | `hot` `search` `me` `favorite` ...（共11个） | 🔐 浏览器 |
-| **zhihu** | `hot` `search` `question` | 🔐 浏览器 |
-| **xiaohongshu** | `search` `notifications` `feed` `me` `user` | 🔐 浏览器 |
+| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `thread` `following` `followers` `notifications` `post` `reply` `delete` `like` `article` `follow` `unfollow` `bookmark` `unbookmark` `download` | 🔐 浏览器 |
+| **reddit** | `hot` `frontpage` `popular` `search` `subreddit` `read` `user` `user-posts` `user-comments` `upvote` `save` `comment` `subscribe` `saved` `upvoted` | 🔐 浏览器 |
+| **cursor** | `status` `send` `read` `new` `dump` `composer` `model` `extract-code` `ask` `screenshot` `history` `export` | 🖥️ 桌面端 |
+| **bilibili** | `hot` `search` `me` `favorite` `history` `feed` `subtitle` `dynamic` `ranking` `following` `user-videos` `download` | 🔐 浏览器 |
+| **codex** | `status` `send` `read` `new` `extract-diff` `model` `ask` `screenshot` `history` `export` | 🖥️ 桌面端 |
+| **chatwise** | `status` `new` `send` `read` `ask` `model` `history` `export` `screenshot` | 🖥️ 桌面端 |
+| **notion** | `status` `search` `read` `new` `write` `sidebar` `favorites` `export` | 🖥️ 桌面端 |
+| **discord-app** | `status` `send` `read` `channels` `servers` `search` `members` | 🖥️ 桌面端 |
+| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 / 🔐 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 浏览器 |
-| **twitter** | `trending` `bookmarks` `profile` `search` `timeline` `following` `followers` `notifications` `post` `reply` `delete` `like` | 🔐 浏览器 |
-| **reddit** | `hot` `frontpage` `search` `subreddit` | 🔐 浏览器 |
-| **weibo** | `hot` | 🔐 浏览器 |
-| **boss** | `search` | 🔐 浏览器 |
+| **antigravity** | `status` `send` `read` `new` `evaluate` | 🖥️ 桌面端 |
+| **chatgpt** | `status` `new` `send` `read` `ask` | 🖥️ 桌面端 |
+| **xiaohongshu** | `search` `notifications` `feed` `me` `user` `download` | 🔐 浏览器 |
+| **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 🌐 公开 |
+| **zhihu** | `hot` `search` `question` `download` | 🔐 浏览器 |
+| **youtube** | `search` `video` `transcript` | 🔐 浏览器 |
+| **boss** | `search` `detail` | 🔐 浏览器 |
 | **coupang** | `search` `add-to-cart` | 🔐 浏览器 |
-| **youtube** | `search` | 🔐 浏览器 |
-| **yahoo-finance** | `quote` | 🔐 浏览器 |
-| **reuters** | `search` | 🔐 浏览器 |
-| **smzdm** | `search` | 🔐 浏览器 |
+| **bbc** | `news` | 🌐 公共 API |
 | **ctrip** | `search` | 🔐 浏览器 |
 | **github** | `search` | 🌐 公共 API |
-| **v2ex** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 公共 API / 🔐 浏览器 |
 | **hackernews** | `top` | 🌐 公共 API |
-| **bbc** | `news` | 🌐 公共 API |
+| **linkedin** | `search` | 🔐 浏览器 |
+| **reuters** | `search` | 🔐 浏览器 |
+| **smzdm** | `search` | 🔐 浏览器 |
+| **weibo** | `hot` | 🔐 浏览器 |
+| **yahoo-finance** | `quote` | 🔐 浏览器 |
+
+## 下载支持
+
+OpenCLI 支持从各平台下载图片、视频和文章。
+
+### 支持的平台
+
+| 平台 | 内容类型 | 说明 |
+|------|----------|------|
+| **小红书** | 图片、视频 | 下载笔记中的所有媒体文件 |
+| **B站** | 视频 | 需要安装 `yt-dlp` |
+| **Twitter/X** | 图片、视频 | 从用户媒体页或单条推文下载 |
+| **知乎** | 文章（Markdown） | 导出文章，可选下载图片到本地 |
+
+### 前置依赖
+
+下载流媒体平台的视频需要安装 `yt-dlp`：
+
+```bash
+# 安装 yt-dlp
+pip install yt-dlp
+# 或者
+brew install yt-dlp
+```
+
+### 使用示例
+
+```bash
+# 下载小红书笔记中的图片/视频
+opencli xiaohongshu download --note-id abc123 --output ./xhs
+
+# 下载B站视频（需要 yt-dlp）
+opencli bilibili download --bvid BV1xxx --output ./bilibili
+opencli bilibili download --bvid BV1xxx --quality 1080p  # 指定画质
+
+# 下载 Twitter 用户的媒体
+opencli twitter download --username elonmusk --limit 20 --output ./twitter
+
+# 下载单条推文的媒体
+opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
+
+# 导出知乎文章为 Markdown
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+
+# 导出文章并下载图片到本地
+opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --download-images
+```
+
+### Pipeline Step（用于 YAML 适配器）
+
+`download` step 可以在 YAML 管线中使用：
+
+```yaml
+pipeline:
+  - fetch: https://api.example.com/media
+  - download:
+      url: ${{ item.imageUrl }}
+      dir: ./downloads
+      filename: ${{ item.title | sanitize }}.jpg
+      concurrency: 5
+      skip_existing: true
+```
 
 ## 输出格式
 
@@ -184,7 +286,10 @@ opencli cascade https://api.example.com/data
 - **返回空数据，或者报错 "Unauthorized"**
   - Chrome 里的登录态可能已经过期（甚至被要求过滑动验证码）。请打开当前 Chrome 页面，在新标签页重新手工登录或刷新该页面。
 - **Node API 错误 (如 parseArgs, fs 等)**
-  - 确保 Node.js 版本 `>= 18`。旧版不支持我们使用的现代核心库 API。
+  - 确保 Node.js 版本 `>= 20`。旧版不支持我们使用的现代核心库 API。
+- **Token 问题**
+  - 运行 `opencli doctor` 诊断所有工具的 Token 配置状态。
+  - 使用 `opencli doctor --live` 测试浏览器连通性。
 
 ## 版本发布
 
@@ -198,4 +303,4 @@ git push --follow-tags
 
 ## License
 
-[BSD-3-Clause](./LICENSE)
+[Apache-2.0](./LICENSE)

SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: opencli
-description: "OpenCLI — Make any website your CLI. Zero risk, AI-powered, reuse Chrome login."
-version: 0.5.1
+description: "OpenCLI — Make any website or Electron App your CLI. Zero risk, AI-powered, reuse Chrome login. 80+ commands across 19 sites."
+version: 0.7.3
 author: jackwener
-tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, AI, agent]
+tags: [cli, browser, web, mcp, playwright, bilibili, zhihu, twitter, github, v2ex, hackernews, reddit, xiaohongshu, xueqiu, youtube, boss, coupang, AI, agent]
 ---
 
 # OpenCLI
 
-> Make any website your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
+> Make any website or Electron App your CLI. Reuse Chrome login, zero risk, AI-powered discovery.
 
 > [!CAUTION]
 > **AI Agent 必读：创建或修改任何适配器之前，你必须先阅读 [CLI-EXPLORER.md](./CLI-EXPLORER.md)！**
@@ -34,7 +34,8 @@ npm update -g @jackwener/opencli
 
 Browser commands require:
 1. Chrome browser running **(logged into target sites)**
-2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension installed and configured
+2. [Playwright MCP Bridge](https://chromewebstore.google.com/detail/playwright-mcp-bridge/mmlmfjhmonkocbjadbfplnigmagldckm) extension installed
+3. Run `opencli setup` to auto-discover token and configure all tools
 
 > **Note**: You must be logged into the target website in Chrome before running commands. Tabs opened during command execution are auto-closed afterwards.
 
@@ -67,7 +68,7 @@ opencli zhihu question --id 34816524     # 问题详情和回答
 opencli xiaohongshu search --keyword "美食"  # 搜索笔记
 opencli xiaohongshu notifications             # 通知（mentions/likes/connections）
 opencli xiaohongshu feed --limit 10           # 推荐 Feed
-opencli xiaohongshu me                         # 我的信息
+opencli xiaohongshu me                        # 我的信息
 opencli xiaohongshu user --uid xxx             # 用户主页
 
 # 雪球 Xueqiu (browser)
@@ -85,15 +86,32 @@ opencli github search --keyword "cli"    # 搜索仓库
 opencli twitter trending --limit 10      # 热门话题
 opencli twitter bookmarks --limit 20     # 获取收藏的书签推文
 opencli twitter search --keyword "AI"    # 搜索推文
-opencli twitter profile --username elonmusk  # 用户资料
+opencli twitter profile elonmusk         # 用户资料
 opencli twitter timeline --limit 20      # 时间线
+opencli twitter thread 1234567890        # 推文 thread（原文 + 回复）
+opencli twitter article 1891511252174299446 # 推文长文内容
+opencli twitter follow elonmusk          # 关注用户
+opencli twitter unfollow elonmusk        # 取消关注
+opencli twitter bookmark https://x.com/... # 收藏推文
+opencli twitter unbookmark https://x.com/... # 取消收藏
 
 # Reddit (browser)
 opencli reddit hot --limit 10            # 热门帖子
 opencli reddit hot --subreddit programming  # 指定子版块
-opencli reddit frontpage --limit 10      # 首页
-opencli reddit search --keyword "AI"     # 搜索
-opencli reddit subreddit --name rust     # 子版块浏览
+opencli reddit frontpage --limit 10      # 首页 /r/all
+opencli reddit popular --limit 10        # /r/popular 热门
+opencli reddit search --query "AI" --sort top --time week  # 搜索（支持排序+时间过滤）
+opencli reddit subreddit --name rust --sort top --time month  # 子版块浏览（支持时间过滤）
+opencli reddit read --post_id 1abc123    # 阅读帖子 + 评论
+opencli reddit user --username spez      # 用户资料（karma、注册时间）
+opencli reddit user-posts --username spez  # 用户发帖历史
+opencli reddit user-comments --username spez  # 用户评论历史
+opencli reddit upvote --post_id xxx --direction up  # 投票（up/down/none）
+opencli reddit save --post_id xxx        # 收藏帖子
+opencli reddit comment --post_id xxx --text "Great!"  # 发表评论
+opencli reddit subscribe --subreddit python  # 订阅子版块
+opencli reddit saved --limit 10          # 我的收藏
+opencli reddit upvoted --limit 10        # 我的赞
 
 # V2EX (public + browser)
 opencli v2ex hot --limit 10              # 热门话题
@@ -114,9 +132,13 @@ opencli weibo hot --limit 10            # 微博热搜
 
 # BOSS直聘 (browser)
 opencli boss search --query "AI agent"  # 搜索职位
+opencli boss detail --securityId xxx    # 职位详情
 
 # YouTube (browser)
 opencli youtube search --query "rust"   # 搜索视频
+opencli youtube video --url "https://www.youtube.com/watch?v=xxx"  # 视频元数据（标题、播放量、描述等）
+opencli youtube transcript --url "https://www.youtube.com/watch?v=xxx"  # 获取视频字幕/转录
+opencli youtube transcript --url "xxx" --lang zh-Hans --mode raw  # 指定语言 + 原始时间戳模式
 
 # Yahoo Finance (browser)
 opencli yahoo-finance quote --symbol AAPL  # 股票行情
@@ -129,6 +151,15 @@ opencli smzdm search --keyword "耳机"    # 搜索好价
 
 # 携程 (browser)
 opencli ctrip search --query "三亚"      # 搜索目的地
+
+# Antigravity (Electron/CDP)
+opencli antigravity status              # 检查 CDP 连接
+opencli antigravity send "hello"        # 发送文本到当前 agent 聊天框
+opencli antigravity read                # 读取整个聊天记录面板
+opencli antigravity new                 # 清空聊天、开启新对话
+opencli antigravity extract-code        # 自动抽取 AI 回复中的代码块
+opencli antigravity model claude        # 切换底层模型
+opencli antigravity watch               # 流式监听增量消息
 ```
 
 ### Management Commands
@@ -139,6 +170,11 @@ opencli list --json         # JSON output
 opencli list -f yaml        # YAML output
 opencli validate            # Validate all CLI definitions
 opencli validate bilibili   # Validate specific site
+opencli setup               # Interactive token setup (auto-discover + TUI checkbox)
+opencli doctor              # Diagnose token & extension config across all tools
+opencli doctor --live       # Also test live browser connectivity
+opencli doctor --fix        # Fix mismatched configs (interactive confirmation)
+opencli doctor --fix -y     # Fix all configs non-interactively
 ```
 
 ### AI Agent Workflow

TESTING.md

@@ -0,0 +1,233 @@
+# Testing Guide
+
+> 面向开发者和 AI Agent 的测试参考手册。
+
+## 目录
+
+- [测试架构](#测试架构)
+- [当前覆盖范围](#当前覆盖范围)
+- [本地运行测试](#本地运行测试)
+- [如何添加新测试](#如何添加新测试)
+- [CI/CD 流水线](#cicd-流水线)
+- [浏览器模式](#浏览器模式)
+- [站点兼容性](#站点兼容性)
+
+---
+
+## 测试架构
+
+测试分为三层，全部使用 **vitest** 运行：
+
+```
+tests/
+├── e2e/                           # E2E 集成测试（子进程运行真实 CLI）
+│   ├── helpers.ts                 # runCli() 共享工具
+│   ├── public-commands.test.ts    # 公开 API 命令（无需浏览器）
+│   ├── browser-public.test.ts     # 浏览器命令（公开数据）
+│   ├── browser-auth.test.ts       # 需登录命令（graceful failure 测试）
+│   ├── management.test.ts         # 管理命令（list, validate, verify, help）
+│   └── output-formats.test.ts     # 输出格式（json/yaml/csv/md）
+├── smoke/                         # 烟雾测试（仅定时 / 手动触发）
+│   └── api-health.test.ts         # 外部 API 可用性检测
+src/
+├── *.test.ts                      # 单元测试（已有 8 个）
+```
+
+| 层 | 位置 | 运行方式 | 用途 |
+|---|---|---|---|
+| 单元测试 | `src/**/*.test.ts` | `npx vitest run src/` | 内部模块逻辑 |
+| E2E 测试 | `tests/e2e/*.test.ts` | `npx vitest run tests/e2e/` | 真实 CLI 命令执行 |
+| 烟雾测试 | `tests/smoke/*.test.ts` | `npx vitest run tests/smoke/` | 外部 API 健康 |
+
+---
+
+## 当前覆盖范围
+
+### 单元测试（8 个文件）
+
+| 文件 | 覆盖内容 |
+|---|---|
+| `browser.test.ts` | JSON-RPC、tab 管理、extension/standalone 模式切换 |
+| `engine.test.ts` | 命令发现与执行 |
+| `registry.test.ts` | 命令注册与策略分配 |
+| `output.test.ts` | 输出格式渲染 |
+| `doctor.test.ts` | Token 诊断 |
+| `coupang.test.ts` | 数据归一化 |
+| `pipeline/template.test.ts` | 模板表达式求值 |
+| `pipeline/transform.test.ts` | 数据变换步骤 |
+
+### E2E 测试（~52 个用例）
+
+| 文件 | 覆盖站点/功能 | 测试数 |
+|---|---|---|
+| `public-commands.test.ts` | hackernews/top, v2ex/hot, v2ex/latest, v2ex/topic | 5 |
+| `browser-public.test.ts` | bbc, bilibili×3, weibo, zhihu×2, reddit×2, twitter, xueqiu×2, reuters, youtube, smzdm, boss, ctrip, coupang, xiaohongshu, yahoo-finance, v2ex/daily | 21 |
+| `browser-auth.test.ts` | bilibili/me,dynamic,favorite,history,following + twitter/bookmarks,timeline,notifications + v2ex/me,notifications + xueqiu/feed,watchlist + xiaohongshu/feed,notifications | 14 |
+| `management.test.ts` | list×5 格式, validate×3 级别, verify, --version, --help, unknown cmd | 12 |
+| `output-formats.test.ts` | json, yaml, csv, md 格式验证 | 5 |
+
+### 烟雾测试
+
+公开 API 可用性（hackernews, v2ex×2, v2ex/topic）+ 全站点注册完整性检查。
+
+---
+
+## 本地运行测试
+
+### 前置条件
+
+```bash
+npm ci                # 安装依赖
+npm run build         # 编译（E2E 测试需要 dist/main.js）
+```
+
+### 运行命令
+
+```bash
+# 全部单元测试
+npx vitest run src/
+
+# 全部 E2E 测试（会真实调用外部 API）
+npx vitest run tests/e2e/
+
+# 单个测试文件
+npx vitest run tests/e2e/management.test.ts
+
+# 全部测试（单元 + E2E）
+npx vitest run
+
+# 烟雾测试
+npx vitest run tests/smoke/
+
+# watch 模式（开发时推荐）
+npx vitest src/
+```
+
+### 浏览器命令本地测试须知
+
+- 无 `PLAYWRIGHT_MCP_EXTENSION_TOKEN` 时，opencli 自动启动一个独立浏览器实例
+- `browser-public.test.ts` 使用 `tryBrowserCommand()`，站点反爬导致空数据时 warn + pass
+- `browser-auth.test.ts` 验证 **graceful failure**（不 crash 不 hang 即通过）
+- 如需测试完整登录态，保持 Chrome 登录态 + 设置 `PLAYWRIGHT_MCP_EXTENSION_TOKEN`，手动跑对应测试
+
+---
+
+## 如何添加新测试
+
+### 新增 YAML Adapter（如 `src/clis/producthunt/trending.yaml`）
+
+1. **无需额外操作**：`validate` 测试会自动覆盖 YAML 结构验证
+2. 根据 adapter 类型，在对应文件加一个 `it()` block：
+
+```typescript
+// 如果 browser: false（公开 API）→ tests/e2e/public-commands.test.ts
+it('producthunt trending returns data', async () => {
+  const { stdout, code } = await runCli(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expect(code).toBe(0);
+  const data = parseJsonOutput(stdout);
+  expect(Array.isArray(data)).toBe(true);
+  expect(data.length).toBeGreaterThanOrEqual(1);
+  expect(data[0]).toHaveProperty('title');
+}, 30_000);
+```
+
+```typescript
+// 如果 browser: true 但可公开访问 → tests/e2e/browser-public.test.ts
+it('producthunt trending returns data', async () => {
+  const data = await tryBrowserCommand(['producthunt', 'trending', '--limit', '3', '-f', 'json']);
+  expectDataOrSkip(data, 'producthunt trending');
+}, 60_000);
+```
+
+```typescript
+// 如果 browser: true 且需登录 → tests/e2e/browser-auth.test.ts
+it('producthunt me fails gracefully without login', async () => {
+  await expectGracefulAuthFailure(['producthunt', 'me', '-f', 'json'], 'producthunt me');
+}, 60_000);
+```
+
+### 新增管理命令（如 `opencli export`）
+
+在 `tests/e2e/management.test.ts` 添加测试。
+
+### 新增内部模块
+
+在 `src/` 下对应位置创建 `*.test.ts`。
+
+### 决策流程图
+
+```
+新增功能 → 是内部模块？ → 是 → src/ 下加 *.test.ts
+                ↓ 否
+         是 CLI 命令？ → browser: false? → tests/e2e/public-commands.test.ts
+                              ↓ true
+                        公开数据？ → tests/e2e/browser-public.test.ts
+                              ↓ 需登录
+                        tests/e2e/browser-auth.test.ts
+```
+
+---
+
+## CI/CD 流水线
+
+### ci.yml（主流水线）
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| **build** | push/PR to main,dev | typecheck + build |
+| **unit-test** | push/PR to main,dev | 单元测试，2 shard 并行 |
+| **smoke-test** | 每周一 08:00 UTC / 手动 | xvfb + real Chrome，外部 API 健康检查 |
+
+### e2e-headed.yml（E2E 测试）
+
+| Job | 触发条件 | 内容 |
+|---|---|---|
+| **e2e-headed** | push/PR to main,dev | xvfb + real Chrome，全部 E2E 测试 |
+
+E2E 使用 `browser-actions/setup-chrome` 安装真实 Chrome，配合 `xvfb-run` 提供虚拟显示器，以 headed 模式运行浏览器。
+
+### Sharding
+
+单元测试使用 vitest 内置 shard：
+
+```yaml
+strategy:
+  matrix:
+    shard: [1, 2]
+steps:
+  - run: npx vitest run src/ --shard=${{ matrix.shard }}/2
+```
+
+---
+
+## 浏览器模式
+
+opencli 根据 `PLAYWRIGHT_MCP_EXTENSION_TOKEN` 环境变量自动选择模式：
+
+| 条件 | 模式 | MCP 参数 | 使用场景 |
+|---|---|---|---|
+| Token 已设置 | Extension 模式 | `--extension` | 本地用户，连接已登录的 Chrome |
+| Token 未设置 | Standalone 模式 | （无特殊 flag） | CI 或无扩展环境，自启浏览器 |
+
+CI 中使用 `OPENCLI_BROWSER_EXECUTABLE_PATH` 指定真实 Chrome 路径：
+
+```yaml
+env:
+  OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
+```
+
+---
+
+## 站点兼容性
+
+在 GitHub Actions 美国 runner 上，部分站点因地域限制或登录要求返回空数据。E2E 测试对这些站点使用 warn + pass 策略，不影响 CI 绿灯。
+
+| 站点 | CI 状态 | 限制原因 |
+|---|---|---|
+| hackernews, bbc, v2ex | ✅ 返回数据 | 无限制 |
+| yahoo-finance | ✅ 返回数据 | 无限制 |
+| bilibili, zhihu, weibo, xiaohongshu | ⚠️ 空数据 | 地域限制（中国站点） |
+| reddit, twitter, youtube | ⚠️ 空数据 | 需登录或 cookie |
+| smzdm, boss, ctrip, coupang, xueqiu | ⚠️ 空数据 | 地域限制 / 需登录 |
+
+> 使用 self-hosted runner（国内服务器）可解决地域限制问题。

package-lock.json

@@ -1,17 +1,18 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.5.2",
+  "version": "0.9.8",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@jackwener/opencli",
-      "version": "0.5.2",
-      "license": "BSD-3-Clause",
+      "version": "0.9.8",
+      "hasInstallScript": true,
+      "license": "Apache-2.0",
       "dependencies": {
         "chalk": "^5.3.0",
         "cli-table3": "^0.6.5",
-        "commander": "^13.1.0",
+        "commander": "^14.0.3",
         "js-yaml": "^4.1.0"
       },
       "bin": {
@@ -26,7 +27,7 @@
         "vitest": "^4.1.0"
       },
       "engines": {
-        "node": ">=18.0.0"
+        "node": ">=20.0.0"
       }
     },
     "node_modules/@colors/colors": {
@@ -894,7 +895,6 @@
       "integrity": "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -1075,12 +1075,12 @@
       }
     },
     "node_modules/commander": {
-      "version": "13.1.0",
-      "resolved": "https://registry.npmjs.org/commander/-/commander-13.1.0.tgz",
-      "integrity": "sha512-/rFeCpNJQbhSZjGVwO9RFV3xPqbnERS8MmIQzCtD/zl6gpJuV/bMLuN92oG3F7d8oDEHHRrujSXNUr8fpjntKw==",
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
       "license": "MIT",
       "engines": {
-        "node": ">=18"
+        "node": ">=20"
       }
     },
     "node_modules/convert-source-map": {
@@ -1563,7 +1563,6 @@
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -1806,7 +1805,6 @@
       "integrity": "sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "esbuild": "~0.27.0",
         "get-tsconfig": "^4.7.5"
@@ -1848,7 +1846,6 @@
       "integrity": "sha512-fPGaRNj9Zytaf8LEiBhY7Z6ijnFKdzU/+mL8EFBaKr7Vw1/FWcTBAMW0wLPJAGMPX38ZPVCVgLceWiEqeoqL2Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@oxc-project/runtime": "0.115.0",
         "lightningcss": "^1.32.0",

package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jackwener/opencli",
-  "version": "0.5.2",
+  "version": "0.9.8",
   "publishConfig": {
     "access": "public"
   },
   "description": "Make any website your CLI. AI-powered.",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "type": "module",
   "main": "dist/main.js",
@@ -16,14 +16,16 @@
   "scripts": {
     "dev": "tsx src/main.ts",
     "build": "tsc && npm run clean-yaml && npm run copy-yaml && npm run build-manifest",
-    "build-manifest": "node dist/build-manifest.js || true",
-    "clean-yaml": "find dist/clis -name '*.yaml' -o -name '*.yml' 2>/dev/null | xargs rm -f",
-    "copy-yaml": "find src/clis -name '*.yaml' -o -name '*.yml' | while read f; do d=\"dist/${f#src/}\"; mkdir -p \"$(dirname \"$d\")\"; cp \"$f\" \"$d\"; done",
+    "build-manifest": "node dist/build-manifest.js",
+    "clean-yaml": "node scripts/clean-yaml.cjs",
+    "copy-yaml": "node scripts/copy-yaml.cjs",
     "start": "node dist/main.js",
+    "postinstall": "node scripts/postinstall.js || true",
     "typecheck": "tsc --noEmit",
     "lint": "tsc --noEmit",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
+    "test:site": "node scripts/test-site.mjs",
     "test:watch": "vitest"
   },
   "keywords": [
@@ -34,7 +36,7 @@
     "playwright"
   ],
   "author": "jackwener",
-  "license": "BSD-3-Clause",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jackwener/opencli.git"
@@ -42,7 +44,7 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "cli-table3": "^0.6.5",
-    "commander": "^13.1.0",
+    "commander": "^14.0.3",
     "js-yaml": "^4.1.0"
   },
   "devDependencies": {

scripts/clean-yaml.cjs

@@ -0,0 +1,19 @@
+/**
+ * Clean YAML files from dist/clis/ before copying fresh ones.
+ */
+const { readdirSync, rmSync, existsSync, statSync } = require('fs');
+const path = require('path');
+
+function walk(dir) {
+  if (!existsSync(dir)) return;
+  for (const f of readdirSync(dir)) {
+    const fp = path.join(dir, f);
+    if (statSync(fp).isDirectory()) {
+      walk(fp);
+    } else if (/\.ya?ml$/.test(f)) {
+      rmSync(fp);
+    }
+  }
+}
+
+walk('dist/clis');

scripts/copy-yaml.cjs

@@ -0,0 +1,21 @@
+/**
+ * Copy YAML files from src/clis/ to dist/clis/.
+ */
+const { readdirSync, copyFileSync, mkdirSync, existsSync, statSync } = require('fs');
+const path = require('path');
+
+function walk(src, dst) {
+  if (!existsSync(src)) return;
+  for (const f of readdirSync(src)) {
+    const sp = path.join(src, f);
+    const dp = path.join(dst, f);
+    if (statSync(sp).isDirectory()) {
+      walk(sp, dp);
+    } else if (/\.ya?ml$/.test(f)) {
+      mkdirSync(path.dirname(dp), { recursive: true });
+      copyFileSync(sp, dp);
+    }
+  }
+}
+
+walk('src/clis', 'dist/clis');

scripts/postinstall.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+/**
+ * postinstall script — automatically install shell completion files.
+ *
+ * Detects the user's default shell and writes the completion script to the
+ * standard system completion directory so that tab-completion works immediately
+ * after `npm install -g`.
+ *
+ * Supported shells: bash, zsh, fish.
+ *
+ * This script is intentionally plain Node.js (no TypeScript, no imports from
+ * the main source tree) so that it can run without a build step.
+ */
+
+import { mkdirSync, writeFileSync, existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+
+// ── Completion script content ──────────────────────────────────────────────
+
+const BASH_COMPLETION = `# Bash completion for opencli (auto-installed)
+_opencli_completions() {
+  local cur words cword
+  _get_comp_words_by_ref -n : cur words cword
+
+  local completions
+  completions=$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)
+
+  COMPREPLY=( $(compgen -W "$completions" -- "$cur") )
+  __ltrim_colon_completions "$cur"
+}
+complete -F _opencli_completions opencli
+`;
+
+const ZSH_COMPLETION = `#compdef opencli
+# Zsh completion for opencli (auto-installed)
+_opencli() {
+  local -a completions
+  local cword=$((CURRENT - 1))
+  completions=(\${(f)"$(opencli --get-completions --cursor "$cword" "\${words[@]:1}" 2>/dev/null)"})
+  compadd -a completions
+}
+_opencli
+`;
+
+const FISH_COMPLETION = `# Fish completion for opencli (auto-installed)
+complete -c opencli -f -a '(
+  set -l tokens (commandline -cop)
+  set -l cursor (count (commandline -cop))
+  opencli --get-completions --cursor $cursor $tokens[2..] 2>/dev/null
+)'
+`;
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function detectShell() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('bash')) return 'bash';
+  if (shell.includes('fish')) return 'fish';
+  return null;
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * Ensure fpath contains the custom completions directory in .zshrc.
+ *
+ * Key detail: the fpath line MUST appear BEFORE the first `compinit` call,
+ * otherwise compinit won't scan our completions directory.  This is critical
+ * for oh-my-zsh users (source $ZSH/oh-my-zsh.sh calls compinit internally).
+ */
+function ensureZshFpath(completionsDir, zshrcPath) {
+  const fpathLine = `fpath=(${completionsDir} $fpath)`;
+  const autoloadLine = `autoload -Uz compinit && compinit`;
+  const marker = '# opencli completion';
+
+  if (!existsSync(zshrcPath)) {
+    writeFileSync(zshrcPath, `${marker}\n${fpathLine}\n${autoloadLine}\n`, 'utf8');
+    return;
+  }
+
+  const content = readFileSync(zshrcPath, 'utf8');
+
+  // Already configured — nothing to do
+  if (content.includes(completionsDir)) {
+    return;
+  }
+
+  // Find the first line that triggers compinit (direct call or oh-my-zsh source)
+  const lines = content.split('\n');
+  let insertIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    // Skip comment-only lines
+    if (trimmed.startsWith('#')) continue;
+    if (/compinit/.test(trimmed) || /source\s+.*oh-my-zsh\.sh/.test(trimmed)) {
+      insertIdx = i;
+      break;
+    }
+  }
+
+  if (insertIdx !== -1) {
+    // Insert fpath BEFORE the compinit / oh-my-zsh source line
+    lines.splice(insertIdx, 0, marker, fpathLine);
+    writeFileSync(zshrcPath, lines.join('\n'), 'utf8');
+  } else {
+    // No compinit found — append fpath + compinit at the end
+    let addition = `\n${marker}\n${fpathLine}\n${autoloadLine}\n`;
+    appendFileSync(zshrcPath, addition, 'utf8');
+  }
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+function main() {
+  // Skip in CI environments
+  if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) {
+    return;
+  }
+
+  // Only install completion for global installs and npm link
+  const isGlobal = process.env.npm_config_global === 'true';
+  if (!isGlobal) {
+    return;
+  }
+
+  const shell = detectShell();
+  if (!shell) {
+    // Cannot determine shell; silently skip
+    return;
+  }
+
+  const home = homedir();
+
+  try {
+    switch (shell) {
+      case 'zsh': {
+        const completionsDir = join(home, '.zsh', 'completions');
+        const completionFile = join(completionsDir, '_opencli');
+        ensureDir(completionsDir);
+        writeFileSync(completionFile, ZSH_COMPLETION, 'utf8');
+
+        // Ensure fpath is set up in .zshrc
+        const zshrcPath = join(home, '.zshrc');
+        ensureZshFpath(completionsDir, zshrcPath);
+
+        console.log(`✓ Zsh completion installed to ${completionFile}`);
+        console.log(`  Restart your shell or run: source ~/.zshrc`);
+        break;
+      }
+      case 'bash': {
+        // Try system-level first, fall back to user-level
+        const userCompDir = join(home, '.bash_completion.d');
+        const completionFile = join(userCompDir, 'opencli');
+        ensureDir(userCompDir);
+        writeFileSync(completionFile, BASH_COMPLETION, 'utf8');
+
+        // Ensure .bashrc sources the completion directory
+        const bashrcPath = join(home, '.bashrc');
+        if (existsSync(bashrcPath)) {
+          const content = readFileSync(bashrcPath, 'utf8');
+          if (!content.includes('.bash_completion.d/opencli')) {
+            appendFileSync(bashrcPath,
+              `\n# opencli completion\n[ -f "${completionFile}" ] && source "${completionFile}"\n`,
+              'utf8'
+            );
+          }
+        }
+
+        console.log(`✓ Bash completion installed to ${completionFile}`);
+        console.log(`  Restart your shell or run: source ~/.bashrc`);
+        break;
+      }
+      case 'fish': {
+        const completionsDir = join(home, '.config', 'fish', 'completions');
+        const completionFile = join(completionsDir, 'opencli.fish');
+        ensureDir(completionsDir);
+        writeFileSync(completionFile, FISH_COMPLETION, 'utf8');
+
+        console.log(`✓ Fish completion installed to ${completionFile}`);
+        console.log(`  Restart your shell to activate.`);
+        break;
+      }
+    }
+  } catch (err) {
+    // Completion install is best-effort; never fail the package install
+    if (process.env.OPENCLI_VERBOSE) {
+      console.error(`Warning: Could not install shell completion: ${err.message}`);
+    }
+  }
+}
+
+main();

scripts/test-site.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const site = process.argv[2]?.trim();
+
+if (!site) {
+  console.error('Usage: npm run test:site -- <site>');
+  process.exit(1);
+}
+
+const repoRoot = path.resolve(new URL('..', import.meta.url).pathname);
+const srcDir = path.join(repoRoot, 'src');
+
+function runStep(label, command, args) {
+  console.log(`\n==> ${label}`);
+  const result = spawnSync(command, args, {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+function walk(dir) {
+  const files = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walk(fullPath));
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function toPosix(filePath) {
+  return filePath.split(path.sep).join('/');
+}
+
+function findSiteTests() {
+  return walk(srcDir)
+    .filter(filePath => filePath.endsWith('.test.ts'))
+    .filter(filePath => {
+      const normalized = toPosix(path.relative(repoRoot, filePath));
+      return normalized.includes(`/clis/${site}/`) || normalized.includes(`/${site}.test.ts`);
+    })
+    .sort();
+}
+
+runStep('Typecheck', 'npm', ['run', 'typecheck']);
+runStep('Targeted verify', 'npx', ['tsx', 'src/main.ts', 'verify', site]);
+
+const testFiles = findSiteTests();
+if (testFiles.length === 0) {
+  console.log(`\nNo site-specific vitest files found for "${site}". Skipping full vitest run.`);
+  process.exit(0);
+}
+
+runStep(
+  `Site tests (${site})`,
+  'npx',
+  ['vitest', 'run', ...testFiles.map(filePath => path.relative(repoRoot, filePath))],
+);

src/bilibili.ts

@@ -56,7 +56,7 @@ export async function wbiSign(
   const mixinKey = getMixinKey(imgKey, subKey);
   const wts = Math.floor(Date.now() / 1000);
   const sorted: Record<string, string> = {};
-  const allParams = { ...params, wts: String(wts) };
+  const allParams: Record<string, any> = { ...params, wts: String(wts) };
   for (const key of Object.keys(allParams).sort()) {
     sorted[key] = String(allParams[key]).replace(/[!'()*]/g, '');
   }
@@ -84,10 +84,10 @@ export async function apiGet(
 }
 
 export async function fetchJson(page: IPage, url: string): Promise<any> {
-  const escapedUrl = url.replace(/"/g, '\\"');
+  const urlJs = JSON.stringify(url);
   return page.evaluate(`
     async () => {
-      const res = await fetch("${escapedUrl}", { credentials: "include" });
+      const res = await fetch(${urlJs}, { credentials: "include" });
       return await res.json();
     }
   `);

src/browser.test.ts

@@ -1,5 +1,13 @@
-import { describe, it, expect } from 'vitest';
-import { PlaywrightMCP, __test__ } from './browser.js';
+import { afterEach, describe, it, expect, vi } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { PlaywrightMCP, __test__ } from './browser/index.js';
+
+afterEach(() => {
+  __test__.resetMcpServerPathCache();
+  __test__.setMcpDiscoveryTestHooks();
+  delete process.env.OPENCLI_MCP_SERVER_PATH;
+});
 
 describe('browser helpers', () => {
   it('creates JSON-RPC requests with unique ids', () => {
@@ -49,28 +57,220 @@ describe('browser helpers', () => {
     expect(__test__.appendLimited('12345', '67890', 8)).toBe('34567890');
   });
 
-  it('builds Playwright MCP args with kebab-case executable path', () => {
-    expect(__test__.buildMcpArgs({
-      mcpPath: '/tmp/cli.js',
-      executablePath: '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe',
-    })).toEqual([
-      '/tmp/cli.js',
-      '--extension',
-      '--executable-path',
-      '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe',
-    ]);
+  it('builds extension MCP args in local mode (no CI)', () => {
+    const savedCI = process.env.CI;
+    delete process.env.CI;
+    try {
+      expect(__test__.buildMcpArgs({
+        mcpPath: '/tmp/cli.js',
+        executablePath: '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe',
+      })).toEqual([
+        '/tmp/cli.js',
+        '--extension',
+        '--executable-path',
+        '/mnt/c/Program Files/Google/Chrome/Application/chrome.exe',
+      ]);
 
-    expect(__test__.buildMcpArgs({
-      mcpPath: '/tmp/cli.js',
-    })).toEqual([
-      '/tmp/cli.js',
-      '--extension',
-    ]);
+      expect(__test__.buildMcpArgs({
+        mcpPath: '/tmp/cli.js',
+      })).toEqual([
+        '/tmp/cli.js',
+        '--extension',
+      ]);
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
+  });
+
+  it('builds standalone MCP args in CI mode', () => {
+    const savedCI = process.env.CI;
+    process.env.CI = 'true';
+    try {
+      // CI mode: no --extension — browser launches in standalone headed mode
+      expect(__test__.buildMcpArgs({
+        mcpPath: '/tmp/cli.js',
+      })).toEqual([
+        '/tmp/cli.js',
+      ]);
+
+      expect(__test__.buildMcpArgs({
+        mcpPath: '/tmp/cli.js',
+        executablePath: '/usr/bin/chromium',
+      })).toEqual([
+        '/tmp/cli.js',
+        '--executable-path',
+        '/usr/bin/chromium',
+      ]);
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
+  });
+
+  it('builds a direct node launch spec when a local MCP path is available', () => {
+    const savedCI = process.env.CI;
+    delete process.env.CI;
+    try {
+      expect(__test__.buildMcpLaunchSpec({
+        mcpPath: '/tmp/cli.js',
+        executablePath: '/usr/bin/google-chrome',
+      })).toEqual({
+        command: 'node',
+        args: ['/tmp/cli.js', '--extension', '--executable-path', '/usr/bin/google-chrome'],
+        usedNpxFallback: false,
+      });
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
+  });
+
+  it('falls back to npx bootstrap when no MCP path is available', () => {
+    const savedCI = process.env.CI;
+    delete process.env.CI;
+    try {
+      expect(__test__.buildMcpLaunchSpec({
+        mcpPath: null,
+      })).toEqual({
+        command: 'npx',
+        args: ['-y', '@playwright/mcp@latest', '--extension'],
+        usedNpxFallback: true,
+      });
+    } finally {
+      if (savedCI !== undefined) {
+        process.env.CI = savedCI;
+      } else {
+        delete process.env.CI;
+      }
+    }
   });
 
   it('times out slow promises', async () => {
     await expect(__test__.withTimeoutMs(new Promise(() => {}), 10, 'timeout')).rejects.toThrow('timeout');
   });
+
+  it('prefers OPENCLI_MCP_SERVER_PATH over discovered locations', () => {
+    process.env.OPENCLI_MCP_SERVER_PATH = '/env/mcp/cli.js';
+    const existsSync = vi.fn((candidate: any) => candidate === '/env/mcp/cli.js');
+    const execSync = vi.fn();
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    expect(__test__.findMcpServerPath()).toBe('/env/mcp/cli.js');
+    expect(execSync).not.toHaveBeenCalled();
+    expect(existsSync).toHaveBeenCalledWith('/env/mcp/cli.js');
+  });
+
+  it('discovers global @playwright/mcp from the current Node runtime prefix', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    const runtimeGlobalMcp = '/opt/homebrew/Cellar/node/25.2.1/lib/node_modules/@playwright/mcp/cli.js';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn((candidate: any) => candidate === runtimeGlobalMcp);
+    const execSync = vi.fn();
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBe(runtimeGlobalMcp);
+      expect(execSync).not.toHaveBeenCalled();
+      expect(existsSync).toHaveBeenCalledWith(runtimeGlobalMcp);
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
+
+  it('falls back to npm root -g when runtime prefix lookup misses', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    const runtimeGlobalMcp = '/opt/homebrew/Cellar/node/25.2.1/lib/node_modules/@playwright/mcp/cli.js';
+    const npmRootGlobal = '/Users/jakevin/.nvm/versions/node/v22.14.0/lib/node_modules';
+    const npmGlobalMcp = '/Users/jakevin/.nvm/versions/node/v22.14.0/lib/node_modules/@playwright/mcp/cli.js';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn((candidate: any) => candidate === npmGlobalMcp);
+    const execSync = vi.fn((command: string) => {
+      if (String(command).includes('npm root -g')) return `${npmRootGlobal}\n` as any;
+      throw new Error(`unexpected command: ${String(command)}`);
+    });
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBe(npmGlobalMcp);
+      expect(execSync).toHaveBeenCalledOnce();
+      expect(existsSync).toHaveBeenCalledWith(runtimeGlobalMcp);
+      expect(existsSync).toHaveBeenCalledWith(npmGlobalMcp);
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
+
+  it('returns null when new global discovery paths are unavailable', () => {
+    const originalExecPath = process.execPath;
+    const runtimeExecPath = '/opt/homebrew/Cellar/node/25.2.1/bin/node';
+    Object.defineProperty(process, 'execPath', {
+      value: runtimeExecPath,
+      configurable: true,
+    });
+
+    const existsSync = vi.fn(() => false);
+    const execSync = vi.fn((command: string) => {
+      if (String(command).includes('npm root -g')) return '/missing/global/node_modules\n' as any;
+      throw new Error(`missing command: ${String(command)}`);
+    });
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    try {
+      expect(__test__.findMcpServerPath()).toBeNull();
+    } finally {
+      Object.defineProperty(process, 'execPath', {
+        value: originalExecPath,
+        configurable: true,
+      });
+    }
+  });
+
+  it('ignores non-server playwright cli paths discovered from fallback scans', () => {
+    const wrongCli = '/root/.npm/_npx/e41f203b7505f1fb/node_modules/playwright/lib/mcp/terminal/cli.js';
+    const npxCacheBase = path.join(os.homedir(), '.npm', '_npx');
+
+    const existsSync = vi.fn((candidate: any) => {
+      const value = String(candidate);
+      return value === npxCacheBase || value === wrongCli;
+    });
+
+    const execSync = vi.fn((command: string) => {
+      if (String(command).includes('npm root -g')) return '/missing/global/node_modules\n' as any;
+      if (String(command).includes('--package=@playwright/mcp which mcp-server-playwright')) return `${wrongCli}\n` as any;
+      if (String(command).includes('which mcp-server-playwright')) return '' as any;
+      if (String(command).includes(`find "${npxCacheBase}"`)) return `${wrongCli}\n` as any;
+      throw new Error(`unexpected command: ${String(command)}`);
+    });
+    __test__.setMcpDiscoveryTestHooks({ existsSync, execSync: execSync as any });
+
+    expect(__test__.findMcpServerPath()).toBeNull();
+  });
 });
 
 describe('PlaywrightMCP state', () => {

src/browser.ts

@@ -1,692 +0,0 @@
-/**
- * Browser interaction via Playwright MCP Bridge extension.
- * Connects to an existing Chrome browser through the extension.
- */
-
-import { spawn, execSync, type ChildProcess } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { fileURLToPath } from 'node:url';
-import * as fs from 'node:fs';
-import * as os from 'node:os';
-import * as path from 'node:path';
-import { formatSnapshot } from './snapshotFormatter.js';
-import { PKG_VERSION } from './version.js';
-import { normalizeEvaluateSource } from './pipeline/template.js';
-import { generateInterceptorJs, generateReadInterceptedJs } from './interceptor.js';
-import { withTimeoutMs } from './runtime.js';
-
-const CONNECT_TIMEOUT = parseInt(process.env.OPENCLI_BROWSER_CONNECT_TIMEOUT ?? '30', 10);
-const STDERR_BUFFER_LIMIT = 16 * 1024;
-const INITIAL_TABS_TIMEOUT_MS = 1500;
-const TAB_CLEANUP_TIMEOUT_MS = 2000;
-let _cachedMcpServerPath: string | null | undefined;
-
-type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'unknown';
-type PlaywrightMCPState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
-
-type ConnectFailureInput = {
-  kind: ConnectFailureKind;
-  timeout: number;
-  hasExtensionToken: boolean;
-  tokenFingerprint?: string | null;
-  stderr?: string;
-  exitCode?: number | null;
-  rawMessage?: string;
-};
-
-export function getTokenFingerprint(token: string | undefined): string | null {
-  if (!token) return null;
-  return createHash('sha256').update(token).digest('hex').slice(0, 8);
-}
-
-export function formatBrowserConnectError(input: ConnectFailureInput): Error {
-  const stderr = input.stderr?.trim();
-  const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
-  const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
-
-  if (input.kind === 'missing-token') {
-    return new Error(
-      'Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
-      'Without this token, Chrome will show a manual approval dialog for every new MCP connection. ' +
-      'Copy the token from the Playwright MCP Bridge extension and set it in BOTH your shell environment and MCP client config.' +
-      suffix,
-    );
-  }
-
-  if (input.kind === 'extension-not-installed') {
-    return new Error(
-      'Failed to connect to Playwright MCP Bridge: the browser extension did not attach.\n\n' +
-      'Make sure Chrome is running and the "Playwright MCP Bridge" extension is installed and enabled. ' +
-      'If Chrome shows an approval dialog, click Allow.' +
-      suffix,
-    );
-  }
-
-  if (input.kind === 'extension-timeout') {
-    const likelyCause = input.hasExtensionToken
-      ? `The most likely cause is that PLAYWRIGHT_MCP_EXTENSION_TOKEN does not match the token currently shown by the browser extension.${tokenHint} Re-copy the token from the extension and update BOTH your shell environment and MCP client config.`
-      : 'PLAYWRIGHT_MCP_EXTENSION_TOKEN is not configured, so the extension may be waiting for manual approval.';
-    return new Error(
-      `Timed out connecting to Playwright MCP Bridge (${input.timeout}s).\n\n` +
-      `${likelyCause} If a browser prompt is visible, click Allow.` +
-      suffix,
-    );
-  }
-
-  if (input.kind === 'mcp-init') {
-    return new Error(`Failed to initialize Playwright MCP: ${input.rawMessage ?? 'unknown error'}${suffix}`);
-  }
-
-  if (input.kind === 'process-exit') {
-    return new Error(
-      `Playwright MCP process exited before the browser connection was established${input.exitCode == null ? '' : ` (code ${input.exitCode})`}.` +
-      suffix,
-    );
-  }
-
-  return new Error(input.rawMessage ?? 'Failed to connect to browser');
-}
-
-function inferConnectFailureKind(args: {
-  hasExtensionToken: boolean;
-  stderr: string;
-  rawMessage?: string;
-  exited?: boolean;
-}): ConnectFailureKind {
-  const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
-
-  if (!args.hasExtensionToken)
-    return 'missing-token';
-  if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))
-    return 'extension-not-installed';
-  if (args.rawMessage?.startsWith('MCP init failed:'))
-    return 'mcp-init';
-  if (args.exited)
-    return 'process-exit';
-  return 'extension-timeout';
-}
-
-// JSON-RPC helpers
-let _nextId = 1;
-function createJsonRpcRequest(method: string, params: Record<string, any> = {}): { id: number; message: string } {
-  const id = _nextId++;
-  return {
-    id,
-    message: JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n',
-  };
-}
-
-import type { IPage } from './types.js';
-
-/**
- * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
- */
-export class Page implements IPage {
-  constructor(private _request: (method: string, params?: Record<string, any>) => Promise<any>) {}
-
-  async call(method: string, params: Record<string, any> = {}): Promise<any> {
-    const resp = await this._request(method, params);
-    if (resp.error) throw new Error(`page.${method}: ${resp.error.message ?? JSON.stringify(resp.error)}`);
-    // Extract text content from MCP result
-    const result = resp.result;
-    if (result?.content) {
-      const textParts = result.content.filter((c: any) => c.type === 'text');
-      if (textParts.length === 1) {
-        let text = textParts[0].text;
-        // MCP browser_evaluate returns: "[JSON]\n### Ran Playwright code\n```js\n...\n```"
-        // Strip the "### Ran Playwright code" suffix to get clean JSON
-        const codeMarker = text.indexOf('### Ran Playwright code');
-        if (codeMarker !== -1) {
-          text = text.slice(0, codeMarker).trim();
-        }
-        // Also handle "### Result\n[JSON]" format (some MCP versions)
-        const resultMarker = text.indexOf('### Result\n');
-        if (resultMarker !== -1) {
-          text = text.slice(resultMarker + '### Result\n'.length).trim();
-        }
-        try { return JSON.parse(text); } catch { return text; }
-      }
-    }
-    return result;
-  }
-
-  // --- High-level methods ---
-
-  async goto(url: string): Promise<void> {
-    await this.call('tools/call', { name: 'browser_navigate', arguments: { url } });
-  }
-
-  async evaluate(js: string): Promise<any> {
-    // Normalize IIFE format to function format expected by MCP browser_evaluate
-    const normalized = normalizeEvaluateSource(js);
-    return this.call('tools/call', { name: 'browser_evaluate', arguments: { function: normalized } });
-  }
-
-  async snapshot(opts: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean } = {}): Promise<any> {
-    const raw = await this.call('tools/call', { name: 'browser_snapshot', arguments: {} });
-    if (opts.raw) return raw;
-    if (typeof raw === 'string') return formatSnapshot(raw, opts);
-    return raw;
-  }
-
-  async click(ref: string): Promise<void> {
-    await this.call('tools/call', { name: 'browser_click', arguments: { element: 'click target', ref } });
-  }
-
-  async typeText(ref: string, text: string): Promise<void> {
-    await this.call('tools/call', { name: 'browser_type', arguments: { element: 'type target', ref, text } });
-  }
-
-  async pressKey(key: string): Promise<void> {
-    await this.call('tools/call', { name: 'browser_press_key', arguments: { key } });
-  }
-
-  async wait(options: number | { text?: string; time?: number; timeout?: number }): Promise<void> {
-    if (typeof options === 'number') {
-      await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: options } });
-    } else {
-      // Pass directly to native wait_for, which supports natively awaiting text strings without heavy DOM polling
-      await this.call('tools/call', { name: 'browser_wait_for', arguments: options });
-    }
-  }
-
-  async tabs(): Promise<any> {
-    return this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'list' } });
-  }
-
-  async closeTab(index?: number): Promise<void> {
-    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'close', ...(index !== undefined ? { index } : {}) } });
-  }
-
-  async newTab(): Promise<void> {
-    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'new' } });
-  }
-
-  async selectTab(index: number): Promise<void> {
-    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'select', index } });
-  }
-
-  async networkRequests(includeStatic: boolean = false): Promise<any> {
-    return this.call('tools/call', { name: 'browser_network_requests', arguments: { includeStatic } });
-  }
-
-  async consoleMessages(level: string = 'info'): Promise<any> {
-    return this.call('tools/call', { name: 'browser_console_messages', arguments: { level } });
-  }
-
-  async scroll(direction: string = 'down', amount: number = 500): Promise<void> {
-    await this.call('tools/call', { name: 'browser_press_key', arguments: { key: direction === 'down' ? 'PageDown' : 'PageUp' } });
-  }
-
-  async autoScroll(options: { times?: number; delayMs?: number } = {}): Promise<void> {
-    const times = options.times ?? 3;
-    const delayMs = options.delayMs ?? 2000;
-    const js = `
-      async () => {
-        const maxTimes = ${times};
-        const maxWaitMs = ${delayMs};
-        for (let i = 0; i < maxTimes; i++) {
-          const lastHeight = document.body.scrollHeight;
-          window.scrollTo(0, lastHeight);
-          await new Promise(resolve => {
-            let timeoutId;
-            const observer = new MutationObserver(() => {
-              if (document.body.scrollHeight > lastHeight) {
-                clearTimeout(timeoutId);
-                observer.disconnect();
-                setTimeout(resolve, 100); // Small debounce for rendering
-              }
-            });
-            observer.observe(document.body, { childList: true, subtree: true });
-            timeoutId = setTimeout(() => {
-              observer.disconnect();
-              resolve(null);
-            }, maxWaitMs);
-          });
-        }
-      }
-    `;
-    await this.evaluate(js);
-  }
-
-  async installInterceptor(pattern: string): Promise<void> {
-    await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {
-      arrayName: '__opencli_xhr',
-      patchGuard: '__opencli_interceptor_patched',
-    }));
-  }
-
-  async getInterceptedRequests(): Promise<any[]> {
-    const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
-    return result || [];
-  }
-}
-
-/**
- * Playwright MCP process manager.
- */
-export class PlaywrightMCP {
-  private static _activeInsts: Set<PlaywrightMCP> = new Set();
-  private static _cleanupRegistered = false;
-
-  private static _registerGlobalCleanup() {
-    if (this._cleanupRegistered) return;
-    this._cleanupRegistered = true;
-    const cleanup = () => {
-      for (const inst of this._activeInsts) {
-        if (inst._proc && !inst._proc.killed) {
-          try { inst._proc.kill('SIGKILL'); } catch {}
-        }
-      }
-    };
-    process.on('exit', cleanup);
-    process.on('SIGINT', () => { cleanup(); process.exit(130); });
-    process.on('SIGTERM', () => { cleanup(); process.exit(143); });
-  }
-
-  private _proc: ChildProcess | null = null;
-  private _buffer = '';
-  private _pending = new Map<number, { resolve: (data: any) => void; reject: (error: Error) => void }>();
-  private _initialTabIdentities: string[] = [];
-  private _closingPromise: Promise<void> | null = null;
-  private _state: PlaywrightMCPState = 'idle';
-
-  private _page: Page | null = null;
-
-  get state(): PlaywrightMCPState {
-    return this._state;
-  }
-
-  private _sendRequest(method: string, params: Record<string, any> = {}): Promise<any> {
-    return new Promise<any>((resolve, reject) => {
-      if (!this._proc?.stdin?.writable) {
-        reject(new Error('Playwright MCP process is not writable'));
-        return;
-      }
-      const { id, message } = createJsonRpcRequest(method, params);
-      this._pending.set(id, { resolve, reject });
-      this._proc.stdin.write(message, (err) => {
-        if (!err) return;
-        this._pending.delete(id);
-        reject(err);
-      });
-    });
-  }
-
-  private _rejectPendingRequests(error: Error): void {
-    const pending = [...this._pending.values()];
-    this._pending.clear();
-    for (const waiter of pending) waiter.reject(error);
-  }
-
-  private _resetAfterFailedConnect(): void {
-    const proc = this._proc;
-    this._page = null;
-    this._proc = null;
-    this._buffer = '';
-    this._initialTabIdentities = [];
-    this._rejectPendingRequests(new Error('Playwright MCP connect failed'));
-    PlaywrightMCP._activeInsts.delete(this);
-    if (proc && !proc.killed) {
-      try { proc.kill('SIGKILL'); } catch {}
-    }
-  }
-
-  async connect(opts: { timeout?: number } = {}): Promise<Page> {
-    if (this._state === 'connected' && this._page) return this._page;
-    if (this._state === 'connecting') throw new Error('Playwright MCP is already connecting');
-    if (this._state === 'closing') throw new Error('Playwright MCP is closing');
-    if (this._state === 'closed') throw new Error('Playwright MCP session is closed');
-
-    const mcpPath = findMcpServerPath();
-    if (!mcpPath) throw new Error('Playwright MCP server not found. Install: npm install -D @playwright/mcp');
-
-    PlaywrightMCP._registerGlobalCleanup();
-    PlaywrightMCP._activeInsts.add(this);
-    this._state = 'connecting';
-    const timeout = opts.timeout ?? CONNECT_TIMEOUT;
-
-    return new Promise<Page>((resolve, reject) => {
-      const isDebug = process.env.DEBUG?.includes('opencli:mcp');
-      const debugLog = (msg: string) => isDebug && console.error(`[opencli:mcp] ${msg}`);
-      const extensionToken = process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
-      const tokenFingerprint = getTokenFingerprint(extensionToken);
-      let stderrBuffer = '';
-      let settled = false;
-
-      const settleError = (kind: ConnectFailureKind, extra: { rawMessage?: string; exitCode?: number | null } = {}) => {
-        if (settled) return;
-        settled = true;
-        this._state = 'idle';
-        clearTimeout(timer);
-        this._resetAfterFailedConnect();
-        reject(formatBrowserConnectError({
-          kind,
-          timeout,
-          hasExtensionToken: !!extensionToken,
-          tokenFingerprint,
-          stderr: stderrBuffer,
-          exitCode: extra.exitCode,
-          rawMessage: extra.rawMessage,
-        }));
-      };
-
-      const settleSuccess = (pageToResolve: Page) => {
-        if (settled) return;
-        settled = true;
-        this._state = 'connected';
-        clearTimeout(timer);
-        resolve(pageToResolve);
-      };
-
-      const timer = setTimeout(() => {
-        debugLog('Connection timed out');
-        settleError(inferConnectFailureKind({
-          hasExtensionToken: !!extensionToken,
-          stderr: stderrBuffer,
-        }));
-      }, timeout * 1000);
-
-      const mcpArgs = buildMcpArgs({
-        mcpPath,
-        executablePath: process.env.OPENCLI_BROWSER_EXECUTABLE_PATH,
-      });
-      if (process.env.OPENCLI_VERBOSE) {
-        console.error(`[opencli] Extension token: ${extensionToken ? `configured (fingerprint ${tokenFingerprint})` : 'missing'}`);
-      }
-      debugLog(`Spawning node ${mcpArgs.join(' ')}`);
-
-      this._proc = spawn('node', mcpArgs, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        env: { ...process.env },
-      });
-
-      // Increase max listeners to avoid warnings
-      this._proc.setMaxListeners(20);
-      if (this._proc.stdout) this._proc.stdout.setMaxListeners(20);
-
-      const page = new Page((method, params = {}) => this._sendRequest(method, params));
-      this._page = page;
-
-      this._proc.stdout?.on('data', (chunk: Buffer) => {
-        this._buffer += chunk.toString();
-        const lines = this._buffer.split('\n');
-        this._buffer = lines.pop() ?? '';
-        for (const line of lines) {
-          if (!line.trim()) continue;
-          debugLog(`RECV: ${line}`);
-          try {
-            const parsed = JSON.parse(line);
-            if (typeof parsed?.id === 'number') {
-              const waiter = this._pending.get(parsed.id);
-              if (waiter) {
-                this._pending.delete(parsed.id);
-                waiter.resolve(parsed);
-              }
-            }
-          } catch (e) {
-            debugLog(`Parse error: ${e}`);
-          }
-        }
-      });
-
-      this._proc.stderr?.on('data', (chunk: Buffer) => {
-        const text = chunk.toString();
-        stderrBuffer = appendLimited(stderrBuffer, text, STDERR_BUFFER_LIMIT);
-        debugLog(`STDERR: ${text}`);
-      });
-      this._proc.on('error', (err) => {
-        debugLog(`Subprocess error: ${err.message}`);
-        this._rejectPendingRequests(new Error(`Playwright MCP process error: ${err.message}`));
-        settleError('process-exit', { rawMessage: err.message });
-      });
-      this._proc.on('close', (code) => {
-        debugLog(`Subprocess closed with code ${code}`);
-        this._rejectPendingRequests(new Error(`Playwright MCP process exited before response${code == null ? '' : ` (code ${code})`}`));
-        if (!settled) {
-          settleError(inferConnectFailureKind({
-            hasExtensionToken: !!extensionToken,
-            stderr: stderrBuffer,
-            exited: true,
-          }), { exitCode: code });
-        }
-      });
-
-      // Initialize: send initialize request
-      debugLog('Waiting for initialize response...');
-      this._sendRequest('initialize', {
-        protocolVersion: '2024-11-05',
-        capabilities: {},
-        clientInfo: { name: 'opencli', version: PKG_VERSION },
-      }).then((resp) => {
-        debugLog('Got initialize response');
-        if (resp.error) {
-          settleError(inferConnectFailureKind({
-            hasExtensionToken: !!extensionToken,
-            stderr: stderrBuffer,
-            rawMessage: `MCP init failed: ${resp.error.message}`,
-          }), { rawMessage: resp.error.message });
-          return;
-        }
-        
-        const initializedMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
-        debugLog(`SEND: ${initializedMsg.trim()}`);
-        this._proc?.stdin?.write(initializedMsg);
-
-        // Use tabs as a readiness probe and for tab cleanup bookkeeping.
-        debugLog('Fetching initial tabs count...');
-        withTimeoutMs(page.tabs(), INITIAL_TABS_TIMEOUT_MS, 'Timed out fetching initial tabs').then((tabs: any) => {
-          debugLog(`Tabs response: ${typeof tabs === 'string' ? tabs : JSON.stringify(tabs)}`);
-          this._initialTabIdentities = extractTabIdentities(tabs);
-          settleSuccess(page);
-        }).catch((err) => {
-          debugLog(`Tabs fetch error: ${err.message}`);
-          settleSuccess(page);
-        });
-      }).catch((err) => {
-        debugLog(`Init promise rejected: ${err.message}`);
-        settleError('mcp-init', { rawMessage: err.message });
-      });
-    });
-  }
-
-
-  async close(): Promise<void> {
-    if (this._closingPromise) return this._closingPromise;
-    if (this._state === 'closed') return;
-    this._state = 'closing';
-    this._closingPromise = (async () => {
-      try {
-        // Extension mode opens bridge/session tabs that we can clean up best-effort.
-        if (this._page && this._proc && !this._proc.killed) {
-          try {
-            const tabs = await withTimeoutMs(this._page.tabs(), TAB_CLEANUP_TIMEOUT_MS, 'Timed out fetching tabs during cleanup');
-            const tabEntries = extractTabEntries(tabs);
-            const tabsToClose = diffTabIndexes(this._initialTabIdentities, tabEntries);
-            for (const index of tabsToClose) {
-              try { await this._page.closeTab(index); } catch {}
-            }
-          } catch {}
-        }
-        if (this._proc && !this._proc.killed) {
-          this._proc.kill('SIGTERM');
-          const exited = await new Promise<boolean>((res) => {
-            let done = false;
-            const finish = (value: boolean) => {
-              if (done) return;
-              done = true;
-              res(value);
-            };
-            this._proc?.once('exit', () => finish(true));
-            setTimeout(() => finish(false), 3000);
-          });
-          if (!exited && this._proc && !this._proc.killed) {
-            try { this._proc.kill('SIGKILL'); } catch {}
-          }
-        }
-      } finally {
-        this._rejectPendingRequests(new Error('Playwright MCP session closed'));
-        this._page = null;
-        this._proc = null;
-        this._state = 'closed';
-        PlaywrightMCP._activeInsts.delete(this);
-      }
-    })();
-    return this._closingPromise;
-  }
-}
-
-function extractTabEntries(raw: any): Array<{ index: number; identity: string }> {
-  if (Array.isArray(raw)) {
-    return raw.map((tab: any, index: number) => ({
-      index,
-      identity: [
-        tab?.id ?? '',
-        tab?.url ?? '',
-        tab?.title ?? '',
-        tab?.name ?? '',
-      ].join('|'),
-    }));
-  }
-
-  if (typeof raw === 'string') {
-    return raw
-      .split('\n')
-      .map(line => line.trim())
-      .filter(Boolean)
-      .map(line => {
-        // Match actual Playwright MCP format: "- 0: (current) [title](url)"  or  "- 1: [title](url)"
-        const mcpMatch = line.match(/^-\s+(\d+):\s*(.*)$/);
-        if (mcpMatch) {
-          return {
-            index: parseInt(mcpMatch[1], 10),
-            identity: mcpMatch[2].trim() || `tab-${mcpMatch[1]}`,
-          };
-        }
-        // Legacy format: "Tab 0 ..."
-        const legacyMatch = line.match(/Tab\s+(\d+)\s*(.*)$/);
-        if (legacyMatch) {
-          return {
-            index: parseInt(legacyMatch[1], 10),
-            identity: legacyMatch[2].trim() || `tab-${legacyMatch[1]}`,
-          };
-        }
-        return null;
-      })
-      .filter((entry): entry is { index: number; identity: string } => entry !== null);
-  }
-
-  return [];
-}
-
-function extractTabIdentities(raw: any): string[] {
-  return extractTabEntries(raw).map(tab => tab.identity);
-}
-
-function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{ index: number; identity: string }>): number[] {
-  if (initialIdentities.length === 0 || currentTabs.length === 0) return [];
-  const remaining = new Map<string, number>();
-  for (const identity of initialIdentities) {
-    remaining.set(identity, (remaining.get(identity) ?? 0) + 1);
-  }
-
-  const tabsToClose: number[] = [];
-  for (const tab of currentTabs) {
-    const count = remaining.get(tab.identity) ?? 0;
-    if (count > 0) {
-      remaining.set(tab.identity, count - 1);
-      continue;
-    }
-    tabsToClose.push(tab.index);
-  }
-
-  return tabsToClose.sort((a, b) => b - a);
-}
-
-function appendLimited(current: string, chunk: string, limit: number): string {
-  const next = current + chunk;
-  if (next.length <= limit) return next;
-  return next.slice(-limit);
-}
-
-function buildMcpArgs(input: { mcpPath: string; executablePath?: string | null }): string[] {
-  const args = [input.mcpPath, '--extension'];
-  if (input.executablePath) {
-    args.push('--executable-path', input.executablePath);
-  }
-  return args;
-}
-
-export const __test__ = {
-  createJsonRpcRequest,
-  extractTabEntries,
-  diffTabIndexes,
-  appendLimited,
-  buildMcpArgs,
-  withTimeoutMs,
-};
-
-function findMcpServerPath(): string | null {
-  if (_cachedMcpServerPath !== undefined) return _cachedMcpServerPath;
-
-  const envMcp = process.env.OPENCLI_MCP_SERVER_PATH;
-  if (envMcp && fs.existsSync(envMcp)) {
-    _cachedMcpServerPath = envMcp;
-    return _cachedMcpServerPath;
-  }
-
-  // Check local node_modules first (@playwright/mcp is the modern package)
-  const localMcp = path.resolve('node_modules', '@playwright', 'mcp', 'cli.js');
-  if (fs.existsSync(localMcp)) {
-    _cachedMcpServerPath = localMcp;
-    return _cachedMcpServerPath;
-  }
-
-  // Check project-relative path
-  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
-  const projectMcp = path.resolve(__dirname2, '..', 'node_modules', '@playwright', 'mcp', 'cli.js');
-  if (fs.existsSync(projectMcp)) {
-    _cachedMcpServerPath = projectMcp;
-    return _cachedMcpServerPath;
-  }
-
-  // Check common locations
-  const candidates = [
-    path.join(os.homedir(), '.npm', '_npx'),
-    path.join(os.homedir(), 'node_modules', '.bin'),
-    '/usr/local/lib/node_modules',
-  ];
-
-  // Try npx resolution (legacy package name)
-  try {
-    const result = execSync('npx -y --package=@playwright/mcp which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 10000 }).trim();
-    if (result && fs.existsSync(result)) {
-      _cachedMcpServerPath = result;
-      return _cachedMcpServerPath;
-    }
-  } catch {}
-
-  // Try which
-  try {
-    const result = execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
-    if (result && fs.existsSync(result)) {
-      _cachedMcpServerPath = result;
-      return _cachedMcpServerPath;
-    }
-  } catch {}
-
-  // Search in common npx cache
-  for (const base of candidates) {
-    if (!fs.existsSync(base)) continue;
-    try {
-      const found = execSync(`find "${base}" -name "cli.js" -path "*playwright*mcp*" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
-      if (found) {
-        _cachedMcpServerPath = found;
-        return _cachedMcpServerPath;
-      }
-    } catch {}
-  }
-
-  _cachedMcpServerPath = null;
-  return _cachedMcpServerPath;
-}

src/browser/discover.ts

@@ -0,0 +1,241 @@
+/**
+ * MCP server path discovery and argument building.
+ */
+
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+let _cachedMcpServerPath: string | null | undefined;
+let _existsSync = fs.existsSync;
+let _execSync = execSync;
+
+function isSupportedMcpEntrypoint(candidate: string): boolean {
+  const normalized = candidate.replace(/\\/g, '/').toLowerCase();
+  return normalized.endsWith('/@playwright/mcp/cli.js') ||
+    normalized.endsWith('/mcp-server-playwright') ||
+    normalized.endsWith('/mcp-server-playwright.js');
+}
+
+function resolveSupportedMcpPath(candidate: string | null | undefined): string | null {
+  const trimmed = candidate?.trim();
+  if (!trimmed || !_existsSync(trimmed)) return null;
+  return isSupportedMcpEntrypoint(trimmed) ? trimmed : null;
+}
+
+export function resetMcpServerPathCache(): void {
+  _cachedMcpServerPath = undefined;
+}
+
+export function setMcpDiscoveryTestHooks(input?: {
+  existsSync?: typeof fs.existsSync;
+  execSync?: typeof execSync;
+}): void {
+  _existsSync = input?.existsSync ?? fs.existsSync;
+  _execSync = input?.execSync ?? execSync;
+}
+
+export function findMcpServerPath(): string | null {
+  if (_cachedMcpServerPath !== undefined) return _cachedMcpServerPath;
+
+  const envMcp = process.env.OPENCLI_MCP_SERVER_PATH;
+  if (envMcp && _existsSync(envMcp)) {
+    _cachedMcpServerPath = envMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check local node_modules first (@playwright/mcp is the modern package)
+  const localMcp = path.resolve('node_modules', '@playwright', 'mcp', 'cli.js');
+  if (_existsSync(localMcp)) {
+    _cachedMcpServerPath = localMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check project-relative path
+  const __dirname2 = path.dirname(fileURLToPath(import.meta.url));
+  const projectMcp = path.resolve(__dirname2, '..', '..', 'node_modules', '@playwright', 'mcp', 'cli.js');
+  if (_existsSync(projectMcp)) {
+    _cachedMcpServerPath = projectMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check global npm/yarn locations derived from current Node runtime.
+  const nodePrefix = path.resolve(path.dirname(process.execPath), '..');
+  const globalNodeModules = path.join(nodePrefix, 'lib', 'node_modules');
+  const globalMcp = path.join(globalNodeModules, '@playwright', 'mcp', 'cli.js');
+  if (_existsSync(globalMcp)) {
+    _cachedMcpServerPath = globalMcp;
+    return _cachedMcpServerPath;
+  }
+
+  // Check npm global root directly.
+  try {
+    const npmRootGlobal = _execSync('npm root -g 2>/dev/null', {
+      encoding: 'utf-8',
+      timeout: 5000,
+    }).trim();
+    const npmGlobalMcp = path.join(npmRootGlobal, '@playwright', 'mcp', 'cli.js');
+    if (npmRootGlobal && _existsSync(npmGlobalMcp)) {
+      _cachedMcpServerPath = npmGlobalMcp;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
+  // Check common locations
+  const candidates = [
+    path.join(os.homedir(), '.npm', '_npx'),
+    path.join(os.homedir(), 'node_modules', '.bin'),
+    '/usr/local/lib/node_modules',
+  ];
+
+  // Try npx resolution (legacy package name)
+  try {
+    const result = _execSync('npx -y --package=@playwright/mcp which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 10000 }).trim();
+    const resolved = resolveSupportedMcpPath(result);
+    if (resolved) {
+      _cachedMcpServerPath = resolved;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
+  // Try which
+  try {
+    const result = _execSync('which mcp-server-playwright 2>/dev/null', { encoding: 'utf-8', timeout: 5000 }).trim();
+    const resolved = resolveSupportedMcpPath(result);
+    if (resolved) {
+      _cachedMcpServerPath = resolved;
+      return _cachedMcpServerPath;
+    }
+  } catch {}
+
+  // Search in common npx cache
+  for (const base of candidates) {
+    if (!_existsSync(base)) continue;
+    try {
+      const found = _execSync(`find "${base}" -type f -path "*/@playwright/mcp/cli.js" 2>/dev/null | head -1`, { encoding: 'utf-8', timeout: 5000 }).trim();
+      const resolved = resolveSupportedMcpPath(found);
+      if (resolved) {
+        _cachedMcpServerPath = resolved;
+        return _cachedMcpServerPath;
+      }
+    } catch {}
+  }
+
+  _cachedMcpServerPath = null;
+  return _cachedMcpServerPath;
+}
+
+/**
+ * Chrome 144+ auto-discovery: read DevToolsActivePort file to get CDP endpoint.
+ *
+ * Starting with Chrome 144, users can enable remote debugging from
+ * chrome://inspect#remote-debugging without any command-line flags.
+ * Chrome writes the active port and browser GUID to a DevToolsActivePort file
+ * in the user data directory, which we read to construct the WebSocket endpoint.
+ */
+export function discoverChromeEndpoint(): string | null {
+  const candidates: string[] = [];
+
+  // User-specified Chrome data dir takes highest priority
+  if (process.env.CHROME_USER_DATA_DIR) {
+    candidates.push(path.join(process.env.CHROME_USER_DATA_DIR, 'DevToolsActivePort'));
+  }
+
+  // Standard Chrome/Edge user data dirs per platform
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA ?? path.join(os.homedir(), 'AppData', 'Local');
+    candidates.push(path.join(localAppData, 'Google', 'Chrome', 'User Data', 'DevToolsActivePort'));
+    candidates.push(path.join(localAppData, 'Microsoft', 'Edge', 'User Data', 'DevToolsActivePort'));
+  } else if (process.platform === 'darwin') {
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Google', 'Chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), 'Library', 'Application Support', 'Microsoft Edge', 'DevToolsActivePort'));
+  } else {
+    candidates.push(path.join(os.homedir(), '.config', 'google-chrome', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'chromium', 'DevToolsActivePort'));
+    candidates.push(path.join(os.homedir(), '.config', 'microsoft-edge', 'DevToolsActivePort'));
+  }
+
+  for (const filePath of candidates) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8').trim();
+      const lines = content.split('\n');
+      if (lines.length >= 2) {
+        const port = parseInt(lines[0], 10);
+        const browserPath = lines[1]; // e.g. /devtools/browser/<GUID>
+        if (port > 0 && browserPath.startsWith('/devtools/browser/')) {
+          return `ws://127.0.0.1:${port}${browserPath}`;
+        }
+      }
+    } catch {}
+  }
+  return null;
+}
+
+export function resolveCdpEndpoint(): { endpoint?: string; requestedCdp: boolean } {
+  const envVal = process.env.OPENCLI_CDP_ENDPOINT;
+  if (envVal === '1' || envVal?.toLowerCase() === 'true') {
+    const autoDiscovered = discoverChromeEndpoint();
+    return { endpoint: autoDiscovered ?? envVal, requestedCdp: true };
+  }
+
+  if (envVal) {
+    return { endpoint: envVal, requestedCdp: true };
+  }
+
+  // Fallback to auto-discovery if not explicitly set
+  const autoDiscovered = discoverChromeEndpoint();
+  if (autoDiscovered) {
+    return { endpoint: autoDiscovered, requestedCdp: true };
+  }
+
+  return { requestedCdp: false };
+}
+
+function buildRuntimeArgs(input?: { executablePath?: string | null; cdpEndpoint?: string }): string[] {
+  const args: string[] = [];
+
+  // Priority 1: CDP endpoint (remote Chrome debugging or local Auto-Discovery)
+  if (input?.cdpEndpoint) {
+    args.push('--cdp-endpoint', input.cdpEndpoint);
+    return args;
+  }
+
+  // Priority 2: Extension mode (local Chrome with MCP Bridge extension)
+  if (!process.env.CI) {
+    args.push('--extension');
+  }
+
+  // CI/standalone mode: @playwright/mcp launches its own browser (headed by default).
+  // xvfb provides a virtual display for headed mode in GitHub Actions.
+  if (input?.executablePath) {
+    args.push('--executable-path', input.executablePath);
+  }
+  return args;
+}
+
+export function buildMcpArgs(input: { mcpPath: string; executablePath?: string | null; cdpEndpoint?: string }): string[] {
+  return [input.mcpPath, ...buildRuntimeArgs(input)];
+}
+
+export function buildMcpLaunchSpec(input: { mcpPath?: string | null; executablePath?: string | null; cdpEndpoint?: string }): {
+  command: string;
+  args: string[];
+  usedNpxFallback: boolean;
+} {
+  const runtimeArgs = buildRuntimeArgs(input);
+  if (input.mcpPath) {
+    return {
+      command: 'node',
+      args: [input.mcpPath, ...runtimeArgs],
+      usedNpxFallback: false,
+    };
+  }
+
+  return {
+    command: 'npx',
+    args: ['-y', '@playwright/mcp@latest', ...runtimeArgs],
+    usedNpxFallback: true,
+  };
+}

src/browser/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * Browser connection error classification and formatting.
+ */
+
+import { createHash } from 'node:crypto';
+
+export type ConnectFailureKind = 'missing-token' | 'extension-timeout' | 'extension-not-installed' | 'mcp-init' | 'process-exit' | 'cdp-connection-failed' | 'unknown';
+
+export type ConnectFailureInput = {
+  kind: ConnectFailureKind;
+  timeout: number;
+  hasExtensionToken: boolean;
+  tokenFingerprint?: string | null;
+  stderr?: string;
+  exitCode?: number | null;
+  rawMessage?: string;
+};
+
+export function getTokenFingerprint(token: string | undefined): string | null {
+  if (!token) return null;
+  return createHash('sha256').update(token).digest('hex').slice(0, 8);
+}
+
+export function formatBrowserConnectError(input: ConnectFailureInput): Error {
+  const stderr = input.stderr?.trim();
+  const suffix = stderr ? `\n\nMCP stderr:\n${stderr}` : '';
+  const tokenHint = input.tokenFingerprint ? ` Token fingerprint: ${input.tokenFingerprint}.` : '';
+
+  if (input.kind === 'cdp-connection-failed') {
+    return new Error(
+      `Failed to connect to remote Chrome via CDP endpoint.\n\n` +
+      `Check if Chrome is running with remote debugging enabled (--remote-debugging-port=9222) or DevToolsActivePort is available under chrome://inspect#remote-debugging.\n` +
+      `If you specified OPENCLI_CDP_ENDPOINT=1, auto-discovery might have failed.` +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'missing-token') {
+    return new Error(
+      'Failed to connect to Playwright MCP Bridge: PLAYWRIGHT_MCP_EXTENSION_TOKEN is not set.\n\n' +
+      'Without this token, Chrome will show a manual approval dialog for every new MCP connection. ' +
+      'Copy the token from the Playwright MCP Bridge extension and set it in BOTH your shell environment and MCP client config.' +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'extension-not-installed') {
+    return new Error(
+      'Failed to connect to Playwright MCP Bridge: the browser extension did not attach.\n\n' +
+      'Make sure Chrome is running and the "Playwright MCP Bridge" extension is installed and enabled. ' +
+      'If Chrome shows an approval dialog, click Allow.' +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'extension-timeout') {
+    const likelyCause = input.hasExtensionToken
+      ? `The most likely cause is that PLAYWRIGHT_MCP_EXTENSION_TOKEN does not match the token currently shown by the browser extension.${tokenHint} Re-copy the token from the extension and update BOTH your shell environment and MCP client config.`
+      : 'PLAYWRIGHT_MCP_EXTENSION_TOKEN is not configured, so the extension may be waiting for manual approval.';
+    return new Error(
+      `Timed out connecting to Playwright MCP Bridge (${input.timeout}s).\n\n` +
+      `${likelyCause} If a browser prompt is visible, click Allow.` +
+      suffix,
+    );
+  }
+
+  if (input.kind === 'mcp-init') {
+    return new Error(`Failed to initialize Playwright MCP: ${input.rawMessage ?? 'unknown error'}${suffix}`);
+  }
+
+  if (input.kind === 'process-exit') {
+    return new Error(
+      `Playwright MCP process exited before the browser connection was established${input.exitCode == null ? '' : ` (code ${input.exitCode})`}.` +
+      suffix,
+    );
+  }
+
+  return new Error(input.rawMessage ?? 'Failed to connect to browser');
+}
+
+export function inferConnectFailureKind(args: {
+  hasExtensionToken: boolean;
+  stderr: string;
+  rawMessage?: string;
+  exited?: boolean;
+  isCdpMode?: boolean;
+}): ConnectFailureKind {
+  const haystack = `${args.rawMessage ?? ''}\n${args.stderr}`.toLowerCase();
+
+  if (args.isCdpMode) {
+    if (args.rawMessage?.startsWith('MCP init failed:')) return 'mcp-init';
+    if (args.exited) return 'cdp-connection-failed';
+    return 'cdp-connection-failed';
+  }
+
+  if (!args.hasExtensionToken)
+    return 'missing-token';
+  if (haystack.includes('extension connection timeout') || haystack.includes('playwright mcp bridge'))
+    return 'extension-not-installed';
+  if (args.rawMessage?.startsWith('MCP init failed:'))
+    return 'mcp-init';
+  if (args.exited)
+    return 'process-exit';
+  return 'extension-timeout';
+}

src/browser/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Browser module — public API re-exports.
+ *
+ * This barrel replaces the former monolithic browser.ts.
+ * External code should import from './browser/index.js' (or './browser.js' via Node resolution).
+ */
+
+export { Page } from './page.js';
+export { PlaywrightMCP } from './mcp.js';
+export { getTokenFingerprint, formatBrowserConnectError } from './errors.js';
+export type { ConnectFailureKind, ConnectFailureInput } from './errors.js';
+export { resolveCdpEndpoint } from './discover.js';
+
+// Test-only helpers — exposed for unit tests
+import { createJsonRpcRequest } from './mcp.js';
+import { extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
+import { buildMcpArgs, buildMcpLaunchSpec, findMcpServerPath, resetMcpServerPathCache, setMcpDiscoveryTestHooks } from './discover.js';
+import { withTimeoutMs } from '../runtime.js';
+
+export const __test__ = {
+  createJsonRpcRequest,
+  extractTabEntries,
+  diffTabIndexes,
+  appendLimited,
+  buildMcpArgs,
+  buildMcpLaunchSpec,
+  findMcpServerPath,
+  resetMcpServerPathCache,
+  setMcpDiscoveryTestHooks,
+  withTimeoutMs,
+};

src/browser/mcp.ts

@@ -0,0 +1,312 @@
+/**
+ * Playwright MCP process manager.
+ * Handles lifecycle management, JSON-RPC communication, and browser session orchestration.
+ */
+
+import { spawn, type ChildProcess } from 'node:child_process';
+import type { IPage } from '../types.js';
+import { withTimeoutMs, DEFAULT_BROWSER_CONNECT_TIMEOUT } from '../runtime.js';
+import { PKG_VERSION } from '../version.js';
+import { Page } from './page.js';
+import { getTokenFingerprint, formatBrowserConnectError, inferConnectFailureKind } from './errors.js';
+import { findMcpServerPath, buildMcpLaunchSpec, resolveCdpEndpoint } from './discover.js';
+import { extractTabIdentities, extractTabEntries, diffTabIndexes, appendLimited } from './tabs.js';
+
+const STDERR_BUFFER_LIMIT = 16 * 1024;
+const INITIAL_TABS_TIMEOUT_MS = 1500;
+const TAB_CLEANUP_TIMEOUT_MS = 2000;
+
+export type PlaywrightMCPState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
+
+// JSON-RPC helpers
+let _nextId = 1;
+export function createJsonRpcRequest(method: string, params: Record<string, unknown> = {}): { id: number; message: string } {
+  const id = _nextId++;
+  return {
+    id,
+    message: JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n',
+  };
+}
+
+/**
+ * Playwright MCP process manager.
+ */
+export class PlaywrightMCP {
+  private static _activeInsts: Set<PlaywrightMCP> = new Set();
+  private static _cleanupRegistered = false;
+
+  private static _registerGlobalCleanup() {
+    if (this._cleanupRegistered) return;
+    this._cleanupRegistered = true;
+    const cleanup = () => {
+      for (const inst of this._activeInsts) {
+        if (inst._proc && !inst._proc.killed) {
+          try { inst._proc.kill('SIGKILL'); } catch {}
+        }
+      }
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(130); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(143); });
+  }
+
+  private _proc: ChildProcess | null = null;
+  private _buffer = '';
+  private _pending = new Map<number, { resolve: (data: any) => void; reject: (error: Error) => void }>();
+  private _initialTabIdentities: string[] = [];
+  private _closingPromise: Promise<void> | null = null;
+  private _state: PlaywrightMCPState = 'idle';
+
+  private _page: Page | null = null;
+
+  get state(): PlaywrightMCPState {
+    return this._state;
+  }
+
+  private _sendRequest(method: string, params: Record<string, unknown> = {}): Promise<any> {
+    return new Promise<any>((resolve, reject) => {
+      if (!this._proc?.stdin?.writable) {
+        reject(new Error('Playwright MCP process is not writable'));
+        return;
+      }
+      const { id, message } = createJsonRpcRequest(method, params);
+      this._pending.set(id, { resolve, reject });
+      this._proc.stdin.write(message, (err) => {
+        if (!err) return;
+        this._pending.delete(id);
+        reject(err);
+      });
+    });
+  }
+
+  private _rejectPendingRequests(error: Error): void {
+    const pending = [...this._pending.values()];
+    this._pending.clear();
+    for (const waiter of pending) waiter.reject(error);
+  }
+
+  private _resetAfterFailedConnect(): void {
+    const proc = this._proc;
+    this._page = null;
+    this._proc = null;
+    this._buffer = '';
+    this._initialTabIdentities = [];
+    this._rejectPendingRequests(new Error('Playwright MCP connect failed'));
+    PlaywrightMCP._activeInsts.delete(this);
+    if (proc && !proc.killed) {
+      try { proc.kill('SIGKILL'); } catch {}
+    }
+  }
+
+  async connect(opts: { timeout?: number } = {}): Promise<IPage> {
+    if (this._state === 'connected' && this._page) return this._page;
+    if (this._state === 'connecting') throw new Error('Playwright MCP is already connecting');
+    if (this._state === 'closing') throw new Error('Playwright MCP is closing');
+    if (this._state === 'closed') throw new Error('Playwright MCP session is closed');
+
+    const mcpPath = findMcpServerPath();
+
+    PlaywrightMCP._registerGlobalCleanup();
+    PlaywrightMCP._activeInsts.add(this);
+    this._state = 'connecting';
+    const timeout = opts.timeout ?? DEFAULT_BROWSER_CONNECT_TIMEOUT;
+
+    return new Promise<Page>((resolve, reject) => {
+      const isDebug = process.env.DEBUG?.includes('opencli:mcp');
+      const debugLog = (msg: string) => isDebug && console.error(`[opencli:mcp] ${msg}`);
+      const { endpoint: cdpEndpoint, requestedCdp } = resolveCdpEndpoint();
+      const useExtension = !requestedCdp;
+      const extensionToken = process.env.PLAYWRIGHT_MCP_EXTENSION_TOKEN;
+      const tokenFingerprint = getTokenFingerprint(extensionToken);
+      let stderrBuffer = '';
+      let settled = false;
+
+      const settleError = (kind: Parameters<typeof formatBrowserConnectError>[0]['kind'], extra: { rawMessage?: string; exitCode?: number | null } = {}) => {
+        if (settled) return;
+        settled = true;
+        this._state = 'idle';
+        clearTimeout(timer);
+        this._resetAfterFailedConnect();
+        reject(formatBrowserConnectError({
+          kind,
+          timeout,
+          hasExtensionToken: !!extensionToken,
+          tokenFingerprint,
+          stderr: stderrBuffer,
+          exitCode: extra.exitCode,
+          rawMessage: extra.rawMessage,
+        }));
+      };
+
+      const settleSuccess = (pageToResolve: Page) => {
+        if (settled) return;
+        settled = true;
+        this._state = 'connected';
+        clearTimeout(timer);
+        resolve(pageToResolve);
+      };
+
+      const timer = setTimeout(() => {
+        debugLog('Connection timed out');
+        settleError(inferConnectFailureKind({
+          hasExtensionToken: !!extensionToken,
+          stderr: stderrBuffer,
+          isCdpMode: requestedCdp,
+        }));
+      }, timeout * 1000);
+
+      const launchSpec = buildMcpLaunchSpec({
+        mcpPath,
+        executablePath: process.env.OPENCLI_BROWSER_EXECUTABLE_PATH,
+        cdpEndpoint,
+      });
+      if (process.env.OPENCLI_VERBOSE) {
+        console.error(`[opencli] Mode: ${requestedCdp ? 'CDP' : useExtension ? 'extension' : 'standalone'}`);
+        if (useExtension) console.error(`[opencli] Extension token: fingerprint ${tokenFingerprint}`);
+        if (launchSpec.usedNpxFallback) {
+          console.error('[opencli] Playwright MCP not found locally; bootstrapping via npx @playwright/mcp@latest');
+        }
+      }
+      debugLog(`Spawning ${launchSpec.command} ${launchSpec.args.join(' ')}`);
+
+      this._proc = spawn(launchSpec.command, launchSpec.args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: { ...process.env },
+      });
+
+      // Increase max listeners to avoid warnings
+      this._proc.setMaxListeners(20);
+      if (this._proc.stdout) this._proc.stdout.setMaxListeners(20);
+
+      const page = new Page((method, params = {}) => this._sendRequest(method, params));
+      this._page = page;
+
+      this._proc.stdout?.on('data', (chunk: Buffer) => {
+        this._buffer += chunk.toString();
+        const lines = this._buffer.split('\n');
+        this._buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          debugLog(`RECV: ${line}`);
+          try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed?.id === 'number') {
+              const waiter = this._pending.get(parsed.id);
+              if (waiter) {
+                this._pending.delete(parsed.id);
+                waiter.resolve(parsed);
+              }
+            }
+          } catch (e) {
+            debugLog(`Parse error: ${e}`);
+          }
+        }
+      });
+
+      this._proc.stderr?.on('data', (chunk: Buffer) => {
+        const text = chunk.toString();
+        stderrBuffer = appendLimited(stderrBuffer, text, STDERR_BUFFER_LIMIT);
+        debugLog(`STDERR: ${text}`);
+      });
+      this._proc.on('error', (err) => {
+        debugLog(`Subprocess error: ${err.message}`);
+        this._rejectPendingRequests(new Error(`Playwright MCP process error: ${err.message}`));
+        settleError('process-exit', { rawMessage: err.message });
+      });
+      this._proc.on('close', (code) => {
+        debugLog(`Subprocess closed with code ${code}`);
+        this._rejectPendingRequests(new Error(`Playwright MCP process exited before response${code == null ? '' : ` (code ${code})`}`));
+        if (!settled) {
+          settleError(inferConnectFailureKind({
+            hasExtensionToken: !!extensionToken,
+            stderr: stderrBuffer,
+            exited: true,
+            isCdpMode: requestedCdp,
+          }), { exitCode: code });
+        }
+      });
+
+      // Initialize: send initialize request
+      debugLog('Waiting for initialize response...');
+      this._sendRequest('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'opencli', version: PKG_VERSION },
+      }).then((resp: any) => {
+        debugLog('Got initialize response');
+        if (resp.error) {
+          settleError(inferConnectFailureKind({
+            hasExtensionToken: !!extensionToken,
+            stderr: stderrBuffer,
+            rawMessage: `MCP init failed: ${resp.error.message}`,
+            isCdpMode: requestedCdp,
+          }), { rawMessage: resp.error.message });
+          return;
+        }
+        
+        const initializedMsg = JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n';
+        debugLog(`SEND: ${initializedMsg.trim()}`);
+        this._proc?.stdin?.write(initializedMsg);
+
+        // Use tabs as a readiness probe and for tab cleanup bookkeeping.
+        debugLog('Fetching initial tabs count...');
+        withTimeoutMs(page.tabs(), INITIAL_TABS_TIMEOUT_MS, 'Timed out fetching initial tabs').then((tabs: any) => {
+          debugLog(`Tabs response: ${typeof tabs === 'string' ? tabs : JSON.stringify(tabs)}`);
+          this._initialTabIdentities = extractTabIdentities(tabs);
+          settleSuccess(page);
+        }).catch((err: Error) => {
+          debugLog(`Tabs fetch error: ${err.message}`);
+          settleSuccess(page);
+        });
+      }).catch((err: Error) => {
+        debugLog(`Init promise rejected: ${err.message}`);
+        settleError('mcp-init', { rawMessage: err.message });
+      });
+    });
+  }
+
+
+  async close(): Promise<void> {
+    if (this._closingPromise) return this._closingPromise;
+    if (this._state === 'closed') return;
+    this._state = 'closing';
+    this._closingPromise = (async () => {
+      try {
+        // Extension mode opens bridge/session tabs that we can clean up best-effort.
+        if (this._page && this._proc && !this._proc.killed) {
+          try {
+            const tabs = await withTimeoutMs(this._page.tabs(), TAB_CLEANUP_TIMEOUT_MS, 'Timed out fetching tabs during cleanup');
+            const tabEntries = extractTabEntries(tabs);
+            const tabsToClose = diffTabIndexes(this._initialTabIdentities, tabEntries);
+            for (const index of tabsToClose) {
+              try { await this._page.closeTab(index); } catch {}
+            }
+          } catch {}
+        }
+        if (this._proc && !this._proc.killed) {
+          this._proc.kill('SIGTERM');
+          const exited = await new Promise<boolean>((res) => {
+            let done = false;
+            const finish = (value: boolean) => {
+              if (done) return;
+              done = true;
+              res(value);
+            };
+            this._proc?.once('exit', () => finish(true));
+            setTimeout(() => finish(false), 3000);
+          });
+          if (!exited && this._proc && !this._proc.killed) {
+            try { this._proc.kill('SIGKILL'); } catch {}
+          }
+        }
+      } finally {
+        this._rejectPendingRequests(new Error('Playwright MCP session closed'));
+        this._page = null;
+        this._proc = null;
+        this._state = 'closed';
+        PlaywrightMCP._activeInsts.delete(this);
+      }
+    })();
+    return this._closingPromise;
+  }
+}

src/browser/page.ts

@@ -0,0 +1,171 @@
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+
+import { formatSnapshot } from '../snapshotFormatter.js';
+import { normalizeEvaluateSource } from '../pipeline/template.js';
+import { generateInterceptorJs, generateReadInterceptedJs } from '../interceptor.js';
+import type { IPage } from '../types.js';
+import { BrowserConnectError } from '../errors.js';
+
+/**
+ * Page abstraction wrapping JSON-RPC calls to Playwright MCP.
+ */
+export class Page implements IPage {
+  constructor(private _request: (method: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>>) {}
+
+  async call(method: string, params: Record<string, unknown> = {}): Promise<any> {
+    const resp = await this._request(method, params);
+    if (resp.error) throw new Error(`page.${method}: ${(resp.error as any).message ?? JSON.stringify(resp.error)}`);
+    // Extract text content from MCP result
+    const result = resp.result as any;
+
+    if (result?.isError) {
+      const errorText = result.content?.find((c: any) => c.type === 'text')?.text || 'Unknown MCP Error';
+      throw new BrowserConnectError(
+        errorText,
+        'Please check if the browser is running or if the Playwright MCP / CDP connection is configured correctly.'
+      );
+    }
+
+    if (result?.content) {
+      const textParts = result.content.filter((c: any) => c.type === 'text');
+      if (textParts.length >= 1) {
+        let text = textParts[textParts.length - 1].text; // Usually the main output is in the last text block
+
+        // Some versions of the MCP return error text without the `isError` boolean flag
+        if (typeof text === 'string' && text.trim().startsWith('### Error')) {
+            throw new BrowserConnectError(
+              text.trim(),
+              'Please check if the browser is running or if the Playwright MCP / CDP connection is configured correctly.'
+            );
+        }
+
+        // MCP browser_evaluate returns: "[JSON]\n### Ran Playwright code\n```js\n...\n```"
+        // Strip the "### Ran Playwright code" suffix to get clean JSON
+        const codeMarker = text.indexOf('### Ran Playwright code');
+        if (codeMarker !== -1) {
+          text = text.slice(0, codeMarker).trim();
+        }
+        // Also handle "### Result\n[JSON]" format (some MCP versions)
+        const resultMarker = text.indexOf('### Result\n');
+        if (resultMarker !== -1) {
+          text = text.slice(resultMarker + '### Result\n'.length).trim();
+        }
+        try { return JSON.parse(text); } catch { return text; }
+      }
+    }
+    return result;
+  }
+
+  // --- High-level methods ---
+
+  async goto(url: string): Promise<void> {
+    await this.call('tools/call', { name: 'browser_navigate', arguments: { url } });
+  }
+
+  async evaluate(js: string): Promise<any> {
+    // Normalize IIFE format to function format expected by MCP browser_evaluate
+    const normalized = normalizeEvaluateSource(js);
+    return this.call('tools/call', { name: 'browser_evaluate', arguments: { function: normalized } });
+  }
+
+  async snapshot(opts: { interactive?: boolean; compact?: boolean; maxDepth?: number; raw?: boolean } = {}): Promise<any> {
+    const raw = await this.call('tools/call', { name: 'browser_snapshot', arguments: {} });
+    if (opts.raw) return raw;
+    if (typeof raw === 'string') return formatSnapshot(raw, opts);
+    return raw;
+  }
+
+  async click(ref: string): Promise<void> {
+    await this.call('tools/call', { name: 'browser_click', arguments: { element: 'click target', ref } });
+  }
+
+  async typeText(ref: string, text: string): Promise<void> {
+    await this.call('tools/call', { name: 'browser_type', arguments: { element: 'type target', ref, text } });
+  }
+
+  async pressKey(key: string): Promise<void> {
+    await this.call('tools/call', { name: 'browser_press_key', arguments: { key } });
+  }
+
+  async wait(options: number | { text?: string; time?: number; timeout?: number }): Promise<void> {
+    if (typeof options === 'number') {
+      await this.call('tools/call', { name: 'browser_wait_for', arguments: { time: options } });
+    } else {
+      // Pass directly to native wait_for, which supports natively awaiting text strings without heavy DOM polling
+      await this.call('tools/call', { name: 'browser_wait_for', arguments: options });
+    }
+  }
+
+  async tabs(): Promise<any> {
+    return this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'list' } });
+  }
+
+  async closeTab(index?: number): Promise<void> {
+    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'close', ...(index !== undefined ? { index } : {}) } });
+  }
+
+  async newTab(): Promise<void> {
+    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'new' } });
+  }
+
+  async selectTab(index: number): Promise<void> {
+    await this.call('tools/call', { name: 'browser_tabs', arguments: { action: 'select', index } });
+  }
+
+  async networkRequests(includeStatic: boolean = false): Promise<any> {
+    return this.call('tools/call', { name: 'browser_network_requests', arguments: { includeStatic } });
+  }
+
+  async consoleMessages(level: string = 'info'): Promise<any> {
+    return this.call('tools/call', { name: 'browser_console_messages', arguments: { level } });
+  }
+
+  async scroll(direction: string = 'down', _amount: number = 500): Promise<void> {
+    await this.call('tools/call', { name: 'browser_press_key', arguments: { key: direction === 'down' ? 'PageDown' : 'PageUp' } });
+  }
+
+  async autoScroll(options: { times?: number; delayMs?: number } = {}): Promise<void> {
+    const times = options.times ?? 3;
+    const delayMs = options.delayMs ?? 2000;
+    const js = `
+      async () => {
+        const maxTimes = ${times};
+        const maxWaitMs = ${delayMs};
+        for (let i = 0; i < maxTimes; i++) {
+          const lastHeight = document.body.scrollHeight;
+          window.scrollTo(0, lastHeight);
+          await new Promise(resolve => {
+            let timeoutId;
+            const observer = new MutationObserver(() => {
+              if (document.body.scrollHeight > lastHeight) {
+                clearTimeout(timeoutId);
+                observer.disconnect();
+                setTimeout(resolve, 100); // Small debounce for rendering
+              }
+            });
+            observer.observe(document.body, { childList: true, subtree: true });
+            timeoutId = setTimeout(() => {
+              observer.disconnect();
+              resolve(null);
+            }, maxWaitMs);
+          });
+        }
+      }
+    `;
+    await this.evaluate(js);
+  }
+
+  async installInterceptor(pattern: string): Promise<void> {
+    await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {
+      arrayName: '__opencli_xhr',
+      patchGuard: '__opencli_interceptor_patched',
+    }));
+  }
+
+  async getInterceptedRequests(): Promise<any[]> {
+    const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
+    return result || [];
+  }
+}

src/browser/tabs.ts

@@ -0,0 +1,76 @@
+/**
+ * Browser tab management helpers: extract, diff, and cleanup tab state.
+ */
+
+export function extractTabEntries(raw: unknown): Array<{ index: number; identity: string }> {
+  if (Array.isArray(raw)) {
+    return raw.map((tab: Record<string, unknown>, index: number) => ({
+      index,
+      identity: [
+        tab?.id ?? '',
+        tab?.url ?? '',
+        tab?.title ?? '',
+        tab?.name ?? '',
+      ].join('|'),
+    }));
+  }
+
+  if (typeof raw === 'string') {
+    return raw
+      .split('\n')
+      .map(line => line.trim())
+      .filter(Boolean)
+      .map(line => {
+        // Match actual Playwright MCP format: "- 0: (current) [title](url)"  or  "- 1: [title](url)"
+        const mcpMatch = line.match(/^-\s+(\d+):\s*(.*)$/);
+        if (mcpMatch) {
+          return {
+            index: parseInt(mcpMatch[1], 10),
+            identity: mcpMatch[2].trim() || `tab-${mcpMatch[1]}`,
+          };
+        }
+        // Legacy format: "Tab 0 ..."
+        const legacyMatch = line.match(/Tab\s+(\d+)\s*(.*)$/);
+        if (legacyMatch) {
+          return {
+            index: parseInt(legacyMatch[1], 10),
+            identity: legacyMatch[2].trim() || `tab-${legacyMatch[1]}`,
+          };
+        }
+        return null;
+      })
+      .filter((entry): entry is { index: number; identity: string } => entry !== null);
+  }
+
+  return [];
+}
+
+export function extractTabIdentities(raw: unknown): string[] {
+  return extractTabEntries(raw).map(tab => tab.identity);
+}
+
+export function diffTabIndexes(initialIdentities: string[], currentTabs: Array<{ index: number; identity: string }>): number[] {
+  if (initialIdentities.length === 0 || currentTabs.length === 0) return [];
+  const remaining = new Map<string, number>();
+  for (const identity of initialIdentities) {
+    remaining.set(identity, (remaining.get(identity) ?? 0) + 1);
+  }
+
+  const tabsToClose: number[] = [];
+  for (const tab of currentTabs) {
+    const count = remaining.get(tab.identity) ?? 0;
+    if (count > 0) {
+      remaining.set(tab.identity, count - 1);
+      continue;
+    }
+    tabsToClose.push(tab.index);
+  }
+
+  return tabsToClose.sort((a, b) => b - a);
+}
+
+export function appendLimited(current: string, chunk: string, limit: number): string {
+  const next = current + chunk;
+  if (next.length <= limit) return next;
+  return next.slice(-limit);
+}

src/build-manifest.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest';
+import { parseTsArgsBlock } from './build-manifest.js';
+
+describe('parseTsArgsBlock', () => {
+  it('keeps args with nested choices arrays', () => {
+    const args = parseTsArgsBlock(`
+      {
+        name: 'period',
+        type: 'string',
+        default: 'seven',
+        help: 'Stats period: seven or thirty',
+        choices: ['seven', 'thirty'],
+      },
+    `);
+
+    expect(args).toEqual([
+      {
+        name: 'period',
+        type: 'string',
+        default: 'seven',
+        required: false,
+        positional: undefined,
+        help: 'Stats period: seven or thirty',
+        choices: ['seven', 'thirty'],
+      },
+    ]);
+  });
+});

src/build-manifest.ts

@@ -11,7 +11,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import yaml from 'js-yaml';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -30,6 +30,7 @@ interface ManifestEntry {
     type?: string;
     default?: any;
     required?: boolean;
+    positional?: boolean;
     help?: string;
     choices?: string[];
   }>;
@@ -42,6 +43,116 @@ interface ManifestEntry {
   modulePath?: string;
 }
 
+function extractBalancedBlock(
+  source: string,
+  startIndex: number,
+  openChar: string,
+  closeChar: string,
+): string | null {
+  let depth = 0;
+  let quote: string | null = null;
+  let escaped = false;
+
+  for (let i = startIndex; i < source.length; i++) {
+    const ch = source[i];
+
+    if (quote) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (ch === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (ch === quote) quote = null;
+      continue;
+    }
+
+    if (ch === '"' || ch === '\'' || ch === '`') {
+      quote = ch;
+      continue;
+    }
+
+    if (ch === openChar) {
+      depth++;
+    } else if (ch === closeChar) {
+      depth--;
+      if (depth === 0) {
+        return source.slice(startIndex + 1, i);
+      }
+    }
+  }
+
+  return null;
+}
+
+function extractTsArgsBlock(source: string): string | null {
+  const argsMatch = source.match(/args\s*:/);
+  if (!argsMatch || argsMatch.index === undefined) return null;
+
+  const bracketIndex = source.indexOf('[', argsMatch.index);
+  if (bracketIndex === -1) return null;
+
+  return extractBalancedBlock(source, bracketIndex, '[', ']');
+}
+
+function parseInlineChoices(body: string): string[] | undefined {
+  const choicesMatch = body.match(/choices\s*:\s*\[([^\]]*)\]/);
+  if (!choicesMatch) return undefined;
+
+  const values = choicesMatch[1]
+    .split(',')
+    .map(s => s.trim().replace(/^['"`]|['"`]$/g, ''))
+    .filter(Boolean);
+
+  return values.length > 0 ? values : undefined;
+}
+
+export function parseTsArgsBlock(argsBlock: string): ManifestEntry['args'] {
+  const args: ManifestEntry['args'] = [];
+  let cursor = 0;
+
+  while (cursor < argsBlock.length) {
+    const nameMatch = argsBlock.slice(cursor).match(/\{\s*name\s*:\s*['"`](\w+)['"`]/);
+    if (!nameMatch || nameMatch.index === undefined) break;
+
+    const objectStart = cursor + nameMatch.index;
+    const body = extractBalancedBlock(argsBlock, objectStart, '{', '}');
+    if (body == null) break;
+
+    const typeMatch = body.match(/type\s*:\s*['"`](\w+)['"`]/);
+    const defaultMatch = body.match(/default\s*:\s*([^,}]+)/);
+    const requiredMatch = body.match(/required\s*:\s*(true|false)/);
+    const helpMatch = body.match(/help\s*:\s*['"`]([^'"`]*)['"`]/);
+    const positionalMatch = body.match(/positional\s*:\s*(true|false)/);
+
+    let defaultVal: any = undefined;
+    if (defaultMatch) {
+      const raw = defaultMatch[1].trim();
+      if (raw === 'true') defaultVal = true;
+      else if (raw === 'false') defaultVal = false;
+      else if (/^\d+$/.test(raw)) defaultVal = parseInt(raw, 10);
+      else if (/^\d+\.\d+$/.test(raw)) defaultVal = parseFloat(raw);
+      else defaultVal = raw.replace(/^['"`]|['"`]$/g, '');
+    }
+
+    args.push({
+      name: nameMatch[1],
+      type: typeMatch?.[1] ?? 'str',
+      default: defaultVal,
+      required: requiredMatch?.[1] === 'true',
+      positional: positionalMatch?.[1] === 'true' || undefined,
+      help: helpMatch?.[1] ?? '',
+      choices: parseInlineChoices(body),
+    });
+
+    cursor = objectStart + body.length + 2;
+  }
+
+  return args;
+}
+
 function scanYaml(filePath: string, site: string): ManifestEntry | null {
   try {
     const raw = fs.readFileSync(filePath, 'utf-8');
@@ -128,37 +239,9 @@ function scanTs(filePath: string, site: string): ManifestEntry {
     }
 
     // Extract args array items: { name: '...', ... }
-    const argsBlockMatch = src.match(/args\s*:\s*\[([\s\S]*?)\]\s*,/);
-    if (argsBlockMatch) {
-      const argsBlock = argsBlockMatch[1];
-      const argRegex = /\{\s*name\s*:\s*['"`](\w+)['"`]([^}]*)\}/g;
-      let m;
-      while ((m = argRegex.exec(argsBlock)) !== null) {
-        const argName = m[1];
-        const body = m[2];
-        const typeMatch = body.match(/type\s*:\s*['"`](\w+)['"`]/);
-        const defaultMatch = body.match(/default\s*:\s*([^,}]+)/);
-        const requiredMatch = body.match(/required\s*:\s*(true|false)/);
-        const helpMatch = body.match(/help\s*:\s*['"`]([^'"`]*)['"`]/);
-
-        let defaultVal: any = undefined;
-        if (defaultMatch) {
-          const raw = defaultMatch[1].trim();
-          if (raw === 'true') defaultVal = true;
-          else if (raw === 'false') defaultVal = false;
-          else if (/^\d+$/.test(raw)) defaultVal = parseInt(raw, 10);
-          else if (/^\d+\.\d+$/.test(raw)) defaultVal = parseFloat(raw);
-          else defaultVal = raw.replace(/^['"`]|['"`]$/g, '');
-        }
-
-        entry.args.push({
-          name: argName,
-          type: typeMatch?.[1] ?? 'str',
-          default: defaultVal,
-          required: requiredMatch?.[1] === 'true',
-          help: helpMatch?.[1] ?? '',
-        });
-      }
+    const argsBlock = extractTsArgsBlock(src);
+    if (argsBlock) {
+      entry.args = parseTsArgsBlock(argsBlock);
     }
   } catch {
     // If parsing fails, fall back to empty metadata — module will self-register at runtime
@@ -167,32 +250,42 @@ function scanTs(filePath: string, site: string): ManifestEntry {
   return entry;
 }
 
-// Main
-const manifest: ManifestEntry[] = [];
+export function buildManifest(): ManifestEntry[] {
+  const manifest: ManifestEntry[] = [];
 
-if (fs.existsSync(CLIS_DIR)) {
-  for (const site of fs.readdirSync(CLIS_DIR)) {
-    const siteDir = path.join(CLIS_DIR, site);
-    if (!fs.statSync(siteDir).isDirectory()) continue;
-    for (const file of fs.readdirSync(siteDir)) {
-      const filePath = path.join(siteDir, file);
-      if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-        const entry = scanYaml(filePath, site);
-        if (entry) manifest.push(entry);
-      } else if (
-        (file.endsWith('.ts') && !file.endsWith('.d.ts') && file !== 'index.ts') ||
-        (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')
-      ) {
-        manifest.push(scanTs(filePath, site));
+  if (fs.existsSync(CLIS_DIR)) {
+    for (const site of fs.readdirSync(CLIS_DIR)) {
+      const siteDir = path.join(CLIS_DIR, site);
+      if (!fs.statSync(siteDir).isDirectory()) continue;
+      for (const file of fs.readdirSync(siteDir)) {
+        const filePath = path.join(siteDir, file);
+        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
+          const entry = scanYaml(filePath, site);
+          if (entry) manifest.push(entry);
+        } else if (
+          (file.endsWith('.ts') && !file.endsWith('.d.ts') && file !== 'index.ts') ||
+          (file.endsWith('.js') && !file.endsWith('.d.js') && file !== 'index.js')
+        ) {
+          manifest.push(scanTs(filePath, site));
+        }
       }
     }
   }
+
+  return manifest;
 }
 
-// Ensure output directory exists
-fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
-fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
+function main(): void {
+  const manifest = buildManifest();
+  fs.mkdirSync(path.dirname(OUTPUT), { recursive: true });
+  fs.writeFileSync(OUTPUT, JSON.stringify(manifest, null, 2));
 
-const yamlCount = manifest.filter(e => e.type === 'yaml').length;
-const tsCount = manifest.filter(e => e.type === 'ts').length;
-console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);
+  const yamlCount = manifest.filter(e => e.type === 'yaml').length;
+  const tsCount = manifest.filter(e => e.type === 'ts').length;
+  console.log(`✅ Manifest compiled: ${manifest.length} entries (${yamlCount} YAML, ${tsCount} TS) → ${OUTPUT}`);
+}
+
+const entrypoint = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;
+if (entrypoint === import.meta.url) {
+  main();
+}

src/clis/antigravity/README.md

@@ -0,0 +1,48 @@
+# Antigravity CLI Adapter
+
+🔥 **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!
+
+Turn your local Antigravity desktop application into a programmable AI node via Chrome DevTools Protocol (CDP). This allows you to compose complex LLM workflows entirely through the terminal by manipulating the actual UI natively, bypassing any API restrictions.
+
+## Prerequisites
+
+Start the Antigravity desktop app with the Chrome DevTools `remote-debugging-port` flag:
+
+\`\`\`bash
+# Start Antigravity in the background
+/Applications/Antigravity.app/Contents/MacOS/Electron \
+  --remote-debugging-port=9224
+\`\`\`
+
+*(Note: Depending on your installation, the executable might be named differently, e.g., \`Antigravity\` instead of \`Electron\`.)*
+
+Next, set the target port in your terminal session to tell OpenCLI where to connect:
+
+\`\`\`bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+\`\`\`
+
+## Available Commands
+
+### \`opencli antigravity status\`
+Check the Chromium CDP connection. Returns the current window title and active internal URL.
+
+### \`opencli antigravity send <message>\`
+Send a text prompt to the AI. Automatically locates the Lexical editor input box, types the prompt securely, and hits Enter.
+
+### \`opencli antigravity read\`
+Scrape the entire current conversation history block as pure text. Useful for feeding the context to another script.
+
+### \`opencli antigravity new\`
+Click the "New Conversation" button to instantly clear the UI state and start fresh.
+
+### \`opencli antigravity extract-code\`
+Extract any multi-line code blocks from the current conversation view. Ideal for automated script extraction (e.g. \`opencli antigravity extract-code > script.sh\`).
+
+### \`opencli antigravity model <name>\`
+Quickly target and switch the active LLM engine. Example: \`opencli antigravity model claude\` or \`opencli antigravity model gemini\`.
+
+### \`opencli antigravity watch\`
+A long-running, streaming process that continuously polls the Antigravity UI for chat updates and outputs them in real-time to standard output.

src/clis/antigravity/README.zh-CN.md

@@ -0,0 +1,51 @@
+# Antigravity CLI Adapter (探针插件)
+
+🔥 **opencli 支持 CLI 化所有 electron 应用！最强大更新来袭！** 🔥
+
+CLI all electron！现在支持把所有 electron 应用 CLI 化，从而组合出各种神奇的能力。
+如果你在使用诸如 Antigravity Ultra 等工具时觉得不够灵活或难以扩展，现在通过 OpenCLI 把他 CLI 化，轻松打破界限。
+
+现在，**AI 可以自己控制自己**！结合 cc/openclaw 就可以远程控制任何 electron 应用！无限玩法！！
+
+通过 Chrome DevTools Protocol (CDP)，将你本地运行的 Antigravity 桌面客户端转变为一个完全可编程的 AI 节点。这让你可以在命令行终端中直接操控它的 UI 界面，实现真正的“零 API 限制”本地自动化大模型工作流调度。
+
+## 开发准备
+
+首先，**请在终端启动 Antigravity 桌面版**，并附加上允许远程调试（CDP）的内核启动参数：
+
+\`\`\`bash
+# 在后台启动并驻留
+/Applications/Antigravity.app/Contents/MacOS/Electron \
+  --remote-debugging-port=9224
+\`\`\`
+
+*(注意：如果你打包的应用重命名过主构建，可能需要把 `Electron` 换成实际的可执行文件名，如 `Antigravity`)*
+
+接下来，在你想执行 CLI 命令的另一个新终端板块里，声明要连入的本地调试端口环境变量：
+
+\`\`\`bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+\`\`\`
+
+## 全部指令一览
+
+### \`opencli antigravity status\`
+快速检查当前探针与内核 CDP 的连接状态。会返回底层的当前 URL 和网页 Title。
+
+### \`opencli antigravity send <message>\`
+给 Agent 发送消息。它会自动定位到底部的 Lexical 输入框，安全地注入你的指定文本然后模拟回车发送。
+
+### \`opencli antigravity read\`
+全量抓取当前的对话面板，将所有历史聊天记录作为一整块纯文本取回。
+
+### \`opencli antigravity new\`
+模拟点击侧边栏顶部的“开启新对话”按钮，瞬间清空并重置 Agent 的上下文状态。
+
+### \`opencli antigravity extract-code\`
+从当前的 Agent 聊天记录中单独提取所有的多行代码块。非常适合自动化脚手架开发（例如直接重定向输出写入本地文件：\`opencli antigravity extract-code > script.sh\`）。
+
+### \`opencli antigravity model <name>\`
+切换大模型引擎。只需传入关键词（比如：\`opencli antigravity model claude\` 或 \`model gemini\`），它会自动帮你点开模型选择菜单并模拟点击。
+
+### \`opencli antigravity watch\`
+开启一个长连接流式监听。通过持续轮询 DOM 的变化量，它能像流式 API 一样，在终端实时向你推送 Agent 刚刚打出的那一行最新回复，直到你按 Ctrl+C 中止。

src/clis/antigravity/SKILL.md

@@ -0,0 +1,42 @@
+---
+description: How to automate Antigravity using OpenCLI
+---
+
+# Antigravity Automation Skill
+
+This skill allows AI agents to control the [Antigravity](https://github.com/chengazhen/Antigravity) desktop app (and any Electron app with CDP enabled) programmatically via OpenCLI. 
+
+## Requirements
+The target Electron application MUST be launched with the remote-debugging-port flag:
+\`\`\`bash
+/Applications/Antigravity.app/Contents/MacOS/Electron --remote-debugging-port=9224
+\`\`\`
+
+The agent must configure the endpoint environment variable locally before invoking standard commands:
+\`\`\`bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+\`\`\`
+
+## High-Level Capabilities
+1. **Send Messages (`opencli antigravity send <message>`)**: Type and send a message directly into the chat UI.
+2. **Read History (`opencli antigravity read`)**: Scrape the raw chat transcript from the main UI container.
+3. **Extract Code (`opencli antigravity extract-code`)**: Automatically isolate and extract source code text blocks from the AI's recent answers.
+4. **Switch Models (`opencli antigravity model <name>`)**: Instantly toggle the active LLM (e.g., \`gemini\`, \`claude\`).
+5. **Clear Context (`opencli antigravity new`)**: Start a fresh conversation.
+
+## Examples for Automated Workflows
+
+### Generating and Saving Code
+\`\`\`bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+opencli antigravity send "Write a python script to fetch HN top stories"
+# wait ~10-15 seconds for output to render
+opencli antigravity extract-code > hn_fetcher.py
+\`\`\`
+
+### Reading Real-time Logs
+Agents can run long-running streaming watch instances:
+\`\`\`bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+opencli antigravity watch
+\`\`\`

src/clis/antigravity/dump.ts

@@ -0,0 +1,30 @@
+import { cli, Strategy } from '../../registry.js';
+import * as fs from 'node:fs';
+
+export const dumpCommand = cli({
+  site: 'antigravity',
+  name: 'dump',
+  description: 'Dump the DOM to help AI understand the UI',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['htmlFile', 'snapFile'],
+  func: async (page) => {
+    // Extract HTML
+    const html = await page.evaluate('document.body.innerHTML');
+    fs.writeFileSync('/tmp/antigravity-dom.html', html);
+    
+    // Extract Snapshot
+    let snapFile = '';
+    try {
+      const snap = await page.snapshot({ raw: true });
+      snapFile = '/tmp/antigravity-snapshot.json';
+      fs.writeFileSync(snapFile, JSON.stringify(snap, null, 2));
+    } catch (e) {
+      snapFile = 'Failed';
+    }
+
+    return [{ htmlFile: '/tmp/antigravity-dom.html', snapFile }];
+  },
+});

src/clis/antigravity/extract-code.ts

@@ -0,0 +1,34 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const extractCodeCommand = cli({
+  site: 'antigravity',
+  name: 'extract-code',
+  description: 'Extract multi-line code blocks from the current Antigravity conversation',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['code'],
+  func: async (page) => {
+    const blocks = await page.evaluate(`
+      async () => {
+        // Find standard pre/code blocks
+        let elements = Array.from(document.querySelectorAll('pre code'));
+        
+        // Fallback to Monaco editor content inside the UI
+        if (elements.length === 0) {
+          elements = Array.from(document.querySelectorAll('.monaco-editor'));
+        }
+        
+        // Generic fallback to any code tag that spans multiple lines
+        if (elements.length === 0) {
+          elements = Array.from(document.querySelectorAll('code')).filter(c => c.innerText.includes('\\n'));
+        }
+        
+        return elements.map(el => el.innerText).filter(text => text.trim().length > 0);
+      }
+    `);
+    
+    return blocks.map((code: string) => ({ code }));
+  },
+});

src/clis/antigravity/model.ts

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const modelCommand = cli({
+  site: 'antigravity',
+  name: 'model',
+  description: 'Switch the active LLM model in Antigravity',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'name', help: 'Target model name (e.g. claude, gemini, o1)', required: true, positional: true }
+  ],
+  columns: ['Status'],
+  func: async (page, kwargs) => {
+    const targetName = kwargs.name.toLowerCase();
+    
+    await page.evaluate(`
+      async () => {
+        const targetModelName = ${JSON.stringify(targetName)};
+        
+        // 1. Locate the model selector dropdown trigger
+        const trigger = document.querySelector('div[aria-haspopup="dialog"] > div[tabindex="0"]');
+        if (!trigger) throw new Error('Could not find the model selector trigger in the UI');
+        trigger.click();
+        
+        // 2. Wait a brief moment for React to mount the Portal/Dialog
+        await new Promise(r => setTimeout(r, 200));
+        
+        // 3. Find the option spanning target text
+        const spans = Array.from(document.querySelectorAll('[role="dialog"] span'));
+        const target = spans.find(s => s.innerText.toLowerCase().includes(targetModelName));
+        if (!target) {
+          // If not found, click the trigger again to close it safely
+          trigger.click();
+          throw new Error('Model matching "' + targetModelName + '" was not found in the dropdown list.');
+        }
+        
+        // 4. Click the closest parent that handles the row action
+        const optionNode = target.closest('.cursor-pointer') || target;
+        optionNode.click();
+      }
+    `);
+    
+    await page.wait(0.5);
+    return [{ Status: `Model switched to: ${kwargs.name}` }];
+  },
+});

src/clis/antigravity/new.ts

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const newCommand = cli({
+  site: 'antigravity',
+  name: 'new',
+  description: 'Start a new conversation / clear context in Antigravity',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['status'],
+  func: async (page) => {
+    await page.evaluate(`
+      async () => {
+        const btn = document.querySelector('[data-tooltip-id="new-conversation-tooltip"]');
+        if (!btn) throw new Error('Could not find New Conversation button');
+        
+        // In case it's disabled, we must check, but we'll try to click it anyway
+        btn.click();
+      }
+    `);
+    
+    // Give it a moment to reset the UI
+    await page.wait(0.5);
+    
+    return [{ status: 'Successfully started a new conversation' }];
+  },
+});

src/clis/antigravity/read.ts

@@ -0,0 +1,36 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const readCommand = cli({
+  site: 'antigravity',
+  name: 'read',
+  description: 'Read the latest chat messages from Antigravity AI',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'last', help: 'Number of recent messages to read (not fully implemented due to generic structure, currently returns full history text or latest chunk)' }
+  ],
+  columns: ['role', 'content'],
+  func: async (page, kwargs) => {
+    // We execute a script inside Antigravity's Chromium environment to extract the text 
+    // of the entire conversation pane.
+    const rawText = await page.evaluate(`
+      async () => {
+        const container = document.getElementById('conversation');
+        if (!container) throw new Error('Could not find conversation container');
+        
+        // Extract the full visible text of the conversation
+        // In Electron/Chromium, innerText preserves basic visual line breaks nicely
+        return container.innerText;
+      }
+    `);
+    
+    // We can do simple heuristic parsing based on typical visual markers if needed.
+    // For now, we return the entire text blob, or just the last 2000 characters if it's too long.
+    const cleanText = String(rawText).trim();
+    return [{ 
+      role: 'history', 
+      content: cleanText 
+    }];
+  },
+});

src/clis/antigravity/send.ts

@@ -0,0 +1,40 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const sendCommand = cli({
+  site: 'antigravity',
+  name: 'send',
+  description: 'Send a message to Antigravity AI via the internal Lexical editor',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'message', help: 'The message text to send', required: true, positional: true }
+  ],
+  columns: ['Status', 'Message'],
+  func: async (page, kwargs) => {
+    const text = kwargs.message;
+
+    // We use evaluate to focus and insert text because Lexical editors maintain
+    // absolute control over their DOM and don't respond to raw node.textContent.
+    // document.execCommand simulates a native paste/typing action perfectly.
+    await page.evaluate(`
+      async () => {
+        const container = document.getElementById('antigravity.agentSidePanelInputBox');
+        if (!container) throw new Error('Could not find antigravity.agentSidePanelInputBox');
+        const editor = container.querySelector('[data-lexical-editor="true"]');
+        if (!editor) throw new Error('Could not find Antigravity input box');
+        
+        editor.focus();
+        document.execCommand('insertText', false, ${JSON.stringify(text)});
+      }
+    `);
+    
+    // Wait for the React/Lexical state to flush the new input
+    await page.wait(0.5);
+    
+    // Press Enter to submit the message
+    await page.pressKey('Enter');
+    
+    return [{ Status: 'Sent successfully', Message: text }];
+  },
+});

src/clis/antigravity/status.ts

@@ -0,0 +1,19 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const statusCommand = cli({
+  site: 'antigravity',
+  name: 'status',
+  description: 'Check Antigravity CDP connection and get current page state',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['status', 'url', 'title'],
+  func: async (page) => {
+    return {
+      status: 'Connected',
+      url: await page.evaluate('window.location.href'),
+      title: await page.evaluate('document.title'),
+    };
+  },
+});

src/clis/antigravity/watch.ts

@@ -0,0 +1,45 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const watchCommand = cli({
+  site: 'antigravity',
+  name: 'watch',
+  description: 'Stream new chat messages from Antigravity in real-time',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  timeoutSeconds: 86400, // Run for up to 24 hours
+  columns: [], // We use direct stdout streaming
+  func: async (page) => {
+    console.log('Watching Antigravity chat... (Press Ctrl+C to stop)');
+    
+    let lastLength = 0;
+    
+    // Loop until process gets killed
+    while (true) {
+      const text = await page.evaluate(`
+        async () => {
+          const container = document.getElementById('conversation');
+          return container ? container.innerText : '';
+        }
+      `);
+      
+      const currentLength = text.length;
+      if (currentLength > lastLength) {
+        // Delta mode
+        const newSegment = text.substring(lastLength);
+        if (newSegment.trim().length > 0) {
+          process.stdout.write(newSegment);
+        }
+        lastLength = currentLength;
+      } else if (currentLength < lastLength) {
+        // The conversation was cleared or updated significantly
+        lastLength = currentLength;
+        console.log('\\n--- Conversation Cleared/Changed ---\\n');
+        process.stdout.write(text);
+      }
+      
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  },
+});

src/clis/barchart/flow.ts

@@ -0,0 +1,120 @@
+/**
+ * Barchart unusual options activity (options flow).
+ * Shows high volume/OI ratio trades that may indicate institutional activity.
+ * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'barchart',
+  name: 'flow',
+  description: 'Barchart unusual options activity / options flow',
+  domain: 'www.barchart.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'type', type: 'str', default: 'all', help: 'Filter: all, call, or put', choices: ['all', 'call', 'put'] },
+    { name: 'limit', type: 'int', default: 20, help: 'Number of results' },
+  ],
+  columns: [
+    'symbol', 'type', 'strike', 'expiration', 'last',
+    'volume', 'openInterest', 'volOiRatio', 'iv',
+  ],
+  func: async (page, kwargs) => {
+    const optionType = kwargs.type || 'all';
+    const limit = kwargs.limit ?? 20;
+
+    await page.goto('https://www.barchart.com/options/unusual-activity/stocks');
+    await page.wait(5);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const limit = ${limit};
+        const typeFilter = '${optionType}'.toLowerCase();
+
+        // Wait for CSRF token to appear (Angular may inject it after initial render)
+        let csrf = '';
+        for (let i = 0; i < 10; i++) {
+          csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+          if (csrf) break;
+          await new Promise(r => setTimeout(r, 500));
+        }
+        if (!csrf) return { error: 'no-csrf' };
+
+        const headers = { 'X-CSRF-TOKEN': csrf };
+        const fields = [
+          'baseSymbol','strikePrice','expirationDate','optionType',
+          'lastPrice','volume','openInterest','volumeOpenInterestRatio','volatility',
+        ].join(',');
+
+        // Fetch extra rows when filtering by type since server-side filter doesn't work
+        const fetchLimit = typeFilter !== 'all' ? limit * 3 : limit;
+
+        // Try unusual_activity first, fall back to mostActive (unusual_activity is
+        // empty outside market hours)
+        const lists = [
+          'options.unusual_activity.stocks.us',
+          'options.mostActive.us',
+        ];
+
+        for (const list of lists) {
+          try {
+            const url = '/proxies/core-api/v1/options/get?list=' + list
+              + '&fields=' + fields
+              + '&orderBy=volumeOpenInterestRatio&orderDir=desc'
+              + '&raw=1&limit=' + fetchLimit;
+
+            const resp = await fetch(url, { credentials: 'include', headers });
+            if (!resp.ok) continue;
+            const d = await resp.json();
+            let items = d?.data || [];
+            if (items.length === 0) continue;
+
+            // Apply client-side type filter
+            if (typeFilter !== 'all') {
+              items = items.filter(i => {
+                const t = ((i.raw || i).optionType || '').toLowerCase();
+                return t === typeFilter;
+              });
+            }
+            return items.slice(0, limit).map(i => {
+              const r = i.raw || i;
+              return {
+                symbol: r.baseSymbol || r.symbol,
+                type: r.optionType,
+                strike: r.strikePrice,
+                expiration: r.expirationDate,
+                last: r.lastPrice,
+                volume: r.volume,
+                openInterest: r.openInterest,
+                volOiRatio: r.volumeOpenInterestRatio,
+                iv: r.volatility,
+              };
+            });
+          } catch(e) {}
+        }
+
+        return [];
+      })()
+    `);
+
+    if (!data) return [];
+
+    if (data.error === 'no-csrf') {
+      throw new Error('Could not extract CSRF token from barchart.com. Make sure you are logged in.');
+    }
+
+    if (!Array.isArray(data)) return [];
+
+    return data.slice(0, limit).map(r => ({
+      symbol: r.symbol || '',
+      type: r.type || '',
+      strike: r.strike,
+      expiration: r.expiration ?? null,
+      last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
+      volume: r.volume,
+      openInterest: r.openInterest,
+      volOiRatio: r.volOiRatio != null ? Number(Number(r.volOiRatio).toFixed(2)) : null,
+      iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
+    }));
+  },
+});

src/clis/barchart/greeks.ts

@@ -0,0 +1,123 @@
+/**
+ * Barchart options greeks overview — IV, delta, gamma, theta, vega, rho
+ * for near-the-money options on a given symbol.
+ * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'barchart',
+  name: 'greeks',
+  description: 'Barchart options greeks overview (IV, delta, gamma, theta, vega)',
+  domain: 'www.barchart.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'symbol', required: true, help: 'Stock ticker (e.g. AAPL)' },
+    { name: 'expiration', type: 'str', help: 'Expiration date (YYYY-MM-DD). Defaults to the nearest available expiration.' },
+    { name: 'limit', type: 'int', default: 10, help: 'Number of near-the-money strikes per type' },
+  ],
+  columns: [
+    'type', 'strike', 'last', 'iv', 'delta', 'gamma', 'theta', 'vega', 'rho',
+    'volume', 'openInterest', 'expiration',
+  ],
+  func: async (page, kwargs) => {
+    const symbol = kwargs.symbol.toUpperCase().trim();
+    const expiration = kwargs.expiration ?? '';
+    const limit = kwargs.limit ?? 10;
+
+    await page.goto(`https://www.barchart.com/stocks/quotes/${encodeURIComponent(symbol)}/options`);
+    await page.wait(4);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const sym = '${symbol}';
+        const expDate = '${expiration}';
+        const limit = ${limit};
+        const csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+        const headers = { 'X-CSRF-TOKEN': csrf };
+
+        try {
+          const fields = [
+            'strikePrice','lastPrice','volume','openInterest',
+            'volatility','delta','gamma','theta','vega','rho',
+            'expirationDate','optionType','percentFromLast',
+          ].join(',');
+
+          let url = '/proxies/core-api/v1/options/chain?symbol=' + encodeURIComponent(sym)
+            + '&fields=' + fields + '&raw=1';
+          if (expDate) url += '&expirationDate=' + encodeURIComponent(expDate);
+          const resp = await fetch(url, { credentials: 'include', headers });
+          if (resp.ok) {
+            const d = await resp.json();
+            let items = d?.data || [];
+
+            if (!expDate) {
+              const expirations = items
+                .map(i => (i.raw || i).expirationDate || null)
+                .filter(Boolean)
+                .sort((a, b) => {
+                  const aTime = Date.parse(a);
+                  const bTime = Date.parse(b);
+                  if (Number.isNaN(aTime) && Number.isNaN(bTime)) return 0;
+                  if (Number.isNaN(aTime)) return 1;
+                  if (Number.isNaN(bTime)) return -1;
+                  return aTime - bTime;
+                });
+              const nearestExpiration = expirations[0];
+              if (nearestExpiration) {
+                items = items.filter(i => ((i.raw || i).expirationDate || null) === nearestExpiration);
+              }
+            }
+
+            // Separate calls and puts, sort by distance from current price
+            const calls = items
+              .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'call')
+              .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
+              .slice(0, limit);
+            const puts = items
+              .filter(i => ((i.raw || i).optionType || '').toLowerCase() === 'put')
+              .sort((a, b) => Math.abs((a.raw || a).percentFromLast || 999) - Math.abs((b.raw || b).percentFromLast || 999))
+              .slice(0, limit);
+
+            return [...calls, ...puts].map(i => {
+              const r = i.raw || i;
+              return {
+                type: r.optionType,
+                strike: r.strikePrice,
+                last: r.lastPrice,
+                iv: r.volatility,
+                delta: r.delta,
+                gamma: r.gamma,
+                theta: r.theta,
+                vega: r.vega,
+                rho: r.rho,
+                volume: r.volume,
+                openInterest: r.openInterest,
+                expiration: r.expirationDate,
+              };
+            });
+          }
+        } catch(e) {}
+
+        return [];
+      })()
+    `);
+
+    if (!data || !Array.isArray(data)) return [];
+
+    return data.map(r => ({
+      type: r.type || '',
+      strike: r.strike,
+      last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
+      iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
+      delta: r.delta != null ? Number(Number(r.delta).toFixed(4)) : null,
+      gamma: r.gamma != null ? Number(Number(r.gamma).toFixed(4)) : null,
+      theta: r.theta != null ? Number(Number(r.theta).toFixed(4)) : null,
+      vega: r.vega != null ? Number(Number(r.vega).toFixed(4)) : null,
+      rho: r.rho != null ? Number(Number(r.rho).toFixed(4)) : null,
+      volume: r.volume,
+      openInterest: r.openInterest,
+      expiration: r.expiration ?? null,
+    }));
+  },
+});

src/clis/barchart/options.ts

@@ -0,0 +1,110 @@
+/**
+ * Barchart options chain — strike, bid/ask, volume, OI, greeks, IV.
+ * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'barchart',
+  name: 'options',
+  description: 'Barchart options chain with greeks, IV, volume, and open interest',
+  domain: 'www.barchart.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'symbol', required: true, help: 'Stock ticker (e.g. AAPL)' },
+    { name: 'type', type: 'str', default: 'Call', help: 'Option type: Call or Put', choices: ['Call', 'Put'] },
+    { name: 'limit', type: 'int', default: 20, help: 'Max number of strikes to return' },
+  ],
+  columns: [
+    'strike', 'bid', 'ask', 'last', 'change', 'volume', 'openInterest',
+    'iv', 'delta', 'gamma', 'theta', 'vega', 'expiration',
+  ],
+  func: async (page, kwargs) => {
+    const symbol = kwargs.symbol.toUpperCase().trim();
+    const optType = kwargs.type || 'Call';
+    const limit = kwargs.limit ?? 20;
+
+    await page.goto(`https://www.barchart.com/stocks/quotes/${encodeURIComponent(symbol)}/options`);
+    await page.wait(4);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const sym = '${symbol}';
+        const type = '${optType}';
+        const limit = ${limit};
+        const csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+        const headers = { 'X-CSRF-TOKEN': csrf };
+
+        // API: options chain with greeks
+        try {
+          const fields = [
+            'strikePrice','bidPrice','askPrice','lastPrice','priceChange',
+            'volume','openInterest','volatility',
+            'delta','gamma','theta','vega',
+            'expirationDate','optionType','percentFromLast',
+          ].join(',');
+
+          const url = '/proxies/core-api/v1/options/chain?symbol=' + encodeURIComponent(sym)
+            + '&fields=' + fields + '&raw=1';
+          const resp = await fetch(url, { credentials: 'include', headers });
+          if (resp.ok) {
+            const d = await resp.json();
+            let items = d?.data || [];
+
+            // Filter by type
+            items = items.filter(i => {
+              const t = (i.raw || i).optionType || '';
+              return t.toLowerCase() === type.toLowerCase();
+            });
+
+            // Sort by closeness to current price
+            items.sort((a, b) => {
+              const aD = Math.abs((a.raw || a).percentFromLast || 999);
+              const bD = Math.abs((b.raw || b).percentFromLast || 999);
+              return aD - bD;
+            });
+
+            return items.slice(0, limit).map(i => {
+              const r = i.raw || i;
+              return {
+                strike: r.strikePrice,
+                bid: r.bidPrice,
+                ask: r.askPrice,
+                last: r.lastPrice,
+                change: r.priceChange,
+                volume: r.volume,
+                openInterest: r.openInterest,
+                iv: r.volatility,
+                delta: r.delta,
+                gamma: r.gamma,
+                theta: r.theta,
+                vega: r.vega,
+                expiration: r.expirationDate,
+              };
+            });
+          }
+        } catch(e) {}
+
+        return [];
+      })()
+    `);
+
+    if (!data || !Array.isArray(data)) return [];
+
+    return data.map(r => ({
+      strike: r.strike,
+      bid: r.bid != null ? Number(Number(r.bid).toFixed(2)) : null,
+      ask: r.ask != null ? Number(Number(r.ask).toFixed(2)) : null,
+      last: r.last != null ? Number(Number(r.last).toFixed(2)) : null,
+      change: r.change != null ? Number(Number(r.change).toFixed(2)) : null,
+      volume: r.volume,
+      openInterest: r.openInterest,
+      iv: r.iv != null ? Number(Number(r.iv).toFixed(2)) + '%' : null,
+      delta: r.delta != null ? Number(Number(r.delta).toFixed(4)) : null,
+      gamma: r.gamma != null ? Number(Number(r.gamma).toFixed(4)) : null,
+      theta: r.theta != null ? Number(Number(r.theta).toFixed(4)) : null,
+      vega: r.vega != null ? Number(Number(r.vega).toFixed(4)) : null,
+      expiration: r.expiration ?? null,
+    }));
+  },
+});

src/clis/barchart/quote.ts

@@ -0,0 +1,137 @@
+/**
+ * Barchart stock quote — price, volume, market cap, P/E, EPS, and key metrics.
+ * Auth: CSRF token from <meta name="csrf-token"> + session cookies.
+ */
+import { cli, Strategy } from '../../registry.js';
+
+cli({
+  site: 'barchart',
+  name: 'quote',
+  description: 'Barchart stock quote with price, volume, and key metrics',
+  domain: 'www.barchart.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'symbol', required: true, help: 'Stock ticker (e.g. AAPL, MSFT, TSLA)' },
+  ],
+  columns: [
+    'symbol', 'name', 'price', 'change', 'changePct',
+    'open', 'high', 'low', 'prevClose', 'volume',
+    'avgVolume', 'marketCap', 'peRatio', 'eps',
+  ],
+  func: async (page, kwargs) => {
+    const symbol = kwargs.symbol.toUpperCase().trim();
+    await page.goto(`https://www.barchart.com/stocks/quotes/${encodeURIComponent(symbol)}/overview`);
+    await page.wait(4);
+
+    const data = await page.evaluate(`
+      (async () => {
+        const sym = '${symbol}';
+        const csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+
+        // Strategy 1: internal proxy API with CSRF token
+        try {
+          const fields = [
+            'symbol','symbolName','lastPrice','priceChange','percentChange',
+            'highPrice','lowPrice','openPrice','previousPrice','volume','averageVolume',
+            'marketCap','peRatio','earningsPerShare','tradeTime',
+          ].join(',');
+          const url = '/proxies/core-api/v1/quotes/get?symbol=' + encodeURIComponent(sym) + '&fields=' + fields;
+          const resp = await fetch(url, {
+            credentials: 'include',
+            headers: { 'X-CSRF-TOKEN': csrf },
+          });
+          if (resp.ok) {
+            const d = await resp.json();
+            const row = d?.data?.[0] || null;
+            if (row) {
+              return { source: 'api', row };
+            }
+          }
+        } catch(e) {}
+
+        // Strategy 2: parse from DOM
+        try {
+          const priceEl = document.querySelector('span.last-change');
+          const price = priceEl ? priceEl.textContent.trim() : null;
+
+          // Change values are sibling spans inside .pricechangerow > .last-change
+          const changeParent = priceEl?.parentElement;
+          const changeSpans = changeParent ? changeParent.querySelectorAll('span') : [];
+          let change = null;
+          let changePct = null;
+          for (const s of changeSpans) {
+            const t = s.textContent.trim();
+            if (s === priceEl) continue;
+            if (t.includes('%')) changePct = t.replace(/[()]/g, '');
+            else if (t.match(/^[+-]?[\\d.]+$/)) change = t;
+          }
+
+          // Financial data rows
+          const rows = document.querySelectorAll('.financial-data-row');
+          const fdata = {};
+          for (const row of rows) {
+            const spans = row.querySelectorAll('span');
+            if (spans.length >= 2) {
+              const label = spans[0].textContent.trim();
+              const valSpan = row.querySelector('span.right span:not(.ng-hide)');
+              fdata[label] = valSpan ? valSpan.textContent.trim() : '';
+            }
+          }
+
+          // Day high/low from row chart
+          const dayLow = document.querySelector('.bc-quote-row-chart .small-6:first-child .inline:not(.ng-hide)');
+          const dayHigh = document.querySelector('.bc-quote-row-chart .text-right .inline:not(.ng-hide)');
+          const openEl = document.querySelector('.mark span');
+          const openText = openEl ? openEl.textContent.trim().replace('Open ', '') : null;
+
+          const name = document.querySelector('h1 span.symbol');
+
+          return {
+            source: 'dom',
+            row: {
+              symbol: sym,
+              symbolName: name ? name.textContent.trim() : sym,
+              lastPrice: price,
+              priceChange: change,
+              percentChange: changePct,
+              open: openText,
+              highPrice: dayHigh ? dayHigh.textContent.trim() : null,
+              lowPrice: dayLow ? dayLow.textContent.trim() : null,
+              previousClose: fdata['Previous Close'] || null,
+              volume: fdata['Volume'] || null,
+              averageVolume: fdata['Average Volume'] || null,
+              marketCap: null,
+              peRatio: null,
+              earningsPerShare: null,
+            }
+          };
+        } catch(e) {
+          return { error: 'Could not fetch quote for ' + sym + ': ' + e.message };
+        }
+      })()
+    `);
+
+    if (!data || data.error) return [];
+
+    const r = data.row || {};
+    // API returns formatted strings like "+1.41" and "+0.56%"; use raw if available
+    const raw = r.raw || {};
+
+    return [{
+      symbol: r.symbol || symbol,
+      name: r.symbolName || r.name || symbol,
+      price: r.lastPrice ?? null,
+      change: r.priceChange ?? null,
+      changePct: r.percentChange ?? null,
+      open: r.openPrice ?? r.open ?? null,
+      high: r.highPrice ?? null,
+      low: r.lowPrice ?? null,
+      prevClose: r.previousPrice ?? r.previousClose ?? null,
+      volume: r.volume ?? null,
+      avgVolume: r.averageVolume ?? null,
+      marketCap: r.marketCap ?? null,
+      peRatio: r.peRatio ?? null,
+      eps: r.earningsPerShare ?? null,
+    }];
+  },
+});

src/clis/bilibili/download.ts

@@ -0,0 +1,161 @@
+/**
+ * Bilibili download — download videos using yt-dlp.
+ *
+ * Usage:
+ *   opencli bilibili download --bvid BV1xxx --output ./bilibili
+ *
+ * Requirements:
+ *   - yt-dlp must be installed: pip install yt-dlp
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { cli, Strategy } from '../../registry.js';
+import {
+  ytdlpDownload,
+  checkYtdlp,
+  sanitizeFilename,
+  getTempDir,
+  exportCookiesToNetscape,
+} from '../../download/index.js';
+import { DownloadProgressTracker, formatBytes } from '../../download/progress.js';
+
+cli({
+  site: 'bilibili',
+  name: 'download',
+  description: '下载B站视频（需要 yt-dlp）',
+  domain: 'www.bilibili.com',
+  strategy: Strategy.COOKIE,
+  args: [
+    { name: 'bvid', required: true, help: 'Video BV ID (e.g., BV1xxx)' },
+    { name: 'output', default: './bilibili-downloads', help: 'Output directory' },
+    { name: 'quality', default: 'best', help: 'Video quality (best, 1080p, 720p, 480p)' },
+  ],
+  columns: ['bvid', 'title', 'status', 'size'],
+  func: async (page, kwargs) => {
+    const bvid = kwargs.bvid;
+    const output = kwargs.output;
+    const quality = kwargs.quality;
+
+    // Check yt-dlp availability
+    if (!checkYtdlp()) {
+      return [{
+        bvid,
+        title: '-',
+        status: 'failed',
+        size: 'yt-dlp not installed. Run: pip install yt-dlp',
+      }];
+    }
+
+    // Navigate to video page to get title and cookies
+    await page.goto(`https://www.bilibili.com/video/${bvid}`);
+    await page.wait(3);
+
+    // Extract video info
+    const data = await page.evaluate(`
+      (() => {
+        const title = document.querySelector('h1.video-title, .video-title')?.textContent?.trim() || 'video';
+        const author = document.querySelector('.up-name, .username')?.textContent?.trim() || 'unknown';
+        return { title, author };
+      })()
+    `);
+
+    const title = sanitizeFilename(data?.title || 'video');
+
+    // Extract cookies for authenticated downloads
+    const cookieString = await page.evaluate(`(() => document.cookie)()`);
+
+    // Create output directory
+    fs.mkdirSync(output, { recursive: true });
+
+    // Export cookies to Netscape format for yt-dlp
+    let cookiesFile: string | undefined;
+    if (typeof cookieString === 'string' && cookieString) {
+      const tempDir = getTempDir();
+      fs.mkdirSync(tempDir, { recursive: true });
+      cookiesFile = path.join(tempDir, `bilibili_cookies_${Date.now()}.txt`);
+
+      const cookies = cookieString.split(';').map((c) => {
+        const [name, ...rest] = c.trim().split('=');
+        return {
+          name: name || '',
+          value: rest.join('=') || '',
+          domain: '.bilibili.com',
+          path: '/',
+          secure: true,
+          httpOnly: false,
+        };
+      }).filter((c) => c.name);
+
+      exportCookiesToNetscape(cookies, cookiesFile);
+    }
+
+    // Build yt-dlp format string based on quality
+    let format = 'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]/best';
+    if (quality === '1080p') {
+      format = 'bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/best[height<=1080]';
+    } else if (quality === '720p') {
+      format = 'bestvideo[height<=720][ext=mp4]+bestaudio[ext=m4a]/best[height<=720]';
+    } else if (quality === '480p') {
+      format = 'bestvideo[height<=480][ext=mp4]+bestaudio[ext=m4a]/best[height<=480]';
+    }
+
+    const destPath = path.join(output, `${bvid}_${title}.mp4`);
+
+    const tracker = new DownloadProgressTracker(1, true);
+    const progressBar = tracker.onFileStart(`${bvid}.mp4`, 0);
+
+    try {
+      const result = await ytdlpDownload(
+        `https://www.bilibili.com/video/${bvid}`,
+        destPath,
+        {
+          cookiesFile,
+          format,
+          extraArgs: [
+            '--merge-output-format', 'mp4',
+            '--embed-thumbnail',
+          ],
+          onProgress: (percent) => {
+            if (progressBar) progressBar.update(percent, 100);
+          },
+        },
+      );
+
+      if (progressBar) {
+        progressBar.complete(result.success, result.success ? formatBytes(result.size) : undefined);
+      }
+
+      tracker.onFileComplete(result.success);
+      tracker.finish();
+
+      // Cleanup cookies file
+      if (cookiesFile && fs.existsSync(cookiesFile)) {
+        fs.unlinkSync(cookiesFile);
+      }
+
+      return [{
+        bvid,
+        title: data?.title || 'video',
+        status: result.success ? 'success' : 'failed',
+        size: result.success ? formatBytes(result.size) : (result.error || 'unknown error'),
+      }];
+    } catch (err: any) {
+      if (progressBar) progressBar.fail(err.message);
+      tracker.onFileComplete(false);
+      tracker.finish();
+
+      // Cleanup cookies file
+      if (cookiesFile && fs.existsSync(cookiesFile)) {
+        fs.unlinkSync(cookiesFile);
+      }
+
+      return [{
+        bvid,
+        title: data?.title || 'video',
+        status: 'failed',
+        size: err.message,
+      }];
+    }
+  },
+});

src/clis/boss/detail.ts

@@ -0,0 +1,115 @@
+/**
+ * BOSS直聘 job detail — fetch full job posting details via browser cookie API.
+ *
+ * Uses securityId from search results to call the detail API.
+ * Returns: job description, skills, welfare, boss info, company info, address.
+ */
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+cli({
+  site: 'boss',
+  name: 'detail',
+  description: 'BOSS直聘查看职位详情',
+  domain: 'www.zhipin.com',
+  strategy: Strategy.COOKIE,
+
+  browser: true,
+  args: [
+    { name: 'security_id', required: true, help: 'Security ID from search results (securityId field)' },
+  ],
+  columns: [
+    'name', 'salary', 'experience', 'degree', 'city', 'district',
+    'description', 'skills', 'welfare',
+    'boss_name', 'boss_title', 'active_time',
+    'company', 'industry', 'scale', 'stage',
+    'address', 'url',
+  ],
+  func: async (page: IPage | null, kwargs) => {
+    if (!page) throw new Error('Browser page required');
+
+    const securityId = kwargs.security_id;
+
+    // Navigate to zhipin.com first to establish cookie context (referrer + cookies)
+    await page.goto('https://www.zhipin.com/web/geek/job');
+    await page.wait({ time: 1 });
+
+    const targetUrl = `https://www.zhipin.com/wapi/zpgeek/job/detail.json?securityId=${encodeURIComponent(securityId)}`;
+
+    if (process.env.OPENCLI_VERBOSE || process.env.DEBUG?.includes('opencli')) {
+      console.error(`[opencli:boss] Fetching job detail...`);
+    }
+
+    const evaluateScript = `
+      async () => {
+        return new Promise((resolve, reject) => {
+          const xhr = new window.XMLHttpRequest();
+          xhr.open('GET', ${JSON.stringify(targetUrl)}, true);
+          xhr.withCredentials = true;
+          xhr.timeout = 15000;
+          xhr.setRequestHeader('Accept', 'application/json, text/plain, */*');
+          xhr.onload = () => {
+            if (xhr.status >= 200 && xhr.status < 300) {
+              try {
+                resolve(JSON.parse(xhr.responseText));
+              } catch (e) {
+                reject(new Error('Failed to parse JSON. Raw (200 chars): ' + xhr.responseText.substring(0, 200)));
+              }
+            } else {
+              reject(new Error('XHR HTTP Status: ' + xhr.status));
+            }
+          };
+          xhr.onerror = () => reject(new Error('XHR Network Error'));
+          xhr.ontimeout = () => reject(new Error('XHR Timeout'));
+          xhr.send();
+        });
+      }
+    `;
+
+    let data: any;
+    try {
+      data = await page.evaluate(evaluateScript);
+    } catch (e: any) {
+      throw new Error('API evaluate failed: ' + e.message);
+    }
+
+    if (data.code !== 0) {
+      if (data.code === 37) {
+        throw new Error('Cookie 已过期！请在当前 Chrome 浏览器中重新登录 BOSS 直聘。');
+      }
+      throw new Error(`BOSS API error: ${data.message || 'Unknown'} (code=${data.code})`);
+    }
+
+    const zpData = data.zpData || {};
+    const jobInfo = zpData.jobInfo || {};
+    const bossInfo = zpData.bossInfo || {};
+    const brandComInfo = zpData.brandComInfo || {};
+
+    if (!jobInfo.jobName) {
+      throw new Error('该职位信息不存在或已下架');
+    }
+
+    return [{
+      name: jobInfo.jobName || '',
+      salary: jobInfo.salaryDesc || '',
+      experience: jobInfo.experienceName || '',
+      degree: jobInfo.degreeName || '',
+      city: jobInfo.locationName || '',
+      district: [jobInfo.areaDistrict, jobInfo.businessDistrict].filter(Boolean).join('·'),
+      description: jobInfo.postDescription || '',
+      skills: (jobInfo.showSkills || []).join(', '),
+      welfare: (brandComInfo.labels || []).join(', '),
+      boss_name: bossInfo.name || '',
+      boss_title: bossInfo.title || '',
+      active_time: bossInfo.activeTimeDesc || '',
+      company: brandComInfo.brandName || bossInfo.brandName || '',
+      industry: brandComInfo.industryName || '',
+      scale: brandComInfo.scaleName || '',
+      stage: brandComInfo.stageName || '',
+      address: jobInfo.address || '',
+      url: jobInfo.encryptId
+        ? 'https://www.zhipin.com/job_detail/' + jobInfo.encryptId + '.html'
+        : '',
+    }];
+  },
+});

src/clis/boss/search.ts

@@ -81,7 +81,7 @@ cli({
     { name: 'page', type: 'int', default: 1, help: 'Page number' },
     { name: 'limit', type: 'int', default: 15, help: 'Number of results' },
   ],
-  columns: ['name', 'salary', 'company', 'area', 'experience', 'degree', 'skills', 'boss', 'url'],
+  columns: ['name', 'salary', 'company', 'area', 'experience', 'degree', 'skills', 'boss', 'security_id', 'url'],
   func: async (page: IPage | null, kwargs) => {
     if (!page) throw new Error('Browser page required');
 
@@ -191,6 +191,7 @@ cli({
           degree: j.jobDegree,
           skills: (j.skills || []).join(','),
           boss: j.bossName + ' · ' + j.bossTitle,
+          security_id: j.securityId || '',
           url: 'https://www.zhipin.com/job_detail/' + j.encryptJobId + '.html',
         });
         addedInBatch++;

src/clis/chatgpt/README.md

@@ -0,0 +1,44 @@
+# ChatGPT Desktop Adapter for OpenCLI
+
+Control the **ChatGPT macOS Desktop App** directly from the terminal. OpenCLI supports two automation approaches for ChatGPT.
+
+## Approach 1: AppleScript (Default, No Setup)
+
+The current built-in commands use native AppleScript automation — no extra launch flags needed.
+
+### Prerequisites
+1. Install the official [ChatGPT Desktop App](https://openai.com/chatgpt/mac/) from OpenAI.
+2. Grant **Accessibility permissions** to your terminal app (Terminal / iTerm / Warp) in **System Settings → Privacy & Security → Accessibility**. This is required for System Events keystroke simulation.
+
+### Commands
+- `opencli chatgpt status`: Check if the ChatGPT app is currently running.
+- `opencli chatgpt new`: Activate ChatGPT and press `Cmd+N` to start a new conversation.
+- `opencli chatgpt send "message"`: Copy your message to clipboard, activate ChatGPT, paste, and submit.
+- `opencli chatgpt read`: Copy the last AI response via `Cmd+Shift+C` and return it as text.
+
+## Approach 2: CDP (Advanced, Electron Debug Mode)
+
+ChatGPT Desktop is also an Electron app and can be launched with a remote debugging port for deeper automation via CDP:
+
+```bash
+/Applications/ChatGPT.app/Contents/MacOS/ChatGPT \
+  --remote-debugging-port=9224
+```
+
+Then set the endpoint:
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+```
+
+> **Note**: The CDP approach enables future advanced commands like DOM inspection, model switching, and code extraction — similar to the Cursor and Codex adapters.
+
+## How It Works
+
+- **AppleScript mode**: Uses `osascript` and `pbcopy`/`pbpaste` for clipboard-based text transfer. No remote debugging port needed.
+- **CDP mode**: Connects via Playwright to the Electron renderer process for direct DOM manipulation.
+
+## Limitations
+
+- macOS only (AppleScript dependency)
+- AppleScript mode requires Accessibility permissions
+- `read` command copies the last response — earlier messages need manual scroll

src/clis/chatgpt/README.zh-CN.md

@@ -0,0 +1,44 @@
+# ChatGPT 桌面端适配器
+
+在终端中直接控制 **ChatGPT macOS 桌面应用**。OpenCLI 支持两种自动化方式。
+
+## 方式一：AppleScript（默认，无需配置）
+
+内置命令使用原生 AppleScript 自动化，无需额外启动参数。
+
+### 前置条件
+1. 安装官方 [ChatGPT Desktop App](https://openai.com/chatgpt/mac/)。
+2. 在 **系统设置 → 隐私与安全性 → 辅助功能** 中为终端应用授予权限。
+
+### 命令
+- `opencli chatgpt status`：检查 ChatGPT 应用是否在运行。
+- `opencli chatgpt new`：激活 ChatGPT 并按 `Cmd+N` 开始新对话。
+- `opencli chatgpt send "消息"`：将消息复制到剪贴板，激活 ChatGPT，粘贴并提交。
+- `opencli chatgpt read`：通过 `Cmd+Shift+C` 复制最后一条 AI 回复并返回文本。
+
+## 方式二：CDP（高级，Electron 调试模式）
+
+ChatGPT Desktop 同样是 Electron 应用，可以通过远程调试端口启动以实现更深度的自动化：
+
+```bash
+/Applications/ChatGPT.app/Contents/MacOS/ChatGPT \
+  --remote-debugging-port=9224
+```
+
+然后设置环境变量：
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
+```
+
+> **注意**：CDP 模式支持未来的高级命令（如 DOM 检查、模型切换、代码提取等），与 Cursor 和 Codex 适配器类似。
+
+## 工作原理
+
+- **AppleScript 模式**：使用 `osascript` 和 `pbcopy`/`pbpaste` 进行剪贴板文本传输，无需远程调试端口。
+- **CDP 模式**：通过 Playwright 连接到 Electron 渲染进程，直接操作 DOM。
+
+## 限制
+
+- 仅支持 macOS（AppleScript 依赖）
+- AppleScript 模式需要辅助功能权限
+- `read` 命令复制最后一条回复，更早的消息需手动滚动

src/clis/chatgpt/ask.ts

@@ -0,0 +1,77 @@
+import { execSync, spawnSync } from 'node:child_process';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const askCommand = cli({
+  site: 'chatgpt',
+  name: 'ask',
+  description: 'Send a prompt and wait for the AI response (send + wait + read)',
+  domain: 'localhost',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [
+    { name: 'text', required: true, positional: true, help: 'Prompt to send' },
+    { name: 'timeout', required: false, help: 'Max seconds to wait for response (default: 30)', default: '30' },
+  ],
+  columns: ['Role', 'Text'],
+  func: async (page: IPage | null, kwargs: any) => {
+    const text = kwargs.text as string;
+    const timeout = parseInt(kwargs.timeout as string, 10) || 30;
+
+    // Backup clipboard
+    let clipBackup = '';
+    try { clipBackup = execSync('pbpaste', { encoding: 'utf-8' }); } catch {}
+
+    // Send the message
+    spawnSync('pbcopy', { input: text });
+    execSync("osascript -e 'tell application \"ChatGPT\" to activate'");
+    execSync("osascript -e 'delay 0.5'");
+
+    const cmd = "osascript " +
+                "-e 'tell application \"System Events\"' " +
+                "-e 'keystroke \"v\" using command down' " +
+                "-e 'delay 0.2' " +
+                "-e 'keystroke return' " +
+                "-e 'end tell'";
+    execSync(cmd);
+
+    // Clear clipboard marker
+    spawnSync('pbcopy', { input: '__OPENCLI_WAITING__' });
+
+    // Wait for response, then read it
+    const pollInterval = 3;
+    const maxPolls = Math.ceil(timeout / pollInterval);
+    let response = '';
+
+    for (let i = 0; i < maxPolls; i++) {
+      // Wait
+      execSync(`sleep ${pollInterval}`);
+
+      // Try Cmd+Shift+C to copy the latest response
+      execSync("osascript -e 'tell application \"ChatGPT\" to activate'");
+      execSync("osascript -e 'tell application \"System Events\" to keystroke \"c\" using {command down, shift down}'");
+      execSync("osascript -e 'delay 0.3'");
+
+      const copied = execSync('pbpaste', { encoding: 'utf-8' }).trim();
+      if (copied && copied !== '__OPENCLI_WAITING__' && copied !== text) {
+        response = copied;
+        break;
+      }
+    }
+
+    // Restore clipboard
+    if (clipBackup) spawnSync('pbcopy', { input: clipBackup });
+
+    if (!response) {
+      return [
+        { Role: 'User', Text: text },
+        { Role: 'System', Text: `No response within ${timeout}s. ChatGPT may still be generating.` },
+      ];
+    }
+
+    return [
+      { Role: 'User', Text: text },
+      { Role: 'Assistant', Text: response },
+    ];
+  },
+});

src/clis/chatgpt/new.ts

@@ -0,0 +1,24 @@
+import { execSync } from 'node:child_process';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const newCommand = cli({
+  site: 'chatgpt',
+  name: 'new',
+  description: 'Open a new chat in ChatGPT Desktop App',
+  domain: 'localhost',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [],
+  columns: ['Status'],
+  func: async (page: IPage | null) => {
+    try {
+      execSync("osascript -e 'tell application \"ChatGPT\" to activate'");
+      execSync("osascript -e 'delay 0.5'");
+      execSync("osascript -e 'tell application \"System Events\" to keystroke \"n\" using command down'");
+      return [{ Status: 'Success' }];
+    } catch (err: any) {
+      return [{ Status: "Error: " + err.message }];
+    }
+  },
+});

src/clis/chatgpt/read.ts

@@ -0,0 +1,32 @@
+import { execSync } from 'node:child_process';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const readCommand = cli({
+  site: 'chatgpt',
+  name: 'read',
+  description: 'Copy the most recent ChatGPT Desktop App response to clipboard and read it',
+  domain: 'localhost',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [],
+  columns: ['Role', 'Text'],
+  func: async (page: IPage | null) => {
+    try {
+      execSync("osascript -e 'tell application \"ChatGPT\" to activate'");
+      execSync("osascript -e 'delay 0.5'");
+      execSync("osascript -e 'tell application \"System Events\" to keystroke \"c\" using {command down, shift down}'");
+      execSync("osascript -e 'delay 0.3'");
+
+      const result = execSync('pbpaste', { encoding: 'utf-8' }).trim();
+      
+      if (!result) {
+        return [{ Role: 'System', Text: 'No text was copied. Is there a response in the chat?' }];
+      }
+
+      return [{ Role: 'Assistant', Text: result }];
+    } catch (err: any) {
+      throw new Error("Failed to read from ChatGPT: " + err.message);
+    }
+  },
+});

src/clis/chatgpt/send.ts

@@ -0,0 +1,48 @@
+import { execSync, spawnSync } from 'node:child_process';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const sendCommand = cli({
+  site: 'chatgpt',
+  name: 'send',
+  description: 'Send a message to the active ChatGPT Desktop App window',
+  domain: 'localhost',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [{ name: 'text', required: true, positional: true, help: 'Message to send' }],
+  columns: ['Status'],
+  func: async (page: IPage | null, kwargs: any) => {
+    const text = kwargs.text as string;
+    try {
+      // Backup current clipboard content
+      let clipBackup = '';
+      try {
+        clipBackup = execSync('pbpaste', { encoding: 'utf-8' });
+      } catch { /* clipboard may be empty */ }
+
+      // Copy text to clipboard
+      spawnSync('pbcopy', { input: text });
+      
+      execSync("osascript -e 'tell application \"ChatGPT\" to activate'");
+      execSync("osascript -e 'delay 0.5'");
+      
+      const cmd = "osascript " +
+                  "-e 'tell application \"System Events\"' " +
+                  "-e 'keystroke \"v\" using command down' " +
+                  "-e 'delay 0.2' " +
+                  "-e 'keystroke return' " +
+                  "-e 'end tell'";
+                     
+      execSync(cmd);
+
+      // Restore original clipboard content
+      if (clipBackup) {
+        spawnSync('pbcopy', { input: clipBackup });
+      }
+
+      return [{ Status: 'Success' }];
+    } catch (err: any) {
+      return [{ Status: "Error: " + err.message }];
+    }
+  },
+});

src/clis/chatgpt/status.ts

@@ -0,0 +1,22 @@
+import { execSync } from 'node:child_process';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const statusCommand = cli({
+  site: 'chatgpt',
+  name: 'status',
+  description: 'Check if ChatGPT Desktop App is running natively on macOS',
+  domain: 'localhost',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  args: [],
+  columns: ['Status'],
+  func: async (page: IPage | null) => {
+    try {
+      const output = execSync("osascript -e 'application \"ChatGPT\" is running'", { encoding: 'utf-8' }).trim();
+      return [{ Status: output === 'true' ? 'Running' : 'Stopped' }];
+    } catch {
+      return [{ Status: 'Error querying application state' }];
+    }
+  },
+});

src/clis/chatwise/README.md

@@ -0,0 +1,38 @@
+# ChatWise Adapter for OpenCLI
+
+Control the **ChatWise Desktop App** from the terminal via Chrome DevTools Protocol (CDP). ChatWise is an Electron-based multi-LLM client supporting GPT-4, Claude, Gemini, and more.
+
+## Prerequisites
+
+1. Install [ChatWise](https://chatwise.app/).
+2. Launch with remote debugging port:
+   ```bash
+   /Applications/ChatWise.app/Contents/MacOS/ChatWise \
+     --remote-debugging-port=9228
+   ```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9228"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli chatwise status`: Check CDP connection status.
+- `opencli chatwise screenshot`: Export DOM + accessibility snapshot.
+
+### Chat
+- `opencli chatwise new`: Start a new conversation (`Cmd+N`).
+- `opencli chatwise send "message"`: Send a message to the active chat.
+- `opencli chatwise read`: Read the current conversation.
+- `opencli chatwise ask "prompt"`: Send + wait for response + return it (one-shot).
+
+### AI Features
+- `opencli chatwise model`: Get the current AI model.
+- `opencli chatwise model gpt-4`: Switch to a different model.
+
+### Organization
+- `opencli chatwise history`: List conversations from the sidebar.
+- `opencli chatwise export`: Export conversation as Markdown.

src/clis/chatwise/README.zh-CN.md

@@ -0,0 +1,38 @@
+# ChatWise 适配器
+
+通过 Chrome DevTools Protocol (CDP) 在终端中控制 **ChatWise 桌面应用**。ChatWise 是基于 Electron 的多 LLM 客户端，支持 GPT-4、Claude、Gemini 等。
+
+## 前置条件
+
+1. 安装 [ChatWise](https://chatwise.app/)。
+2. 通过远程调试端口启动：
+   ```bash
+   /Applications/ChatWise.app/Contents/MacOS/ChatWise \
+     --remote-debugging-port=9228
+   ```
+
+## 配置
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9228"
+```
+
+## 命令
+
+### 诊断
+- `opencli chatwise status`：检查 CDP 连接状态。
+- `opencli chatwise screenshot`：导出 DOM + accessibility 快照。
+
+### 对话
+- `opencli chatwise new`：开始新对话（`Cmd+N`）。
+- `opencli chatwise send "消息"`：发送消息到当前对话。
+- `opencli chatwise read`：读取当前对话内容。
+- `opencli chatwise ask "提示词"`：发送 + 等待回复 + 返回结果（一站式）。
+
+### AI 功能
+- `opencli chatwise model`：获取当前 AI 模型。
+- `opencli chatwise model gpt-4`：切换模型。
+
+### 组织管理
+- `opencli chatwise history`：列出 sidebar 会话列表。
+- `opencli chatwise export`：导出对话为 Markdown 文件。

src/clis/chatwise/ask.ts

@@ -0,0 +1,87 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const askCommand = cli({
+  site: 'chatwise',
+  name: 'ask',
+  description: 'Send a prompt and wait for the AI response (send + wait + read)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'text', required: true, positional: true, help: 'Prompt to send' },
+    { name: 'timeout', required: false, help: 'Max seconds to wait (default: 30)', default: '30' },
+  ],
+  columns: ['Role', 'Text'],
+  func: async (page: IPage, kwargs: any) => {
+    const text = kwargs.text as string;
+    const timeout = parseInt(kwargs.timeout as string, 10) || 30;
+
+    // Snapshot content length
+    const beforeLen = await page.evaluate(`
+      (function() {
+        const msgs = document.querySelectorAll('[data-message-id], [class*="message"], [class*="bubble"]');
+        return msgs.length;
+      })()
+    `);
+
+    // Send message
+    await page.evaluate(`
+      (function(text) {
+        let composer = document.querySelector('textarea');
+        if (!composer) {
+          const editables = Array.from(document.querySelectorAll('[contenteditable="true"]'));
+          composer = editables.length > 0 ? editables[editables.length - 1] : null;
+        }
+        if (!composer) throw new Error('Could not find input');
+        composer.focus();
+        if (composer.tagName === 'TEXTAREA') {
+          const setter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+          setter.call(composer, text);
+          composer.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+          document.execCommand('insertText', false, text);
+        }
+      })(${JSON.stringify(text)})
+    `);
+
+    await page.wait(0.5);
+    await page.pressKey('Enter');
+
+    // Poll for response
+    const pollInterval = 2;
+    const maxPolls = Math.ceil(timeout / pollInterval);
+    let response = '';
+
+    for (let i = 0; i < maxPolls; i++) {
+      await page.wait(pollInterval);
+
+      const result = await page.evaluate(`
+        (function(prevLen) {
+          const msgs = document.querySelectorAll('[data-message-id], [class*="message"], [class*="bubble"]');
+          if (msgs.length <= prevLen) return null;
+          const last = msgs[msgs.length - 1];
+          const text = last.innerText || last.textContent;
+          return text ? text.trim() : null;
+        })(${beforeLen})
+      `);
+
+      if (result) {
+        response = result;
+        break;
+      }
+    }
+
+    if (!response) {
+      return [
+        { Role: 'User', Text: text },
+        { Role: 'System', Text: `No response within ${timeout}s.` },
+      ];
+    }
+
+    return [
+      { Role: 'User', Text: text },
+      { Role: 'Assistant', Text: response },
+    ];
+  },
+});

src/clis/chatwise/export.ts

@@ -0,0 +1,51 @@
+import * as fs from 'node:fs';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const exportCommand = cli({
+  site: 'chatwise',
+  name: 'export',
+  description: 'Export the current ChatWise conversation to a Markdown file',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'output', required: false, positional: true, help: 'Output file (default: /tmp/chatwise-export.md)' },
+  ],
+  columns: ['Status', 'File', 'Messages'],
+  func: async (page: IPage, kwargs: any) => {
+    const outputPath = (kwargs.output as string) || '/tmp/chatwise-export.md';
+
+    const md = await page.evaluate(`
+      (function() {
+        const selectors = [
+          '[data-message-id]',
+          '[class*="message"]',
+          '[class*="chat-item"]',
+          '[class*="bubble"]',
+        ];
+        
+        for (const sel of selectors) {
+          const nodes = document.querySelectorAll(sel);
+          if (nodes.length > 0) {
+            return Array.from(nodes).map((n, i) => '## Message ' + (i + 1) + '\\n\\n' + (n.innerText || n.textContent).trim()).join('\\n\\n---\\n\\n');
+          }
+        }
+        
+        const main = document.querySelector('main, [role="main"], [class*="chat-container"]');
+        if (main) return main.innerText || main.textContent;
+        return document.body.innerText;
+      })()
+    `);
+
+    fs.writeFileSync(outputPath, '# ChatWise Conversation Export\\n\\n' + md);
+
+    return [
+      {
+        Status: 'Success',
+        File: outputPath,
+        Messages: md.split('## Message').length - 1,
+      },
+    ];
+  },
+});

src/clis/chatwise/history.ts

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const historyCommand = cli({
+  site: 'chatwise',
+  name: 'history',
+  description: 'List conversation history in ChatWise sidebar',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Index', 'Title'],
+  func: async (page: IPage) => {
+    const items = await page.evaluate(`
+      (function() {
+        const results = [];
+        const selectors = [
+          '[class*="sidebar"] [class*="item"]',
+          '[class*="conversation-list"] a',
+          '[class*="chat-list"] > *',
+          'nav a',
+          'aside a',
+          '[role="listbox"] [role="option"]',
+        ];
+        
+        for (const sel of selectors) {
+          const nodes = document.querySelectorAll(sel);
+          if (nodes.length > 0) {
+            nodes.forEach((n, i) => {
+              const text = (n.textContent || '').trim().substring(0, 100);
+              if (text) results.push({ Index: i + 1, Title: text });
+            });
+            break;
+          }
+        }
+        
+        return results;
+      })()
+    `);
+
+    if (items.length === 0) {
+      return [{ Index: 0, Title: 'No history found. Ensure the sidebar is visible.' }];
+    }
+
+    return items;
+  },
+});

src/clis/chatwise/model.ts

@@ -0,0 +1,87 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const modelCommand = cli({
+  site: 'chatwise',
+  name: 'model',
+  description: 'Get or switch the active AI model in ChatWise',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'model_name', required: false, positional: true, help: 'Model to switch to (e.g. gpt-4, claude-3)' },
+  ],
+  columns: ['Status', 'Model'],
+  func: async (page: IPage, kwargs: any) => {
+    const desiredModel = kwargs.model_name as string | undefined;
+
+    if (!desiredModel) {
+      // Read current model
+      const currentModel = await page.evaluate(`
+        (function() {
+          // ChatWise is a multi-LLM client, it typically shows the model name in a dropdown or header
+          const selectors = [
+            '[class*="model"] span',
+            '[class*="Model"] span',
+            '[data-testid*="model"]',
+            'button[class*="model"]',
+            '[aria-label*="Model"]',
+            '[aria-label*="model"]',
+          ];
+          
+          for (const sel of selectors) {
+            const el = document.querySelector(sel);
+            if (el) {
+              const text = (el.textContent || el.getAttribute('title') || '').trim();
+              if (text) return text;
+            }
+          }
+          
+          return 'Unknown or Not Found';
+        })()
+      `);
+
+      return [{ Status: 'Active', Model: currentModel }];
+    } else {
+      // Try to switch model
+      await page.evaluate(`
+        (function(target) {
+          const selectors = [
+            '[class*="model"]',
+            '[class*="Model"]',
+            'button[class*="model"]',
+          ];
+          
+          for (const sel of selectors) {
+            const el = document.querySelector(sel);
+            if (el) { el.click(); return; }
+          }
+          throw new Error('Could not find model selector');
+        })(${JSON.stringify(desiredModel)})
+      `);
+
+      await page.wait(0.5);
+
+      // Find and click the target model in the dropdown
+      const found = await page.evaluate(`
+        (function(target) {
+          const options = document.querySelectorAll('[role="option"], [role="menuitem"], [class*="dropdown-item"], li');
+          for (const opt of options) {
+            if ((opt.textContent || '').toLowerCase().includes(target.toLowerCase())) {
+              opt.click();
+              return true;
+            }
+          }
+          return false;
+        })(${JSON.stringify(desiredModel)})
+      `);
+
+      return [
+        {
+          Status: found ? 'Switched' : 'Dropdown opened but model not found',
+          Model: desiredModel,
+        },
+      ];
+    }
+  },
+});

src/clis/chatwise/new.ts

@@ -0,0 +1,21 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const newCommand = cli({
+  site: 'chatwise',
+  name: 'new',
+  description: 'Start a new conversation in ChatWise',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Status'],
+  func: async (page: IPage) => {
+    // ChatWise uses standard Electron shortcuts
+    const isMac = process.platform === 'darwin';
+    await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
+    await page.wait(1);
+
+    return [{ Status: 'Success' }];
+  },
+});

src/clis/chatwise/read.ts

@@ -0,0 +1,42 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const readCommand = cli({
+  site: 'chatwise',
+  name: 'read',
+  description: 'Read the current ChatWise conversation history',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Content'],
+  func: async (page: IPage) => {
+    const content = await page.evaluate(`
+      (function() {
+        // Try common chat message selectors
+        const selectors = [
+          '[data-message-id]',
+          '[class*="message"]',
+          '[class*="chat-item"]',
+          '[class*="bubble"]',
+          '[role="log"] > *',
+        ];
+        
+        for (const sel of selectors) {
+          const nodes = document.querySelectorAll(sel);
+          if (nodes.length > 0) {
+            return Array.from(nodes).map(n => (n.innerText || n.textContent).trim()).filter(Boolean).join('\\n\\n---\\n\\n');
+          }
+        }
+        
+        // Fallback: main content area
+        const main = document.querySelector('main, [role="main"], [class*="chat-container"], [class*="conversation"]');
+        if (main) return main.innerText || main.textContent;
+        
+        return document.body.innerText;
+      })()
+    `);
+
+    return [{ Content: content }];
+  },
+});

src/clis/chatwise/screenshot.ts

@@ -0,0 +1,33 @@
+import * as fs from 'node:fs';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const screenshotCommand = cli({
+  site: 'chatwise',
+  name: 'screenshot',
+  description: 'Capture a snapshot of the current ChatWise window (DOM + Accessibility tree)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'output', required: false, positional: true, help: 'Output file path (default: /tmp/chatwise-snapshot)' },
+  ],
+  columns: ['Status', 'File'],
+  func: async (page: IPage, kwargs: any) => {
+    const basePath = (kwargs.output as string) || '/tmp/chatwise-snapshot';
+
+    const snap = await page.snapshot({ compact: true });
+    const html = await page.evaluate('document.documentElement.outerHTML');
+
+    const htmlPath = basePath + '-dom.html';
+    const snapPath = basePath + '-a11y.txt';
+
+    fs.writeFileSync(htmlPath, html);
+    fs.writeFileSync(snapPath, typeof snap === 'string' ? snap : JSON.stringify(snap, null, 2));
+
+    return [
+      { Status: 'Success', File: htmlPath },
+      { Status: 'Success', File: snapPath },
+    ];
+  },
+});

src/clis/chatwise/send.ts

@@ -0,0 +1,50 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const sendCommand = cli({
+  site: 'chatwise',
+  name: 'send',
+  description: 'Send a message to the active ChatWise conversation',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [{ name: 'text', required: true, positional: true, help: 'Message to send' }],
+  columns: ['Status', 'InjectedText'],
+  func: async (page: IPage, kwargs: any) => {
+    const text = kwargs.text as string;
+
+    await page.evaluate(`
+      (function(text) {
+        // ChatWise input can be textarea or contenteditable
+        let composer = document.querySelector('textarea');
+        if (!composer) {
+          const editables = Array.from(document.querySelectorAll('[contenteditable="true"]'));
+          composer = editables.length > 0 ? editables[editables.length - 1] : null;
+        }
+
+        if (!composer) throw new Error('Could not find ChatWise input element');
+
+        composer.focus();
+        
+        if (composer.tagName === 'TEXTAREA') {
+          // For textarea, set value and dispatch input event
+          const nativeInputValueSetter = Object.getOwnPropertyDescriptor(window.HTMLTextAreaElement.prototype, 'value').set;
+          nativeInputValueSetter.call(composer, text);
+          composer.dispatchEvent(new Event('input', { bubbles: true }));
+        } else {
+          document.execCommand('insertText', false, text);
+        }
+      })(${JSON.stringify(text)})
+    `);
+
+    await page.wait(0.5);
+    await page.pressKey('Enter');
+
+    return [
+      {
+        Status: 'Success',
+        InjectedText: text,
+      },
+    ];
+  },
+});

src/clis/chatwise/status.ts

@@ -0,0 +1,25 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const statusCommand = cli({
+  site: 'chatwise',
+  name: 'status',
+  description: 'Check active CDP connection to ChatWise Desktop',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Status', 'Url', 'Title'],
+  func: async (page: IPage) => {
+    const url = await page.evaluate('window.location.href');
+    const title = await page.evaluate('document.title');
+
+    return [
+      {
+        Status: 'Connected',
+        Url: url,
+        Title: title,
+      },
+    ];
+  },
+});

src/clis/codex/README.md

@@ -0,0 +1,34 @@
+# OpenAI Codex Adapter for OpenCLI
+
+Control the **OpenAI Codex Desktop App** headless or headfully via Chrome DevTools Protocol (CDP).
+Because Codex is built on Electron, OpenCLI can directly drive its internal UI, automate slash commands, and manipulate its AI agent threads.
+
+## Prerequisites
+
+1. You must have the official OpenAI Codex app installed.
+2. Launch it via the terminal and expose the remote debugging port:
+   ```bash
+   # macOS 
+   /Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9222
+   ```
+
+## Setup
+
+Export the CDP endpoint in your shell:
+```bash
+export OPENCLI_CODEX_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli codex status`: Checks connection and reads the current active window URL/title.
+- `opencli codex dump`: Dumps the full UI DOM and Accessibility tree into `/tmp` (ideal for building AI automation tools on top of it).
+
+### Agent Manipulation
+- `opencli codex new`: Simulates `Cmd+N` to start a completely fresh and isolated Git Worktree thread context.
+- `opencli codex send "message"`: Robustly finds the active Thread Composer and injects your text.
+  - *Pro-tip*: You can trigger internal shortcuts by sending them, e.g., `opencli codex send "/review"` or `opencli codex send "$imagegen draw a cat"`.
+- `opencli codex read`: Extracts the entire current thread history and AI reasoning logs into readable text.
+- `opencli codex extract-diff`: Automatically scrapes any visual Patch chunks and Code Diffs the AI generated inside the review UI.
+- `opencli codex model`: Get the currently active AI model.

src/clis/codex/README.zh-CN.md

@@ -0,0 +1,33 @@
+# OpenAI Codex 桌面端适配器 (OpenCLI)
+
+利用 CDP 协议，直接从命令行/外部脚本接管和操控 **OpenAI Codex 官方桌面版**。
+因为官方 Codex 是基于 Electron 构建的“多 Agent 协作中心”，通过本适配器，你可以让 AI 自动控制另一个 AI 完成工作，甚至自动截取代码审查的 Diff！
+
+## 前置环境准备
+
+1. 你必须下载并安装了官方原版的 OpenAI Codex 客户端。
+2. 必须通过命令行挂载 CDP 调试端口启动它：
+   ```bash
+   # macOS 启动示例
+   /Applications/Codex.app/Contents/MacOS/Codex --remote-debugging-port=9222
+   ```
+
+## 配置指南
+
+在你要运行命令的终端里导出环境变量：
+```bash
+export OPENCLI_CODEX_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+## 核心指令
+
+### 探查与调试
+- `opencli codex status`: 检查是否成功连上内部 Chromium，获取上下文 Title。
+- `opencli codex dump`: 强制剥离整个 App 的内部 DOM 树和无障碍视图并保存到 `/tmp`，是编写复杂自动化 RPA 脚本的终极利刃。
+
+### 自动化执行
+- `opencli codex new`: 模拟按下 `Cmd+N`。建立一个彻底干净、隔离了 Git Worktree 的全线并行 Thread。
+- `opencli codex send "要发送的话"`: 强行跨越 Shadow Root 找到对应的富文本编辑器并注入提词。
+  - *高阶技巧*: 你可以直接发送内置宏！例如 `opencli codex send "/review"` 就能触发本工作流的代码审查，或者 `opencli codex send "$imagegen"` 触发技能。
+- `opencli codex read`: 完整抓取并提取整个当前 Thread 里的思考过程和对话日志。
+- `opencli codex extract-diff`: 专门用于拦截并提取由 AI 建议的 `+` / `-` 代码 Patch 修改块，直接输出结构化数据！

src/clis/codex/ask.ts

@@ -0,0 +1,77 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const askCommand = cli({
+  site: 'codex',
+  name: 'ask',
+  description: 'Send a prompt and wait for the AI response (send + wait + read)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'text', required: true, positional: true, help: 'Prompt to send' },
+    { name: 'timeout', required: false, help: 'Max seconds to wait for response (default: 60)', default: '60' },
+  ],
+  columns: ['Role', 'Text'],
+  func: async (page: IPage, kwargs: any) => {
+    const text = kwargs.text as string;
+    const timeout = parseInt(kwargs.timeout as string, 10) || 60;
+
+    // Snapshot the current content length before sending
+    const beforeLen = await page.evaluate(`
+      (function() {
+        const turns = document.querySelectorAll('[data-content-search-turn-key]');
+        return turns.length;
+      })()
+    `);
+
+    // Inject and send
+    await page.evaluate(`
+      (function(text) {
+        const editables = Array.from(document.querySelectorAll('[contenteditable="true"]'));
+        const composer = editables.length > 0 ? editables[editables.length - 1] : document.querySelector('textarea');
+        if (!composer) throw new Error('Could not find Codex input');
+        composer.focus();
+        document.execCommand('insertText', false, text);
+      })(${JSON.stringify(text)})
+    `);
+    await page.wait(0.5);
+    await page.pressKey('Enter');
+
+    // Poll for new content
+    const pollInterval = 3;
+    const maxPolls = Math.ceil(timeout / pollInterval);
+    let response = '';
+
+    for (let i = 0; i < maxPolls; i++) {
+      await page.wait(pollInterval);
+
+      const result = await page.evaluate(`
+        (function(prevLen) {
+          const turns = document.querySelectorAll('[data-content-search-turn-key]');
+          if (turns.length <= prevLen) return null;
+          const lastTurn = turns[turns.length - 1];
+          const text = lastTurn.innerText || lastTurn.textContent;
+          return text ? text.trim() : null;
+        })(${beforeLen})
+      `);
+
+      if (result) {
+        response = result;
+        break;
+      }
+    }
+
+    if (!response) {
+      return [
+        { Role: 'User', Text: text },
+        { Role: 'System', Text: `No response within ${timeout}s. The agent may still be working.` },
+      ];
+    }
+
+    return [
+      { Role: 'User', Text: text },
+      { Role: 'Assistant', Text: response },
+    ];
+  },
+});

src/clis/codex/dump.ts

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '../../registry.js';
+import * as fs from 'fs';
+
+export const dumpCommand = cli({
+  site: 'codex',
+  name: 'dump',
+  description: 'Dump the DOM and Accessibility tree of Codex for reverse-engineering',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  columns: ['action', 'files'],
+  func: async (page) => {
+    // Extract full HTML
+    const dom = await page.evaluate('document.body.innerHTML');
+    fs.writeFileSync('/tmp/codex-dom.html', dom);
+
+    // Get accessibility snapshot
+    const snap = await page.snapshot({ interactive: false });
+    fs.writeFileSync('/tmp/codex-snapshot.json', JSON.stringify(snap, null, 2));
+
+    return [
+      {
+        action: 'Dom extraction finished',
+        files: '/tmp/codex-dom.html, /tmp/codex-snapshot.json',
+      },
+    ];
+  },
+});

src/clis/codex/export.ts

@@ -0,0 +1,42 @@
+import * as fs from 'node:fs';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const exportCommand = cli({
+  site: 'codex',
+  name: 'export',
+  description: 'Export the current Codex conversation to a Markdown file',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'output', required: false, positional: true, help: 'Output file (default: /tmp/codex-export.md)' },
+  ],
+  columns: ['Status', 'File', 'Messages'],
+  func: async (page: IPage, kwargs: any) => {
+    const outputPath = (kwargs.output as string) || '/tmp/codex-export.md';
+
+    const md = await page.evaluate(`
+      (function() {
+        const turns = document.querySelectorAll('[data-content-search-turn-key]');
+        if (turns.length > 0) {
+          return Array.from(turns).map((t, i) => '## Turn ' + (i + 1) + '\\n\\n' + (t.innerText || t.textContent).trim()).join('\\n\\n---\\n\\n');
+        }
+        
+        const main = document.querySelector('main, [role="main"], [role="log"]');
+        if (main) return main.innerText || main.textContent;
+        return document.body.innerText;
+      })()
+    `);
+
+    fs.writeFileSync(outputPath, '# Codex Conversation Export\\n\\n' + md);
+
+    return [
+      {
+        Status: 'Success',
+        File: outputPath,
+        Messages: md.split('## Turn').length - 1,
+      },
+    ];
+  },
+});

src/clis/codex/extract-diff.ts

@@ -0,0 +1,48 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const extractDiffCommand = cli({
+  site: 'codex',
+  name: 'extract-diff',
+  description: 'Extract visual code review diff patches from Codex',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  columns: ['File', 'Diff'],
+  func: async (page) => {
+    const diffs = await page.evaluate(`
+      (function() {
+        const results = [];
+        // Assuming diffs are rendered with standard diff classes or monaco difference editors
+        const diffBlocks = document.querySelectorAll('.diff-editor, .monaco-diff-editor, [data-testid="diff-view"]');
+        
+        diffBlocks.forEach((block, index) => {
+            // Very roughly scrape text representing additions/deletions mapped from the inner wrapper
+            results.push({
+                File: block.getAttribute('data-filename') || \`DiffBlock_\${index+1}\`,
+                Diff: block.innerText || block.textContent
+            });
+        });
+
+        // If no structured diffs found, try to find any code blocks labeled as patches
+        if (results.length === 0) {
+            const codeBlocks = document.querySelectorAll('pre code.language-diff, pre code.language-patch');
+            codeBlocks.forEach((code, index) => {
+                results.push({
+                    File: \`Patch_\${index+1}\`,
+                    Diff: code.innerText || code.textContent
+                });
+            });
+        }
+        
+        return results;
+      })()
+    `);
+
+    if (diffs.length === 0) {
+      return [{ File: 'No diffs found', Diff: 'Try running opencli codex send "/review" first' }];
+    }
+
+    return diffs;
+  },
+});

src/clis/codex/history.ts

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const historyCommand = cli({
+  site: 'codex',
+  name: 'history',
+  description: 'List recent conversation threads in Codex',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Index', 'Title'],
+  func: async (page: IPage) => {
+    const items = await page.evaluate(`
+      (function() {
+        const results = [];
+        // Codex thread list items
+        const entries = document.querySelectorAll('[data-testid*="thread"], [class*="thread-list"] a, [role="listbox"] [role="option"]');
+        
+        entries.forEach((item, i) => {
+          const title = (item.textContent || item.innerText || '').trim().substring(0, 100);
+          if (title) results.push({ Index: i + 1, Title: title });
+        });
+        
+        // Fallback: sidebar/nav links
+        if (results.length === 0) {
+          const nav = document.querySelector('nav, [role="navigation"], aside');
+          if (nav) {
+            const links = nav.querySelectorAll('a, button');
+            links.forEach((link, i) => {
+              const text = (link.textContent || '').trim().substring(0, 100);
+              if (text && text.length > 3) results.push({ Index: i + 1, Title: text });
+            });
+          }
+        }
+        
+        return results;
+      })()
+    `);
+
+    if (items.length === 0) {
+      return [{ Index: 0, Title: 'No threads found. Try opening the thread list first.' }];
+    }
+
+    return items;
+  },
+});

src/clis/codex/model.ts

@@ -0,0 +1,59 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const modelCommand = cli({
+  site: 'codex',
+  name: 'model',
+  description: 'Get or switch the currently active AI model in Codex Desktop',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'model_name', required: false, positional: true, help: 'The ID of the model to switch to (e.g. gpt-4)' }
+  ],
+  columns: ['Status', 'Model'],
+  func: async (page: IPage, kwargs: any) => {
+    const desiredModel = kwargs.model_name as string | undefined;
+
+    if (!desiredModel) {
+      // Just read the current model. We traverse iframes/webviews if needed.
+      const currentModel = await page.evaluate(`
+        (function() {
+          // Look for any typical model switcher selectors in the DOM
+          let m = document.querySelector('[title*="Model"], [aria-label*="Model"], .model-selector, [class*="ModelPicker"]');
+          
+          if (!m && document.querySelector('webview, iframe')) {
+              // Not directly in main DOM, might be in a webview, but Playwright evaluate doesn't cross origin boundaries easily without frames[].
+              return 'Unknown (Likely inside a WebView, please focus the Chat tab)';
+          }
+          return m ? (m.textContent || m.getAttribute('title') || m.getAttribute('aria-label')).trim() : 'Unknown or Not Found';
+        })()
+      `);
+      
+      return [
+        {
+          Status: 'Active',
+          Model: currentModel,
+        },
+      ];
+    } else {
+      // Try to switch model (click dropdown, type/select model)
+      const success = await page.evaluate(`
+        (function(targetModel) {
+          const dropdown = document.querySelector('[title*="Model"], [aria-label*="Model"], .model-selector, [class*="ModelPicker"]');
+          if (!dropdown) return 'Dropdown not found';
+          
+          dropdown.click();
+          return 'Dropdown clicked. Generic interaction initiated.';
+        })(${JSON.stringify(desiredModel)})
+      `);
+      
+      return [
+        {
+          Status: success,
+          Model: desiredModel,
+        },
+      ];
+    }
+  },
+});

src/clis/codex/new.ts

@@ -0,0 +1,29 @@
+import { cli, Strategy } from '../../registry.js';
+
+export const newCommand = cli({
+  site: 'codex',
+  name: 'new',
+  description: 'Start a new Codex conversation thread / isolated workspace',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  columns: ['Status', 'Action'],
+  func: async (page) => {
+    // According to research, Cmd+N / Ctrl+N spins up a new thread
+    const isMac = process.platform === 'darwin';
+    const newThreadKey = isMac ? 'Meta+N' : 'Control+N';
+    
+    // Simulate keyboard shortcut
+    await page.pressKey(newThreadKey);
+
+    // Wait a brief moment for UI animation
+    await page.wait(1);
+
+    return [
+      {
+        Status: 'Success',
+        Action: `Pressed ${newThreadKey} to trigger New Thread`,
+      },
+    ];
+  },
+});

src/clis/codex/read.ts

@@ -0,0 +1,37 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const readCommand = cli({
+  site: 'codex',
+  name: 'read',
+  description: 'Read the contents of the current Codex conversation thread',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Content'],
+  func: async (page: IPage) => {
+    const historyText = await page.evaluate(`
+      (function() {
+        const turns = Array.from(document.querySelectorAll('[data-content-search-turn-key]'));
+        if (turns.length > 0) {
+            return turns.map(t => t.innerText || t.textContent).join('\\n\\n---\\n\\n');
+        }
+        
+        const threadContainer = document.querySelector('[role="log"], [data-testid="conversation"], .thread-container, .messages-list, main');
+        
+        if (threadContainer) {
+          return threadContainer.innerText || threadContainer.textContent;
+        }
+        
+        return document.body.innerText;
+      })()
+    `);
+
+    return [
+      {
+        Content: historyText,
+      },
+    ];
+  },
+});

src/clis/codex/screenshot.ts

@@ -0,0 +1,33 @@
+import * as fs from 'node:fs';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const screenshotCommand = cli({
+  site: 'codex',
+  name: 'screenshot',
+  description: 'Capture a snapshot of the current Codex window (DOM + Accessibility tree)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'output', required: false, positional: true, help: 'Output file path (default: /tmp/codex-snapshot.txt)' },
+  ],
+  columns: ['Status', 'File'],
+  func: async (page: IPage, kwargs: any) => {
+    const outputPath = (kwargs.output as string) || '/tmp/codex-snapshot.txt';
+
+    const snap = await page.snapshot({ compact: true });
+    const html = await page.evaluate('document.documentElement.outerHTML');
+
+    const htmlPath = outputPath.replace(/\.\w+$/, '') + '-dom.html';
+    const snapPath = outputPath.replace(/\.\w+$/, '') + '-a11y.txt';
+
+    fs.writeFileSync(htmlPath, html);
+    fs.writeFileSync(snapPath, typeof snap === 'string' ? snap : JSON.stringify(snap, null, 2));
+
+    return [
+      { Status: 'Success', File: htmlPath },
+      { Status: 'Success', File: snapPath },
+    ];
+  },
+});

src/clis/codex/send.ts

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const sendCommand = cli({
+  site: 'codex',
+  name: 'send',
+  description: 'Send text/commands to the Codex AI composer',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [{ name: 'text', required: true, positional: true, help: 'Text, command (e.g. /review), or skill (e.g. $imagegen)' }],
+  columns: ['Status', 'InjectedText'],
+  func: async (page: IPage, kwargs: any) => {
+    const textToInsert = kwargs.text as string;
+
+    await page.evaluate(`
+      (function(text) {
+        let composer = document.querySelector('textarea, [contenteditable="true"]');
+        
+        const editables = Array.from(document.querySelectorAll('[contenteditable="true"]'));
+        if (editables.length > 0) {
+           composer = editables[editables.length - 1];
+        }
+
+        if (!composer) {
+          throw new Error('Could not find Composer input element in Codex UI');
+        }
+
+        composer.focus();
+        document.execCommand('insertText', false, text);
+      })(${JSON.stringify(textToInsert)})
+    `);
+
+    // Wait for the UI to register the input
+    await page.wait(0.5);
+
+    // Simulate Enter key to submit
+    await page.pressKey('Enter');
+
+    return [
+      {
+        Status: 'Success',
+        InjectedText: textToInsert,
+      },
+    ];
+  },
+});

src/clis/codex/status.ts

@@ -0,0 +1,25 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const statusCommand = cli({
+  site: 'codex',
+  name: 'status',
+  description: 'Check active CDP connection to OpenAI Codex App',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Status', 'Url', 'Title'],
+  func: async (page: IPage) => {
+    const url = await page.evaluate('window.location.href');
+    const title = await page.evaluate('document.title');
+
+    return [
+      {
+        Status: 'Connected',
+        Url: url,
+        Title: title,
+      },
+    ];
+  },
+});

src/clis/cursor/README.md

@@ -0,0 +1,33 @@
+# Cursor Adapter for OpenCLI
+
+Control the **Cursor IDE** from the terminal via Chrome DevTools Protocol (CDP). Since Cursor is built on Electron (VS Code fork), OpenCLI can drive its internal UI, automate Composer interactions, and manipulate chat sessions.
+
+## Prerequisites
+
+1. Install [Cursor](https://cursor.sh/).
+2. Launch it with the remote debugging port:
+   ```bash
+   /Applications/Cursor.app/Contents/MacOS/Cursor --remote-debugging-port=9226
+   ```
+
+## Setup
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9226"
+```
+
+## Commands
+
+### Diagnostics
+- `opencli cursor status`: Check CDP connection status.
+- `opencli cursor dump`: Dump the full DOM and Accessibility snapshot to `/tmp/cursor-dom.html` and `/tmp/cursor-snapshot.json`.
+
+### Chat Manipulation
+- `opencli cursor new`: Press `Cmd+N` to start a new file/tab.
+- `opencli cursor send "message"`: Inject text into the active Composer/Chat input and submit.
+- `opencli cursor read`: Extract the full conversation history from the active chat panel.
+
+### AI Features
+- `opencli cursor composer "prompt"`: Open the Composer panel (`Cmd+I`) and send a prompt for inline AI editing.
+- `opencli cursor model`: Get the currently active AI model (e.g., `claude-4.5-sonnet`).
+- `opencli cursor extract-code`: Extract all code blocks from the current conversation.

src/clis/cursor/README.zh-CN.md

@@ -0,0 +1,33 @@
+# Cursor 适配器
+
+通过 Chrome DevTools Protocol (CDP) 在终端中控制 **Cursor IDE**。由于 Cursor 基于 Electron（VS Code 分支），OpenCLI 可以驱动其内部 UI，自动化 Composer 交互，操控聊天会话。
+
+## 前置条件
+
+1. 安装 [Cursor](https://cursor.sh/)。
+2. 通过远程调试端口启动：
+   ```bash
+   /Applications/Cursor.app/Contents/MacOS/Cursor --remote-debugging-port=9226
+   ```
+
+## 配置
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9226"
+```
+
+## 命令
+
+### 诊断
+- `opencli cursor status`：检查 CDP 连接状态。
+- `opencli cursor dump`：导出完整 DOM 和 Accessibility 快照到 `/tmp/cursor-dom.html` 和 `/tmp/cursor-snapshot.json`。
+
+### 对话操作
+- `opencli cursor new`：按 `Cmd+N` 创建新文件/标签。
+- `opencli cursor send "消息"`：将文本注入活跃的 Composer/Chat 输入框并提交。
+- `opencli cursor read`：提取当前聊天面板的完整对话历史。
+
+### AI 功能
+- `opencli cursor composer "提示词"`：打开 Composer 面板（`Cmd+I`）并发送提示词进行内联 AI 编辑。
+- `opencli cursor model`：获取当前活跃的 AI 模型（如 `claude-4.5-sonnet`）。
+- `opencli cursor extract-code`：从当前对话中提取所有代码块。

src/clis/cursor/ask.ts

@@ -0,0 +1,81 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const askCommand = cli({
+  site: 'cursor',
+  name: 'ask',
+  description: 'Send a prompt and wait for the AI response (send + wait + read)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'text', required: true, positional: true, help: 'Prompt to send' },
+    { name: 'timeout', required: false, help: 'Max seconds to wait for response (default: 30)', default: '30' },
+  ],
+  columns: ['Role', 'Text'],
+  func: async (page: IPage, kwargs: any) => {
+    const text = kwargs.text as string;
+    const timeout = parseInt(kwargs.timeout as string, 10) || 30;
+
+    // Count existing messages before sending
+    const beforeCount = await page.evaluate(`
+      document.querySelectorAll('[data-message-role]').length
+    `);
+
+    // Inject text into the active editor and submit
+    const injected = await page.evaluate(
+      `(function(text) {
+        let editor = document.querySelector('.aislash-editor-input, [data-lexical-editor="true"], [contenteditable="true"]');
+        if (!editor) return false;
+        editor.focus();
+        document.execCommand('insertText', false, text);
+        return true;
+      })(${JSON.stringify(text)})`
+    );
+
+    if (!injected) throw new Error('Could not find input element.');
+    await page.wait(0.5);
+    await page.pressKey('Enter');
+
+    // Poll until a new assistant message appears or timeout
+    const pollInterval = 2; // seconds
+    const maxPolls = Math.ceil(timeout / pollInterval);
+    let response = '';
+
+    for (let i = 0; i < maxPolls; i++) {
+      await page.wait(pollInterval);
+
+      const result = await page.evaluate(`
+        (function(prevCount) {
+          const msgs = document.querySelectorAll('[data-message-role]');
+          if (msgs.length <= prevCount) return null;
+          
+          const lastMsg = msgs[msgs.length - 1];
+          const role = lastMsg.getAttribute('data-message-role');
+          if (role === 'human') return null; // Still waiting for assistant
+          
+          const root = lastMsg.querySelector('.markdown-root');
+          const text = root ? root.innerText : lastMsg.innerText;
+          return text ? text.trim() : null;
+        })(${beforeCount})
+      `);
+
+      if (result) {
+        response = result;
+        break;
+      }
+    }
+
+    if (!response) {
+      return [
+        { Role: 'User', Text: text },
+        { Role: 'System', Text: `No response received within ${timeout}s. The AI may still be generating.` },
+      ];
+    }
+
+    return [
+      { Role: 'User', Text: text },
+      { Role: 'Assistant', Text: response },
+    ];
+  },
+});

src/clis/cursor/composer.ts

@@ -0,0 +1,50 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const composerCommand = cli({
+  site: 'cursor',
+  name: 'composer',
+  description: 'Send a prompt directly into Cursor Composer (Cmd+I shortcut)',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [{ name: 'text', required: true, positional: true, help: 'Text to send into Composer' }],
+  columns: ['Status', 'InjectedText'],
+  func: async (page: IPage, kwargs: any) => {
+    const textToInsert = kwargs.text as string;
+
+    // Open/Focus Composer via shortcut — always works regardless of current state
+    await page.pressKey('Meta+I');
+    await page.wait(1);
+
+    const typed = await page.evaluate(
+      `(function(text) {
+        let composer = document.activeElement;
+        if (!composer || !composer.isContentEditable) {
+            composer = document.querySelector('.composer-bar [data-lexical-editor="true"], [id*="composer"] [contenteditable="true"], .aislash-editor-input');
+        }
+        
+        if (!composer) return false;
+
+        composer.focus();
+        document.execCommand('insertText', false, text);
+        return true;
+      })(${JSON.stringify(textToInsert)})`
+    );
+
+    if (!typed) {
+      throw new Error('Could not find Cursor Composer input element after pressing Cmd+I.');
+    }
+
+    await page.wait(0.5);
+    await page.pressKey('Enter');
+    await page.wait(1);
+
+    return [
+      {
+        Status: 'Success',
+        InjectedText: textToInsert,
+      },
+    ];
+  },
+});

src/clis/cursor/dump.ts

@@ -0,0 +1,28 @@
+import { cli, Strategy } from '../../registry.js';
+import * as fs from 'fs';
+
+export const dumpCommand = cli({
+  site: 'cursor',
+  name: 'dump',
+  description: 'Dump the DOM and Accessibility tree of Cursor for reverse-engineering',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  columns: ['action', 'files'],
+  func: async (page) => {
+    // Extract full HTML
+    const dom = await page.evaluate('document.body.innerHTML');
+    fs.writeFileSync('/tmp/cursor-dom.html', dom);
+
+    // Get accessibility snapshot
+    const snap = await page.snapshot({ interactive: false });
+    fs.writeFileSync('/tmp/cursor-snapshot.json', JSON.stringify(snap, null, 2));
+
+    return [
+      {
+        action: 'Dom extraction finished',
+        files: '/tmp/cursor-dom.html, /tmp/cursor-snapshot.json',
+      },
+    ];
+  },
+});

src/clis/cursor/export.ts

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs';
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+function makeExportCommand(site: string, readSelector: string) {
+  return cli({
+    site,
+    name: 'export',
+    description: `Export the current ${site} conversation to a Markdown file`,
+    domain: 'localhost',
+    strategy: Strategy.UI,
+    browser: true,
+    args: [
+      { name: 'output', required: false, positional: true, help: `Output file (default: /tmp/${site}-export.md)` },
+    ],
+    columns: ['Status', 'File', 'Messages'],
+    func: async (page: IPage, kwargs: any) => {
+      const outputPath = (kwargs.output as string) || `/tmp/${site}-export.md`;
+
+      const md = await page.evaluate(`
+        (function() {
+          const selectors = ${JSON.stringify(readSelector)}.split(',');
+          let messages = [];
+          
+          for (const sel of selectors) {
+            const nodes = document.querySelectorAll(sel.trim());
+            if (nodes.length > 0) {
+              messages = Array.from(nodes).map(n => n.innerText || n.textContent);
+              break;
+            }
+          }
+
+          if (messages.length === 0) {
+            const main = document.querySelector('main, [role="main"], .messages-list, [role="log"]');
+            if (main) messages = [main.innerText || main.textContent];
+          }
+
+          if (messages.length === 0) messages = [document.body.innerText];
+          
+          return messages.map((m, i) => '## Message ' + (i + 1) + '\\n\\n' + m.trim()).join('\\n\\n---\\n\\n');
+        })()
+      `);
+
+      fs.writeFileSync(outputPath, `# ${site} Conversation Export\\n\\n` + md);
+
+      return [
+        {
+          Status: 'Success',
+          File: outputPath,
+          Messages: md.split('## Message').length - 1,
+        },
+      ];
+    },
+  });
+}
+
+export const cursorExport = makeExportCommand('cursor', '[data-message-role]');

src/clis/cursor/extract-code.ts

@@ -0,0 +1,39 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const extractCodeCommand = cli({
+  site: 'cursor',
+  name: 'extract-code',
+  description: 'Extract multi-line code blocks from the current Cursor conversation',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Code'],
+  func: async (page: IPage) => {
+    const blocks = await page.evaluate(`
+      (function() {
+        // Find standard pre/code blocks
+        let elements = Array.from(document.querySelectorAll('pre code, .markdown-root pre'));
+        
+        // Fallback to Monaco editor content inside the UI
+        if (elements.length === 0) {
+          elements = Array.from(document.querySelectorAll('.monaco-editor'));
+        }
+        
+        // Generic fallback to any code tag that spans multiple lines
+        if (elements.length === 0) {
+          elements = Array.from(document.querySelectorAll('code')).filter(c => c.innerText.includes('\\n'));
+        }
+        
+        return elements.map(el => el.innerText || el.textContent || '').filter(text => text.trim().length > 0);
+      })()
+    `);
+    
+    if (!blocks || blocks.length === 0) {
+      return [{ Code: 'No code blocks found in Cursor.' }];
+    }
+
+    return blocks.map((code: string) => ({ Code: code }));
+  },
+});

src/clis/cursor/history.ts

@@ -0,0 +1,47 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const historyCommand = cli({
+  site: 'cursor',
+  name: 'history',
+  description: 'List recent chat sessions from the Cursor sidebar',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [],
+  columns: ['Index', 'Title'],
+  func: async (page: IPage) => {
+    const items = await page.evaluate(`
+      (function() {
+        const results = [];
+        // Cursor chat history lives in sidebar items
+        const entries = document.querySelectorAll('.agent-sidebar-list-item, [data-testid="chat-history-item"], .chat-history-item, .tree-item');
+        
+        entries.forEach((item, i) => {
+          const title = (item.textContent || item.innerText || '').trim().substring(0, 100);
+          if (title) results.push({ Index: i + 1, Title: title });
+        });
+        
+        // Fallback: try to find sidebar text items
+        if (results.length === 0) {
+          const sidebar = document.querySelector('.sidebar, [class*="sidebar"], .agent-sidebar, .side-bar-container');
+          if (sidebar) {
+            const links = sidebar.querySelectorAll('a, [role="treeitem"], [role="option"]');
+            links.forEach((link, i) => {
+              const text = (link.textContent || '').trim().substring(0, 100);
+              if (text) results.push({ Index: i + 1, Title: text });
+            });
+          }
+        }
+        
+        return results;
+      })()
+    `);
+
+    if (items.length === 0) {
+      return [{ Index: 0, Title: 'No chat history found. Open the AI sidebar first.' }];
+    }
+
+    return items;
+  },
+});

src/clis/cursor/model.ts

@@ -0,0 +1,57 @@
+import { cli, Strategy } from '../../registry.js';
+import type { IPage } from '../../types.js';
+
+export const modelCommand = cli({
+  site: 'cursor',
+  name: 'model',
+  description: 'Get or switch the currently active AI model in Cursor',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,
+  args: [
+    { name: 'model_name', required: false, positional: true, help: 'The ID of the model to switch to (e.g. claude-3.5-sonnet)' }
+  ],
+  columns: ['Status', 'Model'],
+  func: async (page: IPage, kwargs: any) => {
+    const desiredModel = kwargs.model_name as string | undefined;
+
+    if (!desiredModel) {
+      // Just read the current model
+      const currentModel = await page.evaluate(`
+        (function() {
+          const m = document.querySelector('.composer-unified-dropdown-model span, [class*="unifiedmodeldropdown"] span');
+          return m ? m.textContent.trim() : 'Unknown or Not Found';
+        })()
+      `);
+      
+      return [
+        {
+          Status: 'Active',
+          Model: currentModel,
+        },
+      ];
+    } else {
+      // Try to switch model (click dropdown, type/select model)
+      const success = await page.evaluate(`
+        (function(targetModel) {
+          const dropdown = document.querySelector('.composer-unified-dropdown-model, [class*="unifiedmodeldropdown"]');
+          if (!dropdown) return 'Dropdown not found';
+          
+          dropdown.click();
+          // After clicking, the DOM usually spawns a popup list.
+          // Because it's hard to predict exactly how the list renders, 
+          // a simple scriptable approach is just to click it, and hope we can select it via UI.
+          // In many React apps, clicking it opens a menu, and clicking the item works.
+          return 'Dropdown opened. Automated switching is not fully generic. Please implement precise list navigation depending on DOM.';
+        })(${JSON.stringify(desiredModel)})
+      `);
+      
+      return [
+        {
+          Status: success,
+          Model: desiredModel,
+        },
+      ];
+    }
+  },
+});