@actiondock/cli 2.7.0 → 2.9.0

package/dist/standalone/index.js

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

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import type { ConfigItemDefinition, InvocationControl } from "@actiondock/core";
+import type { ConfigItemDefinition } from "@actiondock/core/project";
+import type { InvocationControl } from "@actiondock/core/server";
 export type { InvocationControl };
 /**
  * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。

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 +1,9 @@
-export { resolveActionInput, type ResolveActionInputOptions, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";
+import { stripBom } from "@actiondock/core/project";
+export { resolveActionInput, type ResolveActionInputOptions, parseJson, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core/project";
+export { stripBom };
+/**
+ * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
+ * 底层委托 core 的有界读取实现：保持宽松 UTF-8 解码语义与 BOM 剥离行为，
+ * 同时获得默认 10MB 输入上限保护，超限时抛出结构化 INPUT_LIMIT_EXCEEDED 异常。
+ */
+export declare function readStdin(stream?: NodeJS.ReadableStream): Promise<string>;

package/dist/utils/input.js

@@ -1 +1,12 @@
-export { resolveActionInput, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";
+import { readStdinBounded, stripBom } from "@actiondock/core/project";
+export { resolveActionInput, parseJson, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core/project";
+// BOM 剥离单一事实源转引：core 已提供逐字一致的实现，此处仅保留导出面兼容。
+export { stripBom };
+/**
+ * 从标准输入流中完整读取全部数据并转换为 UTF-8 字符串。
+ * 底层委托 core 的有界读取实现：保持宽松 UTF-8 解码语义与 BOM 剥离行为，
+ * 同时获得默认 10MB 输入上限保护，超限时抛出结构化 INPUT_LIMIT_EXCEEDED 异常。
+ */
+export async function readStdin(stream = process.stdin) {
+    return stripBom(await readStdinBounded(stream, { strictUtf8: false }));
+}

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

@@ -0,0 +1,114 @@
+import type { ServerViewOptions } from "@actiondock/core/server";
+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;
+/**
+ * 虚拟视图简要展示信息。
+ */
+export interface ServerViewSummary {
+    name: string;
+    enableMcp?: boolean;
+}
+/**
+ * 打印服务横幅的可选配置参数。
+ */
+export interface PrintServerBannerOptions {
+    views?: Record<string, ServerViewOptions> | ServerViewOptions[];
+    endpointHost?: string;
+    enableMcp?: boolean;
+}
+/**
+ * 从指定文件路径加载虚拟视图配置字典。
+ *
+ * @param filePath 视图配置文件路径
+ * @returns 解析后的视图字典或数组
+ */
+export declare function loadViewsFromFile(filePath: string): Record<string, ServerViewOptions> | ServerViewOptions[];
+/**
+ * 合并项目配置与独立配置文件中的虚拟视图定义。
+ * 命令行 --views-file 优先级高于项目配置文件 actiondock.json 中的 server.views。
+ *
+ * @param configViews 项目配置中的 views
+ * @param fileViews 独立配置文件中的 views
+ */
+export declare function mergeServerViews(configViews?: Record<string, ServerViewOptions> | ServerViewOptions[], fileViews?: Record<string, ServerViewOptions> | ServerViewOptions[]): Record<string, ServerViewOptions> | ServerViewOptions[] | undefined;
+/**
+ * 从服务视图配置中提取所有命名空间视图列表（排除 default 默认视图）。
+ *
+ * @param views 视图字典或数组
+ * @returns 命名空间视图简要信息列表
+ */
+export declare function extractNamespacedViews(views?: Record<string, ServerViewOptions> | ServerViewOptions[]): ServerViewSummary[];
+/**
+ * 打印服务命名空间虚拟视图列表。
+ *
+ * @param views 视图配置字典或数组
+ * @param scheme 访问协议（http 或 https）
+ * @param endpointHost 面向调用的端点主机地址
+ * @param port 监听端口
+ * @param context CLI 上下文
+ * @param options 额外选项（如全局 enableMcp）
+ */
+export declare function printServerViews(views: Record<string, ServerViewOptions> | ServerViewOptions[] | undefined, scheme: string, endpointHost: string, port: number, context?: CliContext, options?: {
+    enableMcp?: boolean;
+}): void;
+/**
+ * 打印服务就绪横幅（顶部固定段，支持展示命名空间视图）。
+ *
+ * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
+ * @param scheme 端点协议（http 或 https）
+ * @param displayHost 面向展示的主机地址
+ * @param port 实际监听端口
+ * @param contextOrOptions 命令行上下文或横幅配置选项
+ * @param maybeOptions 横幅配置选项（包含 views 等信息）
+ */
+export declare function printServerBanner(title: string, scheme: string, displayHost: string, port: number, contextOrOptions?: CliContext | PrintServerBannerOptions, maybeOptions?: PrintServerBannerOptions): void;

package/dist/utils/server-launch.js

@@ -0,0 +1,275 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+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);
+}
+/**
+ * 从指定文件路径加载虚拟视图配置字典。
+ *
+ * @param filePath 视图配置文件路径
+ * @returns 解析后的视图字典或数组
+ */
+export function loadViewsFromFile(filePath) {
+    const resolvedPath = resolve(filePath);
+    if (!existsSync(resolvedPath)) {
+        throw new ArgumentError(`Views file not found: ${resolvedPath}`);
+    }
+    let parsed;
+    try {
+        const content = readFileSync(resolvedPath, "utf-8");
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ArgumentError(`Failed to read views file: ${msg}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new ArgumentError("Invalid views file: expected a JSON object or array");
+    }
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    const obj = parsed;
+    if (obj.views && typeof obj.views === "object") {
+        return obj.views;
+    }
+    if (obj.server && typeof obj.server === "object" && obj.server.views) {
+        const srv = obj.server;
+        return srv.views;
+    }
+    return parsed;
+}
+/**
+ * 合并项目配置与独立配置文件中的虚拟视图定义。
+ * 命令行 --views-file 优先级高于项目配置文件 actiondock.json 中的 server.views。
+ *
+ * @param configViews 项目配置中的 views
+ * @param fileViews 独立配置文件中的 views
+ */
+export function mergeServerViews(configViews, fileViews) {
+    if (!configViews && !fileViews) {
+        return undefined;
+    }
+    if (!configViews) {
+        return fileViews;
+    }
+    if (!fileViews) {
+        return configViews;
+    }
+    if (!Array.isArray(configViews) && !Array.isArray(fileViews)) {
+        return { ...configViews, ...fileViews };
+    }
+    const merged = {};
+    const addEntry = (item, fallbackKey) => {
+        const key = item.name?.trim() || fallbackKey;
+        merged[key] = { ...item, name: key };
+    };
+    if (Array.isArray(configViews)) {
+        configViews.forEach((item, index) => addEntry(item, item.name || `view_${index}`));
+    }
+    else {
+        Object.entries(configViews).forEach(([k, v]) => addEntry(v, k));
+    }
+    if (Array.isArray(fileViews)) {
+        fileViews.forEach((item, index) => addEntry(item, item.name || `view_${index}`));
+    }
+    else {
+        Object.entries(fileViews).forEach(([k, v]) => addEntry(v, k));
+    }
+    return merged;
+}
+/**
+ * 从服务视图配置中提取所有命名空间视图列表（排除 default 默认视图）。
+ *
+ * @param views 视图字典或数组
+ * @returns 命名空间视图简要信息列表
+ */
+export function extractNamespacedViews(views) {
+    if (!views)
+        return [];
+    const result = [];
+    if (Array.isArray(views)) {
+        for (let i = 0; i < views.length; i++) {
+            const item = views[i];
+            if (!item)
+                continue;
+            const name = item.name?.trim() || `view_${i}`;
+            if (name === "default")
+                continue;
+            result.push({
+                name,
+                enableMcp: item.enableMcp,
+            });
+        }
+    }
+    else if (typeof views === "object") {
+        for (const [key, item] of Object.entries(views)) {
+            if (!item)
+                continue;
+            const name = item.name?.trim() || key.trim();
+            if (name === "default")
+                continue;
+            result.push({
+                name,
+                enableMcp: item.enableMcp,
+            });
+        }
+    }
+    return result;
+}
+/**
+ * 打印服务命名空间虚拟视图列表。
+ *
+ * @param views 视图配置字典或数组
+ * @param scheme 访问协议（http 或 https）
+ * @param endpointHost 面向调用的端点主机地址
+ * @param port 监听端口
+ * @param context CLI 上下文
+ * @param options 额外选项（如全局 enableMcp）
+ */
+export function printServerViews(views, scheme, endpointHost, port, context, options) {
+    const namespaced = extractNamespacedViews(views);
+    if (namespaced.length === 0) {
+        return;
+    }
+    writeStdout(`  * Views:`, context);
+    for (const v of namespaced) {
+        const encodedName = encodeURIComponent(v.name);
+        writeStdout(`    - ${v.name}:`, context);
+        writeStdout(`      - HTTP Root:    ${scheme}://${endpointHost}:${port}/views/${encodedName}`, context);
+        const mcpEnabled = options?.enableMcp !== false && v.enableMcp !== false;
+        const mcpDesc = mcpEnabled
+            ? `${scheme}://${endpointHost}:${port}/views/${encodedName}/mcp`
+            : "Disabled";
+        writeStdout(`      - MCP Endpoint: ${mcpDesc}`, context);
+    }
+}
+/**
+ * 打印服务就绪横幅（顶部固定段，支持展示命名空间视图）。
+ *
+ * @param title 横幅主体标题（如 ActionDock 2.0 HTTP Runner Server）
+ * @param scheme 端点协议（http 或 https）
+ * @param displayHost 面向展示的主机地址
+ * @param port 实际监听端口
+ * @param contextOrOptions 命令行上下文或横幅配置选项
+ * @param maybeOptions 横幅配置选项（包含 views 等信息）
+ */
+export function printServerBanner(title, scheme, displayHost, port, contextOrOptions, maybeOptions) {
+    let context;
+    let options;
+    if (contextOrOptions &&
+        ("views" in contextOrOptions || "endpointHost" in contextOrOptions || "enableMcp" in contextOrOptions)) {
+        options = contextOrOptions;
+    }
+    else {
+        context = contextOrOptions;
+        options = maybeOptions;
+    }
+    writeStdout(`\n======================================================`, context);
+    writeStdout(`  ${title}`, context);
+    writeStdout(`======================================================`, context);
+    writeStdout(`  * Listening on:    ${scheme}://${displayHost}:${port}`, context);
+    if (options?.views) {
+        const endpointHost = options.endpointHost || displayHost;
+        printServerViews(options.views, scheme, endpointHost, port, context, {
+            enableMcp: options.enableMcp,
+        });
+    }
+}

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 表示当前目录无工程。