@jackwener/opencli 0.9.6 → 1.0.0

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,83 @@
+name: "🐛 Bug Report"
+description: Report a bug or unexpected behavior in OpenCLI
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. A short reproduction and any error output are usually enough.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear and concise description of the bug.
+      placeholder: What happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce
+      description: How can we reproduce this behavior?
+      value: |
+        1. Run `opencli ...`
+        2. ...
+        3. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: OpenCLI Version
+      description: "Run `opencli --version` to find out."
+      placeholder: "0.8.0"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: node-version
+    attributes:
+      label: Node.js Version
+      options:
+        - "20.x"
+        - "22.x"
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating System
+      options:
+        - macOS
+        - Linux
+        - Windows
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: |
+        Paste any relevant error output. Run with `-v` for verbose logs:
+        ```
+        opencli <command> -v
+        ```
+      render: shell
+    validations:
+      required: false

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📖 Documentation
+    url: https://github.com/jackwener/opencli#readme
+    about: Check the README and docs before opening an issue.
+  - name: 🧪 Testing Guide
+    url: https://github.com/jackwener/opencli/blob/main/TESTING.md
+    about: How to run and write tests for OpenCLI.

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: "✨ Feature Request"
+description: Suggest a new feature or improvement
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make OpenCLI better? We'd love to hear it!
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature Description
+      description: A clear and concise description of the feature you'd like.
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: What problem does this solve? Who benefits from this feature?
+      placeholder: "As a user, I want to ... so that ..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: If you have a specific implementation in mind, describe it here.
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: Any alternative approaches you've thought about?
+    validations:
+      required: false

package/.github/ISSUE_TEMPLATE/new_site_adapter.yml

@@ -0,0 +1,57 @@
+name: "🌐 New Site Adapter Request"
+description: Request support for a new website
+title: "[Site]: "
+labels: ["new-adapter"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Want OpenCLI to support a new site? Tell us about it!
+
+  - type: input
+    id: site-name
+    attributes:
+      label: Site Name
+      description: The name of the website.
+      placeholder: "e.g. Product Hunt"
+    validations:
+      required: true
+
+  - type: input
+    id: site-url
+    attributes:
+      label: Site URL
+      description: The main URL of the website.
+      placeholder: "https://www.producthunt.com"
+    validations:
+      required: true
+
+  - type: textarea
+    id: commands
+    attributes:
+      label: Desired Commands
+      description: What commands would you like? List them with a brief description.
+      value: |
+        - `hot` — trending / popular items
+        - `search` — search the site
+    validations:
+      required: true
+
+  - type: textarea
+    id: api-examples
+    attributes:
+      label: Example Links or API Endpoints
+      description: Share any example page URLs or API endpoints if you have them (optional).
+      placeholder: |
+        Example page: https://www.producthunt.com/posts/example
+        GET https://api.producthunt.com/v2/posts?order=votes
+        Response: { "posts": [{ "name": "...", "tagline": "..." }] }
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Willing to Contribute?
+      options:
+        - label: I'm willing to submit a PR for this adapter

package/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+  # npm dependencies
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "chore(deps)"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "chore(ci)"

package/.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## Description
+
+<!-- Briefly describe your changes and link to any related issues. -->
+
+Related issue:
+
+## Type of Change
+
+- [ ] 🐛 Bug fix
+- [ ] ✨ New feature
+- [ ] 🌐 New site adapter
+- [ ] 📝 Documentation
+- [ ] ♻️ Refactor
+- [ ] 🔧 CI / build / tooling
+
+## Checklist
+
+- [ ] I ran the checks relevant to this PR
+- [ ] I updated tests or docs if needed
+- [ ] I included output or screenshots when useful
+
+## Screenshots / Output
+
+<!-- If applicable, paste CLI output or screenshots here. -->

package/.github/workflows/ci.yml

@@ -9,14 +9,18 @@ on:
     - cron: '0 8 * * 1'  # Weekly Monday 08:00 UTC — smoke tests
   workflow_dispatch:
 
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   # ── Fast gate: typecheck + build ──
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           cache: 'npm'
@@ -34,20 +38,22 @@ jobs:
   unit-test:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
+        node-version: ['20', '22']
         shard: [1, 2]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
-          node-version: '22'
+          node-version: ${{ matrix.node-version }}
           cache: 'npm'
 
       - name: Install dependencies
         run: npm ci
 
-      - name: Run unit tests (shard ${{ matrix.shard }}/2)
+      - name: Run unit tests (Node ${{ matrix.node-version }}, shard ${{ matrix.shard }}/2)
         run: npx vitest run src/ --reporter=verbose --shard=${{ matrix.shard }}/2
 
   # ── Smoke tests (scheduled / manual only) ──
@@ -56,9 +62,9 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           cache: 'npm'

package/.github/workflows/e2e-headed.yml

@@ -7,14 +7,18 @@ on:
     branches: [main, dev]
   workflow_dispatch:
 
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   e2e-headed:
     runs-on: ubuntu-latest
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           cache: 'npm'

package/.github/workflows/pkg-pr-new.yml

@@ -13,9 +13,9 @@ jobs:
     if: ${{ vars.PKG_PR_NEW_ENABLED == 'true' }}
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           cache: 'npm'

package/.github/workflows/release-please.yml

@@ -0,0 +1,25 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Ensure release-please token is configured
+        run: |
+          if [ -z "${{ secrets.RELEASE_PLEASE_TOKEN }}" ]; then
+            echo "RELEASE_PLEASE_TOKEN secret is required so release PRs can trigger downstream CI workflows." >&2
+            exit 1
+          fi
+
+      - uses: googleapis/release-please-action@v4
+        with:
+          release-type: node
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}

