@actiondock/cli 2.5.1 → 2.7.0

package/dist/commands/validate.js

@@ -1,5 +1,5 @@
 import { checkGeneratedTypes, findProjectRoot, GENERATED_TYPES_OUTDATED_CODE, loadActions, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError, ExecutionError } from "../errors.js";
+import { ArgumentError, ExecutionError, notInProjectError, packageNotFoundError } from "../errors.js";
 import { renderActionValidation, renderResult } from "../renderer.js";
 import { getEffectiveOptions } from "../utils/index.js";
 /**
@@ -14,7 +14,6 @@ export function attachValidateCommand(parent, context) {
         .description("Validate action schemas and definitions")
         .option("-P, --package <id>", "Target package ID or path")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .option("--data-dir <path>", "Custom database storage directory")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
@@ -22,14 +21,14 @@ export function attachValidateCommand(parent, context) {
         if (options.package) {
             root = resolvePackageRoot(options.package);
             if (!root) {
-                throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                throw packageNotFoundError(options.package);
             }
         }
         else {
             root = findProjectRoot();
         }
         if (!root) {
-            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id> or cd into a project directory.");
+            throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
         }
         const config = loadProjectConfig(root);
         const actions = await loadActions(root, config.actionsDir);
@@ -73,7 +72,6 @@ export function attachValidateCommand(parent, context) {
         const validationPayload = { valid: allValid, results };
         renderResult(validationPayload, {
             json: options.json,
-            envelope: options.envelope,
             humanFormatter: () => renderActionValidation(results),
             context,
         });

package/dist/errors.d.ts

@@ -12,7 +12,7 @@ export declare class CliError extends Error {
  * 命令行参数与选项校验错误（退出码为 2）。
  */
 export declare class ArgumentError extends CliError {
-    constructor(message: string, details?: unknown);
+    constructor(message: string, details?: unknown, code?: string);
 }
 /**
  * 业务逻辑或框架执行失败错误（退出码为 1）。
@@ -35,6 +35,19 @@ export interface FormattedError {
     exitCode: ExitCodeValue;
     details?: unknown;
 }
+/**
+ * 目标包寻址失败错误（-P 指定的包不在链接注册表也无法按路径寻址）。
+ */
+export declare function packageNotFoundError(pkg: string): ArgumentError;
+/**
+ * 当前目录不在 ActionDock 工程内错误。
+ * `hint` 为命令专属的补救措施提示行（如 -P 参数用法）。
+ */
+export declare function notInProjectError(hint?: string): ArgumentError;
+/**
+ * 当前目录无工程且全局注册表无任何链接包提示文案（非错误场景使用）。
+ */
+export declare const NO_PROJECT_NO_LINKED_MESSAGE = "No ActionDock project in current directory, and no packages linked.";
 /**
  * 解析并格式化任意异常为结构化错误对象。
  *

package/dist/errors.js

@@ -1,4 +1,20 @@
+import { InputError, INVALID_FLAT_ARGUMENT, INVALID_JSON, INVALID_JSON_LITERAL, INPUT_PATH_CONFLICT, FLAT_INPUT_LIMIT_EXCEEDED, INPUT_LIMIT_EXCEEDED, INPUT_POLICY_VIOLATION, INPUT_CONFLICT, INPUT_FILE_NOT_FOUND, INPUT_FILE_READ_FAILED, } from "@actiondock/core";
 import { ExitCode } from "./types.js";
+/**
+ * 扁平与解析输入错误码集合。
+ */
+const FLAT_ERROR_CODES = new Set([
+    INVALID_FLAT_ARGUMENT,
+    INVALID_JSON,
+    INVALID_JSON_LITERAL,
+    INPUT_PATH_CONFLICT,
+    FLAT_INPUT_LIMIT_EXCEEDED,
+    INPUT_LIMIT_EXCEEDED,
+    INPUT_POLICY_VIOLATION,
+    INPUT_CONFLICT,
+    INPUT_FILE_NOT_FOUND,
+    INPUT_FILE_READ_FAILED,
+]);
 /**
  * CLI 信封错误码常量（仅 CLI 输出协议使用，属包内部码，就地常量化管理）。
  */
