@actiondock/core 2.7.0 → 2.8.0

package/dist/process/process-driver.js

@@ -0,0 +1,650 @@
+import childProcess from "node:child_process";
+import { createRequire } from "node:module";
+import { INPUT_CLOSED, UNSUPPORTED_CAPABILITY, ProcessError, } from "../errors.js";
+import { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv, } from "./driver.js";
+export { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv };
+/**
+ * 跨平台终止进程组，确保不会遗留孤儿进程。
+ *
+ * - 在 POSIX 环境下通过负数进程标识终止整个进程组
+ * - 在 Windows 环境下优先通过 taskkill 递归终止整棵进程树，等待其完成后将 process.kill 作为失败或超时 fallback
+ *
+ * @param pid 目标子进程标识
+ * @param signal 发送的系统信号
+ * @param spawnFn 进程启动函数，默认为 childProcess.spawn
+ */
+export function killProcessGroup(pid, signal = "SIGTERM", spawnFn = childProcess.spawn) {
+    if (process.platform === "win32") {
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (!settled) {
+                    settled = true;
+                    resolve();
+                }
+            };
+            const fallbackToProcessKill = () => {
+                try {
+                    process.kill(pid, signal);
+                }
+                catch {
+                    // 忽略已退出状态
+                }
+                finish();
+            };
+            try {
+                const killer = spawnFn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+                // 超时保底 fallback：若 taskkill 超过 2000ms 仍未退出，执行 process.kill 强行兜底
+                const timer = setTimeout(() => {
+                    try {
+                        killer.kill?.();
+                    }
+                    catch {
+                        // 忽略终止失败异常
+                    }
+                    fallbackToProcessKill();
+                }, 2000);
+                timer.unref?.();
+                killer.on?.("error", () => {
+                    clearTimeout(timer);
+                    fallbackToProcessKill();
+                });
+                killer.on?.("close", (code) => {
+                    clearTimeout(timer);
+                    if (code !== 0) {
+                        fallbackToProcessKill();
+                    }
+                    else {
+                        finish();
+                    }
+                });
+            }
+            catch {
+                fallbackToProcessKill();
+            }
+        });
+    }
+    else {
+        try {
+            process.kill(-pid, signal);
+        }
+        catch {
+            try {
+                process.kill(pid, signal);
+            }
+            catch {
+                // 忽略已退出状态
+            }
+        }
+        return Promise.resolve();
+    }
+}
+/**
+ * node-pty 探测结果模块级缓存：getCapabilities 处于 spawn 热路径，
+ * createRequire 与 require 探测开销只需在首次调用时执行一次。
+ */
+let cachedCapabilities;
+/**
+ * POSIX 标准信号编号到名称的映射表（1-31，对齐 Linux 信号集）。
+ * pipe 模式下 Node 的 exit 事件直接给出 "SIGTERM" 等字符串信号名；
+ * node-pty 的 onExit 回调只给数字，必须经此表转换才能与 pipe 模式及
+ * FakeProcessDriver 的 signal 契约保持一致，杜绝 "15" 这类原始数字漂移。
+ */
+const POSIX_SIGNAL_NAMES = [
+    undefined, // 0：无信号
+    "SIGHUP", // 1
+    "SIGINT", // 2
+    "SIGQUIT", // 3
+    "SIGILL", // 4
+    "SIGTRAP", // 5
+    "SIGABRT", // 6
+    "SIGBUS", // 7
+    "SIGFPE", // 8
+    "SIGKILL", // 9
+    "SIGUSR1", // 10
+    "SIGSEGV", // 11
+    "SIGUSR2", // 12
+    "SIGPIPE", // 13
+    "SIGALRM", // 14
+    "SIGTERM", // 15
+    "SIGSTKFLT", // 16
+    "SIGCHLD", // 17
+    "SIGCONT", // 18
+    "SIGSTOP", // 19
+    "SIGTSTP", // 20
+    "SIGTTIN", // 21
+    "SIGTTOU", // 22
+    "SIGURG", // 23
+    "SIGXCPU", // 24
+    "SIGXFSZ", // 25
+    "SIGVTALRM", // 26
+    "SIGPROF", // 27
+    "SIGWINCH", // 28
+    "SIGIO", // 29
+    "SIGPWR", // 30
+    "SIGSYS", // 31
+];
+/**
+ * 将 PTY 退出回调给出的信号数字转换为标准信号名称。
+ * 0、负数与非整数视为无信号（对齐 pipe 模式的 null 语义）；
+ * 表内已知编号返回 POSIX 名称，未知编号回退 SIG<num> 形式，绝不返回原始数字字符串。
+ */
+function ptySignalToName(signal) {
+    if (typeof signal !== "number" || !Number.isInteger(signal) || signal <= 0) {
+        return null;
+    }
+    return POSIX_SIGNAL_NAMES[signal] ?? `SIG${signal}`;
+}
+/**
+ * 基于 Node.js 标准子进程实现的平台驱动。
+ * 遵循《ActionDock Managed Process 设计 v2》规范：
+ * - pipe 模式采用 child_process.spawn，支持进程组隔离与跨平台 killProcessGroup
+ * - 输出与生命周期监听在 spawn 返回前完成绑定，杜绝竞态丢失
+ * - 环境变量按 allowlisted 白名单与 none 策略严格继承，叠加 set 与 unset 变更
+ * - 写入支持背压流控与管道提早关闭异常捕获
+ * - 输入流支持 inputEOF 干净终止
+ * - 支持 5s 优雅输出排空 deadline 与 outputClosed 状态上报
+ * - PTY 模式在无 node-pty 环境明确拒绝并报告 UNSUPPORTED_CAPABILITY
+ */
+export class NodeProcessDriver {
+    drainDeadlineMs;
+    spawnFn;
+    instances = new Map();
+    constructor(options = {}) {
+        this.drainDeadlineMs = options.drainDeadlineMs ?? 5000;
+        this.spawnFn = options.spawnFn ?? childProcess.spawn;
+    }
+    /**
+     * 运行时能力集属性访问器。
+     */
+    get capabilities() {
+        return this.getCapabilities();
+    }
+    /**
+     * 获取驱动支持的运行时能力集。
+     */
+    getCapabilities() {
+        if (cachedCapabilities) {
+            return { ...cachedCapabilities };
+        }
+        let ptySupported = false;
+        try {
+            const cjsRequire = createRequire(import.meta.url);
+            cjsRequire("node-pty");
+            ptySupported = true;
+        }
+        catch {
+            ptySupported = false;
+        }
+        cachedCapabilities = {
+            pty: ptySupported,
+            resize: ptySupported,
+            inputEOF: true,
+            interruptForeground: process.platform !== "win32",
+            terminationScope: "process-tree",
+        };
+        return { ...cachedCapabilities };
+    }
+    /**
+     * 依据《Managed Process 设计 v2》标准契约启动受管进程。
+     */
+    async spawn(spec, observer) {
+        return this.spawnStandard(spec, observer, observer.processId);
+    }
+    /**
+     * 标准接口派生受管进程实现。
+     */
+    async spawnStandard(spec, observer, customId) {
+        if (spec.io.mode === "pty") {
+            return this.spawnPty(spec, observer, customId);
+        }
+        return this.spawnPipe(spec, observer, customId);
+    }
+    /**
+     * PTY 模式派生：检查运行环境能力，若缺失 node-pty 则明确抛出异常。
+     */
+    async spawnPty(spec, observer, customId) {
+        let ptyModule;
+        try {
+            const cjsRequire = createRequire(import.meta.url);
+            ptyModule = cjsRequire("node-pty");
+        }
+        catch (err) {
+            throw new ProcessError(UNSUPPORTED_CAPABILITY, `PTY mode is not supported because node-pty is unavailable: ${err?.message || String(err)}`);
+        }
+        const handleId = customId ?? crypto.randomUUID();
+        const env = resolveProcessEnv(spec.env);
+        const cols = spec.io.cols ?? 80;
+        const rows = spec.io.rows ?? 24;
+        const name = spec.io.term ?? "xterm-256color";
+        let ptyProcess;
+        try {
+            ptyProcess = ptyModule.spawn(spec.executable, spec.args, {
+                name,
+                cols,
+                rows,
+                cwd: spec.cwd,
+                env,
+            });
+        }
+        catch (err) {
+            const faultError = err instanceof Error ? err : new Error(String(err));
+            observer.fault?.(faultError);
+            observer.exited({ code: null, signal: null });
+            observer.outputClosed("natural");
+            throw faultError;
+        }
+        const exitListeners = [];
+        const instance = {
+            id: handleId,
+            pid: ptyProcess.pid,
+            child: ptyProcess,
+            observer,
+            mode: "pty",
+            ptyProcess,
+            exited: false,
+            outputClosed: false,
+            exitListeners,
+            onExit(cb) {
+                if (instance.exited) {
+                    cb();
+                }
+                else {
+                    exitListeners.push(cb);
+                }
+            },
+            cleanup() {
+                if (instance.drainTimer) {
+                    clearTimeout(instance.drainTimer);
+                    instance.drainTimer = undefined;
+                }
+                exitListeners.length = 0;
+            },
+            selfRelease: () => {
+                // 终态收敛后自移除：按实例身份判断，dispose 先行移除或表内已换新实例时不重复删除
+                if (this.instances.get(handleId) === instance) {
+                    this.instances.delete(handleId);
+                }
+            },
+        };
+        const markExited = (code, signal) => {
+            if (!instance.exited) {
+                instance.exited = true;
+                instance.exitResult = { code, signal };
+                observer.exited({ code, signal });
+                for (const listener of exitListeners) {
+                    listener();
+                }
+            }
+        };
+        const markOutputClosed = (reason) => {
+            if (instance.drainTimer) {
+                clearTimeout(instance.drainTimer);
+                instance.drainTimer = undefined;
+            }
+            if (!instance.outputClosed) {
+                instance.outputClosed = true;
+                observer.outputClosed(reason);
+            }
+            instance.selfRelease();
+        };
+        // 绑定 PTY 数据输出
+        ptyProcess.onData((data) => {
+            observer.output("pty", new TextEncoder().encode(data));
+        });
+        ptyProcess.onExit((e) => {
+            // node-pty 只回传信号数字，必须经映射表转为标准信号名与 pipe 模式对齐
+            const signalStr = ptySignalToName(e.signal);
+            markExited(e.exitCode, signalStr);
+            markOutputClosed("natural");
+        });
+        this.instances.set(handleId, instance);
+        return this.createHandleObject(instance);
+    }
+    /**
+     * pipe 模式派生：使用 child_process.spawn，同步完成监听绑定杜绝竞态。
+     */
+    async spawnPipe(spec, observer, customId) {
+        const handleId = customId ?? crypto.randomUUID();
+        const env = resolveProcessEnv(spec.env);
+        let child;
+        try {
+            child = this.spawnFn(spec.executable, spec.args, {
+                cwd: spec.cwd,
+                env,
+                stdio: ["pipe", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+            });
+        }
+        catch (err) {
+            const faultError = err instanceof Error ? err : new Error(String(err));
+            observer.fault?.(faultError);
+            observer.exited({ code: null, signal: null });
+            observer.outputClosed("natural");
+            throw faultError;
+        }
+        const exitListeners = [];
+        const instance = {
+            id: handleId,
+            pid: child.pid,
+            child,
+            observer,
+            mode: "pipe",
+            exited: false,
+            outputClosed: false,
+            exitListeners,
+            onExit(cb) {
+                if (instance.exited) {
+                    cb();
+                }
+                else {
+                    exitListeners.push(cb);
+                }
+            },
+            cleanup() {
+                if (instance.drainTimer) {
+                    clearTimeout(instance.drainTimer);
+                    instance.drainTimer = undefined;
+                }
+                exitListeners.length = 0;
+            },
+            selfRelease: () => {
+                // 终态收敛后自移除：按实例身份判断，dispose 先行移除或表内已换新实例时不重复删除
+                if (this.instances.get(handleId) === instance) {
+                    this.instances.delete(handleId);
+                }
+            },
+        };
+        const markExited = (code, signal) => {
+            if (!instance.exited) {
+                instance.exited = true;
+                instance.exitResult = { code, signal };
+                observer.exited({ code, signal });
+                for (const listener of exitListeners) {
+                    listener();
+                }
+            }
+        };
+        const markOutputClosed = (reason) => {
+            if (instance.drainTimer) {
+                clearTimeout(instance.drainTimer);
+                instance.drainTimer = undefined;
+            }
+            if (!instance.outputClosed) {
+                instance.outputClosed = true;
+                observer.outputClosed(reason);
+            }
+            instance.selfRelease();
+        };
+        // 同步完成 stdout/stderr 监听绑定，防止产生数据丢失竞态
+        if (child.stdout) {
+            child.stdout.on("data", (chunk) => {
+                observer.output("stdout", new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+            });
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (chunk) => {
+                observer.output("stderr", new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+            });
+        }
+        // 监听 stdin 错误避免未捕获 EPIPE 导致宿主异常退出
+        if (child.stdin) {
+            child.stdin.on("error", () => {
+                // 忽略管道断开异常
+            });
+        }
+        child.on("exit", (code, signal) => {
+            markExited(code, signal);
+            if (!instance.outputClosed && !instance.drainTimer) {
+                instance.drainTimer = setTimeout(() => {
+                    markOutputClosed("drain-timeout");
+                }, this.drainDeadlineMs);
+                instance.drainTimer.unref?.();
+            }
+        });
+        child.on("close", (code, signal) => {
+            markExited(code, signal);
+            markOutputClosed("natural");
+        });
+        child.on("error", (err) => {
+            instance.cleanup();
+            observer.fault?.(err);
+            markExited(null, null);
+            markOutputClosed("natural");
+        });
+        this.instances.set(handleId, instance);
+        return this.createHandleObject(instance);
+    }
+    /**
+     * 构造对齐驱动操作的 ProcessHandle 对象。
+     */
+    createHandleObject(instance) {
+        return {
+            id: instance.id,
+            pid: instance.pid,
+            write: (data) => this.write(instance, data),
+            sendInputEOF: () => this.inputEOF(instance),
+            interruptForeground: () => this.interruptForeground(instance),
+            resize: (cols, rows) => this.resize(instance, cols, rows),
+            terminate: (graceMs) => this.terminate(instance, graceMs),
+        };
+    }
+    /**
+     * 向受管进程输入流写入字节数据，支持背压与管道提早关闭错误捕获。
+     * 终态自清理（selfRelease）或 dispose 先行移除实例时，进程已退出且输入管道必然关闭，
+     * 按已关闭语义抛出 INPUT_CLOSED 而非笼统异常。
+     */
+    async write(handle, data) {
+        const instance = this.instances.get(handle.id);
+        if (!instance) {
+            throw new ProcessError(INPUT_CLOSED, "Process stdin is closed or destroyed");
+        }
+        if (instance.mode === "pty" && instance.ptyProcess) {
+            const text = new TextDecoder().decode(data);
+            instance.ptyProcess.write(text);
+            return;
+        }
+        const stdin = instance.child.stdin;
+        if (!stdin || stdin.destroyed || !stdin.writable) {
+            throw new ProcessError(INPUT_CLOSED, "Process stdin is closed or destroyed");
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => {
+                stdin.removeListener("error", onError);
+                stdin.removeListener("drain", onDrain);
+            };
+            const onError = (err) => {
+                if (!settled) {
+                    settled = true;
+                    cleanup();
+                    reject(new ProcessError(INPUT_CLOSED, `Failed to write to stdin: ${err.message}`));
+                }
+            };
+            const onDrain = () => {
+                if (!settled) {
+                    settled = true;
+                    cleanup();
+                    resolve();
+                }
+            };
+            stdin.once("error", onError);
+            const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+            const canContinue = stdin.write(buffer, (err) => {
+                if (err) {
+                    onError(err);
+                }
+            });
+            if (canContinue) {
+                if (!settled) {
+                    settled = true;
+                    cleanup();
+                    resolve();
+                }
+            }
+            else {
+                stdin.once("drain", onDrain);
+            }
+        });
+    }
+    /**
+     * 结束输入流写入，发送 EOF。
+     */
+    async inputEOF(handle) {
+        const instance = this.resolveInstance(handle);
+        if (instance.mode === "pty") {
+            // PTY 模式下发送 EOF 控制符 Ctrl+D (\x04)
+            if (instance.ptyProcess) {
+                instance.ptyProcess.write("\x04");
+            }
+            return;
+        }
+        const stdin = instance.child.stdin;
+        if (!stdin || stdin.destroyed || !stdin.writable) {
+            return;
+        }
+        return new Promise((resolve) => {
+            stdin.end(() => {
+                resolve();
+            });
+        });
+    }
+    /**
+     * 中断前台作业组。
+     */
+    async interruptForeground(handle) {
+        const instance = this.resolveInstance(handle);
+        const pid = instance.pid;
+        if (!pid || instance.exited) {
+            return;
+        }
+        if (instance.mode === "pty" && instance.ptyProcess) {
+            // PTY 模式发送 Ctrl+C (\x03)
+            instance.ptyProcess.write("\x03");
+            return;
+        }
+        if (process.platform === "win32") {
+            throw new ProcessError(UNSUPPORTED_CAPABILITY, "interruptForeground is not supported on Windows in pipe mode");
+        }
+        else {
+            try {
+                process.kill(-pid, "SIGINT");
+            }
+            catch {
+                try {
+                    process.kill(pid, "SIGINT");
+                }
+                catch {
+                    // 忽略已退出状态
+                }
+            }
+        }
+    }
+    /**
+     * 动态调整终端尺寸，仅 PTY 模式生效。
+     */
+    async resize(handle, cols, rows) {
+        const instance = this.resolveInstance(handle);
+        if (instance.mode !== "pty" || !instance.ptyProcess) {
+            throw new ProcessError(UNSUPPORTED_CAPABILITY, "Terminal resize is unsupported in pipe mode");
+        }
+        instance.ptyProcess.resize(cols, rows);
+    }
+    /**
+     * 优雅终止进程，超时未退出则发送 SIGKILL 强杀兜底。
+     * 终态自清理（selfRelease）或 dispose 先行移除实例时视为已终止，直接无害返回。
+     */
+    async terminate(handle, graceMs) {
+        const instance = this.instances.get(handle.id);
+        if (!instance) {
+            return;
+        }
+        const pid = instance.pid;
+        if (!pid || instance.exited) {
+            return;
+        }
+        await killProcessGroup(pid, "SIGTERM", this.spawnFn);
+        if (graceMs <= 0) {
+            if (!instance.exited) {
+                await killProcessGroup(pid, "SIGKILL", this.spawnFn);
+            }
+            return;
+        }
+        if (instance.exited) {
+            return;
+        }
+        await new Promise((resolve) => {
+            let timer;
+            let settled = false;
+            let exitFinish;
+            const finish = () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                // 完成后自注销本次注册的 exit 监听器，避免同一实例反复 terminate 时累积监听器
+                if (exitFinish) {
+                    const idx = instance.exitListeners.indexOf(exitFinish);
+                    if (idx >= 0) {
+                        instance.exitListeners.splice(idx, 1);
+                    }
+                }
+                if (timer)
+                    clearTimeout(timer);
+                resolve();
+            };
+            exitFinish = finish;
+            instance.onExit(finish);
+            timer = setTimeout(async () => {
+                if (!instance.exited) {
+                    try {
+                        await killProcessGroup(pid, "SIGKILL", this.spawnFn);
+                    }
+                    catch {
+                        // 忽略终止失败异常
+                    }
+                }
+                finish();
+            }, graceMs);
+            timer.unref?.();
+        });
+    }
+    /**
+     * 销毁进程句柄并清理相关资源。
+     * 对仍在运行的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
+     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出实例直接清理。
+     * 终态自清理（selfRelease）与 dispose 可能并发到达，二者均按实例身份判断，
+     * 后到方对已删除条目为无害空操作。
+     */
+    async dispose(handle) {
+        const instance = this.instances.get(handle.id);
+        if (instance) {
+            if (!instance.exited) {
+                try {
+                    await this.terminate(handle, 0);
+                }
+                catch {
+                    // 兜底终止失败不阻断句柄清理，退出事件仍会经监听链路上报
+                }
+            }
+            instance.cleanup();
+            if (this.instances.get(handle.id) === instance) {
+                this.instances.delete(handle.id);
+            }
+        }
+    }
+    /**
+     * 解析查找内部受管进程实例。
+     */
+    resolveInstance(handle) {
+        const instance = this.instances.get(handle.id);
+        if (!instance) {
+            throw new Error(`Process instance not found for handle id: ${handle.id}`);
+        }
+        return instance;
+    }
+}
+/**
+ * 兼容原有命名导出。
+ */
+export { NodeProcessDriver as ProcessDriverImpl };

