@mearl/setup 2.7.1 → 2.7.2

package/README.md

@@ -3,8 +3,8 @@
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
-npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
-npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]
+npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
+npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -17,9 +17,10 @@ npx @mearl/setup agentbay
 无交互环境可使用 `--stdin` 或 `--key-file <path>`。为避免 Key 进入 shell history 和
 进程参数，不接受把 Key 直接写在命令行中。
 
-Qoder Cloud Agent 仅在常规云连接失败、Mearl Skill 进入 Qoder 异常接管分支时使用
-`npx @mearl/setup qoder --yes` 生成一次性配对指令。它不安装额外隧道，也不会把 Qoder
-PAT 写入配对 URL；正常安装和连接流程无需执行该命令。
+在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup --qoder-cloud --yes` 选择 Qoder
+配对模式。它与 `--cloud` 安装同一套 cloud-server、client 和 Skill，只把 cloud-server
+模式记录为 Qoder；`mearl-cloud-server` 的命令交互保持不变，`start` 和 `restart` 输出新的
+配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。
 
 ## 行为
 
@@ -30,10 +31,12 @@ PAT 写入配对 URL；正常安装和连接流程无需执行该命令。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
   `mearl-native-host`、`mearl-cloud-server`、`mearl-mcp-server` 自动检测，可同时处理
   多个已安装环境。
-- `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境。
+- `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境；
+  `--qoder-cloud` 选择相同的 cloud 环境并记录 Qoder 配对模式，不能与 `--cloud` 同时使用。
 - 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
-- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：首次安装后启动
-  Server，更新后仅在 Server 原本运行时重启，卸载前停止。
+- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：WebSocket 模式首次安装后
+  启动 Server，更新后仅在 Server 原本运行时重启；Qoder 模式由相同的 `start` 命令生成
+  新配对但不起服务；卸载前均调用 `stop`。
 - local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
 - 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。

package/dist/cli.d.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin } from './agentBay.js';
-import { type MearlLifecycleOperation } from './lifecycle.js';
+import { runMearlLifecycle, type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
-import { createQoderPairingInfo } from './qoder.js';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
     agentBayReadStdin: boolean;
+    cloudMode?: 'websocket' | 'qoder';
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay' | 'qoder';
+    operation?: MearlLifecycleOperation | 'agentbay';
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -20,7 +20,7 @@ export interface SetupCliDependencies {
     promptAgentBayKey?: typeof promptAgentBayApiKey;
     readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
     readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
-    createQoderPairing?: typeof createQoderPairingInfo;
+    runLifecycle?: typeof runMearlLifecycle;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
 export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;

package/dist/cli.js

@@ -2,7 +2,6 @@
 import { createRequire } from 'node:module';
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { runMearlLifecycle } from './lifecycle.js';
-import { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
 import { isMearlReleaseLine } from './version.js';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
@@ -53,20 +52,6 @@ export function parseSetupArgs(argv) {
         }
         throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
     }
-    if (operation === 'qoder') {
-        const options = argv.slice(1);
-        const allowed = new Set(['--yes', '-y', '--non-interactive']);
-        if (options.some(option => !allowed.has(option))) {
-            throw new Error('Usage: npx @mearl/setup qoder [--yes]');
-        }
-        return {
-            agentBayReadStdin: false,
-            help: false,
-            operation,
-            skipSkill: false,
-            yes: options.length > 0,
-        };
-    }
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
@@ -74,6 +59,7 @@ export function parseSetupArgs(argv) {
     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') {
@@ -93,9 +79,16 @@ export function parseSetupArgs(argv) {
             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;
+        }
         const candidate = arg === '--local'
             ? 'local'
-            : arg === '--cloud'
+            : arg === '--cloud' || arg === '--qoder-cloud'
                 ? 'cloud'
                 : arg === '--mcp'
                     ? 'mcp'
@@ -112,6 +105,7 @@ export function parseSetupArgs(argv) {
         agentBayReadStdin: false,
         help: false,
         operation,
+        ...(cloudMode ? { cloudMode } : {}),
         ...(profiles.length > 0 ? { profiles } : {}),
         skipSkill,
         targetLine,
@@ -122,21 +116,21 @@ function printHelp(toError = false) {
     const output = `Mearl Setup v${SETUP_VERSION}
 
 Usage:
