@actiondock/cli 2.9.1 → 2.11.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
@@ -77,30 +336,69 @@ export function createCliProgram(context) {
     program.exitOverride((err) => {
         throw err;
     });
-    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);
+    if (context?.stdout || context?.stderr) {
+        program.configureOutput({
+            writeOut: (str) => {
+                if (context.stdout)
+                    context.stdout(str);
+                else
+                    process.stdout.write(str);
+            },
+            writeErr: (str) => {
+                if (context.stderr)
+                    context.stderr(str);
+                else
+                    process.stderr.write(str);
+            },
+        });
+    }
+    program.addHelpText("after", `
+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.`);
+    // 注册轻量级占位命令声明（零重型模块导入开销）
+    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/info.js

@@ -9,6 +9,26 @@ import { applyTargetOptions, getEffectiveOptions, resolveFallbackStrategy, resol
  * 将远端信息响应归一为本地工程详情视图。
  */
 function remoteInfoToDetail(remoteInfo) {
+    const actionsMap = new Map();
+    const rawActions = remoteInfo.actionsDetail || remoteInfo.actions || [];
+    for (const a of rawActions) {
+        if (typeof a === "string") {
+            actionsMap.set(a, { id: a });
+        }
+        else if (a && typeof a === "object") {
+            actionsMap.set(a.id, { id: a.id, description: a.description });
+        }
+    }
+    const playbooksMap = new Map();
+    const rawPlaybooks = remoteInfo.playbooksDetail || remoteInfo.playbooks || [];
+    for (const pb of rawPlaybooks) {
+        if (typeof pb === "string") {
+            playbooksMap.set(pb, { id: pb });
+        }
+        else if (pb && typeof pb === "object") {
+            playbooksMap.set(pb.id, { id: pb.id, description: pb.description });
+        }
+    }
     return {
         id: remoteInfo.id,
         name: remoteInfo.name || remoteInfo.id,
@@ -17,12 +37,14 @@ function remoteInfoToDetail(remoteInfo) {
         projectRoot: remoteInfo.path || remoteInfo.projectRoot || "",
         actionsDir: "remote",
         playbooksDir: "remote",
-        actionsCount: remoteInfo.actionsCount || (remoteInfo.actions ? remoteInfo.actions.length : 0),
-        playbooksCount: remoteInfo.playbooksCount || (remoteInfo.playbooks ? remoteInfo.playbooks.length : 0),
-        actions: (remoteInfo.actionsDetail || remoteInfo.actions || []).map((a) => typeof a === "string" ? a : a.id),
-        playbooks: (remoteInfo.playbooksDetail || remoteInfo.playbooks || []).map((pb) => typeof pb === "string" ? pb : pb.id),
+        actionsCount: actionsMap.size,
+        playbooksCount: playbooksMap.size,
+        actions: Array.from(actionsMap.keys()),
+        playbooks: Array.from(playbooksMap.keys()),
         configDeclared: Object.keys(remoteInfo.configDeclared || {}),
         configDef: remoteInfo.configDeclared,
+        actionsMap,
+        playbooksMap,
     };
 }
 /**
@@ -116,6 +138,9 @@ export function registerInfoCommand(program, context) {
         }
         // 扫描本地候选包（当前工程根目录 + 全局已链接包）
         const { currentRoot, aggregated } = scanLocalAggregatedPackages(context);
+        const infoHints = [
+            "Tip: Run 'ad info <package-id>' to view detailed package configuration and schema.",
+        ];
         // 无关键字过滤场景
         if (!effectiveIntent) {
             if (currentRoot) {
@@ -130,7 +155,7 @@ export function registerInfoCommand(program, context) {
                 });
                 return;
             }
-            renderResult({ linkedPackages: aggregated }, {
+            renderResult({ linkedPackages: aggregated, hints: infoHints }, {
                 ...outOpts,
                 humanFormatter: () => renderAggregatedPackages(aggregated),
             });
@@ -147,7 +172,7 @@ export function registerInfoCommand(program, context) {
         }
         if (aggregated.length === 0) {
             if (isMachine) {
-                renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false }, outOpts);
+                renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false, hints: infoHints }, outOpts);
                 return;
             }
             throw new ExecutionError(`No ActionDock project or linked packages available to match '${effectiveIntent}'`);
@@ -164,14 +189,14 @@ export function registerInfoCommand(program, context) {
         if (filterRes.matchedCount === 0) {
             if (!filterRes.isFallback) {
                 if (isMachine) {
-                    renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false }, outOpts);
+                    renderResult({ linkedPackages: [], matchedCount: 0, isFallback: false, hints: infoHints }, outOpts);
                     return;
                 }
                 throw new ExecutionError(`No packages matched intent '${effectiveIntent}'`);
             }
             // 回退模式：展示全部包并附带提示
             if (isMachine) {
-                renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0 }, outOpts);
+                renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0, hints: infoHints }, outOpts);
                 return;
             }
             renderResult({ linkedPackages: filterRes.items, isFallback: true, matchedCount: 0 }, {
@@ -183,7 +208,7 @@ export function registerInfoCommand(program, context) {
         }
         // 机器模式下搜索：稳定返回列表结构，不因为 matchedCount === 1 突变为详情
         if (isMachine) {
-            renderResult({ linkedPackages: filterRes.items, matchedCount: filterRes.matchedCount, isFallback: false }, outOpts);
+            renderResult({ linkedPackages: filterRes.items, matchedCount: filterRes.matchedCount, isFallback: false, hints: infoHints }, outOpts);
             return;
         }
         // 人类终端交互：精确匹配单个包展开详情

package/dist/commands/list.js

@@ -63,8 +63,19 @@ export function attachListCommand(parent, context) {
                 };
             });
             const filterRes = filterWithFallbackInfo(rawList, effectiveIntent, [(a) => a.id, (a) => a.description], shouldFallback);
-            if (filterRes.isFallback && isMachine) {
-                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+            const hints = [
+                "Tip: For composite or multi-step tasks, check 'ad playbook list' for standard operating procedures.",
+            ];
+            if (isMachine) {
+                if (filterRes.isFallback) {
+                    renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0, hints }, { json: options.json, context });
+                    return;
+                }
+                renderResult({
+                    items: filterRes.items,
+                    ...(filterRes.matchedCount !== undefined ? { matchedCount: filterRes.matchedCount } : {}),
+                    hints,
+                }, { json: options.json, context });
                 return;
             }
             const title = resolved.type === "remote"

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({