@actiondock/core 2.5.1 → 2.6.0

package/dist/runtime/standalone.js

@@ -1,4 +1,5 @@
 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";
@@ -119,7 +120,7 @@ export class StandaloneDispatcher {
         const subArgs = filteredArgs.slice(1);
         // 2. 独立入口拒绝异步启动语义
         if (args.includes("--async")) {
-            const isJson = args.includes("--json") || args.includes("--envelope");
+            const isJson = args.includes("--json");
             if (isJson) {
                 this.writeOut(JSON.stringify({
                     ok: false,
@@ -193,8 +194,7 @@ export class StandaloneDispatcher {
         }
     }
     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 +222,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,8 +235,7 @@ 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");
             return ExitCode.INVALID_ARGUMENT;
@@ -260,8 +256,7 @@ export class StandaloneDispatcher {
             outputSchema: action.outputSchema,
         };
         if (isJson) {
-            const payload = useEnvelope ? { ok: true, data: detail } : detail;
-            this.writeOut(JSON.stringify(payload, null, 2));
+            this.writeOut(JSON.stringify(detail, null, 2));
         }
         else {
             let text = `Action: ${action.id}\n`;
@@ -285,9 +280,13 @@ export class StandaloneDispatcher {
         }
         let input = {};
         let timeoutMs;
+        let isJson = false;
         for (let i = 0; i < subArgs.length; i++) {
             const arg = subArgs[i];
-            if (arg === "--timeout" && i + 1 < subArgs.length) {
+            if (arg === "--json") {
+                isJson = true;
+            }
+            else if (arg === "--timeout" && i + 1 < subArgs.length) {
                 timeoutMs = parseDuration(subArgs[++i]);
             }
             else if (arg.startsWith("--timeout=")) {
@@ -325,7 +324,89 @@ export class StandaloneDispatcher {
             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 +433,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 +512,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 +535,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 +588,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 +619,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:");

package/dist/server/dispatcher.d.ts

@@ -4,6 +4,8 @@
 export type FetchDispatcherProvider = () => unknown;
 /**
  * 注册全局用于忽略服务端证书校验的调度器提供者。
+ * 唯一注册通道：平台适配层（如 @actiondock/runtime-node 的
+ * installInsecureDispatcher）显式调用完成注册，不再读取全局符号注入。
  */
 export declare function setInsecureDispatcherProvider(provider?: FetchDispatcherProvider): void;
 /**
@@ -13,12 +15,15 @@ export declare function getInsecureDispatcherProvider(): FetchDispatcherProvider
 /**
  * 获取用于忽略服务端证书校验的调度器实例。
  * 纯粹解耦设计：
- * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 注册）；
- * 2. 检查全局符号注入的提供者；
- * 3. 若在 Node 环境下且前述未注入，安全动态加载兜底连接池，绝不让 core 包产生静态硬编译依赖。
+ * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 显式安装）；
+ * 2. 若在 Node 环境下且无注册提供者，动态加载 @actiondock/runtime-node
+ *    （其入口聚合点会显式完成安装），绝不让 core 包产生静态硬编译依赖；
+ * 3. 仍不可得时返回 undefined，由调用方回退默认 fetch，绝不在 core 内
+ *    直接探测加载 undici，避免与平台适配层形成层次倒置与隐藏依赖环。
  */
 export declare function getInsecureDispatcher(): unknown;
 /**
  * 显式强制重置并销毁调度器连接池（仅用于单元测试重置或进程退出）。
+ * core 自身不再持有任何兜底连接池，关闭语义完全委托已注册的平台提供者宿主。
  */
 export declare function closeInsecureDispatcher(): Promise<void>;

package/dist/server/dispatcher.js

@@ -1,8 +1,9 @@
 import { createRequire } from "node:module";
 let insecureDispatcherProvider;
-let fallbackInsecureAgent;
 /**
  * 注册全局用于忽略服务端证书校验的调度器提供者。
+ * 唯一注册通道：平台适配层（如 @actiondock/runtime-node 的
+ * installInsecureDispatcher）显式调用完成注册，不再读取全局符号注入。
  */
 export function setInsecureDispatcherProvider(provider) {
     insecureDispatcherProvider = provider;
@@ -16,18 +17,16 @@ export function getInsecureDispatcherProvider() {
 /**
  * 获取用于忽略服务端证书校验的调度器实例。
  * 纯粹解耦设计：
- * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 注册）；
- * 2. 检查全局符号注入的提供者；
- * 3. 若在 Node 环境下且前述未注入，安全动态加载兜底连接池，绝不让 core 包产生静态硬编译依赖。
+ * 1. 优先调用显式注册的提供者（如由 @actiondock/runtime-node 显式安装）；
+ * 2. 若在 Node 环境下且无注册提供者，动态加载 @actiondock/runtime-node
+ *    （其入口聚合点会显式完成安装），绝不让 core 包产生静态硬编译依赖；
+ * 3. 仍不可得时返回 undefined，由调用方回退默认 fetch，绝不在 core 内
+ *    直接探测加载 undici，避免与平台适配层形成层次倒置与隐藏依赖环。
  */
 export function getInsecureDispatcher() {
     if (insecureDispatcherProvider) {
         return insecureDispatcherProvider();
     }
-    const globalProvider = globalThis[Symbol.for("actiondock.insecureDispatcherProvider")];
-    if (typeof globalProvider === "function") {
-        return globalProvider();
-    }
     if (typeof process !== "undefined" && process.versions?.node) {
         try {
             const req = createRequire(import.meta.url);
@@ -39,48 +38,25 @@ export function getInsecureDispatcher() {
         catch {
             // 忽略未安装 @actiondock/runtime-node 的情况
         }
-        if (!fallbackInsecureAgent || fallbackInsecureAgent.closed || fallbackInsecureAgent.destroyed) {
-            try {
-                const req = createRequire(import.meta.url);
-                const undici = req("undici");
-                if (undici?.Agent) {
-                    fallbackInsecureAgent = new undici.Agent({
-                        connect: {
-                            rejectUnauthorized: false,
-                        },
-                        bodyTimeout: 0,
-                    });
-                }
-            }
-            catch {
-                // 忽略非 Node 环境或未安装 undici 的异常
-            }
-        }
-        return fallbackInsecureAgent;
     }
     return undefined;
 }
 /**
  * 显式强制重置并销毁调度器连接池（仅用于单元测试重置或进程退出）。
+ * core 自身不再持有任何兜底连接池，关闭语义完全委托已注册的平台提供者宿主。
  */
 export async function closeInsecureDispatcher() {
-    const globalClose = globalThis[Symbol.for("actiondock.closeInsecureDispatcher")];
-    if (typeof globalClose === "function") {
-        try {
-            await globalClose();
-        }
-        catch {
-            // 忽略关闭异常
-        }
-    }
-    if (fallbackInsecureAgent) {
-        const agent = fallbackInsecureAgent;
-        fallbackInsecureAgent = undefined;
+    if (insecureDispatcherProvider) {
+        // 提供者由平台层注册：优先委托提供者宿主的关闭语义（如可用）
         try {
-            await agent.close();
+            const req = createRequire(import.meta.url);
+            const runtimeNode = req("@actiondock/runtime-node");
+            if (typeof runtimeNode?.closeInsecureDispatcher === "function") {
+                await runtimeNode.closeInsecureDispatcher();
+            }
         }
         catch {
-            // 忽略关闭异常
+            // 忽略未安装 @actiondock/runtime-node 的情况
         }
     }
 }

package/dist/server/routes/runs.js

@@ -49,12 +49,11 @@ export async function handleRunsRoutes(ctx) {
                 }
                 if (app.storage && typeof app.storage.listRuns === "function") {
                     try {
-                        const records = app.storage.listRuns({ actionId, limit });
+                        // 状态过滤下推到存储层 SQL，避免先分页后过滤导致某包前 N 条非目标状态时贡献 0 条
+                        const records = app.storage.listRuns({ actionId, status, limit });
                         for (const r of records) {
                             if (!seenRunIds.has(r.id)) {
                                 seenRunIds.add(r.id);
-                                if (status && r.status !== status)
-                                    continue;
                                 if (options.packageAllowlist &&
                                     options.packageAllowlist.length > 0 &&
                                     r.packageId &&
@@ -65,7 +64,10 @@ export async function handleRunsRoutes(ctx) {
                             }
                         }
                     }
-                    catch { }
+                    catch (err) {
+                        // 单包查询失败不阻断整体列表响应，但必须可观测
+                        console.warn(`[actiondock] listRuns failed for package '${app.packageId}': ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
             }
             allRuns.sort((a, b) => (b.startedAt || "").localeCompare(a.startedAt || ""));

package/dist/server/security.d.ts

@@ -1,3 +1,4 @@
+export { isLoopbackHost } from "../utils/net.js";
 /**
  * 恒定时间字符串比较（Constant-time comparison）。
  * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
@@ -7,13 +8,6 @@
  * @returns 两个字符串内容是否完全一致
  */
 export declare function safeEqual(a: string, b: string): boolean;
-/**
- * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
- * 支持 127.0.0.1, localhost, ::1 等形式。
- *
- * @param host 主机名或 IP 字符串
- */
-export declare function isLoopbackHost(host: string): boolean;
 /**
  * 校验 HTTP 请求中的鉴权令牌选项。
  */

package/dist/server/security.js

@@ -1,4 +1,6 @@
 import { timingSafeEqual } from "node:crypto";
+// isLoopbackHost 已上移至 utils/net.ts（通用谓词单一事实源），此处仅保留 re-export 兼容旧引用路径
+export { isLoopbackHost } from "../utils/net.js";
 /**
  * 恒定时间字符串比较（Constant-time comparison）。
  * 使用底层的 `crypto.timingSafeEqual` 防范时序攻击（Timing Attack）。
@@ -15,19 +17,6 @@ export function safeEqual(a, b) {
     }
     return timingSafeEqual(aa, bb);
 }
-/**
- * 检查指定的主机地址是否为本地回环接口（Loopback Host）。
- * 支持 127.0.0.1, localhost, ::1 等形式。
- *
- * @param host 主机名或 IP 字符串
- */
-export function isLoopbackHost(host) {
-    const trimmed = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
-    return (trimmed === "127.0.0.1" ||
-        trimmed === "::1" ||
-        trimmed === "localhost" ||
-        trimmed === "0:0:0:0:0:0:0:1");
-}
 /**
  * 校验 HTTP 请求中的鉴权令牌是否有效。
  *

package/dist/storage/clock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 统一时间与时钟基础契约。
+ *
+ * 单一事实源：Clock 接口与 SystemClock 实现定义于此，runtime/clock.ts 与
+ * storage/types.ts 一律从本文件引用或转发，禁止重复实现。
+ */
+/**
+ * 统一时间与时钟接口。
+ */
+export interface Clock {
+    /** 获取当前系统墙上时间 */
+    now(): Date;
+    /** 获取单调递增时间戳（单位：毫秒） */
+    monotonic(): number;
+    /** 异步休眠指定毫秒 */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * 生产环境系统时钟实现。
+ */
+export declare class SystemClock implements Clock {
+    now(): Date;
+    monotonic(): number;
+    sleep(ms: number): Promise<void>;
+}

package/dist/storage/clock.js

@@ -0,0 +1,23 @@
+/**
+ * 统一时间与时钟基础契约。
+ *
+ * 单一事实源：Clock 接口与 SystemClock 实现定义于此，runtime/clock.ts 与
+ * storage/types.ts 一律从本文件引用或转发，禁止重复实现。
+ */
+/**
+ * 生产环境系统时钟实现。
+ */
+export class SystemClock {
+    now() {
+        return new Date();
+    }
+    monotonic() {
+        if (typeof performance !== "undefined" && typeof performance.now === "function") {
+            return performance.now();
+        }
+        return Date.now();
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}

package/dist/storage/data-dir-lock.d.ts

@@ -1,3 +1,4 @@
+import { cleanStaleQuarantines, isProcessAlive, parseQuarantineTimestamp, safeRemoveStaleReclaimGuard, safeRollbackLock } from "./lock-core.js";
 /**
  * 数据目录排他锁元数据契约。
  */
@@ -17,41 +18,7 @@ export interface DataDirLockInfo {
     /** 宿主会话标识 */
     hostSessionId?: string;
 }
-/**
- * 检查目标进程是否处于存活状态。
- *
- * @param pid 待检测的进程标识符
- */
-export declare function isProcessAlive(pid: number): boolean;
-/**
- * 安全清理陈旧接管守卫（reclaim guard）。
- * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
- *
- * @param reclaimPath 目标守卫路径
- * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
- */
-export declare function safeRemoveStaleReclaimGuard(reclaimPath: string, expectedGuardToken: string): void;
-/**
- * 从隔离或回滚临时目录名称中解析操作者 PID 与隔离生成时间戳。
- * 命名规范：*.(quarantine|rollback|release).<pid>.<timestamp>.<uuid>
- */
-export declare function parseQuarantineTimestamp(entryName: string): {
-    operatorPid?: number;
-    timestamp?: number;
-};
-/**
- * 清理过期的隔离目录（GC 回收机制）。
- * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏：
- * - 共同前置条件：存活年龄必须超过 maxAgeMs（默认 10000ms），未超期前严禁清理（保持宽限期）。
- * - 活跃隔离目录（quarantine / rollback / release）：若 operatorPid 存活或内部 metadata.json 记录的 pid 与 childPids 存活，跳过不予清理。
- * - 孤儿脱离目录（orphan）：内部旧 metadata.pid 不再作为续命依据；提取其内部 orphanToken，仅当当前规范主路径（主锁目录与 reclaim 目录）依然持有该凭证时保守跳过；规范路径不存在或已变更凭据时直接安全清理。
- */
-export declare function cleanStaleQuarantines(parentDir: string, basePrefix: string, maxAgeMs?: number, deadline?: number): void;
-/**
- * 安全回滚当前进程创建的主锁。
- * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
- */
-export declare function safeRollbackLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+export { isProcessAlive, parseQuarantineTimestamp, cleanStaleQuarantines, safeRemoveStaleReclaimGuard, safeRollbackLock, };
 /**
  * 安全释放主锁。
  * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
@@ -95,7 +62,7 @@ export declare class DataDirLock {
     /**
      * 尝试获取指定数据目录的排他锁。
      *
-     * 仲裁规则：
+     * 仲裁规则由目录锁内核（lock-core）统一承载：
      * - 引入所有竞争者均遵守的原子 reclaim guard 机制（lockDirPath.reclaim），每个 guard 具备全局唯一 guardToken。
      * - 基于原子目录创建 mkdirSync(lockDirPath, { mode: 0o700 }) 确立所有权，并在其下存放 metadata.json。
      * - 兼容已有常规文件锁（如老版本或测试 mock 场景）。