package/.github/workflows/release.yml

@@ -13,9 +13,9 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: '22'
           registry-url: 'https://registry.npmjs.org'

package/.github/workflows/security.yml

@@ -0,0 +1,36 @@
+name: Security Audit
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+  schedule:
+    - cron: '0 9 * * 1'  # Weekly Monday 09:00 UTC
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: npm audit (production)
+        run: npm audit --omit=dev --audit-level=high
+
+      - name: Check for known vulnerabilities
+        run: npx --yes audit-ci@^7 --high --skip-dev

package/CDP.md

@@ -1,6 +1,6 @@
 # Connecting OpenCLI via CDP (Remote/Headless Servers)
 
-If you cannot use the Playwright MCP Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**.
+If you cannot use the opencli Browser Bridge extension (e.g., in a remote headless server environment without a UI), OpenCLI provides an alternative: connecting directly to Chrome via **CDP (Chrome DevTools Protocol)**.
 
 Because CDP binds to `localhost` by default for security reasons, accessing it from a remote server requires an additional networking tunnel.
 

package/CDP.zh-CN.md

@@ -1,6 +1,6 @@
 # 通过 CDP 远程连接 OpenCLI (服务器/无头环境)
 
-如果你无法使用 Playwright MCP Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。
+如果你无法使用 opencli Browser Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。
 
 出于安全考虑，CDP 默认仅绑定在 `localhost` 的本地端口。所以，若是想让**远程服务器**调用本地的 CDP 服务，我们需要依靠一层额外的网络隧道。
 

package/CLI-ELECTRON.md

@@ -4,30 +4,51 @@ description: How to CLI-ify and automate any Electron Desktop Application via CD
 
 # CLI-ifying Electron Applications (Skill Guide)
 
-Based on the successful extraction and automation of **Antigravity** and **OpenAI Codex** desktop apps, this guide serves as the standard operating procedure (SOP) for adapting ANY Electron-based application into an OpenCLI adapter.
+Based on the successful automation of **Cursor**, **Codex**, **Antigravity**, **ChatWise**, **Notion**, and **Discord** desktop apps, this guide serves as the standard operating procedure (SOP) for adapting ANY Electron-based application into an OpenCLI adapter.
 
-## 核心原理 (Core Concept)
-Electron 应用本质上是运行在本地的 Chromium 浏览器实例。只要在启动应用时暴露了调试端口（CDP，Chrome DevTools Protocol），我们就可以利用 Playwright MCP 直接穿透其 UI 层，获取并操控包括 React/Vue 组件、Shadow DOM 等在内的所有底层状态，实现“从应用外挂入自动化脚本”。
+## Core Concept
 
