@mearl/client 2.0.2 → 2.2.0

package/dist/socket.js

@@ -7,6 +7,7 @@
  * 当 Socket 文件不存在（ENOENT）时，自动尝试拉起 native host，稍后重试连接。
  */
 import net from 'node:net';
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
@@ -15,6 +16,7 @@ import { listLiveBrowsers, findBrowser, describeBrowser } from './browserRegistr
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 const require = createRequire(import.meta.url);
 export const CLIENT_VERSION = require('../package.json').version;
+const MAX_SOCKET_BUFFER_SIZE = 64 * 1024 * 1024;
 /**
  * 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
@@ -79,8 +81,8 @@ let spawnAttempted = false;
  * 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)
+async function trySpawnNativeHost(registerBrowser = true, retryPreviousAttempt = false) {
+    if (registerBrowser && spawnAttempted && !retryPreviousAttempt)
         return false;
     if (registerBrowser)
         spawnAttempted = true;
@@ -128,20 +130,37 @@ export function invoke(action, data = {}, options = {}) {
             return Promise.reject(error);
         }
     }
-    const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser } = options;
+    const { timeoutSec = resolveActionTimeoutSec(action, data), transport, browser, controlSource = 'local', } = options;
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined).then(decorateBrowserListResult);
+        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(decorateBrowserListResult);
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
-    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector);
+    return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
 }
 function isConnError(error) {
     const code = error?.code;
     return code === 'ENOENT' || code === 'ECONNREFUSED';
 }
-async function dispatchInvoke(action, data, timeoutSec, transport, selector) {
+function isSocketSandboxError(error) {
+    return error?.code === 'EPERM';
+}
+async function dispatchInvoke(action, data, timeoutSec, transport, selector, controlSource) {
+    const configuredSocketPath = process.env.MEARL_SOCKET_PATH?.trim();
+    if (!selector && configuredSocketPath) {
+        try {
+            return await invokeOnce(action, data, timeoutSec, transport, configuredSocketPath, controlSource);
+        }
+        catch (error) {
+            if (isConnError(error) || isSocketSandboxError(error)) {
+                throw new Error(formatConnectError(error, configuredSocketPath), {
+                    cause: error,
+                });
+            }
+            throw error;
+        }
+    }
     const browsers = listLiveBrowsers();
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
@@ -150,10 +169,10 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector) {
             throw new Error(formatNoMatchError(selector, browsers));
         }
         try {
-            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath);
+            return await invokeOnce(action, data, timeoutSec, transport, match.socketPath, controlSource);
         }
         catch (error) {
-            if (isConnError(error)) {
+            if (isConnError(error) || isSocketSandboxError(error)) {
                 throw new Error(formatConnectError(error, match.socketPath), {
                     cause: error,
                 });
@@ -165,42 +184,56 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector) {
     // 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);
+            return await invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
         }
         catch (error) {
+            if (isSocketSandboxError(error)) {
+                throw new Error(formatConnectError(error, browsers[0].socketPath), { cause: error });
+            }
             if (!isConnError(error))
                 throw error;
         }
     }
-    return invokeViaLegacy(action, data, timeoutSec, transport, /* isRetry */ false);
+    return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
 /** Legacy well-known socket, auto-spawning a native-host on ENOENT and retrying once. */
