@jackwener/opencli 1.0.6 → 1.1.1

package/docs/adapters/browser/weread.md

@@ -0,0 +1,48 @@
+# 微信读书 (WeRead)
+
+**Mode**: 🔐 Browser · **Domain**: `weread.qq.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli weread shelf` | List books on your bookshelf |
+| `opencli weread search` | Search books on WeRead |
+| `opencli weread book` | View book details |
+| `opencli weread ranking` | Book rankings by category |
+| `opencli weread notebooks` | List books that have highlights or notes |
+| `opencli weread highlights` | List your highlights (underlines) in a book |
+| `opencli weread notes` | List your notes (thoughts) on a book |
+
+## Usage Examples
+
+```bash
+# View your bookshelf
+opencli weread shelf --limit 20
+
+# Search books
+opencli weread search "三体"
+
+# View book details
+opencli weread book <book-id>
+
+# Book rankings
+opencli weread ranking --limit 10
+
+# List books with notes/highlights
+opencli weread notebooks
+
+# View highlights for a book
+opencli weread highlights <book-id>
+
+# View your notes
+opencli weread notes <book-id>
+
+# JSON output
+opencli weread shelf -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** weread.qq.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

package/docs/adapters/browser/wikipedia.md

@@ -0,0 +1,30 @@
+# Wikipedia
+
+**Mode**: 🌐 Public · **Domain**: `wikipedia.org`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli wikipedia search` | Search Wikipedia articles |
+| `opencli wikipedia summary` | Get Wikipedia article summary |
+
+## Usage Examples
+
+```bash
+# Search articles
+opencli wikipedia search "quantum computing" --limit 10
+
+# Get article summary
+opencli wikipedia summary --title "Artificial intelligence"
+
+# Search in other languages
+opencli wikipedia search "人工智能" --lang zh
+
+# JSON output
+opencli wikipedia search "Rust" -f json
+```
+
+## Prerequisites
+
+- No browser required — uses public Wikipedia API

package/docs/adapters/browser/xiaohongshu.md

@@ -9,9 +9,13 @@
 | `opencli xiaohongshu search` | |
 | `opencli xiaohongshu notifications` | |
 | `opencli xiaohongshu feed` | |
-| `opencli xiaohongshu me` | |
 | `opencli xiaohongshu user` | |
 | `opencli xiaohongshu download` | |
+| `opencli xiaohongshu creator-notes` | |
+| `opencli xiaohongshu creator-note-detail` | |
+| `opencli xiaohongshu creator-notes-summary` | |
+| `opencli xiaohongshu creator-profile` | |
+| `opencli xiaohongshu creator-stats` | |
 
 ## Usage Examples
 

package/docs/adapters/desktop/chatgpt.md

@@ -14,7 +14,7 @@ The current built-in commands use native AppleScript automation — no extra lau
 - `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.
+- `opencli chatgpt read`: Read the last visible message from the focused ChatGPT window via the Accessibility tree.
 
 ## Approach 2: CDP (Advanced, Electron Debug Mode)
 
@@ -33,11 +33,11 @@ export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9224"
 
 ## How It Works
 
-- **AppleScript mode**: Uses `osascript` and `pbcopy`/`pbpaste` for clipboard-based text transfer.
+- **AppleScript mode**: Uses `osascript` to control ChatGPT, `pbcopy`/`pbpaste` to paste prompts, and the macOS Accessibility tree to read visible chat messages.
 - **CDP mode**: Connects via Chrome DevTools Protocol to the Electron renderer process.
 
 ## Limitations
 
 - macOS only (AppleScript dependency)
 - AppleScript mode requires Accessibility permissions
-- `read` command copies the last response — earlier messages need manual scroll
+- `read` returns the last visible message in the focused ChatGPT window — scroll first if the message you want is not visible

package/docs/adapters/index.md

@@ -14,6 +14,7 @@ Run `opencli list` for the live registry.
 | **[xueqiu](/adapters/browser/xueqiu)** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` | 🔐 Browser |
 | **[youtube](/adapters/browser/youtube)** | `search` `video` `transcript` | 🔐 Browser |
 | **[v2ex](/adapters/browser/v2ex)** | `hot` `latest` `topic` `daily` `me` `notifications` | 🌐 / 🔐 |
+| **[bloomberg](/adapters/browser/bloomberg)** | `main` `markets` `economics` `industries` `tech` `politics` `businessweek` `opinions` `feeds` `news` | 🌐 / 🔐 |
 | **[weibo](/adapters/browser/weibo)** | `hot` | 🔐 Browser |
 | **[linkedin](/adapters/browser/linkedin)** | `search` | 🔐 Browser |
 | **[coupang](/adapters/browser/coupang)** | `search` `add-to-cart` | 🔐 Browser |
