@actiondock/cli 2.7.0 → 2.8.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,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 表示当前目录无工程。

package/dist/utils/target.js

@@ -1,5 +1,7 @@
-import { createActionDockTarget, findProjectRoot, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
-import { createNodePlatform } from "@actiondock/runtime-node";
+import { connectActionDock, createActionDock, createNodePlatform, findProjectRoot, } from "@actiondock/core";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
+import { resolveTarget, } from "@actiondock/core/profile";
+import { ArgumentError } from "../errors.js";
 /**
  * 统一为 Commander 命令节点挂载目标环境解析相关选项（单一事实源）。
  * 包括：-p/--profile, -s/--server, -t/--token, -k/--insecure, --allow-insecure-http。
@@ -23,7 +25,7 @@ export function applyTargetOptions(command) {
  *
  * @param options 命令选项视图（支持直接传入 Commander 解析后的 options 对象）
  * @param context CLI 上下文
- * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Target 实例）
+ * @returns 解析后的目标拓扑信息（仅信息解析，不创建 Service 实例）
  */
 export function resolveTargetFromOptions(options, context) {
     return resolveTarget({
@@ -35,10 +37,10 @@ export function resolveTargetFromOptions(options, context) {
     }, context?.customHome);
 }
 /**
- * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
+ * 高阶服务执行辅助：统一封装「目标解析 → Service 创建 → 业务回调 → try/finally close」样板。
  *
- * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
- * 都保证 target 资源被正确释放，业务异常原样透传。
+ * 回调获得创建好的 service 与解析后的目标拓扑信息；无论回调成功或抛出，
+ * 都保证 service 资源被正确释放，业务异常原样透传。
  *
  * 默认旁观打开：内部创建的本地 Host 以非收割模式打开存储（不置 recoverOrphans），
  * 供 ad state / ad runs / ad config 等查询命令与运行中的 serve 进程并发访问同一库；
@@ -46,29 +48,28 @@ export function resolveTargetFromOptions(options, context) {
  *
  * @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 async function withTarget(options, context, fn, localOptions) {
+export async function withService(options, context, fn, localOptions) {
     const resolved = resolveTargetFromOptions(options, context);
+    if (localOptions?.requireRemote && resolved.type === "local") {
+        throw new ArgumentError("'ad runs cancel' is only supported for remote execution targets. Use --profile <name> or --server <url>.");
+    }
     // localRoot 仅在 local 分支求值，避免远端模式下触发包寻址副作用
     const localRoot = resolved.type === "local"
         ? (typeof localOptions?.localRoot === "function" ? localOptions.localRoot() : localOptions?.localRoot) ??
             findProjectRoot() ??
             undefined
         : undefined;
-    // 本地执行命令声明持有者身份时，向 App 层透传收割开关；
-    // 查询命令保持缺省不传，存储以旁观模式打开
-    const appRecoverOrphans = localOptions?.ownDataDir === true ? { recoverOrphans: true } : undefined;
-    const target = await createActionDockTarget(resolved.type === "remote"
-        ? {
-            type: "remote",
+    const service = resolved.type === "remote"
+        ? await connectActionDock({
             serverUrl: resolved.serverUrl,
             token: resolved.token,
             insecure: resolved.insecure,
             allowInsecureHttp: resolved.allowInsecureHttp ?? options.allowInsecureHttp,
-        }
-        : {
+        })
+        : await createActionDock({
             type: "local",
             projectRoot: localRoot,
             customHome: context?.customHome,
@@ -81,33 +82,13 @@ export async function withTarget(options, context, fn, localOptions) {
             ...(localOptions?.scanLinkedPackages !== undefined
                 ? { scanLinkedPackages: localOptions.scanLinkedPackages }
                 : undefined),
-            ...(appRecoverOrphans ? { recoverOrphans: true } : undefined),
+            ...(localOptions?.ownDataDir === true ? { recoverOrphans: true } : undefined),
         });
     try {
-        await fn(target, resolved);
-    }
-    finally {
-        await target.close();
-    }
-}
-/**
- * 仅远端模式目标执行辅助：创建远端 Target 并保证资源释放。
- * 适用于 runs cancel 等明确要求远端目标的命令。
- */
-export async function withRemoteTarget(options, context, fn) {
-    const resolved = resolveTargetFromOptions(options, context);
-    const target = await createActionDockTarget({
-        type: "remote",
-        serverUrl: resolved.serverUrl,
-        token: resolved.token,
-        insecure: resolved.insecure,
-        allowInsecureHttp: resolved.allowInsecureHttp ?? options.allowInsecureHttp,
-    });
-    try {
-        await fn(target, resolved);
+        await fn(service, resolved);
     }
     finally {
-        await target.close();
+        await service.close();
     }
 }
 /**

package/dist/utils/utils.d.ts

@@ -1,3 +1,35 @@
+import { loadProjectConfig } from "@actiondock/core";
+import { type ActionDockManifest, type ProjectTransaction } from "@actiondock/core/project";
+/**
+ * 「未显式指定包且当前目录无工程」的统一补救提示（单一事实源）。
+ */
+export declare const PACKAGE_HINT_MESSAGE = "Please specify -P, --package <id> or cd into a project directory.";
+/**
+ * 远端目标拓扑的最小字段视图（与 core 的 ResolvedTarget 远端分支兼容）。
+ */
+export interface RemoteTargetLike {
+    serverUrl?: string;
+    profileName?: string;
+}
+/**
+ * 拼接远端目标标题后缀（单一事实源）。
+ *
+ * 形如 `on remote server <url> (Profile: <name>)`，供列表类命令的
+ * 标题拼接复用（如 `Actions ${remoteTargetSuffix(target)}`），
+ * 消除五处同构模板漂移。
+ *
+ * @param resolved 目标拓扑解析结果（远端分支）
+ */
+export declare function remoteTargetSuffix(resolved: RemoteTargetLike): string;
+/**
+ * 拼接远端目标标题标签（单一事实源）。
+ *
+ * 形如 `Remote Server <url> (Profile: <name>)`，与 remoteTargetSuffix 共享
+ * 同一拼接实现，供 state、config 等直接以远端目标为标题主体的命令复用。
+ *
+ * @param resolved 目标拓扑解析结果（远端分支）
+ */
+export declare function remoteTargetLabel(resolved: RemoteTargetLike): string;
 /**
  * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
  * 多个关键字使用 '|'（正则逻辑或）连接。
@@ -19,14 +51,82 @@ export declare function getTargetRoot(packageOption?: string, keyHint?: string):
     root: string;
     key: string;
 };
+/**
+ * 包根目录寻址脚手架（单一事实源）：显式指定包且寻址失败抛 packageNotFoundError，
+ * 未指定包且当前目录无工程抛 notInProjectError（附带 -P 补救提示）。
+ *
+ * 与 getTargetRoot 的差异：不消费 pkg/ 键前缀提示，寻址失败必抛错而非返回 null；
+ * 与 resolveLocalPackageRoot 的差异：后者保留 null 返回值供降级视图使用；
+ * 与 resolveLocalRunScope 的差异：后者在工程清单损坏时降级为链接包视图而非报错，语义不同不并入。
+ */
+/** requirePackageRoot 的返回视图（未请求加载工程配置时仅含根目录）。 */
+export interface PackageRootScope {
+    /** 目标包根目录 */
+    root: string;
+}
+/** requirePackageRoot 的返回视图（loadConfig 为真时附带非空工程配置）。 */
+export interface PackageRootWithConfigScope {
+    /** 目标包根目录 */
+    root: string;
+    /** 目标工程配置（仅在 loadConfig 为真时返回，值恒存在） */
+    projConfig: ReturnType<typeof loadProjectConfig>;
+}
+/**
+ * 解析目标包根目录（重载入口：loadConfig 为真时一并返回工程配置）。
+ *
+ * @param packageOption 显式指定的包标识或路径（对应 -P, --package）
+ * @param options 可选项：loadConfig 请求加载工程配置；hint 覆盖无工程时的补救提示行
+ */
+export declare function requirePackageRoot(packageOption: string | undefined, options: {
+    loadConfig: true;
+    hint?: string;
+}): PackageRootWithConfigScope;
+export declare function requirePackageRoot(packageOption: string | undefined, options?: {
+    loadConfig?: false;
+    hint?: string;
+}): PackageRootScope;
+/**
+ * 依赖类命令（ad add / ad remove）的工程根目录与清单解析脚手架（单一事实源）。
+ *
+ * 与 requirePackageRoot 的差异：-P 语义为工程目录路径而非包标识，
+ * 显式路径不做注册表寻址（不抛 packageNotFoundError，缺失清单由后续存在性检查报错）。
+ *
+ * @param packageOption 显式指定的工程目录路径（对应 -P, --package <path>）
+ * @returns 工程根目录与已验存的 actiondock.json 清单
+ */
+export declare function requireProjectManifestRoot(packageOption: string | undefined): {
+    root: string;
+    manifest: ActionDockManifest;
+};
+/**
+ * 依赖事务失败回滚辅助（ad add / ad remove 共享）：回滚事务后按统一规则透传异常。
+ *
+ * 回滚与包裹规则：
+ * - 先执行事务回滚快照，保留原始磁盘状态；
+ * - ActionDockError 与 CliError 原样透传（保留 code 与 details）；
+ * - 其余包裹为 ExecutionError 并保留原始 code，缺省时回退 fallbackCode。
+ *
+ * @param tx 已开启的工程事务快照
+ * @param err 业务回调抛出的原始异常
+ * @param fallbackCode 包裹分支缺省错误码（命令专属，如 ADD_DEPENDENCY_FAILED）
+ */
+export declare function rollbackAndRethrow(tx: ProjectTransaction, err: unknown, fallbackCode: string): Promise<never>;
 /**
  * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
 export declare function getEffectiveOptions(rawOptions: any, cmd?: any): any;
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json）仅在显式传 --fallback 时回退，
+ *
+ * 统一事实源：机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
+ *
+ * 回退标志的显式性判定完全依据 Commander 解析结果（由调用方传入）：
+ * 同时注册 --fallback 与 --no-fallback 的命令，未指定时 fallback 为
+ * undefined、显式 --fallback 为 true、--no-fallback 为 false，
+ * 不再直读 process.argv，消除隐藏的全局依赖。
+ *
+ * @param options 命令选项视图（含 fallback 与 json 字段）
  */
 export declare function resolveFallbackStrategy(options: {
     fallback?: boolean;