@actiondock/core 2.6.0 → 2.8.0

package/dist/ipc/target.js

@@ -1,365 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { fork } from "node:child_process";
-import { DiagnosticForwarder } from "./diagnostic.js";
-import { EXECUTION_ABORTED, HOST_PROCESS_EXITED } from "../errors.js";
-/**
- * 跨进程取消信号占位标记字段名。
- * AbortSignal 不可序列化，序列化 options 时把 signal 字段替换为该标记，
- * 宿主侧识别后重建 AbortController 并接入 abort 消息通知链路。
- */
-export const IPC_SIGNAL_MARKER = "__ipcSignal";
-/**
- * 判断执行选项中是否携带跨进程取消信号占位标记。
- *
- * @param value 待检查的选项值
- */
-export function hasIpcSignalMarker(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value[IPC_SIGNAL_MARKER] === true);
-}
-/**
- * 序列化执行选项：剥离不可序列化的 AbortSignal 并写入占位标记。
- * 未携带 signal 时返回浅拷贝，避免消息通道直接持有调用方原始对象。
- *
- * @param options 原始执行选项
- */
-function markIpcSignal(options) {
-    if (!options)
-        return undefined;
-    const { signal: _signal, ...rest } = options;
-    if (!_signal)
-        return rest;
-    return { ...rest, [IPC_SIGNAL_MARKER]: true };
-}
-/**
- * 基于 Node IPC 监督进程通信通道的 ActionDockTarget 实现。
- *
- * 职责：
- * 1. 监督并隔离子进程的生命周期与标准输出，保证父进程标准输入输出通道 100% 纯净。
- * 2. 将子进程标准输出/错误通过 DiagnosticForwarder 进行受控排空与诊断流限流转发。
- * 3. 当子进程异常终止时，立即将当前活跃调用转换为结构化 HOST_PROCESS_EXITED 错误，防止调用方死锁。
- */
-export class IpcActionDockTarget {
-    child;
-    forwarder;
-    pendingCalls = new Map();
-    isClosed = false;
-    exitError;
-    readyPromise;
-    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("IpcActionDockTarget requires either 'childProcess' or 'scriptPath'");
-        }
-        // 绑定子进程输出至受控限流排空器，绝不泄露至 process.stdout
-        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 Error(resp.error?.message || "IPC Target call failed");
-                        if (resp.error?.code)
-                            err.code = resp.error.code;
-                        if (resp.error?.details)
-                            err.details = 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 Error(exitMsg);
-            err.code = "HOST_PROCESS_EXITED";
-            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();
-            resolveReady(); // 避免就绪死锁
-        });
-        this.child.on("error", (err) => {
-            this.exitError = err;
-        });
-    }
-    /**
-     * 等待宿主子进程初始化就绪。
-     */
-    async waitReady(timeoutMs = 5000) {
-        if (this.exitError)
-            throw this.exitError;
-        let timer;
-        const timeout = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`Timeout waiting for host process ready after ${timeoutMs}ms`)), timeoutMs);
-        });
-        try {
-            await Promise.race([this.readyPromise, timeout]);
-        }
-        finally {
-            if (timer !== undefined) {
-                clearTimeout(timer);
-            }
-        }
-    }
-    /**
-     * 获取底层子进程实例。
-     */
-    get process() {
-        return this.child;
-    }
-    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 Error("Host process is already closed");
-        }
-        const id = randomUUID();
-        const msg = {
-            id,
-            type: "call",
-            method,
-            args,
-        };
-        // 事件驱动跨进程取消：signal 存在且未中止时注册 abort 监听，
-        // 触发即向宿主子进程发送 abort 消息，由宿主侧中止同调用控制器；
-        // 调用结束（无论成败）后注销监听，避免监听器泄漏
-        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) {
-                    this.child.send(msg);
-                }
-                else {
-                    this.pendingCalls.delete(id);
-                    reject(new Error("IPC channel unavailable on child process"));
-                }
-            }
-            catch (err) {
-                this.pendingCalls.delete(id);
-                reject(err);
-            }
-        }).finally(() => {
-            if (onAbort && signal) {
-                signal.removeEventListener("abort", onAbort);
-            }
-        });
-    }
-    /**
-     * 向宿主子进程发送跨进程取消通知，发送异常不阻断父侧调用链路。
-     *
-     * @param id 目标调用的唯一标识
-     */
-    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 Target] Failed to send abort for call '${id}': ${err instanceof Error ? err.message : String(err)}\n`);
-        }
-    }
-    async info() {
-        return this.callRemote("info", []);
-    }
-    async listPackages() {
-        return this.callRemote("listPackages", []);
-    }
-    async listActions(options) {
-        return this.callRemote("listActions", [options]);
-    }
-    async describeAction(ref) {
-        return this.callRemote("describeAction", [ref]);
-    }
-    async listPlaybooks(options) {
-        return this.callRemote("listPlaybooks", [options]);
-    }
-    async describePlaybook(id) {
-        return this.callRemote("describePlaybook", [id]);
-    }
-    async runAction(ref, input, options) {
-        if (options?.signal?.aborted) {
-            return {
-                ok: false,
-                runId: randomUUID(),
-                error: {
-                    code: EXECUTION_ABORTED,
-                    message: "Execution was aborted before starting",
-                },
-            };
-        }
-        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
-        const serializableOptions = markIpcSignal(options);
-        return this.callRemote("runAction", [ref, input, serializableOptions], options?.signal);
-    }
-    async startAction(ref, input, options) {
-        if (options?.signal?.aborted) {
-            throw new Error("Execution was aborted before starting");
-        }
-        // AbortSignal 不可序列化：以占位标记替换后随消息通道传递，宿主侧重建控制器
-        const serializableOptions = markIpcSignal(options);
-        return this.callRemote("startAction", [ref, input, serializableOptions], options?.signal);
-    }
-    async getRun(runId) {
-        const res = await this.callRemote("getRun", [runId]);
-        return res ?? undefined;
-    }
-    async cancelRun(runId) {
-        return this.callRemote("cancelRun", [runId]);
-    }
-    async listRuns(options) {
-        return this.callRemote("listRuns", [options]);
-    }
-    async *events(_runId, _options) {
-        // 基础 IPC 通道暂不流式下发历史事件
-    }
-    async listConfig(packageId) {
-        return this.callRemote("listConfig", [packageId]);
-    }
-    async getConfig(packageId, key) {
-        return this.callRemote("getConfig", [packageId, key]);
-    }
-    async setConfig(packageId, key, value) {
-        return this.callRemote("setConfig", [packageId, key, value]);
-    }
-    async deleteConfig(packageId, key) {
-        return this.callRemote("deleteConfig", [packageId, key]);
-    }
-    async getState(packageId, actionId, key, options) {
-        return this.callRemote("getState", [
-            packageId,
-            actionId,
-            key,
-            options,
-        ]);
-    }
-    async setState(packageId, actionId, key, value, options) {
-        return this.callRemote("setState", [packageId, actionId, key, value, options]);
-    }
-    async deleteState(packageId, actionId, key, options) {
-        return this.callRemote("deleteState", [packageId, actionId, key, options]);
-    }
-    async listStateKeys(packageId, actionId, options) {
-        return this.callRemote("listStateKeys", [packageId, actionId, options]);
-    }
-    async clearState(packageId, actionId, options) {
-        return this.callRemote("clearState", [packageId, actionId, options]);
-    }
-    async close() {
-        if (this.isClosed)
-            return;
-        if (this.child.exitCode !== null) {
-            this.forwarder.detachAll();
-            return;
-        }
-        const exitPromise = new Promise((resolve) => {
-            if (this.child.exitCode !== null) {
-                resolve();
-            }
-            else {
-                this.child.once("exit", () => resolve());
-            }
-        });
-        try {
-            if (this.child.connected) {
-                this.child.send({ type: "close" });
-            }
-        }
-        catch {
-            // 忽略发送关闭消息异常
-        }
-        // 若子进程超时未退出，先 SIGTERM 再 SIGKILL
-        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/platform/default.d.ts

@@ -1,38 +0,0 @@
-import type { ProcessAPI } from "@actiondock/sdk";
-import { type Clock } from "../runtime/clock.js";
-import { type ModuleLoader } from "../runtime/module-loader.js";
-import { ProcessManager } from "../process/process-manager.js";
-import type { ProcessDriver } from "../process/driver.js";
-import type { FileSystem, RuntimePlatform, StorageFactory } from "./types.js";
-/**
- * 默认运行时平台构建选项。
- */
-export interface DefaultPlatformOptions {
-    /** 平台名称覆盖（默认使用 node） */
-    name?: "node" | "test";
-    /** 自定义文件系统实现（默认使用 NodeFileSystem） */
-    files?: FileSystem;
-    /** 自定义时间与时钟驱动（默认使用 SystemClock） */
-    clock?: Clock;
-    /** 自定义进程执行驱动（默认依托 ProcessManager 与对应驱动） */
-    process?: ProcessAPI;
-    /** 可选注入的底层进程驱动 */
-    processDriver?: ProcessDriver;
-    /** 可选注入的受管进程管理器 */
-    processManager?: ProcessManager;
-    /** 自定义源码加载驱动（默认使用 DefaultModuleLoader） */
-    modules?: ModuleLoader;
-    /** 自定义存储工厂（默认基于 core/storage 构造） */
-    storage?: StorageFactory;
-    /** 自定义 ActionDock 家目录 */
-    customHome?: string;
-    /** 自定义全局数据存储目录 */
-    dataDir?: string;
-    /** 文件系统沙箱根目录 */
-    rootDir?: string;
-}
-/**
- * 创建默认 RuntimePlatform 平台实例。
- * 直接基于 Node 原生与 Core 内核能力组装平台，禁止任何全局单例状态。
- */
-export declare function createDefaultPlatform(options?: DefaultPlatformOptions): RuntimePlatform;

package/dist/platform/default.js

@@ -1,78 +0,0 @@
-import { SystemClock } from "../runtime/clock.js";
-import { DefaultModuleLoader } from "../runtime/module-loader.js";
-import { ProcessError, UNSUPPORTED_CAPABILITY } from "../errors.js";
-import { ProcessManager } from "../process/process-manager.js";
-import { createGlobalStorage as coreCreateGlobalStorage, createStorage as coreCreateStorage, } from "../storage/index.js";
-import { NodeFileSystem } from "./node-fs.js";
-/**
- * 构造不支持进程能力的 ProcessAPI：
- * 默认平台不含进程驱动，任何进程操作均抛出明确错误，
- * 指引调用方显式注入 processDriver 或改用 @actiondock/runtime-node 的 createNodePlatform。
- */
-function createUnsupportedProcessApi() {
-    const unsupported = (operation) => Promise.reject(new ProcessError(UNSUPPORTED_CAPABILITY, `The default platform does not bundle a process driver, so process.${operation} is unavailable. ` +
-        "Explicitly inject a processDriver (for example MemoryProcessDriver from @actiondock/core for testing) " +
-        "or use createNodePlatform from @actiondock/runtime-node, which provides NodeProcessDriver."));
-    return {
-        run: () => unsupported("run"),
-        start: () => unsupported("start"),
-        inspect: () => unsupported("inspect"),
-        list: () => unsupported("list"),
-        acquire: () => unsupported("acquire"),
-        renew: () => unsupported("renew"),
-        release: () => unsupported("release"),
-        write: () => unsupported("write"),
-        operation: () => unsupported("operation"),
-        read: () => unsupported("read"),
-        control: () => unsupported("control"),
-        stop: () => unsupported("stop"),
-    };
-}
-/**
- * 创建默认 RuntimePlatform 平台实例。
- * 直接基于 Node 原生与 Core 内核能力组装平台，禁止任何全局单例状态。
- */
-export function createDefaultPlatform(options = {}) {
-    const platformName = options.name ?? "node";
-    const clock = options.clock ?? new SystemClock();
-    const files = options.files ?? new NodeFileSystem({ rootDir: options.rootDir });
-    const modules = options.modules ?? new DefaultModuleLoader();
-    // 未注入底层驱动时不静默回退内存模拟驱动：默认平台不提供可用进程能力，
-    // 避免默认路径下的进程调用无声挂死或必然超时
-    const processDriver = options.processDriver;
-    const processManager = options.processManager ??
-        (processDriver ? new ProcessManager({ driver: processDriver }) : undefined);
-    const process = options.process ??
-        (processManager
-            ? processManager.forOwner({
-                tenantId: "default",
-                principalId: "default",
-                packageInstanceId: "default",
-                generationId: "default",
-            })
-            : createUnsupportedProcessApi());
-    const storage = options.storage ?? {
-        createStorage(packageId, opts) {
-            return coreCreateStorage(packageId, {
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
-            });
-        },
-        createGlobalStorage(opts) {
-            return coreCreateGlobalStorage({
-                customHome: options.customHome,
-                dataDir: options.dataDir,
-                ...opts,
-            });
-        },
-    };
-    return {
-        name: platformName,
-        clock,
-        files,
-        modules,
-        process,
-        storage,
-    };
-}

package/dist/project/resolver.d.ts

@@ -1,116 +0,0 @@
-import { type ActionDockLockfile } from "./lockfile.js";
-import type { ActionDockManifest, PlaybookDefinition } from "./types.js";
-/**
- * 语义化版本元数据结构。
- */
-export interface SemVer {
-    major: number;
-    minor: number;
-    patch: number;
-    prerelease?: string;
-}
-/**
- * 解析基础 SemVer 版本字符串。
- */
-export declare function parseSemVer(v: string): SemVer | null;
-/**
- * 校验两个语义化版本范围是否兼容并能收敛为单一解析版本。
- * 遵循设计规范：直接或传递版本范围无法收敛时拒绝并抛出 ACTION_PACKAGE_VERSION_CONFLICT。
- */
-export declare function areVersionsCompatible(v1: string, v2: string): boolean;
-/**
- * 版本冲突错误。
- */
-export declare class ActionPackageVersionConflictError extends Error {
-    readonly code = "ACTION_PACKAGE_VERSION_CONFLICT";
-    readonly packageId: string;
-    readonly conflicts: Array<{
-        requester: string;
-        rangeOrVersion: string;
-    }>;
-    constructor(packageId: string, conflicts: Array<{
-        requester: string;
-        rangeOrVersion: string;
-    }>);
-}
-/**
- * 未声明依赖调用拦截错误。
- */
-export declare class UndeclaredActionDependencyError extends Error {
-    readonly code = "UNDECLARED_ACTION_DEPENDENCY";
-    readonly targetRef: string;
-    readonly caller?: string;
-    constructor(targetRef: string, caller?: string, reason?: string);
-}
-/**
- * 已解析 Action 包信息。
- */
-export interface ResolvedPackageInfo {
-    packageId: string;
-    npmPackage: string;
-    version: string;
-    packageRoot: string;
-    manifest: ActionDockManifest;
-    manifestDigest: string;
-    isDirect: boolean;
-    isRoot: boolean;
-}
-/**
- * 完整 Action 包依赖图结构。
- */
-export interface DependencyGraph {
-    rootPackageId: string;
-    packages: Map<string, ResolvedPackageInfo>;
-    directDependencyIds: Set<string>;
-    transitiveDependencyIds: Set<string>;
-    visiblePlaybooks: Map<string, PlaybookDefinition>;
-    delegatedActions: Set<string>;
-}
-export interface ActionPackageResolverOptions {
-    projectRoot: string;
-    manifest?: ActionDockManifest;
-    lockfile?: ActionDockLockfile;
-    allowDevLinks?: boolean;
-    customHome?: string;
-    packageRoots?: Record<string, string>;
-}
-/**
- * 依赖解析器 ActionPackageResolver。
- * 负责从 actiondock.json.dependencies 与 actiondock.lock.json 建立包索引与依赖闭包，
- * 实施版本冲突检测与调用可见性鉴权。
- */
-export declare class ActionPackageResolver {
-    readonly projectRoot: string;
-    private options;
-    private resolvedGraph?;
-    constructor(options: ActionPackageResolverOptions);
-    /**
-     * 同步解析依赖图。
-     */
-    resolveSync(): DependencyGraph;
-    /**
-     * 异步解析依赖图。
-     */
-    resolve(): Promise<DependencyGraph>;
-    /**
-     * 判定目标 Action 是否允许作为根调用发起。
-     * 规则：
-     * - 目标属于当前根包；
-     * - 目标属于 actiondock.json 直接依赖；
-     * - 目标属于可见 Playbook 精确委托点名的 Action。
-     */
-    canRootCall(targetPackageId: string, targetActionId: string): boolean;
-    /**
-     * 校验根调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
-     */
-    assertRootCallAllowed(targetPackageId: string, targetActionId: string): void;
-    /**
-     * 判定跨包级联调用是否合法。
-     * 规则：调用者 Action 必须在 actiondock.json 的 uses 中显式声明对目标 Action 的依赖。
-     */
-    canCascadeCall(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): boolean;
-    /**
-     * 校验跨包级联调用权限，不合法时抛出 UNDECLARED_ACTION_DEPENDENCY。
-     */
-    assertCascadeCallAllowed(callerPackageId: string, callerActionId: string, targetPackageId: string, targetActionId: string): void;
-}