@jackwener/opencli 1.6.1 → 1.6.3

package/docs/superpowers/specs/2026-03-28-perf-smart-wait-design.md

@@ -1,170 +0,0 @@
-# Performance: Smart Wait & INTERCEPT Fix
-
-**Date**: 2026-03-28
-**Status**: Approved
-
-## Problem
-
-Three distinct performance/correctness issues:
-
-1. **INTERCEPT strategy semantic bug**: After `installInterceptor()` + `goto()`, adapters call `wait(N)` — which now uses `waitForDomStableJs` and returns early when the DOM settles. But DOM-settle != network capture. The API response may arrive *after* DOM is stable, causing `getInterceptedRequests()` to return an empty array.
-
-2. **Blind `wait(N)` in adapters**: ~30 high-traffic adapters (Twitter family, Medium, Substack, etc.) call `wait(5)` waiting for React/Vue to hydrate. These should wait for a specific DOM element to appear, not a fixed cap.
-
-3. **Daemon cold-start polling**: Fixed 300ms poll loop means ~600ms before first successful `isExtensionConnected()` check, even though the daemon is typically ready in 500–800ms.
-
-## Design
-
-### Layer 1 — `waitForCapture()` (correctness fix + perf)
-
-Add `waitForCapture(timeout?: number): Promise<void>` to `IPage`.
-
-Polls `window.__opencli_xhr.length > 0` every 100ms inside the browser tab. Resolves as soon as ≥1 capture arrives; rejects after `timeout` seconds.
-
-```typescript
-// dom-helpers.ts
-export function waitForCaptureJs(maxMs: number): string {
-  return `
-    new Promise((resolve, reject) => {
-      const deadline = Date.now() + ${maxMs};
-      const check = () => {
-        if ((window.__opencli_xhr || []).length > 0) return resolve('captured');
-        if (Date.now() > deadline) return reject(new Error('No capture within ${maxMs / 1000}s'));
-        setTimeout(check, 100);
-      };
-      check();
-    })
-  `;
-}
-```
-
-`page.ts` and `cdp.ts` implement `waitForCapture()` by calling `waitForCaptureJs`.
-
-**All INTERCEPT adapters** replace `wait(N)` → `waitForCapture(N+2)` (slightly longer timeout as safety margin).
-
-`stepIntercept` in `pipeline/steps/intercept.ts` replaces its internal `wait(timeout)` with `waitForCapture(timeout)`.
-
-**Expected gain**: 36kr hot/search: 6s → ~1–2s. Twitter search/followers: 5–8s → ~1–3s.
-
-### Layer 2 — `wait({ selector })` (semantic precision)
-
-Extend `WaitOptions` with `selector?: string`.
-
-Add `waitForSelectorJs(selector, timeoutMs)` to `dom-helpers.ts` — polls `document.querySelector(selector)` every 100ms, resolves on first match, rejects on timeout.
-
-```typescript
-// types.ts
-export interface WaitOptions {
-  text?: string;
-  selector?: string;   // NEW
-  time?: number;
-  timeout?: number;
-}
-```
-
-```typescript
-// dom-helpers.ts
-export function waitForSelectorJs(selector: string, timeoutMs: number): string {
-  return `
-    new Promise((resolve, reject) => {
-      const deadline = Date.now() + ${timeoutMs};
-      const check = () => {
-        if (document.querySelector(${JSON.stringify(selector)})) return resolve('found');
-        if (Date.now() > deadline) return reject(new Error('Selector not found: ' + ${JSON.stringify(selector)}));
-        setTimeout(check, 100);
-      };
-      check();
-    })
-  `;
-}
-```
-
-`page.ts` and `cdp.ts` handle `selector` branch in `wait()`.
-
-**High-impact adapter changes**:
-
-| Adapter | Old | New |
-|---------|-----|-----|
-| `twitter/*` (15 adapters) | `wait(5)` | `wait({ selector: '[data-testid="primaryColumn"]', timeout: 6 })` |
-| `twitter/reply.ts` | `wait(5)` | `wait({ selector: '[data-testid="tweetTextarea_0"]', timeout: 8 })` |
-| `medium/utils.ts` | `wait(5)` + inline 3s setTimeout | `wait({ selector: 'article', timeout: 8 })` + remove inline sleep |
-| `substack/utils.ts` | `wait(5)` × 2 | `wait({ selector: 'article', timeout: 8 })` |
-| `bloomberg/news.ts` | `wait(5)` | `wait({ selector: 'article', timeout: 6 })` |
-| `sinablog/utils.ts` | `wait(5)` | `wait({ selector: 'article, .article', timeout: 6 })` |
-| `producthunt` (already covered by layer 1) | — | — |
-
-**Expected gain**: Twitter commands: 5s → ~0.5–2s. Medium: 8s → ~1–3s.
-
-### Layer 3 — Daemon exponential backoff (cold-start)
-
-Replace fixed 300ms poll in `_ensureDaemon()` (`browser/mcp.ts`) with exponential backoff:
-
-```typescript
-// before
-while (Date.now() < deadline) {
-  await new Promise(resolve => setTimeout(resolve, 300));
-  if (await isExtensionConnected()) return;
-}
-
-// after
-const backoffs = [50, 100, 200, 400, 800, 1500, 3000];
-let i = 0;
-while (Date.now() < deadline) {
-  await new Promise(resolve => setTimeout(resolve, backoffs[Math.min(i++, backoffs.length - 1)]));
-  if (await isExtensionConnected()) return;
-}
-```
-
-**Expected gain**: First cold-start check succeeds at ~150ms instead of ~600ms.
-
-## Files Changed
-
-### New / Modified (framework)
-- `src/types.ts` — `WaitOptions.selector`, `IPage.waitForCapture()`
-- `src/browser/dom-helpers.ts` — `waitForCaptureJs()`, `waitForSelectorJs()`
-- `src/browser/page.ts` — `waitForCapture()`, `wait()` selector branch
-- `src/browser/cdp.ts` — `waitForCapture()`, `wait()` selector branch
-- `src/browser/mcp.ts` — exponential backoff in `_ensureDaemon()`
-- `src/pipeline/steps/intercept.ts` — use `waitForCapture()`
-
-### Modified (adapters — Layer 1, INTERCEPT)
-- `src/clis/36kr/hot.ts`
-- `src/clis/36kr/search.ts`
-- `src/clis/twitter/search.ts`
-- `src/clis/twitter/followers.ts`
-- `src/clis/twitter/following.ts`
-- `src/clis/producthunt/hot.ts`
-- `src/clis/producthunt/browse.ts`
-
-### Modified (adapters — Layer 2, selector)
-- `src/clis/twitter/reply.ts`
-- `src/clis/twitter/follow.ts`
-- `src/clis/twitter/unfollow.ts`
-- `src/clis/twitter/like.ts`
-- `src/clis/twitter/bookmark.ts`
-- `src/clis/twitter/unbookmark.ts`
-- `src/clis/twitter/block.ts`
-- `src/clis/twitter/unblock.ts`
-- `src/clis/twitter/hide-reply.ts`
-- `src/clis/twitter/notifications.ts`
-- `src/clis/twitter/profile.ts`
-- `src/clis/twitter/thread.ts`
-- `src/clis/twitter/timeline.ts`
-- `src/clis/twitter/delete.ts`
-- `src/clis/twitter/reply-dm.ts`
-- `src/clis/medium/utils.ts`
-- `src/clis/substack/utils.ts`
-- `src/clis/bloomberg/news.ts`
-- `src/clis/sinablog/utils.ts`
-
-## Delivery Order
-
-1. Layer 1 (`waitForCapture`) — correctness fix, highest ROI
-2. Layer 3 (backoff) — 3-line change, zero risk
-3. Layer 2 (`wait({ selector })`) — largest adapter surface, can be done per-site
-
-## Testing
-
-- Unit tests: `waitForCaptureJs`, `waitForSelectorJs` exported and tested in `dom-helpers.test.ts` (if exists) or new test file
-- Adapter tests: existing tests must continue to pass (mock `page.wait` / `page.waitForCapture`)
-- Run: `npx vitest run --project unit --project adapter`

