@jackwener/opencli 1.0.3 → 1.0.4

package/docs/guide/troubleshooting.md

@@ -0,0 +1,56 @@
+# Troubleshooting
+
+## Common Issues
+
+### "Extension not connected"
+
+- Ensure the opencli Browser Bridge extension is installed and **enabled** in `chrome://extensions`.
+- Run `opencli doctor` to diagnose connectivity.
+
+### Empty data or 'Unauthorized' error
+
+- Your login session in Chrome might have expired. Open a normal Chrome tab, navigate to the target site, and log in or refresh the page.
+- Some sites have geographic restrictions (e.g., Bilibili, Zhihu from outside China).
+
+### Node API errors
+
+- Make sure you are using **Node.js >= 20**. Some dependencies require modern Node APIs.
+- Run `node --version` to verify.
+
+### Daemon issues
+
+```bash
+# Check daemon status
+curl localhost:19825/status
+
+# View extension logs
+curl localhost:19825/logs
+
+# Kill and restart daemon
+pkill -f opencli-daemon
+opencli doctor
+```
+
+### Desktop adapter connection issues
+
+For Electron/CDP-based adapters (Cursor, Codex, etc.):
+
+1. Make sure the app is launched with `--remote-debugging-port=XXXX`
+2. Verify the endpoint is set: `echo $OPENCLI_CDP_ENDPOINT`
+3. Test the endpoint: `curl http://127.0.0.1:XXXX/json/version`
+
+### Build errors
+
+```bash
+# Clean rebuild
+rm -rf dist/
+npm run build
+
+# Type check
+npx tsc --noEmit
+```
+
+## Getting Help
+
+- [GitHub Issues](https://github.com/jackwener/opencli/issues) — Bug reports and feature requests
+- Run `opencli doctor --live` for comprehensive diagnostics

package/docs/index.md

@@ -0,0 +1,35 @@
+---
+layout: home
+
+hero:
+  name: OpenCLI
+  text: Make any website or Electron App your CLI
+  tagline: Zero risk · Reuse Chrome login · AI-powered discovery · Browser + Desktop automation
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/jackwener/opencli
+
+features:
+  - icon: 🖥️
+    title: CLI All Electron
+    details: Turn ANY Electron application into a CLI tool — Cursor, Codex, Antigravity, ChatGPT, Notion, and more. AI can control itself natively.
+  - icon: 🔐
+    title: Account Safe
+    details: Reuses Chrome's logged-in state. Your credentials never leave the browser — no tokens, no exposed passwords.
+  - icon: 🤖
+    title: AI Agent Ready
+    details: "explore discovers APIs, synthesize generates adapters, cascade finds auth strategies. Built for AI-first workflows."
+  - icon: ⚡
+    title: Dual-Engine Architecture
+    details: Supports both YAML declarative data pipelines and robust browser runtime TypeScript injections for maximum flexibility.
+  - icon: 🔧
+    title: Self-Healing Setup
+    details: "opencli setup verifies Browser Bridge connectivity. opencli doctor diagnoses daemon, extension, and live browser."
+  - icon: 📦
+    title: Dynamic Loader
+    details: Simply drop .ts or .yaml adapters into the clis/ folder for auto-registration. Zero boilerplate.
+---

package/docs/zh/adapters/index.md

@@ -0,0 +1,5 @@
+# 所有适配器
+
+运行 `opencli list` 查看完整命令列表。
+
+详细文档请参考 [英文版本](/adapters/)。

package/docs/zh/advanced/cdp.md

@@ -0,0 +1,3 @@
+# Chrome DevTools Protocol
+
+详细文档请参考 [英文版本](/advanced/cdp)。

package/docs/zh/developer/contributing.md

@@ -0,0 +1,24 @@
+# 贡献指南
+
+详细贡献指南请参考 [英文版本](/developer/contributing)。
+
+## 快速开始
+
+```bash
+git clone git@github.com:<your-username>/opencli.git
+cd opencli
+npm install
+npm run build
+npx tsc --noEmit
+npx vitest run src/
+```
+
+## 提交规范
+
+使用 [Conventional Commits](https://www.conventionalcommits.org/)：
+
+```
+feat(twitter): add thread command
+fix(browser): handle CDP timeout gracefully
+docs: update CONTRIBUTING.md
+```

package/docs/zh/guide/browser-bridge.md

@@ -0,0 +1,25 @@
+# Browser Bridge 设置
+
+> **⚠️ 重要**: 浏览器命令复用你的 Chrome 登录会话。运行命令前必须在 Chrome 中登录目标网站。
+
+OpenCLI 通过轻量级 **Browser Bridge** Chrome 扩展 + 微守护进程连接浏览器（零配置，自动启动）。
+
+## 扩展安装
+
+### 方法 1：下载预构建版本（推荐）
+
+1. 前往 GitHub [Releases 页面](https://github.com/jackwener/opencli/releases) 下载最新的 `opencli-extension.zip` 或 `opencli-extension.crx`。
+2. 打开 `chrome://extensions`，启用**开发者模式**。
+3. 拖放 `.crx` 文件或解压后的文件夹到扩展页面。
+
+### 方法 2：加载源码（开发者）
+
+1. 打开 `chrome://extensions`，启用**开发者模式**。
+2. 点击**加载已解压的扩展程序**，选择仓库中的 `extension/` 目录。
+
+## 验证
+
+```bash
+opencli doctor            # 检查扩展 + 守护进程连接
+opencli doctor --live     # 同时测试实时浏览器命令
+```

package/docs/zh/guide/getting-started.md

@@ -0,0 +1,40 @@
+# 快速开始
+
+> **让任何网站或 Electron 应用成为你的 CLI。**
+> 零风险 · 复用 Chrome 登录态 · AI 驱动发现 · 浏览器 + 桌面自动化
+
+OpenCLI 将**任何网站**或 **Electron 应用**变成命令行界面 — Bilibili、知乎、小红书、Twitter/X、Reddit、YouTube、Antigravity 等 — 基于浏览器会话复用和 AI 原生发现。
+
+## 安装
+
+```bash
+npm install -g @jackwener/opencli
+```
+
+## 基本使用
+
+```bash
+opencli list                              # 查看所有命令
+opencli hackernews top --limit 5          # 公开 API，无需浏览器
+opencli bilibili hot --limit 5            # 浏览器命令
+opencli zhihu hot -f json                 # JSON 输出
+```
+
+## 输出格式
+
+所有命令支持 `--format` / `-f`：
+
+```bash
+opencli bilibili hot -f table   # 默认：终端表格
+opencli bilibili hot -f json    # JSON
+opencli bilibili hot -f yaml    # YAML
+opencli bilibili hot -f md      # Markdown
+opencli bilibili hot -f csv     # CSV
+```
+
+## 下一步
+
+- [安装详情](/zh/guide/installation)
+- [Browser Bridge 设置](/zh/guide/browser-bridge)
+- [所有适配器](/zh/adapters/)
+- [开发者指南](/zh/developer/contributing)

package/docs/zh/guide/installation.md

@@ -0,0 +1,37 @@
+# 安装
+
+## 系统要求
+
+- **Node.js**: >= 20.0.0
+- **Chrome** 已运行并登录目标网站（浏览器命令需要）
+
+## 通过 npm 安装（推荐）
+
+```bash
+npm install -g @jackwener/opencli
+```
+
+## 从源码安装
+
+```bash
+git clone git@github.com:jackwener/opencli.git
+cd opencli
+npm install
+npm run build
+npm link
+opencli list
+```
+
+## 更新
+
+```bash
+npm install -g @jackwener/opencli@latest
+```
+
+## 验证安装
+
+```bash
+opencli --version
+opencli list
+opencli doctor
+```

package/docs/zh/index.md

@@ -0,0 +1,29 @@
+---
+layout: home
+
+hero:
+  name: OpenCLI
+  text: 让任何网站或 Electron 应用成为你的 CLI
+  tagline: 零风险 · 复用 Chrome 登录态 · AI 驱动发现 · 浏览器 + 桌面自动化
+  actions:
+    - theme: brand
+      text: 快速开始
+      link: /zh/guide/getting-started
+    - theme: alt
+      text: 在 GitHub 查看
+      link: https://github.com/jackwener/opencli
+
+features:
+  - icon: 🖥️
+    title: CLI 所有 Electron 应用
+    details: 将任何 Electron 应用变成 CLI 工具 — Cursor、Codex、Antigravity、ChatGPT、Notion 等。AI 可以原生控制自身。
+  - icon: 🔐
+    title: 账号安全
+    details: 复用 Chrome 登录态，凭证永远不会离开浏览器 — 无 token，无密码泄露。
+  - icon: 🤖
+    title: AI Agent 就绪
+    details: explore 发现 API，synthesize 生成适配器，cascade 查找认证策略。为 AI 优先工作流而生。
+  - icon: ⚡
+    title: 双引擎架构
+    details: 同时支持 YAML 声明式数据管道和强大的浏览器运行时 TypeScript 注入。
+---

package/extension/dist/background.js

@@ -160,30 +160,35 @@ function scheduleReconnect() {
     connect();
   }, delay);
 }
-let automationWindowId = null;
-let windowIdleTimer = null;
+const automationSessions = /* @__PURE__ */ new Map();
 const WINDOW_IDLE_TIMEOUT = 3e4;
-function resetWindowIdleTimer() {
-  if (windowIdleTimer) clearTimeout(windowIdleTimer);
-  windowIdleTimer = setTimeout(async () => {
-    if (automationWindowId !== null) {
-      try {
-        await chrome.windows.remove(automationWindowId);
-        console.log(`[opencli] Automation window ${automationWindowId} closed (idle timeout)`);
-      } catch {
-      }
-      automationWindowId = null;
+function getWorkspaceKey(workspace) {
+  return workspace?.trim() || "default";
+}
+function resetWindowIdleTimer(workspace) {
+  const session = automationSessions.get(workspace);
+  if (!session) return;
+  if (session.idleTimer) clearTimeout(session.idleTimer);
+  session.idleDeadlineAt = Date.now() + WINDOW_IDLE_TIMEOUT;
+  session.idleTimer = setTimeout(async () => {
+    const current = automationSessions.get(workspace);
+    if (!current) return;
+    try {
+      await chrome.windows.remove(current.windowId);
+      console.log(`[opencli] Automation window ${current.windowId} (${workspace}) closed (idle timeout)`);
+    } catch {
     }
-    windowIdleTimer = null;
+    automationSessions.delete(workspace);
   }, WINDOW_IDLE_TIMEOUT);
 }
-async function getAutomationWindow() {
-  if (automationWindowId !== null) {
+async function getAutomationWindow(workspace) {
+  const existing = automationSessions.get(workspace);
+  if (existing) {
     try {
-      await chrome.windows.get(automationWindowId);
-      return automationWindowId;
+      await chrome.windows.get(existing.windowId);
+      return existing.windowId;
     } catch {
-      automationWindowId = null;
+      automationSessions.delete(workspace);
     }
   }
   const win = await chrome.windows.create({
@@ -193,17 +198,22 @@ async function getAutomationWindow() {
     height: 900,
     type: "normal"
   });
-  automationWindowId = win.id;
-  console.log(`[opencli] Created automation window ${automationWindowId}`);
-  return automationWindowId;
+  const session = {
+    windowId: win.id,
+    idleTimer: null,
+    idleDeadlineAt: Date.now() + WINDOW_IDLE_TIMEOUT
+  };
+  automationSessions.set(workspace, session);
+  console.log(`[opencli] Created automation window ${session.windowId} (${workspace})`);
+  resetWindowIdleTimer(workspace);
+  return session.windowId;
 }
 chrome.windows.onRemoved.addListener((windowId) => {
-  if (windowId === automationWindowId) {
-    console.log("[opencli] Automation window closed");
-    automationWindowId = null;
-    if (windowIdleTimer) {
-      clearTimeout(windowIdleTimer);
-      windowIdleTimer = null;
+  for (const [workspace, session] of automationSessions.entries()) {
+    if (session.windowId === windowId) {
+      console.log(`[opencli] Automation window closed (${workspace})`);
+      if (session.idleTimer) clearTimeout(session.idleTimer);
+      automationSessions.delete(workspace);
     }
   }
 });
@@ -226,21 +236,24 @@ chrome.alarms.onAlarm.addListener((alarm) => {
   if (alarm.name === "keepalive") connect();
 });
 async function handleCommand(cmd) {
-  resetWindowIdleTimer();
+  const workspace = getWorkspaceKey(cmd.workspace);
+  resetWindowIdleTimer(workspace);
   try {
     switch (cmd.action) {
       case "exec":
-        return await handleExec(cmd);
+        return await handleExec(cmd, workspace);
       case "navigate":
-        return await handleNavigate(cmd);
+        return await handleNavigate(cmd, workspace);
       case "tabs":
-        return await handleTabs(cmd);
+        return await handleTabs(cmd, workspace);
       case "cookies":
         return await handleCookies(cmd);
       case "screenshot":
-        return await handleScreenshot(cmd);
+        return await handleScreenshot(cmd, workspace);
       case "close-window":
-        return await handleCloseWindow(cmd);
+        return await handleCloseWindow(cmd, workspace);
+      case "sessions":
+        return await handleSessions(cmd);
       default:
         return { id: cmd.id, ok: false, error: `Unknown action: ${cmd.action}` };
     }
@@ -256,9 +269,9 @@ function isWebUrl(url) {
   if (!url) return false;
   return !url.startsWith("chrome://") && !url.startsWith("chrome-extension://");
 }
-async function resolveTabId(tabId) {
+async function resolveTabId(tabId, workspace) {
   if (tabId !== void 0) return tabId;
-  const windowId = await getAutomationWindow();
+  const windowId = await getAutomationWindow(workspace);
   const tabs = await chrome.tabs.query({ windowId });
   const webTab = tabs.find((t) => t.id && isWebUrl(t.url));
   if (webTab?.id) return webTab.id;
@@ -267,9 +280,23 @@ async function resolveTabId(tabId) {
   if (!newTab.id) throw new Error("Failed to create tab in automation window");
   return newTab.id;
 }
-async function handleExec(cmd) {
+async function listAutomationTabs(workspace) {
+  const session = automationSessions.get(workspace);
+  if (!session) return [];
+  try {
+    return await chrome.tabs.query({ windowId: session.windowId });
+  } catch {
+    automationSessions.delete(workspace);
+    return [];
+  }
+}
+async function listAutomationWebTabs(workspace) {
+  const tabs = await listAutomationTabs(workspace);
+  return tabs.filter((tab) => isWebUrl(tab.url));
+}
+async function handleExec(cmd, workspace) {
   if (!cmd.code) return { id: cmd.id, ok: false, error: "Missing code" };
-  const tabId = await resolveTabId(cmd.tabId);
+  const tabId = await resolveTabId(cmd.tabId, workspace);
   try {
     const data = await evaluateAsync(tabId, cmd.code);
     return { id: cmd.id, ok: true, data };
@@ -277,9 +304,9 @@ async function handleExec(cmd) {
     return { id: cmd.id, ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
-async function handleNavigate(cmd) {
+async function handleNavigate(cmd, workspace) {
   if (!cmd.url) return { id: cmd.id, ok: false, error: "Missing url" };
-  const tabId = await resolveTabId(cmd.tabId);
+  const tabId = await resolveTabId(cmd.tabId, workspace);
   await chrome.tabs.update(tabId, { url: cmd.url });
   await new Promise((resolve) => {
     chrome.tabs.get(tabId).then((tab2) => {
@@ -303,11 +330,11 @@ async function handleNavigate(cmd) {
   const tab = await chrome.tabs.get(tabId);
   return { id: cmd.id, ok: true, data: { title: tab.title, url: tab.url, tabId } };
 }
-async function handleTabs(cmd) {
+async function handleTabs(cmd, workspace) {
   switch (cmd.op) {
     case "list": {
-      const tabs = await chrome.tabs.query({});
-      const data = tabs.filter((t) => isWebUrl(t.url)).map((t, i) => ({
+      const tabs = await listAutomationWebTabs(workspace);
+      const data = tabs.map((t, i) => ({
         index: i,
         tabId: t.id,
         url: t.url,
@@ -317,19 +344,20 @@ async function handleTabs(cmd) {
       return { id: cmd.id, ok: true, data };
     }
     case "new": {
-      const tab = await chrome.tabs.create({ url: cmd.url, active: true });
+      const windowId = await getAutomationWindow(workspace);
+      const tab = await chrome.tabs.create({ windowId, url: cmd.url ?? "about:blank", active: true });
       return { id: cmd.id, ok: true, data: { tabId: tab.id, url: tab.url } };
     }
     case "close": {
       if (cmd.index !== void 0) {
-        const tabs = await chrome.tabs.query({});
+        const tabs = await listAutomationWebTabs(workspace);
         const target = tabs[cmd.index];
         if (!target?.id) return { id: cmd.id, ok: false, error: `Tab index ${cmd.index} not found` };
         await chrome.tabs.remove(target.id);
         detach(target.id);
         return { id: cmd.id, ok: true, data: { closed: target.id } };
       }
-      const tabId = await resolveTabId(cmd.tabId);
+      const tabId = await resolveTabId(cmd.tabId, workspace);
       await chrome.tabs.remove(tabId);
       detach(tabId);
       return { id: cmd.id, ok: true, data: { closed: tabId } };
@@ -341,7 +369,7 @@ async function handleTabs(cmd) {
         await chrome.tabs.update(cmd.tabId, { active: true });
         return { id: cmd.id, ok: true, data: { selected: cmd.tabId } };
       }
-      const tabs = await chrome.tabs.query({});
+      const tabs = await listAutomationWebTabs(workspace);
       const target = tabs[cmd.index];
       if (!target?.id) return { id: cmd.id, ok: false, error: `Tab index ${cmd.index} not found` };
       await chrome.tabs.update(target.id, { active: true });
@@ -367,8 +395,8 @@ async function handleCookies(cmd) {
   }));
   return { id: cmd.id, ok: true, data };
 }
-async function handleScreenshot(cmd) {
-  const tabId = await resolveTabId(cmd.tabId);
+async function handleScreenshot(cmd, workspace) {
+  const tabId = await resolveTabId(cmd.tabId, workspace);
   try {
     const data = await screenshot(tabId, {
       format: cmd.format,
@@ -380,13 +408,25 @@ async function handleScreenshot(cmd) {
     return { id: cmd.id, ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
-async function handleCloseWindow(cmd) {
-  if (automationWindowId !== null) {
+async function handleCloseWindow(cmd, workspace) {
+  const session = automationSessions.get(workspace);
+  if (session) {
     try {
-      await chrome.windows.remove(automationWindowId);
+      await chrome.windows.remove(session.windowId);
     } catch {
     }
-    automationWindowId = null;
+    if (session.idleTimer) clearTimeout(session.idleTimer);
+    automationSessions.delete(workspace);
   }
   return { id: cmd.id, ok: true, data: { closed: true } };
 }
+async function handleSessions(cmd) {
+  const now = Date.now();
+  const data = await Promise.all([...automationSessions.entries()].map(async ([workspace, session]) => ({
+    workspace,
+    windowId: session.windowId,
+    tabCount: (await chrome.tabs.query({ windowId: session.windowId })).filter((tab) => isWebUrl(tab.url)).length,
+    idleMsRemaining: Math.max(0, session.idleDeadlineAt - now)
+  })));
+  return { id: cmd.id, ok: true, data };
+}