@@ -25,8 +41,8 @@ export class CliError extends Error {
  * 命令行参数与选项校验错误（退出码为 2）。
  */
 export class ArgumentError extends CliError {
-    constructor(message, details) {
-        super(message, ExitCode.INVALID_ARGUMENT, "INVALID_ARGUMENT", details);
+    constructor(message, details, code = "INVALID_ARGUMENT") {
+        super(message, ExitCode.INVALID_ARGUMENT, code, details);
         this.name = "ArgumentError";
     }
 }
@@ -48,6 +64,24 @@ export class SigintError extends CliError {
         this.name = "SigintError";
     }
 }
+/**
+ * 目标包寻址失败错误（-P 指定的包不在链接注册表也无法按路径寻址）。
+ */
+export function packageNotFoundError(pkg) {
+    return new ArgumentError(`Package '${pkg}' not found in linked packages or path`);
+}
+/**
+ * 当前目录不在 ActionDock 工程内错误。
+ * `hint` 为命令专属的补救措施提示行（如 -P 参数用法）。
+ */
+export function notInProjectError(hint) {
+    const base = "Not in an ActionDock project (actiondock.json not found)";
+    return new ArgumentError(hint ? `${base}.\n${hint}` : base);
+}
+/**
+ * 当前目录无工程且全局注册表无任何链接包提示文案（非错误场景使用）。
+ */
+export const NO_PROJECT_NO_LINKED_MESSAGE = "No ActionDock project in current directory, and no packages linked.";
 /**
  * 解析并格式化任意异常为结构化错误对象。
  *
@@ -62,10 +96,26 @@ export function formatError(err) {
             details: err.details,
         };
     }
+    if (err instanceof InputError) {
+        return {
+            code: err.code,
+            message: err.message,
+            exitCode: ExitCode.INVALID_ARGUMENT,
+            details: err.details,
+        };
+    }
     // Commander.js 原生错误处理
     if (typeof err === "object" && err !== null && "code" in err && typeof err.code === "string") {
+        const code = err.code;
+        if (FLAT_ERROR_CODES.has(code)) {
+            return {
+                code,
+                message: err.message || String(err),
+                exitCode: ExitCode.INVALID_ARGUMENT,
+                details: err.details,
+            };
+        }
         const commanderErr = err;
-        const code = commanderErr.code;
         // 参数类异常
         if (code.startsWith("commander.unknownOption") ||
             code.startsWith("commander.missingArgument") ||

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type InvocationControl } from "./types.js";
 export * from "./types.js";
 export * from "./errors.js";
 export * from "./renderer.js";
@@ -10,6 +11,12 @@ export * from "./commands/index.js";
  * ActionDock CLI 主执行入口函数。
  *
  * @param argv 命令行参数数组（默认使用 process.argv）
+ * @param control 可选的中断与取消控制契约
  * @returns 进程退出码
  */
-export declare function main(argv?: string[]): Promise<number>;
+export declare function main(argv?: string[], control?: InvocationControl): Promise<number>;
+/**
+ * 命令行独立进程适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export declare function runCliProcess(argv?: string[]): Promise<void>;

package/dist/index.js

@@ -1,7 +1,8 @@
 import { CommanderError } from "commander";
 import { createCliProgram } from "./commands/index.js";
-import { formatError } from "./errors.js";
+import { formatError, SigintError } from "./errors.js";
 import { renderError } from "./renderer.js";
+import { ExitCode } from "./types.js";
 export * from "./types.js";
 export * from "./errors.js";
 export * from "./renderer.js";
@@ -14,16 +15,37 @@ export * from "./commands/index.js";
  * ActionDock CLI 主执行入口函数。
  *
  * @param argv 命令行参数数组（默认使用 process.argv）
+ * @param control 可选的中断与取消控制契约
  * @returns 进程退出码
  */
-export async function main(argv = process.argv) {
-    const program = createCliProgram();
-    const isMachine = argv.includes("--json") || argv.includes("--envelope");
+export async function main(argv = process.argv, control) {
+    const context = { control, exitCode: 0 };
+    const program = createCliProgram(context);
+    const isMachine = argv.includes("--json");
+    const normalizedArgv = argv.length >= 2 &&
+        (argv[0].endsWith("node") ||
+            argv[0].endsWith("bun") ||
+            argv[0].endsWith("tsx") ||
+            argv[1].includes("/") ||
+            argv[1].includes("\\") ||
+            argv[1].endsWith(".js") ||
+            argv[1].endsWith(".ts"))
+        ? argv
+        : ["node", "ad", ...argv];
     try {
-        await program.parseAsync(argv);
-        return typeof process.exitCode === "number" ? process.exitCode : 0;
+        await program.parseAsync(normalizedArgv);
+        if (control?.cancellationSource === "sigint" && control?.signal?.aborted) {
+            return ExitCode.SIGINT;
+        }
+        return (context.exitCode && context.exitCode !== 0)
+            ? context.exitCode
+            : (typeof process.exitCode === "number" ? process.exitCode : 0);
     }
     catch (err) {
+        if (control?.cancellationSource === "sigint" &&
+            (control?.signal?.aborted || err?.name === "AbortError" || err?.message?.includes("SIGINT") || err instanceof SigintError)) {
+            return ExitCode.SIGINT;
+        }
         if (err instanceof CommanderError) {
             if (err.exitCode === 0) {
                 return 0;
@@ -32,10 +54,39 @@ export async function main(argv = process.argv) {
         // 复用 renderer 的 renderError 统一错误信封，消除手工拼装的双实现
         renderError(err, {
             json: isMachine,
-            envelope: isMachine,
+            context,
         });
-        process.exitCode = formatError(err).exitCode;
-        return process.exitCode;
+        return formatError(err).exitCode;
+    }
+}
+/**
+ * 命令行独立进程适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export async function runCliProcess(argv = process.argv) {
+    const controller = new AbortController();
+    const control = {
+        signal: controller.signal,
+    };
+    let sigintCount = 0;
+    const sigintHandler = () => {
+        sigintCount++;
+        if (sigintCount === 1) {
+            control.cancellationSource = "sigint";
+            controller.abort(new Error("Interrupted by SIGINT"));
+        }
+        else {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+    };
+    process.on("SIGINT", sigintHandler);
+    try {
+        const exitCode = await main(argv, control);
+        process.exitCode = exitCode;
+    }
+    finally {
+        process.removeListener("SIGINT", sigintHandler);
     }
 }
 import { fileURLToPath } from "node:url";
@@ -43,7 +94,7 @@ import { resolve } from "node:path";
 const isDirectRun = Boolean(process.argv[1]) &&
     resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 if (isDirectRun) {
-    main().catch((err) => {
+    runCliProcess().catch((err) => {
         console.error("Fatal error:", err);
         process.exitCode = 1;
     });

package/dist/renderer.d.ts

@@ -1,5 +1,5 @@
 import type { RunRecord } from "@actiondock/sdk";
-import type { RegistryStatusReport } from "@actiondock/core";
+import { type RegistryStatusReport } from "@actiondock/core";
 import type { Envelope, ProjectDetailInfo, AggregatedPackage, EnvCheckItem, CliContext } from "./types.js";
 /**
  * 构造标准成功结果信封。
@@ -37,7 +37,6 @@ export declare function writeStderr(message: string, context?: CliContext): void
  */
 export declare function renderResult<T>(data: T, options: {
     json?: boolean;
-    envelope?: boolean;
     humanFormatter?: () => string;
     context?: CliContext;
 }): void;
@@ -46,7 +45,6 @@ export declare function renderResult<T>(data: T, options: {
  */
 export declare function renderError(err: unknown, options: {
     json?: boolean;
-    envelope?: boolean;
     context?: CliContext;
 }): void;
 /**
@@ -114,7 +112,8 @@ export declare function renderActionList(items: Array<{
     packageId?: string;
 }>, title?: string, isFallback?: boolean, intent?: string): string;
 /**
- * 格式化渲染 Action 详情。
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
  */
 export declare function renderActionDetail(action: {
     id: string;

package/dist/renderer.js

@@ -1,3 +1,4 @@
+import { formatActionDetail } from "@actiondock/core";
 import { formatError } from "./errors.js";
 /**
  * 构造标准成功结果信封。
@@ -72,21 +73,9 @@ export function writeStderr(message, context) {
  * 统一根据输出模式进行渲染输出。
  */
 export function renderResult(data, options) {
-    const isJson = Boolean(options.json || options.envelope);
-    const useEnvelope = Boolean(options.envelope || (isJson && options.context?.defaultEnvelope));
+    const isJson = Boolean(options.json);
     if (isJson) {
-        if (useEnvelope) {
-            // 避免重复包装已有信封
-            if (typeof data === "object" && data !== null && "ok" in data) {
-                writeStdout(formatJson(data), options.context);
-            }
-            else {
-                writeStdout(formatJson(createSuccessEnvelope(data)), options.context);
-            }
-        }
-        else {
-            writeStdout(formatJson(data), options.context);
-        }
+        writeStdout(formatJson(data), options.context);
     }
     else {
         if (options.humanFormatter) {
@@ -102,7 +91,7 @@ export function renderResult(data, options) {
  */
 export function renderError(err, options) {
     const formatted = formatError(err);
-    const isMachine = Boolean(options.json || options.envelope || options.context?.defaultEnvelope);
+    const isMachine = Boolean(options.json);
     if (isMachine) {
         const errorEnv = createErrorEnvelope(formatted.code, formatted.message, formatted.details);
         writeStdout(formatJson(errorEnv), options.context);
@@ -266,27 +255,11 @@ export function renderActionList(items, title = "Actions", isFallback = false, i
     return lines.join("\n");
 }
 /**
- * 格式化渲染 Action 详情。
+ * 格式化渲染 Action 详情（编码顾问 Encoding Advisor）。
+ * 统一复用 core 下沉的 formatActionDetail 实现，与独立分发器保持完全一致。
  */
 export function renderActionDetail(action) {
-    const lines = [];
-    lines.push(`Action:      ${action.id}`);
-    if (action.packageId) {
-        const rootDesc = action.projectRoot ? ` (${action.projectRoot})` : "";
-        lines.push(`Package:     ${action.packageId}${rootDesc}`);
-    }
-    if (action.description) {
-        lines.push(`Description: ${action.description}`);
-    }
-    if (action.inputSchema) {
-        lines.push("\nInput Schema:");
-        lines.push(JSON.stringify(action.inputSchema, null, 2));
-    }
-    if (action.outputSchema) {
-        lines.push("\nOutput Schema:");
-        lines.push(JSON.stringify(action.outputSchema, null, 2));
-    }
-    return lines.join("\n");
+    return formatActionDetail(action);
 }
 /**
  * 格式化渲染 Action 校验结果。

package/dist/services/config-merge.d.ts

@@ -0,0 +1,41 @@
+import { type ActionDockTarget, type ConfigItemDefinition } from "@actiondock/core";
+/**
+ * 配置合并视图条目：跨作用域合并后的键值展示结构。
+ * source 标签语义：project（包级持久化）> global（全局持久化）> env（环境变量）> default（声明默认值）。
+ */
+export interface MergedConfigEntry {
+    key: string;
+    value: unknown;
+    source: "project" | "global" | "env" | "default";
+    secret: boolean;
+    description?: string;
+}
+/**
+ * 解析单个配置键的合并视图（项目包级 > 全局持久化 > 环境变量 > 声明默认值）。
+ *
+ * 与 config list 的整表合并保持同一优先级链：包级持久化命中即短路，
+ * 全局持久化次之，环境变量再次，最后回退声明默认值。
+ *
+ * @param key 配置键名
+ * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
+ * @param declaredItem 工程声明的配置项定义
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
+ */
+export declare function resolveMergedConfigEntry(key: string, packageId: string, declaredItem: ConfigItemDefinition | undefined, target: ActionDockTarget, reveal: boolean): Promise<{
+    value: unknown;
+    source: MergedConfigEntry["source"];
+    secret: boolean;
+}>;
+/**
+ * 构造工程范围的完整配置合并视图（config list 单一事实源）。
+ *
+ * 键全集 = 工程声明键 ∪ 包级持久化键 ∪ 全局持久化键，
+ * 每个键按 resolveMergedConfigEntry 相同的优先级链取值，
+ * 消除 config get 与 config list 两命令间的合并实现差异。
+ *
+ * @param root 工程根目录
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文
+ */
+export declare function buildMergedConfigEntries(root: string, target: ActionDockTarget, reveal: boolean): Promise<MergedConfigEntry[]>;

package/dist/services/config-merge.js

@@ -0,0 +1,93 @@
+import { isSecretConfigKey, loadProjectConfig, maskSecretValue, resolveEnvValue, } from "@actiondock/core";
+/**
+ * 解析单个配置键的合并视图（项目包级 > 全局持久化 > 环境变量 > 声明默认值）。
+ *
+ * 与 config list 的整表合并保持同一优先级链：包级持久化命中即短路，
+ * 全局持久化次之，环境变量再次，最后回退声明默认值。
+ *
+ * @param key 配置键名
+ * @param packageId 包标识（用于包级作用域寻址与环境变量解析）
+ * @param declaredItem 工程声明的配置项定义
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文（为假且敏感键时打码）
+ */
+export async function resolveMergedConfigEntry(key, packageId, declaredItem, target, reveal) {
+    const confView = await target.getConfig(packageId, key);
+    const envResolved = resolveEnvValue(key, declaredItem, packageId);
+    let rawValue;
+    let source;
+    if (confView && confView.configured) {
+        rawValue = confView.value;
+        source = confView.source === "package" ? "project" : confView.source;
+    }
+    else if (envResolved !== undefined) {
+        rawValue = envResolved.value;
+        source = "env";
+    }
+    else {
+        rawValue = declaredItem?.default;
+        source = "default";
+    }
+    const isSecret = confView?.secret ?? isSecretConfigKey(key, declaredItem);
+    const displayValue = !reveal && isSecret && rawValue !== undefined ? maskSecretValue(rawValue) : rawValue;
+    return { value: displayValue, source, secret: isSecret };
+}
+/**
+ * 构造工程范围的完整配置合并视图（config list 单一事实源）。
+ *
+ * 键全集 = 工程声明键 ∪ 包级持久化键 ∪ 全局持久化键，
+ * 每个键按 resolveMergedConfigEntry 相同的优先级链取值，
+ * 消除 config get 与 config list 两命令间的合并实现差异。
+ *
+ * @param root 工程根目录
+ * @param target 已创建的 Target 门面实例
+ * @param reveal 是否揭示敏感值明文
+ */
+export async function buildMergedConfigEntries(root, target, reveal) {
+    const projConfig = loadProjectConfig(root);
+    const declared = projConfig.config || {};
+    const projectConfigList = await target.listConfig(projConfig.id);
+    const globalConfigList = await target.listConfig("global");
+    const projectConfigMap = new Map(projectConfigList.map((c) => [c.key, c]));
+    const globalConfigMap = new Map(globalConfigList.map((c) => [c.key, c]));
+    const allKeys = new Set([
+        ...Object.keys(declared),
+        ...projectConfigList.map((c) => c.key),
+        ...globalConfigList.map((c) => c.key),
+    ]);
+    const entries = [];
+    for (const key of allKeys) {
+        const declaredItem = declared[key];
+        const envResolved = resolveEnvValue(key, declaredItem, projConfig.id);
+        const projItem = projectConfigMap.get(key);
+        const globItem = globalConfigMap.get(key);
+        let rawValue;
+        let source;
+        if (projItem && projItem.configured && projItem.source === "package") {
+            rawValue = projItem.value;
+            source = "project";
+        }
+        else if (globItem && globItem.configured) {
+            rawValue = globItem.value;
+            source = "global";
+        }
+        else if (envResolved !== undefined) {
+            rawValue = envResolved.value;
+            source = "env";
+        }
+        else {
+            rawValue = declaredItem?.default;
+            source = "default";
+        }
+        const isSecret = isSecretConfigKey(key, declaredItem);
+        const displayValue = !reveal && isSecret && rawValue !== undefined ? maskSecretValue(rawValue) : rawValue;
+        entries.push({
+            key,
+            value: displayValue,
+            source,
+            secret: isSecret,
+            ...(declaredItem?.description !== undefined ? { description: declaredItem.description } : {}),
+        });
+    }
+    return entries;
+}

package/dist/services/index.d.ts

@@ -1 +1,2 @@
 export * from "./inspect.js";
+export * from "./config-merge.js";

package/dist/services/index.js

@@ -1 +1,2 @@
 export * from "./inspect.js";
+export * from "./config-merge.js";

package/dist/standalone/index.d.ts

@@ -1,5 +1,6 @@
-import { StandaloneDispatcher as CoreStandaloneDispatcher } from "@actiondock/core";
+import { StandaloneDispatcher as CoreStandaloneDispatcher, type InvocationControl } from "@actiondock/core";
 import type { StandaloneOptions } from "../types.js";
+export { type InvocationControl };
 /**
  * 独立二进制轻量参数解析分发器（委托 Core 统一实现，消除重复逻辑）。
  */
@@ -9,8 +10,13 @@ export declare class StandaloneDispatcher extends CoreStandaloneDispatcher {
 /**
  * 运行独立二进制参数解析分发器并返回退出状态码。
  */
-export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions): Promise<number>;
+export declare function runStandaloneCli(argv: string[] | undefined, options: StandaloneOptions, control?: InvocationControl): Promise<number>;
 /**
  * 创建独立二进制运行时分发器实例。
  */
 export declare function createStandaloneDispatcher(options: StandaloneOptions): StandaloneDispatcher;
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export declare function runStandaloneProcess(argv: string[] | undefined, options: StandaloneOptions): Promise<void>;

package/dist/standalone/index.js

@@ -10,9 +10,9 @@ export class StandaloneDispatcher extends CoreStandaloneDispatcher {
 /**
  * 运行独立二进制参数解析分发器并返回退出状态码。
  */
-export async function runStandaloneCli(argv = process.argv.slice(2), options) {
+export async function runStandaloneCli(argv = process.argv.slice(2), options, control) {
     const dispatcher = new StandaloneDispatcher(options);
-    return dispatcher.dispatch(argv);
+    return dispatcher.dispatch(argv, control);
 }
 /**
  * 创建独立二进制运行时分发器实例。
@@ -20,3 +20,33 @@ export async function runStandaloneCli(argv = process.argv.slice(2), options) {
 export function createStandaloneDispatcher(options) {
     return new StandaloneDispatcher(options);
 }
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export async function runStandaloneProcess(argv = process.argv.slice(2), options) {
+    const controller = new AbortController();
+    const control = {
+        signal: controller.signal,
+    };
+    let sigintCount = 0;
+    const sigintHandler = () => {
+        sigintCount++;
+        if (sigintCount === 1) {
+            control.cancellationSource = "sigint";
+            controller.abort(new Error("Interrupted by SIGINT"));
+        }
+        else {
+            process.exitCode = 130;
+            process.exit(130);
+        }
+    };
+    process.on("SIGINT", sigintHandler);
+    try {
+        const exitCode = await runStandaloneCli(argv, options, control);
+        process.exitCode = exitCode;
+    }
+    finally {
+        process.removeListener("SIGINT", sigintHandler);
+    }
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ActionDefinition } from "@actiondock/sdk";
-import type { ConfigItemDefinition } from "@actiondock/core";
+import type { ConfigItemDefinition, InvocationControl } from "@actiondock/core";
+export type { InvocationControl };
 /**
  * 统一退出码定义（事实源位于 core 包 StandaloneDispatcher，此处仅 re-export 维持既有导入路径兼容）。
  * - SUCCESS: 执行成功（0）
@@ -67,8 +68,6 @@ export interface CliContext {
     dataDir?: string;
     /** 自定义 ActionDock 用户家目录（用于测试隔离与多租户环境） */
     customHome?: string;
-    /** 默认信封包装输出模式 */
-    defaultEnvelope?: boolean;
     /** 自定义标准输出写入函数 */
     stdout?: (msg: string) => void;
     /** 自定义标准错误写入函数 */
@@ -80,6 +79,10 @@ export interface CliContext {
         secret?: boolean;
         mask?: string;
     }) => Promise<string>;
+    /** 可选的中断与取消控制契约 */
+    control?: InvocationControl;
+    /** 退出码收集器（避免污染全局 process.exitCode） */
+    exitCode?: number;
 }
 /**
  * 工程自省详情信息结构。

package/dist/utils/index.d.ts

@@ -5,3 +5,4 @@ export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
+export * from "./input.js";

package/dist/utils/index.js

@@ -5,3 +5,4 @@ export * from "./filter.js";
 export * from "./target.js";
 export * from "./spawn.js";
 export * from "./cert.js";
+export * from "./input.js";

package/dist/utils/input.d.ts

@@ -0,0 +1 @@
+export { resolveActionInput, type ResolveActionInputOptions, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";

package/dist/utils/input.js

@@ -0,0 +1 @@
+export { resolveActionInput, parseJson, readStdin, stripBom, InputError, FlatInputError, buildActionInputAdvice, formatActionDetail, } from "@actiondock/core";

package/dist/utils/spawn.d.ts

@@ -1,3 +1,10 @@
+/**
+ * 校验包管理器依赖说明符仅包含白名单字符。
+ * 非法字符直接抛出参数错误，不进入子进程拼接链路。
+ *
+ * @param spec 待校验的包说明符（如 `@scope/pkg@^1.2.3`）
+ */
+export declare function assertSafePackageSpec(spec: string): void;
 /**
  * 子进程执行结果视图。
  */
@@ -16,6 +23,12 @@ export interface SpawnAsyncResult {
  *
  * 与 spawnSync 语义对齐：stdio 默认 pipe，进程结束（而非继承输出）后返回聚合结果。
  *
+ * win32 shell 取舍说明：npm 在 Windows 上是 `.cmd` 批处理脚本，Node 20.12+
+ * 针对 CVE-2024-27980 的缓解措施使 `shell:false` 直接 spawn `.cmd` 抛出 EINVAL，
+ * 因此 win32 保留 shell 拼接模式；命令注入面由调用方的
+ * assertSafePackageSpec 白名单前置校验关闭（包说明符仅允许
+ * 字母数字与 `@/:/-_/.+`，全部 shell 元字符被拒绝）。
+ *
  * @param command 可执行文件名
  * @param args 参数列表
  * @param options 附加选项（cwd 与 shell 策略）