package/docs/superpowers/specs/2026-03-31-daemon-lifecycle-redesign.md

@@ -1,208 +0,0 @@
-# Daemon Lifecycle Redesign
-
-## Problem
-
-OpenCLI's daemon auto-exits after 5 minutes of idle time. During typical development
-cycles (write code → test → modify → test again), coding intervals frequently exceed
-5 minutes. Each restart incurs 2-4 seconds of overhead (process spawn + Extension
-WebSocket reconnection), creating a noticeable and frustrating delay.
-
-The current design treats the daemon as a disposable process, but the actual cost
-profile doesn't justify this:
-
-| Cost of staying alive | Cost of restarting |
-|-----------------------|--------------------|
-| ~12 MB memory, 0% CPU | 2-4 seconds delay per restart |
-
-The restart cost far outweighs the idle cost.
-
-## Solution
-
-Replace the aggressive 5-minute fixed timeout with a long-lived daemon model. The
-daemon stays running for hours, exits only when truly abandoned, and reconnects to
-the Chrome Extension faster when needed.
-
-Four changes:
-
-1. Extend idle timeout from 5 minutes to 4 hours (configurable)
-2. Require dual idle condition: both no CLI requests AND no Extension connection
-3. Reduce Extension WebSocket reconnect backoff cap from 60s to 5s
-4. Add `opencli daemon status/stop/restart` commands
-
-## Design
-
-### Timeout Strategy
-
-**Current behavior:** A single idle timer resets on each HTTP request. After 5
-minutes without a request, the daemon calls `process.exit(0)`.
-
-**New behavior:** The daemon tracks two activity signals independently:
-
-- **CLI activity:** timestamp of the last HTTP request from any CLI invocation
-- **Extension activity:** whether a WebSocket connection from the Chrome Extension
-  is currently open
-
-The exit countdown starts only when BOTH conditions are met simultaneously:
-
-- No CLI request for `IDLE_TIMEOUT` duration
-- No Extension WebSocket connection
-
-If either signal is active, the daemon stays alive. This means:
-
-- A connected Extension keeps the daemon alive indefinitely (user has Chrome open,
-  likely still working)
-- Recent CLI activity keeps the daemon alive even if Extension temporarily
-  disconnects (Chrome restarting, Extension updating)
-
-**Timeout value:** 4 hours by default, configurable via `OPENCLI_DAEMON_TIMEOUT`
-environment variable. Value in milliseconds. Set to `0` to disable timeout entirely.
-
-```typescript
-const DEFAULT_IDLE_TIMEOUT = 4 * 60 * 60 * 1000; // 4 hours
-const IDLE_TIMEOUT = Number(process.env.OPENCLI_DAEMON_TIMEOUT ?? DEFAULT_IDLE_TIMEOUT);
-```
-
-**Timer implementation:**
-
-```
-resetIdleTimer():
-  clear existing timer
-  if Extension is connected:
-    do not start timer (Extension connection keeps daemon alive)
-    return
-  start timer with IDLE_TIMEOUT duration
-  on timeout: process.exit(0)
-
-On CLI HTTP request:
-  update lastRequestTime
-  resetIdleTimer()
-
-On Extension WebSocket connect:
-  clear timer (Extension keeps daemon alive)
-
-On Extension WebSocket disconnect:
-  elapsed = now - lastRequestTime
-  if elapsed >= IDLE_TIMEOUT:
-    process.exit(0)  // CLI has been idle long enough already
-  else:
-    start timer with (IDLE_TIMEOUT - elapsed)  // count remaining time
-```
-
-### Extension Fast Reconnect
-
-**Current behavior:** When the Extension loses its WebSocket connection to the
-daemon, it reconnects with exponential backoff: 2s → 4s → 8s → 16s → 32s → 60s
-(capped). In the worst case, the Extension waits up to 60 seconds before attempting
-reconnection.
-
-**New behavior:** Cap the backoff at 5 seconds instead of 60 seconds.
-
-```typescript
-// extension/src/background.ts
-const WS_RECONNECT_MAX_DELAY = 5000; // was 60000
-```
-
-Rationale: with a 4-hour daemon timeout, the daemon is almost always running. Long
-backoff intervals are unnecessary and only increase reconnection latency. A 5-second
-cap means the Extension reconnects within 5 seconds of the daemon becoming available.
-
-### Daemon Management Commands
-
-Add three new CLI commands for daemon lifecycle management:
-
-**`opencli daemon status`**
-
-Queries the daemon's `/status` endpoint (new) and displays:
-
-```
-Daemon: running (PID 12345)
-Uptime: 2h 15m
-Extension: connected
-Last CLI request: 8 min ago
-Memory: 12.3 MB
-Port: 19825
-```
-
-If daemon is not running:
-
-```
-Daemon: not running
-```
-
-**`opencli daemon stop`**
-
-Sends a `POST /shutdown` request to the daemon, which triggers a graceful shutdown:
-reject pending requests with a shutdown message, close WebSocket connections, close
-HTTP server, then exit.
-
-**`opencli daemon restart`**
-
-Equivalent to `stop` followed by spawning a new daemon. Useful when the daemon gets
-into a bad state.
-
-**Daemon-side endpoints:**
-
-- `GET /status` — returns JSON with PID, uptime, extension connection state, last
-  request time, memory usage
-- `POST /shutdown` — initiates graceful shutdown
-
-Both endpoints require the same `X-OpenCLI` header as existing endpoints for CSRF
-protection.
-
-### CLI Connection Experience
-
-**Current behavior:** When daemon is running but Extension is not connected, the CLI
-silently polls every 300ms and eventually times out with a generic error.
-
-**New behavior:** Show a progress indicator and actionable message:
-
-```
-⏳ Waiting for Chrome extension to connect...
-   Make sure Chrome is open and the OpenCLI extension is enabled.
-```
-
-Poll interval reduced from 300ms to 200ms for slightly faster detection.
-
-If the daemon is not running at all (connection refused), the CLI spawns it as before
-and shows:
-
-```
-⏳ Starting daemon...
-```
-
-## Files Changed
-
-| File | Change | Estimated LOC |
-|------|--------|---------------|
-| `src/daemon.ts` | Dual-condition idle timeout, `/status` endpoint, `/shutdown` endpoint | ~40 |
-| `extension/src/background.ts` | `WS_RECONNECT_MAX_DELAY` 60000 → 5000 | 1 |
-| `src/browser/daemon-client.ts` | Better connection-waiting UX, 200ms poll interval | ~20 |
-| `src/commands/daemon.ts` (new) | `status`, `stop`, `restart` subcommands | ~80 |
-| `src/constants.ts` | `DEFAULT_IDLE_TIMEOUT` constant | 2 |
-
-**Total: ~143 lines of new/changed code.**
-
-## Backward Compatibility
-
-- No breaking changes to CLI commands or Extension protocol
-- Existing `OPENCLI_DAEMON_PORT` environment variable continues to work
-- The only observable behavior change: daemon stays alive longer
-- New `daemon` subcommands are additive
-
-## Testing
-
-- Unit test: idle timer starts only when both CLI and Extension are idle
-- Unit test: idle timer is cleared when Extension connects
-- Unit test: `/status` returns correct state
-- Unit test: `/shutdown` triggers graceful exit
-- Integration test: daemon survives 10+ minutes without CLI requests while Extension
-  is connected
-- Integration test: daemon exits after configured timeout when fully idle
-- Integration test: `opencli daemon status/stop/restart` work correctly
-
-## Out of Scope
-
-- OS-level daemon management (launchd/systemd) — can be added later if needed
-- Daemon auto-update mechanism
-- Multi-daemon coordination
-- Persistent daemon state across restarts