-  npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
-  npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]
+  npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
+  npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
-  npx @mearl/setup qoder [--yes]
 
 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
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
-  qoder        Create a Qoder client-side tool pairing request for troubleshooting
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
-  --cloud      Manage @mearl/cloud-server and the unified @mearl/client
+  --cloud      Manage cloud packages in WebSocket server mode
+  --qoder-cloud
+               Manage the same cloud packages in Qoder pairing mode
   --mcp        Manage @mearl/mcp-server and its configuration
   --stdin      Read the AgentBay API key from standard input
   --key-file   Read the AgentBay API key from a local file
@@ -158,7 +152,7 @@ Examples:
   npx @mearl/setup --local --cloud
   npx @mearl/setup update
   npx @mearl/setup agentbay
-  npx @mearl/setup qoder --yes
+  npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
   npx @mearl/setup uninstall --local`;
     if (toError)
@@ -209,25 +203,15 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             return 1;
         }
     }
-    if (parsed.operation === 'qoder') {
-        try {
-            const pairing = (dependencies.createQoderPairing ?? createQoderPairingInfo)();
-            console.log(formatQoderPairingOutput(pairing));
-            return 0;
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            return 1;
-        }
-    }
     if (!interactiveTerminal && !parsed.yes && parsed.operation !== 'update') {
         console.error('Non-interactive input detected. Re-run with --yes or --non-interactive.');
         return 2;
     }
     try {
-        const ok = await runMearlLifecycle({
+        const ok = await (dependencies.runLifecycle ?? runMearlLifecycle)({
             operation: parsed.operation,
             profiles: parsed.profiles,
+            cloudMode: parsed.cloudMode,
             skipSkill: parsed.skipSkill,
             targetLine: parsed.targetLine,
             yes: parsed.yes,

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 export type { AgentBayConfigurationOptions, AgentBayConfigurationResult, AgentBaySecretInput, AgentBaySecretOutput, } from './agentBay.js';
-export { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
-export type { QoderPairingInfo, QoderPairingOptions } from './qoder.js';
 export type { DetectedGlobalPackage, GlobalPackageCommand, GlobalPackageManager, PackageManagerInstallation, PackageOperation, PackageDetectionOptions, } from './packageManager.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export type { MearlLifecycleDependencies, MearlLifecycleOperation, MearlLifecycleOptions, } from './lifecycle.js';

package/dist/index.js

@@ -1,6 +1,5 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
-export { createQoderPairingInfo, formatQoderPairingOutput } from './qoder.js';
 export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';

package/dist/lifecycle.d.ts

@@ -6,6 +6,7 @@ import { type CommandRunner } from './process.js';
 export type MearlLifecycleOperation = 'install' | 'update' | 'uninstall';
 export interface MearlLifecycleOptions {
     operation: MearlLifecycleOperation;
+    cloudMode?: 'websocket' | 'qoder';
     /** @deprecated Use profiles when selecting one or more composable environments. */
     profile?: MearlProfile;
     profiles?: MearlProfile[];

package/dist/lifecycle.js

@@ -56,9 +56,10 @@ async function runPackageOperation(installation, operation, packages, targetLine
     }
     return { command, ok: true };
 }
-async function runHook(profile, operation, detected, runner, existsSync, env, writeLine, yes) {
+async function runHook(profile, operation, detected, runner, existsSync, env, writeLine, yes, cloudMode) {
     let executable;
     let args;
+    let hookEnv = env;
     if (profile === 'local' && operation !== 'uninstall') {
         executable = detected.executable;
         args = ['--init', '--mode', 'skills'];
@@ -81,11 +82,14 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
             writeLine(`Hook: ${profile} ${operation} command was not found.`);
             return false;
         }
+        const requestedMode = operation === 'uninstall' ? 'websocket' : cloudMode;
+        const commandEnv = requestedMode ? { ...env, MEARL_CLOUD_MODE: requestedMode } : env;
+        hookEnv = commandEnv;
         if (operation === 'uninstall') {
             args = ['stop'];
         }
         else {
-            const status = await runLifecycleCommand(runner, executable, ['status'], env, 'Hook: cloud status', writeLine, true);
+            const status = await runLifecycleCommand(runner, executable, ['status'], commandEnv, 'Hook: cloud status', writeLine, true);
             if (!status)
                 return false;
             if (status.code !== 0) {
@@ -93,11 +97,12 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
                 return false;
             }
             const running = /\[CloudServer\]\s+Status:\s+running\b/.test(status.stdout);
-            if (operation === 'update' && !running) {
+            const qoderMode = cloudMode === 'qoder' || /\[CloudServer\]\s+Mode:\s+qoder\b/.test(status.stdout);
+            if (operation === 'update' && !running && !qoderMode) {
                 writeLine('Hook: cloud update skipped because cloud-server is not running.');
                 return true;
             }
-            args = [running ? 'restart' : 'start'];
+            args = [running && !qoderMode ? 'restart' : 'start'];
         }
     }
     else {
@@ -107,7 +112,7 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
         writeLine(`Hook: ${profile} ${operation} command was not found.`);
         return false;
     }
-    const result = await runLifecycleCommand(runner, executable, args, env, `Hook: ${profile} ${operation}`, writeLine);
+    const result = await runLifecycleCommand(runner, executable, args, hookEnv, `Hook: ${profile} ${operation}`, writeLine);
     if (!result)
         return false;
     if (result.code !== 0) {
@@ -233,7 +238,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
         if (options.operation === 'uninstall' &&
-            !(await runHook(profile, options.operation, current, runner, existsSync, env, writeLine, options.yes === true))) {
+            !(await runHook(profile, options.operation, current, runner, existsSync, env, writeLine, options.yes === true, options.cloudMode))) {
             packagesOk = false;
             continue;
         }
@@ -253,7 +258,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                 env: prependCommandPath(packageResult.command.command, env),
             }) ?? current;
             if (!refreshed ||
-                !(await runHook(profile, options.operation, refreshed, runner, existsSync, env, writeLine, options.yes === true))) {
+                !(await runHook(profile, options.operation, refreshed, runner, existsSync, env, writeLine, options.yes === true, options.cloudMode))) {
                 packagesOk = false;
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.7.1",
+  "version": "2.7.2",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -30,10 +30,6 @@
       "types": "./dist/agentBay.d.ts",
       "import": "./dist/agentBay.js"
     },
-    "./qoder": {
-      "types": "./dist/qoder.d.ts",
-      "import": "./dist/qoder.js"
-    },
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js"

package/dist/qoder.d.ts

@@ -1,18 +0,0 @@
-export interface QoderPairingInfo {
-    pairingCode: string;
-    createdAt: number;
-    connectorUrl: string;
-    toolInput: {
-        action: 'pair';
-        payload: {
-            code: string;
-        };
-    };
-}
-export interface QoderPairingOptions {
-    now?: () => number;
-    createCode?: () => string;
-}
-/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
-export declare function createQoderPairingInfo(options?: QoderPairingOptions): QoderPairingInfo;
-export declare function formatQoderPairingOutput(info: QoderPairingInfo): string;

package/dist/qoder.js

@@ -1,32 +0,0 @@
-import { randomBytes } from 'node:crypto';
-/** Create a short-lived correlation handle without embedding Qoder credentials in the URL. */
-export function createQoderPairingInfo(options = {}) {
-    const pairingCode = (options.createCode ?? (() => randomBytes(24).toString('base64url')))();
-    if (!/^[A-Za-z0-9_-]{16,128}$/.test(pairingCode)) {
-        throw new Error('Qoder pairing code must be 16-128 URL-safe characters');
-    }
-    const createdAt = (options.now ?? Date.now)();
-    if (!Number.isSafeInteger(createdAt) ||
-        createdAt < 1_000_000_000_000 ||
-        createdAt > 9_999_999_999_999) {
-        throw new Error('Qoder pairing timestamp must be a 13-digit epoch millisecond value');
-    }
-    return {
-        pairingCode,
-        createdAt,
-        connectorUrl: `qoder://pair/${pairingCode}?created=${createdAt}`,
-        toolInput: { action: 'pair', payload: { code: pairingCode } },
-    };
-}
-export function formatQoderPairingOutput(info) {
-    const connectorCommand = `npx @mearl/cloud-connector "${info.connectorUrl}"`;
-    return `[Qoder] Mearl local-browser pairing is ready.
-
-Show the user this command and ask them to run it on the computer that owns the browser:
-  ${connectorCommand}
-
-Then immediately invoke the Qoder client-side custom tool named "mearl" with this input:
-  ${JSON.stringify(info.toolInput)}
-
-The connector resolves QODER_PERSONAL_ACCESS_TOKEN from the local environment, ~/.mearl/.env, or supported local credential storage. Never add the PAT to the pairing URL.`;
-}