@actiondock/core 2.5.1 → 2.7.0

package/dist/runtime/standalone.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDefinition } from "@actiondock/sdk";
+import { type ActionDefinition } from "@actiondock/sdk";
 import type { ActionSpec } from "../app/types.js";
 import type { ConfigItemDefinition } from "../project/types.js";
 import type { ActionDockTarget } from "../target/types.js";
@@ -11,6 +11,13 @@ export declare const ExitCode: {
     readonly INVALID_ARGUMENT: 2;
     readonly SIGINT: 130;
 };
+/**
+ * 调用控制选项契约。
+ */
+export interface InvocationControl {
+    signal?: AbortSignal;
+    cancellationSource?: "external" | "sigint";
+}
 /**
  * 独立二进制运行分发器配置选项。
  */
@@ -63,14 +70,25 @@ export declare class StandaloneDispatcher {
      * 解析命令行参数并分发执行对应子命令。
      *
      * @param argv 命令行参数数组（如 process.argv.slice(2)）
+     * @param control 可选的中断与取消控制契约
      * @returns 退出状态码（0: 成功, 1: 失败, 2: 参数错误, 130: 中断）
      */
-    dispatch(argv: string[]): Promise<number>;
+    dispatch(argv: string[], control?: InvocationControl): Promise<number>;
     private handleList;
     private handleDescribe;
     private handleRun;
     private handleConfig;
     private handleState;
+    /**
+     * 判定配置读取异常是否为目标层能力缺失（键未配置语义）而非内部故障。
+     */
+    private isTargetCapabilityError;
+    /**
+     * 解析携带命名空间前缀的状态键参数：委托 sdk 单一事实源 decodeStateKey。
+     *
+     * 解析失败（如存在多个未转义冒号的歧义键）时按纯键处理，交由存储层兜底。
+     */
+    private decodeStateKeyArg;
     private printHelp;
 }
 /**
@@ -87,3 +105,8 @@ export declare class StandaloneRuntime {
  * 工厂函数：创建独立运行时实例。
  */
 export declare function createStandaloneRuntime(options: StandaloneRuntimeOptions): StandaloneRuntime;
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export declare function runStandaloneProcess(argv: string[], options: StandaloneDispatcherOptions): Promise<void>;

package/dist/runtime/standalone.js

@@ -1,7 +1,9 @@
-import { readFileSync } from "node:fs";
+import { decodeStateKey } from "@actiondock/sdk";
 import { filterWithFallbackInfo } from "../filter/index.js";
 import { createActionDockTarget } from "../target/target.js";
 import { STANDALONE_ASYNC_UNSUPPORTED } from "../errors.js";
+import { resolveActionInput, formatActionDetail, buildActionDescribePayload, mapInputValidationFailure, } from "../input/index.js";
+import { validateActionInputValue } from "../json/value-validator.js";
 import { normalizeActionCollection } from "./action-collection.js";
 import { parseDuration } from "../utils/index.js";
 /**
@@ -83,24 +85,27 @@ export class StandaloneDispatcher {
      * 解析命令行参数并分发执行对应子命令。
      *
      * @param argv 命令行参数数组（如 process.argv.slice(2)）
+     * @param control 可选的中断与取消控制契约
      * @returns 退出状态码（0: 成功, 1: 失败, 2: 参数错误, 130: 中断）
      */
