@jackwener/opencli 1.1.1 → 1.2.1

package/dist/types.d.ts

@@ -4,6 +4,39 @@
  * All pipeline steps and CLI adapters should use this interface
  * instead of `any` for browser interactions.
  */
+export interface BrowserCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    expirationDate?: number;
+}
+export interface SnapshotOptions {
+    interactive?: boolean;
+    compact?: boolean;
+    maxDepth?: number;
+    raw?: boolean;
+    viewportExpand?: number;
+    maxTextLength?: number;
+}
+export interface WaitOptions {
+    text?: string;
+    time?: number;
+    timeout?: number;
+}
+export interface ScreenshotOptions {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    fullPage?: boolean;
+    path?: string;
+}
+export interface BrowserSessionInfo {
+    workspace?: string;
+    connected?: boolean;
+    [key: string]: unknown;
+}
 export interface IPage {
     goto(url: string, options?: {
         waitUntil?: 'load' | 'none';
@@ -13,29 +46,14 @@ export interface IPage {
     getCookies(opts?: {
         domain?: string;
         url?: string;
-    }): Promise<Array<{
-        name: string;
-        value: string;
-        domain: string;
-        path?: string;
-        secure?: boolean;
-        httpOnly?: boolean;
-        expirationDate?: number;
-    }>>;
-    snapshot(opts?: {
-        interactive?: boolean;
-        compact?: boolean;
-        maxDepth?: number;
-        raw?: boolean;
-    }): Promise<any>;
+    }): Promise<BrowserCookie[]>;
+    snapshot(opts?: SnapshotOptions): Promise<any>;
     click(ref: string): Promise<void>;
     typeText(ref: string, text: string): Promise<void>;
     pressKey(key: string): Promise<void>;
-    wait(options: number | {
-        text?: string;
-        time?: number;
-        timeout?: number;
-    }): Promise<void>;
+    scrollTo(ref: string): Promise<any>;
+    getFormState(): Promise<any>;
+    wait(options: number | WaitOptions): Promise<void>;
     tabs(): Promise<any>;
     closeTab(index?: number): Promise<void>;
     newTab(): Promise<void>;
@@ -49,10 +67,5 @@ export interface IPage {
     }): Promise<void>;
     installInterceptor(pattern: string): Promise<void>;
     getInterceptedRequests(): Promise<any[]>;
-    screenshot(options?: {
-        format?: 'png' | 'jpeg';
-        quality?: number;
-        fullPage?: boolean;
-        path?: string;
-    }): Promise<string>;
+    screenshot(options?: ScreenshotOptions): Promise<string>;
 }

package/dist/validate.js

