ghost-bridge 0.4.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 <Author>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,156 +1,159 @@
-# Ghost Bridge
+# 👻 Ghost Bridge
 
-> 无侵入 Chrome AI 副驾 —— 通过 MCP 让 AI 无缝接管你正在使用的浏览器，实时调试、观察页面、操控交互，无需启动新浏览器实例。
+[![npm version](https://img.shields.io/npm/v/ghost-bridge.svg?style=flat-square)](https://www.npmjs.com/package/ghost-bridge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-## ✨ 特性
+> **Zero-restart Chrome AI Copilot** — Subvert your workflow. Allow AI to seamlessly take over the browser you're already using, enabling real-time debugging, visual observation, and interactive manipulation without launching a new Chrome instance.
 
-- 🔌 **零配置附加** — 不依赖 `--remote-debugging-port`，通过 Chrome 扩展直接获取 CDP
-- 🔍 **无 sourcemap 调试** — 片段截取、字符串搜索、覆盖率分析，在压缩代码中定位问题
-- 🌐 **网络请求分析** — 完整记录请求/响应，支持多维度过滤和响应体查看
-- 📸 **页面截图与内容提取** — 视觉分析 + 结构化数据提取
-- 🎯 **DOM 交互操控** — AI 可直接点击按钮、填写表单、按键提交，使用 CDP 物理级模拟，兼容 React/Vue/Angular
-- 📊 **性能诊断** — JS 堆内存、DOM 规模、Layout 开销、Web Vitals、资源加载分析
-- 🔄 **多实例支持** — 自动单例管理，多个 MCP 客户端共享同一 Chrome 连接
+---
 
-## 快速开始
+## ✨ Why Ghost Bridge?
 
-### 1. 安装与初始化
+- 🔌 **Zero-Config Attach** — Bypasses the need for `--remote-debugging-port`. Captures Chrome's native DevTools Protocol directly via an extension.
+- 🔍 **No-Sourcemap Debugging** — Slice code fragments, perform string searches, and analyze coverage to pinpoint bugs straight in minified production code.
+- 🌐 **Deep Network Analysis** — Comprehensive capture of requests/responses with multi-dimensional filtering and response body inspection.
+- 📸 **Visual & Structural Perception** — Full-page or clipped high-fidelity screenshots paired with structural data extraction (titles, links, forms, buttons).
+- 🎯 **DOM Physical Manipulation** — Empowers AI to click, type, and form-submit with CDP-level physical simulation. Fully compatible with complex SPAs (React/Vue/Angular/Svelte).
+- 📊 **Performance Diagnostics** — Get granular engine metrics: JS Heap, Layout recalculations, Web Vitals (TTFB/FCP/LCP), and resource loading speeds.
+- 🔄 **Multi-Client Mastery** — Built-in singleton manager automatically coordinates multiple MCP clients sharing a single Chrome transport.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install & Initialize
 
 ```bash
-# 全局安装
+# Install globally
 npm install -g ghost-bridge
 
-# 自动配置 Claude MCP 并准备扩展
+# Auto-configure MCP (Claude Code, Antigravity, Codex) and prepare the extension directory
 ghost-bridge init
 ```
 
-### 2. 加载 Chrome 扩展
+> **Note on other MCP clients (Cursor, Windsurf, Roo):** 
+> `ghost-bridge init` attempts to auto-configure supported clients. If your client isn't auto-detected, simply add the following to your client's MCP configuration file (e.g., `mcp.json`):
+> ```json
+> {
+>   "mcpServers": {
+>     "ghost-bridge": {
+>       "command": "node",
+>       "args": ["/absolute/path/to/global/node_modules/ghost-bridge/dist/server.js"]
+>     }
+>   }
+> }
+> ```
 
-1. 打开 Chrome，访问 `chrome://extensions`
-2. 开启右上角的 **开发者模式**
-3. 点击 **加载已解压的扩展程序**
-4. 选择目录：`~/.ghost-bridge/extension`
+### 2. Load the Chrome Extension
 
-> 💡 运行 `ghost-bridge extension --open` 可直接打开该目录
+1. Open Chrome and navigate to `chrome://extensions`
+2. Toggle **Developer mode** in the top right corner.
+3. Click **Load unpacked**
+4. Select the directory: `~/.ghost-bridge/extension`
 
-### 3. 连接并使用
+> 💡 *Tip: Run `ghost-bridge extension --open` to reveal the directory directly.*
 
-1. 点击浏览器工具栏中的 Ghost Bridge 图标
-2. 点击 **连接**，等待状态变为 ✅ 已连接
-3. 打开 Claude Desktop 或 Claude CLI，即可使用所有调试工具
+### 3. Connect & Command
 
-## CLI 命令
+1. Click the **Ghost Bridge** ghost icon in your browser toolbar.
+2. Click **Connect** and wait for the status to turn to ✅ **ON**.
+3. Open Claude Desktop or your Claude CLI. All tools are now primed and ready!
 
-| 命令 | 说明 |
-|------|------|
-| `ghost-bridge init` | 配置 MCP 并复制扩展文件 |
-| `ghost-bridge status` | 检查配置状态 |
-| `ghost-bridge extension` | 显示扩展安装路径（`--open` 打开目录） |
-| `ghost-bridge start` | 手动启动 MCP 服务（通常不需要） |
+---
 
-## 工具一览
+## 🛠️ Tool Arsenal
 
-### 🔍 基础调试
+### 🔍 Core Debugging
 
-| 工具 | 说明 |
-|------|------|
-| `get_server_info` | 获取服务器状态（端口、连接状态、角色） |
-| `get_last_error` | 汇总最近的异常 / console 错误 / 网络报错，附行列与脚本标识 |
-| `get_script_source` | 抓取目标脚本源码，支持按 URL 片段筛选、指定行列定位、beautify |
-| `coverage_snapshot` | 启动执行覆盖率采集（默认 1.5s），返回最活跃的脚本列表 |
-| `find_by_string` | 在页面脚本源码中按关键词搜索，返回 200 字符上下文窗口 |
-| `symbolic_hints` | 采集资源列表、全局变量 key、localStorage key、UA 与 URL |
-| `eval_script` | 在页面执行 JS 表达式（谨慎使用） |
+| Tool | Capability |
+|------|------------|
+| `get_server_info` | Retrieves server instance status, WebSocket ports, and client roles. |
+| `get_last_error` | Aggregates recent exceptions, console errors, and failed network requests with mapped locators. |
+| `get_script_source` | Pulls raw script definitions. Supports URL-fragment filtering, specific line targeting, and beautification. |
+| `coverage_snapshot` | Triggers a quick coverage trace (1.5s default) to identify the most active scripts on the page. |
+| `find_by_string` | Scans page script sources for keywords, returning a 200-character context window. |
+| `symbolic_hints` | Gathers context clues: Resource lists, Global Variable keys, LocalStorage schema, and UA strings. |
+| `eval_script` | Executes raw JavaScript expressions in the page context. *(Use with caution)* |
 
-### � 网络请求分析
+### 🌍 Network Intelligence
 
-| 工具 | 说明 |
-|------|------|
-| `list_network_requests` | 列出捕获的网络请求，支持按 URL / 方法 / 状态 / 资源类型过滤 |
-| `get_network_detail` | 获取单个请求的详细信息（请求头、响应头、timing），可选获取响应体 |
-| `clear_network_requests` | 清空已捕获的网络请求记录 |
+| Tool | Capability |
+|------|------------|
+| `list_network_requests` | Lists captured network traffic. Supports filtering by URL, Method, Status Code, or Resource Type. |
+| `get_network_detail` | Dives deep into a specific request's Headers, Timing, and optional Response Body extraction. |
+| `clear_network_requests` | Wipes the current network capture buffer. |
 
-### 📸 页面内容
+### 📸 Page Perception
 
-| 工具 | 说明 |
-|------|------|
-| `capture_screenshot` | 截取页面截图（支持完整长截图、指定区域、JPEG/PNG 格式） |
-| `get_page_content` | 提取页面内容：纯文本 / HTML / 结构化数据（标题、链接、按钮、表单） |
+| Tool | Capability |
+|------|------------|
+| `capture_screenshot` | Captures the viewport or emulates full-page scrolling screenshots. |
+| `get_page_content` | Extracts raw text, sanitized HTML, or structured actionable data representations. |
 
-### 🎯 页面交互（DOM 操作）
+### 🎯 Interactive Automation (DOM)
 
-| 工具 | 说明 |
-|------|------|
-| `get_interactive_snapshot` | 扫描页面所有可见可交互元素，返回带 ref 短标识（e1, e2...）的精简列表，支持 Shadow DOM 穿透 |
-| `dispatch_action` | 对目标元素执行动作（click / fill / press / scroll / select / hover / focus），使用 CDP 物理级模拟 |
+| Tool | Capability |
+|------|------------|
+| `get_interactive_snapshot` | Scans for visible interactive elements, returning a concise map `[e1, e2...]`. Pierces open Shadow DOMs. |
+| `dispatch_action` | Dispatches physical UI actions (click, fill, press, hover) against targeted element references (e.g., `e1`). |
 
-**交互工作流示例：**
+**Example Agent Workflow:**
+1. AI: `get_interactive_snapshot` ➝ `[{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]`
+2. AI: `dispatch_action({ref: "e1", action: "fill", value: "hello"})`
+3. AI: `dispatch_action({ref: "e2", action: "click"})`
+4. AI: `capture_screenshot` to verify state changes.
 
-```
-1. AI 调用 get_interactive_snapshot
-   → 返回: [{ref:"e1", tag:"input", placeholder:"Search..."}, {ref:"e2", tag:"button", text:"Login"}]
+### 📊 Performance Profiling
 
-2. AI 调用 dispatch_action({ref: "e1", action: "fill", value: "hello"})
-   → 在搜索框中输入 "hello"
+| Tool | Capability |
+|------|------------|
+| `perf_metrics` | Collects layered performance data (Engine Metrics, Web Vitals, and Resource Load Summaries). |
 
-3. AI 调用 dispatch_action({ref: "e2", action: "click"})
-   → 点击 Login 按钮
+---
 
-4. AI 调用 capture_screenshot 验证操作结果
-```
+## ⚙️ Configuration
 
-### 📊 性能分析
+| Setting | Default | Description |
+|---------|---------|-------------|
+| **Base Port** | `33333` | WS port. Auto-increments if occupied. |
+| **Token** | *Monthly UUID* | Local WS auth token, auto-rotates on the 1st of every month. |
+| **Auto Detach** | `false` | Keeps debugger attached to actively buffer invisible exceptions and network calls. |
 
-| 工具 | 说明 |
-|------|------|
-| `perf_metrics` | 获取页面性能指标，包含三层数据：|
+**Environment Variables:**
+- `GHOST_BRIDGE_PORT` — Override base port.
+- `GHOST_BRIDGE_TOKEN` — Override connection token.
 
-**`perf_metrics` 返回的数据：**
+---
 
-- **引擎级指标** — JS 堆内存（使用量/总量/占比）、DOM 节点数、事件监听器数、Layout 重排次数与耗时、脚本执行时间
-- **Web Vitals** — Navigation Timing 各阶段（DNS / TTFB / DOM Interactive / Load）、FP、FCP、Long Tasks 统计
-- **资源加载摘要** — 按类型分组统计（count / size / avgDuration）、最慢资源识别
+## 🏗️ Architecture
 
-## 配置
-
-| 项目 | 默认值 | 说明 |
-|------|--------|------|
-| 端口 | `33333` | WebSocket 服务端口，自动递增寻找可用端口 |
-| Token | 当月自动生成 | 本机 WS 校验，基于当月 1 号时间戳 |
-| 自动 Detach | `false` | 保持附加，便于持续捕获异常和网络请求 |
+```mermaid
+graph LR
+    A[Claude CLI/Desktop] <-->|stdio| B(MCP Server\nserver.js)
+    B <-->|WebSocket| C(Chrome Extension\nbackground.js)
+    C <-->|CDP| D[Browser Tab\nTarget Context]
+```
 
-环境变量：
+- **MCP Server**: Spawned by Claude via standard I/O streams. Orchestrates WS connections.
+- **Chrome Extension (MV3)**: Taps into `chrome.debugger` API. Utilizes an Offscreen Document to prevent WS hibernation.
+- **Singleton Design**: If multiple agents spawn servers, the first becomes the master bridge while subsequent instances chain transparently as clients.
 
-- `GHOST_BRIDGE_PORT` — 自定义基础端口
-- `GHOST_BRIDGE_TOKEN` — 自定义 token
+---
 
-## 架构
+## ⚠️ Known Limitations
 
-```
-┌──────────────┐     stdio      ┌──────────────┐    WebSocket    ┌──────────────┐
-│  Claude CLI  │ ◄────────────► │  MCP Server  │ ◄──────────────►│Chrome Extension│
-│  / Desktop   │                │ (server.js)  │                 │(background.js)│
-└──────────────┘                └──────────────┘                 └──────┬───────┘
-                                                                       │ CDP
-                                                                 ┌─────▼──────┐
-                                                                 │  浏览器页面  │
-                                                                 └────────────┘
-```
+- **Service Workers Suspending**: MV3 background workers may suspend. We've built robust auto-reconnection logic, but prolonged inactivity might require re-toggling.
+- **DevTools Conflict**: If you manually open Chrome DevTools (F12) on the target tab, `chrome.debugger.attach` may be rejected.
+- **Beautify Overhead**: Beautifying massive single-line bundles is expensive; the server will auto-truncate overly large scripts.
+- **Cross-Origin OOPIF**: Elements and errors deeply embedded in strict Cross-Origin Iframes might evade the primary debugger hook without further multi-target attach logic.
 
-- **MCP Server** — 通过 stdio 被 Claude 拉起，与扩展通过 WebSocket 通信
-- **Chrome Extension (MV3)** — 使用 `chrome.debugger` API 附加页面，Offscreen Document 维持 WebSocket 长连接
-- **单例模式** — 多个 MCP 客户端自动协调，首个实例为主服务，后续实例作为客户端连接
+---
 
-## 已知限制
+## 🤝 Contributing
 
-- 扩展 Service Worker 可能被挂起，已内置重连策略；若长时间无流量需重新唤醒
-- 若目标页面已打开 DevTools，`chrome.debugger.attach` 可能失败，请关闭后重试
-- 大体积单行 bundle beautify 可能耗时，服务端对超长源码会截取片段
-- 跨月时 token 会自动更新，扩展和服务端需在同月内启动
-- DOM 交互：SPA 路由变化后 ref 标识会失效，需重新调用 `get_interactive_snapshot`
-- DOM 交互：跨域 iframe 内的元素暂不支持细粒度操作
-- DOM 交互：Shadow DOM 内的元素可以被扫描到，但部分封闭模式的 Shadow Root 可能无法穿透
+Contributions, issues, and feature requests are welcome! 
+Check out our [Contributing Guide](CONTRIBUTING.md) to get started building tools or improving the bridge.
 
-## License
+## 📄 License
 
-MIT
+This project is [MIT](LICENSE) licensed.

package/dist/cli.js

@@ -5454,9 +5454,15 @@ var require_lib = __commonJS({
 import path from "path";
 import os2 from "os";
 import { fileURLToPath } from "url";
-function getClaudeConfigPath() {
+function getClientConfigPaths() {
   const homeDir = os2.homedir();
-  return path.join(homeDir, ".claude.json");
+  return [
+    { name: "Claude Code", path: path.join(homeDir, ".claude.json") },
+    { name: "Antigravity", path: path.join(homeDir, ".gemini", "antigravity", "mcp.json") },
+    // Codex config placeholder - exact path depends on how Codex stores user config.
+    // Assuming a common pattern here like ~/.codex/mcp.json or similar.
+    { name: "Codex", path: path.join(homeDir, ".codex", "mcp.json") }
+  ];
 }
 function getExtensionPath() {
   const __filename2 = fileURLToPath(import.meta.url);
@@ -5502,20 +5508,28 @@ function openFolder(folderPath) {
 }
 async function init(options) {
   console.log(source_default.bold("\u{1F47B} Ghost Bridge Initialization"));
-  const configPath = getClaudeConfigPath();
+  const clientConfigs = getClientConfigPaths();
   const serverPath = getServerPath();
   const isDryRun = options.dryRun;
-  console.log(source_default.dim("Checking Claude configuration..."));
-  if (isDryRun) {
-    console.log(source_default.yellow(`[Dry Run] Would check config at: ${configPath}`));
-    console.log(source_default.yellow(`[Dry Run] Would add MCP server pointing to: ${serverPath}`));
-  } else {
-    if (!import_fs_extra.default.existsSync(configPath)) {
-      console.log(source_default.yellow(`Configuration file not found at ${configPath}, creating/skipping...`));
+  console.log(source_default.dim("Checking MCP Client configurations..."));
+  let configuredCount = 0;
+  for (const client of clientConfigs) {
+    const configPath = client.path;
+    if (isDryRun) {
+      console.log(source_default.yellow(`[Dry Run] Would check ${client.name} config at: ${configPath}`));
+      if (import_fs_extra.default.existsSync(configPath) || client.name === "Claude Code") {
+        console.log(source_default.yellow(`[Dry Run] Would add MCP server logic for ${client.name}`));
+      }
+      continue;
+    }
+    const exists = import_fs_extra.default.existsSync(configPath);
+    if (!exists && client.name !== "Claude Code") {
+      continue;
+    }
+    if (!exists) {
+      console.log(source_default.yellow(`Configuration file not found for ${client.name} at ${configPath}, creating...`));
       await import_fs_extra.default.ensureDir(path2.dirname(configPath));
-      if (!import_fs_extra.default.existsSync(configPath)) {
-        await import_fs_extra.default.writeJson(configPath, { mcpServers: {} }, { spaces: 2 });
-      }
+      await import_fs_extra.default.writeJson(configPath, { mcpServers: {} }, { spaces: 2 });
     }
     try {
       const config = await import_fs_extra.default.readJson(configPath);
@@ -5525,11 +5539,15 @@ async function init(options) {
         args: [serverPath]
       };
       await import_fs_extra.default.writeJson(configPath, config, { spaces: 2 });
-      console.log(source_default.green(`\u2705 MCP Server 'ghost-bridge' configured in ${configPath}`));
+      console.log(source_default.green(`\u2705 MCP Server configured for ${source_default.bold(client.name)} in ${configPath}`));
+      configuredCount++;
     } catch (err) {
-      console.error(source_default.red(`Failed to update config: ${err.message}`));
+      console.error(source_default.red(`Failed to update config for ${client.name}: ${err.message}`));
     }
   }
+  if (configuredCount === 0 && !isDryRun) {
+    console.log(source_default.yellow("\u26A0\uFE0F No supported MCP clients found to configure automatically."));
+  }
   const sourceExt = getExtensionPath();
   const targetExt = getUserExtensionDir();
   console.log(source_default.dim(`Setting up extension in ${targetExt}...`));
@@ -5617,34 +5635,47 @@ __export(status_exports, {
 });
 async function status() {
   console.log(source_default.bold("\u{1F47B} Ghost Bridge Status"));
-  const configPath = getClaudeConfigPath();
+  const clientConfigs = getClientConfigPaths();
   const extDir = getUserExtensionDir();
   const serverPath = getServerPath();
-  let mcpStatus = source_default.red("Not Configured");
-  let mcpDetails = "";
-  if (import_fs_extra3.default.existsSync(configPath)) {
-    try {
-      const config = await import_fs_extra3.default.readJson(configPath);
-      if (config.mcpServers && config.mcpServers["ghost-bridge"]) {
-        mcpStatus = source_default.green("Configured");
-        const cfg = config.mcpServers["ghost-bridge"];
-        const configuredPath = cfg.args[0];
-        if (configuredPath === serverPath) {
-          mcpDetails = source_default.dim("(Paths match)");
-        } else {
-          mcpDetails = source_default.yellow(`(Path mismatch)
-  Configured: ${configuredPath}
-  Current:    ${serverPath}`);
+  console.log(source_default.bold.blue("\nMCP Client Configurations:"));
+  let configuredCount = 0;
+  for (const client of clientConfigs) {
+    let mcpStatus = source_default.gray("Not Configured");
+    let mcpDetails = "";
+    const configPath = client.path;
+    if (import_fs_extra3.default.existsSync(configPath)) {
+      try {
+        const config = await import_fs_extra3.default.readJson(configPath);
+        if (config.mcpServers && config.mcpServers["ghost-bridge"]) {
+          mcpStatus = source_default.green("Configured");
+          const cfg = config.mcpServers["ghost-bridge"];
+          const configuredPath = cfg.args[0];
+          if (configuredPath === serverPath) {
+            mcpDetails = source_default.dim("(Paths match)");
+          } else {
+            mcpDetails = source_default.yellow(`(Path mismatch) 
+      Configured: ${configuredPath}
+      Current:    ${serverPath}`);
+          }
+          configuredCount++;
         }
+      } catch (e) {
+        mcpStatus = source_default.red("Error reading config");
+      }
+    } else {
+      if (client.name === "Claude Code") {
+        mcpStatus = source_default.yellow("Config file not found");
+      } else {
+        mcpStatus = source_default.gray("Not Installed");
       }
-    } catch (e) {
-      mcpStatus = source_default.red("Error reading config");
     }
-  } else {
-    mcpStatus = source_default.yellow("Config file not found");
+    console.log(`  ${source_default.bold(client.name)}: ${mcpStatus} ${mcpDetails}`);
+    console.log(`    Config File: ${source_default.dim(configPath)}`);
+  }
+  if (configuredCount === 0) {
+    console.log(source_default.yellow("\n  No MCP clients currently have ghost-bridge configured. Run `ghost-bridge init`."));
   }
-  console.log(`MCP Configuration: ${mcpStatus} ${mcpDetails}`);
-  console.log(`  Config File: ${configPath}`);
   let extStatus = source_default.red("Not Installed (Run init)");
   if (import_fs_extra3.default.existsSync(extDir)) {
     extStatus = source_default.green("Installed");