-    async dispatch(argv) {
-        const args = [...argv];
+    async dispatch(argv, control) {
+        const separator = argv.indexOf("--");
+        const controlArgs = separator >= 0 ? argv.slice(0, separator) : argv;
+        const actionArgs = separator >= 0 ? argv.slice(separator + 1) : [];
         let dataDir;
         const configOverrides = {};
-        // 1. 提取全局参数（--data-dir, --config）
+        // 1. 提取全局参数（--data-dir, --config）仅从 controlArgs 中解析
         const filteredArgs = [];
-        for (let i = 0; i < args.length; i++) {
-            const arg = args[i];
-            if (arg === "--data-dir" && i + 1 < args.length) {
-                dataDir = args[++i];
+        for (let i = 0; i < controlArgs.length; i++) {
+            const arg = controlArgs[i];
+            if (arg === "--data-dir" && i + 1 < controlArgs.length) {
+                dataDir = controlArgs[++i];
             }
             else if (arg.startsWith("--data-dir=")) {
                 dataDir = arg.slice(11);
             }
-            else if (arg === "--config" && i + 1 < args.length) {
-                const pair = args[++i];
+            else if (arg === "--config" && i + 1 < controlArgs.length) {
+                const pair = controlArgs[++i];
                 const [k, ...v] = pair.split("=");
                 if (k)
                     configOverrides[k] = v.join("=");
@@ -118,8 +123,8 @@ export class StandaloneDispatcher {
         const command = filteredArgs[0] || "help";
         const subArgs = filteredArgs.slice(1);
         // 2. 独立入口拒绝异步启动语义
-        if (args.includes("--async")) {
-            const isJson = args.includes("--json") || args.includes("--envelope");
+        if (controlArgs.includes("--async")) {
+            const isJson = controlArgs.includes("--json");
             if (isJson) {
                 this.writeOut(JSON.stringify({
                     ok: false,
@@ -154,47 +159,51 @@ export class StandaloneDispatcher {
             this.writeErr(`Error initializing standalone target: ${err?.message || err}`);
             return ExitCode.FAILURE;
         }
-        const controller = new AbortController();
-        const sigintHandler = () => {
-            controller.abort(new Error("Interrupted by SIGINT"));
-        };
-        process.once("SIGINT", sigintHandler);
         try {
+            let code;
             switch (command) {
                 case "list":
-                    return await this.handleList(target, subArgs);
+                    code = await this.handleList(target, subArgs);
+                    break;
                 case "describe":
                 case "show":
-                    return await this.handleDescribe(target, subArgs);
+                    code = await this.handleDescribe(target, subArgs);
+                    break;
                 case "run":
-                    return await this.handleRun(target, subArgs, controller.signal);
+                    code = await this.handleRun(target, subArgs, actionArgs, control?.signal);
+                    break;
                 case "config":
-                    return await this.handleConfig(target, subArgs);
+                    code = await this.handleConfig(target, subArgs);
+                    break;
                 case "state":
-                    return await this.handleState(target, subArgs);
+                    code = await this.handleState(target, subArgs);
+                    break;
                 default:
                     this.writeErr(`Unknown command: '${command}'`);
                     this.printHelp();
                     return ExitCode.INVALID_ARGUMENT;
             }
+            if (control?.cancellationSource === "sigint" && control?.signal?.aborted) {
+                return ExitCode.SIGINT;
+            }
+            return code;
         }
         catch (err) {
-            if (err?.name === "AbortError" || controller.signal.aborted) {
+            if (control?.cancellationSource === "sigint" &&
+                (control?.signal?.aborted || err?.name === "AbortError" || err?.message?.includes("SIGINT"))) {
                 return ExitCode.SIGINT;
             }
             this.writeErr(`Error: ${err?.message || err}`);
             return ExitCode.FAILURE;
         }
         finally {
-            process.removeListener("SIGINT", sigintHandler);
             if (ownsTarget) {
                 await target.close();
             }
         }
     }
     async handleList(target, subArgs) {
-        const isJson = subArgs.includes("--json") || subArgs.includes("--envelope");
-        const useEnvelope = subArgs.includes("--envelope");
+        const isJson = subArgs.includes("--json");
         const noFallback = subArgs.includes("--no-fallback");
         let intent;
         const positionalPatterns = [];
@@ -222,10 +231,7 @@ export class StandaloneDispatcher {
         }));
         const filterRes = filterWithFallbackInfo(list, effectiveIntent, [(a) => a.id, (a) => a.description], !noFallback);
         if (isJson) {
-            const payload = useEnvelope
-                ? { ok: true, data: filterRes.items }
-                : filterRes.items;
-            this.writeOut(JSON.stringify(payload, null, 2));
+            this.writeOut(JSON.stringify(filterRes.items, null, 2));
         }
         else {
             let text = `Actions in ${this.options.packageId} (v${this.options.version}):\n\n`;
@@ -238,10 +244,20 @@ export class StandaloneDispatcher {
     }
     async handleDescribe(target, subArgs) {
         const id = subArgs.find((a) => !a.startsWith("-"));
-        const isJson = subArgs.includes("--json") || subArgs.includes("--envelope");
-        const useEnvelope = subArgs.includes("--envelope");
+        const isJson = subArgs.includes("--json");
         if (!id) {
-            this.writeErr("Error: Action ID is required for describe");
+            if (isJson) {
+                this.writeOut(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: "INVALID_ARGUMENT",
+                        message: "Action ID is required for describe",
+                    },
+                }, null, 2));
+            }
+            else {
+                this.writeErr("Error: Action ID is required for describe");
+            }
             return ExitCode.INVALID_ARGUMENT;
         }
         let action;
@@ -249,83 +265,223 @@ export class StandaloneDispatcher {
             action = await target.describeAction(id);
         }
         catch {
-            this.writeErr(`Error: Action '${id}' not found`);
+            if (isJson) {
+                this.writeOut(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: "INVALID_ARGUMENT",
+                        message: `Action '${id}' not found`,
+                    },
+                }, null, 2));
+            }
+            else {
+                this.writeErr(`Error: Action '${id}' not found`);
+            }
             return ExitCode.INVALID_ARGUMENT;
         }
-        const detail = {
-            id: action.id,
+        const payload = buildActionDescribePayload(action, {
             packageId: this.options.packageId,
-            description: action.description,
-            inputSchema: action.inputSchema,
-            outputSchema: action.outputSchema,
-        };
+        });
         if (isJson) {
-            const payload = useEnvelope ? { ok: true, data: detail } : detail;
             this.writeOut(JSON.stringify(payload, null, 2));
         }
         else {
-            let text = `Action: ${action.id}\n`;
-            if (action.description)
-                text += `Description: ${action.description}\n`;
-            if (action.inputSchema) {
-                text += `\nInput Schema:\n${JSON.stringify(action.inputSchema, null, 2)}\n`;
-            }
-            if (action.outputSchema) {
-                text += `\nOutput Schema:\n${JSON.stringify(action.outputSchema, null, 2)}\n`;
-            }
-            this.writeOut(text.trimEnd());
+            this.writeOut(formatActionDetail(payload));
         }
         return ExitCode.SUCCESS;
     }
-    async handleRun(target, subArgs, signal) {
+    async handleRun(target, subArgs, actionArgs, signal) {
+        const isJson = subArgs.includes("--json");
         const id = subArgs.find((a) => !a.startsWith("-"));
         if (!id) {
-            this.writeErr("Error: Action ID is required for run");
+            if (isJson) {
+                this.writeOut(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: "INVALID_ARGUMENT",
+                        message: "Error: Action ID is required for run",
+                    },
+                }, null, 2));
+            }
+            else {
+                this.writeErr("Error: Action ID is required for run");
+            }
             return ExitCode.INVALID_ARGUMENT;
         }
-        let input = {};
+        let inputStr;
+        let inputFile;
         let timeoutMs;
         for (let i = 0; i < subArgs.length; i++) {
             const arg = subArgs[i];
             if (arg === "--timeout" && i + 1 < subArgs.length) {
-                timeoutMs = parseDuration(subArgs[++i]);
-            }
-            else if (arg.startsWith("--timeout=")) {
-                timeoutMs = parseDuration(arg.slice(10));
-            }
-            else if (arg === "--input" && i + 1 < subArgs.length) {
                 try {
-                    input = JSON.parse(subArgs[++i]);
+                    timeoutMs = parseDuration(subArgs[++i]);
                 }
-                catch (e) {
-                    this.writeErr(`Error parsing --input JSON: ${e.message}`);
+                catch (err) {
+                    if (isJson) {
+                        this.writeOut(JSON.stringify({
+                            ok: false,
+                            error: {
+                                code: "INVALID_ARGUMENT",
+                                message: `Invalid timeout format: ${err?.message || err}`,
+                            },
+                        }, null, 2));
+                    }
+                    else {
+                        this.writeErr(`Error: Invalid timeout format: ${err?.message || err}`);
+                    }
                     return ExitCode.INVALID_ARGUMENT;
                 }
             }
-            else if (arg.startsWith("--input=")) {
+            else if (arg.startsWith("--timeout=")) {
                 try {
-                    input = JSON.parse(arg.slice(8));
+                    timeoutMs = parseDuration(arg.slice(10));
                 }
-                catch (e) {
-                    this.writeErr(`Error parsing --input JSON: ${e.message}`);
+                catch (err) {
+                    if (isJson) {
+                        this.writeOut(JSON.stringify({
+                            ok: false,
+                            error: {
+                                code: "INVALID_ARGUMENT",
+                                message: `Invalid timeout format: ${err?.message || err}`,
+                            },
+                        }, null, 2));
+                    }
+                    else {
+                        this.writeErr(`Error: Invalid timeout format: ${err?.message || err}`);
+                    }
                     return ExitCode.INVALID_ARGUMENT;
                 }
             }
+            else if (arg === "--input" && i + 1 < subArgs.length) {
+                inputStr = subArgs[++i];
+            }
+            else if (arg.startsWith("--input=")) {
+                inputStr = arg.slice(8);
+            }
             else if (arg === "--input-file" && i + 1 < subArgs.length) {
-                try {
-                    input = JSON.parse(readFileSync(subArgs[++i], "utf-8"));
-                }
-                catch (e) {
-                    this.writeErr(`Error reading --input-file: ${e.message}`);
-                    return ExitCode.INVALID_ARGUMENT;
-                }
+                inputFile = subArgs[++i];
+            }
+            else if (arg.startsWith("--input-file=")) {
+                inputFile = arg.slice(13);
             }
         }
+        let input;
+        try {
+            input = await resolveActionInput({
+                input: inputStr,
+                inputFile,
+                flatArgs: actionArgs.length > 0 ? actionArgs : undefined,
+                stdin: process.stdin,
+            });
+            const check = validateActionInputValue(input);
+            if (!check.valid) {
+                throw mapInputValidationFailure("cli-pre-target", check);
+            }
+        }
+        catch (err) {
+            if (isJson) {
+                this.writeOut(JSON.stringify({
+                    ok: false,
+                    error: {
+                        code: err?.code || "INVALID_ARGUMENT",
+                        message: err?.message || String(err),
+                        ...(err?.details !== undefined ? { details: err.details } : {}),
+                    },
+                }, null, 2));
+            }
+            else {
+                this.writeErr(`Error: ${err?.message || String(err)}`);
+            }
+            return ExitCode.INVALID_ARGUMENT;
+        }
         const result = await target.runAction(id, input, {
             signal,
             timeoutMs,
         });
-        this.writeOut(JSON.stringify(result, null, 2));
+        if (isJson) {
+            this.writeOut(JSON.stringify(result, null, 2));
+        }
+        else {
+            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);
+                    }
+                }
+                else if (data !== undefined) {
+                    rawText = String(data);
+                }
+                else {
+                    rawText = "";
+                }
+                if (metaInfo) {
+                    const parts = [];
+                    const title = metaInfo.path ? String(metaInfo.path) : id;
+                    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) {
+                        this.writeErr(`[${parts.join(" | ")}]`);
+                    }
+                }
+                this.writeOut(rawText);
+            }
+            else {
+                this.writeErr(`Error [${result.error.code}]: ${result.error.message}`);
+                if (result.error.details) {
+                    this.writeErr(typeof result.error.details === "string"
+                        ? result.error.details
+                        : JSON.stringify(result.error.details, null, 2));
+                }
+            }
+        }
         return result.ok ? ExitCode.SUCCESS : ExitCode.FAILURE;
     }
     async handleConfig(target, subArgs) {
@@ -352,9 +508,15 @@ export class StandaloneDispatcher {
                 this.writeOut(item.configured ? JSON.stringify(item.value) : "undefined");
                 return ExitCode.SUCCESS;
             }
-            catch {
-                this.writeOut("undefined");
-                return ExitCode.SUCCESS;
+            catch (err) {
+                // 目标层能力缺失（如远端未开启管理接口）视为键未配置，输出 undefined
+                if (this.isTargetCapabilityError(err)) {
+                    this.writeOut("undefined");
+                    return ExitCode.SUCCESS;
+                }
+                // 内部异常严禁吞没：透传 stderr 并以 FAILURE 退出码暴露
+                this.writeErr(`Error reading config '${key}': ${err?.message || String(err)}`);
+                return ExitCode.FAILURE;
             }
         }
         if (sub === "set") {
@@ -425,10 +587,10 @@ export class StandaloneDispatcher {
             }
             let ns = namespace;
             let actualKey = key;
-            if (ns === undefined && key.includes(":")) {
-                const colonIdx = key.indexOf(":");
-                ns = key.slice(0, colonIdx);
-                actualKey = key.slice(colonIdx + 1);
+            if (ns === undefined) {
+                const decoded = this.decodeStateKeyArg(key);
+                ns = decoded.namespace || undefined;
+                actualKey = decoded.key;
             }
             const val = await target.getState(this.options.packageId, "", actualKey, { namespace: ns });
             if (isJson) {
@@ -448,10 +610,10 @@ export class StandaloneDispatcher {
             }
             let ns = namespace || "";
             let actualKey = key;
-            if (namespace === undefined && key.includes(":")) {
-                const colonIdx = key.indexOf(":");
-                ns = key.slice(0, colonIdx);
-                actualKey = key.slice(colonIdx + 1);
+            if (namespace === undefined) {
+                const decoded = this.decodeStateKeyArg(key);
+                ns = decoded.namespace;
+                actualKey = decoded.key;
             }
             let parsed = rawVal;
             try {
@@ -501,6 +663,30 @@ export class StandaloneDispatcher {
         this.writeErr(`Unknown state subcommand: '${sub}'`);
         return ExitCode.INVALID_ARGUMENT;
     }
+    /**
+     * 判定配置读取异常是否为目标层能力缺失（键未配置语义）而非内部故障。
+     */
+    isTargetCapabilityError(err) {
+        const code = String(err?.code || "");
+        const msg = String(err?.message || "");
+        return (code === "TARGET_CAPABILITY_UNAVAILABLE" ||
+            code === "CAPABILITY_UNAVAILABLE" ||
+            msg.includes("TARGET_CAPABILITY_UNAVAILABLE") ||
+            msg.includes("Management APIs are not enabled"));
+    }
+    /**
+     * 解析携带命名空间前缀的状态键参数：委托 sdk 单一事实源 decodeStateKey。
+     *
+     * 解析失败（如存在多个未转义冒号的歧义键）时按纯键处理，交由存储层兜底。
+     */
+    decodeStateKeyArg(key) {
+        try {
+            return decodeStateKey(key);
+        }
+        catch {
+            return { namespace: "", key };
+        }
+    }
     printHelp() {
         this.writeOut(`${this.options.packageId} (v${this.options.version})`);
         if (this.options.description)
@@ -508,7 +694,8 @@ export class StandaloneDispatcher {
         this.writeOut("Usage:");
         this.writeOut("  <cmd> list [--json]                         List available actions");
         this.writeOut("  <cmd> describe <id> [--json]                Show action details and schemas");
-        this.writeOut("  <cmd> run <id> [--input '<json>']           Execute action with JSON input");
+        this.writeOut("  <cmd> run <id> [--input '<json>']           Execute action (raw text output by default)");
+        this.writeOut("  <cmd> run <id> [--json]                     Output standard execution result in JSON format");
         this.writeOut("  <cmd> config list/get/set/delete            Manage package configuration");
         this.writeOut("  <cmd> state list/get/set/delete             Manage shared state store");
         this.writeOut("\nGlobal options:");
@@ -534,3 +721,34 @@ export class StandaloneRuntime {
 export function createStandaloneRuntime(options) {
     return new StandaloneRuntime(options);
 }
+/**
+ * 独立二进制进程入口适配器。
+ * 仅在命令行可执行入口调用，负责全局 SIGINT 监听与退出状态码写入。
+ */
+export async function runStandaloneProcess(argv, 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 dispatcher = new StandaloneDispatcher(options);
+        const exitCode = await dispatcher.dispatch(argv, control);
+        process.exitCode = exitCode;
+    }
+    finally {
+        process.removeListener("SIGINT", sigintHandler);
+    }
+}

package/dist/schema/index.d.ts

@@ -0,0 +1 @@
+export * from "./validator.js";

package/dist/schema/index.js

@@ -0,0 +1 @@
+export * from "./validator.js";

package/dist/schema/validator.d.ts

@@ -10,8 +10,18 @@ export interface ValidationResult {
 }
 /**
  * 递归检查数据中是否包含危险的原型污染属性键名（__proto__、constructor、prototype）。
+ * 内部委托 validateActionInputValue 执行迭代遍历，确保环路安全、有向无环图安全且无调用栈溢出风险。
  */
 export declare function hasDangerousKeys(data: unknown): boolean;
+/**
+ * 内部纯 Schema 校验器。
+ * 仅处理布尔 Schema 与 Ajv 规则校验，严禁执行 dangerous-key 遍历。
+ *
+ * @param schema 期望匹配的 JSON Schema 对象
+ * @param data 待校验的原始数据
+ * @returns 包含 valid 状态与错误信息列表的 ValidationResult
+ */
+export declare function validateSchemaOnly(schema: JsonSchema | undefined, data: unknown): ValidationResult;
 /**
  * 校验指定数据是否符合给定的 JSON Schema 契约。
  *