@jackwener/opencli 1.4.1 → 1.5.1

package/.github/workflows/build-extension.yml

@@ -39,12 +39,8 @@ jobs:
         working-directory: extension
 
       - name: Prepare extension package
-        run: |
-          rm -rf extension-package
-          mkdir -p extension-package
-          cp extension/manifest.json extension-package/
-          cp -R extension/dist extension-package/
-          cp -R extension/icons extension-package/
+        run: npm run package:release -- --out ../extension-package
+        working-directory: extension
 
       - name: Create Extension ZIP
         run: |

package/.github/workflows/ci.yml

@@ -61,6 +61,27 @@ jobs:
       - name: Run unit tests (Node ${{ matrix.node-version }}, shard ${{ matrix.shard }}/2)
         run: npm test -- --reporter=verbose --shard=${{ matrix.shard }}/2
 
+  # ── Bun compatibility check ──
+  bun-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.5
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run unit tests under Bun
+        run: bun vitest run --project unit --reporter=verbose
+
   adapter-test:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -125,4 +146,3 @@ jobs:
         env:
           OPENCLI_BROWSER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
     timeout-minutes: 15
-

package/README.md

@@ -3,8 +3,7 @@
 > **Make any website, Electron App, or Local Tool your CLI.**  
 > Zero risk · Reuse Chrome login · AI-powered discovery · Universal CLI Hub
 
