@actiondock/cli 2.6.0 → 2.8.0

package/dist/renderer.js

@@ -1,3 +1,4 @@
+import { formatActionDetail, } from "@actiondock/core/project";
 import { formatError } from "./errors.js";
 /**
  * 构造标准成功结果信封。
@@ -254,27 +255,11 @@ export function renderActionList(items, title = "Actions", isFallback = false, i
     return lines.join("\n");
 }
 /**
- * 格式化渲染 Action 详情。
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
  */
 export function renderActionDetail(action) {
-    const lines = [];
-    lines.push(`Action:      ${action.id}`);
-    if (action.packageId) {
-        const rootDesc = action.projectRoot ? ` (${action.projectRoot})` : "";
-        lines.push(`Package:     ${action.packageId}${rootDesc}`);
-    }
-    if (action.description) {
-        lines.push(`Description: ${action.description}`);
-    }
-    if (action.inputSchema) {
-        lines.push("\nInput Schema:");
-        lines.push(JSON.stringify(action.inputSchema, null, 2));
-    }
-    if (action.outputSchema) {
-        lines.push("\nOutput Schema:");
-        lines.push(JSON.stringify(action.outputSchema, null, 2));
-    }
-    return lines.join("\n");
+    return formatActionDetail(action);
 }
 /**
  * 格式化渲染 Action 校验结果。

package/dist/services/config-merge.d.ts

@@ -1,4 +1,5 @@
-import { type ActionDockTarget, type ConfigItemDefinition } from "@actiondock/core";
+import { type ConfigItemDefinition } from "@actiondock/core/project";
+import { type ActionDockService } from "@actiondock/core";
 /**
  * 配置合并视图条目：跨作用域合并后的键值展示结构。
  * source 标签语义：project（包级持久化）> global（全局持久化）> env（环境变量）> default（声明默认值）。
@@ -19,10 +20,10 @@ export interface MergedConfigEntry {
  * @param key 配置键名
  * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
  * @param declaredItem 工程声明的配置项定义
- * @param target 已创建的 Target 门面实例
+ * @param service 已创建的 Service 服务实例
  * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
  */