package/docs/superpowers/specs/2026-04-02-browse-skill-testing-design.md

@@ -1,144 +0,0 @@
-# Browse Skill Testing Design
-
-Two-layer testing framework for `opencli browse` commands and the
-Claude Code skill integration.
-
-## Goal
-
-Verify that `opencli browse` works reliably on real websites and that
-Claude Code can use the skill to complete browser tasks end-to-end.
-
-## Architecture
-
-```
-autoresearch/
-├── browse-tasks.json       ← 59 task definitions with browse command sequences
-├── eval-browse.ts          ← Layer 1: deterministic browse command testing
-├── eval-skill.ts           ← Layer 2: Claude Code skill E2E testing
-├── run-browse.sh           ← Launch Layer 1
-├── run-skill.sh            ← Launch Layer 2
-├── baseline-browse.txt     ← Layer 1 best score
-├── baseline-skill.txt      ← Layer 2 best score
-└── results/                ← Per-run results (gitignored)
-```
-
-## Layer 1: Deterministic Browse Command Testing
-
-Tests `opencli browse` commands directly on real websites. No LLM
-involved — pure command reliability testing.
-
-### How It Works
-
-Each task defines a sequence of browse commands and a judge for the
-last command's output:
-
-```json
-{
-  "name": "hn-top-stories",
-  "steps": [
-    "opencli browse open https://news.ycombinator.com",
-    "opencli browse eval \"JSON.stringify([...document.querySelectorAll('.titleline a')].slice(0,5).map(a=>({title:a.textContent,url:a.href})))\""
-  ],
-  "judge": { "type": "arrayMinLength", "minLength": 5 }
-}
-```
-
-### Execution
-
-```bash
-./autoresearch/run-browse.sh
-```
-
-- Runs all 59 tasks serially
-- Each task: execute steps → judge last step output → pass/fail
-- `opencli browse close` between tasks for clean state
-- Expected: ~2 minutes, $0 cost
-
-### Task Categories
-
-| Category | Count | Example |
-|----------|-------|---------|
-| extract | 9 | Open page, eval JS to extract data |
-| list | 10 | Open page, eval JS to extract array |
-| search | 6 | Open, type query, keys Enter, eval results |
-| nav | 7 | Open, click link, eval new page title |
-| scroll | 5 | Open, scroll, eval footer/hidden content |
-| form | 6 | Open, type into fields, eval field values |
-| complex | 6 | Multi-step: open → click → navigate → extract |
-| bench | 10 | Test set (various) |
-
-## Layer 2: Claude Code Skill E2E Testing
-
-Spawns Claude Code with the opencli-operate skill to complete tasks
-autonomously using browse commands.
-
-### How It Works
-
-```bash
-claude -p \
-  --system-prompt "$(cat skills/opencli-operate/SKILL.md)" \
-  --dangerously-skip-permissions \
-  --allowedTools "Bash(opencli:*)" \
-  --output-format json \
-  "用 opencli browse 完成任务：Extract the top 5 stories from Hacker News with title and score. Start URL: https://news.ycombinator.com"
-```
-
-### Execution
-
-```bash
-./autoresearch/run-skill.sh
-```
-
-- Runs all 59 tasks serially
-- Each task: spawn Claude Code → it uses browse commands autonomously → judge output
-- Expected: ~20 minutes, ~$5-10
-
-### Judge
-
-Both layers use the same judge types:
-
-| Type | Description |
-|------|-------------|
-| `contains` | Output contains a substring |
-| `arrayMinLength` | Output is an array with ≥ N items |
-| `arrayFieldsPresent` | Array items have required fields |
-| `nonEmpty` | Output is non-empty |
-| `matchesPattern` | Output matches a regex |
-
-## Output Format
-
-```
-🔬 Layer 1: Browse Commands — 59 tasks
-
-  [1/59] extract-title-example... ✓ (0.5s)
-  [2/59] hn-top-stories... ✓ (1.2s)
-  ...
-
-  Score: 55/59 (93%)
-  Time: 2min
-  Cost: $0
-
-🔬 Layer 2: Skill E2E — 59 tasks
-
-  [1/59] extract-title-example... ✓ (8s, $0.01)
-  [2/59] hn-top-stories... ✓ (15s, $0.08)
-  ...
-
-  Score: 52/59 (88%)
-  Time: 20min
-  Cost: $6.50
-```
-
-## Constraints
-
-- All 59 tasks run on real websites (no mocks)
-- Layer 1: zero LLM cost, ~2 min
-- Layer 2: ~$5-10 LLM cost, ~20 min
-- Results saved to `autoresearch/results/` (gitignored)
-- Baselines tracked in `baseline-browse.txt` and `baseline-skill.txt`
-
-## Success Criteria
-
-- Layer 1 ≥ 90% (browse commands work on real sites)
-- Layer 2 ≥ 85% (Claude Code can use skill effectively)
-- Both layers cover all 8 task categories