-### 启动 Target App 
-要在本地操作任何 Electron 应用，必须先要求用户使用以下参数注入调试端点：
+Electron apps are essentially local Chromium browser instances. By exposing a debugging port (CDP — Chrome DevTools Protocol) at launch time, we can use the Browser Bridge to pierce through the UI layer, accessing and controlling all underlying state including React/Vue components and Shadow DOM.
+
+> **Note:** Not all desktop apps are Electron. WeChat (native Cocoa) and Feishu/Lark (custom Lark Framework) embed Chromium but do NOT expose CDP. For those apps, use the AppleScript + clipboard approach instead (see [Non-Electron Pattern](#non-electron-pattern-applescript)).
+
+### Launching the Target App
 ```bash
 /Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
 ```
 
-## 标准适配模式：The 5-Command Pattern
+### Verifying Electron
+```bash
+# Check for Electron Framework in the app bundle
+ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
+# If this directory exists → Electron → CDP works
+# If not → check for libEGL.dylib (embedded Chromium/CEF, CDP may not work)
+```
+
+## The 5-Command Pattern (CDP / Electron)
 
-适配一个新的 App，必须在 `src/clis/<app_name>/` 下实现这 5 个标准化指令：
+Every new Electron adapter should implement these 5 commands in `src/clis/<app_name>/`:
 
-### 1. `status.ts` (连接测试)
-负责确认应用监听正确。
-- **机制**: 直接 `export const statusCommand = cli({...})`
-- **核心代码**: 获取 `window.location.href` 与 `document.title`。
-- **注意**: 必须指明 `domain: 'localhost'` 和 `browser: true`。
+### 1. `status.ts` — Connection Test
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  name: 'status',
+  domain: 'localhost',
+  strategy: Strategy.UI,
+  browser: true,       // Requires CDP connection
+  args: [],
+  columns: ['Status', 'Url', 'Title'],
+  func: async (page: IPage) => {
+    const url = await page.evaluate('window.location.href');
+    const title = await page.evaluate('document.title');
+    return [{ Status: 'Connected', Url: url, Title: title }];
+  },
+});
+```
 
-### 2. `dump.ts` (逆向工程核心)
-很多现代 App DOM 极其庞大且混淆。**千万不要直接猜选择器**。
-首先编写 dump 脚本，将当前页面的 DOM 与 Accessibility Tree 导出到 `/tmp/`，方便用 AI (或者 `grep`) 提取精确的容器名称和 Class。
+### 2. `dump.ts` — Reverse Engineering Core
+Modern app DOMs are huge and obfuscated. **Never guess selectors.** Dump first, then extract precise class names with AI or `grep`:
 ```typescript
 const dom = await page.evaluate('document.body.innerHTML');
 fs.writeFileSync('/tmp/app-dom.html', dom);
@@ -35,38 +56,70 @@ const snap = await page.snapshot({ interactive: false });
 fs.writeFileSync('/tmp/app-snapshot.json', JSON.stringify(snap, null, 2));
 ```
 
-### 3. `send.ts` (高级注入技巧)
-Electron 应用常常使用极端复杂的富文本编辑器（如 Monaco, Lexical, ProseMirror）。直接修改元素的 `value` 常常会被 React 状态机忽略。
-- **最佳实践**: 使用 `document.execCommand('insertText')` 完美模拟真实的人类复制粘贴输入流，完全穿透 React state。
+### 3. `send.ts` — Advanced Text Injection
+Electron apps often use complex rich-text editors (Monaco, Lexical, ProseMirror). Setting `.value` directly is ignored by React state.
+
+**Best practice:** Use `document.execCommand('insertText')` to perfectly simulate real user input, fully piercing React state:
 ```javascript
-// 寻路机制：优先尝试寻找 contenteditable
-let composer = document.querySelector('[contenteditable="true"]');
+const composer = document.querySelector('[contenteditable="true"]');
 composer.focus();
-document.execCommand('insertText', false, "你好");
+document.execCommand('insertText', false, 'Hello');
 ```
-- **提交快捷键**: `await page.pressKey('Enter')`。
+Then submit with `await page.pressKey('Enter')`.
 
-### 4. `read.ts` (上下文解析)
-不要提取整个页面的文本。应该利用 `dump.ts` 抓取出来的特征寻找真正的“对话容器”。
-- **技巧**: 检查带有语义化结构的数据，例如 `[role="log"]`、`[data-testid="conversation"]` 或是 `[data-content-search-turn-key]`。
-- **格式化**: 拼接抓取出的文本转粗暴渲染成 Markdown 返回，这样不仅你和人类能读懂，LLM 后续作为 Agent 也能精准切分。
+### 4. `read.ts` — Context Extraction
+Don't extract the entire page text. Use `dump.ts` output to find the real "conversation container":
+- Look for semantic selectors: `[role="log"]`, `[data-testid="conversation"]`, `[data-content-search-turn-key]`
+- Format output as Markdown — readable by both humans and LLMs
 
-### 5. `new.ts` / Action Macros (底层事件模拟)
-许多图形界面操作难以找到按钮实例，但它们通常响应原生快捷键。
-- **最佳实践**: 模拟系统级快捷键直接驱动 `(Meta+N / Control+N)`。
+### 5. `new.ts` — Keyboard Shortcuts
+Many GUI actions respond to native shortcuts rather than button clicks:
 ```typescript
 const isMac = process.platform === 'darwin';
 await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
