@actiondock/core 2.20.0 → 2.21.0

package/dist/process/command-executor.js

@@ -0,0 +1,326 @@
+import { INVALID_ARGUMENT, INPUT_CLOSED, PROCESS_CANCELLED, PROCESS_SPAWN_ERROR, PROCESS_TIMEOUT, ProcessError, } from "../errors.js";
+import { NodeProcessDriver } from "./process-driver.js";
+/**
+ * 独立深拷贝字节切片，脱离原始底层 ArrayBuffer 并杜绝驱动缓冲区复用污染。
+ */
+function cloneSlice(source, length) {
+    const cloned = new Uint8Array(length);
+    cloned.set(source.subarray(0, length));
+    return cloned;
+}
+/**
+ * 辅助将多个字节切片合并并解码为 UTF-8 文本。
+ */
+function decodeChunks(chunks, totalBytes) {
+    if (totalBytes === 0) {
+        return "";
+    }
+    const merged = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return new TextDecoder("utf-8").decode(merged);
+}
+/**
+ * 单流有界输出缓冲。
+ *
+ * 契约：
+ * - 超出上限的切片截断保留并置 truncated，之后的数据仅标记不再累积；
+ * - 捕获字节经独立深拷贝隔离，脱离驱动底层缓冲区以防复用污染；
+ * - decode 一次性合并全部切片并按 UTF-8 解码。
+ */
+function makeStreamBuffer(maxBytes) {
+    const chunks = [];
+    let totalBytes = 0;
+    let truncated = false;
+    return {
+        push(data) {
+            const remaining = maxBytes - totalBytes;
+            if (remaining > 0) {
+                if (data.byteLength <= remaining) {
+                    chunks.push(cloneSlice(data, data.byteLength));
+                    totalBytes += data.byteLength;
+                }
+                else {
+                    chunks.push(cloneSlice(data, remaining));
+                    totalBytes += remaining;
+                    truncated = true;
+                }
+            }
+            else {
+                truncated = true;
+            }
+        },
+        decode() {
+            return decodeChunks(chunks, totalBytes);
+        },
+        get truncated() {
+            return truncated;
+        },
+    };
+}
+/**
+ * 面向工程工具的一次性命令适配执行器。
+ *
+ * 核心设计契约：
+ * - 复用底层 ProcessDriver 平台驱动，严格保持进程组隔离与进程树收敛能力；
+ * - 绝不启用系统 Shell，参数列表原样透传，杜绝命令注入与参数转义漏洞；
+ * - 默认每流上限 512KiB 字节有界捕获，超出上限继续排空或转发并置 truncated 标志；
+ * - 捕获字节独立深拷贝，脱离原始底层缓冲区以防内存滞留与复用篡改；
+ * - 仅当显式指定 onOutput 时流式转发，严格保证跨分块 UTF-8 字符解码完整性；
+ * - 规范化取消、超时与异常收敛：等待 driver.terminate 与 outputClosed 终态后抛出结构化 ProcessError。
+ */
+export async function executeCommand(executable, args, options) {
+    // 参数合法性前置校验
+    if (options?.maxOutputBytes !== undefined) {
+        if (!Number.isSafeInteger(options.maxOutputBytes) ||
+            options.maxOutputBytes < 0) {
+            throw new ProcessError(INVALID_ARGUMENT, "maxOutputBytes must be a non-negative finite number");
+        }
+    }
+    if (options?.timeoutMs !== undefined) {
+        if (!Number.isFinite(options.timeoutMs) ||
+            options.timeoutMs > 2_147_483_647 ||
+            options.timeoutMs < 0) {
+            throw new ProcessError(INVALID_ARGUMENT, "timeoutMs must be a non-negative finite number");
+        }
+    }
+    const driver = options?.driver ??
+        new NodeProcessDriver({ waitForOutputClose: true });
+    // 若信号在启动前已触发中止，直接以 PROCESS_CANCELLED 拒绝
+    if (options?.signal?.aborted) {
+        throw new ProcessError(PROCESS_CANCELLED, `Command execution was cancelled before spawn: ${executable}`, { cause: options.signal.reason, executable, args: [...args] });
+    }
+    // 组装环境变量：未传 env 时显式复制 process.env 中非 undefined 项，通过 inherit: 'none' 保留私有凭据与配置
+    const envSet = {};
+    if (options?.env) {
+        for (const [k, v] of Object.entries(options.env)) {
+            if (v !== undefined) {
+                envSet[k] = v;
+            }
+        }
+    }
+    else {
+        for (const [k, v] of Object.entries(process.env)) {
+            if (v !== undefined) {
+                envSet[k] = v;
+            }
+        }
+    }
+    const spec = {
+        executable,
+        args: [...args],
+        cwd: options?.cwd,
+        env: {
+            inherit: "none",
+            set: envSet,
+        },
+        io: {
+            mode: "pipe",
+        },
+    };
+    const maxBytes = options?.maxOutputBytes ?? 512 * 1024;
+    const stdoutBuffer = makeStreamBuffer(maxBytes);
+    const stderrBuffer = makeStreamBuffer(maxBytes);
+    const stdoutDecoder = options?.onOutput ? new TextDecoder("utf-8") : undefined;
+    const stderrDecoder = options?.onOutput ? new TextDecoder("utf-8") : undefined;
+    let abortReason = null;
+    let abortCause = null;
+    let resolveAbort;
+    const abortTriggeredPromise = new Promise((r) => {
+        resolveAbort = r;
+    });
+    const triggerAbort = (reason, cause) => {
+        if (abortReason)
+            return;
+        abortReason = reason;
+        abortCause = cause;
+        resolveAbort();
+    };
+    const dispatchOutput = (stream, text) => {
+        if (state.closed || abortReason !== null || !options?.onOutput)
+            return;
+        try {
+            options.onOutput(stream, text);
+        }
+        catch (err) {
+            triggerAbort("output-error", err);
+        }
+    };
+    const flushDecoders = () => {
+        if (stdoutDecoder) {
+            const rem = stdoutDecoder.decode();
+            if (rem.length > 0) {
+                dispatchOutput("stdout", rem);
+            }
+        }
+        if (stderrDecoder) {
+            const rem = stderrDecoder.decode();
+            if (rem.length > 0) {
+                dispatchOutput("stderr", rem);
+            }
+        }
+    };
+    const state = { exitResult: null, faultError: null, closed: false };
+    let resolveOutputClosed;
+    const outputClosedPromise = new Promise((r) => {
+        resolveOutputClosed = r;
+    });
+    // 在 spawn 之前创建 observer 与关联 promise，杜绝同步驱动或测试桩发出的生命周期事件丢失
+    const observer = {
+        output(stream, data) {
+            if (state.closed || abortReason !== null) {
+                return;
+            }
+            // pty 输出不属于一次性管道命令的捕获范围，保持与原实现一致地忽略
+            if (stream !== "stdout" && stream !== "stderr") {
+                return;
+            }
+            const buffer = stream === "stdout" ? stdoutBuffer : stderrBuffer;
+            const decoder = stream === "stdout" ? stdoutDecoder : stderrDecoder;
+            buffer.push(data);
+            if (decoder) {
+                const text = decoder.decode(data, { stream: true });
+                if (text.length > 0) {
+                    dispatchOutput(stream, text);
+                }
+            }
+        },
+        exited(result) {
+            state.exitResult = result;
+        },
+        outputClosed(reason = "natural") {
+            if (state.closed)
+                return;
+            if (reason === "natural") {
+                flushDecoders();
+                state.closed = true;
+                resolveOutputClosed();
+                return;
+            }
+            state.closed = true;
+            if (reason === "drain-timeout") {
+                triggerAbort("drain-timeout", new ProcessError(PROCESS_TIMEOUT, `Process output drain timed out before completion: ${executable}`, { executable, args: [...args] }));
+            }
+            else {
+                triggerAbort("host-lost", new ProcessError(PROCESS_SPAWN_ERROR, `Process host connection was lost: ${executable}`, { executable, args: [...args] }));
+            }
+            resolveOutputClosed();
+        },
+        fault(err) {
+            state.faultError = err;
+            triggerAbort("fault", err);
+        },
+    };
+    // 绑定外部取消信号与超时定时器
+    let timeoutTimer;
+    const onSignalAbort = () => {
+        triggerAbort("cancelled", options?.signal?.reason);
+    };
+    if (options?.signal) {
+        options.signal.addEventListener("abort", onSignalAbort, { once: true });
+        // 监听注册后再次检查，消除注册前后的时序竞态
+        if (options.signal.aborted) {
+            triggerAbort("cancelled", options.signal.reason);
+        }
+    }
+    if (options?.timeoutMs && options.timeoutMs > 0) {
+        timeoutTimer = setTimeout(() => {
+            triggerAbort("timeout");
+        }, options.timeoutMs);
+    }
+    let handle;
+    // 将当前中止原因与关联异常映射为规范的结构化 ProcessError
+    const buildAbortError = () => {
+        switch (abortReason) {
+            case "output-error":
+                return abortCause;
+            case "fault":
+                return new ProcessError(PROCESS_SPAWN_ERROR, `Process reported fault: ${state.faultError?.message ?? String(abortCause)}`, { cause: abortCause, executable });
+            case "drain-timeout":
+            case "host-lost":
+                if (abortCause instanceof Error) {
+                    return abortCause;
+                }
+                return abortReason === "drain-timeout"
+                    ? new ProcessError(PROCESS_TIMEOUT, `Process output drain timed out before completion: ${executable}`, { executable, args: [...args] })
+                    : new ProcessError(PROCESS_SPAWN_ERROR, `Process host connection was lost: ${executable}`, { executable, args: [...args] });
+            case "timeout":
+                return new ProcessError(PROCESS_TIMEOUT, `Command execution timed out after ${options?.timeoutMs}ms: ${executable}`, { timeoutMs: options?.timeoutMs, executable });
+            default:
+                return new ProcessError(PROCESS_CANCELLED, `Command execution was cancelled: ${executable}`, { cause: abortCause, executable });
+        }
+    };
+    // 统一的中止清理与错误抛出函数：真实等待驱动终止与输出闭合，绝不吞错，绝不假放行
+    const performAbortCleanupAndThrow = async (activeHandle) => {
+        if (activeHandle) {
+            await driver.terminate(activeHandle, abortReason === "output-error" ? 0 : 200);
+            await outputClosedPromise;
+        }
+        throw buildAbortError();
+    };
+    try {
+        try {
+            handle = await driver.spawn(spec, observer);
+        }
+        catch (err) {
+            const spawnErr = err instanceof ProcessError && err.code === PROCESS_SPAWN_ERROR
+                ? err
+                : new ProcessError(PROCESS_SPAWN_ERROR, `Failed to spawn command "${executable}": ${err?.message || String(err)}`, { cause: err, executable, args: [...args] });
+            throw spawnErr;
+        }
+        // 检查在派生过程（await driver.spawn）中是否发生了取消、超时或异常
+        if (abortReason) {
+            await performAbortCleanupAndThrow(handle);
+        }
+        // 派生成功后立即发送 EOF 关闭标准输入，防止子进程因等待输入而死锁挂起
+        if (driver.inputEOF && !state.closed) {
+            const eof = Promise.resolve().then(() => driver.inputEOF(handle)).then(() => ({ error: undefined, failed: false }), (error) => ({ error, failed: true }));
+            const result = await Promise.race([
+                eof,
+                abortTriggeredPromise.then(() => undefined),
+            ]);
+            if (result?.failed) {
+                const error = result.error;
+                const isClosedError = error?.code === INPUT_CLOSED || error?.code === "EPIPE" || error?.code === "ERR_STREAM_DESTROYED";
+                if (!isClosedError && !state.closed) {
+                    triggerAbort("output-error", result.error);
+                }
+            }
+        }
+        // 检查发送 EOF 期间是否已被触发中止
+        if (abortReason) {
+            await performAbortCleanupAndThrow(handle);
+        }
+        // 等待输出完全收敛或中途触发中止
+        await Promise.race([outputClosedPromise, abortTriggeredPromise]);
+        if (abortReason) {
+            await performAbortCleanupAndThrow(handle);
+        }
+        // 若底层 observer 上报严重故障，无论 exitResult 是否存在，均终结为 PROCESS_SPAWN_ERROR
+        if (state.faultError) {
+            throw new ProcessError(PROCESS_SPAWN_ERROR, `Process reported fault: ${state.faultError.message}`, { cause: state.faultError, executable });
+        }
+        return {
+            status: state.exitResult?.code ?? null,
+            signal: state.exitResult?.signal ?? null,
+            stdout: stdoutBuffer.decode(),
+            stderr: stderrBuffer.decode(),
+            truncated: stdoutBuffer.truncated || stderrBuffer.truncated,
+        };
+    }
+    finally {
+        if (timeoutTimer) {
+            clearTimeout(timeoutTimer);
+            timeoutTimer = undefined;
+        }
+        if (options?.signal) {
+            options.signal.removeEventListener("abort", onSignalAbort);
+        }
+        if (handle && driver.dispose) {
+            await driver.dispose(handle);
+        }
+    }
+}

