@actiondock/cli 2.6.0 → 2.8.0

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;

package/dist/utils/utils.js

@@ -1,5 +1,36 @@
-import { resolvePackageRoot, findProjectRoot } from "@actiondock/core";
-import { ArgumentError, notInProjectError, packageNotFoundError } from "../errors.js";
+import { resolvePackageRoot, } from "@actiondock/core/registry";
+import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
+import { loadManifest, } from "@actiondock/core/project";
+import { resolve } from "node:path";
+import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError, wrapAsExecutionError } from "../errors.js";
+/**
+ * 「未显式指定包且当前目录无工程」的统一补救提示（单一事实源）。
+ */
+export const PACKAGE_HINT_MESSAGE = "Please specify -P, --package <id> or cd into a project directory.";
+/**
+ * 拼接远端目标标题后缀（单一事实源）。
+ *
+ * 形如 `on remote server <url> (Profile: <name>)`，供列表类命令的
+ * 标题拼接复用（如 `Actions ${remoteTargetSuffix(target)}`），
+ * 消除五处同构模板漂移。
+ *
+ * @param resolved 目标拓扑解析结果（远端分支）
+ */
+export function remoteTargetSuffix(resolved) {
+    const profile = resolved.profileName ? ` (Profile: ${resolved.profileName})` : "";
+    return `on remote server ${resolved.serverUrl}${profile}`;
+}
+/**
+ * 拼接远端目标标题标签（单一事实源）。
+ *
+ * 形如 `Remote Server <url> (Profile: <name>)`，与 remoteTargetSuffix 共享
+ * 同一拼接实现，供 state、config 等直接以远端目标为标题主体的命令复用。
+ *
+ * @param resolved 目标拓扑解析结果（远端分支）
+ */
+export function remoteTargetLabel(resolved) {
+    return `Remote Server ${resolved.serverUrl}${resolved.profileName ? ` (Profile: ${resolved.profileName})` : ""}`;
+}
 /**
  * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
  * 多个关键字使用 '|'（正则逻辑或）连接。
@@ -81,11 +112,64 @@ export function getTargetRoot(packageOption, keyHint) {
             throw packageNotFoundError(targetPackage);
         }
         else {
-            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
+            throw notInProjectError(PACKAGE_HINT_MESSAGE);
         }
     }
     return { root, key: effectiveKey };
 }
+export function requirePackageRoot(packageOption, options) {
+    const root = packageOption ? resolvePackageRoot(packageOption) : findProjectRoot();
+    if (!root) {
+        if (packageOption) {
+            throw packageNotFoundError(packageOption);
+        }
+        throw notInProjectError(options?.hint ?? PACKAGE_HINT_MESSAGE);
+    }
+    return options?.loadConfig
+        ? { root, projConfig: loadProjectConfig(root) }
+        : { root };
+}
+/**
+ * 依赖类命令（ad add / ad remove）的工程根目录与清单解析脚手架（单一事实源）。
+ *
+ * 与 requirePackageRoot 的差异：-P 语义为工程目录路径而非包标识，
+ * 显式路径不做注册表寻址（不抛 packageNotFoundError，缺失清单由后续存在性检查报错）。
+ *
+ * @param packageOption 显式指定的工程目录路径（对应 -P, --package <path>）
+ * @returns 工程根目录与已验存的 actiondock.json 清单
+ */
+export function requireProjectManifestRoot(packageOption) {
+    const root = packageOption ? resolve(packageOption) : findProjectRoot();
+    if (!root) {
+        throw notInProjectError("Please specify -P, --package <path> or cd into a project directory.");
+    }
+    const manifest = loadManifest(root);
+    if (!manifest) {
+        throw new ArgumentError(`actiondock.json not found in ${root}`);
+    }
+    return { root, manifest };
+}
+/**
+ * 依赖事务失败回滚辅助（ad add / ad remove 共享）：回滚事务后按统一规则透传异常。
+ *
+ * 回滚与包裹规则：
+ * - 先执行事务回滚快照，保留原始磁盘状态；
+ * - ActionDockError 与 CliError 原样透传（保留 code 与 details）；
+ * - 其余包裹为 ExecutionError 并保留原始 code，缺省时回退 fallbackCode。
+ *
+ * @param tx 已开启的工程事务快照
+ * @param err 业务回调抛出的原始异常
+ * @param fallbackCode 包裹分支缺省错误码（命令专属，如 ADD_DEPENDENCY_FAILED）
+ */
+export async function rollbackAndRethrow(tx, err, fallbackCode) {
+    await tx.rollback({ frozenInstall: false });
+    const passthrough = wrapAsExecutionError(err);
+    if (passthrough !== err) {
+        const original = err;
+        throw new ExecutionError(original.message, err, original.code || fallbackCode);
+    }
+    throw passthrough;
+}
 /**
  * 聚合命令自身选项与根程序全局选项（如 --json、--data-dir 等）。
  */
@@ -97,15 +181,21 @@ export function getEffectiveOptions(rawOptions, cmd) {
 }
 /**
  * 解析意图过滤回退策略。
- * 机器输出模式（--json）仅在显式传 --fallback 时回退，
+ *
+ * 统一事实源：机器输出模式（--json）仅在显式传 --fallback 时回退，
  * 人类交互模式默认回退（可被 --no-fallback 关闭）。
+ *
+ * 回退标志的显式性判定完全依据 Commander 解析结果（由调用方传入）：
+ * 同时注册 --fallback 与 --no-fallback 的命令，未指定时 fallback 为
+ * undefined、显式 --fallback 为 true、--no-fallback 为 false，
+ * 不再直读 process.argv，消除隐藏的全局依赖。
+ *
+ * @param options 命令选项视图（含 fallback 与 json 字段）
  */
 export function resolveFallbackStrategy(options) {
     const isMachine = Boolean(options.json);
-    const fallbackExplicit = options.fallback === true ||
-        (Array.isArray(process.argv) && process.argv.includes("--fallback"));
     return {
         isMachine,
-        shouldFallback: isMachine ? fallbackExplicit : options.fallback !== false,
+        shouldFallback: isMachine ? options.fallback === true : options.fallback !== false,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -34,11 +34,10 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.6.0",
-    "@actiondock/core": "^2.6.0",
-    "@actiondock/mcp": "^2.6.0",
-    "@actiondock/runtime-node": "^2.6.0",
-    "@actiondock/sdk": "^2.6.0",
+    "@actiondock/builder": "^2.8.0",
+    "@actiondock/core": "^2.8.0",
+    "@actiondock/mcp": "^2.8.0",
+    "@actiondock/sdk": "^2.8.0",
     "commander": "^13.1.0",
     "selfsigned": "^5.5.0"
   },

package/dist/utils/bytes.d.ts

@@ -1 +0,0 @@
-export { parseByteSize } from "./utils.js";

package/dist/utils/bytes.js

@@ -1 +0,0 @@
-export { parseByteSize } from "./utils.js";

package/dist/utils/filter.d.ts

@@ -1 +0,0 @@
-export { resolveIntent } from "./utils.js";

package/dist/utils/filter.js

@@ -1 +0,0 @@
-export { resolveIntent } from "./utils.js";