@actiondock/core 2.7.0 → 2.8.0

package/dist/ipc/diagnostic.js

@@ -25,18 +25,6 @@ export class DiagnosticForwarder {
         this.prefix = options.prefix ?? "";
         this.onTruncated = options.onTruncated;
     }
-    /**
-     * 是否已达到上限并处于截断状态。
-     */
-    get isTruncated() {
-        return this.truncated;
-    }
-    /**
-     * 已成功转发的累计字节数。
-     */
-    get bytesEmitted() {
-        return this.totalBytesEmitted;
-    }
     /**
      * 绑定并监听可读流（如 childProcess.stdout 或 childProcess.stderr）。
      *
@@ -117,13 +105,4 @@ export class DiagnosticForwarder {
         }
         this.attachedStreams.clear();
     }
-    /**
-     * 重置计数器与截断标志。
-     */
-    reset() {
-        this.totalBytesEmitted = 0;
-        this.bytesInCurrentWindow = 0;
-        this.windowStartMs = Date.now();
-        this.truncated = false;
-    }
 }

package/dist/ipc/host.d.ts

@@ -1,12 +1,12 @@
-import type { ActionDockTarget } from "../target/types.js";
+import type { ActionDockService } from "../service/types.js";
 /**
- * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockService 门面能力。
  *
  * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
  * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
  * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
  * 调用完成后清理映射，确保取消信号全链路透传。
  *
- * @param target 已构造好的 ActionDockTarget 实例
+ * @param service 已构造好的 ActionDockService 实例
  */
-export declare function serveParentIpc(target: ActionDockTarget): Promise<void>;
+export declare function serveParentIpc(service: ActionDockService): Promise<void>;

package/dist/ipc/host.js

@@ -1,47 +1,49 @@
-import { TARGET_CAPABILITY_UNAVAILABLE } from "../target/types.js";
-import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./target.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, SERVICE_ERROR } from "../errors.js";
+import { hasIpcSignalMarker, IPC_SIGNAL_MARKER } from "./service.js";
 /**
- * IPC 通道允许反射调用的目标方法白名单。
+ * IPC 通道方法分发表：方法名到目标调用的唯一事实源。
  *
- * 严格对齐 ActionDockTarget 公共接口方法名集合：白名单之外的方法一律拒绝，
- * 防止 IPC 消息通道触达任意内部属性或危险方法（如 close 之外的私有能力）。
+ * 严格对齐 ActionDockService 公共方法集合：表之外的方法一律拒绝，
+ * 防止 IPC 消息通道触达任意内部属性或危险方法。
+ * 白名单即分发表的键集合，杜绝两份清单重复维护漂移。
  */
-const IPC_ALLOWED_METHODS = new Set([
-    "info",
-    "listPackages",
-    "listActions",
-    "describeAction",
-    "listPlaybooks",
-    "describePlaybook",
-    "runAction",
-    "startAction",
-    "listRuns",
-    "getRun",
-    "cancelRun",
-    "clearRuns",
-    "events",
-    "getConfig",
-    "setConfig",
-    "deleteConfig",
-    "listConfig",
-    "getState",
-    "setState",
-    "deleteState",
-    "listStateKeys",
-    "clearState",
-    "listStateEntries",
-]);
+const IPC_METHOD_HANDLERS = {
+    info: async (service) => service.info(),
+    listPackages: async (service) => service.discovery.listPackages(),
+    listActions: async (service, a) => service.discovery.listActions(a[0]),
+    describeAction: async (service, a) => service.discovery.describeAction(a[0]),
+    listPlaybooks: async (service, a) => service.discovery.listPlaybooks(a[0]),
+    describePlaybook: async (service, a) => service.discovery.describePlaybook(a[0]),
+    runAction: async (service, a) => service.execution.run(a[0], a[1], a[2]),
+    startAction: async (service, a) => service.execution.start(a[0], a[1], a[2]),
+    listRuns: async (service, a) => service.runs.list(a[0]),
+    getRun: async (service, a) => service.runs.get(a[0]),
+    cancelRun: async (service, a) => service.runs.cancel(a[0], a[1]),
+    clearRuns: async (service, a) => service.runs.clear ? await service.runs.clear(a[0]) : 0,
+    getConfig: async (service, a) => service.management?.config.get(a[0], a[1]),
+    setConfig: async (service, a) => service.management?.config.set(a[0], a[1], a[2]),
+    deleteConfig: async (service, a) => service.management?.config.delete(a[0], a[1]),
+    listConfig: async (service, a) => service.management?.config.list(a[0]),
+    getState: async (service, a) => service.management?.state.get(a[0], a[1], a[2], a[3]),
+    setState: async (service, a) => service.management?.state.set(a[0], a[1], a[2], a[3], a[4]),
+    deleteState: async (service, a) => service.management?.state.delete(a[0], a[1], a[2], a[3]),
+    listStateKeys: async (service, a) => service.management?.state.list(a[0], a[1], a[2]),
+    clearState: async (service, a) => service.management?.state.clear(a[0], a[1], a[2]),
+    listStateEntries: async (service, a) => service.management?.state.listEntries
+        ? await service.management.state.listEntries(a[0], a[1])
+        : [],
+};
 /**
- * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockTarget 门面能力。
+ * 在 Host 子进程中启动 Node IPC 服务，向父进程暴露 ActionDockService 门面能力。
  *
  * 跨进程取消链路：监督进程序列化执行选项时把 AbortSignal 替换为占位标记，
  * 本侧反序列化时识别标记并重建 AbortController 传入目标调用，同时维护
  * 调用 id 到控制器的映射；收到 abort 消息时触发对应控制器中止，
  * 调用完成后清理映射，确保取消信号全链路透传。
  *
- * @param target 已构造好的 ActionDockTarget 实例
+ * @param service 已构造好的 ActionDockService 实例
  */
