@mearl/client 3.0.0-beta.3 → 3.0.0-beta.5

package/dist/scriptCli.js

@@ -0,0 +1,94 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Command } from 'commander';
+import { executeScript } from './script.js';
+export async function runScriptCli(args, commandName) {
+    const program = new Command()
+        .name(`${commandName} run`)
+        .description('执行 Node.js 脚本；预注入 mearl SDK，支持顶层 await、条件和循环')
+        .option('--file <path>', '读取 JavaScript 文件；省略时从 stdin 读取')
+        .option('--session <new-or-id>', '首次建立或复用控制会话')
+        .option('--browser <id-or-name>', '指定浏览器')
+        .option('--connector <id-or-name>', '限制到远端 connector')
+        .option('--local', '仅使用本机浏览器')
+        .option('--cdp', '强制本机 CDP')
+        .option('--server <url>', '覆盖 cloud-server 地址')
+        .option('--timeout <seconds>', '整个脚本的执行时限（默认 60 秒）', '60')
+        .allowExcessArguments(false)
+        .exitOverride()
+        .addHelpText('after', `\n示例：\n  ${commandName} run --file task.mjs\n  ${commandName} run <<'JS'\n  console.log(await mearl.tabList());\n  JS\n\n脚本拥有当前宿主的 Node.js 权限；使用 await import() 加载模块。\n调用 Skill 命令：await mearl.invokePlugin('notes', { command: 'search', input: { query: 'project' } })。\n用 console.log(await mearl.help('pageClick')) 查询共享帮助，mearl.structure(value) 查看结果结构。\n每次运行重建 JS 变量；复用 session 和 tabId 可继续同一浏览器任务。\n`);
+    let source;
+    let options;
+    try {
+        program.parse(args, { from: 'user' });
+        options = program.opts();
+        const timeout = Number(options.timeout);
+        if (!Number.isFinite(timeout) || timeout <= 0 || timeout * 1000 > 2_147_483_647)
+            throw new Error('--timeout 必须是有效范围内的大于 0 的秒数');
+        if ((options.local || options.cdp) && options.connector)
+            throw new Error('--local/--cdp 不能与 --connector 同时使用');
+        if (options.file)
+            source = await readFile(resolve(options.file), 'utf8');
+        else {
+            if (process.stdin.isTTY)
+                throw new Error('通过 stdin 提交脚本，或使用 --file <path>');
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of process.stdin) {
+                const buffer = Buffer.from(chunk);
+                size += buffer.length;
+                if (size > 1024 * 1024)
+                    throw new Error('脚本不能超过 1 MiB');
+                chunks.push(buffer);
+            }
+            source = Buffer.concat(chunks).toString('utf8');
+        }
+        if (!source.trim() || Buffer.byteLength(source) > 1024 * 1024)
+            throw new Error('脚本必须是非空且不超过 1 MiB 的 JavaScript');
+    }
+    catch (error) {
+        if (error.code === 'commander.helpDisplayed')
+            return 0;
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.once('SIGINT', abort);
+    process.once('SIGTERM', abort);
+    try {
+        const result = await executeScript(source, {
+            executionTimeoutSec: Number(options.timeout),
+            signal: controller.signal,
+            source: 'cli',
+            ...(options.session ? { session: options.session } : {}),
+            ...(options.browser ? { browser: options.browser } : {}),
+            ...(options.connector ? { connector: options.connector } : {}),
+            ...(options.local || options.cdp ? { local: true } : {}),
+            ...(options.cdp ? { transport: 'cdp' } : {}),
+            ...(options.server ? { serverUrl: options.server } : {}),
+        });
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+        if (result.session)
+            console.error(JSON.stringify({ session: result.session }));
+        if (!result.success)
+            console.error(JSON.stringify({
+                error: result.error,
+                executionStopped: result.executionStopped,
+                mayHaveLateEffects: result.mayHaveLateEffects,
+                pendingActions: result.pendingActions,
+            }));
+        return result.success ? 0 : 1;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    finally {
+        process.removeListener('SIGINT', abort);
+        process.removeListener('SIGTERM', abort);
+    }
+}

package/dist/scriptErrors.d.ts

@@ -0,0 +1,8 @@
+export declare function serializeScriptError(error: unknown, fallback?: string): {
+    stack?: string | undefined;
+    attempt?: {} | null | undefined;
+    stage?: string | undefined;
+    details?: Record<string, unknown> | undefined;
+    code: string;
+    message: string;
+};

package/dist/scriptErrors.js

@@ -0,0 +1,21 @@
+import { serializePluginExecutionError } from './plugins/runtime/pluginExecutorProtocol.js';
+export function serializeScriptError(error, fallback = 'SCRIPT_ERROR') {
+    const value = error;
+    const diagnostic = serializePluginExecutionError({
+        message: typeof value?.message === 'string' ? value.message : String(error),
+        code: typeof value?.code === 'string' ? value.code : fallback,
+        details: {
+            ...value?.details,
+            ...(value?.attempt !== undefined ? { attempt: value.attempt } : {}),
+        },
+        ...(typeof value?.stage === 'string' ? { stage: value.stage } : {}),
+    });
+    return {
+        code: diagnostic.code ?? fallback,
+        message: diagnostic.message,
+        ...(diagnostic.details ? { details: diagnostic.details } : {}),
+        ...(typeof diagnostic.metadata?.stage === 'string' ? { stage: diagnostic.metadata.stage } : {}),
+        ...(diagnostic.details?.attempt !== undefined ? { attempt: diagnostic.details.attempt } : {}),
+        ...(typeof value?.stack === 'string' ? { stack: value.stack.slice(0, 16384) } : {}),
+    };
+}

package/dist/scriptWorker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scriptWorker.js

@@ -0,0 +1,50 @@
+import { getStructure } from '@mearl/browser-core';
+import { serializeScriptError } from './scriptErrors.js';
+const pending = new Map();
+let sequence = 0;
+let session;
+const call = (method, args) => new Promise((resolve, reject) => {
+    const id = ++sequence;
+    pending.set(id, { resolve, reject });
+    process.send({ type: 'call', id, method, args });
+});
+process.on('disconnect', () => process.exit(1));
+process.on('message', async (message) => {
+    if (message.type === 'response') {
+        const entry = pending.get(message.id);
+        if (!entry)
+            return;
+        pending.delete(message.id);
+        session = message.session ?? session;
+        if (message.error)
+            entry.reject(Object.assign(new Error(message.error.message), message.error));
+        else
+            entry.resolve(message.result);
+        return;
+    }
+    if (message.type !== 'start')
+        return;
+    session = message.session;
+    const api = Object.fromEntries(message.methods.map((method) => [method, (...args) => call(method, args)]));
+    api.structure = getStructure;
+    Object.defineProperty(api, 'session', { get: () => session, enumerable: true });
+    Object.defineProperty(globalThis, 'mearl', { value: Object.freeze(api), configurable: true });
+    let failure;
+    try {
+        const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+        const fn = new AsyncFunction('mearl', '"use strict";\n' + message.code + '\n//# sourceURL=mearl-script.js');
+        await fn(api);
+        if (pending.size)
+            throw Object.assign(new Error('Script finished with unawaited SDK calls'), {
+                code: 'SCRIPT_PENDING_CALLS',
+            });
+    }
+    catch (error) {
+        failure = serializeScriptError(error);
+    }
+    await Promise.all([
+        new Promise(resolve => process.stdout.write('', resolve)),
+        new Promise(resolve => process.stderr.write('', resolve)),
+    ]);
+    process.send(failure ? { type: 'error', error: failure } : { type: 'done' });
+});

package/dist/sdkMethods.d.ts

@@ -0,0 +1,3 @@
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export declare const SDK_METHOD_ACTIONS: Map<string, string>;
+export declare const SDK_OPTIONS_ONLY_METHODS: Set<string>;

package/dist/sdkMethods.js

@@ -0,0 +1,9 @@
+import { BROWSER_COMMAND_ACTIONS } from '@mearl/browser-core/browserActionProtocol';
+/** Method names and signature exceptions shared by script dispatch and command help. */
+export const SDK_METHOD_ACTIONS = new Map(Object.keys(BROWSER_COMMAND_ACTIONS).map(action => [
+    action.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()),
+    action,
+]));
+SDK_METHOD_ACTIONS.set('selectBrowser', 'browser_select_browser');
+SDK_METHOD_ACTIONS.set('captureCheckpoint', 'tab_checkpoint');
+export const SDK_OPTIONS_ONLY_METHODS = new Set(['browserList', 'tabList', 'getRules']);

