@mearl/setup 2.4.0 → 2.5.1

package/README.md

@@ -1,11 +1,21 @@
 # @mearl/setup
 
-Mearl 环境的一次性安装、更新与卸载工具。无需先全局安装 setup：
+Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
 npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
 ```
 
+配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
+重复执行会更新现有 Key，并保留 `~/.mearl/.env` 中的其他配置：
+
+```bash
+npx @mearl/setup agentbay
+```
+
+无交互环境可使用 `--stdin` 或 `--key-file <path>`。为避免 Key 进入 shell history 和
+进程参数，不接受把 Key 直接写在命令行中。
+
 ## 行为
 
 - `install` 未指定环境时默认 `--local`。
@@ -14,6 +24,8 @@ npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
   多个已安装环境。
 - 显式传入 `--local`、`--cloud` 或 `--mcp` 时只处理指定环境。
 - 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
+- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/cloud-client`：首次安装后启动
+  Server，更新后仅在 Server 原本运行时重启，卸载前停止。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
@@ -59,6 +71,12 @@ npx @mearl/setup uninstall --local
 
 # 自动检测并无交互卸载
 npx @mearl/setup uninstall --yes
+
+# 配置或更新 AgentBay API Key
+npx @mearl/setup agentbay
+
+# 无交互配置（从权限受控的文件读取）
+npx @mearl/setup agentbay --key-file ./agentbay.key
 ```
 
 原有的 npm/npx 安装方式和各包 CLI 保持可用；setup 只是统一的便利入口。

package/dist/agentBay.d.ts

@@ -0,0 +1,23 @@
+export interface AgentBayConfigurationOptions {
+    envFile?: string;
+}
+export interface AgentBayConfigurationResult {
+    envFile: string;
+    updated: boolean;
+}
+export interface AgentBaySecretInput {
+    isRaw?: boolean;
+    isTTY?: boolean;
+    on(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+    pause(): unknown;
+    removeListener(event: 'data', listener: (chunk: Buffer | string) => void): unknown;
+    resume(): unknown;
+    setRawMode?(mode: boolean): unknown;
+}
+export interface AgentBaySecretOutput {
+    write(value: string): unknown;
+}
+export declare function readAgentBayApiKeyFile(file: string): string;
+export declare function readAgentBayApiKeyStdin(input?: NodeJS.ReadableStream): Promise<string>;
+export declare function promptAgentBayApiKey(input?: AgentBaySecretInput, output?: AgentBaySecretOutput): Promise<string>;
+export declare function configureAgentBayApiKey(apiKey: string, options?: AgentBayConfigurationOptions): AgentBayConfigurationResult;

package/dist/agentBay.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const AGENTBAY_ENV_KEY = 'AGENTBAY_KEY';
+const AGENTBAY_ENV_LINE = /^\s*(?:export\s+)?AGENTBAY_KEY\s*=/;
+function normalizeApiKey(apiKey) {
+    const value = apiKey.trim();
+    if (!value)
+        throw new Error('AgentBay API key is required.');
+    if (/[\r\n\0]/.test(value)) {
+        throw new Error('AgentBay API key must be a single-line value.');
+    }
+    return value;
+}
+export function readAgentBayApiKeyFile(file) {
+    const resolved = path.resolve(file);
+    return normalizeApiKey(fs.readFileSync(resolved, 'utf8'));
+}
+export async function readAgentBayApiKeyStdin(input = process.stdin) {
+    let value = '';
+    for await (const chunk of input)
+        value += chunk.toString();
+    return normalizeApiKey(value);
+}
+export function promptAgentBayApiKey(input = process.stdin, output = process.stderr) {
+    if (!input.isTTY || !input.setRawMode) {
+        return Promise.reject(new Error('A TTY is required to enter the AgentBay API key securely.'));
+    }
+    const setRawMode = input.setRawMode.bind(input);
+    return new Promise((resolvePrompt, rejectPrompt) => {
+        const wasRaw = input.isRaw === true;
+        let value = '';
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            input.removeListener('data', onData);
+            setRawMode(wasRaw);
+            input.pause();
+            output.write('\n');
+            if (error)
+                rejectPrompt(error);
+            else {
+                try {
+                    resolvePrompt(normalizeApiKey(value));
+                }
+                catch (validationError) {
+                    rejectPrompt(validationError instanceof Error ? validationError : new Error(String(validationError)));
+                }
+            }
+        };
+        const onData = (chunk) => {
+            for (const character of chunk.toString()) {
+                if (character === '\u0003') {
+                    finish(new Error('AgentBay API key input cancelled.'));
+                    return;
+                }
+                if (character === '\r' || character === '\n') {
+                    finish();
+                    return;
+                }
+                if (character === '\u007f' || character === '\b') {
+                    value = Array.from(value).slice(0, -1).join('');
+                    continue;
+                }
+                if (character >= ' ')
+                    value += character;
+            }
+        };
+        output.write('AgentBay API key: ');
+        setRawMode(true);
+        input.resume();
+        input.on('data', onData);
+    });
+}
+function updateEnvContent(content, apiKey) {
+    const newline = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content ? content.split(/\r?\n/) : [];
+    if (lines.at(-1) === '')
+        lines.pop();
+    const entry = `${AGENTBAY_ENV_KEY}=${apiKey}`;
+    const output = [];
+    let updated = false;
+    for (const line of lines) {
+        if (!AGENTBAY_ENV_LINE.test(line)) {
+            output.push(line);
+            continue;
+        }
+        if (!updated)
+            output.push(entry);
+        updated = true;
+    }
+    if (!updated)
+        output.push(entry);
+    return { content: `${output.join(newline)}${newline}`, updated };
+}
+export function configureAgentBayApiKey(apiKey, options = {}) {
+    const value = normalizeApiKey(apiKey);
+    const envFile = options.envFile ?? path.join(os.homedir(), '.mearl', '.env');
+    let current = '';
+    try {
+        current = fs.readFileSync(envFile, 'utf8');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const next = updateEnvContent(current, value);
+    fs.mkdirSync(path.dirname(envFile), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(envFile, next.content, { encoding: 'utf8', mode: 0o600 });
+    fs.chmodSync(envFile, 0o600);
+    return { envFile, updated: next.updated };
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -1,13 +1,45 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 export function parseSetupArgs(argv) {
     if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
-        return { help: true, skipSkill: false, yes: false };
+        return { agentBayReadStdin: false, help: true, skipSkill: false, yes: false };
     }
     const operation = argv[0];
+    if (operation === 'agentbay') {
+        if (argv.length === 1) {
+            return {
+                agentBayReadStdin: false,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        if (argv.length === 2 && argv[1] === '--stdin') {
+            return {
+                agentBayReadStdin: true,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        if (argv.length === 3 && argv[1] === '--key-file' && argv[2]?.trim()) {
+            return {
+                agentBayKeyFile: argv[2],
+                agentBayReadStdin: false,
+                help: false,
+                operation,
+                skipSkill: false,
+                yes: false,
+            };
+        }
+        throw new Error('Usage: npx @mearl/setup agentbay [--stdin | --key-file <path>]. API keys are not accepted as command-line arguments.');
+    }
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
@@ -51,23 +83,35 @@ export function parseSetupArgs(argv) {
     if (operation === 'uninstall' && targetLine) {
         throw new Error('--target-line is not available for uninstall');
     }
-    return { help: false, operation, profile, skipSkill, targetLine, yes };
+    return {
+        agentBayReadStdin: false,
+        help: false,
+        operation,
+        profile,
+        skipSkill,
+        targetLine,
+        yes,
+    };
 }
 function printHelp() {
     console.error(`Mearl Setup
 
 Usage:
   npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
