@jackwener/opencli 1.6.1 → 1.6.3

package/docs/developer/contributing.md

@@ -1,155 +0,0 @@
-# Contributing
-
-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
-npm test
-npm run test:adapter
-
-# 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.
-
-Before you start:
-
-- Prefer positional args for the command's primary subject (`search <query>`, `topic <id>`, `download <url>`). Reserve named flags for optional modifiers such as `--limit`, `--sort`, `--lang`, and `--output`.
-- Normalize expected adapter failures to `CliError` subclasses instead of raw `Error` whenever possible. Prefer `AuthRequiredError`, `EmptyResultError`, `CommandExecutionError`, `TimeoutError`, and `ArgumentError` so the top-level CLI can render better messages and hints.
-- If you add a new adapter or make a command newly discoverable, update the matching doc page and the user-facing indexes that expose it.
-
-### YAML Adapter (Recommended for data-fetching commands)
-
-Create a file like `src/clis/<site>/<command>.yaml`:
-
-::: v-pre
-```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`](https://github.com/jackwener/opencli/blob/main/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';
-import { CommandExecutionError, EmptyResultError } from '../../errors.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;
-    // ... browser automation logic
-    if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response');
-    if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword');
-    return data.slice(0, Number(limit)).map((item: any) => ({
-      title: item.title,
-      url: item.url,
-      date: item.created_at,
-    }));
-  },
-});
-```
-
-### Validate Your Adapter
-
-```bash
-opencli validate               # Validate YAML syntax and schema
-opencli <site> <command> --limit 3 -f json   # Test your command
-opencli <site> <command> -v    # Verbose mode for debugging
-```
-
-## 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.
-- **Errors** — throw `CliError` subclasses for expected adapter failures; avoid raw `Error` for normal adapter control flow.
-
-## 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
-```
-
-## 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:
-   ```bash
-   npx tsc --noEmit           # Type check
-   npm test                   # Core unit tests
-   npm run test:adapter       # Focused adapter tests (if adapter logic changed)
-   opencli validate           # YAML validation (if applicable)
-   ```
-4. Commit using conventional commit format
-5. Push and open a PR
-
-If your PR adds a new adapter or changes user-facing commands, also verify:
-
-- Adapter docs exist under `docs/adapters/`
-- `docs/adapters/index.md` is updated for new adapters
-- VitePress sidebar includes the new doc page
-- `README.md` / `README.zh-CN.md` stay aligned when command discoverability changes

package/docs/developer/testing.md