@@ -9,6 +9,12 @@ const KNOWN_STEP_NAMES = new Set([
     'select', 'map', 'filter', 'sort', 'limit',
     'intercept', 'tap',
 ]);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 export function validateClisWithTarget(dirs, target) {
     const results = [];
     let errors = 0;
@@ -45,7 +51,7 @@ function validateYamlFile(filePath) {
     try {
         const raw = fs.readFileSync(filePath, 'utf-8');
         const def = yaml.load(raw);
-        if (!def || typeof def !== 'object') {
+        if (!isRecord(def)) {
             errors.push('Not a valid YAML object');
             return { path: filePath, errors, warnings };
         }
@@ -75,7 +81,7 @@ function validateYamlFile(filePath) {
         }
     }
     catch (e) {
-        errors.push(`YAML parse error: ${e.message}`);
+        errors.push(`YAML parse error: ${getErrorMessage(e)}`);
     }
     return { path: filePath, errors, warnings };
 }

package/docs/.vitepress/config.mts

@@ -31,6 +31,7 @@ export default defineConfig({
                 { text: 'Installation', link: '/guide/installation' },
                 { text: 'Browser Bridge', link: '/guide/browser-bridge' },
                 { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+                { text: 'Plugins', link: '/guide/plugins' },
               ],
             },
           ],
@@ -67,6 +68,9 @@ export default defineConfig({
                 { text: 'Chaoxing', link: '/adapters/browser/chaoxing' },
                 { text: 'Grok', link: '/adapters/browser/grok' },
                 { text: 'WeRead', link: '/adapters/browser/weread' },
+                { text: 'Douban', link: '/adapters/browser/douban' },
+                { text: 'Sina Blog', link: '/adapters/browser/sinablog' },
+                { text: 'Substack', link: '/adapters/browser/substack' },
               ],
             },
             {
@@ -74,7 +78,7 @@ export default defineConfig({
               collapsed: false,
               items: [
                 { text: 'HackerNews', link: '/adapters/browser/hackernews' },
-                { text: 'GitHub', link: '/adapters/browser/github' },
+                { text: 'Dev.to', link: '/adapters/browser/devto' },
                 { text: 'BBC', link: '/adapters/browser/bbc' },
                 { text: 'Apple Podcasts', link: '/adapters/browser/apple-podcasts' },
                 { text: 'Xiaoyuzhou', link: '/adapters/browser/xiaoyuzhou' },
@@ -98,9 +102,6 @@ export default defineConfig({
                 { text: 'ChatWise', link: '/adapters/desktop/chatwise' },
                 { text: 'Notion', link: '/adapters/desktop/notion' },
                 { text: 'Discord', link: '/adapters/desktop/discord' },
-                { text: 'Feishu', link: '/adapters/desktop/feishu' },
-                { text: 'WeChat', link: '/adapters/desktop/wechat' },
-                { text: 'NeteaseMusic', link: '/adapters/desktop/neteasemusic' },
               ],
             },
           ],
@@ -150,6 +151,7 @@ export default defineConfig({
                 { text: '快速开始', link: '/zh/guide/getting-started' },
                 { text: '安装', link: '/zh/guide/installation' },
                 { text: 'Browser Bridge', link: '/zh/guide/browser-bridge' },
+                { text: '插件', link: '/zh/guide/plugins' },
               ],
             },
           ],

package/docs/adapters/browser/barchart.md

@@ -1,6 +1,6 @@
 # Barchart
 
-**Mode**: 🌐 Public · **Domain**: `barchart.com`
+**Mode**: 🔐 Browser · **Domain**: `barchart.com`
 
 ## Commands
 
@@ -15,13 +15,13 @@
 
 ```bash
 # Get stock quote
-opencli barchart quote --symbol AAPL
+opencli barchart quote AAPL
 
 # View options chain
-opencli barchart options --symbol TSLA
+opencli barchart options TSLA
 
 # Options greeks overview
-opencli barchart greeks --symbol NVDA
+opencli barchart greeks NVDA
 
 # Unusual options flow
 opencli barchart flow --limit 20 -f json
@@ -29,4 +29,5 @@ opencli barchart flow --limit 20 -f json
 
 ## Prerequisites
 
-- No browser required — uses public API
+- Chrome running and able to open `barchart.com`
+- [Browser Bridge extension](/guide/browser-bridge) installed

package/docs/adapters/browser/bilibili.md

@@ -25,6 +25,15 @@
 # Quick start
 opencli bilibili hot --limit 5
 
+# Search videos
+opencli bilibili search 黑神话 --limit 10
+
+# Read one creator's videos
+opencli bilibili user-videos 2 --limit 10
+
+# Fetch subtitles
+opencli bilibili subtitle BV1xx411c7mD --lang zh-CN
+
 # JSON output
 opencli bilibili hot -f json
 

package/docs/adapters/browser/devto.md

@@ -0,0 +1,35 @@
+# Dev.to
+
+**Mode**: 🌐 Public · **Domain**: `dev.to`
+
+Fetch the latest and greatest developer articles from the DEV community without needing an API key.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli devto top` | Top DEV.to articles of the day |
+| `opencli devto tag` | Latest articles for a specific tag |
+| `opencli devto user` | Recent articles from a specific user |
+
+## Usage Examples
+
+```bash
+# Top articles today
+opencli devto top --limit 5
+
+# Articles by tag (positional argument)
+opencli devto tag javascript
+opencli devto tag python --limit 20
+
+# Articles by a specific author
+opencli devto user ben
+opencli devto user thepracticaldev --limit 5
+
+# JSON output
+opencli devto top -f json
+```
+
+## Prerequisites
+
+- No browser required — uses the public DEV.to API

package/docs/adapters/browser/douban.md

@@ -0,0 +1,38 @@
+# 豆瓣 (Douban)
+
+**Mode**: 🔐 Browser (Cookie) · **Domain**: `douban.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli douban movie-hot` | 豆瓣电影热门榜单 |
+| `opencli douban book-hot` | 豆瓣图书热门榜单 |
+| `opencli douban search` | 搜索豆瓣电影、图书或音乐 |
+
+## Usage Examples
+
+```bash
+# 电影热门
+opencli douban movie-hot --limit 10
+
+# 图书热门
+opencli douban book-hot --limit 10
+
+# 搜索电影
+opencli douban search "流浪地球"
+
+# 搜索图书
+opencli douban search --type book "三体"
+
+# 搜索音乐
+opencli douban search --type music "周杰伦"
+
+# JSON output
+opencli douban movie-hot -f json
+```
+
+## Prerequisites
+
+- Chrome logged into `douban.com`
+- Browser Bridge extension installed

package/docs/adapters/browser/facebook.md

@@ -0,0 +1,36 @@
+# Facebook
+
+**Mode**: 🔐 Browser · **Domain**: `facebook.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli facebook profile` | Get user/page profile info |
+| `opencli facebook notifications` | Get recent notifications |
+| `opencli facebook feed` | Get news feed posts |
+| `opencli facebook search` | Search people, pages, posts |
+
+## Usage Examples
+
+```bash
+# View a profile
+opencli facebook profile zuck
+
+# Get notifications
+opencli facebook notifications --limit 10
+
+# News feed
+opencli facebook feed --limit 5
+
+# Search
+opencli facebook search "OpenAI" --limit 5
+
+# JSON output
+opencli facebook profile zuck -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** facebook.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

package/docs/adapters/browser/google.md

@@ -0,0 +1,62 @@
+# Google
+
+**Mode**: 🌐 / 🔐 Mixed · **Domains**: `google.com`, `suggestqueries.google.com`, `news.google.com`, `trends.google.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli google search <keyword>` | Search Google and extract results from the page |
+| `opencli google suggest <keyword>` | Get Google search suggestions |
+| `opencli google news [keyword]` | Get Google News headlines (top stories or search) |
+| `opencli google trends` | Get Google Trends daily trending searches |
+
+## What works today
+
+- Public API commands work without a browser:
+  - `suggest` — JSON API, no auth needed
+  - `news` — RSS feed, supports top stories and keyword search
+  - `trends` — RSS feed, supports different regions
+- `google search` uses browser mode to extract results from google.com.
+
+## Current limitations
+
+- `google search` may trigger CAPTCHA in Standalone browser mode. Extension mode (with an established Chrome session) is more reliable.
+- Google frequently changes its DOM structure. If `search` stops returning results, selectors may need updating.
+- Snippet extraction may return empty for some results depending on Google's layout.
+
+## Usage Examples
+
+```bash
+# Search Google
+opencli google search "typescript tutorial" --limit 10
+
+# Get search suggestions
+opencli google suggest python
+
+# Get top news headlines
+opencli google news --limit 5
+
+# Search news for a topic
+opencli google news "artificial intelligence" --limit 10 --lang en --region US
+
+# Get trending searches in Japan
+opencli google trends --region JP --limit 10
+
+# Output as JSON
+opencli google search "machine learning" -f json
+```
+
+## Prerequisites
+
+- `suggest`, `news`, `trends` do not require Chrome.
+- `search` requires:
+  - Chrome running (or Standalone mode will auto-launch)
+  - For best results, use the [Browser Bridge extension](/guide/browser-bridge) with an established Google session
+
+## Notes
+
+- `suggest` defaults to `--lang zh-CN`; other commands default to `--lang en`.
+- `news` supports `--lang` and `--region` parameters for localized results.
+- `trends` traffic values are raw strings (e.g. "500K+", "1,000,000+"), not numeric.
+- `search` output includes three result types: `result` (standard), `snippet` (featured answer box), and `paa` (People Also Ask).

package/docs/adapters/browser/grok.md

@@ -1,24 +1,28 @@
 # Grok
 
-**Mode**: 🔐 Browser · **Domain**: `grok.com`
+**Mode**: Default Grok adapter + optional explicit consumer web path · **Domain**: `grok.com`
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `opencli grok ask` | Send a message to Grok and get response |
+| `opencli grok ask` | Keep the default Grok ask behavior |
+| `opencli grok ask --web` | Use the explicit grok.com consumer web UI flow |
 
 ## Usage Examples
 
 ```bash
-# Ask Grok a question
+# Default / compatibility path
 opencli grok ask --prompt "Explain quantum computing in simple terms"
 
-# Start a new chat session
-opencli grok ask --prompt "Hello" --new
+# Explicit consumer web path
+opencli grok ask --prompt "Explain quantum computing in simple terms" --web
+
+# Best-effort fresh chat on the consumer web path
+opencli grok ask --prompt "Hello" --web --new
 
 # Set custom timeout (default: 120s)
-opencli grok ask --prompt "Write a long essay" --timeout 180
+opencli grok ask --prompt "Write a long essay" --web --timeout 180
 ```
 
 ### Options
@@ -27,9 +31,23 @@ opencli grok ask --prompt "Write a long essay" --timeout 180
 |--------|-------------|
 | `--prompt` | The message to send (required) |
 | `--timeout` | Wait timeout in seconds (default: 120) |
-| `--new` | Start a new chat session (default: false) |
+| `--new` | Start a new chat before sending (default: false) |
+| `--web` | Opt into the explicit grok.com consumer web flow (default: false) |
+
+## Behavior
+
+- `opencli grok ask` keeps the upstream/default behavior intact.
+- `opencli grok ask --web` switches to the newer hardened consumer-web implementation.
+- The `--web` path adds stricter composer detection, clearer blocked/session-gated hints, and waits for a stabilized assistant bubble before returning.
 
 ## Prerequisites
 
-- Chrome running and **logged into** grok.com
+- The Grok adapter still depends on browser-backed access to `grok.com`
+- For `--web`, Chrome should already be running with an authenticated Grok consumer session
 - [Browser Bridge extension](/guide/browser-bridge) installed
+
+## Caveats
+
+- `--web` drives the Grok consumer web UI in the browser, not an API.
+- It depends on an already-authenticated session and can fail if Grok shows login, challenge, rate-limit, or other session-gating UI.
+- It may break when the Grok composer DOM, submit button behavior, or message bubble structure changes.

package/docs/adapters/browser/instagram.md

@@ -0,0 +1,46 @@
+# Instagram
+
+**Mode**: 🔐 Browser · **Domain**: `instagram.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli instagram profile` | Get user profile info |
+| `opencli instagram search` | Search users |
+| `opencli instagram user` | Get recent posts from a user |
+| `opencli instagram explore` | Discover trending posts |
+| `opencli instagram followers` | List user's followers |
+| `opencli instagram following` | List user's following |
+| `opencli instagram saved` | Get your saved posts |
+
+## Usage Examples
+
+```bash
+# View a user's profile
+opencli instagram profile nasa
+
+# Search users
+opencli instagram search nasa --limit 5
+
+# View a user's recent posts
+opencli instagram user nasa --limit 10
+
+# Discover trending posts
+opencli instagram explore --limit 20
+
+# List followers/following
+opencli instagram followers nasa --limit 20
+opencli instagram following nasa --limit 20
+
+# Get your saved posts
+opencli instagram saved --limit 10
+
+# JSON output
+opencli instagram profile nasa -f json
+```
+
+## Prerequisites
+
+- Chrome running and **logged into** instagram.com
+- [Browser Bridge extension](/guide/browser-bridge) installed

package/docs/adapters/browser/lobsters.md

@@ -0,0 +1,32 @@
+# Lobsters
+
+**Mode**: 🌐 Public · **Domain**: `lobste.rs`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli lobsters hot` | Hottest stories |
+| `opencli lobsters newest` | Latest stories |
+| `opencli lobsters active` | Most active discussions |
+| `opencli lobsters tag` | Stories by tag |
+
+## Usage Examples
+
+```bash
+# Quick start
+opencli lobsters hot --limit 10
+
+# Filter by tag
+opencli lobsters tag --tag rust --limit 5
+
+# JSON output
+opencli lobsters hot -f json
+
+# Verbose mode
+opencli lobsters hot -v
+```
+
+## Prerequisites
+
+None — all commands use the public JSON API, no browser or login required.

package/docs/adapters/browser/medium.md

@@ -0,0 +1,32 @@
+# Medium
+
+**Mode**: 🌗 Mixed · **Domain**: `medium.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli medium feed` | Get hot Medium posts, optionally scoped to a topic |
+| `opencli medium search` | Search Medium posts by keyword |
+| `opencli medium user` | Get recent articles by a user |
+
+## Usage Examples
+
+```bash
+# Get the general Medium feed
+opencli medium feed --limit 10
+
+# Search posts by keyword
+opencli medium search ai
+
+# Get articles by a user
+opencli medium user @username
+
+# Topic feed as JSON
+opencli medium feed --topic programming -f json
+```
+
+## Prerequisites
+
+- `opencli medium search` can run without a browser
+- `opencli medium feed` and `opencli medium user` require Browser Bridge access to `medium.com`

package/docs/adapters/browser/reddit.md

@@ -28,6 +28,15 @@
 # Quick start
 opencli reddit hot --limit 5
 
+# Read one subreddit
+opencli reddit subreddit python --limit 10
+
+# Read a post thread
+opencli reddit read 1abc123 --depth 2
+
+# Comment on a post
+opencli reddit comment 1abc123 "Great post"
+
 # JSON output
 opencli reddit hot -f json
 

package/docs/adapters/browser/sinablog.md

@@ -0,0 +1,36 @@
+# 新浪博客 (Sina Blog)
+
+**Mode**: 🌐 Public (search) / 🔐 Browser (hot, article, user) · **Domain**: `blog.sina.com.cn`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli sinablog hot` | 获取新浪博客热门文章/推荐 |
+| `opencli sinablog search` | 搜索新浪博客文章（通过新浪搜索，无需浏览器） |
+| `opencli sinablog article` | 获取新浪博客单篇文章详情 |
+| `opencli sinablog user` | 获取新浪博客用户的文章列表 |
+
+## Usage Examples
+
+```bash
+# 热门文章
+opencli sinablog hot --limit 10
+
+# 搜索文章（公开 API，无需浏览器）
+opencli sinablog search "人工智能"
+
+# 文章详情
+opencli sinablog article "https://blog.sina.com.cn/s/blog_xxx.html"
+
+# 用户文章列表
+opencli sinablog user 1234567890 --limit 10
+
+# JSON output
+opencli sinablog hot -f json
+```
+
+## Prerequisites
+
+- `search` command: No login required (public API)
+- `hot`, `article`, `user` commands: Chrome with `blog.sina.com.cn` accessible, Browser Bridge extension installed

package/docs/adapters/browser/substack.md

@@ -0,0 +1,38 @@
+# Substack
+
+**Mode**: 🌐 Public (search) / 🔐 Browser (feed, publication) · **Domain**: `substack.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli substack feed` | Substack 热门文章 Feed |
+| `opencli substack search` | 搜索 Substack 文章和 Newsletter（无需浏览器） |
+| `opencli substack publication` | 获取特定 Substack Newsletter 的最新文章 |
+
+## Usage Examples
+
+```bash
+# 热门 Feed
+opencli substack feed --limit 10
+
+# 按分类浏览
+opencli substack feed --category tech --limit 10
+
+# 搜索文章（公开 API，无需浏览器）
+opencli substack search "AI"
+
+# 搜索 Newsletter
+opencli substack search "technology" --type publications
+
+# 查看特定 Newsletter 的最新文章
+opencli substack publication "https://example.substack.com" --limit 10
+
+# JSON output
+opencli substack search "AI" -f json
+```
+
+## Prerequisites
+
+- `search` command: No login required (public API)
+- `feed`, `publication` commands: Chrome with `substack.com` accessible, Browser Bridge extension installed