@@ -21,6 +22,12 @@ Run `opencli list` for the live registry.
 | **[ctrip](/adapters/browser/ctrip)** | `search` | 🔐 Browser |
 | **[reuters](/adapters/browser/reuters)** | `search` | 🔐 Browser |
 | **[smzdm](/adapters/browser/smzdm)** | `search` | 🔐 Browser |
+| **[jike](/adapters/browser/jike)** | `feed` `search` `post` `topic` `user` `create` `comment` `like` `repost` `notifications` | 🔐 Browser |
+| **[jimeng](/adapters/browser/jimeng)** | `generate` `history` | 🔐 Browser |
+| **[linux-do](/adapters/browser/linux-do)** | `hot` `latest` `categories` `category` `search` `topic` | 🔐 Browser |
+| **[chaoxing](/adapters/browser/chaoxing)** | `assignments` `exams` | 🔐 Browser |
+| **[grok](/adapters/browser/grok)** | `ask` | 🔐 Browser |
+| **[weread](/adapters/browser/weread)** | `shelf` `search` `book` `ranking` `notebooks` `highlights` `notes` | 🔐 Browser |
 
 ## Public API Adapters
 
@@ -32,6 +39,12 @@ Run `opencli list` for the live registry.
 | **[apple-podcasts](/adapters/browser/apple-podcasts)** | `search` `episodes` `top` | 🌐 Public |
 | **[xiaoyuzhou](/adapters/browser/xiaoyuzhou)** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
 | **[yahoo-finance](/adapters/browser/yahoo-finance)** | `quote` | 🌐 Public |
+| **[arxiv](/adapters/browser/arxiv)** | `search` `paper` | 🌐 Public |
+| **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
+| **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
+| **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |
+| **[stackoverflow](/adapters/browser/stackoverflow)** | `hot` `search` `bounties` `unanswered` | 🌐 Public |
+| **[wikipedia](/adapters/browser/wikipedia)** | `search` `summary` | 🌐 Public |
 
 ## Desktop Adapters
 

package/docs/advanced/download.md

@@ -26,23 +26,23 @@ brew install yt-dlp
 
 ```bash
 # Download images/videos from Xiaohongshu note
-opencli xiaohongshu download --note_id abc123 --output ./xhs
+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
 
 # Download Twitter media from user
-opencli twitter download --username elonmusk --limit 20 --output ./twitter
+opencli twitter download elonmusk --limit 20 --output ./twitter
 
 # Download single tweet media
 opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
 
 # Export Zhihu article to Markdown
-opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
 
 # Export with local images
-opencli zhihu download --url "https://zhuanlan.zhihu.com/p/xxx" --download-images
+opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --download-images
 ```
 
 ## Pipeline Step (YAML Adapters)

package/docs/developer/architecture.md

@@ -34,8 +34,14 @@ OpenCLI is built on a **Dual-Engine Architecture** that supports both declarativ
 ### Registry (`src/registry.ts`)
 Central command registry. All adapters register their commands via the `cli()` function with metadata: site, name, description, domain, strategy, args, columns.
 
-### Engine (`src/engine.ts`)
-Command discovery and execution engine. Discovers commands from the registry, parses arguments, executes the appropriate adapter, and routes output through the formatter.
+### Discovery (`src/discovery.ts`)
+CLI discovery and manifest loading. Discovers commands from YAML and TypeScript adapter files, parses YAML pipelines, and registers them into the central registry.
+
+### Execution (`src/execution.ts`)
+Command execution: argument validation, lazy loading of adapter modules, and executing the appropriate handler function.
+
+### Commander Adapter (`src/commanderAdapter.ts`)
+Bridges the Registry commands to Commander.js subcommands. Handles positional args, named options, browser session wiring, and output formatting. Isolates all Commander-specific logic so the core is framework-agnostic.
 
 ### Browser (`src/browser.ts`)
 Manages connections to Chrome via the Browser Bridge WebSocket daemon. Handles JSON-RPC messaging, tab management, and extension/standalone mode switching.
@@ -60,15 +66,22 @@ OpenCLI uses a 3-tier authentication strategy:
 | `public` | Direct HTTP fetch, no auth | Public APIs (HackerNews, BBC) |
 | `cookie` | Reuse Chrome cookies via Browser Bridge | Logged-in sites (Bilibili, Zhihu) |
 | `header` | Custom auth headers | API-key based services |
