@actiondock/cli 2.9.1 → 2.11.0

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）。
  *
@@ -31,6 +31,9 @@ export function registerPlaybookCommands(program, context) {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
         const { shouldFallback, isMachine } = resolveFallbackStrategy(options);
+        const hints = [
+            "Tip: Run 'ad playbook show <id>' to inspect procedure steps before execution.",
+        ];
         // 1. 远端服务分支
         const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
@@ -40,6 +43,10 @@ export function registerPlaybookCommands(program, context) {
                 allowInsecureHttp: Boolean(options.allowInsecureHttp),
                 insecure: target.insecure,
             });
+            if (isMachine) {
+                renderResult({ items: remotePbs, hints }, { json: options.json, context });
+                return;
+            }
             renderResult(remotePbs, {
                 json: options.json,
                 humanFormatter: () => renderPlaybookList(remotePbs, `Playbooks ${remoteTargetSuffix(target)}`, false, effectiveIntent),
@@ -48,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);
@@ -67,8 +67,16 @@ export function registerPlaybookCommands(program, context) {
                 packageId: config.id,
             }));
             const filterRes = filterWithFallbackInfo(rawList, effectiveIntent, [(p) => p.id, (p) => p.description], shouldFallback);
-            if (filterRes.isFallback && isMachine) {
-                renderResult({ items: filterRes.items, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+            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;
             }
             renderResult(filterRes.items, {
@@ -81,6 +89,10 @@ export function registerPlaybookCommands(program, context) {
         // 3. 扫描所有已链接的外部包
         const linkedList = listLinkedPackages(context?.customHome);
         if (linkedList.length === 0) {
+            if (isMachine) {
+                renderResult({ packages: [], hints }, { json: options.json, context });
+                return;
+            }
             renderResult([], {
                 json: options.json,
                 humanFormatter: () => NO_PROJECT_NO_LINKED_MESSAGE,
@@ -136,8 +148,12 @@ export function registerPlaybookCommands(program, context) {
                 isFallback = true;
             }
         }
-        if (isFallback && isMachine) {
-            renderResult({ packages: filteredPackages, isFallback: true, matchedCount: 0 }, { json: options.json, context });
+        if (isMachine) {
+            if (isFallback) {
+                renderResult({ packages: filteredPackages, isFallback: true, matchedCount: 0, hints }, { json: options.json, context });
+                return;
+            }
+            renderResult({ packages: filteredPackages, hints }, { json: options.json, context });
             return;
         }
         renderResult(filteredPackages, {
@@ -150,6 +166,7 @@ export function registerPlaybookCommands(program, context) {
                         lines.push(`    - ${pb.id.padEnd(26)} ${pb.description || ""}`);
                     }
                 }
+                lines.push("\nTip: Run 'ad playbook show <id>' to inspect procedure steps before execution.");
                 return lines.join("\n");
             },
             context,
@@ -169,39 +186,46 @@ export function registerPlaybookCommands(program, context) {
         // 1. 远端服务分支
         const target = resolveTargetFromOptions(options, context);
         if (target.type === "remote") {
-            const detail = await fetchRemotePlaybookShow(target.serverUrl, id, target.token, {
-                allowInsecureHttp: Boolean(options.allowInsecureHttp),
-                insecure: target.insecure,
-            });
-            renderResult(detail, {
-                json: options.json,
-                humanFormatter: () => renderPlaybookDetail(detail),
-                context,
-            });
-            return;
+            try {
+                const detail = await fetchRemotePlaybookShow(target.serverUrl, id, target.token, {
+                    allowInsecureHttp: Boolean(options.allowInsecureHttp),
+                    insecure: target.insecure,
+                });
+                renderResult(detail, {
+                    json: options.json,
+                    humanFormatter: () => renderPlaybookDetail(detail),
+                    context,
+                });
+                return;
+            }
+            catch (err) {
+                const hint = "Tip: Run 'ad playbook list' to discover available playbooks.";
+                throw new ArgumentError(`${err.message}\n${hint}`, err?.details, err?.code, hint);
+            }
         }
         // 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();
             resolved = resolvePlaybook(showTarget, { graph });
         }
         catch (err) {
-            throw new ArgumentError(err.message);
+            const hint = "Tip: Run 'ad playbook list' to discover available playbooks.";
+            throw new ArgumentError(`${err.message}\n${hint}`, err?.details, err?.code, hint);
         }
         const pb = resolved.playbook;
+        const hints = [
+            "Tip: Follow steps sequentially. Invoke constituent actions using 'ad run <action> [options] -- <assignments...>'.",
+        ];
         const detail = {
             id: pb.id,
             packageId: resolved.packageId,
@@ -209,6 +233,7 @@ export function registerPlaybookCommands(program, context) {
             actions: pb.actions,
             filePath: pb.filePath,
             content: pb.content,
+            hints,
         };
         renderResult(detail, {
             json: options.json,
@@ -224,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);
@@ -253,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();
@@ -292,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();
@@ -317,14 +335,14 @@ export function registerPlaybookCommands(program, context) {
                                 resolveAction(actRef, { graph, catalog, caller: target.packageId });
                             }
                             catch (e) {
-                                errors.push(`Referenced cross-package action '${actRef}' not resolvable: ${e.message}`);
+                                errors.push(`Referenced cross-package action '${actRef}' not resolvable: ${e.message}. Hint: Action '${actRef}' not found. Run 'ad action create ${actRef}' to create local action, or 'ad add <pkg>' to install external dependency.`);
                             }
                         }
                         else {
                             const foundInActions = actions.has(actRef);
                             const foundInManifest = Boolean(manifest?.actions?.[actRef]);
                             if (!foundInActions && !foundInManifest) {
-                                errors.push(`Referenced action '${actRef}' not found in project actions`);
+                                errors.push(`Referenced action '${actRef}' not found in project actions. Hint: Action '${actRef}' not found. Run 'ad action create ${actRef}' to create local action, or 'ad add <pkg>' to install external dependency.`);
                             }
                         }
                     }
@@ -374,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

@@ -6,7 +6,8 @@ import type { CliContext } from "../types.js";
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
- * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
+ * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
 export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext): void;
 /**

package/dist/commands/run.js

@@ -1,5 +1,6 @@
 import { validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core/project";
 import { resolveTarget, } from "@actiondock/core/profile";
+import { resolveExecutionHint } from "@actiondock/core";
 import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
 import { writeStderr, writeStdout } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, resolveTimeoutMs, withService, } from "../utils/index.js";
@@ -7,44 +8,18 @@ import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLoc
  * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
  *
  * 设计契约：
- * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
+ * - 通用纯文本透传：标量直接输出，结构化对象按标准规范呈现，杜绝私有业务字段嗅探。
+ * - 标准输出仅承载业务有效载荷，保持原生排版与真实换行，供用户调阅或下游管道消费。
  */
 export function renderRawExecutionResult(targetRef, result, context) {
     if (result.ok) {
         const data = result.data;
         let rawText;
-        let metaInfo;
         if (typeof data === "string") {
             rawText = data;
         }
         else if (data !== null && typeof data === "object") {
-            if ("content" in data && data.content !== undefined) {
-                rawText =
-                    typeof data.content === "object" && data.content !== null
-                        ? JSON.stringify(data.content, null, 2)
-                        : String(data.content);
-                const { content, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else if ("text" in data && typeof data.text === "string") {
-                rawText = data.text;
-                const { text, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else if ("message" in data && typeof data.message === "string") {
-                rawText = data.message;
-                const { message, ...rest } = data;
-                if (Object.keys(rest).length > 0) {
-                    metaInfo = rest;
-                }
-            }
-            else {
-                rawText = JSON.stringify(data, null, 2);
-            }
+            rawText = JSON.stringify(data, null, 2);
         }
         else if (data !== undefined) {
             rawText = String(data);
@@ -52,32 +27,6 @@ export function renderRawExecutionResult(targetRef, result, context) {
         else {
             rawText = "";
         }
-        if (metaInfo) {
-            const parts = [];
-            const title = metaInfo.path ? String(metaInfo.path) : targetRef;
-            parts.push(title);
-            if (metaInfo.startLine !== undefined && metaInfo.endLine !== undefined) {
-                parts.push(`lines ${metaInfo.startLine}-${metaInfo.endLine}`);
-            }
-            else if (metaInfo.line !== undefined) {
-                parts.push(`line ${metaInfo.line}`);
-            }
-            if (metaInfo.hasMore !== undefined) {
-                parts.push(`hasMore: ${metaInfo.hasMore}`);
-            }
-            if (metaInfo.truncated) {
-                parts.push("truncated: true");
-            }
-            const handled = new Set(["path", "startLine", "endLine", "line", "hasMore", "truncated"]);
-            for (const [k, v] of Object.entries(metaInfo)) {
-                if (!handled.has(k) && v !== undefined) {
-                    parts.push(`${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
-                }
-            }
-            if (parts.length > 0) {
-                writeStderr(`[${parts.join(" | ")}]`, context);
-            }
-        }
         writeStdout(rawText, context);
     }
     else {
@@ -87,6 +36,10 @@ export function renderRawExecutionResult(targetRef, result, context) {
                 ? result.error.details
                 : JSON.stringify(result.error.details, null, 2), context);
         }
+        const hint = resolveExecutionHint(targetRef, result.error);
+        if (hint) {
+            writeStderr(hint, context);
+        }
         if (context) {
             context.exitCode = 1;
         }
@@ -189,7 +142,14 @@ export async function executeAction(id, options, context, flatArgs, control) {
                     throw new SigintError();
                 }
                 if (isMachine) {
-                    writeStdout(JSON.stringify(result, null, 2), context);
+                    if (!result.ok) {
+                        const hint = resolveExecutionHint(targetRef, result.error);
+                        const machineOutput = hint !== undefined ? { ...result, hint } : result;
+                        writeStdout(JSON.stringify(machineOutput, null, 2), context);
+                    }
+                    else {
+                        writeStdout(JSON.stringify(result, null, 2), context);
+                    }
                 }
                 else {
                     renderRawExecutionResult(targetRef, result, context);
@@ -260,6 +220,9 @@ export function attachRunCommand(parent, context) {
         .option("-i, --input <json>", "Action input as inline JSON")
         .option("-f, --input-file <path>", "Action input from JSON file, or '-' for stdin")
         .option("-c, --config <key=value...>", "Temporary config override (repeatable)");
+    cmd.unknownOption = function (flag) {
+        this.error(`unknown option '${flag}'\nHint: Separate action inputs from CLI options using '--', e.g.: ad run <id> [options] -- <param>=<val> or <param>:=<json>.`, { code: "commander.unknownOption" });
+    };
     return applyTargetOptions(cmd)
         .option("--timeout <duration>", "Execution timeout (e.g. 30s, 5m, 500ms)")
         .option("--request-id <id>", "Idempotency request ID for deduplication")

package/dist/commands/runs.d.ts

@@ -1,7 +1,12 @@
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
 /**
- * 注册 runs 动作执行历史管理命令（list、show、clear、cancel）。
+ * 归一化 requestId 选项值为去重后的非空原样字符串数组。
+ * 将 requestId 作为不作解释的原样字符串，不拆分逗号、不剔除首尾空白，只做非空有效字符串检查与去重。
+ */
+export declare function normalizeRequestIds(raw: unknown): string[];
+/**
+ * 注册 runs 动作执行历史管理命令（list、show、watch、clear、cancel）。
  *
  * @param program Commander 实例
  * @param context 命令行上下文