+  npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
   install      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
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
-  --cloud      Manage @mearl/cloud-client
+  --cloud      Manage @mearl/cloud-server and @mearl/cloud-client
   --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
   --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
@@ -81,10 +125,11 @@ Examples:
   npx @mearl/setup install --yes
   npx @mearl/setup install --cloud
   npx @mearl/setup update
+  npx @mearl/setup agentbay
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
   npx @mearl/setup uninstall --local`);
 }
-export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true) {
+export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true, dependencies = {}) {
     let parsed;
     try {
         parsed = parseSetupArgs(argv);
@@ -98,6 +143,31 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         printHelp();
         return 0;
     }
+    if (parsed.operation === 'agentbay') {
+        try {
+            const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;
+            let apiKey;
+            if (parsed.agentBayKeyFile) {
+                apiKey = (dependencies.readAgentBayKeyFile ?? readAgentBayApiKeyFile)(parsed.agentBayKeyFile);
+            }
+            else if (parsed.agentBayReadStdin) {
+                apiKey = await (dependencies.readAgentBayKeyStdin ?? readAgentBayApiKeyStdin)();
+            }
+            else {
+                if (!interactiveTerminal) {
+                    throw new Error('Interactive input is unavailable. Re-run with --stdin or --key-file <path>.');
+                }
+                apiKey = await (dependencies.promptAgentBayKey ?? promptAgentBayApiKey)();
+            }
+            const result = configureAgentBay(apiKey);
+            console.error(`AgentBay API key saved to ${result.envFile}.`);
+            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;

package/dist/index.d.ts

@@ -1,4 +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 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,4 +1,5 @@
 export { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
+export { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.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.js

@@ -28,10 +28,10 @@ function siblingExecutable(anchor, name, existsSync) {
     }
     return null;
 }
-async function runLifecycleCommand(runner, command, args, env, label, writeLine) {
+async function runLifecycleCommand(runner, command, args, env, label, writeLine, capture = false) {
     try {
         return await runner(command, args, {
-            capture: false,
+            capture,
             env: prependCommandPath(command, env),
         });
     }
@@ -59,6 +59,31 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
         executable = siblingExecutable(detected.executable, 'mearl-mcp-configure', existsSync);
         args = ['--skip-mcp', '--global-install'];
     }
+    else if (profile === 'cloud') {
+        executable = siblingExecutable(detected.executable, 'mearl-cloud-server', existsSync);
+        if (!executable) {
+            writeLine(`Hook: ${profile} ${operation} command was not found.`);
+            return false;
+        }
+        if (operation === 'uninstall') {
+            args = ['stop'];
+        }
+        else {
+            const status = await runLifecycleCommand(runner, executable, ['status'], env, 'Hook: cloud status', writeLine, true);
+            if (!status)
+                return false;
+            if (status.code !== 0) {
+                writeLine(`Hook: cloud status failed (exit ${status.code}).`);
+                return false;
+            }
+            const running = /\[CloudServer\]\s+Status:\s+running\b/.test(status.stdout);
+            if (operation === 'update' && !running) {
+                writeLine('Hook: cloud update skipped because cloud-server is not running.');
+                return true;
+            }
+            args = [running ? 'restart' : 'start'];
+        }
+    }
     else {
         return true;
     }
@@ -174,7 +199,8 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             packagesOk = false;
             continue;
         }
-        if (options.operation !== 'uninstall' && (profile === 'local' || profile === 'mcp')) {
+        if (options.operation !== 'uninstall' &&
+            (profile === 'local' || profile === 'cloud' || profile === 'mcp')) {
             const refreshed = detectPackage(config.anchorPackage, config.anchorBins, {
                 env: prependCommandPath(command.command, env),
             }) ?? current;

package/dist/profiles.js

@@ -13,7 +13,7 @@ export const MEARL_PROFILES = {
         label: 'cloud agent',
         anchorPackage: '@mearl/cloud-client',
         anchorBins: ['mearl-cloud'],
-        packages: ['@mearl/cloud-client'],
+        packages: ['@mearl/cloud-server', '@mearl/cloud-client'],
         usesSkill: true,
     },
     mcp: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mearl/setup",
-  "version": "2.4.0",
-  "description": "One-shot installer, updater, and uninstaller for Mearl environments",
+  "version": "2.5.1",
+  "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,10 @@
       "types": "./dist/nativeHost.d.ts",
       "import": "./dist/nativeHost.js"
     },
+    "./agentbay": {
+      "types": "./dist/agentBay.d.ts",
+      "import": "./dist/agentBay.js"
+    },
     "./version": {
       "types": "./dist/version.d.ts",
       "import": "./dist/version.js"