@actiondock/cli 2.0.12 → 2.2.1

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+import type { ActionDefinition } from "@actiondock/sdk";
+import type { ConfigItemDefinition } from "@actiondock/core";
+/**
+ * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
+ * - SUCCESS: 执行成功（0）
+ * - FAILURE: 业务或框架执行失败（1）
+ * - INVALID_ARGUMENT: 命令行参数或选项错误（2）
+ * - SIGINT: 进程接收中断信号退出（130）
+ */
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly FAILURE: 1;
+    readonly INVALID_ARGUMENT: 2;
+    readonly SIGINT: 130;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * 标准执行与数据信封接口。
+ */
+export interface Envelope<T = unknown> {
+    ok: boolean;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    meta?: Record<string, unknown>;
+}
+/**
+ * 独立二进制运行模式声明。
+ */
+export interface StandaloneOptions {
+    /** 所属 Package ID */
+    packageId: string;
+    /** 版本号 */
+    version: string;
+    /** 描述信息 */
+    description?: string;
+    /** 声明的配置依赖字典 */
+    configDefs?: Record<string, ConfigItemDefinition>;
+    /** 内置动作定义映射或数组 */
+    actions: Map<string, ActionDefinition> | Array<{
+        id: string;
+        action: ActionDefinition;
+    } | (ActionDefinition & {
+        id: string;
+    })> | Record<string, ActionDefinition>;
+    /** 自定义数据目录 */
+    dataDir?: string;
+    /** 自定义 ActionDock 用户家目录 */
+    customHome?: string;
+    /** 自定义标准输出写入函数 */
+    stdout?: (msg: string) => void;
+    /** 自定义标准错误写入函数 */
+    stderr?: (msg: string) => void;
+    /** 是否采用纯内存运行模式 */
+    inMemory?: boolean;
+}
+/**
+ * CLI 上下文环境。
+ */
+export interface CliContext {
+    /** 独立运行模式配置 */
+    standalone?: StandaloneOptions;
+    /** 自定义数据目录 */
+    dataDir?: string;
+    /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
+    customHome?: string;
+    /** 默认信封包装输出模式 */
+    defaultEnvelope?: boolean;
+    /** 自定义标准输出写入函数 */
+    stdout?: (msg: string) => void;
+    /** 自定义标准错误写入函数 */
+    stderr?: (msg: string) => void;
+    /** 自定义标准输入流 */
+    stdin?: NodeJS.ReadableStream;
+    /** 自定义交互式输入提示函数（用于测试或外部调用重定向） */
+    promptInput?: (promptText: string, options?: {
+        secret?: boolean;
+        mask?: string;
+    }) => Promise<string>;
+}
+/**
+ * 工程自省详情信息结构。
+ */
+export interface ProjectDetailInfo {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    projectRoot: string;
+    actionsDir: string;
+    playbooksDir: string;
+    actionsCount: number;
+    playbooksCount: number;
+    actions: string[];
+    playbooks: string[];
+    configDeclared: string[];
+    configDef?: Record<string, ConfigItemDefinition>;
+    actionsMap?: Map<string, {
+        id?: string;
+        description?: string;
+    }>;
+    playbooksMap?: Map<string, any>;
+}
+/**
+ * 聚合 Package 信息结构。
+ */
+export interface AggregatedPackage {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    path: string;
+    actionsCount: number;
+    playbooksCount: number;
+    actions: string[];
+    playbooks: string[];
+    configDeclared: string[];
+}
+/**
+ * 环境变量满足率检测项。
+ */
+export interface EnvCheckItem {
+    key: string;
+    required: boolean;
+    satisfied: boolean;
+    matchedEnv: string | null;
+    hasDefault: boolean;
+    secret: boolean;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+import { ExitCode as CoreExitCode } from "@actiondock/core";
+/**
+ * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
+ * - SUCCESS: 执行成功（0）
+ * - FAILURE: 业务或框架执行失败（1）
+ * - INVALID_ARGUMENT: 命令行参数或选项错误（2）
+ * - SIGINT: 进程接收中断信号退出（130）
+ */
+export const ExitCode = CoreExitCode;

package/dist/utils/bytes.d.ts

@@ -1 +1 @@
-export { parseByteSize } from "@actiondock/runtime-cli";
+export { parseByteSize } from "./utils.js";

package/dist/utils/bytes.js

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

package/dist/utils/duration.js

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

package/dist/utils/filter.d.ts

@@ -1 +1 @@
-export { resolveIntent } from "@actiondock/runtime-cli";
+export { resolveIntent } from "./utils.js";

package/dist/utils/filter.js

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

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./utils.js";
+export * from "./bytes.js";
+export * from "./duration.js";
+export * from "./filter.js";
+export * from "./target.js";
+export * from "./spawn.js";

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+export * from "./utils.js";
+export * from "./bytes.js";
+export * from "./duration.js";
+export * from "./filter.js";
+export * from "./target.js";
+export * from "./spawn.js";

package/dist/utils/spawn.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 子进程执行结果视图。
+ */
+export interface SpawnAsyncResult {
+    /** 进程退出码（null 表示被信号终止） */
+    status: number | null;
+    /** 终止信号名称 */
+    signal: string | null;
+    /** 标准输出内容 */
+    stdout: string;
+    /** 标准错误内容 */
+    stderr: string;
+}
+/**
+ * 异步执行子进程（Promise 化 spawn），保留 win32 shell 处理与退出码透传。
+ *
+ * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
+ *
+ * @param command 可执行文件名
+ * @param args 参数列表
+ * @param options 附加选项（cwd 与 shell 策略）
+ */
+export declare function spawnAsync(command: string, args: string[], options?: {
+    cwd?: string;
+    shell?: boolean;
+    stdio?: "pipe" | "inherit";
+}): Promise<SpawnAsyncResult>;

package/dist/utils/spawn.js

@@ -0,0 +1,35 @@
+import { spawn } from "node:child_process";
+/**
+ * 异步执行子进程（Promise 化 spawn），保留 win32 shell 处理与退出码透传。
+ *
+ * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
+ *
+ * @param command 可执行文件名
+ * @param args 参数列表
+ * @param options 附加选项（cwd 与 shell 策略）
+ */
+export function spawnAsync(command, args, options) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn(command, args, {
+            cwd: options?.cwd,
+            stdio: options?.stdio ?? "pipe",
+            shell: options?.shell ?? process.platform === "win32",
+        });
+        let stdout = "";
+        let stderr = "";
+        if (proc.stdout) {
+            proc.stdout.on("data", (chunk) => {
+                stdout += chunk.toString();
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on("data", (chunk) => {
+                stderr += chunk.toString();
+            });
+        }
+        proc.on("error", reject);
+        proc.on("close", (status, signal) => {
+            resolve({ status, signal: signal ?? null, stdout, stderr });
+        });
+    });
+}