package/dist/process/process-executor.d.ts

@@ -0,0 +1,47 @@
+import type { spawn } from "node:child_process";
+import { type CallOptions, type ControlGrant, type OperationReceipt, type ProcessAcquireInput, type ProcessControlInput, type ProcessExecOptions, type ProcessInfo, type ProcessListInput, type ProcessListResult, type ProcessReadInput, type ProcessResult, type ProcessRunInput, type ProcessRunResult, type ProcessStartInput, type ProcessStartResult, type ProcessStopInput, type ProcessWriteInput, type ReadResult } from "@actiondock/sdk";
+import type { ProcessDriver } from "./driver.js";
+import { killProcessGroup } from "./process-driver.js";
+import type { ProcessExecutor } from "../runtime/process.js";
+export { killProcessGroup };
+/**
+ * 基于 NodeProcessDriver 实现的兼容命令执行器。
+ * 核心 OS 进程派生与生命周期管理统一由 NodeProcessDriver 承担，不再重复派生与调度。
+ */
+export declare class NodeProcessExecutor implements ProcessExecutor {
+    private readonly driver;
+    private readonly gracePeriodMs;
+    constructor(options?: number | {
+        gracePeriodMs?: number;
+        spawnFn?: typeof spawn;
+        driver?: ProcessDriver;
+    });
+    /**
+     * 执行外部系统命令，完整支持标准输入管道、超时控制、取消信号、输出容量截断及错误拦截。
+     *
+     * @param command 执行命令
+     * @param args 参数列表
+     * @param options 执行选项
+     * @param internal 内部专用参数：envAlreadyResolved 为 true 时 options.env 视为已完整解析
+     */
+    exec(command: string, args?: string[], options?: ProcessExecOptions, internal?: {
+        envAlreadyResolved?: boolean;
+    }): Promise<ProcessResult>;
+    spawn(command: string, args?: string[], options?: ProcessExecOptions): Promise<ProcessResult>;
+    run(input: ProcessRunInput, call?: CallOptions): Promise<ProcessRunResult>;
+    start(_input: ProcessStartInput, _call?: CallOptions): Promise<ProcessStartResult>;
+    inspect(_id: string, _call?: CallOptions): Promise<ProcessInfo>;
+    list(_input: ProcessListInput, _call?: CallOptions): Promise<ProcessListResult>;
+    acquire(_id: string, _input: ProcessAcquireInput, _call?: CallOptions): Promise<ControlGrant>;
+    renew(_id: string, _token: string, _ttlMs: number, _call?: CallOptions): Promise<ControlGrant>;
+    release(_id: string, _token: string, _call?: CallOptions): Promise<void>;
+    write(_id: string, _input: ProcessWriteInput, _call?: CallOptions): Promise<OperationReceipt>;
+    operation(_id: string, _requestId: string, _call?: CallOptions): Promise<OperationReceipt>;
+    read(_id: string, _input: ProcessReadInput, _call?: CallOptions): Promise<ReadResult>;
+    control(_id: string, _input: ProcessControlInput, _call?: CallOptions): Promise<OperationReceipt>;
+    stop(_id: string, _input: ProcessStopInput, _call?: CallOptions): Promise<ProcessInfo>;
+}
+/**
+ * 兼容原有类名导出。
+ */
+export { NodeProcessExecutor as ExecaProcessExecutor };