package/dist/socket.js

@@ -133,6 +133,7 @@ function isOrdinaryLocalBrowser(browser) {
 function supportsAction(browser, action, data) {
     if (browser.transport === 'provider') {
         if (action === 'browser_control' ||
+            (action === 'get_capabilities' && isConnectedBrowser(browser)) ||
             (action === 'browser_release' && data[SESSION_OPTION]))
             return true;
         if (action.startsWith('__artifact_'))
@@ -686,7 +687,7 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ENOENT') {
         return [
             `未找到 Socket: ${socketPath}`,
-            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx --@mearl:registry=https://registry.npmjs.org @mearl/setup --local --yes。',
+            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx @mearl/setup --local --yes。',
             '自动拉起只使用默认 daemon 参数；自定义 CDP/Profile/浏览器参数需手工启动，参见 mearl-native-host --help。',
             '',
             '【方式一：浏览器插件模式】',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.5",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,10 @@
     "./plugin": {
       "types": "./dist/plugin.d.ts",
       "import": "./dist/plugin.js"
+    },
+    "./script": {
+      "types": "./dist/script.d.ts",
+      "import": "./dist/script.js"
     }
   },
   "bin": {
@@ -60,16 +64,14 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "acorn": "^8.16.0",
-    "ajv": "^8.18.0",
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "3.0.0-beta.3",
-    "@mearl/cloud-types": "3.0.0-beta.3",
-    "@mearl/provider": "3.0.0-beta.3",
-    "@mearl/agent-runtime": "3.0.0-beta.3",
-    "@mearl/browser-core": "3.0.0-beta.3"
+    "@mearl/provider": "3.0.0-beta.5",
+    "@mearl/agent-runtime": "3.0.0-beta.5",
+    "@mearl/browser-core": "3.0.0-beta.5",
+    "@mearl/cloud-types": "3.0.0-beta.5",
+    "@mearl/daemon-core": "3.0.0-beta.5"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",