-export async function serveParentIpc(target) {
+export async function serveParentIpc(service) {
     if (!process.send) {
         // 若当前未以 IPC 模式运行，直接退出
         return;
@@ -52,7 +54,7 @@ export async function serveParentIpc(target) {
             return;
         isClosing = true;
         try {
-            await target.close();
+            await service.close();
         }
         catch {
             // 忽略关闭异常
@@ -97,19 +99,14 @@ export async function serveParentIpc(target) {
             const callMsg = msg;
             const { id, method, args } = callMsg;
             try {
-                // 白名单校验：仅允许 ActionDockTarget 公共接口方法，阻止任意方法反射调用
-                if (typeof method !== "string" || !IPC_ALLOWED_METHODS.has(method)) {
-                    const err = new Error(`Target method '${method}' is not allowed over IPC (not in ActionDockTarget public interface)`);
-                    err.code = TARGET_CAPABILITY_UNAVAILABLE;
-                    throw err;
-                }
-                const fn = target[method];
-                if (typeof fn !== "function") {
-                    throw new Error(`Target method '${method}' not found`);
+                // 白名单校验：仅允许分发表内方法，阻止任意方法反射调用
+                const handler = typeof method === "string" ? IPC_METHOD_HANDLERS[method] : undefined;
+                if (!handler) {
+                    throw new ActionDockError(CAPABILITY_UNAVAILABLE, `Target method '${method}' is not allowed over IPC`);
                 }
                 // 反序列化执行选项：识别取消信号占位标记并重建控制器接入取消链路
-                const revivedArgs = (args || []).map((arg) => reviveIpcSignal(id, arg));
-                const result = await fn.apply(target, revivedArgs);
+                const a = (args || []).map((arg) => reviveIpcSignal(id, arg));
+                const result = await handler(service, a);
                 const response = {
                     id,
                     type: "response",
@@ -126,7 +123,7 @@ export async function serveParentIpc(target) {
                     type: "response",
                     ok: false,
                     error: {
-                        code: err?.code || "TARGET_ERROR",
+                        code: err?.code || SERVICE_ERROR,
                         message: err?.message || String(err),
                         stack: err?.stack,
                         details: err?.details,
@@ -162,7 +159,7 @@ export async function serveParentIpc(target) {
             }
         }
         else {
-            // 向后兼容：旧版本对端可能推送未知消息类型，防御性忽略并记录诊断，不中断通道
+            // 防御性忽略未知消息类型并记录诊断，不中断通道
             process.stderr.write(`[IPC Host] Ignoring unknown IPC message type: ${JSON.stringify(msg.type)}\n`);
         }
     });

package/dist/ipc/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types.js";
 export * from "./diagnostic.js";
 export * from "./host.js";
-export * from "./target.js";
+export * from "./service.js";

package/dist/ipc/index.js

@@ -1,4 +1,4 @@
 export * from "./types.js";
 export * from "./diagnostic.js";
 export * from "./host.js";
-export * from "./target.js";
+export * from "./service.js";

package/dist/ipc/service.d.ts

@@ -0,0 +1,40 @@
+import { type ChildProcess } from "node:child_process";
+import type { PackageInfo } from "../package/types.js";
+import type { ActionDockService, ConfigPort, DiscoveryPort, ExecutionPort, RunsPort, StatePort } from "../service/types.js";
+import type { IpcServiceOptions } from "./types.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export declare const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ */
+export declare function hasIpcSignalMarker(value: unknown): value is Record<string, unknown>;
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
+ * 遵循标准 Service Ports 体系，隔离子进程生命周期并暴露结构化服务端口。
+ */
+export declare class IpcActionDockService implements ActionDockService {
+    private child;
+    private forwarder;
+    private pendingCalls;
+    private isClosed;
+    private exitError?;
+    private readyPromise;
+    readonly discovery: DiscoveryPort;
+    readonly execution: ExecutionPort;
+    readonly runs: RunsPort;
+    readonly management?: {
+        config: ConfigPort;
+        state: StatePort;
+    };
+    constructor(options: IpcServiceOptions);
+    private callRemote;
+    private sendAbort;
+    info(): Promise<PackageInfo[]>;
+    get process(): ChildProcess;
+    waitReady(): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/ipc/service.js

@@ -0,0 +1,349 @@
+import { randomUUID } from "node:crypto";
+import { fork } from "node:child_process";
+import { DiagnosticForwarder } from "./diagnostic.js";
+import { ActionDockError, CAPABILITY_UNAVAILABLE, EXECUTION_ABORTED, HOST_PROCESS_EXITED, IPC_ERROR, SERVICE_CLOSED, } from "../errors.js";
+/**
+ * 跨进程取消信号占位标记字段名。
+ * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
+ * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
+ */
+export const IPC_SIGNAL_MARKER = "__ipcSignal";
+/**
+ * 判断执行选项中是否携带跨进程取消信号占位标记。
+ */
+export function hasIpcSignalMarker(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[IPC_SIGNAL_MARKER] === true);
+}
+/**
+ * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
+ */
+function markIpcSignal(options) {
+    if (!options)
+        return undefined;
+    const clean = {};
+    if (options.timeoutMs !== undefined)
+        clean.timeoutMs = options.timeoutMs;
+    if (options.config !== undefined)
+        clean.config = options.config;
+    if (options.requestId !== undefined)
+        clean.requestId = options.requestId;
+    if (options.signal) {
+        clean[IPC_SIGNAL_MARKER] = true;
+    }
+    return clean;
+}
+/**
+ * 基于 Node IPC 监督进程通信通道的 ActionDockService 实现。
+ * 遵循标准 Service Ports 体系，隔离子进程生命周期并暴露结构化服务端口。
+ */
+export class IpcActionDockService {
+    child;
+    forwarder;
+    pendingCalls = new Map();
+    isClosed = false;
+    exitError;
+    readyPromise;
+    discovery;
+    execution;
+    runs;
+    management;
+    constructor(options) {
+        this.forwarder = new DiagnosticForwarder({
+            maxBytes: options.maxDiagnosticBytes,
+            maxRateBytesPerSec: options.maxDiagnosticRate,
+            target: options.diagnosticTarget,
+        });
+        if (options.childProcess) {
+            this.child = options.childProcess;
+        }
+        else if (options.scriptPath) {
+            this.child = fork(options.scriptPath, options.scriptArgs || [], {
+                cwd: options.cwd || process.cwd(),
+                env: options.env || process.env,
+                stdio: ["pipe", "pipe", "pipe", "ipc"],
+            });
+        }
+        else {
+            throw new Error("IpcActionDockService requires either 'childProcess' or 'scriptPath'");
+        }
+        if (this.child.stdout) {
+            this.forwarder.attach(this.child.stdout, "stdout");
+        }
+        if (this.child.stderr) {
+            this.forwarder.attach(this.child.stderr, "stderr");
+        }
+        let resolveReady;
+        this.readyPromise = new Promise((r) => {
+            resolveReady = r;
+        });
+        this.child.on("message", (msg) => {
+            if (!msg || typeof msg !== "object")
+                return;
+            if (msg.type === "ready") {
+                resolveReady();
+            }
+            else if (msg.type === "response") {
+                const resp = msg;
+                const pending = this.pendingCalls.get(resp.id);
+                if (pending) {
+                    this.pendingCalls.delete(resp.id);
+                    if (resp.ok) {
+                        pending.resolve(resp.data);
+                    }
+                    else {
+                        const err = new ActionDockError(resp.error?.code || IPC_ERROR, resp.error?.message || "IPC Service call failed", resp.error?.details);
+                        pending.reject(err);
+                    }
+                }
+            }
+        });
+        this.child.on("exit", (code, signal) => {
+            const exitMsg = `Host process exited prematurely with code ${code ?? signal ?? "unknown"}`;
+            const err = new ActionDockError(HOST_PROCESS_EXITED, exitMsg);
+            this.exitError = err;
+            this.isClosed = true;
+            // 快速失败所有待处理调用
+            for (const pending of this.pendingCalls.values()) {
+                if (pending.method === "runAction") {
+                    pending.resolve({
+                        ok: false,
+                        runId: randomUUID(),
+                        error: {
+                            code: HOST_PROCESS_EXITED,
+                            message: exitMsg,
+                        },
+                    });
+                }
+                else {
+                    pending.reject(err);
+                }
+            }
+            this.pendingCalls.clear();
+            this.forwarder.detachAll();
+            resolveReady();
+        });
+        const self = this;
+        /**
+         * 生成方法级端口转发器：把端口方法调用映射为 callRemote 远端调用。
+         * 方法名与参数列表的对应关系即唯一事实源，杜绝手写转发样板膨胀。
+         */
+        const forward = (method, args) => self.callRemote(method, args);
+        this.discovery = {
+            async listPackages() {
+                return forward("listPackages", []);
+            },
+            async listActions(opts) {
+                return forward("listActions", [opts]);
+            },
+            async describeAction(ref) {
+                return forward("describeAction", [ref]);
+            },
+            async listPlaybooks(opts) {
+                return forward("listPlaybooks", [opts]);
+            },
+            async describePlaybook(id) {
+                return forward("describePlaybook", [id]);
+            },
+        };
+        this.execution = {
+            async run(ref, input, opts) {
+                if (opts?.signal?.aborted) {
+                    return {
+                        ok: false,
+                        runId: randomUUID(),
+                        error: {
+                            code: EXECUTION_ABORTED,
+                            message: "Execution was aborted before starting",
+                        },
+                    };
+                }
+                const serializableOptions = markIpcSignal(opts);
+                return self.callRemote("runAction", [ref, input ?? {}, serializableOptions], opts?.signal);
+            },
+            async start(ref, input, opts) {
+                if (opts?.signal?.aborted) {
+                    throw new ActionDockError(EXECUTION_ABORTED, "Execution was aborted before starting");
+                }
+                const serializableOptions = markIpcSignal(opts);
+                return self.callRemote("startAction", [ref, input ?? {}, serializableOptions], opts?.signal);
+            },
+        };
+        this.runs = {
+            async list(query) {
+                return forward("listRuns", [query]);
+            },
+            async get(runId) {
+                const res = await forward("getRun", [runId]);
+                return res ?? undefined;
+            },
+            async cancel(runId, reason) {
+                return forward("cancelRun", [runId, reason]);
+            },
+            async clear(opts) {
+                return forward("clearRuns", [opts]);
+            },
+        };
+        if (options.enableManagement !== false) {
+            this.management = {
+                config: {
+                    async get(packageId, key) {
+                        return forward("getConfig", [packageId, key]);
+                    },
+                    async set(packageId, key, value) {
+                        return forward("setConfig", [packageId, key, value]);
+                    },
+                    async delete(packageId, key) {
+                        return forward("deleteConfig", [packageId, key]);
+                    },
+                    async list(packageId) {
+                        return forward("listConfig", [packageId]);
+                    },
+                },
+                state: {
+                    async get(packageId, actionId, key, opts) {
+                        return forward("getState", [packageId, actionId, key, opts]);
+                    },
+                    async set(packageId, actionId, key, value, opts) {
+                        return forward("setState", [packageId, actionId, key, value, opts]);
+                    },
+                    async delete(packageId, actionId, key, opts) {
+                        return forward("deleteState", [packageId, actionId, key, opts]);
+                    },
+                    async list(packageId, actionId, opts) {
+                        return forward("listStateKeys", [packageId, actionId, opts]);
+                    },
+                    async clear(packageId, actionId, opts) {
+                        return forward("clearState", [packageId, actionId, opts]);
+                    },
+                    async listEntries(packageId, opts) {
+                        return forward("listStateEntries", [packageId, opts]);
+                    },
+                },
+            };
+        }
+    }
+    async callRemote(method, args, signal) {
+        if (this.isClosed || this.exitError) {
+            if (method === "runAction") {
+                return {
+                    ok: false,
+                    runId: randomUUID(),
+                    error: {
+                        code: HOST_PROCESS_EXITED,
+                        message: this.exitError?.message || "Host process is already closed",
+                    },
+                };
+            }
+            throw this.exitError || new ActionDockError(SERVICE_CLOSED, `IpcActionDockService is closed: cannot call '${method}'`);
+        }
+        await this.readyPromise;
+        if (signal?.aborted) {
+            const err = new Error(signal.reason ? String(signal.reason) : "Operation aborted");
+            err.name = "AbortError";
+            throw err;
+        }
+        const id = randomUUID();
+        const message = {
+            id,
+            type: "call",
+            method,
+            args,
+        };
+        let onAbort;
+        if (signal && !signal.aborted) {
+            onAbort = () => {
+                this.sendAbort(id);
+            };
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingCalls.set(id, { resolve, reject, method });
+            try {
+                if (!this.child.send) {
+                    throw new ActionDockError(CAPABILITY_UNAVAILABLE, "ChildProcess IPC channel is not available");
+                }
+                this.child.send(message, (err) => {
+                    if (err) {
+                        this.pendingCalls.delete(id);
+                        reject(err);
+                    }
+                });
+            }
+            catch (err) {
+                this.pendingCalls.delete(id);
+                reject(err);
+            }
+        }).finally(() => {
+            if (onAbort && signal) {
+                signal.removeEventListener("abort", onAbort);
+            }
+        });
+    }
+    sendAbort(id) {
+        if (this.isClosed)
+            return;
+        try {
+            const abortMsg = { id, type: "abort" };
+            if (this.child.send) {
+                this.child.send(abortMsg);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[IPC Service] Failed to send abort for call '${id}': ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+    }
+    async info() {
+        return this.discovery.listPackages();
+    }
+    get process() {
+        return this.child;
+    }
+    async waitReady() {
+        return this.readyPromise;
+    }
+    async close() {
+        if (this.isClosed)
+            return;
+        if (this.child.exitCode !== null) {
+            this.forwarder.detachAll();
+            return;
+        }
+        const exitPromise = new Promise((resolve) => {
+            this.child.once("exit", () => resolve());
+        });
+        try {
+            if (this.child.connected) {
+                this.child.send({ type: "close" });
+            }
+        }
+        catch {
+            // 忽略发送关闭消息异常
+        }
+        const termTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGTERM");
+                }
+                catch { }
+            }
+        }, 1500);
+        const killTimer = setTimeout(() => {
+            if (this.child.exitCode === null) {
+                try {
+                    this.child.kill("SIGKILL");
+                }
+                catch { }
+            }
+        }, 3000);
+        try {
+            await exitPromise;
+        }
+        finally {
+            clearTimeout(termTimer);
+            clearTimeout(killTimer);
+            this.forwarder.detachAll();
+        }
+    }
+}

package/dist/ipc/types.d.ts

@@ -32,20 +32,26 @@ export interface IpcResponseMessage {
     };
 }
 /**
- * 宿主子进程向监督进程流式推送的执行事件。
+ * 监督进程 IPC 服务初始化选项。
  */
-export interface IpcEventMessage {
-    type: "event";
-    runId: string;
-    event: unknown;
+export interface IpcServiceOptions {
+    type?: "ipc";
+    /** 已启动的子进程实例（需具备 IPC 通道） */
+    childProcess?: any;
+    /** 待启动的脚本物理路径 */
+    scriptPath?: string;
+    /** 启动参数 */
+    scriptArgs?: string[];
+    /** 工作目录 */
+    cwd?: string;
+    /** 环境变量 */
+    env?: NodeJS.ProcessEnv;
+    /** 诊断流最大缓冲字节数 */
+    maxDiagnosticBytes?: number;
+    /** 诊断流每秒最大字节速率 */
+    maxDiagnosticRate?: number;
+    /** 诊断流目标输出 */
+    diagnosticTarget?: any;
+    /** 是否启用管理端口（默认 true） */
+    enableManagement?: boolean;
 }
-/**
- * 宿主子进程初始化就绪通知。
- */
-export interface IpcReadyMessage {
-    type: "ready";
-}
-/**
- * 联合 IPC 消息类型。
- */
-export type IpcMessage = IpcCallMessage | IpcResponseMessage | IpcAbortMessage | IpcEventMessage | IpcReadyMessage;

package/dist/node/index.d.ts

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

package/dist/node/index.js

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