package/dist/process/index.d.ts

@@ -10,4 +10,5 @@ export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";
 export * from "./process-driver.js";
+export * from "./command-executor.js";
 export * from "./converters.js";

package/dist/process/index.js

@@ -10,4 +10,5 @@ export * from "./input-dispatcher.js";
 export * from "./process-manager.js";
 export * from "./context-process.js";
 export * from "./process-driver.js";
+export * from "./command-executor.js";
 export * from "./converters.js";

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

@@ -3,6 +3,17 @@ import type { Capabilities, LaunchSpec } from "@actiondock/sdk";
 import { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv, type ProcessDriver, type ProcessDriverCallbacks, type ProcessDriverHandle, type ProcessHandle, type ProcessObserver } from "./driver.js";
 export { DEFAULT_ENV_ALLOWLIST, resolveProcessEnv };
 export type { ProcessDriver, ProcessObserver, ProcessHandle, ProcessDriverCallbacks, ProcessDriverHandle };
+/**
+ * 跨平台探测进程组是否在操作系统中仍然存活。
+ *
+ * - 在 POSIX 环境下驱动创建了独立进程组，仅向负数进程标识 (-pid) 发送探测信号 0；
+ *   若返回 EPERM 视为仍存活；若返回 ESRCH 则表示进程组已彻底消亡；其他错误不静默当作消亡；
+ *   绝不对正 pid 探测，杜绝命中操作系统已重用 PID 的其他进程。
+ * - 在 Windows 环境下通过 process.kill(pid, 0) 探测父进程存活性。
+ *
+ * @param pid 目标进程标识
+ */
+export declare function isProcessGroupAlive(pid: number): boolean;
 /**
  * 跨平台终止进程组，确保不会遗留孤儿进程。
  *
@@ -22,6 +33,8 @@ export interface NodeProcessDriverOptions {
     drainDeadlineMs?: number;
     /** 进程派生函数，默认为 childProcess.spawn */
     spawnFn?: typeof spawn;