-export declare function resolveMergedConfigEntry(key: string, packageId: string, declaredItem: ConfigItemDefinition | undefined, target: ActionDockTarget, reveal: boolean): Promise<{
+export declare function resolveMergedConfigEntry(key: string, packageId: string, declaredItem: ConfigItemDefinition | undefined, service: ActionDockService, reveal: boolean): Promise<{
     value: unknown;
     source: MergedConfigEntry["source"];
     secret: boolean;
@@ -35,7 +36,7 @@ export declare function resolveMergedConfigEntry(key: string, packageId: string,
  * 消除 config get 与 config list 两命令间的合并实现差异。
  *
  * @param root 工程根目录
- * @param target 已创建的 Target 门面实例
+ * @param service 已创建的 Service 服务实例
  * @param reveal 是否揭示敏感值明文
  */
-export declare function buildMergedConfigEntries(root: string, target: ActionDockTarget, reveal: boolean): Promise<MergedConfigEntry[]>;
+export declare function buildMergedConfigEntries(root: string, service: ActionDockService, reveal: boolean): Promise<MergedConfigEntry[]>;

package/dist/services/config-merge.js

@@ -1,4 +1,6 @@
-import { isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue, } from "@actiondock/core";
+import { isSecretConfigKey, maskSecretValue, } from "@actiondock/core/project";
+import { loadProjectConfig, } from "@actiondock/core";
+import { resolveEnvValue, } from "@actiondock/core/profile";
 /**
  * 解析单个配置键的合并视图（项目包级 > 全局持久化 > 环境变量 > 声明默认值）。
  *
@@ -8,11 +10,11 @@ import { isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue,
  * @param key 配置键名
  * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
  * @param declaredItem 工程声明的配置项定义
- * @param target 已创建的 Target 门面实例
+ * @param service 已创建的 Service 服务实例
  * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
  */
-export async function resolveMergedConfigEntry(key, packageId, declaredItem, target, reveal) {
-    const confView = await target.getConfig(packageId, key);
+export async function resolveMergedConfigEntry(key, packageId, declaredItem, service, reveal) {
+    const confView = await service.management?.config.get(packageId, key);
     const envResolved = resolveEnvValue(key, declaredItem, packageId);
     let rawValue;
     let source;
@@ -40,14 +42,14 @@ export async function resolveMergedConfigEntry(key, packageId, declaredItem, tar
  * 消除 config get 与 config list 两命令间的合并实现差异。
  *
  * @param root 工程根目录
- * @param target 已创建的 Target 门面实例
+ * @param service 已创建的 Service 服务实例
  * @param reveal 是否揭示敏感值明文
  */
-export async function buildMergedConfigEntries(root, target, reveal) {
+export async function buildMergedConfigEntries(root, service, reveal) {
     const projConfig = loadProjectConfig(root);
     const declared = projConfig.config || {};
-    const projectConfigList = await target.listConfig(projConfig.id);
-    const globalConfigList = await target.listConfig("global");
+    const projectConfigList = (await service.management?.config.list(projConfig.id)) ?? [];
+    const globalConfigList = (await service.management?.config.list("global")) ?? [];
     const projectConfigMap = new Map(projectConfigList.map((c) => [c.key, c]));
     const globalConfigMap = new Map(globalConfigList.map((c) => [c.key, c]));
     const allKeys = new Set([

package/dist/services/inspect.js

@@ -1,5 +1,7 @@
 import { existsSync } from "node:fs";
-import { findProjectRoot, listLinkedPackages, loadManifest, loadPlaybooks, loadProjectConfig, } from "@actiondock/core";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { listLinkedPackages, } from "@actiondock/core/registry";
+import { loadManifest, loadPlaybooks, } from "@actiondock/core/project";
 /**
  * 装配单个工程的详情自省信息（清单、动作映射与 Playbook 映射）。
  *

package/dist/standalone/index.d.ts

@@ -1,16 +1,12 @@
-import { StandaloneDispatcher as CoreStandaloneDispatcher } from "@actiondock/core";
+import { type InvocationControl } from "@actiondock/core/server";
 import type { StandaloneOptions } from "../types.js";
+export { type InvocationControl };
 /**
- * 独立二进制轻量参数解析分发器（委托 Core 统一实现，消除重复逻辑）。
+ * 运行独立二进制参数解析分发器并返回退出状态码（委托 Core 统一实现）。
  */
-export declare class StandaloneDispatcher extends CoreStandaloneDispatcher {
-    constructor(options: StandaloneOptions);
-}
+export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions, control?: InvocationControl): Promise<number>;
 /**
- * 运行独立二进制参数解析分发器并返回退出状态码。
+ * 独立二进制进程入口适配器（事实源位于 core 包，此处 re-export 维持既有导入路径兼容）。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
  */
-export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions): Promise<number>;
-/**
- * 创建独立二进制运行时分发器实例。
- */
-export declare function createStandaloneDispatcher(options: StandaloneOptions): StandaloneDispatcher;
+export { runStandaloneProcess } from "@actiondock/core/server";

package/dist/standalone/index.js

@@ -1,22 +1,13 @@
-import { StandaloneDispatcher as CoreStandaloneDispatcher, } from "@actiondock/core";
+import { StandaloneDispatcher as CoreStandaloneDispatcher, } from "@actiondock/core/server";
 /**
- * 独立二进制轻量参数解析分发器（委托 Core 统一实现，消除重复逻辑）。
+ * 运行独立二进制参数解析分发器并返回退出状态码（委托 Core 统一实现）。
  */
-export class StandaloneDispatcher extends CoreStandaloneDispatcher {
-    constructor(options) {
-        super(options);
-    }
+export async function runStandaloneCli(argv = process.argv.slice(2), options, control) {
+    const dispatcher = new CoreStandaloneDispatcher(options);
+    return dispatcher.dispatch(argv, control);
 }
 /**
- * 运行独立二进制参数解析分发器并返回退出状态码。
+ * 独立二进制进程入口适配器（事实源位于 core 包，此处 re-export 维持既有导入路径兼容）。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
  */
-export async function runStandaloneCli(argv = process.argv.slice(2), options) {
-    const dispatcher = new StandaloneDispatcher(options);
-    return dispatcher.dispatch(argv);
-}
-/**
- * 创建独立二进制运行时分发器实例。
- */
-export function createStandaloneDispatcher(options) {
-    return new StandaloneDispatcher(options);
-}
+export { runStandaloneProcess } from "@actiondock/core/server";

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import type { ConfigItemDefinition } from "@actiondock/core";
+import type { ConfigItemDefinition } from "@actiondock/core/project";
+import type { InvocationControl } from "@actiondock/core/server";
+export type { InvocationControl };
 /**
  * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
  * - SUCCESS: 执行成功（0）
@@ -78,6 +80,10 @@ export interface CliContext {
         secret?: boolean;
         mask?: string;
     }) => Promise<string>;
+    /** 可选的中断与取消控制契约 */
+    control?: InvocationControl;
+    /** 退出码收集器（避免污染全局 process.exitCode） */
+    exitCode?: number;
 }
 /**
  * 工程自省详情信息结构。

package/dist/types.js

@@ -1,4 +1,4 @@
-import { ExitCode as CoreExitCode } from "@actiondock/core";
+import { ExitCode as CoreExitCode, } from "@actiondock/core/server";
 /**
  * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
  * - SUCCESS: 执行成功（0）

package/dist/utils/cert.js

@@ -3,7 +3,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSy
 import { isIP } from "node:net";
 import { hostname, networkInterfaces } from "node:os";
 import { join } from "node:path";
-import { getActionDockHome } from "@actiondock/core";
+import { getActionDockHome, } from "@actiondock/core/registry";
 import { generate } from "selfsigned";
 /**
  * 判定字符串是否为有效 IPv4 或 IPv6 地址。

package/dist/utils/duration.d.ts

@@ -1 +1 @@
-export { parseDuration } from "@actiondock/core";
+export { parseDuration } from "@actiondock/core/project";

package/dist/utils/duration.js

@@ -1 +1 @@
-export { parseDuration } from "@actiondock/core";
+export { parseDuration } from "@actiondock/core/project";

package/dist/utils/index.d.ts

@@ -1,8 +1,7 @@
 export * from "./utils.js";
-export * from "./bytes.js";
 export * from "./duration.js";
-export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
 export * from "./input.js";
+export * from "./server-launch.js";

package/dist/utils/index.js

@@ -1,8 +1,7 @@
 export * from "./utils.js";
-export * from "./bytes.js";
 export * from "./duration.js";
-export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
 export * from "./input.js";
+export * from "./server-launch.js";

package/dist/utils/input.d.ts

@@ -1,46 +1,9 @@
-import type { JsonValue } from "@actiondock/sdk";
-/**
- * 获取异常的标准描述信息。
- *
- * @param err 待提取消息的异常对象
- */
-export declare function getErrorMessage(err: unknown): string;
-/**
- * 剔除 UTF-8 文本起始处的 BOM 字节标记（\uFEFF）。
- *
- * @param text 原始输入文本
- */
-export declare function stripBom(text: string): string;
-/**
- * 统一解析 JSON 字符串为标准 JSON 值对象，并在失败时抛出结构化参数异常。
- *
- * @param text 待解析文本内容
- * @param source 输入源描述（如 "--input"、"stdin" 或文件物理路径）
- */
-export declare function parseJson(text: string, source: string): JsonValue;
+import { stripBom } from "@actiondock/core/project";
+export { resolveActionInput, type ResolveActionInputOptions, parseJson, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core/project";
+export { stripBom };
 /**
  * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
- *
- * @param stream 标准输入可读流，默认为 process.stdin
+ * 底层委托 core 的有界读取实现：保持宽松 UTF-8 解码语义与 BOM 剥离行为，
+ * 同时获得默认 10MB 输入上限保护，超限时抛出结构化 INPUT_LIMIT_EXCEEDED 异常。
  */
 export declare function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;
-/**
- * Action 执行输入解析选项。
- */
-export interface ResolveActionInputOptions {
-    input?: string;
-    inputFile?: string;
-    stdin?: NodeJS.ReadableStream;
-}
-/**
- * 统一解析 Action 执行入参。
- *
- * 遵循确定性入参契约：
- * - 当未指定任何输入参数时，默认返回空对象 `{}`。
- * - 简单输入通过 `--input` 传递内联 JSON 字符串。
- * - 复杂输入或标准输入通过 `--input-file` 传递（`-` 表示标准输入 stdin）。
- * - 严禁同时指定 `--input` 与 `--input-file`，检测到冲突时明确抛出参数错误。
- *
- * @param options 输入解析选项
- */
-export declare function resolveActionInput(options: ResolveActionInputOptions): Promise<JsonValue>;

package/dist/utils/input.js

@@ -1,89 +1,12 @@
-import { readFile } from "node:fs/promises";
-import { ArgumentError } from "../errors.js";
-/**
- * 获取异常的标准描述信息。
- *
- * @param err 待提取消息的异常对象
- */
-export function getErrorMessage(err) {
-    if (err instanceof Error) {
-        return err.message;
-    }
-    return String(err);
-}
-/**
- * 剔除 UTF-8 文本起始处的 BOM 字节标记（\uFEFF）。
- *
- * @param text 原始输入文本
- */
-export function stripBom(text) {
-    return text.replace(/^\uFEFF/, "");
-}
-/**
- * 统一解析 JSON 字符串为标准 JSON 值对象，并在失败时抛出结构化参数异常。
- *
- * @param text 待解析文本内容
- * @param source 输入源描述（如 "--input"、"stdin" 或文件物理路径）
- */
-export function parseJson(text, source) {
-    try {
-        return JSON.parse(stripBom(text));
-    }
-    catch (err) {
-        throw new ArgumentError(`Invalid JSON input from ${source}: ${getErrorMessage(err)}`, undefined, "INVALID_JSON");
-    }
-}
+import { readStdinBounded, stripBom } from "@actiondock/core/project";
+export { resolveActionInput, parseJson, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core/project";
+// BOM 剥离单一事实源转引：core 已提供逐字一致的实现，此处仅保留导出面兼容。
+export { stripBom };
 /**
  * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
- *
- * @param stream 标准输入可读流，默认为 process.stdin
+ * 底层委托 core 的有界读取实现：保持宽松 UTF-8 解码语义与 BOM 剥离行为，
+ * 同时获得默认 10MB 输入上限保护，超限时抛出结构化 INPUT_LIMIT_EXCEEDED 异常。
  */
 export async function readStdin(stream = process.stdin) {
-    const chunks = [];
-    for await (const chunk of stream) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    }
-    return Buffer.concat(chunks).toString("utf8");
-}
-/**
- * 统一解析 Action 执行入参。
- *
- * 遵循确定性入参契约：
- * - 当未指定任何输入参数时，默认返回空对象 `{}`。
- * - 简单输入通过 `--input` 传递内联 JSON 字符串。
- * - 复杂输入或标准输入通过 `--input-file` 传递（`-` 表示标准输入 stdin）。
- * - 严禁同时指定 `--input` 与 `--input-file`，检测到冲突时明确抛出参数错误。
- *
- * @param options 输入解析选项
- */
-export async function resolveActionInput(options) {
-    if (options.input !== undefined && options.inputFile !== undefined) {
-        throw new ArgumentError("--input and --input-file cannot be used together", undefined, "INPUT_CONFLICT");
-    }
-    if (options.input !== undefined) {
-        return parseJson(options.input, "--input");
-    }
-    if (options.inputFile !== undefined) {
-        let text;
-        if (options.inputFile === "-") {
-            try {
-                text = await readStdin(options.stdin || process.stdin);
-            }
-            catch (err) {
-                throw new ArgumentError(`Failed to read stdin: ${getErrorMessage(err)}`, undefined, "INPUT_FILE_READ_FAILED");
-            }
-            return parseJson(text, "stdin");
-        }
-        try {
-            text = await readFile(options.inputFile, "utf8");
-        }
-        catch (err) {
-            if (err && err.code === "ENOENT") {
-                throw new ArgumentError(`Input file not found: ${options.inputFile}`, undefined, "INPUT_FILE_NOT_FOUND");
-            }
-            throw new ArgumentError(`Failed to read input file '${options.inputFile}': ${getErrorMessage(err)}`, undefined, "INPUT_FILE_READ_FAILED");
-        }
-        return parseJson(text, options.inputFile);
-    }
-    return {};
+    return stripBom(await readStdinBounded(stream, { strictUtf8: false }));
 }

package/dist/utils/server-launch.d.ts

@@ -0,0 +1,61 @@
+import type { CliContext } from "../types.js";
+/**
+ * 服务类命令（ad serve、ad mcp serve、ad mcp、ad run）的共享启动脚手架（单一事实源）。
+ *
+ * 收敛端口/主机/token 解析（含 ACTIONDOCK_TOKEN 环境变量回退）、
+ * maxBodyBytes 与 timeoutMs 的 try-catch 包装、corsOrigins 归一化、
+ * 停止信号注册与横幅打印，消除 serve.ts 与 mcp.ts 的逐行重复。
+ */
+/**
+ * 解析监听端口：解析失败时回退缺省端口。
+ *
+ * @param rawPort 命令行原始端口串
+ * @param defaultPort 缺省端口（ad serve 为 5177，ad mcp serve 为 5178）
+ * @param falsyFallsBack 是否对零值也回退（mcp serve 旧行为为 parseInt || default，
+ *   端口 0 会回退缺省；ad serve 为 NaN 判定，端口 0 保留）
+ */
+export declare function resolveServerPort(rawPort: string, defaultPort: number, falsyFallsBack?: boolean): number;
+/**
+ * 解析监听主机：未指定时回退 127.0.0.1。
+ */
+export declare function resolveServerHost(rawHost: string | undefined): string;
+/**
+ * 解析鉴权 Token：显式参数优先，其次 --token-env 指定的环境变量，最后 ACTIONDOCK_TOKEN 兜底。
+ *
+ * @param token 显式 -t/--token 参数
+ * @param tokenEnv --token-env 指定的环境变量名
+ */
+export declare function resolveServerToken(token?: string, tokenEnv?: string): string | undefined;
+/**
+ * 解析请求体大小上限（--max-body）：格式非法时抛 ArgumentError。
+ */
+export declare function resolveMaxBodyBytes(maxBody: string | undefined): number | undefined;
+/**
+ * 解析执行超时（--timeout）：格式非法时抛 ArgumentError。
+ */
+export declare function resolveTimeoutMs(timeout: string | undefined): number | undefined;
+/**
+ * 归一化 CORS 来源列表：空列表归一为 undefined。
+ */
+export declare function normalizeCorsOrigins(corsOrigin: string[] | undefined): string[] | undefined;
+/**
+ * 注册 SIGINT/SIGTERM 停止信号处理器（serve 与 mcp serve 共享同一语义）。
+ *
+ * 停止失败必须可见：写入 stderr 一行并标记失败退出码；
+ * 无论成功与否最终强制进程退出。
+ *
+ * @param server 目标服务实例（提供 stop 方法）
+ * @param serverName 横幅与停止消息中的服务名（如 ActionDock server / MCP HTTP server）
+ */
+export declare function registerStopSignalHandler(server: {
+    stop(): Promise<unknown> | unknown;
+}, serverName: string, context?: CliContext): void;
+/**
+ * 打印服务就绪横幅（顶部固定段，serve 与 mcp serve 共享排版）。
+ *
+ * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
+ * @param scheme 端点协议（http 或 https）
+ * @param displayHost 面向展示的主机地址
+ * @param port 实际监听端口
+ */
+export declare function printServerBanner(title: string, scheme: string, displayHost: string, port: number, context?: CliContext): void;

package/dist/utils/server-launch.js

@@ -0,0 +1,114 @@
+import { parseDuration, } from "@actiondock/core/project";
+import { ArgumentError } from "../errors.js";
+import { writeStderr, writeStdout } from "../renderer.js";
+import { parseByteSize } from "./utils.js";
+/**
+ * 服务类命令（ad serve、ad mcp serve、ad mcp、ad run）的共享启动脚手架（单一事实源）。
+ *
+ * 收敛端口/主机/token 解析（含 ACTIONDOCK_TOKEN 环境变量回退）、
+ * maxBodyBytes 与 timeoutMs 的 try-catch 包装、corsOrigins 归一化、
+ * 停止信号注册与横幅打印，消除 serve.ts 与 mcp.ts 的逐行重复。
+ */
+/**
+ * 解析监听端口：解析失败时回退缺省端口。
+ *
+ * @param rawPort 命令行原始端口串
+ * @param defaultPort 缺省端口（ad serve 为 5177，ad mcp serve 为 5178）
+ * @param falsyFallsBack 是否对零值也回退（mcp serve 旧行为为 parseInt || default，
+ *   端口 0 会回退缺省；ad serve 为 NaN 判定，端口 0 保留）
+ */
+export function resolveServerPort(rawPort, defaultPort, falsyFallsBack) {
+    const parsed = parseInt(rawPort, 10);
+    if (falsyFallsBack) {
+        return parsed || defaultPort;
+    }
+    return Number.isNaN(parsed) ? defaultPort : parsed;
+}
+/**
+ * 解析监听主机：未指定时回退 127.0.0.1。
+ */
+export function resolveServerHost(rawHost) {
+    return rawHost || "127.0.0.1";
+}
+/**
+ * 解析鉴权 Token：显式参数优先，其次 --token-env 指定的环境变量，最后 ACTIONDOCK_TOKEN 兜底。
+ *
+ * @param token 显式 -t/--token 参数
+ * @param tokenEnv --token-env 指定的环境变量名
+ */
+export function resolveServerToken(token, tokenEnv) {
+    return (token ||
+        (tokenEnv && typeof process !== "undefined" ? process.env?.[tokenEnv] : undefined) ||
+        (typeof process !== "undefined" ? process.env?.ACTIONDOCK_TOKEN : undefined));
+}
+/**
+ * 解析请求体大小上限（--max-body）：格式非法时抛 ArgumentError。
+ */
+export function resolveMaxBodyBytes(maxBody) {
+    if (!maxBody)
+        return undefined;
+    try {
+        return parseByteSize(maxBody);
+    }
+    catch (err) {
+        throw new ArgumentError(`Invalid max-body format: ${err.message}`);
+    }
+}
+/**
+ * 解析执行超时（--timeout）：格式非法时抛 ArgumentError。
+ */
+export function resolveTimeoutMs(timeout) {
+    if (!timeout)
+        return undefined;
+    try {
+        return parseDuration(timeout);
+    }
+    catch (err) {
+        throw new ArgumentError(`Invalid timeout format: ${err.message}`);
+    }
+}
+/**
+ * 归一化 CORS 来源列表：空列表归一为 undefined。
+ */
+export function normalizeCorsOrigins(corsOrigin) {
+    return corsOrigin && corsOrigin.length > 0 ? corsOrigin : undefined;
+}
+/**
+ * 注册 SIGINT/SIGTERM 停止信号处理器（serve 与 mcp serve 共享同一语义）。
+ *
+ * 停止失败必须可见：写入 stderr 一行并标记失败退出码；
+ * 无论成功与否最终强制进程退出。
+ *
+ * @param server 目标服务实例（提供 stop 方法）
+ * @param serverName 横幅与停止消息中的服务名（如 ActionDock server / MCP HTTP server）
+ */
+export function registerStopSignalHandler(server, serverName, context) {
+    const stopSignalHandler = () => {
+        writeStdout(`\nStopping ${serverName}...`, context);
+        Promise.resolve(server.stop())
+            .catch((err) => {
+            // 停止失败必须可见：写入 stderr 一行并标记失败退出码
+            writeStderr(`[ERROR] Failed to stop ${serverName} gracefully: ${err instanceof Error ? err.message : String(err)}`, context);
+            process.exitCode = 1;
+        })
+            .finally(() => {
+            process.exit(typeof process.exitCode === "number" ? process.exitCode : 0);
+        });
+    };
+    process.once("SIGINT", stopSignalHandler);
+    process.once("SIGTERM", stopSignalHandler);
+}
+/**
+ * 打印服务就绪横幅（顶部固定段，serve 与 mcp serve 共享排版）。
+ *
+ * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
+ * @param scheme 端点协议（http 或 https）
+ * @param displayHost 面向展示的主机地址
+ * @param port 实际监听端口
+ */
+export function printServerBanner(title, scheme, displayHost, port, context) {
+    writeStdout(`\n======================================================`, context);
+    writeStdout(`  ${title}`, context);
+    writeStdout(`======================================================`, context);
+    writeStdout(`  * Listening on:    ${scheme}://${displayHost}:${port}`, context);
+}

package/dist/utils/target.d.ts

@@ -1,4 +1,5 @@
-import { type ActionDockTarget, type ResolvedTarget } from "@actiondock/core";
+import { type ActionDockService } from "@actiondock/core";
+import { type ResolvedTarget } from "@actiondock/core/profile";
 import type { Command } from "commander";
 import type { CliContext } from "../types.js";
 /**
@@ -10,7 +11,7 @@ import type { CliContext } from "../types.js";
  */
 export declare function applyTargetOptions(command: Command): Command;
 /**
- * 目标解析与 Target 创建所需的统一选项视图。
+ * 目标解析与 Service 创建所需的统一选项视图。
  * 与既有命令内联解析逻辑保持逐字段一致，作为唯一事实源供各命令复用。
  */
 export interface TargetResolutionOptions {
@@ -37,14 +38,14 @@ export interface TargetResolutionOptions {
  *
  * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
  * @param context CLI 上下文
- * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Service 实例）
  */
 export declare function resolveTargetFromOptions(options: TargetResolutionOptions, context?: CliContext): ResolvedTarget;
 /**
- * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
+ * 高阶服务执行辅助：统一封装「目标解析 → Service 创建 → 业务回调 → try/finally close」样板。
  *
- * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
- * 都保证 target 资源被正确释放，业务异常原样透传。
+ * 回调获得创建好的 service 与解析后的目标拓扑信息；无论回调成功或抛出，
+ * 都保证 service 资源被正确释放，业务异常原样透传。
  *
  * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
  * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
@@ -52,10 +53,10 @@ export declare function resolveTargetFromOptions(options: TargetResolutionOption
  *
  * @param options 命令选项视图（profile/server/token/package/dataDir/insecure/allowInsecureHttp）
  * @param context CLI 上下文
- * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
+ * @param fn 业务回调（service 为已创建的服务端口实例，resolved 为拓扑解析结果）
  * @param localOptions 本地分支附加选项（如 scanLinkedPackages）与 localRoot 回退策略
  */
-export declare function withTarget(options: TargetResolutionOptions, context: CliContext | undefined, fn: (target: ActionDockTarget, resolved: ResolvedTarget) => Promise<void>, localOptions?: {
+export declare function withService(options: TargetResolutionOptions, context: CliContext | undefined, fn: (service: ActionDockService, resolved: ResolvedTarget) => Promise<void>, localOptions?: {
     /** 本地工程根目录（支持惰性工厂，仅在 local 分支求值）；未提供时按 findProjectRoot 回退 */
     localRoot?: string | (() => string | undefined);
     /** 是否扫描全局链接包（对应 scanLinkedPackages） */
@@ -66,12 +67,12 @@ export declare function withTarget(options: TargetResolutionOptions, context: Cl
      * 保持缺省 false，避免误收割并发 serve 进程的在途运行记录。
      */
     ownDataDir?: boolean;
+    /**
+     * 是否强制要求远端目标：true 时 local 分支直接抛 ArgumentError（如 ad runs cancel），
+     * 替代原 withRemoteService 的专用实现。
+     */
+    requireRemote?: boolean;
 }): Promise<void>;
-/**
- * 仅远端模式目标执行辅助：创建远端 Target 并保证资源释放。
- * 适用于 runs cancel 等明确要求远端目标的命令。
- */
-export declare function withRemoteTarget(options: TargetResolutionOptions, context: CliContext | undefined, fn: (target: ActionDockTarget, resolved: ResolvedTarget) => Promise<void>): Promise<void>;
 /**
  * 目标包根目录解析（含 -P 显式寻址与当前工程回退）。
  * 供命令在创建 Target 前统一完成包寻址，返回 null 表示当前目录无工程。