-async function invokeViaLegacy(action, data, timeoutSec, transport, isRetry) {
+async function invokeViaLegacy(action, data, timeoutSec, transport, controlSource, isRetry) {
     try {
-        return await invokeOnce(action, data, timeoutSec, transport, SOCKET_PATH);
+        return await invokeOnce(action, data, timeoutSec, transport, SOCKET_PATH, controlSource);
     }
     catch (error) {
         const err = error;
-        if (err.code === 'ENOENT' && !isRetry) {
-            const spawned = await trySpawnNativeHost(action !== 'browser_list');
+        const shouldAttemptSpawn = err.code === 'ENOENT' || (action === 'browser_release' && err.code === 'ECONNREFUSED');
+        if (shouldAttemptSpawn && !isRetry) {
+            const spawned = await trySpawnNativeHost(action !== 'browser_list', action === 'browser_release');
             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 invokeOnce(action, data, timeoutSec, transport, browsers[0].socketPath, controlSource);
                 }
-                return invokeViaLegacy(action, data, timeoutSec, transport, /* isRetry */ true);
+                return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
+                /* isRetry */ true);
             }
         }
-        if (err instanceof Error && !isConnError(err))
+        if (err instanceof Error && !isConnError(err) && !isSocketSandboxError(err))
             throw err;
         throw new Error(formatConnectError(err, SOCKET_PATH), { cause: error });
     }
 }
-function invokeOnce(action, data, timeoutSec, transport, socketPath) {
+function invokeOnce(action, data, timeoutSec, transport, socketPath, controlSource) {
     const id = `${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
     return new Promise((resolve, reject) => {
+        if (process.platform !== 'win32' && fs.existsSync(socketPath) && process.getuid) {
+            const ownerUid = fs.statSync(socketPath).uid;
+            if (ownerUid !== process.getuid()) {
+                const error = new Error(`拒绝连接不属于当前用户的 Socket: ${socketPath}`);
+                Object.assign(error, { code: 'EACCES' });
+                reject(error);
+                return;
+            }
+        }
         const socket = net.createConnection(socketPath);
         let settled = false;
         let buffer = '';
@@ -220,13 +253,23 @@ function invokeOnce(action, data, timeoutSec, transport, socketPath) {
             settle(new Error(`请求超时，已等待 ${timeoutSec} 秒`));
         }, timeoutSec * 1000);
         socket.on('connect', () => {
-            const message = { id, action, data, version: CLIENT_VERSION };
+            const message = {
+                id,
+                action,
+                data,
+                version: CLIENT_VERSION,
+                controlSource,
+            };
             if (transport)
                 message.transport = transport;
             socket.write(JSON.stringify(message) + '\n');
         });
         socket.on('data', chunk => {
             buffer += chunk.toString('utf-8');
+            if (Buffer.byteLength(buffer, 'utf-8') > MAX_SOCKET_BUFFER_SIZE) {
+                settle(new Error(`Socket 响应超过 ${MAX_SOCKET_BUFFER_SIZE} 字节限制`));
+                return;
+            }
             let newlineIndex;
             while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
                 const line = buffer.slice(0, newlineIndex);
@@ -289,6 +332,14 @@ function formatConnectError(error, socketPath) {
             installHint,
         ].join('\n');
     }
+    if (error.code === 'EPERM') {
+        return [
+            `Socket 连接被执行环境拦截: ${socketPath}`,
+            '当前进程没有访问该 Mearl Unix Socket 的权限（EPERM）。',
+            '如果命令运行在 Agent 沙箱中，请为这个 Socket 配置精确的 Unix Socket 白名单后重试。',
+            '无需重新安装浏览器插件，也不要使用 sudo 或改写 Socket 权限。',
+        ].join('\n');
+    }
     return [`Socket 连接失败: ${error.message}`, '', installHint].join('\n');
 }
 /** Error message when an explicit --browser selector matches no live browser. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Client SDK & CLI for Mearl — communicate with Chrome Extension via Unix Socket",
   "type": "module",
   "main": "dist/index.js",
@@ -36,9 +36,9 @@
     "typescript": "^5.8.3"
   },
   "scripts": {
-    "build": "rm -rf dist/ && tsc && chmod +x dist/cli.js",
+    "build": "node ../../scripts/generate-client-action-protocol.mjs --check && rm -rf dist/ && tsc && chmod +x dist/cli.js",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node ../../scripts/generate-client-action-protocol.mjs --check && tsc --noEmit",
     "test": "vitest run"
   }
 }