pi-to-chrome 0.1.2

package/README.md

@@ -0,0 +1,50 @@
+# pi-to-chrome
+
+## Why?
+
+I've used Claude and OpenCode for frontend development for a long time. Their MCP integrations for Chrome — built on Playwright and the like — feel like starships: massive, feature-bloated, 90% of which I never use. And they burn through tokens like there's no tomorrow.
+
+It frustrated me.
+
+Suddenly I found Pi. Its simplicity, elegance, restraint — so refreshing. Just 4 essential tools. That's it. That's all you need.
+
+Inspired and led by Pi's philosophy, I built **pi-to-chrome** for myself. The exact 4 tools I actually use. No more, no less.
+
+The world went quiet, quickly, and clean.
+
+---
+
+## Only 4 tools
+
+1. **find_elements** — Searching a jungle of hundreds of components and DOM nodes for the "Select Date" button? Use this to search the whole page and returns the element's id, className, and the full DOM hierarchy.
+2. **inspect_styles** — When a CSS rule sneaks in from nowhere and ruins your layout, use this to dump every style definition — inherited, computed, cascading — for the LLM to untangle.
+3. **read_console** — Chrome's console log is too tiny to read. Hundreds of entries and you still can't find what you want. Use this to stream all logs to the LLM for analysis.
+4. **execute_js** — Throw any JavaScript at Chrome. Execute it, get results back, debug on the fly.
+
+## Only 2 commands
+
+- `/chrome-start` — launch a Chrome instance (or connect to one already running), enable this toolbox
+- `/chrome-stop` — closes the browser, and disable this toolbox
+
+
+---
+
+## Install
+
+```bash
+pi install npm:pi-to-chrome
+```
+
+---
+
+
+## Requirements
+
+- [Pi](https://pi.dev) — you already have it
+- Chrome browser with DevTools protocol enabled
+
+---
+
+### Sollawen
+
+email: sollawen@163.com

package/console-buffer.ts

@@ -0,0 +1,121 @@
+/**
+ * ConsoleBuffer - Ring buffer for Chrome console messages
+ *
+ * Listens to CDP console events via puppeteer's page.on('console') API.
+ * Captures log/warn/error/info from ALL tabs automatically.
+ */
+
+import type { Browser, Page, ConsoleMessage } from 'puppeteer-core';
+
+export type ConsoleLevel = 'log' | 'warn' | 'error' | 'info';
+
+export interface BufferedConsoleMessage {
+  type: ConsoleLevel;
+  text: string;
+  url: string;
+  timestamp: number;
+}
+
+const MAX_BUFFER_SIZE = 1000;
+
+export class ConsoleBuffer {
+  private buffer: BufferedConsoleMessage[] = [];
+  private listeners: Array<{ page: Page; handler: (msg: ConsoleMessage) => void }> = [];
+  private browser: Browser | null = null;
+
+  /**
+   * Start listening to console events from all current and future pages.
+   */
+  startListening(browser: Browser): void {
+    this.browser = browser;
+
+    // Listen to all existing pages
+    browser.pages().then(pages => {
+      for (const page of pages) {
+        this.attachPageListener(page);
+      }
+    }).catch((error) => {
+      console.error('[pi-to-chrome] console-buffer: browser.pages() 失败', error);
+    });
+
+    // Listen to new pages opened after connection
+    browser.on('targetcreated', async (target) => {
+      if (target.type() === 'page') {
+        try {
+          const page = await target.page();
+          if (page) {
+            this.attachPageListener(page);
+          }
+        } catch (error) {
+          console.error('[pi-to-chrome] console-buffer: targetcreated page() 失败', error);
+        }
+      }
+    });
+  }
+
+  /**
+   * Stop all listeners and clear buffer.
+   */
+  stopListening(): void {
+    for (const { page, handler } of this.listeners) {
+      try {
+        page.off('console', handler);
+      } catch (error) {
+        console.error('[pi-to-chrome] console-buffer: page.off() 失败', error);
+      }
+    }
+    this.listeners = [];
+    this.browser = null;
+    this.buffer = [];
+  }
+
+  /**
+   * Get messages from buffer, optionally filtered by level and limited.
+   */
+  getMessages(level: ConsoleLevel | 'all' = 'all', limit = 50): BufferedConsoleMessage[] {
+    let filtered = this.buffer;
+    if (level !== 'all') {
+      filtered = filtered.filter(m => m.type === level);
+    }
+    return filtered.slice(-limit);
+  }
+
+  /**
+   * Clear all buffered messages.
+   */
+  clear(): void {
+    this.buffer = [];
+  }
+
+  /**
+   * Total number of messages in buffer.
+   */
+  get count(): number {
+    return this.buffer.length;
+  }
+
+  private attachPageListener(page: Page): void {
+    const handler = (msg: ConsoleMessage) => {
+      const type = msg.type() as ConsoleLevel;
+      if (!['log', 'warn', 'error', 'info'].includes(type)) return;
+
+      this.addMessage({
+        type,
+        text: msg.text(),
+        url: page.url(),
+        timestamp: Date.now()
+      });
+    };
+
+    page.on('console', handler);
+    this.listeners.push({ page, handler });
+  }
+
+  private addMessage(msg: BufferedConsoleMessage): void {
+    this.buffer.push(msg);
+    // Ring buffer: drop oldest when over capacity
+    if (this.buffer.length > MAX_BUFFER_SIZE) {
+      this.buffer.shift();
+    }
+  }
+}

package/core/browser.ts

@@ -0,0 +1,254 @@
+/**
+ * core/browser - Browser lifecycle and utilities
+ *
+ * All browser-related logic centralized here:
+ * - Lifecycle (connect/disconnect/spawn/kill)
+ * - Page utilities (getActivePage)
+ * - Proxy bypass
+ * - Profile management
+ */
+
+import type { Browser, Page } from 'puppeteer-core';
+import { spawn, execSync } from 'child_process';
+import { existsSync, mkdirSync, symlinkSync } from 'fs';
+import { homedir } from 'os';
+import * as path from 'path';
+
+// ─── Connection mode ───
+export type ConnectionMode = 'local' | 'remote';
+
+// ─── Configurable state ───
+let connectionMode: ConnectionMode = 'local';
+let debugHost: string = '127.0.0.1';
+let debugPort: number = 9222;
+
+// ─── Chrome paths (local mode only) ───
+const CHROME_PATH = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const DEFAULT_PROFILE_DIR = path.join(homedir(), 'Library/Application Support/Google/Chrome');
+export const DEBUG_PROFILE_DIR = path.join(homedir(), 'Library/Application Support/Google/Chrome-Debug');
+
+// ─── Module state ───
+let browser: Browser | null = null;
+
+// ─── 断线回调 ───
+let disconnectedCallback: (() => void) | null = null;
+
+// ─── 健康检查缓存 ───
+let lastHealthCheckTime = 0;
+let lastHealthCheckResult = true;
+const HEALTH_CHECK_TTL_MS = 5000; // 5 秒内有效
+
+// ─── Connection configuration ───
+export function configureConnection(options: {
+  mode?: ConnectionMode;
+  host?: string;
+  port?: number;
+}): void {
+  if (options.mode !== undefined) connectionMode = options.mode;
+  if (options.host !== undefined) debugHost = options.host;
+  if (options.port !== undefined) debugPort = options.port;
+}
+
+export function getMode(): ConnectionMode {
+  return connectionMode;
+}
+
+export function getDebugUrl(): string {
+  return `http://${debugHost}:${debugPort}`;
+}
+
+export function isConnected(): boolean {
+  return browser !== null;
+}
+
+export function getBrowser(): Browser {
+  if (!browser) throw new Error('Chrome 未连接，请先执行 /chrome-start');
+  return browser;
+}
+
+/** 注册断线回调（由 index.ts 调用，回调中无 pi ctx，只有 pi 可用） */
+export function onDisconnected(cb: () => void): void {
+  disconnectedCallback = cb;
+}
+
+/** 健康检查：确认 browser 连接有效。失败则 throw 明确错误。 */
+export async function ensureConnection(): Promise<void> {
+  if (!browser) {
+    throw new Error('Chrome 连接已断开，请执行 /chrome-start 重连');
+  }
+
+  // 利用缓存避免并发工具调用时重复 CDP 请求
+  const now = Date.now();
+  if (now - lastHealthCheckTime < HEALTH_CHECK_TTL_MS && lastHealthCheckResult) {
+    return;
+  }
+
+  try {
+    await browser.version();
+    lastHealthCheckTime = now;
+    lastHealthCheckResult = true;
+  } catch (error) {
+    lastHealthCheckResult = false;
+    console.error('[pi-to-chrome] ensureConnection: browser.version() 失败', error);
+    throw new Error('Chrome 连接已断开，请执行 /chrome-start 重连');
+  }
+}
+
+// ─── Proxy bypass ───
+export async function fetchChromeDebug(urlPath: string, init?: RequestInit): Promise<Response> {
+  const prevNoProxy = process.env.NO_PROXY;
+  const prevNoProxy2 = process.env.no_proxy;
+  process.env.NO_PROXY = '127.0.0.1';
+  process.env.no_proxy = '127.0.0.1';
+  try {
+    return await fetch(`${getDebugUrl()}${urlPath}`, init);
+  } finally {
+    if (prevNoProxy !== undefined) process.env.NO_PROXY = prevNoProxy;
+    else delete process.env.NO_PROXY;
+    if (prevNoProxy2 !== undefined) process.env.no_proxy = prevNoProxy2;
+    else delete process.env.no_proxy;
+  }
+}
+
+// ─── Profile management ───
+export function ensureDebugProfile(): void {
+  try {
+    if (!existsSync(DEBUG_PROFILE_DIR)) {
+      mkdirSync(DEBUG_PROFILE_DIR, { recursive: true });
+    }
+    const defaultDataDir = path.join(DEFAULT_PROFILE_DIR, 'Default');
+    const debugDefaultLink = path.join(DEBUG_PROFILE_DIR, 'Default');
+    if (!existsSync(debugDefaultLink) && existsSync(defaultDataDir)) {
+      symlinkSync(defaultDataDir, debugDefaultLink);
+    }
+  } catch (error: any) {
+    console.error('Failed to setup debug profile:', error.message);
+  }
+}
+
+// ─── Page utilities ───
+/** 判断是否为 Chrome 内部页面（非用户页面） */
+function isChromeInternalPage(url: string): boolean {
+  return url.startsWith('chrome://') ||
+    url.startsWith('chrome-search://') ||
+    url.startsWith('chrome-extension://') ||
+    url.startsWith('devtools://');
+}
+
+export async function getActivePage(): Promise<Page> {
+  const b = getBrowser();
+
+  try {
+    const pages = await b.pages();
+
+    // 优先从用户页面中找 visible 的
+    for (const page of pages) {
+      if (isChromeInternalPage(page.url())) continue;
+      try {
+        const visibilityState = await page.evaluate(() => document.visibilityState);
+        if (visibilityState === 'visible') {
+          return page;
+        }
+      } catch (error) {
+        console.error(`[pi-to-chrome] getActivePage: page.evaluate() 失败 (url=${page.url()})`, error);
+      }
+    }
+
+    // 没有 visible 的用户页面，返回第一个用户页面
+    const userPage = pages.find(p => !isChromeInternalPage(p.url()));
+    if (userPage) return userPage;
+
+    // 兜底：只有内部页面时返回第一个
+    if (pages.length > 0) {
+      return pages[0];
+    }
+  } catch (error) {
+    console.error('[pi-to-chrome] getActivePage: b.pages() 失败', error);
+  }
+
+  throw new Error('无法获取当前页面');
+}
+
+// ─── Lifecycle ───
+export async function isChromeRunning(): Promise<boolean> {
+  try {
+    const response = await fetchChromeDebug('/json/version', {
+      signal: AbortSignal.timeout(1000)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function killChrome(): Promise<void> {
+  return new Promise((resolve) => {
+    const kill = spawn('pkill', ['-f', 'Google Chrome'], {
+      stdio: 'ignore',
+      shell: true
+    });
+    kill.on('close', async () => {
+      const deadline = Date.now() + 5000;
+      while (Date.now() < deadline) {
+        try {
+          const out = execSync('pgrep -f "Google Chrome"', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+          if (!out.trim()) break;
+        } catch { break; }
+        await new Promise(r => setTimeout(r, 300));
+      }
+      resolve();
+    });
+    kill.on('error', () => resolve());
+  });
+}
+
+export function spawnChrome(): void {
+  ensureDebugProfile();
+
+  spawn(CHROME_PATH, [
+    '--remote-debugging-port=9222',
+    `--user-data-dir=${DEBUG_PROFILE_DIR}`,
+    '--restore-last-session'
+  ], {
+    detached: true,
+    stdio: 'ignore'
+  }).unref();
+}
+
+export async function waitForChromeReady(timeoutMs: number = 15000): Promise<boolean> {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeoutMs) {
+    if (await isChromeRunning()) {
+      return true;
+    }
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+
+export async function connectChrome(): Promise<Browser> {
+  const puppeteer = await import('puppeteer-core');
+  browser = await puppeteer.connect({ browserURL: getDebugUrl(), defaultViewport: null });
+
+  // 注册断线监听
+  browser.on('disconnected', () => {
+    console.error('[pi-to-chrome] browser disconnected 事件触发');
+    browser = null;                          // 直接置 null，不做任何 CDP 请求
+    lastHealthCheckResult = false;           // 失效化健康检查缓存
+    disconnectedCallback?.();                // 通知 index.ts 做清理和通知
+  });
+
+  return browser;
+}
+
+export async function disconnectChrome(): Promise<void> {
+  if (browser) {
+    try {
+      browser.disconnect();
+    } catch (error) {
+      console.error('[pi-to-chrome] disconnectChrome: browser.disconnect() 失败', error);
+    }
+    browser = null;
+    lastHealthCheckResult = false;
+  }
+}

package/core/types.ts

@@ -0,0 +1,29 @@
+/**
+ * core/types - Shared types for chrome extension tools
+ */
+
+import type { Page } from 'puppeteer-core';
+import type { ConsoleBuffer } from '../console-buffer';
+import type { TSchema } from '@sinclair/typebox';
+
+// Tool unified return format
+export interface ToolResult {
+  content: [{ type: 'text'; text: string }];
+  details: Record<string, any>;
+}
+
+// Tool dependencies (injected at call time)
+export interface ToolDeps {
+  consoleBuffer: ConsoleBuffer;
+}
+
+// Tool definition object (generic preserves parameter types)
+export interface ToolDefinition<TParams = any> {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+  execute: (page: Page, params: TParams, deps?: ToolDeps) => Promise<ToolResult>;
+}

package/index.ts

@@ -0,0 +1,173 @@
+/**
+ * chrome-inspect - Chrome Browser Inspection Extension for pi
+ *
+ * Provides tools to inspect DOM, CSS styles, console logs, and execute JS
+ * in a Chrome browser connected via remote debugging port.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+import { ConsoleBuffer } from './console-buffer';
+import * as browser from './core/browser';
+import { registerTools } from './tool-registry';
+
+export default async function(pi: ExtensionAPI) {
+  const consoleBuffer = new ConsoleBuffer();
+  let toolNames: string[] = [];
+
+  // ─── /chrome-start ───
+  pi.registerCommand('chrome-start', {
+    description: '连接 Chrome 浏览器并启用页面检查工具 (--remote 用于 SSH 隧道连接)',
+    handler: async (args: any, ctx: any) => {
+      // Parse args: --remote, --host <value>, --port <value>
+      const argStr = typeof args === 'string' ? args : '';
+      const argParts = argStr.trim().split(/\s+/);
+      let isRemote = false;
+      let host = '127.0.0.1';
+      let port = 9222;
+
+      for (let i = 0; i < argParts.length; i++) {
+        const part = argParts[i];
+        if (part === '--remote' || part === '-r') {
+          isRemote = true;
+        } else if (part === '--host' && i + 1 < argParts.length) {
+          host = argParts[++i];
+        } else if (part === '--port' && i + 1 < argParts.length) {
+          const parsed = parseInt(argParts[++i], 10);
+          if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+            ctx.ui.notify('❌ 无效端口号，范围: 1-65535', 'error');
+            return;
+          }
+          port = parsed;
+        }
+      }
+
+      // Configure connection mode (always reset all fields to avoid stale state)
+      browser.configureConnection({
+        mode: isRemote ? 'remote' : 'local',
+        host: isRemote ? host : '127.0.0.1',
+        port: isRemote ? port : 9222,
+      });
+
+      ctx.ui.notify(isRemote ? '正在连接远程 Chrome...' : '正在连接 Chrome...', 'info');
+
+      try {
+        try {
+          await browser.connectChrome();
+          ctx.ui.notify('✅ 已连接到运行中的 Chrome', 'info');
+        } catch {
+          if (isRemote) {
+            ctx.ui.notify(
+              '❌ 无法连接到远程 Chrome，请确认：\n' +
+              '1. Mac 上 Chrome 已启动（--remote-debugging-port=9222）\n' +
+              '2. SSH 隧道已建立（ssh -R 9222:127.0.0.1:9222 ...）',
+              'error'
+            );
+            return;
+          }
+
+          if (await browser.isChromeRunning()) {
+            const ok = await ctx.ui.confirm(
+              '关闭 Chrome？',
+              '需要关闭现有 Chrome，未保存内容可能丢失。是否继续？'
+            );
+            if (!ok) {
+              ctx.ui.notify('已取消', 'warning');
+              return;
+            }
+            await browser.killChrome();
+          }
+
+          browser.spawnChrome();
+
+          if (!(await browser.waitForChromeReady())) {
+            ctx.ui.notify('Chrome 启动超时，请手动检查', 'error');
+            return;
+          }
+
+          await browser.connectChrome();
+          ctx.ui.notify('✅ Chrome 启动成功', 'info');
+        }
+
+        // 注册断线回调（在 startListening/registerTools 之前，消除 race window）
+        browser.onDisconnected(() => {
+          if (toolNames.length === 0) return;
+
+          consoleBuffer.stopListening();
+          const allActive = pi.getActiveTools();
+          const remaining = allActive.filter((name: string) => !toolNames.includes(name));
+          pi.setActiveTools(remaining);
+          toolNames = [];
+
+          pi.sendMessage({
+            customType: 'chrome-disconnected',
+            content: '⚠️ Chrome 连接已断开！\n如需查看原因，请立即切换到 Chrome 查看 console 日志\n如需重新连接，请执行 /chrome-start',
+            display: true,
+          });
+        });
+
+        consoleBuffer.startListening(browser.getBrowser());
+
+        toolNames = registerTools(pi, consoleBuffer);
+        // 将新注册的工具加入 active tools
+        const currentActive = pi.getActiveTools();
+        pi.setActiveTools([...currentActive, ...toolNames]);
+        ctx.ui.notify('✅ Chrome 检查工具已就绪（4 个工具已注册）', 'info');
+
+      } catch (err: any) {
+        ctx.ui.notify('❌ 连接失败: ' + err.message, 'error');
+      }
+    }
+  });
+
+  // ─── /chrome-stop ───
+  pi.registerCommand('chrome-stop', {
+    description: '断开 Chrome 连接并关闭浏览器',
+    handler: async (args: any, ctx: any) => {
+      const isRemote = browser.getMode() === 'remote';
+
+      if (isRemote) {
+        // 远程模式：只断开连接，不关闭 Chrome
+        const allActive = pi.getActiveTools();
+        const remaining = allActive.filter((name: string) => !toolNames.includes(name));
+        pi.setActiveTools(remaining);
+        toolNames = [];
+
+        consoleBuffer.stopListening();
+        await browser.disconnectChrome();
+
+        ctx.ui.notify('✅ 已断开远程 Chrome 连接（浏览器未关闭）', 'info');
+      } else {
+        // 本地模式：断开并关闭
+        const ok = await ctx.ui.confirm(
+          '关闭 Chrome？',
+          '将关闭 Chrome 浏览器，是否继续？'
+        );
+        if (!ok) {
+          ctx.ui.notify('已取消', 'warning');
+          return;
+        }
+
+        const allActive = pi.getActiveTools();
+        const remaining = allActive.filter((name: string) => !toolNames.includes(name));
+        pi.setActiveTools(remaining);
+        toolNames = [];
+
+        consoleBuffer.stopListening();
+        await browser.disconnectChrome();
+        await browser.killChrome();
+
+        ctx.ui.notify('✅ Chrome 已断开并关闭', 'info');
+      }
+    }
+  });
+
+  // ─── session_shutdown cleanup ───
+  pi.on('session_shutdown', async () => {
+    if (browser.isConnected()) {
+      toolNames = [];  // 先清空，防止 disconnectChrome 触发断线回调发送误导通知
+      consoleBuffer.stopListening();
+      await browser.disconnectChrome();
+    }
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-to-chrome",
+  "version": "0.1.2",
+  "description": "The tinest Pi extension for Chrome — Only 4 tools what you need.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sollawen/pi-to-chrome.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sollawen/pi-to-chrome/issues"
+  },
+  "homepage": "https://github.com/sollawen/pi-to-chrome#readme",
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "chrome",
+    "devtools",
+    "puppeteer"
+  ],
+  "type": "module",
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "puppeteer-core": "^24.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "files": [
+    "index.ts",
+    "core/",
+    "tools/",
+    "tool-registry.ts",
+    "console-buffer.ts"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}