package/docs/zh/adapters/index.md

@@ -1,5 +0,0 @@
-# 所有适配器
-
-运行 `opencli list` 查看完整命令列表。
-
-详细文档请参考 [英文版本](/adapters/)。

package/docs/zh/advanced/cdp.md

@@ -1,3 +0,0 @@
-# Chrome DevTools Protocol
-
-详细文档请参考 [英文版本](/advanced/cdp)。

package/docs/zh/developer/contributing.md

@@ -1,24 +0,0 @@
-# 贡献指南
-
-详细贡献指南请参考 [英文版本](/developer/contributing)。
-
-## 快速开始
-
-```bash
-git clone git@github.com:<your-username>/opencli.git
-cd opencli
-npm install
-npm run build
-npx tsc --noEmit
-npx vitest run src/
-```
-
-## 提交规范
-
-使用 [Conventional Commits](https://www.conventionalcommits.org/)：
-
-```
-feat(twitter): add thread command
-fix(browser): handle CDP timeout gracefully
-docs: update CONTRIBUTING.md
-```

package/docs/zh/guide/browser-bridge.md

@@ -1,36 +0,0 @@
-# Browser Bridge 设置
-
-> **⚠️ 重要**: 浏览器命令复用你的 Chrome 登录会话。运行命令前必须在 Chrome 中登录目标网站。
-
-OpenCLI 通过轻量级 **Browser Bridge** Chrome 扩展 + 微守护进程连接浏览器（零配置，自动启动）。
-
-## 扩展安装
-
-### 方法 1：下载预构建版本（推荐）
-
-1. 前往 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension.zip`。
-2. 解压后打开 `chrome://extensions`，启用**开发者模式**。
-3. 点击**加载已解压的扩展程序**，选择解压后的文件夹。
-
-### 方法 2：加载源码（开发者）
-
-1. 打开 `chrome://extensions`，启用**开发者模式**。
-2. 点击**加载已解压的扩展程序**，选择仓库中的 `extension/` 目录。
-
-## 验证
-
-```bash
-opencli doctor            # 检查扩展 + 守护进程连接
-```
-
-## Daemon 生命周期
-
-Daemon 在首次运行浏览器命令时自动启动，默认保持 **4 小时**。仅当 CLI 空闲超时**且** Chrome 扩展未连接时才会退出。
-
-```bash
-opencli daemon status    # 查看 daemon 状态（PID、运行时长、扩展连接、内存）
-opencli daemon stop      # 优雅关停
-opencli daemon restart   # 重启
-```
-
-通过 `OPENCLI_DAEMON_TIMEOUT` 环境变量覆盖超时时间（毫秒）。设为 `0` 则永不超时。