@mearl/setup 2.8.2 → 2.9.1

package/README.md

@@ -3,9 +3,9 @@
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
-npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
-npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
-npx @mearl/setup extension [--force] [--yes]
+npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup extension [--full] [--force]
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -51,6 +51,10 @@ npx @mearl/setup agentbay
   加载；后续更新由 `mearl check --local --json` 确认当前扩展仍来自 setup 管理目录后，直接替换
   文件并通过 Native Host 触发扩展 reload。固定目录和 manifest 中的 `key` 保证扩展 ID
   与浏览器存储保持稳定。
+- `extension --full` 会先安装或更新扩展，再复用 local profile 安装
+  `@mearl/client`、安装并初始化 `@mearl/native-host`，最后安装全局 Mearl Skill。
+  两部分都会尽量执行；任一步失败时命令返回非零退出码，已安装的部分会保留。它不安装
+  cloud 或 MCP 环境。
 - 下载前会通过 CDP 检查同 ID 插件的来源。未安装，或来源为固定目录中的 `UNPACKED`
   插件时可继续；Chrome 商店、企业策略或其他本地目录安装的版本默认保持不变。只有显式
   传入 `--force` 才会接管并替换这些版本。
@@ -61,6 +65,12 @@ npx @mearl/setup agentbay
 npx @mearl/setup extension
 ```
 
+首次使用时可一次安装完整的本地浏览器环境：
+
+```bash
+npx @mearl/setup extension --full
+```
+
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。无 TTY
@@ -127,6 +137,9 @@ npx @mearl/setup update
 # 独立安装或更新到最新浏览器扩展
 npx @mearl/setup extension
 
+# 安装完整本地环境（client、Native Host、Skill 和扩展）
+npx @mearl/setup extension --full
+
 # 只卸载本地环境
 npx @mearl/setup uninstall --local
 

package/dist/browserExtension.js

@@ -488,11 +488,12 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
     const setupManagedAtStart = setupManagedBrowserIds.length > 0;
     let cdpSession;
     const inspectOnce = async () => {
-        if (!useSharedCdpSession)
-            return inspectInstallation(chromeUserDataDirectory);
+        if (!useSharedCdpSession) {
+            return options.force ? null : inspectInstallation(chromeUserDataDirectory);
+        }
         const candidate = await connectCdp(chromeUserDataDirectory);
         try {
-            const installed = await candidate.inspectInstallation();
+            const installed = options.force ? null : await candidate.inspectInstallation();
             cdpSession?.close();
             cdpSession = candidate;
             return installed;

package/dist/cli.d.ts

@@ -9,6 +9,7 @@ interface ParsedArgs {
     agentBayReadStdin: boolean;
     cloudMode?: 'websocket' | 'qoder';
     force?: boolean;
+    full?: boolean;
     help: boolean;
     operation?: MearlLifecycleOperation | 'agentbay' | 'extension';
     profiles?: MearlProfile[];

package/dist/cli.js

@@ -1,132 +1,142 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
+import { Command, CommanderError } from 'commander';
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
-export function parseSetupArgs(argv) {
-    if (argv.includes('--help') || argv.includes('-h')) {
-        return { agentBayReadStdin: false, help: true, skipSkill: false, yes: false };
+const baseParsedArgs = () => ({
+    agentBayReadStdin: false,
+    help: false,
+    skipSkill: false,
+    yes: false,
+});
+function commanderError(error) {
+    const message = error.message.replace(/^error:\s*/i, '');
+    if (error.code === 'commander.unknownCommand') {
+        return new Error(message.replace(/^unknown command/i, 'Unknown operation'));
     }
-    if (argv.includes('--version') || argv.includes('-v')) {
-        return {
-            agentBayReadStdin: false,
-            help: false,
-            skipSkill: false,
-            version: true,
-            yes: false,
-        };
+    if (error.code === 'commander.unknownOption') {
+        return new Error(message.replace(/^unknown option/i, 'Unknown option'));
     }
-    const firstArg = argv[0];
-    const operation = firstArg === undefined || firstArg.startsWith('-') ? 'install' : firstArg;
-    const optionStart = operation === firstArg ? 1 : 0;
-    if (operation === 'agentbay') {
-        if (argv.length === 1) {
-            return {
-                agentBayReadStdin: false,
-                help: false,
+    return new Error(message);
+}
+export function parseSetupArgs(argv) {
+    let parsed;
+    const program = new Command()
+        .name('mearl-setup')
+        .version(SETUP_VERSION, '-v, --version')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } });
+    const addLifecycleCommand = (operation) => {
+        const command = new Command(operation)
+            .exitOverride()
+            .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+            .option('--local')
+            .option('--cloud')
+            .option('--qoder-cloud')
+            .option('--mcp')
+            .option('--target-line <major.minor.x>')
+            .option('--skip-skill')
+            .option('-y, --yes')
+            .option('--non-interactive')
+            .action(() => {
+            const options = command.opts();
+            if (options.cloud && options.qoderCloud) {
+                throw new Error('--cloud and --qoder-cloud cannot be used together');
+            }
+            if (options.targetLine && !isMearlReleaseLine(options.targetLine)) {
+                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
+            }
+            if (operation === 'uninstall' && options.targetLine) {
+                throw new Error('--target-line is not available for uninstall');
+            }
+            const profiles = [];
+            if (options.local)
+                profiles.push('local');
+            if (options.cloud || options.qoderCloud)
+                profiles.push('cloud');
+            if (options.mcp)
+                profiles.push('mcp');
+            parsed = {
+                ...baseParsedArgs(),
                 operation,
-                skipSkill: false,
-                yes: false,
+                ...(options.cloud || options.qoderCloud
+                    ? { cloudMode: options.qoderCloud ? 'qoder' : 'websocket' }
+                    : {}),
+                ...(profiles.length > 0 ? { profiles } : {}),
+                skipSkill: options.skipSkill === true,
+                targetLine: options.targetLine,
+                yes: options.yes === true || options.nonInteractive === true,
             };
+        });
+        program.addCommand(command);
+    };
+    addLifecycleCommand('install');
+    addLifecycleCommand('update');
+    addLifecycleCommand('uninstall');
+    const extension = new Command('extension')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+        .option('--full')
+        .option('--force')
+        .option('-y, --yes')
+        .option('--non-interactive')
+        .action(() => {
+        const options = extension.opts();
+        parsed = {
+            ...baseParsedArgs(),
+            ...(options.force ? { force: true } : {}),
+            ...(options.full ? { full: true } : {}),
+            operation: 'extension',
+            yes: options.yes === true || options.nonInteractive === true,
+        };
+    });
+    program.addCommand(extension);
+    const agentbay = new Command('agentbay')
+        .exitOverride()
+        .configureOutput({ writeErr: () => { }, writeOut: () => { } })
+        .argument('[api-key]')
+        .option('--stdin')
+        .option('--key-file <path>')
+        .action((apiKey) => {
+        const options = agentbay.opts();
+        if (apiKey) {
+            throw new Error('API keys are not accepted as command-line arguments');
         }
-        if (argv.length === 2 && argv[1] === '--stdin') {
-            return {
-                agentBayReadStdin: true,
-                help: false,
-                operation,
-                skipSkill: false,
-                yes: false,
-            };
+        if (options.stdin && options.keyFile) {
+            throw new Error('--stdin and --key-file cannot be used together');
         }
-        if (argv.length === 3 && argv[1] === '--key-file' && argv[2]?.trim()) {
-            return {
-                agentBayKeyFile: argv[2],
-                agentBayReadStdin: false,
-                help: false,
-                operation,
-                skipSkill: false,
-                yes: false,
-            };
+        if (options.keyFile !== undefined && !options.keyFile.trim()) {
+            throw new Error('--key-file requires a non-empty path');
         }
-        throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
-    }
-    if (operation === 'extension') {
-        const accepted = new Set(['--force', '--yes', '-y', '--non-interactive']);
-        const confirmationFlags = new Set(['--yes', '-y', '--non-interactive']);
-        const unknown = argv.slice(1).find(arg => !accepted.has(arg));
-        if (unknown)
-            throw new Error(`Unknown option: ${unknown}`);
-        return {
-            agentBayReadStdin: false,
-            help: false,
-            ...(argv.slice(1).includes('--force') ? { force: true } : {}),
-            operation,
-            skipSkill: false,
-            yes: argv.slice(1).some(arg => confirmationFlags.has(arg)),
+        parsed = {
+            ...baseParsedArgs(),
+            ...(options.keyFile ? { agentBayKeyFile: options.keyFile } : {}),
+            agentBayReadStdin: options.stdin === true,
+            operation: 'agentbay',
         };
+    });
+    program.addCommand(agentbay);
+    const normalizedArgv = argv[0] === undefined || argv[0].startsWith('-') ? ['install', ...argv] : argv;
+    try {
+        program.parse(['node', 'mearl-setup', ...normalizedArgv]);
     }
-    if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
-        throw new Error(`Unknown operation: ${operation}`);
-    }
-    const profiles = [];
-    let skipSkill = false;
-    let targetLine;
-    let yes = false;
-    let cloudMode;
-    for (let index = optionStart; index < argv.length; index += 1) {
-        const arg = argv[index];
-        if (arg === '--yes' || arg === '-y' || arg === '--non-interactive') {
-            yes = true;
-            continue;
-        }
-        if (arg === '--skip-skill') {
-            skipSkill = true;
-            continue;
-        }
-        if (arg === '--target-line') {
-            const value = argv[index + 1];
-            if (!isMearlReleaseLine(value)) {
-                throw new Error('--target-line requires a valid Mearl release line such as 2.3.x');
-            }
-            targetLine = value;
-            index += 1;
-            continue;
-        }
-        if (arg === '--cloud' || arg === '--qoder-cloud') {
-            const requestedMode = arg === '--qoder-cloud' ? 'qoder' : 'websocket';
-            if (cloudMode && cloudMode !== requestedMode) {
-                throw new Error('--cloud and --qoder-cloud cannot be used together');
-            }
-            cloudMode = requestedMode;
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.code === 'commander.helpDisplayed')
+                return { ...baseParsedArgs(), help: true };
+            if (error.code === 'commander.version')
+                return { ...baseParsedArgs(), version: true };
+            throw commanderError(error);
         }
-        const candidate = arg === '--local'
-            ? 'local'
-            : arg === '--cloud' || arg === '--qoder-cloud'
-                ? 'cloud'
-                : arg === '--mcp'
-                    ? 'mcp'
-                    : undefined;
-        if (!candidate)
-            throw new Error(`Unknown option: ${arg}`);
-        if (!profiles.includes(candidate))
-            profiles.push(candidate);
+        throw error;
     }
-    if (operation === 'uninstall' && targetLine) {
-        throw new Error('--target-line is not available for uninstall');
-    }
-    return {
-        agentBayReadStdin: false,
-        help: false,
-        operation,
-        ...(cloudMode ? { cloudMode } : {}),
-        ...(profiles.length > 0 ? { profiles } : {}),
-        skipSkill,
-        targetLine,
-        yes,
-    };
+    if (!parsed)
+        throw new Error('No setup operation was selected');
+    return parsed;
 }
 function printHelp(toError = false) {
     const output = `Mearl Setup v${SETUP_VERSION}