-await page.wait(1); // 等待重渲染
+await page.wait(1); // Wait for re-render
 ```
 
-## 全局环境变量
-为了让 Core Framework 挂载到我们指定的端口，必须在执行指令前（或在 README 中指导用户）注入目标环境端口：
+## Environment Variable
 ```bash
 export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
 ```
 
-## 踩坑避雷 (Pitfalls & Gotchas)
-1. **端口占用 (EADDRINUSE)**: 确保同一时间只能有一个 App 占据一个端口。如果同时测试 Antigravity (9224) 且你要测试别的 App (9222)，要将 CDP Endpoint 分配开来。
-2. **TypeScript 抽象**: OpenCLI 内部封装了 `IPage` 类型（`src/types.ts`），不是原生的 Playwright Page。要用 `page.pressKey()` 和 `page.evaluate()`，而非 `page.keyboard.press()`。
-3. **延时等待**: DOM 发生剧烈变化后，一定要加上 `await page.wait(0.5)` 到 `1.0` 给框架反应的时间。不要立刻 return 导致连接 prematurely 阻断。
+## Non-Electron Pattern (AppleScript)
+
+For native macOS apps (WeChat, Feishu) that don't expose CDP:
+```typescript
+export const statusCommand = cli({
+  site: 'myapp',
+  strategy: Strategy.PUBLIC,
+  browser: false,       // No browser needed
+  func: async (page: IPage | null) => {
+    const output = execSync("osascript -e 'application \"MyApp\" is running'", { encoding: 'utf-8' }).trim();
+    return [{ Status: output === 'true' ? 'Running' : 'Stopped' }];
+  },
+});
+```
+
+Core techniques:
+- **status**: `osascript -e 'application "AppName" is running'`
+- **send**: `pbcopy` → activate window → `Cmd+V` → `Enter`
+- **read**: `Cmd+A` → `Cmd+C` → `pbpaste`
+- **search**: Activate → `Cmd+F`/`Cmd+K` → `keystroke "query"`
+
+## Pitfalls & Gotchas
+
+1. **Port conflicts (EADDRINUSE)**: Only one app per port. Use unique ports: Codex=9222, ChatGPT=9224, Cursor=9226, ChatWise=9228, Notion=9230, Discord=9232
+2. **IPage abstraction**: OpenCLI wraps the browser page as `IPage` (`src/types.ts`). Use `page.pressKey()` and `page.evaluate()`, NOT direct DOM APIs
+3. **Timing**: Always add `await page.wait(0.5)` to `1.0` after DOM mutations. Returning too early disconnects prematurely
+4. **AppleScript requires Accessibility**: Terminal app must be granted permission in System Settings → Privacy & Security → Accessibility
+
+## Port Assignment Table
+
+| App | Port | Mode |
+|-----|------|------|
+| Codex | 9222 | CDP |
+| ChatGPT | 9224 | CDP / AppleScript |
+| Cursor | 9226 | CDP |
+| ChatWise | 9228 | CDP |
+| Notion | 9230 | CDP |
+| Discord App | 9232 | CDP |

package/CLI-EXPLORER.md

@@ -9,12 +9,12 @@
 
 ---
 
-## AI Agent 开发者必读：用 Playwright MCP Bridge 探索
+## AI Agent 开发者必读：用浏览器探索
 
 > [!CAUTION]
-> **你（AI Agent）必须通过 Playwright MCP Bridge 打开浏览器去访问目标网站！**  
+> **你（AI Agent）必须通过浏览器打开目标网站去探索！**  
 > 不要只靠 `opencli explore` 命令或静态分析来发现 API。  
-> 你拥有 Playwright MCP 工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。
+> 你拥有浏览器工具，必须主动用它们浏览网页、观察网络请求、模拟用户交互。
 
 ### 为什么？
 
@@ -36,7 +36,7 @@
 
 | ❌ 错误做法 | ✅ 正确做法 |
 |------------|------------|
-| 只用 `opencli explore` 命令，等结果自动出来 | 用 MCP Bridge 打开浏览器，主动浏览页面 |
+| 只用 `opencli explore` 命令，等结果自动出来 | 用浏览器工具打开页面，主动浏览 |
 | 直接在代码里 `fetch(url)`，不看浏览器实际请求 | 先在浏览器中确认 API 可用，再写代码 |
 | 页面打开后直接抓包，期望所有 API 都出现 | 模拟点击交互（展开评论/切换标签/加载更多） |
 | 遇到 HTTP 200 但空数据就放弃 | 检查是否需要 Wbi 签名或 Cookie 鉴权 |