@mearl/client 2.0.0

package/dist/socket.js

@@ -0,0 +1,306 @@
+/**
+ * 底层 Socket 通信模块
+ *
+ * 通过 Unix Domain Socket (macOS/Linux) 或 Named Pipe (Windows) 与 native host 进程通信。
+ * 每次调用新建连接，收到响应后关闭，简单可靠。
+ *
+ * 当 Socket 文件不存在（ENOENT）时，自动尝试拉起 native host，稍后重试连接。
+ */
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { resolveFileRefs } from './fileRefs.js';
+import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistry.js';
+import { resolveActionTimeoutSec } from './actionTimeouts.js';
+const require = createRequire(import.meta.url);
+export const CLIENT_VERSION = require('../package.json').version;
+/**
+ * Legacy well-known socket. New native-hosts publish per-browser sockets in the
+ * registry and we address those; this path is a fallback for pre-registry hosts
+ * (or the pre-ping startup window) and is what auto-spawn targets.
+ */
+export const SOCKET_PATH = process.platform === 'win32'
+    ? '\\\\.\\pipe\\mearl-agent'
+    : path.join(os.tmpdir(), 'mearl-agent.sock');
+/**
+ * Process-wide default browser selector. Lets a long-lived host (e.g. the MCP
+ * server) pin a target once via `select_browser` without threading it through
+ * every call. Explicit `options.browser` still wins per-call.
+ */
+let defaultBrowser;
+/** Pin the default target browser for subsequent invokes (undefined clears it). */
+export function setDefaultBrowser(selector) {
+    defaultBrowser = selector && selector.trim() ? selector.trim() : undefined;
+}
+export function getDefaultBrowser() {
+    return defaultBrowser;
+}
+function findConnectedBrowser(items, selector) {
+    const normalized = selector.trim().toLowerCase();
+    const connected = items.filter(item => item.status === 'connected');
+    return (connected.find(item => String(item.browserId).toLowerCase() === normalized) ??
+        connected.find(item => String(item.name).toLowerCase() === normalized) ??
+        connected.find(item => String(item.browserId).toLowerCase().includes(normalized) ||
+            String(item.name).toLowerCase().includes(normalized)) ??
+        null);
+}
+export function decorateBrowserListResult(result) {
+    const browsers = Array.isArray(result?.browsers) ? result.browsers : [];
+    const selector = getDefaultBrowser() ?? process.env.MEARL_BROWSER;
+    const selected = selector
+        ? findConnectedBrowser(browsers, selector)
+        : (browsers.find(browser => browser.status === 'connected') ?? null);
+    return {
+        ...result,
+        defaultBrowserId: selected?.browserId ?? null,
+    };
+}
+function selectBrowserResult(data) {
+    const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
+    if (!selector) {
+        setDefaultBrowser(undefined);
+        return {
+            selected: null,
+            note: 'Cleared: default target is now the most-recently focused browser.',
+        };
+    }
+    const browsers = listLiveBrowsers();
+    const match = findBrowser(browsers, selector);
+    if (!match)
+        throw new Error(formatNoMatchError(selector, browsers));
+    setDefaultBrowser(match.browserId);
+    return { selected: { browserId: match.browserId, name: match.browserName } };
+}
+/** Whether this process has already attempted to auto-spawn a persistent native-host. */
+let spawnAttempted = false;
+/**
+ * Attempt to spawn `mearl-native-host` in the background (detached).
+ * Inventory-only hosts serve one browser_list request without publishing a fake CDP target.
+ * Returns true if a spawn was attempted (regardless of success).
+ */
+async function trySpawnNativeHost(registerBrowser = true) {
+    if (registerBrowser && spawnAttempted)
+        return false;
+    if (registerBrowser)
+        spawnAttempted = true;
+    try {
+        const { spawn } = await import('node:child_process');
+        return await new Promise(resolve => {
+            const args = registerBrowser ? ['--daemon'] : ['--daemon', '--skip-browser-registration'];
+            const child = spawn('mearl-native-host', args, {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+            let settled = false;
+            const finish = (ok) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(ok);
+            };
+            // `spawn ENOENT` 等错误会通过事件异步抛出；必须显式监听避免进程崩溃。
+            child.once('error', () => finish(false));
+            child.once('spawn', () => {
+                child.unref();
+                finish(true);
+            });
+        });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 向 native host 发送一个 action 请求并等待响应。
+ *
+ * 目标解析优先级：显式 options.browser → setDefaultBrowser → 环境变量
+ * MEARL_BROWSER → 自动（注册表中最近聚焦的浏览器）。注册表为空时回退到
+ * legacy well-known socket，并在 socket 不存在（ENOENT）时自动拉起 native host。
+ */
+export function invoke(action, data = {}, options = {}) {
+    if (action === 'browser_select_browser') {
+        try {
+            return Promise.resolve(selectBrowserResult(data));
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser } = options;
+    // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
+    const resolvedData = resolveFileRefs(data);
+    if (action === 'browser_list') {
+        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined).then(decorateBrowserListResult);
+    }
+    const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
+    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector);
+}
+function isConnError(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'ECONNREFUSED';
+}
+async function dispatchInvoke(action, data, timeoutSec, transport, selector) {
+    const browsers = listLiveBrowsers();
+    // Explicit target: must match a live browser; do not silently fall back.
+    if (selector) {
+        const match = findBrowser(browsers, selector);
+        if (!match) {
+            throw new Error(formatNoMatchError(selector, browsers));
+        }
+        try {
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath);
+        }
+        catch (error) {
+            if (isConnError(error)) {
+                throw new Error(formatConnectError(error, match.socketPath), {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
+    // No explicit target: prefer the most-recently-focused live browser; on a
+    // stale socket, fall through to the legacy path + auto-spawn.
+    if (browsers.length > 0) {
+        try {
+            return await invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath);
+        }
+        catch (error) {
+            if (!isConnError(error))
+                throw error;
+        }
+    }
+    return invokeViaLegacy(action, data, timeoutSec, transport, /* isRetry */ false);
+}
+/** Legacy well-known socket, auto-spawning a native-host on ENOENT and retrying once. */
+async function invokeViaLegacy(action, data, timeoutSec, transport, isRetry) {
+    try {
+        return await invokeOnce(action, data, timeoutSec, transport, SOCKET_PATH);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT' && !isRetry) {
+            const spawned = await trySpawnNativeHost(action !== 'browser_list');
+            if (spawned) {
+                // Wait for the native host to start listening; persistent hosts also publish their registry record.
+                await new Promise(r => setTimeout(r, 1200));
+                const browsers = listLiveBrowsers();
+                if (browsers.length > 0) {
+                    return invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath);
+                }
+                return invokeViaLegacy(action, data, timeoutSec, transport, /* isRetry */ true);
+            }
+        }
+        if (err instanceof Error && !isConnError(err))
+            throw err;
+        throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
+    }
+}
+function invokeOnce(action, data, timeoutSec, transport, socketPath) {
+    const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socketPath);
+        let settled = false;
+        let buffer = '';
+        const settle = (error, result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeAllListeners();
+            socket.end();
+            if (error)
+                reject(error instanceof Error ? error : new Error(String(error)));
+            else
+                resolve(result);
+        };
+        const timer = setTimeout(() => {
+            settle(new Error(`请求超时，已等待 ${timeoutSec} 秒`));
+        }, timeoutSec * 1000);
+        socket.on('connect', () => {
+            const message = { id, action, data, version: CLIENT_VERSION };
+            if (transport)
+                message.transport = transport;
+            socket.write(JSON.stringify(message) + '\n');
+        });
+        socket.on('data', chunk => {
+            buffer += chunk.toString('utf-8');
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIndex);
+                buffer = buffer.slice(newlineIndex + 1);
+                if (!line.trim())
+                    continue;
+                try {
+                    const response = JSON.parse(line);
+                    if (response.id !== id)
+                        continue;
+                    if (response.versionWarning) {
+                        console.warn(response.versionWarning);
+                    }
+                    if (response.success)
+                        settle(null, response.data);
+                    else
+                        settle(new Error(response.error || 'Socket 服务端返回未知错误'));
+                    return;
+                }
+                catch {
+                    settle(new Error(`无效的 JSON 响应: ${line}`));
+                    return;
+                }
+            }
+        });
+        // Preserve the raw error (with .code) so the caller can branch on
+        // ENOENT / ECONNREFUSED to prune stale sockets or auto-spawn.
+        socket.on('error', (error) => settle(error));
+        socket.on('end', () => {
+            if (!settled)
+                settle(new Error('在收到响应前 Socket 已关闭'));
+        });
+    });
+}
+const EXTENSION_INSTALL_URL = 'https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm';
+function formatConnectError(error, socketPath) {
+    const installHint = `如果尚未安装浏览器插件，请先前往: ${EXTENSION_INSTALL_URL}`;
+    if (error.code === 'ENOENT') {
+        return [
+            `未找到 Socket: ${socketPath}`,
+            'native host 自动拉起失败，请手动排查：',
+            '',
+            '【方式一：浏览器插件模式】',
+            `1. 确认已安装 Mearl 浏览器插件（${EXTENSION_INSTALL_URL}）`,
+            '2. 确认已执行 Native Messaging 初始化（安装 @mearl/native-host 时会自动完成）',
+            '3. 确认 Chrome 浏览器正在运行，如仍无法连接可在 chrome://extensions 重新加载插件',
+            '',
+            '【方式二：CDP 远程调试模式（Chrome 145+，无需插件）】',
+            '  访问 chrome://inspect/#remote-debugging，勾选 "Discover network targets"',
+            '  Chrome 会弹出授权提示，点击允许，native host 自动读取 DevToolsActivePort 文件连接',
+            '  确认有普通网页已打开（非 chrome:// 页面）',
+        ].join('\n');
+    }
+    if (error.code === 'ECONNREFUSED') {
+        return [
+            `Socket 连接被拒绝: ${socketPath}`,
+            'native host 可能已退出。',
+            '请确认 Chrome 浏览器正在运行，可尝试在 chrome://extensions 重新加载插件。',
+            '',
+            installHint,
+        ].join('\n');
+    }
+    return [`Socket 连接失败: ${error.message}`, '', installHint].join('\n');
+}
+/** Error message when an explicit --browser selector matches no live browser. */
+function formatNoMatchError(selector, browsers) {
+    const available = browsers.length
+        ? browsers.map(b => `  - ${describeBrowser(b)}`).join('\n')
+        : '  （当前没有已连接的浏览器）';
+    return [
+        `未找到匹配 "${selector}" 的浏览器。`,
+        '当前已连接的浏览器：',
+        available,
+        '',
+        '用 `mearl browser_list` 查看完整列表；可用 browserId 或名称匹配。',
+    ].join('\n');
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mearl/client",
+  "version": "2.0.0",
+  "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./action-timeouts": {
+      "types": "./dist/actionTimeouts.d.ts",
+      "import": "./dist/actionTimeouts.js"
+    }
+  },
+  "bin": {
+    "mearl": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mearl",
+    "chrome-extension",
+    "devtools",
+    "socket-client"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "rm -rf dist/ && tsc && chmod +x dist/cli.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}