@@ -134,14 +144,14 @@ function printHelp(toError = false) {
 Usage:
   npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
   npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
-  npx @mearl/setup extension [--force] [--yes]
+  npx @mearl/setup extension [--full] [--force] [--yes]
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
   install      Default command; defaults to --local when no environment is specified
   update       Auto-detects installed environments from the current PATH
   uninstall    Auto-detects installed environments and asks for confirmation
-  extension    Download the latest browser extension and install or reload it through CDP
+  extension    Install or update the browser extension; --full also installs the local environment
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
 
 Options:
@@ -155,6 +165,7 @@ Options:
   --target-line <major.minor.x>
                Install the latest packages from one release line, such as 2.3.x
   --skip-skill Keep the independently managed Mearl Skill unchanged
+  --full       Also install @mearl/client, @mearl/native-host, and the Mearl Skill
   --force      Replace an existing store, managed, or other local Mearl extension
   --yes, -y    Run without prompts and accept detected defaults
   --non-interactive
@@ -171,6 +182,7 @@ Examples:
   npx @mearl/setup --local --cloud
   npx @mearl/setup update
   npx @mearl/setup extension
+  npx @mearl/setup extension --full
   npx @mearl/setup agentbay
   npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
@@ -228,6 +240,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
             return 2;
         }