-[中文文档](./README.zh-CN.md)
-
+[![中文文档](https://img.shields.io/badge/docs-%E4%B8%AD%E6%96%87-0F766E?style=flat-square)](./README.zh-CN.md)
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
 [![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)
@@ -50,11 +49,31 @@ There are many great browser automation tools. Here's when opencli is the right
 
 ## Prerequisites
 
-- **Node.js**: >= 20.0.0
+- **Node.js**: >= 20.0.0 (or **Bun** >= 1.0 — see [Runtime Support](#runtime-support) below)
 - **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.
 
+### Runtime Support
+
+OpenCLI works with both **Node.js** (≥ 20) and **Bun** (≥ 1.0). All commands and adapters are runtime-agnostic.
+
+```bash
+# Development with Bun (faster startup)
+npm run dev:bun
+
+# Run the built CLI with Bun
+npm run start:bun
+
+# Run unit tests under Bun
+npm run test:bun
+
+# Run E2E tests with Bun as the runtime
+OPENCLI_TEST_RUNTIME=bun npm run test:e2e
+```
+
+Use `opencli doctor` to check your current runtime — it displays the active engine (e.g. `node v22.13.0` or `bun 1.1.42`).
+
 OpenCLI connects to your browser through a lightweight **Browser Bridge** Chrome Extension + micro-daemon (zero config, auto-start).
 
 ### Browser Bridge Extension Setup
@@ -132,7 +151,7 @@ Run `opencli list` for the live registry.
 | **v2ex** | `hot` `latest` `topic` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | Public / Browser |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` `fund-holdings` `fund-snapshot` | Browser |
 | **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | Desktop |
-| **chatgpt** | `status` `new` `send` `read` `ask` | Desktop |
+| **chatgpt** | `status` `new` `send` `read` `ask` `model` | Desktop |
 | **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | Browser |
 | **apple-podcasts** | `search` `episodes` `top` | Public |
 | **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | Public |
@@ -147,6 +166,7 @@ Run `opencli list` for the live registry.
 | **devto** | `top` `tag` `user` | Public |
 | **dictionary** | `search` `synonyms` `examples` | Public |
 | **arxiv** | `search` `paper` | Public |
+| **paperreview** | `submit` `review` `feedback` | Public |
 | **wikipedia** | `search` `summary` `random` `trending` | Public |
 | **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | Public |
 | **jd** | `item` | Browser |
@@ -164,13 +184,16 @@ Run `opencli list` for the live registry.
 | **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | Browser |
 | **jimeng** | `generate` `history` | Browser |
 | **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | Browser |
-| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | Public |
+| **linux-do** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | Browser |
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | Public |
 | **steam** | `top-sellers` | Public |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | Browser |
-| **douban** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | Browser |
+| **douban** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | Browser |
 | **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | Browser |
 | **google** | `news` `search` `suggest` `trends` | Public |
+| **36kr** | `news` `hot` `search` `article` | Public / Browser |
+| **imdb** | `search` `title` `top` `trending` `person` `reviews` | Public |
+| **producthunt** | `posts` `today` `hot` `browse` | Public / Browser |
 | **instagram** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | Browser |
 | **lobsters** | `hot` `newest` `active` `tag` | Public |
 | **medium** | `feed` `search` `user` | Browser |
@@ -206,6 +229,8 @@ opencli register mycli
 
 Each desktop adapter has its own detailed documentation with commands reference, setup guide, and examples:
 
+If you want to add support for a new Electron desktop app, start with [docs/guide/electron-app-cli.md](./docs/guide/electron-app-cli.md) and the deeper [Electron guide](./docs/advanced/electron.md).
+
 | App | Description | Doc |
 |-----|-------------|-----|
 | **Cursor** | Control Cursor IDE — Composer, chat, code extraction | [Doc](./docs/adapters/desktop/cursor.md) |
@@ -228,6 +253,7 @@ OpenCLI supports downloading images, videos, and articles from supported platfor
 | **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 |
+| **douban** | Images | Downloads poster / still image lists from movie subjects |
 | **pixiv** | Images | Downloads original-quality illustrations, supports multi-page works |
 | **zhihu** | Articles (Markdown) | Exports articles with optional image download |
 | **weixin** | Articles (Markdown) | Exports WeChat Official Account articles |
@@ -259,6 +285,9 @@ 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
 
+# Download Douban posters / stills
+opencli douban download 30382501 --output ./douban
+
 # Export Zhihu article to Markdown
 opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
 

package/README.zh-CN.md

@@ -3,8 +3,7 @@
 > **把任何网站、本地工具、Electron 应用变成能够让 AI 调用的命令行！**  
 > 零风控 · 复用 Chrome 登录 · AI 自动发现接口 · 全能 CLI 枢纽
 
-[English](./README.md)
-
+[![English](https://img.shields.io/badge/docs-English-1D4ED8?style=flat-square)](./README.md)
 [![npm](https://img.shields.io/npm/v/@jackwener/opencli?style=flat-square)](https://www.npmjs.com/package/@jackwener/opencli)
 [![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)
@@ -134,7 +133,7 @@ npm install -g @jackwener/opencli@latest
 | **v2ex** | `hot` `latest` `topic` `node` `user` `member` `replies` `nodes` `daily` `me` `notifications` | 公开 / 浏览器 |
 | **xueqiu** | `feed` `hot-stock` `hot` `search` `stock` `watchlist` `earnings-date` `fund-holdings` `fund-snapshot` | 浏览器 |
 | **antigravity** | `status` `send` `read` `new` `dump` `extract-code` `model` `watch` | 桌面端 |
-| **chatgpt** | `status` `new` `send` `read` `ask` | 桌面端 |
+| **chatgpt** | `status` `new` `send` `read` `ask` `model` | 桌面端 |
 | **xiaohongshu** | `search` `notifications` `feed` `user` `download` `publish` `creator-notes` `creator-note-detail` `creator-notes-summary` `creator-profile` `creator-stats` | 浏览器 |
 | **apple-podcasts** | `search` `episodes` `top` | 公开 |
 | **xiaoyuzhou** | `podcast` `podcast-episodes` `episode` | 公开 |
@@ -149,6 +148,7 @@ npm install -g @jackwener/opencli@latest
 | **devto** | `top` `tag` `user` | 公开 |
 | **dictionary** | `search` `synonyms` `examples` | 公开 |
 | **arxiv** | `search` `paper` | 公开 |
+| **paperreview** | `submit` `review` `feedback` | 公开 |
 | **wikipedia** | `search` `summary` `random` `trending` | 公开 |
 | **hackernews** | `top` `new` `best` `ask` `show` `jobs` `search` `user` | 公共 API |
 | **jd** | `item` | 浏览器 |
@@ -166,13 +166,16 @@ npm install -g @jackwener/opencli@latest
 | **jike** | `feed` `search` `create` `like` `comment` `repost` `notifications` `post` `topic` `user` | 浏览器 |
 | **jimeng** | `generate` `history` | 浏览器 |
 | **yollomi** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 浏览器 |
-| **linux-do** | `hot` `latest` `search` `categories` `category` `topic` | 公开 |
+| **linux-do** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | 浏览器 |
 | **stackoverflow** | `hot` `search` `bounties` `unanswered` | 公开 |
 | **steam** | `top-sellers` | 公开 |
 | **weread** | `shelf` `search` `book` `highlights` `notes` `notebooks` `ranking` | 浏览器 |
-| **douban** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | 浏览器 |
+| **douban** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | 浏览器 |
 | **facebook** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 浏览器 |
 | **google** | `news` `search` `suggest` `trends` | 公开 |
+| **36kr** | `news` `hot` `search` `article` | 公开 / 浏览器 |
+| **imdb** | `search` `title` `top` `trending` `person` `reviews` | 公开 |
+| **producthunt** | `posts` `today` `hot` `browse` | 公开 / 浏览器 |
 | **instagram** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | 浏览器 |
 | **lobsters** | `hot` `newest` `active` `tag` | 公开 |
 | **medium** | `feed` `search` `user` | 浏览器 |
@@ -233,6 +236,7 @@ OpenCLI 支持从各平台下载图片、视频和文章。
 | **Pixiv** | 图片 | 下载原始画质插画，支持多页作品 |
 | **知乎** | 文章（Markdown） | 导出文章，可选下载图片到本地 |
 | **微信公众号** | 文章（Markdown） | 导出微信公众号文章为 Markdown |
+| **豆瓣** | 图片 | 下载电影条目的海报 / 剧照图片 |
 
 ### 前置依赖
 
@@ -261,6 +265,9 @@ opencli twitter download elonmusk --limit 20 --output ./twitter
 # 下载单条推文的媒体
 opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
 
+# 下载豆瓣电影海报 / 剧照
+opencli douban download 30382501 --output ./douban
+
 # 导出知乎文章为 Markdown
 opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
 

package/SKILL.md

@@ -286,6 +286,8 @@ opencli chaoxing exams                   # 考试列表
 opencli douban search "三体"              # 搜索 (query positional)
 opencli douban top250                     # 豆瓣 Top 250
 opencli douban subject 1234567            # 条目详情 (id positional)
+opencli douban photos 30382501            # 图片列表 / 直链（默认海报）
+opencli douban download 30382501          # 下载海报 / 剧照
 opencli douban marks --limit 10           # 我的标记
 opencli douban reviews --limit 10         # 短评
 

package/dist/browser/cdp.d.ts

@@ -8,13 +8,14 @@
  * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
  */
 import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
 export interface CDPTarget {
     type?: string;
     url?: string;
     title?: string;
     webSocketDebuggerUrl?: string;
 }
-export declare class CDPBridge {
+export declare class CDPBridge implements IBrowserFactory {
     private _ws;
     private _idCounter;
     private _pending;

package/dist/browser/cdp.js

@@ -135,6 +135,7 @@ export class CDPBridge {
 class CDPPage {
     bridge;
     _pageEnabled = false;
+    _lastUrl = null;
     constructor(bridge) {
         this.bridge = bridge;
     }
@@ -146,6 +147,7 @@ class CDPPage {
         const loadPromise = this.bridge.waitForEvent('Page.loadEventFired', 30_000).catch(() => { });
         await this.bridge.send('Page.navigate', { url });
         await loadPromise;
+        this._lastUrl = url;
         if (options?.waitUntil !== 'none') {
             const maxMs = options?.settleMs ?? 1000;
             await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
@@ -251,6 +253,9 @@ class CDPPage {
     async consoleMessages(_level) {
         return [];
     }
+    async getCurrentUrl() {
+        return this._lastUrl;
+    }
     async installInterceptor(pattern) {
         const { generateInterceptorJs } = await import('../interceptor.js');
         await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {

package/dist/browser/discover.d.ts

@@ -9,7 +9,10 @@ export { isDaemonRunning };
 /**
  * Check daemon status and return connection info.
  */
-export declare function checkDaemonStatus(): Promise<{
+export declare function checkDaemonStatus(opts?: {
+    timeout?: number;
+}): Promise<{
     running: boolean;
     extensionConnected: boolean;
+    extensionVersion?: string;
 }>;

package/dist/browser/discover.js

@@ -10,14 +10,18 @@ export { isDaemonRunning };
 /**
  * Check daemon status and return connection info.
  */
-export async function checkDaemonStatus() {
+export async function checkDaemonStatus(opts) {
     try {
         const port = parseInt(process.env.OPENCLI_DAEMON_PORT ?? String(DEFAULT_DAEMON_PORT), 10);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), opts?.timeout ?? 2000);
         const res = await fetch(`http://127.0.0.1:${port}/status`, {
             headers: { 'X-OpenCLI': '1' },
+            signal: controller.signal,
         });
         const data = await res.json();
-        return { running: true, extensionConnected: data.extensionConnected };
+        clearTimeout(timer);
+        return { running: true, extensionConnected: data.extensionConnected, extensionVersion: data.extensionVersion };
     }
     catch {
         return { running: false, extensionConnected: false };

package/dist/browser/errors.d.ts

@@ -4,6 +4,6 @@
  * Simplified — no more token/extension/CDP classification.
  * The daemon architecture has a single failure mode: daemon not reachable or extension not connected.
  */
-import { BrowserConnectError } from '../errors.js';
-export type ConnectFailureKind = 'daemon-not-running' | 'extension-not-connected' | 'command-failed' | 'unknown';
+import { BrowserConnectError, type BrowserConnectKind } from '../errors.js';
+export type ConnectFailureKind = BrowserConnectKind;
 export declare function formatBrowserConnectError(kind: ConnectFailureKind, detail?: string): BrowserConnectError;

package/dist/browser/errors.js

@@ -9,20 +9,12 @@ import { DEFAULT_DAEMON_PORT } from '../constants.js';
 export function formatBrowserConnectError(kind, detail) {
     switch (kind) {
         case 'daemon-not-running':
-            return new BrowserConnectError('Cannot connect to opencli daemon.' +
-                (detail ? `\n\n${detail}` : ''), 'The daemon should start automatically. If it doesn\'t, try:\n' +
-                '  node dist/daemon.js\n' +
-                `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
+            return new BrowserConnectError('Cannot connect to opencli daemon.' + (detail ? `\n\n${detail}` : ''), `The daemon should auto-start. If it keeps failing, make sure port ${DEFAULT_DAEMON_PORT} is available.`, kind);
         case 'extension-not-connected':
-            return new BrowserConnectError('opencli Browser Bridge extension is not connected.' +
-                (detail ? `\n\n${detail}` : ''), 'Please install the extension:\n' +
-                '  1. Download from GitHub Releases\n' +
-                '  2. Open chrome://extensions/ → Enable Developer Mode\n' +
-                '  3. Click "Load unpacked" → select the extension folder\n' +
-                '  4. Make sure Chrome is running');
+            return new BrowserConnectError('Browser Bridge extension is not connected.' + (detail ? `\n\n${detail}` : ''), 'Install the extension from GitHub Releases, then reload.', kind);
         case 'command-failed':
-            return new BrowserConnectError(`Browser command failed: ${detail ?? 'unknown error'}`);
+            return new BrowserConnectError(`Browser command failed: ${detail ?? 'unknown error'}`, undefined, kind);
         default:
-            return new BrowserConnectError(detail ?? 'Failed to connect to browser');
+            return new BrowserConnectError(detail ?? 'Failed to connect to browser', undefined, kind);
     }
 }

package/dist/browser/mcp.d.ts

@@ -2,11 +2,12 @@
  * Browser session manager — auto-spawns daemon and provides IPage.
  */
 import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
 export type BrowserBridgeState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
 /**
  * Browser factory: manages daemon lifecycle and provides IPage instances.
  */
-export declare class BrowserBridge {
+export declare class BrowserBridge implements IBrowserFactory {
     private _state;
     private _page;
     private _daemonProc;

package/dist/browser/page.d.ts

@@ -18,6 +18,8 @@ export declare class Page implements IPage {
     constructor(workspace?: string);
     /** Active tab ID, set after navigate and used in all subsequent commands */
     private _tabId;
+    /** Last navigated URL, tracked in-memory to avoid extra round-trips */
+    private _lastUrl;
     /** Helper: spread workspace into command params */
     private _wsOpt;
     /** Helper: spread workspace + tabId into command params */
@@ -26,6 +28,7 @@ export declare class Page implements IPage {
         waitUntil?: 'load' | 'none';
         settleMs?: number;
     }): Promise<void>;
+    getCurrentUrl(): Promise<string | null>;
     /** Close the automation window in the extension */
     closeWindow(): Promise<void>;
     evaluate(js: string): Promise<unknown>;

package/dist/browser/page.js

@@ -26,6 +26,8 @@ export class Page {
     }
     /** Active tab ID, set after navigate and used in all subsequent commands */
     _tabId;
+    /** Last navigated URL, tracked in-memory to avoid extra round-trips */
+    _lastUrl = null;
     /** Helper: spread workspace into command params */
     _wsOpt() {
         return { workspace: this.workspace };
@@ -42,10 +44,11 @@ export class Page {
             url,
             ...this._cmdOpts(),
         });
-        // Remember the tabId for subsequent exec calls
+        // Remember the tabId and URL for subsequent calls
         if (result?.tabId) {
             this._tabId = result.tabId;
         }
+        this._lastUrl = url;
         // Inject stealth anti-detection patches (guard flag prevents double-injection).
         try {
             await sendCommand('exec', {
@@ -66,6 +69,9 @@ export class Page {
             });
         }
     }
+    async getCurrentUrl() {
+        return this._lastUrl;
+    }
     /** Close the automation window in the extension */
     async closeWindow() {
         try {
@@ -163,6 +169,23 @@ export class Page {
     }
     async wait(options) {
         if (typeof options === 'number') {
+            if (options >= 1) {
+                // For waits >= 1s, use DOM-stable check: return early when the page
+                // stops mutating, with the original wait time as the hard cap.
+                // This turns e.g. `page.wait(5)` from a fixed 5s sleep into
+                // "wait until DOM is stable, max 5s" — often completing in <1s.
+                try {
+                    const maxMs = options * 1000;
+                    await sendCommand('exec', {
+                        code: waitForDomStableJs(maxMs, Math.min(500, maxMs)),
+                        ...this._cmdOpts(),
+                    });
+                    return;
+                }
+                catch {
+                    // Fallback: fixed sleep (e.g. if page has no DOM yet)
+                }
+            }
             await new Promise(resolve => setTimeout(resolve, options * 1000));
             return;
         }

package/dist/build-manifest.d.ts

@@ -27,6 +27,8 @@ export interface ManifestEntry {
     columns?: string[];
     pipeline?: Record<string, unknown>[];
     timeout?: number;
+    deprecated?: boolean | string;
+    replacedBy?: string;
     /** 'yaml' or 'ts' — determines how executeCommand loads the handler */
     type: 'yaml' | 'ts';
     /** Relative path from clis/ dir, e.g. 'bilibili/hot.yaml' or 'bilibili/search.js' */

package/dist/build-manifest.js

@@ -16,6 +16,7 @@ import { getErrorMessage } from './errors.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.resolve(__dirname, 'clis');
 const OUTPUT = path.resolve(__dirname, '..', 'dist', 'cli-manifest.json');
+import { parseYamlArgs } from './yaml-schema.js';
 import { isRecord } from './utils.js';
 function extractBalancedBlock(source, startIndex, openChar, closeChar) {
     let depth = 0;
@@ -126,20 +127,7 @@ function scanYaml(filePath, site) {
         const strategyStr = cliDef.strategy ?? (cliDef.browser === false ? 'public' : 'cookie');
         const strategy = strategyStr.toUpperCase();
         const browser = cliDef.browser ?? (strategy !== 'PUBLIC');
-        const args = [];
-        if (cliDef.args && typeof cliDef.args === 'object') {
-            for (const [argName, argDef] of Object.entries(cliDef.args)) {
-                args.push({
-                    name: argName,
-                    type: argDef?.type ?? 'str',
-                    default: argDef?.default,
-                    required: argDef?.required ?? false,
-                    positional: argDef?.positional === true || undefined,
-                    help: argDef?.description ?? argDef?.help ?? '',
-                    choices: argDef?.choices,
-                });
-            }
-        }
+        const args = parseYamlArgs(cliDef.args);
         return {
             site: cliDef.site ?? site,
             name: cliDef.name ?? path.basename(filePath, path.extname(filePath)),
@@ -151,6 +139,8 @@ function scanYaml(filePath, site) {
             columns: cliDef.columns,
             pipeline: cliDef.pipeline,
             timeout: cliDef.timeout,
+            deprecated: cliDef.deprecated,
+            replacedBy: cliDef.replacedBy,
             type: 'yaml',
             navigateBefore: cliDef.navigateBefore,
         };
@@ -218,6 +208,18 @@ export function scanTs(filePath, site) {
             if (navStringMatch)
                 entry.navigateBefore = navStringMatch[1];
         }
+        const deprecatedBoolMatch = src.match(/deprecated\s*:\s*(true|false)/);
+        if (deprecatedBoolMatch) {
+            entry.deprecated = deprecatedBoolMatch[1] === 'true';
+        }
+        else {
+            const deprecatedStringMatch = src.match(/deprecated\s*:\s*['"`]([^'"`]+)['"`]/);
+            if (deprecatedStringMatch)
+                entry.deprecated = deprecatedStringMatch[1];
+        }
+        const replacedByMatch = src.match(/replacedBy\s*:\s*['"`]([^'"`]+)['"`]/);
+        if (replacedByMatch)
+            entry.replacedBy = replacedByMatch[1];
         return entry;
     }
     catch (err) {
@@ -283,6 +285,29 @@ function main() {
     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}`);
+    // Restore executable permissions on bin entries.
+    // tsc does not preserve the +x bit, so after a clean rebuild the CLI
+    // entry-point loses its executable permission, causing "Permission denied".
+    // See: https://github.com/jackwener/opencli/issues/446
+    if (process.platform !== 'win32') {
+        const pkgPath = path.resolve(__dirname, '..', 'package.json');
+        try {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            const bins = typeof pkg.bin === 'string'
+                ? { [pkg.name ?? 'cli']: pkg.bin }
+                : pkg.bin ?? {};
+            for (const binPath of Object.values(bins)) {
+                const abs = path.resolve(__dirname, '..', binPath);
+                if (fs.existsSync(abs)) {
+                    fs.chmodSync(abs, 0o755);
+                    console.log(`✅ Restored executable permission: ${binPath}`);
+                }
+            }
+        }
+        catch {
+            // Best-effort; never break the build for a permission fix.
+        }
+    }
 }
 const entrypoint = process.argv[1] ? pathToFileURL(path.resolve(process.argv[1])).href : null;
 if (entrypoint === import.meta.url) {

package/dist/build-manifest.test.js

@@ -125,4 +125,25 @@ describe('manifest helper rules', () => {
             modulePath: 'xueqiu/fund-holdings.js',
         });
     });
+    it('captures deprecated metadata for TS adapters', () => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'opencli-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, 'legacy.ts');
+        fs.writeFileSync(file, `
+      import { cli } from '../../registry.js';
+      cli({
+        site: 'demo',
+        name: 'legacy',
+        description: 'legacy command',
+        deprecated: 'legacy is deprecated',
+        replacedBy: 'opencli demo new',
+      });
+    `);
+        expect(scanTs(file, 'demo')).toMatchObject({
+            site: 'demo',
+            name: 'legacy',
+            deprecated: 'legacy is deprecated',
+            replacedBy: 'opencli demo new',
+        });
+    });
 });

package/dist/capabilityRouting.d.ts

@@ -1,2 +1,4 @@
 import { type CliCommand } from './registry.js';
+/** Pipeline steps that require a live browser session. */
+export declare const BROWSER_ONLY_STEPS: Set<string>;
 export declare function shouldUseBrowserSession(cmd: CliCommand): boolean;

package/dist/capabilityRouting.js

@@ -1,5 +1,6 @@
 import { Strategy } from './registry.js';
-const BROWSER_ONLY_STEPS = new Set([
+/** Pipeline steps that require a live browser session. */
+export const BROWSER_ONLY_STEPS = new Set([
     'navigate',
     'click',
     'type',