@@ -1,261 +0,0 @@
-# Testing Guide
-
-> 面向开发者和 AI Agent 的测试参考手册。
-
-## 目录
-
-- [测试架构](#测试架构)
-- [当前覆盖范围](#当前覆盖范围)
-- [本地运行测试](#本地运行测试)
-- [如何添加新测试](#如何添加新测试)
-- [CI/CD 流水线](#cicd-流水线)
-- [浏览器模式](#浏览器模式)
-- [站点兼容性](#站点兼容性)
-
----
-
-## 测试架构
-
-测试分为三层，全部使用 **vitest** 运行：
-
-```text
-tests/
-├── e2e/                           # E2E 集成测试（子进程运行真实 CLI）
-│   ├── helpers.ts                 # runCli() / parseJsonOutput() 共享工具
-│   ├── 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     # 输出格式校验
-├── smoke/
-│   └── api-health.test.ts         # 外部 API、adapter 定义、命令注册健康检查
-src/
-├── **/*.test.ts                   # 核心单元测试（默认 `unit` project）
-└── clis/{zhihu,twitter,reddit,bilibili}/**/*.test.ts  # 聚焦 adapter tests
-```
-
-| 层 | 位置 | 当前文件数 | 运行方式 | 用途 |
-|---|---|---:|---|---|
-| 单元测试 | `src/**/*.test.ts`（排除 `src/clis/**`） | - | `npm test` | 内部模块、pipeline、runtime |
-| Adapter 测试 | `src/clis/{zhihu,twitter,reddit,bilibili}/**/*.test.ts` | - | `npm run test:adapter` | 保留 4 个重点站点的 adapter 覆盖 |
-| E2E 测试 | `tests/e2e/*.test.ts` | 5 | `npx vitest run tests/e2e/` | 真实 CLI 命令执行 |
-| 烟雾测试 | `tests/smoke/*.test.ts` | 1 | `npx vitest run tests/smoke/` | 外部 API 与注册完整性 |
-
----
-
-## 当前覆盖范围
-
-### 单元测试与 Adapter 测试
-
-| 领域 | 文件 |
-|---|---|
-| 核心运行时与输出 | `src/browser.test.ts`, `src/browser/dom-snapshot.test.ts`, `src/build-manifest.test.ts`, `src/capabilityRouting.test.ts`, `src/doctor.test.ts`, `src/engine.test.ts`, `src/interceptor.test.ts`, `src/output.test.ts`, `src/plugin.test.ts`, `src/registry.test.ts`, `src/snapshotFormatter.test.ts` |
-| pipeline 与下载 | `src/download/index.test.ts`, `src/pipeline/executor.test.ts`, `src/pipeline/template.test.ts`, `src/pipeline/transform.test.ts` |
-| 聚焦 adapter 逻辑 | `src/clis/zhihu/download.test.ts`, `src/clis/twitter/timeline.test.ts`, `src/clis/reddit/read.test.ts`, `src/clis/bilibili/dynamic.test.ts` |
-
-这些测试覆盖的重点包括：
-
-- Browser Bridge、DOM snapshot、interceptor、capability routing
-- manifest 生成、命令发现、插件安装与注册表
-- 输出格式渲染与 snapshot formatting
-- pipeline 模板求值、执行器与变换步骤
-- 各站点 adapter 的数据归一化、参数处理与容错逻辑
-
-### E2E 测试（5 个文件）
-
-| 文件 | 当前覆盖范围 |
-|---|---|
-| `tests/e2e/public-commands.test.ts` | `bloomberg`、`apple-podcasts`、`hackernews`、`v2ex`、`xiaoyuzhou`、`google suggest` 等公开命令 |
-| `tests/e2e/browser-public.test.ts` | `bbc`、`bloomberg`、`bilibili`、`weibo`、`zhihu`、`reddit`、`twitter`、`xueqiu`、`reuters`、`youtube`、`smzdm`、`boss`、`ctrip`、`coupang`、`xiaohongshu`、`google`、`yahoo-finance`、`v2ex daily` |
-| `tests/e2e/browser-auth.test.ts` | `bilibili`、`twitter`、`v2ex`、`xueqiu`、`linux-do`、`xiaohongshu` 的需登录命令 graceful failure |
-| `tests/e2e/management.test.ts` | `list`、`validate`、`verify`、`--version`、`--help`、unknown command |
-| `tests/e2e/output-formats.test.ts` | `json` / `yaml` / `csv` / `md` 输出格式校验 |
-
-### 烟雾测试（1 个文件）
-
-| 文件 | 当前覆盖范围 |
-|---|---|
-| `tests/smoke/api-health.test.ts` | `hackernews`、`v2ex` 公开 API 可用性，`validate` 全量 adapter 校验，以及命令注册表基础完整性 |
-
-### 快速核对命令
-
-需要刷新测试清单时，直接以仓库文件为准：
-
-```bash
-find src -name '*.test.ts' | sort
-find tests/e2e -name '*.test.ts' | sort
-find tests/smoke -name '*.test.ts' | sort
-```
-
----
-
-## 本地运行测试
-
-### 前置条件
-
-```bash
-npm ci                # 安装依赖
-npm run build         # 编译（E2E / smoke 测试需要 dist/main.js）
-```
-
-### 运行命令
-
-```bash
-# 默认核心单元测试（不含大多数 adapter tests）
-npm test
-
-# 聚焦 adapter tests（只保留 4 个重点站点）
-npm run test:adapter
-
-# 全部 E2E 测试（会真实调用外部 API / 浏览器）
-npx vitest run tests/e2e/
-
-# 全部 smoke 测试
-npx vitest run tests/smoke/
-
-# 单个测试文件
-npx vitest run src/clis/apple-podcasts/commands.test.ts
-npx vitest run tests/e2e/management.test.ts
-
-# 全部测试
-npx vitest run
-
-# watch 模式（开发时推荐）
-npx vitest src/
-```
-
-### 浏览器命令本地测试须知
-
-- opencli 通过 Browser Bridge 扩展连接已运行的 Chrome 浏览器
-- E2E 测试通过 `tests/e2e/helpers.ts` 里的 `runCli()` 调用已构建的 `dist/main.js`
-- `browser-public.test.ts` 使用 `tryBrowserCommand()`，站点反爬或地域限制导致空数据时会 warn + pass
-- `browser-auth.test.ts` 验证 **graceful failure**，重点是不 crash、不 hang、错误信息可控
-- 如需测试完整登录态，保持 Chrome 登录态并安装 Browser Bridge 扩展，再手动运行对应测试
-
----
-
-## 如何添加新测试
-
-### 新增 YAML Adapter（如 `src/clis/producthunt/trending.yaml`）
-
-1. `opencli validate` 的 E2E / smoke 测试会覆盖 adapter 结构校验
-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` 添加测试；如果新命令会影响输出格式，也同步补 `tests/e2e/output-formats.test.ts`。
-
-### 新增内部模块
-
-在对应源码旁创建 `*.test.ts`，优先和被测模块放在同一目录下，便于发现与维护。
-
-### 决策流程图
-
-```text
-新增功能 → 是内部模块？ → 是 → 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 到 `main`,`dev` | `tsc --noEmit` + `npm run build` |
-| `unit-test` | push/PR 到 `main`,`dev` | Node `20` 与 `22` 双版本运行核心 `unit` tests，按 `2` shard 并行 |
-| `adapter-test` | push/PR 到 `main`,`dev` | Node `22` 运行聚焦的 `zhihu/twitter/reddit/bilibili` adapter tests |
-| `smoke-test` | `schedule` 或 `workflow_dispatch` | 安装真实 Chrome，`xvfb-run` 执行 `tests/smoke/` |
-
-### `e2e-headed.yml`
-
-| Job | 触发条件 | 内容 |
-|---|---|---|
-| `e2e-headed` | push/PR 到 `main`,`dev`，或手动触发 | 安装真实 Chrome，`xvfb-run` 执行 `tests/e2e/` |
-
-E2E 与 smoke 都使用 `./.github/actions/setup-chrome` 准备真实 Chrome，并通过 `OPENCLI_BROWSER_EXECUTABLE_PATH` 注入浏览器路径。
-
-### Sharding
-
-单元测试使用 vitest 内置 shard，并在 Node `20` / `22` 两个版本上运行：
-
-::: v-pre
-```yaml
-strategy:
-  matrix:
-    node-version: ['20', '22']
-    shard: [1, 2]
-steps:
-  - run: npm test -- --reporter=verbose --shard=${{ matrix.shard }}/2
-```
-:::
-
----
-
-## 浏览器模式
-
-opencli 通过 Browser Bridge 扩展连接浏览器：
-
-| 条件 | 模式 | 使用场景 |
-|---|---|---|
-| 扩展已安装 / 已连接 | Extension 模式 | 本地用户，连接已登录的 Chrome |
-| 无扩展 token | CLI 自行拉起浏览器 | CI、无登录态或纯自动化场景 |
-
-CI 中使用 `OPENCLI_BROWSER_EXECUTABLE_PATH` 指定真实 Chrome 路径：
-
-::: v-pre
-```yaml
-env:
-  OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
-```
-:::
-
----
-
-## 站点兼容性
-
-GitHub Actions 的美国 runner 上，部分站点会因为地域限制、登录要求或反爬而返回空数据。当前 E2E 对这些场景采用 warn + pass 策略，避免偶发站点限制把整条 CI 打红。
-
-| 站点 | CI 表现 | 常见原因 |
-|---|---|---|
-| `hackernews`、`bbc`、`v2ex`、`bloomberg` | 通常返回数据 | 公开接口或公开页面 |
-| `yahoo-finance`、`google` | 通常返回数据 | 页面公开，但仍可能受限流影响 |
-| `bilibili`、`zhihu`、`weibo`、`xiaohongshu`、`xueqiu` | 容易空数据 | 地域限制、反爬、登录要求 |
-| `reddit`、`twitter`、`youtube` | 容易空数据 | 登录态、cookie、机器人检测 |
-| `smzdm`、`boss`、`ctrip`、`coupang`、`linux-do` | 结果波动较大 | 地域限制、风控或页面结构变动 |
-
-> 如果需要更稳定的浏览器 E2E 结果，优先使用具备目标站点网络可达性的 self-hosted runner。

package/docs/developer/ts-adapter.md

@@ -1,105 +0,0 @@
-# TypeScript Adapter Guide
-
-Use TypeScript adapters when you need browser-side logic, multi-step flows, DOM manipulation, or complex data extraction that goes beyond simple API fetching.
-
-## Basic Structure
-
-```typescript
-import { cli, Strategy } from '../../registry.js';
-import { CommandExecutionError, EmptyResultError } from '../../errors.js';
-
-cli({
-  site: 'mysite',
-  name: 'search',
-  description: 'Search MySite',
-  domain: 'www.mysite.com',
-  strategy: Strategy.COOKIE,      // PUBLIC | COOKIE | HEADER
-  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;
-
-    // Navigate and extract data
-    await page.goto('https://www.mysite.com');
-
-    const data = await page.evaluate(`
-      (async () => {
-        const res = await fetch('/api/search?q=${encodeURIComponent(String(query))}', {
-          credentials: 'include'
-        });
-        return (await res.json()).results;
-      })()
-    `);
-
-    if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response');
-    if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword');
-
-    return data.slice(0, Number(limit)).map((item: any) => ({
-      title: item.title,
-      url: item.url,
-      date: item.created_at,
-    }));
-  },
-});
-```
-
-## Strategy Types
-
-| Strategy | Constant | Use Case |
-|----------|----------|----------|
-| Public | `Strategy.PUBLIC` | No auth needed |
-| Cookie | `Strategy.COOKIE` | Browser session cookies |
-| Header | `Strategy.HEADER` | Custom headers/tokens |
-
-## The `page` Object
-
-The `page` parameter provides browser interaction methods:
-
-- `page.goto(url)` — Navigate to a URL
-- `page.evaluate(script)` — Execute JavaScript in the page context
-- `page.waitForSelector(selector)` — Wait for an element
-- `page.click(selector)` — Click an element
-- `page.type(selector, text)` — Type text into an input
-
-## The `kwargs` Object
-
-Contains parsed CLI arguments as key-value pairs. Always destructure with defaults:
-
-```typescript
-const { query, limit = 10, format = 'json' } = kwargs;
-```
-
-For most search/read/detail commands, the main subject should be positional (`opencli mysite search "rust"`, `opencli mysite article 123`) instead of a named flag such as `--query` or `--id`. Keep named flags for optional modifiers.
-
-## Error Handling
-
-Prefer throwing `CliError` subclasses from `src/errors.ts` for expected adapter failures:
-
-- `AuthRequiredError` for missing login / cookies
-- `EmptyResultError` for empty but valid responses
-- `CommandExecutionError` for unexpected API or browser failures
-- `TimeoutError` for site timeouts
-- `ArgumentError` for invalid user input
-
-Avoid raw `Error` for normal adapter control flow. This keeps top-level CLI output consistent and preserves hints for users.
-
-## AI-Assisted Development
-
-Use the AI workflow tools to accelerate adapter creation:
-
-```bash
-# Discover APIs and page structure
-opencli explore https://example.com --site mysite
-
-# Auto-generate adapter from explore artifacts
-opencli synthesize mysite
-
-# One-shot: explore → synthesize → register
-opencli generate https://example.com --goal "trending"
-```
-
-See [AI Workflow](/developer/ai-workflow) for the complete guide.

package/docs/developer/yaml-adapter.md

@@ -1,124 +0,0 @@
-# YAML Adapter Guide
-
-YAML adapters are the recommended way to add new commands when the site offers a straightforward API. They use a declarative pipeline approach — no TypeScript required.
-
-Use YAML only when the command stays mostly declarative. If you find yourself embedding long JavaScript expressions, many fallbacks, or multi-step browser logic, move the command to a TypeScript adapter instead of growing an opaque template blob.
-
-## Basic Structure
-
-::: v-pre
-```yaml
-site: mysite          # Site identifier
-name: trending        # Command name (opencli mysite trending)
-description: ...      # Help text
-domain: www.mysite.com
-strategy: public      # public | cookie | header
-browser: false        # true if browser session is needed
-
-args:                 # CLI arguments
-  limit:
-    type: int
-    default: 20
-    description: Number of items
-
-pipeline:             # Data processing steps
-  - fetch:
-      url: https://api.mysite.com/trending
-
-  - map:
-      rank: ${{ index + 1 }}
-      title: ${{ item.title }}
-
-  - limit: ${{ args.limit }}
-
-columns: [rank, title, score, url]
-```
-:::
-
-For most commands, keep the primary subject positional. Good examples:
-
-- `opencli mysite search "rust"`
-- `opencli mysite topic 123`
-- `opencli mysite download "https://example.com/post/1"`
-
-Prefer named flags only for optional modifiers such as `--limit`, `--sort`, `--lang`, or `--output`.
-
-## Pipeline Steps
-
-### `fetch`
-Fetch data from a URL. Supports template expressions for dynamic URLs.
-
-::: v-pre
-```yaml
-- fetch:
-    url: https://api.example.com/search?q=${{ args.query }}
-    headers:
-      Accept: application/json
-```
-:::
-
-### `map`
-
-::: v-pre
-Transform each item in the result array. Use `${{ item.xxx }}` for field access and `${{ index }}` for position.
-
-```yaml
-- map:
-    rank: ${{ index + 1 }}
-    title: ${{ item.title }}
-    url: https://example.com${{ item.path }}
-```
-:::
-
-### `limit`
-Truncate results to N items.
-
-::: v-pre
-```yaml
-- limit: ${{ args.limit }}
-```
-:::
-
-### `filter`
-Filter items by condition.
-
-::: v-pre
-```yaml
-- filter: ${{ item.score > 100 }}
-```
-:::
-
-### `download`
-Download media files.
-
-::: v-pre
-```yaml
-- download:
-    url: ${{ item.imageUrl }}
-    dir: ./downloads
-    filename: ${{ item.title | sanitize }}.jpg
-```
-:::
-
-## Template Expressions
-
-::: v-pre
-Use `${{ ... }}` for dynamic values:
-
-| Expression | Description |
-|-----------|-------------|
-| `${{ args.limit }}` | CLI argument |
-| `${{ item.title }}` | Current item field |
-| `${{ index }}` | Current index (0-based) |
-| `${{ item.x \| sanitize }}` | Pipe filters |
-:::
-
-## Real Example
-
-See [`src/clis/hackernews/top.yaml`](https://github.com/jackwener/opencli/blob/main/src/clis/hackernews/top.yaml).
-
-## Guardrails
-
-- Add fallbacks for optional fields in `map` expressions when upstream payloads may be sparse.
-- Keep template expressions short and readable. If the expression starts looking like a mini program, switch to TypeScript.
-- If you add a new adapter, also add the matching doc page plus index/sidebar entries so `doc-coverage` stays green.

package/docs/guide/browser-bridge.md

@@ -1,49 +0,0 @@
-# Browser Bridge Setup
-
-> **⚠️ Important**: Browser commands reuse your Chrome login session. You must be logged into the target website in Chrome before running commands.
-
-OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
-
-## Extension Installation
-
-### Method 1: Download Pre-built Release (Recommended)
-
-1. Go to the GitHub [Releases page](https://github.com/jackwener/opencli/releases) and download the latest `opencli-extension.zip`.
-2. Unzip the file and open `chrome://extensions`, enable **Developer mode** (top-right toggle).
-3. Click **Load unpacked** and select the unzipped folder.
-
-### Method 2: Load Unpacked Source (For Developers)
-
-1. Open `chrome://extensions` and enable **Developer mode**.
-2. Click **Load unpacked** and select the `extension/` directory from the repository.
-
-## Verification
-
-That's it! The daemon auto-starts when you run any browser command. No tokens, no manual configuration.
-
-```bash
-opencli doctor            # Check extension + daemon connectivity
-```
-
-## How It Works
-
-```
-┌─────────────┐     WebSocket      ┌──────────────┐     Chrome API     ┌─────────┐
-│  opencli    │ ◄──────────────► │  micro-daemon │ ◄──────────────► │  Chrome  │
-│  (Node.js)  │    localhost:19825  │  (auto-start) │    Extension       │ Browser  │
-└─────────────┘                    └──────────────┘                    └─────────┘
-```
-
-The daemon manages the WebSocket connection between your CLI commands and the Chrome extension. The extension executes JavaScript in the context of web pages, with access to the logged-in session.
-
-## Daemon Lifecycle
-
-The daemon auto-starts on first browser command and stays alive for **4 hours** by default. It exits only when both conditions are met: no CLI requests for the timeout period AND no Chrome extension connected.
-
-```bash
-opencli daemon status    # Check daemon state (PID, uptime, extension, memory)
-opencli daemon stop      # Graceful shutdown
-opencli daemon restart   # Stop + restart
-```
-
-Override the timeout via the `OPENCLI_DAEMON_TIMEOUT` environment variable (milliseconds). Set to `0` to keep the daemon alive indefinitely.