+        let extensionInstalled = false;
         try {
             const result = await (dependencies.installBrowserExtension ?? installMearlBrowserExtension)({
                 force: parsed.force,
@@ -240,20 +253,35 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
                     : `Browser extension v${result.version} installed or reloaded through CDP.`);
                 console.error(`Extension ID: ${result.extensionId}`);
                 console.error(`Extension directory: ${result.path}`);
-                return 0;
+                extensionInstalled = true;
+            }
+            else {
+                console.error(result.filesUpdated
+                    ? `Browser extension v${result.version} files were updated, but the extension was not reloaded.`
+                    : `Browser extension v${result.version} was not installed.`);
+                if (result.cdpError)
+                    console.error(`CDP installation pending: ${result.cdpError}`);
+                console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
             }
-            console.error(result.filesUpdated
-                ? `Browser extension v${result.version} files were updated, but the extension was not reloaded.`
-                : `Browser extension v${result.version} was not installed.`);
-            if (result.cdpError)
-                console.error(`CDP installation pending: ${result.cdpError}`);
-            console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
-            return 1;
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));
-            return 1;
         }
+        if (!parsed.full)
+            return extensionInstalled ? 0 : 1;
+        let localInstalled = false;
+        try {
+            localInstalled = await (dependencies.runLifecycle ?? runMearlLifecycle)({
+                operation: 'install',
+                profiles: ['local'],
+                skipSkill: false,
+                yes: parsed.yes,
+            });
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+        }
+        return extensionInstalled && localInstalled ? 0 : 1;
     }
     if (!interactiveTerminal && !parsed.yes && parsed.operation !== 'update') {
         console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.8.2",
+  "version": "2.9.1",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -56,15 +56,16 @@
   ],
   "license": "ISC",
   "engines": {
-    "node": ">=18"
+    "node": ">=22.12.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.8.2"
+    "@mearl/client": "2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",