@jackwener/opencli 1.3.3 → 1.4.1

package/docs/developer/ts-adapter.md

@@ -6,6 +6,7 @@ Use TypeScript adapters when you need browser-side logic, multi-step flows, DOM
 
 ```typescript
 import { cli, Strategy } from '../../registry.js';
+import { CommandExecutionError, EmptyResultError } from '../../errors.js';
 
 cli({
   site: 'mysite',
@@ -34,6 +35,9 @@ cli({
       })()
     `);
 
+    if (!Array.isArray(data)) throw new CommandExecutionError('MySite returned an unexpected response');
+    if (!data.length) throw new EmptyResultError('mysite search', 'Try a different keyword');
+
     return data.slice(0, Number(limit)).map((item: any) => ({
       title: item.title,
       url: item.url,
@@ -69,6 +73,20 @@ Contains parsed CLI arguments as key-value pairs. Always destructure with defaul
 const { query, limit = 10, format = 'json' } = kwargs;
 ```
 
+For most search/read/detail commands, the main subject should be positional (`opencli mysite search "rust"`, `opencli mysite article 123`) instead of a named flag such as `--query` or `--id`. Keep named flags for optional modifiers.
+
+## Error Handling
+
+Prefer throwing `CliError` subclasses from `src/errors.ts` for expected adapter failures:
+
+- `AuthRequiredError` for missing login / cookies
+- `EmptyResultError` for empty but valid responses
+- `CommandExecutionError` for unexpected API or browser failures
+- `TimeoutError` for site timeouts
+- `ArgumentError` for invalid user input
+
+Avoid raw `Error` for normal adapter control flow. This keeps top-level CLI output consistent and preserves hints for users.
+
 ## AI-Assisted Development
 
 Use the AI workflow tools to accelerate adapter creation:

package/docs/developer/yaml-adapter.md

@@ -2,6 +2,8 @@
 
 YAML adapters are the recommended way to add new commands when the site offers a straightforward API. They use a declarative pipeline approach — no TypeScript required.
 
+Use YAML only when the command stays mostly declarative. If you find yourself embedding long JavaScript expressions, many fallbacks, or multi-step browser logic, move the command to a TypeScript adapter instead of growing an opaque template blob.
+
 ## Basic Structure
 
 ::: v-pre
@@ -33,6 +35,14 @@ columns: [rank, title, score, url]
 ```
 :::
 
+For most commands, keep the primary subject positional. Good examples:
+
+- `opencli mysite search "rust"`
+- `opencli mysite topic 123`
+- `opencli mysite download "https://example.com/post/1"`
+
+Prefer named flags only for optional modifiers such as `--limit`, `--sort`, `--lang`, or `--output`.
+
 ## Pipeline Steps
 
 ### `fetch`
@@ -106,3 +116,9 @@ Use `${{ ... }}` for dynamic values:
 ## Real Example
 
 See [`src/clis/hackernews/top.yaml`](https://github.com/jackwener/opencli/blob/main/src/clis/hackernews/top.yaml).
+
+## Guardrails
+
+- Add fallbacks for optional fields in `map` expressions when upstream payloads may be sparse.
+- Keep template expressions short and readable. If the expression starts looking like a mini program, switch to TypeScript.
+- If you add a new adapter, also add the matching doc page plus index/sidebar entries so `doc-coverage` stays green.

package/docs/guide/plugins.md

@@ -11,6 +11,12 @@ opencli plugin install github:ByteYue/opencli-plugin-github-trending
 # List installed plugins
 opencli plugin list
 
+# Update one plugin
+opencli plugin update github-trending
+
+# Update all installed plugins
+opencli plugin update --all
+
 # Use the plugin (it's just a regular command)
 opencli github-trending repos --limit 10
 
@@ -31,6 +37,10 @@ opencli plugin install https://github.com/user/repo
 
 The repo name prefix `opencli-plugin-` is automatically stripped for the local directory name. For example, `opencli-plugin-hot-digest` becomes `hot-digest`.
 
+## Version Tracking
+
+OpenCLI records installed plugin versions in `~/.opencli/plugins.lock.json`. Each entry stores the plugin source, current git commit hash, install time, and last update time. `opencli plugin list` shows the short commit hash when version metadata is available.
+
 ## Creating a Plugin
 
 ### Option 1: YAML Plugin (Simplest)

package/docs/zh/guide/plugins.md

@@ -11,6 +11,12 @@ opencli plugin install github:ByteYue/opencli-plugin-github-trending
 # 列出已安装插件
 opencli plugin list
 
+# 更新单个插件
+opencli plugin update github-trending
+
+# 更新全部已安装插件
+opencli plugin update --all
+
 # 使用插件（本质上就是普通 command）
 opencli github-trending today
 
@@ -31,6 +37,10 @@ opencli plugin install https://github.com/user/repo
 
 如果仓库名带 `opencli-plugin-` 前缀，本地目录会自动去掉这个前缀。例如 `opencli-plugin-hot-digest` 会变成 `hot-digest`。
 
+## 版本追踪
+
+OpenCLI 会把已安装 plugin 的版本记录到 `~/.opencli/plugins.lock.json`。每条记录会保存 plugin source、当前 git commit hash、安装时间，以及最近一次更新时间。只要有这份元数据，`opencli plugin list` 就会显示对应的短 commit hash。
+
 ## YAML plugin 示例
 
 ```text

package/extension/dist/background.js

@@ -5,9 +5,10 @@ const WS_RECONNECT_BASE_DELAY = 2e3;
 const WS_RECONNECT_MAX_DELAY = 6e4;
 
 const attached = /* @__PURE__ */ new Set();
+const BLANK_PAGE$1 = "data:text/html,<html></html>";
 function isDebuggableUrl$1(url) {
   if (!url) return true;
-  return !url.startsWith("chrome://") && !url.startsWith("chrome-extension://");
+  return url.startsWith("http://") || url.startsWith("https://") || url === BLANK_PAGE$1;
 }
 async function ensureAttached(tabId) {
   try {
@@ -100,11 +101,11 @@ async function screenshot(tabId, options = {}) {
     }
   }
 }
-function detach(tabId) {
+async function detach(tabId) {
   if (!attached.has(tabId)) return;
   attached.delete(tabId);
   try {
-    chrome.debugger.detach({ tabId });
+    await chrome.debugger.detach({ tabId });
   } catch {
   }
 }
@@ -115,15 +116,9 @@ function registerListeners() {
   chrome.debugger.onDetach.addListener((source) => {
     if (source.tabId) attached.delete(source.tabId);
   });
-  chrome.tabs.onUpdated.addListener((tabId, info) => {
+  chrome.tabs.onUpdated.addListener(async (tabId, info) => {
     if (info.url && !isDebuggableUrl$1(info.url)) {
-      if (attached.has(tabId)) {
-        attached.delete(tabId);
-        try {
-          chrome.debugger.detach({ tabId });
-        } catch {
-        }
-      }
+      await detach(tabId);
     }
   });
 }
@@ -188,9 +183,11 @@ function connect() {
     ws?.close();
   };
 }
+const MAX_EAGER_ATTEMPTS = 6;
 function scheduleReconnect() {
   if (reconnectTimer) return;
   reconnectAttempts++;
+  if (reconnectAttempts > MAX_EAGER_ATTEMPTS) return;
   const delay = Math.min(WS_RECONNECT_BASE_DELAY * Math.pow(2, reconnectAttempts - 1), WS_RECONNECT_MAX_DELAY);
   reconnectTimer = setTimeout(() => {
     reconnectTimer = null;
@@ -229,7 +226,7 @@ async function getAutomationWindow(workspace) {
     }
   }
   const win = await chrome.windows.create({
-    url: "data:text/html,<html></html>",
+    url: BLANK_PAGE,
     focused: false,
     width: 1280,
     height: 900,
@@ -273,6 +270,15 @@ chrome.runtime.onStartup.addListener(() => {
 chrome.alarms.onAlarm.addListener((alarm) => {
   if (alarm.name === "keepalive") connect();
 });
+chrome.runtime.onMessage.addListener((msg, _sender, sendResponse) => {
+  if (msg?.type === "getStatus") {
+    sendResponse({
+      connected: ws?.readyState === WebSocket.OPEN,
+      reconnecting: reconnectTimer !== null
+    });
+  }
+  return false;
+});
 async function handleCommand(cmd) {
   const workspace = getWorkspaceKey(cmd.workspace);
   resetWindowIdleTimer(workspace);
@@ -303,16 +309,41 @@ async function handleCommand(cmd) {
     };
   }
 }
+const BLANK_PAGE = "data:text/html,<html></html>";
 function isDebuggableUrl(url) {
   if (!url) return true;
-  return !url.startsWith("chrome://") && !url.startsWith("chrome-extension://");
+  return url.startsWith("http://") || url.startsWith("https://") || url === BLANK_PAGE;
+}
+function isSafeNavigationUrl(url) {
+  return url.startsWith("http://") || url.startsWith("https://");
+}
+function normalizeUrlForComparison(url) {
+  if (!url) return "";
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol === "https:" && parsed.port === "443" || parsed.protocol === "http:" && parsed.port === "80") {
+      parsed.port = "";
+    }
+    const pathname = parsed.pathname === "/" ? "" : parsed.pathname;
+    return `${parsed.protocol}//${parsed.host}${pathname}${parsed.search}${parsed.hash}`;
+  } catch {
+    return url;
+  }
+}
+function isTargetUrl(currentUrl, targetUrl) {
+  return normalizeUrlForComparison(currentUrl) === normalizeUrlForComparison(targetUrl);
 }
 async function resolveTabId(tabId, workspace) {
   if (tabId !== void 0) {
     try {
       const tab = await chrome.tabs.get(tabId);
-      if (isDebuggableUrl(tab.url)) return tabId;
-      console.warn(`[opencli] Tab ${tabId} URL is not debuggable (${tab.url}), re-resolving`);
+      const session = automationSessions.get(workspace);
+      if (isDebuggableUrl(tab.url) && session && tab.windowId === session.windowId) return tabId;
+      if (session && tab.windowId !== session.windowId) {
+        console.warn(`[opencli] Tab ${tabId} belongs to window ${tab.windowId}, not automation window ${session.windowId}, re-resolving`);
+      } else if (!isDebuggableUrl(tab.url)) {
+        console.warn(`[opencli] Tab ${tabId} URL is not debuggable (${tab.url}), re-resolving`);
+      }
     } catch {
       console.warn(`[opencli] Tab ${tabId} no longer exists, re-resolving`);
     }
@@ -323,7 +354,7 @@ async function resolveTabId(tabId, workspace) {
   if (debuggableTab?.id) return debuggableTab.id;
   const reuseTab = tabs.find((t) => t.id);
   if (reuseTab?.id) {
-    await chrome.tabs.update(reuseTab.id, { url: "data:text/html,<html></html>" });
+    await chrome.tabs.update(reuseTab.id, { url: BLANK_PAGE });
     await new Promise((resolve) => setTimeout(resolve, 300));
     try {
       const updated = await chrome.tabs.get(reuseTab.id);
@@ -332,7 +363,7 @@ async function resolveTabId(tabId, workspace) {
     } catch {
     }
   }
-  const newTab = await chrome.tabs.create({ windowId, url: "data:text/html,<html></html>", active: true });
+  const newTab = await chrome.tabs.create({ windowId, url: BLANK_PAGE, active: true });
   if (!newTab.id) throw new Error("Failed to create tab in automation window");
   return newTab.id;
 }
@@ -362,40 +393,58 @@ async function handleExec(cmd, workspace) {
 }
 async function handleNavigate(cmd, workspace) {
   if (!cmd.url) return { id: cmd.id, ok: false, error: "Missing url" };
+  if (!isSafeNavigationUrl(cmd.url)) {
+    return { id: cmd.id, ok: false, error: "Blocked URL scheme -- only http:// and https:// are allowed" };
+  }
   const tabId = await resolveTabId(cmd.tabId, workspace);
   const beforeTab = await chrome.tabs.get(tabId);
-  const beforeUrl = beforeTab.url ?? "";
+  const beforeNormalized = normalizeUrlForComparison(beforeTab.url);
   const targetUrl = cmd.url;
+  if (beforeTab.status === "complete" && isTargetUrl(beforeTab.url, targetUrl)) {
+    return {
+      id: cmd.id,
+      ok: true,
+      data: { title: beforeTab.title, url: beforeTab.url, tabId, timedOut: false }
+    };
+  }
+  await detach(tabId);
   await chrome.tabs.update(tabId, { url: targetUrl });
   let timedOut = false;
   await new Promise((resolve) => {
-    let urlChanged = false;
+    let settled = false;
+    let checkTimer = null;
+    let timeoutTimer = null;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      chrome.tabs.onUpdated.removeListener(listener);
+      if (checkTimer) clearTimeout(checkTimer);
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      resolve();
+    };
+    const isNavigationDone = (url) => {
+      return isTargetUrl(url, targetUrl) || normalizeUrlForComparison(url) !== beforeNormalized;
+    };
     const listener = (id, info, tab2) => {
       if (id !== tabId) return;
-      if (info.url && info.url !== beforeUrl) {
-        urlChanged = true;
-      }
-      if (urlChanged && info.status === "complete") {
-        chrome.tabs.onUpdated.removeListener(listener);
-        resolve();
+      if (info.status === "complete" && isNavigationDone(tab2.url ?? info.url)) {
+        finish();
       }
     };
     chrome.tabs.onUpdated.addListener(listener);
-    setTimeout(async () => {
+    checkTimer = setTimeout(async () => {
       try {
         const currentTab = await chrome.tabs.get(tabId);
-        if (currentTab.url !== beforeUrl && currentTab.status === "complete") {
-          chrome.tabs.onUpdated.removeListener(listener);
-          resolve();
+        if (currentTab.status === "complete" && isNavigationDone(currentTab.url)) {
+          finish();
         }
       } catch {
       }
     }, 100);
-    setTimeout(() => {
-      chrome.tabs.onUpdated.removeListener(listener);
+    timeoutTimer = setTimeout(() => {
       timedOut = true;
       console.warn(`[opencli] Navigate to ${targetUrl} timed out after 15s`);
-      resolve();
+      finish();
     }, 15e3);
   });
   const tab = await chrome.tabs.get(tabId);
@@ -419,8 +468,11 @@ async function handleTabs(cmd, workspace) {
       return { id: cmd.id, ok: true, data };
     }
     case "new": {
+      if (cmd.url && !isSafeNavigationUrl(cmd.url)) {
+        return { id: cmd.id, ok: false, error: "Blocked URL scheme -- only http:// and https:// are allowed" };
+      }
       const windowId = await getAutomationWindow(workspace);
-      const tab = await chrome.tabs.create({ windowId, url: cmd.url ?? "data:text/html,<html></html>", active: true });
+      const tab = await chrome.tabs.create({ windowId, url: cmd.url ?? BLANK_PAGE, active: true });
       return { id: cmd.id, ok: true, data: { tabId: tab.id, url: tab.url } };
     }
     case "close": {
@@ -429,18 +481,28 @@ async function handleTabs(cmd, 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);
+        await detach(target.id);
         return { id: cmd.id, ok: true, data: { closed: target.id } };
       }
       const tabId = await resolveTabId(cmd.tabId, workspace);
       await chrome.tabs.remove(tabId);
-      detach(tabId);
+      await detach(tabId);
       return { id: cmd.id, ok: true, data: { closed: tabId } };
     }
     case "select": {
       if (cmd.index === void 0 && cmd.tabId === void 0)
         return { id: cmd.id, ok: false, error: "Missing index or tabId" };
       if (cmd.tabId !== void 0) {
+        const session = automationSessions.get(workspace);
+        let tab;
+        try {
+          tab = await chrome.tabs.get(cmd.tabId);
+        } catch {
+          return { id: cmd.id, ok: false, error: `Tab ${cmd.tabId} no longer exists` };
+        }
+        if (!session || tab.windowId !== session.windowId) {
+          return { id: cmd.id, ok: false, error: `Tab ${cmd.tabId} is not in the automation window` };
+        }
         await chrome.tabs.update(cmd.tabId, { active: true });
         return { id: cmd.id, ok: true, data: { selected: cmd.tabId } };
       }
@@ -455,6 +517,9 @@ async function handleTabs(cmd, workspace) {
   }
 }
 async function handleCookies(cmd) {
+  if (!cmd.domain && !cmd.url) {
+    return { id: cmd.id, ok: false, error: "Cookie scope required: provide domain or url to avoid dumping all cookies" };
+  }
   const details = {};
   if (cmd.domain) details.domain = cmd.domain;
   if (cmd.url) details.url = cmd.url;

package/extension/manifest.json

@@ -1,8 +1,8 @@
 {
   "manifest_version": 3,
   "name": "OpenCLI",
-  "version": "1.2.6",
-  "description": "Bridge between opencli CLI and your browser — execute commands, read cookies, manage tabs.",
+  "version": "1.4.1",
+  "description": "Browser automation bridge for the OpenCLI CLI tool. Executes commands in isolated Chrome windows via a local daemon.",
   "permissions": [
     "debugger",
     "tabs",
@@ -22,10 +22,14 @@
   },
   "action": {
     "default_title": "OpenCLI",
+    "default_popup": "popup.html",
     "default_icon": {
       "16": "icons/icon-16.png",
       "32": "icons/icon-32.png"
     }
   },
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'self'"
+  },
   "homepage_url": "https://github.com/jackwener/opencli"
 }

package/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencli-extension",
-  "version": "1.2.6",
+  "version": "1.4.1",
   "private": true,
   "type": "module",
   "scripts": {

package/extension/popup.html

@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      width: 280px;
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      font-size: 13px;
+      color: #333;
+      background: #fff;
+      padding: 16px;
+    }
+    .header {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      margin-bottom: 14px;
+    }
+    .header img { width: 24px; height: 24px; }
+    .header h1 { font-size: 15px; font-weight: 600; }
+    .status-row {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 10px 12px;
+      border-radius: 8px;
+      background: #f5f5f5;
+    }
+    .dot {
+      width: 8px; height: 8px;
+      border-radius: 50%;
+      flex-shrink: 0;
+    }
+    .dot.connected { background: #34c759; }
+    .dot.disconnected { background: #ff3b30; }
+    .dot.connecting { background: #ff9500; }
+    .status-text { font-size: 13px; color: #555; }
+    .status-text strong { color: #333; }
+    .hint {
+      margin-top: 10px;
+      padding: 8px 10px;
+      border-radius: 6px;
+      background: #f0f4ff;
+      font-size: 11px;
+      color: #666;
+      line-height: 1.5;
+      display: none;
+    }
+    .hint code {
+      background: #e8ecf1;
+      padding: 1px 4px;
+      border-radius: 3px;
+      font-size: 11px;
+    }
+    .footer {
+      margin-top: 14px;
+      text-align: center;
+      font-size: 11px;
+      color: #999;
+    }
+    .footer a { color: #007aff; text-decoration: none; }
+    .footer a:hover { text-decoration: underline; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <img src="icons/icon-48.png" alt="OpenCLI">
+    <h1>OpenCLI</h1>
+  </div>
+  <div class="status-row">
+    <span class="dot disconnected" id="dot"></span>
+    <span class="status-text" id="status">Checking...</span>
+  </div>
+  <div class="hint" id="hint">
+    This is normal. The extension connects automatically when you run any <code>opencli</code> command.
+  </div>
+  <div class="footer">
+    <a href="https://github.com/jackwener/opencli" target="_blank">Documentation</a>
+  </div>
+  <script src="popup.js"></script>
+</body>
+</html>

package/extension/popup.js

@@ -0,0 +1,25 @@
+// Query connection status from background service worker
+chrome.runtime.sendMessage({ type: 'getStatus' }, (resp) => {
+  const dot = document.getElementById('dot');
+  const status = document.getElementById('status');
+  const hint = document.getElementById('hint');
+  if (chrome.runtime.lastError || !resp) {
+    dot.className = 'dot disconnected';
+    status.innerHTML = '<strong>No daemon connected</strong>';
+    hint.style.display = 'block';
+    return;
+  }
+  if (resp.connected) {
+    dot.className = 'dot connected';
+    status.innerHTML = '<strong>Connected to daemon</strong>';
+    hint.style.display = 'none';
+  } else if (resp.reconnecting) {
+    dot.className = 'dot connecting';
+    status.innerHTML = '<strong>Reconnecting...</strong>';
+    hint.style.display = 'none';
+  } else {
+    dot.className = 'dot disconnected';
+    status.innerHTML = '<strong>No daemon connected</strong>';
+    hint.style.display = 'block';
+  }
+});

package/extension/src/background.test.ts

@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 type Listener<T extends (...args: any[]) => void> = { addListener: (fn: T) => void };
 
@@ -96,9 +96,15 @@ function createChromeMock() {
 describe('background tab isolation', () => {
   beforeEach(() => {
     vi.resetModules();
+    vi.useRealTimers();
     vi.stubGlobal('WebSocket', MockWebSocket);
   });
 
+  afterEach(() => {
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
   it('lists only automation-window web tabs', async () => {
     const { chrome } = createChromeMock();
     vi.stubGlobal('chrome', chrome);
@@ -133,6 +139,45 @@ describe('background tab isolation', () => {
     expect(create).toHaveBeenCalledWith({ windowId: 1, url: 'https://new.example', active: true });
   });
 
+  it('treats normalized same-url navigate as already complete', async () => {
+    const { chrome, tabs, update } = createChromeMock();
+    tabs[0].url = 'https://www.bilibili.com/';
+    tabs[0].title = 'bilibili';
+    tabs[0].status = 'complete';
+    vi.stubGlobal('chrome', chrome);
+
+    const mod = await import('./background');
+    mod.__test__.setAutomationWindowId('site:bilibili', 1);
+
+    const result = await mod.__test__.handleNavigate(
+      { id: 'same-url', action: 'navigate', url: 'https://www.bilibili.com', workspace: 'site:bilibili' },
+      'site:bilibili',
+    );
+
+    expect(result).toEqual({
+      id: 'same-url',
+      ok: true,
+      data: {
+        title: 'bilibili',
+        url: 'https://www.bilibili.com/',
+        tabId: 1,
+        timedOut: false,
+      },
+    });
+    expect(update).not.toHaveBeenCalled();
+  });
+
+  it('keeps hash routes distinct when comparing target URLs', async () => {
+    const { chrome } = createChromeMock();
+    vi.stubGlobal('chrome', chrome);
+
+    const mod = await import('./background');
+
+    expect(mod.__test__.isTargetUrl('https://example.com/', 'https://example.com')).toBe(true);
+    expect(mod.__test__.isTargetUrl('https://example.com/#feed', 'https://example.com/#settings')).toBe(false);
+    expect(mod.__test__.isTargetUrl('https://example.com/app/', 'https://example.com/app')).toBe(false);
+  });
+
   it('reports sessions per workspace', async () => {
     const { chrome } = createChromeMock();
     vi.stubGlobal('chrome', chrome);