@mearl/client 2.0.0

package/dist/cli.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * mearl CLI — 通过命令行调用 Mearl 浏览器插件能力
+ *
+ * 用法：
+ *   mearl <action> [--payload <json> | --payload-file <path>] [--timeout <seconds>] [--compact] [--output <path>]
+ *
+ * 示例：
+ *   mearl get_requests --payload '{"count":5}'
+ *   mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
+ *   mearl page_screenshot --output ./screenshot.png
+ *   mearl set_mock --payload-file ./mock-data.json
+ */
+import fs from 'node:fs';
+import { invoke, CLIENT_VERSION } from './socket.js';
+import { COMMAND_MAP } from './commands.js';
+import { runCheck } from './check.js';
+import { resolveActionTimeoutSec } from './actionTimeouts.js';
+// ─── Usage / Help ─────────────────────────────────────────────────────────────
+const CATEGORIES = [
+    { title: 'API 调试', names: ['get_requests', 'get_logs', 'get_events', 'get_api_schema'] },
+    { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
+    { title: '网络代理', names: ['send_request', 'send_mtop_request'] },
+    { title: '标签页', names: ['tab_open', 'tab_close', 'tab_list'] },
+    {
+        title: '页面操作',
+        names: [
+            'page_click',
+            'page_type',
+            'page_hover',
+            'page_scroll',
+            'page_eval',
+            'page_press',
+            'page_wait',
+            'page_navigate',
+            'page_upload',
+        ],
+    },
+    { title: '组合调用', names: ['run_actions'] },
+    {
+        title: '页面感知',
+        names: ['page_snapshot', 'page_screenshot', 'page_selected_element', 'page_frames'],
+    },
+    { title: '环境模拟', names: ['set_device_emulation', 'set_timezone'] },
+    { title: '用户信息', names: ['get_user_info'] },
+    { title: '录制', names: ['record_start', 'record_stop'] },
+    { title: 'TDBank', names: ['tdbank_account'] },
+    {
+        title: '浏览器',
+        names: ['browser_list', 'browser_launch', 'browser_close'],
+    },
+];
+function printUsage() {
+    const lines = [
+        '用法：',
+        '  mearl <action> [选项]',
+        '  mearl <action> --help',
+        '  mearl check',
+        '',
+        '通用选项：',
+        '  --payload <json>      直接传入 JSON 参数',
+        '  --payload-file <path> 从文件读取整个 JSON 参数（适合大体积 payload）',
+        '  --timeout <seconds>   超时时间（默认按 action 推导，普通 action 为 15 秒）',
+        '  --compact             输出紧凑格式 JSON',
+        '  --output <path>       输出文件路径（page_screenshot / page_selected_element 可用）',
+        '  --cdp                 强制使用 CDP 模式（跳过插件通道）',
+        '  --browser <id|名称>   指定目标浏览器（多浏览器时；缺省用最近聚焦的那个）',
+        '',
+        '文件引用（任意 action 通用，减少上下文占用）：',
+        '  payload 顶层字段写成 "@<path>"（@ 开头的字符串）即从文件读取该字段值，',
+        '  默认按 JSON 解析、失败按原始文本；找不到文件则原样保留该字符串。',
+        `  例：set_mock --payload '{"apiName":"x","mockData":"@/abs/resp.json"}'`,
+        '',
+        '内置命令：',
+        '  check                 检测环境配置，排查连接问题',
+    ];
+    for (const cat of CATEGORIES) {
+        lines.push('');
+        lines.push(`  ${cat.title}`);
+        for (const name of cat.names) {
+            const cmd = COMMAND_MAP.get(name);
+            if (cmd) {
+                lines.push(`    ${name.padEnd(26)}${cmd.description}`);
+            }
+        }
+    }
+    lines.push('');
+    lines.push('运行 mearl <action> --help 查看某个命令的详细参数');
+    console.error(lines.join('\n'));
+}
+function printCommandHelp(cmd) {
+    const outputOption = cmd.outputFlag ? ' [--output <path>]' : '';
+    const lines = [
+        `${cmd.name}`,
+        `  ${cmd.description}`,
+        '',
+        '用法：',
+        `  mearl ${cmd.name} [--payload <json>] [--timeout <seconds>]${outputOption}`,
+        '',
+    ];
+    if (cmd.params && cmd.params.length > 0) {
+        lines.push('参数（--payload JSON 字段）：');
+        for (const p of cmd.params) {
+            const req = p.required ? '必填' : '可选';
+            lines.push(`  ${p.name.padEnd(22)}${req.padEnd(6)}${p.type.padEnd(28)}${p.description}`);
+        }
+        lines.push('');
+    }
+    if (cmd.outputFlag) {
+        lines.push('CLI 选项：');
+        lines.push('  --output <path>       将截图保存到本地文件');
+        lines.push('');
+    }
+    if (cmd.examples && cmd.examples.length > 0) {
+        lines.push('示例：');
+        for (const ex of cmd.examples) {
+            lines.push(`  mearl ${ex}`);
+        }
+        lines.push('');
+    }
+    console.error(lines.join('\n'));
+}
+function parseArgs(argv) {
+    if (argv.includes('--version') || argv.includes('-v')) {
+        console.log(CLIENT_VERSION);
+        process.exit(0);
+    }
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        return { showHelp: true, action: COMMAND_MAP.has(argv[0]) ? argv[0] : undefined };
+    }
+    const action = argv[0];
+    let payloadRaw = '{}';
+    let payloadFile = null;
+    let timeoutSec;
+    let compact = false;
+    let outputPath = null;
+    let forceCdp = false;
+    let browser;
+    let i = 1;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === '--payload') {
+            if (i + 1 >= argv.length)
+                throw new Error('缺少 --payload 的参数值');
+            payloadRaw = argv[i + 1];
+            i += 2;
+            continue;
+        }
+        if (arg === '--payload-file') {
+            if (i + 1 >= argv.length)
+                throw new Error('缺少 --payload-file 的参数值');
+            payloadFile = argv[i + 1];
+            i += 2;
+            continue;
+        }
+        if (arg === '--timeout') {
+            if (i + 1 >= argv.length)
+                throw new Error('缺少 --timeout 的参数值');
+            const value = Number(argv[i + 1]);
+            if (!Number.isFinite(value) || value <= 0)
+                throw new Error('--timeout 必须是大于 0 的数字');
+            timeoutSec = value;
+            i += 2;
+            continue;
+        }
+        if (arg === '--compact') {
+            compact = true;
+            i += 1;
+            continue;
+        }
+        if (arg === '--cdp') {
+            forceCdp = true;
+            i += 1;
+            continue;
+        }
+        if (arg === '--browser') {
+            if (i + 1 >= argv.length)
+                throw new Error('缺少 --browser 的参数值');
+            browser = argv[i + 1];
+            i += 2;
+            continue;
+        }
+        if (arg === '--output') {
+            if (i + 1 >= argv.length)
+                throw new Error('缺少 --output 的参数值');
+            outputPath = argv[i + 1];
+            i += 2;
+            continue;
+        }
+        throw new Error(`未知参数: ${arg}`);
+    }
+    return {
+        showHelp: false,
+        action,
+        payloadRaw,
+        payloadFile,
+        timeoutSec,
+        compact,
+        outputPath,
+        forceCdp,
+        browser,
+    };
+}
+function parsePayload(payloadRaw) {
+    try {
+        return JSON.parse(payloadRaw);
+    }
+    catch (error) {
+        throw new Error(`无效的 JSON payload: ${payloadRaw}`, { cause: error });
+    }
+}
+function saveBase64Image(outputPath, base64Data) {
+    fs.writeFileSync(outputPath, Buffer.from(base64Data, 'base64'));
+}
+function extractScreenshotResult(action, result) {
+    if (action === 'page_screenshot' && result?.meta && result?.data) {
+        return {
+            label: 'Screenshot',
+            meta: result.meta,
+            data: result.data,
+            extraLines: [`  Page: ${result.meta.title}`, `  URL: ${result.meta.url}`],
+        };
+    }
+    if (action === 'page_selected_element' && result?.screenshot?.meta && result?.screenshot?.data) {
+        return {
+            label: 'Selected element screenshot',
+            meta: result.screenshot.meta,
+            data: result.screenshot.data,
+            extraLines: [
+                `  Element: ${result.tagName || 'unknown'}`,
+                `  Selector: ${result.selector || 'N/A'}`,
+            ],
+        };
+    }
+    return null;
+}
+async function main() {
+    // Handle built-in subcommands before normal arg parsing
+    if (process.argv[2] === 'check') {
+        await runCheck();
+        return;
+    }
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exit(2);
+    }
+    if (args.showHelp) {
+        if (args.action) {
+            printCommandHelp(COMMAND_MAP.get(args.action));
+        }
+        else {
+            printUsage();
+        }
+        return;
+    }
+    if (!COMMAND_MAP.has(args.action)) {
+        console.error(`不支持的 action: ${args.action}`);
+        console.error(`运行 mearl --help 查看所有可用命令`);
+        process.exit(2);
+    }
+    let data;
+    try {
+        if (args.payloadFile) {
+            if (!fs.existsSync(args.payloadFile)) {
+                throw new Error(`Payload file not found: ${args.payloadFile}`);
+            }
+            const fileContent = fs.readFileSync(args.payloadFile, 'utf-8');
+            data = JSON.parse(fileContent);
+        }
+        else {
+            data = parsePayload(args.payloadRaw);
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(2);
+    }
+    try {
+        if (args.action === 'page_selected_element' && args.outputPath) {
+            data = { ...data, includeScreenshot: true };
+        }
+        const result = await invoke(args.action, data, {
+            timeoutSec: args.timeoutSec ?? resolveActionTimeoutSec(args.action, data),
+            transport: args.forceCdp ? 'cdp' : undefined,
+            browser: args.browser,
+        });
+        const screenshot = extractScreenshotResult(args.action, result);
+        if (screenshot) {
+            const sizeKB = Math.round(screenshot.meta.size / 1024);
+            if (args.outputPath) {
+                try {
+                    saveBase64Image(args.outputPath, screenshot.data);
+                    console.error(`✓ ${screenshot.label} saved to: ${args.outputPath}`);
+                }
+                catch (err) {
+                    console.error(`✗ Failed to save ${screenshot.label.toLowerCase()}: ${err instanceof Error ? err.message : String(err)}`);
+                    process.exit(1);
+                }
+            }
+            console.error(`✓ ${screenshot.label} captured`);
+            console.error(`  Format: ${screenshot.meta.format.toUpperCase()}`);
+            console.error(`  Size: ${screenshot.meta.width}x${screenshot.meta.height}`);
+            console.error(`  File size: ~${sizeKB}KB`);
+            screenshot.extraLines.forEach(line => console.error(line));
+            if (!args.outputPath) {
+                const output = args.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+                process.stdout.write(output + '\n');
+            }
+            return;
+        }
+        const output = args.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2);
+        process.stdout.write(output + '\n');
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+main();

package/dist/commands.d.ts

@@ -0,0 +1,18 @@
+export interface ParamDef {
+    name: string;
+    type: string;
+    required?: boolean;
+    description: string;
+}
+export interface CommandDef {
+    name: string;
+    description: string;
+    /** payload 字段说明 */
+    params?: ParamDef[];
+    /** 是否支持 --output */
+    outputFlag?: boolean;
+    examples?: string[];
+}
+export declare const COMMANDS: CommandDef[];
+export type KnownAction = 'get_requests' | 'get_logs' | 'get_events' | 'get_api_schema' | 'set_mock' | 'get_mocks' | 'set_rule' | 'get_rules' | 'send_request' | 'send_mtop_request' | 'tab_open' | 'tab_close' | 'tab_list' | 'page_click' | 'page_type' | 'page_hover' | 'page_scroll' | 'page_eval' | 'page_press' | 'page_wait' | 'page_navigate' | 'page_upload' | 'page_snapshot' | 'page_screenshot' | 'page_selected_element' | 'page_frames' | 'set_device_emulation' | 'set_timezone' | 'record_start' | 'record_stop' | 'request_domain_permission' | 'get_user_info' | 'browser_list' | 'browser_launch' | 'browser_close' | 'run_actions';
+export declare const COMMAND_MAP: Map<string, CommandDef>;