+| `intercept` | Network request interception | GraphQL/XHR capture (Twitter) |
+| `ui` | DOM interaction via accessibility snapshot | Desktop apps, write operations |
 
 ## Directory Structure
 
 ```
 src/
 ├── main.ts              # Entry point
-├── engine.ts            # Command execution engine
+├── cli.ts               # Commander.js CLI setup + built-in commands
+├── commanderAdapter.ts  # Registry → Commander bridge
+├── discovery.ts         # CLI discovery, manifest loading, YAML parsing
+├── execution.ts         # Arg validation, command execution
 ├── registry.ts          # Command registry
-├── browser.ts           # Browser Bridge connection
+├── serialization.ts     # Command serialization helpers
+├── runtime.ts           # Browser session & timeout management
+├── browser/             # Browser Bridge connection
 ├── output.ts            # Output formatting
 ├── doctor.ts            # Diagnostic tool
 ├── pipeline/            # YAML pipeline engine

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jackwener/opencli",
-  "version": "1.0.6",
+  "version": "1.1.1",
   "publishConfig": {
     "access": "public"
   },

package/scripts/check-doc-coverage.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# check-doc-coverage.sh — Verify every adapter in src/clis/ has a doc page.
+#
+# Exit codes:
+#   0 — all adapters have docs
+#   1 — at least one adapter is missing documentation
+#
+# Usage:
+#   bash scripts/check-doc-coverage.sh          # report only
+#   bash scripts/check-doc-coverage.sh --strict  # exit 1 on missing docs
+
+set -euo pipefail
+
+STRICT=false
+if [[ "${1:-}" == "--strict" ]]; then
+  STRICT=true
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+SRC_DIR="$ROOT_DIR/src/clis"
+DOCS_DIR="$ROOT_DIR/docs/adapters"
+
+missing=()
+covered=0
+total=0
+
+for adapter_dir in "$SRC_DIR"/*/; do
+  adapter_name="$(basename "$adapter_dir")"
+  total=$((total + 1))
+
+  # Check if doc exists in browser/ or desktop/ subdirectories
+  if [[ -f "$DOCS_DIR/browser/$adapter_name.md" ]] || \
+     [[ -f "$DOCS_DIR/desktop/$adapter_name.md" ]]; then
+    covered=$((covered + 1))
+  else
+    # Handle directory name mismatches (e.g., discord-app -> discord)
+    alt_name="${adapter_name%-app}"
+    if [[ "$alt_name" != "$adapter_name" ]] && \
+       { [[ -f "$DOCS_DIR/browser/$alt_name.md" ]] || \
+         [[ -f "$DOCS_DIR/desktop/$alt_name.md" ]]; }; then
+      covered=$((covered + 1))
+    else
+      missing+=("$adapter_name")
+    fi
+  fi
+done
+
+echo "📊 Doc Coverage: $covered/$total adapters documented"
+echo ""
+
+if [[ ${#missing[@]} -gt 0 ]]; then
+  echo "⚠️  Missing docs for ${#missing[@]} adapter(s):"
+  for name in "${missing[@]}"; do
+    echo "   - $name  →  create docs/adapters/browser/$name.md or docs/adapters/desktop/$name.md"
+  done
+  echo ""
+  if $STRICT; then
+    echo "❌ Doc check failed (--strict mode)."
+    exit 1
+  else
+    echo "💡 Run with --strict to fail CI on missing docs."
+    exit 0
+  fi
+else
+  echo "✅ All adapters have documentation."
+  exit 0
+fi

package/scripts/copy-yaml.cjs

@@ -19,3 +19,10 @@ function walk(src, dst) {
 }
 
 walk('src/clis', 'dist/clis');
+
+// Copy external CLI registry to dist/
+const extSrc = 'src/external-clis.yaml';
+if (existsSync(extSrc)) {
+  mkdirSync('dist', { recursive: true });
+  copyFileSync(extSrc, 'dist/external-clis.yaml');
+}

package/src/browser/cdp.ts

@@ -8,7 +8,7 @@
  * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
  */
 
-import { WebSocket } from 'ws';
+import { WebSocket, type RawData } from 'ws';
 import type { IPage } from '../types.js';
 import { wrapForEval } from './utils.js';
 import {
@@ -63,12 +63,12 @@ export class CDPBridge {
         resolve(new CDPPage(this));
       });
 
-      ws.on('error', (err) => {
+      ws.on('error', (err: Error) => {
         clearTimeout(timeout);
         reject(err);
       });
 
-      ws.on('message', (data) => {
+      ws.on('message', (data: RawData) => {
         try {
           const msg = JSON.parse(data.toString());
           // Handle command responses
@@ -158,12 +158,17 @@ class CDPPage implements IPage {
   constructor(private bridge: CDPBridge) {}
 
   /** Navigate with proper load event waiting (P1 fix #3) */
-  async goto(url: string): Promise<void> {
+  async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     await this.bridge.send('Page.enable');
     const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000)
       .catch(() => {}); // Don't fail if event times out
     await this.bridge.send('Page.navigate', { url });
     await loadPromise;
+    // Post-load settle: SPA frameworks need extra time to render after load event
+    if (options?.waitUntil !== 'none') {
+      const settleMs = options?.settleMs ?? 1000;
+      await new Promise(resolve => setTimeout(resolve, settleMs));
+    }
   }
 
   async evaluate(js: string): Promise<any> {

package/src/browser/page.ts

@@ -42,7 +42,7 @@ export class Page implements IPage {
     return { workspace: this.workspace };
   }
 
-  async goto(url: string): Promise<void> {
+  async goto(url: string, options?: { waitUntil?: 'load' | 'none'; settleMs?: number }): Promise<void> {
     const result = await sendCommand('navigate', {
       url,
       ...this._workspaceOpt(),
@@ -52,6 +52,12 @@ export class Page implements IPage {
     if (result?.tabId) {
       this._tabId = result.tabId;
     }
+    // Post-load settle: the extension already waits for tab.status === 'complete',
+    // but SPA frameworks (React/Vue) need extra time to render after DOM load.
+    if (options?.waitUntil !== 'none') {
+      const settleMs = options?.settleMs ?? 1000;
+      await new Promise(resolve => setTimeout(resolve, settleMs));
+    }
   }
 
   /** Close the automation window in the extension */

package/src/build-manifest.ts

@@ -196,26 +196,29 @@ function scanYaml(filePath: string, site: string): ManifestEntry | null {
   }
 }
 
-function scanTs(filePath: string, site: string): ManifestEntry {
+function scanTs(filePath: string, site: string): ManifestEntry | null {
   // TS adapters self-register via cli() at import time.
   // We statically parse the source to extract metadata for the manifest stub.
   const baseName = path.basename(filePath, path.extname(filePath));
   const relativePath = `${site}/${baseName}.js`;
 
-  const entry: ManifestEntry = {
-    site,
-    name: baseName,
-    description: '',
-    strategy: 'cookie',
-    browser: true,
-    args: [],
-    type: 'ts',
-    modulePath: relativePath,
-  };
-
   try {
     const src = fs.readFileSync(filePath, 'utf-8');
 
+    // Helper/test modules should not appear as CLI commands in the manifest.
+    if (!/\bcli\s*\(/.test(src)) return null;
+
+    const entry: ManifestEntry = {
+      site,
+      name: baseName,
+      description: '',
+      strategy: 'cookie',
+      browser: true,
+      args: [],
+      type: 'ts',
+      modulePath: relativePath,
+    };
+
     // Extract description
     const descMatch = src.match(/description\s*:\s*['"`]([^'"`]*)['"`]/);
     if (descMatch) entry.description = descMatch[1];
@@ -244,11 +247,13 @@ function scanTs(filePath: string, site: string): ManifestEntry {
     if (argsBlock) {
       entry.args = parseTsArgsBlock(argsBlock);
     }
-  } catch {
-    // If parsing fails, fall back to empty metadata — module will self-register at runtime
-  }
 
-  return entry;
+    return entry;
+  } catch (err: any) {
+    // If parsing fails, log a warning (matching scanYaml behaviour) and skip the entry.
+    process.stderr.write(`Warning: failed to scan ${filePath}: ${err.message}\n`);
+    return null;
+  }
 }
 
 export function buildManifest(): ManifestEntry[] {
@@ -264,10 +269,11 @@ export function buildManifest(): ManifestEntry[] {
           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')
+          (file.endsWith('.ts') && !file.endsWith('.d.ts') && !file.endsWith('.test.ts') && file !== 'index.ts') ||
+          (file.endsWith('.js') && !file.endsWith('.d.js') && !file.endsWith('.test.js') && file !== 'index.js')
         ) {
-          manifest.push(scanTs(filePath, site));
+          const entry = scanTs(filePath, site);
+          if (entry) manifest.push(entry);
         }
       }
     }