@actiondock/cli 2.10.0 → 2.12.0

package/dist/commands/index.js

@@ -1,29 +1,6 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { Command } from "commander";
-import { registerActionCommands } from "./action/index.js";
-import { registerAddCommand } from "./add.js";
-import { registerBuildCommand } from "./build.js";
-import { registerConfigCommands } from "./config/index.js";
-import { registerDescribeCommand } from "./describe.js";
-import { registerDoctorCommand } from "./doctor.js";
-import { registerExportCommand } from "./export.js";
-import { registerGenerateCommands } from "./generate.js";
-import { registerInfoCommand } from "./info.js";
-import { registerInitCommand } from "./init.js";
-import { registerLinkCommands } from "./link.js";
-import { registerListCommand } from "./list.js";
-import { registerMcpCommands } from "./mcp.js";
-import { registerPackCommand } from "./pack.js";
-import { registerPlaybookCommands } from "./playbook.js";
-import { registerProfileCommands } from "./profile.js";
-import { registerRemoveCommand } from "./remove.js";
-import { registerRunCommand } from "./run.js";
-import { registerRunsCommands } from "./runs.js";
-import { registerServeCommand } from "./serve.js";
-import { registerStateCommands } from "./state.js";
-import { registerTestCommand } from "./test.js";
-import { registerValidateCommand } from "./validate.js";
 /**
  * 读取 CLI 自身 package.json 的版本号（单一事实源）。
  * 兼容源码运行（src/commands）与构建产物运行（dist/commands）两种目录层级。
@@ -62,6 +39,288 @@ function applyCommonOptions(cmd) {
         applyCommonOptions(sub);
     }
 }
+/**
+ * 动态加载子命令实现模块（兼容构建产物 .js 与开发环境 .ts）。
+ */
+function importCommandModule(relativePath) {
+    const ext = existsSync(join(import.meta.dirname, "run.js")) ? ".js" : ".ts";
+    return import(`${relativePath}${ext}`);
+}
+const COMMAND_DECLARATIONS = [
+    {
+        name: "init",
+        spec: "init [directory]",
+        description: "Initialize a new ActionDock project",
+        loader: "./init",
+        registerFn: "registerInitCommand",
+    },
+    {
+        name: "add",
+        spec: "add <package>",
+        description: "Install and lock an Action package dependency into current project",
+        loader: "./add",
+        registerFn: "registerAddCommand",
+    },
+    {
+        name: "remove",
+        spec: "remove <package>",
+        description: "Remove an Action package dependency and update actiondock.lock.json",
+        loader: "./remove",
+        registerFn: "registerRemoveCommand",
+    },
+    {
+        name: "action",
+        spec: "action",
+        description: "Manage Action definitions and scaffolding (create)",
+        loader: "./action/create",
+        registerFn: "registerActionCommands",
+    },
+    {
+        name: "info",
+        spec: "info [patterns...]",
+        description: "Display information about current project, linked package, or remote target",
+        loader: "./info",
+        registerFn: "registerInfoCommand",
+    },
+    {
+        name: "doctor",
+        spec: "doctor",
+        description: "Check ActionDock environment, registry health, and project diagnostics",
+        loader: "./doctor",
+        registerFn: "registerDoctorCommand",
+    },
+    {
+        name: "list",
+        spec: "list [patterns...]",
+        description: "List actions in current project, linked packages, or remote profile",
+        loader: "./list",
+        registerFn: "registerListCommand",
+    },
+    {
+        name: "describe",
+        spec: "describe <id>",
+        description: "Show action definition, schema, and description",
+        loader: "./describe",
+        registerFn: "registerDescribeCommand",
+    },
+    {
+        name: "run",
+        spec: "run <id> [params...]",
+        description: "Execute an action (from current project, linked packages, or remote profile)",
+        loader: "./run",
+        registerFn: "registerRunCommand",
+    },
+    {
+        name: "validate",
+        spec: "validate [id]",
+        description: "Validate action schemas and definitions",
+        loader: "./validate",
+        registerFn: "registerValidateCommand",
+    },
+    {
+        name: "generate",
+        spec: "generate",
+        description: "Generate project artifacts such as TypeScript declarations",
+        loader: "./generate",
+        registerFn: "registerGenerateCommands",
+    },
+    {
+        name: "playbook",
+        spec: "playbook",
+        description: "Manage task Playbooks (Task SOPs for AI Agents)",
+        loader: "./playbook",
+        registerFn: "registerPlaybookCommands",
+    },
+    {
+        name: "config",
+        spec: "config",
+        description: "Manage runtime configuration store (Global & Project-level)",
+        loader: "./config/index",
+        registerFn: "registerConfigCommands",
+    },
+    {
+        name: "state",
+        spec: "state",
+        description: "Inspect and manage Shared State store",
+        loader: "./state",
+        registerFn: "registerStateCommands",
+    },
+    {
+        name: "runs",
+        spec: "runs",
+        description: "Inspect action execution history",
+        loader: "./runs",
+        registerFn: "registerRunsCommands",
+    },
+    {
+        name: "test",
+        spec: "test [pattern]",
+        description: "Run project tests using configured test runner (node:test or bun test)",
+        loader: "./test",
+        registerFn: "registerTestCommand",
+    },
+    {
+        name: "build",
+        spec: "build",
+        description: "Build project actions into a runnable Node.js delivery directory",
+        loader: "./build",
+        registerFn: "registerBuildCommand",
+    },
+    {
+        name: "pack",
+        spec: "pack",
+        description: "Pack Action package into a standard npm tarball (.tgz) for distribution",
+        loader: "./pack",
+        registerFn: "registerPackCommand",
+    },
+    {
+        name: "export",
+        spec: "export",
+        description: "Export project artifacts",
+        loader: "./export",
+        registerFn: "registerExportCommand",
+    },
+    {
+        name: "link",
+        spec: "link [path]",
+        description: "Link local Action package(s) or workspace directory into global registry for instant cross-directory execution",
+        loader: "./link",
+        registerFn: "registerLinkCommands",
+        linkedNames: ["link", "unlink"],
+    },
+    {
+        name: "unlink",
+        spec: "unlink [identifier]",
+        description: "Unlink a package, workspace, or prune stale entries from global developer registry",
+        loader: "./link",
+        registerFn: "registerLinkCommands",
+        linkedNames: ["link", "unlink"],
+    },
+    {
+        name: "profile",
+        spec: "profile",
+        description: "Manage multi-cloud and remote execution profiles",
+        loader: "./profile",
+        registerFn: "registerProfileCommands",
+    },
+    {
+        name: "serve",
+        spec: "serve",
+        description: "Start the ActionDock lightweight HTTP Runner server for remote execution",
+        loader: "./serve",
+        registerFn: "registerServeCommand",
+    },
+    {
+        name: "mcp",
+        spec: "mcp",
+        description: "Model Context Protocol (MCP) server for ActionDock Actions (STDIO default)",
+        loader: "./mcp",
+        registerFn: "registerMcpCommands",
+    },
+];
+const RUNTIME_EXECUTABLES = new Set(["node", "bun", "tsx", "deno"]);
+/**
+ * 判断命令行参数数组是否以宿主运行环境（node、bun、tsx 等）及入口脚本为前置元素。
+ */
+export function isNodeArgv(argv) {
+    if (!Array.isArray(argv) || argv.length < 2)
+        return false;
+    const first = argv[0];
+    if (!first || first.startsWith("-"))
+        return false;
+    const base = first.split(/[/\\]/).pop()?.toLowerCase().replace(/\.exe$/i, "") ?? "";
+    if (RUNTIME_EXECUTABLES.has(base)) {
+        return true;
+    }
+    // 严格排除已知子命令与内置 help 命令，杜绝将纯用户子命令参数错误识别为运行时
+    if (COMMAND_DECLARATIONS.some((d) => d.name === first || d.alias === first) ||
+        first === "help") {
+        return false;
+    }
+    return false;
+}
+/**
+ * 从命令行参数数组中解析出目标子命令名称（跳过全局选项与启动包装参数）。
+ *
+ * @param argv 命令行原始参数数组
+ * @param parseOptions Commander 解析选项（如 { from: 'user' }）
+ * @returns 目标子命令名称或 null
+ */
+export function resolveTargetSubcommand(argv, parseOptions) {
+    let startIndex = 0;
+    if (parseOptions?.from === "user") {
+        startIndex = 0;
+    }
+    else if (parseOptions?.from === "eval") {
+        startIndex = 1;
+    }
+    else if (parseOptions?.from === "node") {
+        startIndex = 2;
+    }
+    else if (isNodeArgv(argv)) {
+        startIndex = 2;
+    }
+    else {
+        startIndex = 0;
+    }
+    let i = startIndex;
+    while (i < argv.length) {
+        const arg = argv[i];
+        if (arg === "--data-dir") {
+            i += 2;
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            i++;
+            continue;
+        }
+        // 特殊处理 Commander 内置 help 命令（如 ad help run）
+        if (arg === "help" && i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+            return argv[i + 1];
+        }
+        return arg;
+    }
+    return null;
+}
+/**
+ * 按需加载并挂载目标子命令模块。
+ * 基于 Promise 缓存机制消除并发调用时的竞态条件。
+ */
+async function loadAndAttachCommand(targetSubcommand, program, placeholders, loadingPromises, context) {
+    const decl = COMMAND_DECLARATIONS.find((d) => d.name === targetSubcommand || d.alias === targetSubcommand);
+    if (!decl)
+        return;
+    const existing = loadingPromises.get(decl.loader);
+    if (existing) {
+        return existing;
+    }
+    const loadPromise = (async () => {
+        // 移除对应的占位命令节点
+        const toRemove = decl.linkedNames || [decl.name];
+        for (const name of toRemove) {
+            const p = placeholders.get(name);
+            if (p) {
+                const idx = program.commands.indexOf(p);
+                if (idx !== -1) {
+                    program.commands.splice(idx, 1);
+                }
+                placeholders.delete(name);
+            }
+        }
+        // 动态导入实际命令模块并挂载真实命令
+        const mod = await importCommandModule(decl.loader);
+        const fn = mod[decl.registerFn];
+        if (typeof fn === "function") {
+            fn(program, context);
+            applyCommonOptions(program);
+        }
+    })();
+    loadingPromises.set(decl.loader, loadPromise);
+    loadPromise.catch(() => {
+        loadingPromises.delete(decl.loader);
+    });
+    return loadPromise;
+}
 export function createCliProgram(context) {
     const program = new Command();
     program
@@ -97,30 +356,49 @@ export function createCliProgram(context) {
 Workflow Guidance:
   For multi-step workflows, run 'ad playbook list' before invoking atomic actions.
   Run 'ad info [intent]' to discover packages and playbooks by keyword.`);
-    registerInitCommand(program);
-    registerAddCommand(program, context);
-    registerRemoveCommand(program, context);
-    registerActionCommands(program, context);
-    registerInfoCommand(program, context);
-    registerDoctorCommand(program, context);
-    registerListCommand(program, context);
-    registerDescribeCommand(program, context);
-    registerRunCommand(program, context);
-    registerValidateCommand(program, context);
-    registerGenerateCommands(program, context);
-    registerPlaybookCommands(program, context);
-    registerConfigCommands(program, context);
-    registerStateCommands(program, context);
-    registerRunsCommands(program, context);
-    registerTestCommand(program);
-    registerBuildCommand(program, context);
-    registerPackCommand(program, context);
-    registerExportCommand(program, context);
-    registerLinkCommands(program);
-    registerProfileCommands(program);
-    registerServeCommand(program, context);
-    registerMcpCommands(program, context);
+    // 注册轻量级占位命令声明（零重型模块导入开销）
+    const placeholders = new Map();
+    for (const decl of COMMAND_DECLARATIONS) {
+        const cmd = program.command(decl.spec).description(decl.description);
+        if (decl.alias) {
+            cmd.alias(decl.alias);
+        }
+        placeholders.set(decl.name, cmd);
+    }
     applyCommonOptions(program);
+    // 拦截 parseAsync 以在实际执行或具体帮助展示时按需动态加载真实子命令
+    const originalParseAsync = program.parseAsync.bind(program);
+    const loadingPromises = new Map();
+    program.parseAsync = async function (argv, parseOptions) {
+        const targetArgv = argv || process.argv;
+        const targetSubcommand = resolveTargetSubcommand(targetArgv, parseOptions);
+        if (targetSubcommand) {
+            await loadAndAttachCommand(targetSubcommand, program, placeholders, loadingPromises, context);
+        }
+        return originalParseAsync(argv, parseOptions);
+    };
     return program;
 }
-export { registerActionCommands, registerAddCommand, registerBuildCommand, registerConfigCommands, registerDescribeCommand, registerDoctorCommand, registerExportCommand, registerGenerateCommands, registerInfoCommand, registerInitCommand, registerLinkCommands, registerListCommand, registerMcpCommands, registerPackCommand, registerPlaybookCommands, registerProfileCommands, registerRemoveCommand, registerRunCommand, registerRunsCommands, registerServeCommand, registerStateCommands, registerTestCommand, registerValidateCommand, };
+export const registerActionCommands = (program, context) => importCommandModule("./action/create").then((m) => m.registerActionCommands(program, context));
+export const registerAddCommand = (program, context) => importCommandModule("./add").then((m) => m.registerAddCommand(program, context));
+export const registerBuildCommand = (program, context) => importCommandModule("./build").then((m) => m.registerBuildCommand(program, context));
+export const registerConfigCommands = (program, context) => importCommandModule("./config/index").then((m) => m.registerConfigCommands(program, context));
+export const registerDescribeCommand = (program, context) => importCommandModule("./describe").then((m) => m.registerDescribeCommand(program, context));
+export const registerDoctorCommand = (program, context) => importCommandModule("./doctor").then((m) => m.registerDoctorCommand(program, context));
+export const registerExportCommand = (program, context) => importCommandModule("./export").then((m) => m.registerExportCommand(program, context));
+export const registerGenerateCommands = (program, context) => importCommandModule("./generate").then((m) => m.registerGenerateCommands(program, context));
+export const registerInfoCommand = (program, context) => importCommandModule("./info").then((m) => m.registerInfoCommand(program, context));
+export const registerInitCommand = (program) => importCommandModule("./init").then((m) => m.registerInitCommand(program));
+export const registerLinkCommands = (program) => importCommandModule("./link").then((m) => m.registerLinkCommands(program));
+export const registerListCommand = (program, context) => importCommandModule("./list").then((m) => m.registerListCommand(program, context));
+export const registerMcpCommands = (program, context) => importCommandModule("./mcp").then((m) => m.registerMcpCommands(program, context));
+export const registerPackCommand = (program, context) => importCommandModule("./pack").then((m) => m.registerPackCommand(program, context));
+export const registerPlaybookCommands = (program, context) => importCommandModule("./playbook").then((m) => m.registerPlaybookCommands(program, context));
+export const registerProfileCommands = (program) => importCommandModule("./profile").then((m) => m.registerProfileCommands(program));
+export const registerRemoveCommand = (program, context) => importCommandModule("./remove").then((m) => m.registerRemoveCommand(program, context));
+export const registerRunCommand = (program, context) => importCommandModule("./run").then((m) => m.registerRunCommand(program, context));
+export const registerRunsCommands = (program, context) => importCommandModule("./runs").then((m) => m.registerRunsCommands(program, context));
+export const registerServeCommand = (program, context) => importCommandModule("./serve").then((m) => m.registerServeCommand(program, context));
+export const registerStateCommands = (program, context) => importCommandModule("./state").then((m) => m.registerStateCommands(program, context));
+export const registerTestCommand = (program) => importCommandModule("./test").then((m) => m.registerTestCommand(program));
+export const registerValidateCommand = (program, context) => importCommandModule("./validate").then((m) => m.registerValidateCommand(program, context));

package/dist/commands/mcp.js

@@ -116,7 +116,6 @@ export function registerMcpCommands(program, context) {
             const platform = createNodePlatform({
                 customHome: context?.customHome,
                 dataDir: options.dataDir || context?.dataDir,
-                rootDir: projectRoots?.[0],
             });
             const { startMcpHttpServer } = await import("@actiondock/mcp");
             const server = await startMcpHttpServer({

package/dist/commands/playbook.js

@@ -3,11 +3,11 @@ import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { assertPathWithinRoot, loadActions, loadManifest, loadPlaybooks, saveManifest, filterWithFallbackInfo, } from "@actiondock/core/project";
 import { DefaultActionCatalog, PackageGraphBuilder, resolveAction, resolvePlaybook, } from "@actiondock/core/graph";
 import { fetchRemotePlaybooks, fetchRemotePlaybookShow, } from "@actiondock/core/profile";
-import { findProjectRoot, loadProjectConfig, } from "@actiondock/core";
-import { listLinkedPackages, resolvePackageRoot, } from "@actiondock/core/registry";
-import { ArgumentError, CliError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, notInProjectError, packageNotFoundError, wrapAsExecutionError, } from "../errors.js";
+import { loadProjectConfig, } from "@actiondock/core";
+import { listLinkedPackages, } from "@actiondock/core/registry";
+import { ArgumentError, CliError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, wrapAsExecutionError, } from "../errors.js";
 import { renderPlaybookDetail, renderPlaybookList, renderResult, writeStdout, } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, resolveFallbackStrategy, resolveIntent, resolveTargetFromOptions, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, remoteTargetSuffix, requirePackageRoot, resolveFallbackStrategy, resolveIntent, resolveLocalPackageRoot, resolveTargetFromOptions, } from "../utils/index.js";
 /**
  * 注册 Playbook 命令集合（list, show, validate, create）。
  *
@@ -55,16 +55,9 @@ export function registerPlaybookCommands(program, context) {
             return;
         }
         // 2. 本地工程模式
-        let targetRoot = null;
-        if (options.package) {
-            targetRoot = resolvePackageRoot(options.package);
-            if (!targetRoot) {
-                throw packageNotFoundError(options.package);
-            }
-        }
-        else {
-            targetRoot = findProjectRoot();
-        }
+        const targetRoot = options.package
+            ? requirePackageRoot(options.package).root
+            : resolveLocalPackageRoot();
         if (targetRoot) {
             const config = loadProjectConfig(targetRoot);
             const playbooks = loadPlaybooks(targetRoot, config.playbooksDir);
@@ -213,16 +206,13 @@ export function registerPlaybookCommands(program, context) {
         // 2. 本地项目模式
         let showTarget = id;
         if (options.package && !id.includes("/")) {
-            const pkgRoot = resolvePackageRoot(options.package);
-            if (!pkgRoot) {
-                throw packageNotFoundError(options.package);
-            }
+            requirePackageRoot(options.package);
             showTarget = `${options.package}/${id}`;
         }
         let resolved;
         try {
             const graph = new PackageGraphBuilder({
-                root: findProjectRoot() || undefined,
+                root: resolveLocalPackageRoot() || undefined,
                 customHome: context?.customHome,
                 allowDevLinks: true,
             }).buildSync();
@@ -259,16 +249,9 @@ export function registerPlaybookCommands(program, context) {
         .option("--json", "Output as JSON")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
-        let root = null;
-        if (options.package) {
-            root = resolvePackageRoot(options.package);
-            if (!root) {
-                throw packageNotFoundError(options.package);
-            }
-        }
-        else {
-            root = findProjectRoot();
-        }
+        const root = options.package
+            ? requirePackageRoot(options.package).root
+            : resolveLocalPackageRoot();
         const targets = [];
         if (root) {
             const config = loadProjectConfig(root);
@@ -288,7 +271,7 @@ export function registerPlaybookCommands(program, context) {
             let resolved;
             try {
                 const graph = new PackageGraphBuilder({
-                    root: findProjectRoot() || undefined,
+                    root: resolveLocalPackageRoot() || undefined,
                     customHome: context?.customHome,
                     allowDevLinks: true,
                 }).buildSync();
@@ -327,7 +310,7 @@ export function registerPlaybookCommands(program, context) {
         }
         const results = [];
         const graph = new PackageGraphBuilder({
-            root: findProjectRoot() || undefined,
+            root: resolveLocalPackageRoot() || undefined,
             customHome: context?.customHome,
             allowDevLinks: true,
         }).buildSync();
@@ -409,10 +392,7 @@ export function registerPlaybookCommands(program, context) {
     });
 }
 export function handlePlaybookCreate(id, options, context) {
-    const root = findProjectRoot();
-    if (!root) {
-        throw notInProjectError();
-    }
+    const { root } = requirePackageRoot(undefined);
     try {
         const config = loadProjectConfig(root);
         const pbDir = resolve(root, config.playbooksDir || "playbooks");

package/dist/commands/profile.js

@@ -1,4 +1,5 @@
-import { addProfile, checkRemoteHealth, getProfile, listProfiles, loadProfiles, removeProfile, resolveProfileToken, resolveTarget, toSnakeUpperCase, updateProfile, useProfile, } from "@actiondock/core/profile";
+import { addProfile, checkRemoteHealth, getProfile, listProfiles, loadProfiles, removeProfile, resolveProfileToken, resolveTarget, updateProfile, useProfile, } from "@actiondock/core/profile";
+import { toSnakeUpperCase } from "@actiondock/core";
 import { filterWithFallbackInfo, maskSecretValue, } from "@actiondock/core/project";
 import { ArgumentError, ExecutionError, wrapAsExecutionError, } from "../errors.js";
 import { renderResult, writeStderr, writeStdout } from "../renderer.js";

package/dist/commands/remove.js

@@ -79,7 +79,7 @@ export function registerRemoveCommand(program, context) {
             }
             // 调用包管理器执行卸载（说明符白名单校验，消除 win32 shell 拼接注入面）
             assertSafePackageSpec(npmPackageName);
-            const installCmd = getInstallCommand(root);
+            const installCmd = await getInstallCommand(root);
             const pm = installCmd[0];
             const args = pm === "bun" ? ["remove", npmPackageName] : ["uninstall", npmPackageName, "--ignore-scripts"];
             const uninstallProc = await spawnAsync(pm, args, {

package/dist/commands/run.d.ts

@@ -2,13 +2,18 @@ import { type InvocationControl } from "@actiondock/core/server";
 import type { ExecutionResult } from "@actiondock/sdk";
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+export interface RawExecutionRenderOptions {
+    textField?: string;
+}
 /**
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
- * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
+ * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 显式或声明式正文输出：指定 textField 时仅输出该自有字符串字段至 stdout，剩余字段以 JSON 对象形式输出至 stderr。
+ * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
-export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext): void;
+export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext, options?: RawExecutionRenderOptions): void;
 /**
  * 统一执行 Action 核心逻辑（使用 ActionDockService 服务端口）。
  *