@jackwener/opencli 1.0.5 → 1.1.0

package/src/external-clis.yaml

@@ -0,0 +1,39 @@
+- name: gh
+  binary: gh
+  description: "GitHub CLI — repos, PRs, issues, releases, gists"
+  homepage: "https://cli.github.com"
+  tags: [github, git, dev]
+  install:
+    mac: "brew install gh"
+
+- name: obsidian
+  binary: obsidian
+  description: "Obsidian vault management — notes, search, tags, tasks, sync"
+  homepage: "https://obsidian.md/help/cli"
+  tags: [notes, knowledge, markdown]
+  install:
+    mac: "brew install --cask obsidian"
+
+- name: readwise
+  binary: readwise
+  description: "Readwise & Reader CLI — highlights, annotations, reading list"
+  homepage: "https://github.com/readwiseio/readwise-cli"
+  tags: [reading, highlights]
+  install:
+    default: "npm install -g @readwiseio/readwise-cli"
+
+- name: kubectl
+  binary: kubectl
+  description: "Kubernetes command-line tool"
+  homepage: "https://kubernetes.io/docs/reference/kubectl/"
+  tags: [kubernetes, k8s, devops]
+  install:
+    mac: "brew install kubectl"
+
+- name: docker
+  binary: docker
+  description: "Docker command-line interface"
+  homepage: "https://docs.docker.com/engine/reference/commandline/cli/"
+  tags: [docker, containers, devops]
+  install:
+    mac: "brew install --cask docker"

package/src/external.ts