package/dist/utils/target.d.ts

@@ -0,0 +1,45 @@
+import { type ActionDockTarget, type ResolvedTarget } from "@actiondock/core";
+import type { CliContext } from "../types.js";
+/**
+ * 目标解析与 Target 创建所需的统一选项视图。
+ * 与既有命令内联解析逻辑保持逐字段一致，作为唯一事实源供各命令复用。
+ */
+export interface TargetResolutionOptions {
+    /** 显式指定的包标识或路径（对应 -P, --package） */
+    package?: string;
+    /** 远端 Profile 名称（对应 -p, --profile） */
+    profile?: string;
+    /** 远端服务地址（对应 -s, --server） */
+    server?: string;
+    /** 远端鉴权 Token（对应 -t, --token） */
+    token?: string;
+    /** 自定义数据目录（对应 --data-dir） */
+    dataDir?: string;
+}
+/**
+ * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
+ *
+ * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
+ * 都保证 target 资源被正确释放，业务异常原样透传。
+ *
+ * @param options 命令选项视图（profile/server/token/package/dataDir）
+ * @param context CLI 上下文
+ * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
+ * @param localOptions 本地分支附加选项（如 scanLinkedPackages）与 localRoot 回退策略
+ */
+export declare function withTarget(options: TargetResolutionOptions, context: CliContext | undefined, fn: (target: ActionDockTarget, resolved: ResolvedTarget) => Promise<void>, localOptions?: {
+    /** 本地工程根目录（支持惰性工厂，仅在 local 分支求值）；未提供时按 findProjectRoot 回退 */
+    localRoot?: string | (() => string | undefined);
+    /** 是否扫描全局链接包（对应 scanLinkedPackages） */
+    scanLinkedPackages?: 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 表示当前目录无工程。
+ */
+export declare function resolveLocalPackageRoot(pkgId?: string): string | null;

package/dist/utils/target.js

@@ -0,0 +1,78 @@
+import { createActionDockTarget, findProjectRoot, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
+/**
+ * 高阶目标执行辅助：统一封装「目标解析 → Target 创建 → 业务回调 → try/finally close」样板。
+ *
+ * 回调获得创建好的 target 与解析后的目标拓扑信息；无论回调成功或抛出，
+ * 都保证 target 资源被正确释放，业务异常原样透传。
+ *
+ * @param options 命令选项视图（profile/server/token/package/dataDir）
+ * @param context CLI 上下文
+ * @param fn 业务回调（target 为已创建的门面实例，resolved 为拓扑解析结果）
+ * @param localOptions 本地分支附加选项（如 scanLinkedPackages）与 localRoot 回退策略
+ */
+export async function withTarget(options, context, fn, localOptions) {
+    const resolved = resolveTarget({
+        profile: options.profile,
+        server: options.server,
+        token: options.token,
+    }, context?.customHome);
+    // localRoot 仅在 local 分支求值，避免远端模式下触发包寻址副作用
+    const localRoot = resolved.type === "local"
+        ? (typeof localOptions?.localRoot === "function" ? localOptions.localRoot() : localOptions?.localRoot) ??
+            findProjectRoot() ??
+            undefined
+        : undefined;
+    const target = await createActionDockTarget(resolved.type === "remote"
+        ? {
+            type: "remote",
+            serverUrl: resolved.serverUrl,
+            token: resolved.token,
+        }
+        : {
+            type: "local",
+            projectRoot: localRoot,
+            customHome: context?.customHome,
+            dataDir: options.dataDir || context?.dataDir,
+            ...(localOptions?.scanLinkedPackages !== undefined
+                ? { scanLinkedPackages: localOptions.scanLinkedPackages }
+                : undefined),
+        });
+    try {
+        await fn(target, resolved);
+    }
+    finally {
+        await target.close();
+    }
+}
+/**
+ * 仅远端模式目标执行辅助：创建远端 Target 并保证资源释放。
+ * 适用于 runs cancel 等明确要求远端目标的命令。
+ */
+export async function withRemoteTarget(options, context, fn) {
+    const resolved = resolveTarget({
+        profile: options.profile,
+        server: options.server,
+        token: options.token,
+    }, context?.customHome);
+    const target = await createActionDockTarget({
+        type: "remote",
+        serverUrl: resolved.serverUrl,
+        token: resolved.token,
+    });
+    try {
+        await fn(target, resolved);
+    }
+    finally {
+        await target.close();
+    }
+}
+/**
+ * 目标包根目录解析（含 -P 显式寻址与当前工程回退）。
+ * 供命令在创建 Target 前统一完成包寻址，返回 null 表示当前目录无工程。
+ */
+export function resolveLocalPackageRoot(pkgId) {
+    if (pkgId) {
+        return resolvePackageRoot(pkgId);
+    }
+    return findProjectRoot();
+}

package/dist/utils/utils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
+ * 多个关键字使用 '|'（正则逻辑或）连接。
+ */
+export declare function resolveIntent(optionsIntent?: string, positionalPatterns?: string[]): string | undefined;
+/**
+ * 解析人类可读的字节大小字符串为整数字节数。
+ * 例如：'1mb' -> 1048576, '500kb' -> 512000, '1048576' -> 1048576
+ */
+export declare function parseByteSize(str: string): number;
+/**
+ * 将逗号分隔或多次指定的选项转换为字符串数组。
+ */
+export declare function parseListOption(val: string, prev?: string[]): string[];
+/**
+ * 根据 Package 选项或键前缀解析目标工程物理根目录。
+ */
+export declare function getTargetRoot(packageOption?: string, keyHint?: string): {
+    root: string;
+    key: string;
+};
+/**
+ * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ */
+export declare function getEffectiveOptions(rawOptions: any, cmd?: any): any;
+/**
+ * 解析意图过滤回退策略。
+ * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 人类交互模式默认回退（可被 --no-fallback 关闭）。
+ */
+export declare function resolveFallbackStrategy(options: {
+    fallback?: boolean;
+    json?: boolean;
+    envelope?: boolean;
+}): {
+    isMachine: boolean;
+    shouldFallback: boolean;
+};

package/dist/utils/utils.js

@@ -0,0 +1,111 @@
+import { resolvePackageRoot, findProjectRoot } from "@actiondock/core";
+import { ArgumentError } from "../errors.js";
+/**
+ * 解析意图字符串（从显式 --intent 或位置模式参数聚合）。
+ * 多个关键字使用 '|'（正则逻辑或）连接。
+ */
+export function resolveIntent(optionsIntent, positionalPatterns) {
+    const parts = [];
+    if (optionsIntent && optionsIntent.trim()) {
+        parts.push(optionsIntent.trim());
+    }
+    if (positionalPatterns && positionalPatterns.length > 0) {
+        for (const p of positionalPatterns) {
+            if (typeof p === "string" && p.trim()) {
+                parts.push(p.trim());
+            }
+        }
+    }
+    if (parts.length === 0)
+        return undefined;
+    if (parts.length === 1)
+        return parts[0];
+    return parts.join("|");
+}
+/**
+ * 解析人类可读的字节大小字符串为整数字节数。
+ * 例如：'1mb' -> 1048576, '500kb' -> 512000, '1048576' -> 1048576
+ */
+export function parseByteSize(str) {
+    const trimmed = str.trim().toLowerCase();
+    const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([a-z]+)?$/);
+    if (!match) {
+        const num = Number(trimmed);
+        if (!isNaN(num) && num > 0)
+            return num;
+        throw new ArgumentError(`Invalid byte size format: '${str}'. Examples: '1mb', '500kb', '1048576'`);
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2] || "b";
+    switch (unit) {
+        case "b":
+        case "bytes":
+            return Math.floor(value);
+        case "k":
+        case "kb":
+        case "kib":
+            return Math.floor(value * 1024);
+        case "m":
+        case "mb":
+        case "mib":
+            return Math.floor(value * 1024 * 1024);
+        case "g":
+        case "gb":
+        case "gib":
+            return Math.floor(value * 1024 * 1024 * 1024);
+        default:
+            throw new ArgumentError(`Unsupported byte size unit '${unit}' in '${str}'`);
+    }
+}
+/**
+ * 将逗号分隔或多次指定的选项转换为字符串数组。
+ */
+export function parseListOption(val, prev = []) {
+    const parts = val.split(",").map((s) => s.trim()).filter(Boolean);
+    return [...prev, ...parts];
+}
+/**
+ * 根据 Package 选项或键前缀解析目标工程物理根目录。
+ */
+export function getTargetRoot(packageOption, keyHint) {
+    let targetPackage = packageOption;
+    let effectiveKey = keyHint || "";
+    if (!targetPackage && keyHint && keyHint.includes("/")) {
+        const slashIdx = keyHint.lastIndexOf("/");
+        targetPackage = keyHint.slice(0, slashIdx);
+        effectiveKey = keyHint.slice(slashIdx + 1);
+    }
+    const root = resolvePackageRoot(targetPackage) || (targetPackage ? null : findProjectRoot());
+    if (!root) {
+        if (targetPackage) {
+            throw new ArgumentError(`Package '${targetPackage}' not found in linked packages or path`);
+        }
+        else {
+            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found). Please specify -P, --package <id> or cd into a project directory.");
+        }
+    }
+    return { root, key: effectiveKey };
+}
+/**
+ * 聚合命令自身选项与根程序全局选项（如 --json、--envelope、--data-dir 等）。
+ */
+export function getEffectiveOptions(rawOptions, cmd) {
+    if (cmd && typeof cmd.optsWithGlobals === "function") {
+        return { ...cmd.optsWithGlobals(), ...rawOptions };
+    }
+    return rawOptions || {};
+}
+/**
+ * 解析意图过滤回退策略。
+ * 机器输出模式（--json/--envelope）仅在显式传 --fallback 时回退，
+ * 人类交互模式默认回退（可被 --no-fallback 关闭）。
+ */
+export function resolveFallbackStrategy(options) {
+    const isMachine = Boolean(options.json || options.envelope);
+    const fallbackExplicit = options.fallback === true ||
+        (Array.isArray(process.argv) && process.argv.includes("--fallback"));
+    return {
+        isMachine,
+        shouldFallback: isMachine ? fallbackExplicit : options.fallback !== false,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/cli",
-  "version": "2.0.12",
+  "version": "2.2.1",
   "description": "ActionDock CLI facade for developing, testing, building, and exporting standalone Agent Actions and Skills",
   "type": "module",
   "bin": {
@@ -23,25 +23,23 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=24.12.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "bun run ../../scripts/build.ts",
-    "test": "bun test"
+    "build": "node ../../scripts/build.ts",
+    "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/builder": "^2.0.12",
-    "@actiondock/core": "^2.0.12",
-    "@actiondock/mcp": "^2.0.12",
-    "@actiondock/runtime-cli": "^2.0.12",
-    "@actiondock/runtime-node": "^2.0.12",
-    "@actiondock/sdk": "^2.0.12",
-    "commander": "^13.1.0",
-    "tsx": "^4.19.3"
+    "@actiondock/builder": "^2.2.1",
+    "@actiondock/core": "^2.2.1",
+    "@actiondock/mcp": "^2.2.1",
+    "@actiondock/runtime-node": "^2.2.1",
+    "@actiondock/sdk": "^2.2.1",
+    "commander": "^13.1.0"
   },
   "devDependencies": {
     "typescript": "^5.7.0"

package/dist/commands/action/index.d.ts

@@ -1,16 +0,0 @@
-import type { Command } from "commander";
-import { executeAction } from "@actiondock/runtime-cli";
-export { executeAction };
-export { registerActionCreateCommand } from "./create";
-export { registerActionSyncCommand } from "./sync";
-export { registerActionListCommand } from "./list";
-export { registerActionShowCommand } from "./show";
-export { registerActionValidateCommand } from "./validate";
-export { registerActionRunCommand } from "./run";
-/**
- * 注册 Action 相关的 CLI 命令集合。
- * 委托 list, show, validate, run 至 @actiondock/runtime-cli，保留开发者专用的 create 与 sync 命令。
- *
- * @param program Commander 根程序对象
- */
-export declare function registerActionCommands(program: Command): void;

package/dist/commands/action/list.d.ts

@@ -1,5 +0,0 @@
-import type { Command } from "commander";
-/**
- * @deprecated 核心逻辑已统一下沉至 @actiondock/runtime-cli
- */
-export declare function registerActionListCommand(actionCmd: Command): void;

package/dist/commands/action/run.d.ts

@@ -1,4 +0,0 @@
-import { executeAction } from "@actiondock/runtime-cli";
-import type { Command } from "commander";
-export { executeAction };
-export declare function registerActionRunCommand(actionCmd: Command, program: Command): void;

package/dist/commands/action/show.d.ts

@@ -1,5 +0,0 @@
-import type { Command } from "commander";
-/**
- * @deprecated 核心逻辑已统一下沉至 @actiondock/runtime-cli
- */
-export declare function registerActionShowCommand(actionCmd: Command): void;

package/dist/commands/action/sync.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from "commander";
-export declare function registerActionSyncCommand(actionCmd: Command): void;

package/dist/commands/action/validate.d.ts

@@ -1,5 +0,0 @@
-import type { Command } from "commander";
-/**
- * @deprecated 核心逻辑已统一下沉至 @actiondock/runtime-cli
- */
-export declare function registerActionValidateCommand(actionCmd: Command): void;

package/dist/commands/action.d.ts

@@ -1 +0,0 @@
-export * from "./action/index";

package/dist/commands/config.d.ts

@@ -1,2 +0,0 @@
-import type { Command } from "commander";
-export declare function registerConfigCommands(program: Command): void;