+    /** 是否在自然 exit 后等待输出流真实 close（默认 false） */
+    waitForOutputClose?: boolean;
 }
 /**
  * 基于 Node.js 标准子进程实现的平台驱动。
@@ -37,6 +50,7 @@ export interface NodeProcessDriverOptions {
 export declare class NodeProcessDriver implements ProcessDriver {
     private readonly drainDeadlineMs;
     readonly spawnFn: typeof spawn;
+    private readonly waitForOutputClose;
     private readonly instances;
     constructor(options?: NodeProcessDriverOptions);
     /**
@@ -86,16 +100,15 @@ export declare class NodeProcessDriver implements ProcessDriver {
      */
     resize(handle: ProcessHandle, cols: number, rows: number): Promise<void>;
     /**
-     * 优雅终止进程，超时未退出则发送 SIGKILL 强杀兜底。
-     * 终态自清理（selfRelease）或 dispose 先行移除实例时视为已终止，直接无害返回。
+     * 优雅终止进程整棵进程树，超时未退出则发送 SIGKILL 强杀兜底。
+     * 修复父进程先退出导致的短路，确保整组存活成员（包括忽略 SIGTERM 的孙进程及未闭合输出的活实例）被彻底终止，
+     * 并等待父进程与输出收敛。
      */
     terminate(handle: ProcessHandle, graceMs: number): Promise<void>;
     /**
      * 销毁进程句柄并清理相关资源。
-     * 对仍在运行的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
-     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出实例直接清理。
-     * 终态自清理（selfRelease）与 dispose 可能并发到达，二者均按实例身份判断，
-     * 后到方对已删除条目为无害空操作。
+     * 对仍在运行或进程树存活或输出未闭合的实例先执行 terminate(0) 兜底（SIGTERM 后立即 SIGKILL），
+     * 绝不从受管表移除仍存活的子进程而遗留孤儿；已退出且输出闭合实例直接清理。
      */
     dispose(handle: ProcessHandle): Promise<void>;
     /**