@@ -0,0 +1,182 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawnSync, execSync } from 'node:child_process';
+import yaml from 'js-yaml';
+import chalk from 'chalk';
+import { log } from './logger.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export interface ExternalCliInstall {
+  mac?: string;
+  linux?: string;
+  windows?: string;
+  default?: string;
+}
+
+export interface ExternalCliConfig {
+  name: string;
+  binary: string;
+  description?: string;
+  homepage?: string;
+  tags?: string[];
+  install?: ExternalCliInstall;
+}
+
+function getUserRegistryPath(): string {
+  const home = os.homedir();
+  return path.join(home, '.opencli', 'external-clis.yaml');
+}
+
+export function loadExternalClis(): ExternalCliConfig[] {
+  const configs = new Map<string, ExternalCliConfig>();
+
+  // 1. Load built-in
+  const builtinPath = path.resolve(__dirname, 'external-clis.yaml');
+  try {
+    if (fs.existsSync(builtinPath)) {
+      const raw = fs.readFileSync(builtinPath, 'utf8');
+      const parsed = (yaml.load(raw) || []) as ExternalCliConfig[];
+      for (const item of parsed) configs.set(item.name, item);
+    }
+  } catch (err: any) {
+    log.warn(`Failed to parse built-in external-clis.yaml: ${err.message}`);
+  }
+
+  // 2. Load user custom
+  const userPath = getUserRegistryPath();
+  try {
+    if (fs.existsSync(userPath)) {
+      const raw = fs.readFileSync(userPath, 'utf8');
+      const parsed = (yaml.load(raw) || []) as ExternalCliConfig[];
+      for (const item of parsed) {
+        configs.set(item.name, item); // Overwrite built-in if duplicated
+      }
+    }
+  } catch (err: any) {
+    log.warn(`Failed to parse user external-clis.yaml: ${err.message}`);
+  }
+
+  return Array.from(configs.values()).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function isBinaryInstalled(binary: string): boolean {
+  try {
+    const isWindows = os.platform() === 'win32';
+    const cmd = isWindows ? 'where' : 'command -v';
+    execSync(`${cmd} ${binary}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getInstallCmd(installConfig?: ExternalCliInstall): string | null {
+  if (!installConfig) return null;
+  const platform = os.platform();
+  if (platform === 'darwin' && installConfig.mac) return installConfig.mac;
+  if (platform === 'linux' && installConfig.linux) return installConfig.linux;
+  if (platform === 'win32' && installConfig.windows) return installConfig.windows;
+  if (installConfig.default) return installConfig.default;
+  return null;
+}
+
+export function installExternalCli(cli: ExternalCliConfig): boolean {
+  if (!cli.install) {
+    console.error(chalk.red(`No auto-install command configured for '${cli.name}'.`));
+    console.error(`Please install '${cli.binary}' manually.`);
+    return false;
+  }
+
+  const cmd = getInstallCmd(cli.install);
+  if (!cmd) {
+    console.error(chalk.red(`No install command for your platform (${os.platform()}) for '${cli.name}'.`));
+    if (cli.homepage) console.error(`See: ${cli.homepage}`);
+    return false;
+  }
+
+  console.log(chalk.cyan(`🔹 '${cli.name}' is not installed. Auto-installing...`));
+  console.log(chalk.dim(`$ ${cmd}`));
+  try {
+    execSync(cmd, { stdio: 'inherit' });
+    console.log(chalk.green(`✅ Installed '${cli.name}' successfully.\n`));
+    return true;
+  } catch (err: any) {
+    console.error(chalk.red(`❌ Failed to install '${cli.name}': ${err.message}`));
+    return false;
+  }
+}
+
+export async function executeExternalCli(name: string, args: string[]): Promise<void> {
+  const configs = loadExternalClis();
+  const cli = configs.find((c) => c.name === name);
+  if (!cli) {
+    throw new Error(`External CLI '${name}' not found in registry.`);
+  }
+
+  // 1. Check if installed
+  if (!isBinaryInstalled(cli.binary)) {
+    // 2. Try to auto install
+    const success = installExternalCli(cli);
+    if (!success) {
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  // 3. Passthrough execution
+  // We use spawnSync to properly inherit stdio and block until completion
+  const result = spawnSync(cli.binary, args, { stdio: 'inherit' });
+  if (result.error) {
+    console.error(chalk.red(`Failed to execute '${cli.binary}': ${result.error.message}`));
+    process.exitCode = 1;
+    return;
+  }
+  
+  if (result.status !== null) {
+    process.exitCode = result.status;
+  }
+}
+
+export function registerExternalCli(name: string, binary?: string, install?: string, description?: string): void {
+  const userPath = getUserRegistryPath();
+  const configDir = path.dirname(userPath);
+
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  let items: ExternalCliConfig[] = [];
+  if (fs.existsSync(userPath)) {
+    try {
+      const raw = fs.readFileSync(userPath, 'utf8');
+      items = (yaml.load(raw) || []) as ExternalCliConfig[];
+    } catch {
+      // Ignore
+    }
+  }
+
+  const existingIndex = items.findIndex((c) => c.name === name);
+  
+  const newItem: ExternalCliConfig = {
+    name,
+    binary: binary || name,
+  };
+  if (description) newItem.description = description;
+  if (install) newItem.install = { default: install };
+
+  if (existingIndex >= 0) {
+    // Merge
+    items[existingIndex] = { ...items[existingIndex], ...newItem };
+    console.log(chalk.green(`Updated '${name}' in user registry.`));
+  } else {
+    items.push(newItem);
+    console.log(chalk.green(`Registered '${name}' in user registry.`));
+  }
+
+  const dump = yaml.dump(items, { indent: 2, sortKeys: true });
+  fs.writeFileSync(userPath, dump, 'utf8');
+  console.log(chalk.dim(userPath));
+}

package/CDP.md

@@ -1,103 +0,0 @@
-# Connecting OpenCLI via CDP (Remote/Headless Servers)
-
-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.
-
-This guide is broken down into three phases:
-1. **Preparation**: Start Chrome with CDP enabled locally.
-2. **Network Tunnels**: Expose that CDP port to your remote server using either **SSH Tunnels** or **Reverse Proxies**.
-3. **Execution**: Run OpenCLI on your server.
-
----
-
-## Phase 1: Preparation (Local Machine)
-
-First, you need to start a Chrome browser on your local machine with remote debugging enabled.
-
-**macOS:**
-```bash
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/chrome-debug-profile" \
-  --remote-allow-origins="*"
-```
-
-**Linux:**
-```bash
-google-chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/chrome-debug-profile" \
-  --remote-allow-origins="*"
-```
-
-**Windows:**
-```cmd
-"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
-  --remote-debugging-port=9222 ^
-  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
-  --remote-allow-origins="*"
-```
-
-> **Note**: The `--remote-allow-origins="*"` flag is often required for modern Chrome versions to accept cross-origin CDP WebSocket connections (e.g. from reverse proxies like ngrok).
-
-Once this browser instance opens, **log into the target websites you want to use** (e.g., bilibili.com, zhihu.com) so that the session contains the correct cookies.
-
----
-
-## Phase 2: Remote Access Methods
-
-Once CDP is running locally on port `9222`, you must securely expose this port to your remote server. Choose one of the two methods below depending on your network conditions.
-
-### Method A: SSH Tunnel (Recommended)
-
-If your local machine has SSH access to the remote server, this is the most secure and straightforward method.
-
-Run this command on your **Local Machine** to forward the remote server's port `9222` back to your local port `9222`:
-
-```bash
-ssh -R 9222:localhost:9222 your-server-user@your-server-ip
-```
-
-Leave this SSH session running in the background.
-
-### Method B: Reverse Proxy (ngrok / frp / socat)
-
-If you cannot establish a direct SSH connection (e.g., due to NAT or firewalls), you can use an intranet penetration tool like `ngrok`.
-
-Run this command on your **Local Machine** to expose your local port `9222` to the public internet securely via ngrok:
-
-```bash
-ngrok http 9222
-```
-
-This will print a forwarding URL, such as `https://abcdef.ngrok.app`. **Copy this URL**.
-
----
-
-## Phase 3: Execution (Remote Server)
-
-Now switch to your **Remote Server** where OpenCLI is installed. 
-
-Depending on the network tunnel method you chose in Phase 2, set the `OPENCLI_CDP_ENDPOINT` environment variable and run your commands.
-
-### If you used Method A (SSH Tunnel):
-
-```bash
-export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
-opencli doctor                    # Verify connection
-opencli bilibili hot --limit 5    # Test a command
-```
-
-### If you used Method B (Reverse Proxy like ngrok):
-
-```bash
-# Use the URL you copied from ngrok earlier
-export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
-opencli doctor                    # Verify connection
-opencli bilibili hot --limit 5    # Test a command
-```
-
-> *Tip: If you provide a standard HTTP/HTTPS CDP endpoint, OpenCLI requests the `/json` target list and picks the most likely inspectable app/page target automatically. If multiple app targets exist, you can further narrow selection with `OPENCLI_CDP_TARGET` (for example `antigravity` or `codex`).*
-
-If you plan to use this setup frequently, you can persist the environment variable by adding the `export` line to your `~/.bashrc` or `~/.zshrc` on the server.

package/CDP.zh-CN.md

@@ -1,103 +0,0 @@
-# 通过 CDP 远程连接 OpenCLI (服务器/无头环境)
-
-如果你无法使用 opencli Browser Bridge 浏览器扩展（例如：在无界面的远程服务器上运行 OpenCLI 时），OpenCLI 提供了备选方案：通过连接 **CDP (Chrome DevTools Protocol，即 Chrome 开发者工具协议)** 来直接控制本地 Chrome。
-
-出于安全考虑，CDP 默认仅绑定在 `localhost` 的本地端口。所以，若是想让**远程服务器**调用本地的 CDP 服务，我们需要依靠一层额外的网络隧道。
-
-本指南将整个过程拆分为三个阶段：
-1. **阶段一：准备工作**（在本地启动允许 CDP 调试的 Chrome）。
-2. **阶段二：建立网络隧道**（通过 **SSH反向隧道** 或 **反向代理工具**，将本地的 CDP 端口暴露给服务器）。
-3. **阶段三：执行命令**（在服务器端运行 OpenCLI）。
-
----
-
-## 阶段一：准备工作 (本地电脑)
-
-首先，你需要在你的本地电脑上，通过命令行参数启动一个开启了远程调试端口的 Chrome 实例。
-
-**macOS:**
-```bash
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/chrome-debug-profile" \
-  --remote-allow-origins="*"
-```
-
-**Linux:**
-```bash
-google-chrome \
-  --remote-debugging-port=9222 \
-  --user-data-dir="$HOME/chrome-debug-profile" \
-  --remote-allow-origins="*"
-```
-
-**Windows:**
-```cmd
-"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
-  --remote-debugging-port=9222 ^
-  --user-data-dir="%USERPROFILE%\chrome-debug-profile" ^
-  --remote-allow-origins="*"
-```
-
-> **注意**：此处增加的 `--remote-allow-origins="*"` 参数对于较新版本的 Chrome 来说通常是[必需的]，以允许来自反向代理（如 ngrok）的跨域 WebSocket 连接请求。
-
-待这个新的浏览器实例打开后，**手工登录那些你打算使用的网站**（如 bilibili.com、zhihu.com 等），这可以让该浏览器的运行资料（Profile）保留上这些网站登录用的 Cookie。
-
----
-
-## 阶段二：建立网络隧道
-
-现在你的本地已经有了一个监听在 `9222` 端口的 CDP 服务，接下来，选择以下任意一种方式将其实际暴露给你的远端服务器。
-
-### 方法 A：SSH 反向端口转发 (推荐)
-
-如果你的本地电脑可以直连远程服务器的 SSH，那么这是最简单且最安全的做法。
-
-在你的 **本地电脑** 终端上直接运行这条 ssh 命令，将远程服务器的 `9222` 端口反向映射回本地的 `9222` 端口：
-
-```bash
-ssh -R 9222:localhost:9222 your-server-user@your-server-ip
-```
-
-保持此 SSH 会话在后台运行即可。
-
-### 方法 B：反向代理 / 内网穿透 (ngrok / frp / socat)
-
-如果因为 NAT 或防火墙等因素导致无法直连 SSH 服务器，你可以使用 `ngrok` 等内网穿透工具。
-
-在 **本地电脑** 运行 ngrok 将本地的 `9222` 端口暴露到公网：
-
-```bash
-ngrok http 9222
-```
-
-此时终端里会打印出一段专属的转发 URL 地址（如：`https://abcdef.ngrok.app`）。**复制这一段 URL 地址备用**。
-
----
-
-## 阶段三：执行命令 (远程服务器)
-
-现在，所有的准备工作已结束。请切换到你已安装好 OpenCLI 的 **远程服务器** 终端上。
-
-根据你在上方阶段二所选择的隧道方案，在终端中配置对应的 `OPENCLI_CDP_ENDPOINT` 环境变量：
-
-### 若使用 方法 A (SSH 反向隧道)：
-
-```bash
-export OPENCLI_CDP_ENDPOINT="http://localhost:9222"
-opencli doctor                    # 查看并验证连接是否通畅
-opencli bilibili hot --limit 5    # 执行目标命令
-```
-
-### 若使用 方法 B (Ngrok 等反向代理)：
-
-```bash
-# 将刚刚使用 ngrok 得到的地址填入这里
-export OPENCLI_CDP_ENDPOINT="https://abcdef.ngrok.app"
-opencli doctor                    # 查看并验证连接是否通畅
-opencli bilibili hot --limit 5    # 执行目标命令
-```
-
-> *Tip: 如果你填写的是一个普通 HTTP/HTTPS 的 CDP 地址，OpenCLI 会自动请求 `/json` target 列表，并挑选最可能的 app/page target；如果同一个端口下暴露了多个应用 target，还可以通过 `OPENCLI_CDP_TARGET`（例如 `antigravity`、`codex`）进一步缩小匹配范围。*
-
-如果你想在此服务器上永久启用该配置，可以将对应的 `export` 语句追加进入你的 `~/.bashrc` 或 `~/.zshrc` 配置文件中。

package/CLI-ELECTRON.md

@@ -1,125 +0,0 @@
----
-description: How to CLI-ify and automate any Electron Desktop Application via CDP
----
-
-# CLI-ifying Electron Applications (Skill Guide)
-
-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 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
-```
-
-### 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)
-
-Every new Electron adapter should implement these 5 commands in `src/clis/<app_name>/`:
-
-### 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` — 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);
-const snap = await page.snapshot({ interactive: false });
-fs.writeFileSync('/tmp/app-snapshot.json', JSON.stringify(snap, null, 2));
-```
-
-### 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
-const composer = document.querySelector('[contenteditable="true"]');
-composer.focus();
-document.execCommand('insertText', false, 'Hello');
-```
-Then submit with `await page.pressKey('Enter')`.
-
-### 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` — 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); // Wait for re-render
-```
-
-## Environment Variable
-```bash
-export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
-```
-
-## 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 |