@veryfront/ext-content-mdx 0.1.1186 → 0.1.1189

package/esm/src/platform/compat/process/command.d.ts

@@ -3,6 +3,8 @@ export interface CommandResult {
     code: number;
     stdout?: string;
     stderr?: string;
+    /** True when captured output exceeded the configured byte limit. */
+    outputTruncated?: boolean;
 }
 export interface CommandOptions {
     args?: string[];
@@ -16,9 +18,30 @@ export interface CommandOptions {
     inherit?: boolean;
     /** Use shell to run the command (needed for .cmd files on Windows) */
     shell?: boolean;
-    /** Kill the command if it exceeds this duration (milliseconds) */
+    /**
+     * Kill the command after this duration in milliseconds. Positive values are
+     * floored to whole milliseconds and clamped to the portable timer maximum;
+     * `undefined`, non-positive values, and NaN disable the timeout.
+     */
     timeoutMs?: number;
+    /** Terminate the command when the caller cancels. */
+    signal?: AbortSignal;
+    /**
+     * Best-effort process-tree cleanup after the managed command settles.
+     * Disabled by default so generic callers retain normal daemon/background
+     * process behavior. Sandboxed or otherwise lifecycle-owning callers can
+     * enable it to prevent ordinary descendants from outliving the command.
+     */
+    terminateProcessTreeOnExit?: boolean;
+    /**
+     * Maximum combined stdout and stderr bytes retained when `capture` is true.
+     *
+     * @default 16777216
+     */
+    maxOutputBytes?: number;
 }
+/** @internal Exported so Windows tree-termination arguments can be tested on every host. */
+export declare function buildWindowsTaskkillArgs(pid: number, force: boolean): string[];
 /**
  * Run a command and return the result.
  * Works across Deno, Node.js, and Bun.

package/esm/src/platform/compat/process/command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/compat/process/command.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyFD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA+LxB"}
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/compat/process/command.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAuED,4FAA4F;AAC5F,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAK9E;AAoTD;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,CAAC,CAmVxB"}

package/esm/src/platform/compat/process/command.js

@@ -1,78 +1,299 @@
 import * as dntShim from "../../../../_dnt.shims.js";
 import { dynamicImport } from "../dynamic-import.js";
+import { addAbortSignalListenerOnce, isAbortSignalAborted, isAbortSignalWithoutHooks, removeAbortSignalListener, } from "../abort-signal.js";
 import { getDenoRuntime, isBun as IS_BUN, isDeno as IS_DENO } from "../runtime.js";
 import { isWindowsPlatform, runtimeProcess } from "./runtime-process.js";
 const COMMAND_TIMEOUT_EXIT_CODE = 124;
+const COMMAND_OUTPUT_LIMIT_EXIT_CODE = 125;
+const COMMAND_ABORT_EXIT_CODE = 130;
 const FORCE_KILL_GRACE_MS = 250;
-function createShellCommand(cmd, args) {
-    if (isWindowsPlatform()) {
-        return { cmd: "cmd.exe", args: ["/d", "/s", "/c", cmd, ...args] };
-    }
-    if (args.length === 0) {
-        return { cmd: "sh", args: ["-c", cmd] };
-    }
-    return { cmd: "sh", args: ["-c", 'exec "$@"', "sh", cmd, ...args] };
-}
-function createTimeoutResult(timeoutMs, stdout, stderr) {
+const DEFAULT_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+const MAX_COMMAND_TIMEOUT_MS = 2_147_483_647;
+const apply = Reflect.apply;
+const uint8ArraySlice = Uint8Array.prototype.slice;
+function createTerminationResult(reason, detail, stdout, stderr, outputTruncated = reason === "output-limit") {
+    const message = reason === "timeout"
+        ? `Command timed out after ${detail}ms`
+        : reason === "output-limit"
+            ? `Command output exceeded ${detail} bytes`
+            : "Command aborted";
     return {
         success: false,
-        code: COMMAND_TIMEOUT_EXIT_CODE,
+        code: reason === "timeout"
+            ? COMMAND_TIMEOUT_EXIT_CODE
+            : reason === "output-limit"
+                ? COMMAND_OUTPUT_LIMIT_EXIT_CODE
+                : COMMAND_ABORT_EXIT_CODE,
         stdout,
-        stderr: `${stderr ?? ""}\nCommand timed out after ${timeoutMs}ms`.trim(),
+        stderr: `${stderr ?? ""}\n${message}`.trim(),
+        outputTruncated: outputTruncated || undefined,
     };
 }
-function createProcessTimeout(timeoutMs, terminate, forceTerminate) {
-    let timedOut = false;
+function validateAbortSignal(signal) {
+    if (signal === undefined)
+        return;
+    if (!isAbortSignalWithoutHooks(signal)) {
+        throw new TypeError("signal must be an AbortSignal");
+    }
+}
+function resolveCommandTimeoutMs(timeoutMs) {
+    if (typeof timeoutMs !== "number" || !(timeoutMs > 0))
+        return undefined;
+    return Math.min(Math.floor(timeoutMs), MAX_COMMAND_TIMEOUT_MS);
+}
+/** @internal Exported so Windows tree-termination arguments can be tested on every host. */
+export function buildWindowsTaskkillArgs(pid, force) {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        throw new RangeError("Windows taskkill pid must be a positive safe integer");
+    }
+    return ["/PID", String(pid), "/T", ...(force ? ["/F"] : [])];
+}
+function tryDirectSignal(signalDirect, signal) {
+    try {
+        signalDirect(signal);
+    }
+    catch {
+        // The target may have exited before taskkill failure became observable.
+    }
+}
+function tryForceSettledProcessTree(signalTree) {
+    try {
+        signalTree("SIGKILL");
+    }
+    catch {
+        // A settled command with no remaining descendants has no process group or
+        // live direct handle. Cleanup is intentionally idempotent in that case.
+    }
+}
+function signalWindowsTreeWithDeno(deno, pid, force, signalDirect) {
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (!Number.isSafeInteger(pid) || (pid ?? 0) <= 0) {
+        tryDirectSignal(signalDirect, signal);
+        return;
+    }
+    try {
+        const taskkill = new deno.Command("taskkill", {
+            args: buildWindowsTaskkillArgs(pid, force),
+            stdin: "null",
+            stdout: "null",
+            stderr: "null",
+        }).spawn();
+        void taskkill.status.then((status) => {
+            if (!status.success)
+                tryDirectSignal(signalDirect, signal);
+        }).catch(() => tryDirectSignal(signalDirect, signal));
+    }
+    catch {
+        tryDirectSignal(signalDirect, signal);
+    }
+}
+function signalWindowsTreeWithBun(bun, pid, force, signalDirect) {
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (!Number.isSafeInteger(pid) || (pid ?? 0) <= 0) {
+        tryDirectSignal(signalDirect, signal);
+        return;
+    }
+    try {
+        const taskkill = bun.spawn({
+            cmd: ["taskkill", ...buildWindowsTaskkillArgs(pid, force)],
+            stdout: "ignore",
+            stderr: "ignore",
+        });
+        taskkill.unref?.();
+        void taskkill.exited.then((code) => {
+            if (code !== 0)
+                tryDirectSignal(signalDirect, signal);
+        }).catch(() => tryDirectSignal(signalDirect, signal));
+    }
+    catch {
+        tryDirectSignal(signalDirect, signal);
+    }
+}
+function signalWindowsTreeWithNode(spawn, pid, force, signalDirect) {
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (!Number.isSafeInteger(pid) || (pid ?? 0) <= 0) {
+        tryDirectSignal(signalDirect, signal);
+        return;
+    }
+    try {
+        const taskkill = spawn("taskkill", buildWindowsTaskkillArgs(pid, force), {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        taskkill.once("error", () => tryDirectSignal(signalDirect, signal));
+        taskkill.once("close", (code) => {
+            if (code !== 0)
+                tryDirectSignal(signalDirect, signal);
+        });
+    }
+    catch {
+        tryDirectSignal(signalDirect, signal);
+    }
+}
+function signalProcessTree(pid, signal, detachedProcessGroup, signalGroup, signalDirect) {
+    if (detachedProcessGroup && Number.isSafeInteger(pid) && (pid ?? 0) > 0) {
+        try {
+            signalGroup(-pid, signal);
+            return;
+        }
+        catch (_) {
+            // The child may have exited before its process group became observable.
+            // Fall through to the direct handle so cancellation remains best effort.
+        }
+    }
+    signalDirect(signal);
+}
+function createProcessGuard(timeoutMs, signal, terminate, forceTerminate, releaseAfterForce) {
+    let terminationReason = null;
     let timeoutId;
     let forceKillId;
+    let forceTerminationCompleted = false;
+    const abortListener = () => stop("abort");
     if (timeoutMs && timeoutMs > 0) {
         timeoutId = dntShim.setTimeout(() => {
-            timedOut = true;
-            try {
-                terminate();
-            }
-            catch (_) {
-                /* expected: best-effort terminate may fail if process already exited */
-            }
-            forceKillId = dntShim.setTimeout(() => {
-                try {
-                    forceTerminate();
-                }
-                catch (_) {
-                    /* expected: best-effort force terminate may fail if process already exited */
-                }
-            }, FORCE_KILL_GRACE_MS);
+            stop("timeout");
         }, timeoutMs);
     }
+    if (signal) {
+        addAbortSignalListenerOnce(signal, abortListener);
+        if (isAbortSignalAborted(signal))
+            stop("abort");
+    }
     return {
-        hasTimedOut: () => timedOut,
+        stop,
+        reason: () => terminationReason,
         clear: () => {
             if (timeoutId)
                 clearTimeout(timeoutId);
-            if (forceKillId)
-                clearTimeout(forceKillId);
+            if (signal)
+                removeAbortSignalListener(signal, abortListener);
+            if (terminationReason === null) {
+                if (forceKillId)
+                    clearTimeout(forceKillId);
+                return;
+            }
+            // The directly managed process may settle after SIGTERM while a child in
+            // its process group remains alive. Do not cancel escalation on that
+            // abnormal settlement; force it immediately before releasing lifecycle
+            // ownership.
+            forceTerminateOnce();
         },
     };
+    function stop(reason) {
+        if (terminationReason !== null)
+            return;
+        terminationReason = reason;
+        try {
+            terminate();
+        }
+        catch (_) {
+            /* expected: best-effort terminate may fail if process already exited */
+        }
+        forceKillId = dntShim.setTimeout(forceTerminateOnce, FORCE_KILL_GRACE_MS);
+    }
+    function forceTerminateOnce() {
+        if (forceTerminationCompleted)
+            return;
+        forceTerminationCompleted = true;
+        if (forceKillId) {
+            clearTimeout(forceKillId);
+            forceKillId = undefined;
+        }
+        try {
+            forceTerminate();
+        }
+        catch (_) {
+            /* expected: best-effort force terminate may fail if process already exited */
+        }
+        finally {
+            releaseAfterForce();
+        }
+    }
+}
+function createCaptureBudget(maxOutputBytes, onExceeded) {
+    return {
+        remaining: maxOutputBytes,
+        exceeded: false,
+        onExceeded,
+    };
 }
-async function readStreamToString(stream) {
-    const reader = stream.getReader();
-    const chunks = [];
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        if (value)
-            chunks.push(value);
-    }
-    const total = chunks.reduce((acc, c) => acc + c.length, 0);
+function captureChunk(chunks, chunk, budget) {
+    const available = budget.remaining;
+    if (available > 0) {
+        // Invoke the typed-array intrinsic directly: Buffer#slice() returns a view
+        // and can retain a much larger pooled backing allocation.
+        const retained = apply(uint8ArraySlice, chunk, [
+            0,
+            Math.min(chunk.byteLength, available),
+        ]);
+        chunks.push(retained);
+        budget.remaining -= retained.byteLength;
+    }
+    if (chunk.byteLength > available && !budget.exceeded) {
+        budget.exceeded = true;
+        budget.onExceeded();
+    }
+}
+function decodeChunks(chunks) {
+    const total = chunks.reduce((acc, chunk) => acc + chunk.byteLength, 0);
     const merged = new Uint8Array(total);
     let offset = 0;
     for (const chunk of chunks) {
         merged.set(chunk, offset);
-        offset += chunk.length;
+        offset += chunk.byteLength;
     }
     return new TextDecoder().decode(merged);
 }
+function captureStreamToString(stream, budget) {
+    const reader = stream.getReader();
+    const chunks = [];
+    let cancelled = false;
+    return {
+        result: (async () => {
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value)
+                        captureChunk(chunks, value, budget);
+                }
+            }
+            catch (error) {
+                if (!cancelled)
+                    throw error;
+            }
+            finally {
+                reader.releaseLock();
+            }
+            return decodeChunks(chunks);
+        })(),
+        cancel: (reason) => {
+            if (cancelled)
+                return;
+            cancelled = true;
+            try {
+                const cancellation = reader.cancel(reason);
+                void cancellation.catch(() => { });
+            }
+            catch {
+                // The stream may already have closed between termination and release.
+            }
+        },
+    };
+}
+function resolveShellCommand(cmd, args) {
+    if (isWindowsPlatform()) {
+        return { cmd: "cmd.exe", args: ["/d", "/s", "/c", cmd, ...args] };
+    }
+    if (args.length === 0) {
+        return { cmd: "sh", args: ["-c", cmd] };
+    }
+    return {
+        cmd: "sh",
+        args: ["-c", 'exec "$@"', "sh", cmd, ...args],
+    };
+}
 /**
  * Run a command and return the result.
  * Works across Deno, Node.js, and Bun.
@@ -84,32 +305,67 @@ async function readStreamToString(stream) {
  * @param options.shell - Use shell to run command (needed for .cmd on Windows)
  */
 export async function runCommand(cmd, options = {}) {
-    const { args = [], cwd: cmdCwd, env: cmdEnv, clearEnv = false, capture = false, inherit = false, shell = false, timeoutMs, } = options;
-    const effectiveTimeoutMs = timeoutMs && timeoutMs > 0 ? Math.floor(timeoutMs) : undefined;
+    const { args = [], cwd: cmdCwd, env: cmdEnv, clearEnv = false, capture = false, inherit = false, shell = false, timeoutMs, signal, terminateProcessTreeOnExit = false, maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES, } = options;
+    validateAbortSignal(signal);
+    if (typeof terminateProcessTreeOnExit !== "boolean") {
+        throw new TypeError("terminateProcessTreeOnExit must be a boolean");
+    }
+    const effectiveTimeoutMs = resolveCommandTimeoutMs(timeoutMs);
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes <= 0) {
+        throw new RangeError("maxOutputBytes must be a positive safe integer");
+    }
+    if (signal && isAbortSignalAborted(signal)) {
+        return createTerminationResult("abort", 0);
+    }
     // Determine stdio mode: inherit > capture > null
-    const stdioMode = inherit ? "inherit" : capture ? "piped" : "null";
+    const shouldCapture = capture && !inherit;
+    const stdioMode = inherit ? "inherit" : shouldCapture ? "piped" : "null";
+    const detachedProcessGroup = !isWindowsPlatform() &&
+        (effectiveTimeoutMs !== undefined ||
+            signal !== undefined ||
+            shouldCapture ||
+            terminateProcessTreeOnExit);
     const deno = IS_DENO ? getDenoRuntime() : undefined;
     if (deno) {
-        const denoCommand = shell ? createShellCommand(cmd, args) : { cmd, args };
+        const denoCommand = shell ? resolveShellCommand(cmd, args) : { cmd, args };
         const command = new deno.Command(denoCommand.cmd, {
-            args: denoCommand.args,
+            args: [...denoCommand.args],
             cwd: cmdCwd,
             env: cmdEnv,
             clearEnv,
             stdin: inherit ? "inherit" : "null",
             stdout: stdioMode,
             stderr: stdioMode,
+            detached: detachedProcessGroup,
         });
         const child = command.spawn();
-        const timeout = createProcessTimeout(effectiveTimeoutMs, () => child.kill("SIGTERM"), () => child.kill("SIGKILL"));
+        const windowsPlatform = isWindowsPlatform();
+        const directSignal = (terminationSignal) => child.kill(terminationSignal);
+        const signalChild = (terminationSignal) => windowsPlatform
+            ? signalWindowsTreeWithDeno(deno, child.pid, terminationSignal === "SIGKILL", directSignal)
+            : signalProcessTree(child.pid, terminationSignal, detachedProcessGroup, (processGroupId, groupSignal) => deno.kill(processGroupId, groupSignal), directSignal);
+        const captures = {};
+        const guard = createProcessGuard(effectiveTimeoutMs, signal, () => signalChild("SIGTERM"), () => signalChild("SIGKILL"), () => {
+            const reason = new Error("Command capture closed after forced termination");
+            captures.stdout?.cancel(reason);
+            captures.stderr?.cancel(reason);
+        });
+        const captureBudget = createCaptureBudget(maxOutputBytes, () => guard.stop("output-limit"));
+        captures.stdout = shouldCapture && child.stdout
+            ? captureStreamToString(child.stdout, captureBudget)
+            : undefined;
+        captures.stderr = shouldCapture && child.stderr
+            ? captureStreamToString(child.stderr, captureBudget)
+            : undefined;
         try {
             const [status, stdout, stderr] = await Promise.all([
                 child.status,
-                capture && child.stdout ? readStreamToString(child.stdout) : Promise.resolve(undefined),
-                capture && child.stderr ? readStreamToString(child.stderr) : Promise.resolve(undefined),
+                captures.stdout?.result ?? Promise.resolve(undefined),
+                captures.stderr?.result ?? Promise.resolve(undefined),
             ]);
-            if (timeout.hasTimedOut()) {
-                return createTimeoutResult(effectiveTimeoutMs ?? 0, stdout, stderr);
+            const reason = guard.reason();
+            if (reason) {
+                return createTerminationResult(reason, reason === "timeout" ? effectiveTimeoutMs ?? 0 : maxOutputBytes, stdout, stderr, captureBudget.exceeded);
             }
             return {
                 success: status.success,
@@ -119,41 +375,73 @@ export async function runCommand(cmd, options = {}) {
             };
         }
         finally {
-            timeout.clear();
+            if (terminateProcessTreeOnExit && guard.reason() === null) {
+                tryForceSettledProcessTree(signalChild);
+            }
+            guard.clear();
         }
     }
     if (IS_BUN) {
         const bunGlobal = dntShim.dntGlobalThis;
-        const bunStdio = inherit ? "inherit" : capture ? "pipe" : "ignore";
-        const shellCommand = shell ? createShellCommand(cmd, args) : undefined;
+        const bunStdio = inherit ? "inherit" : shouldCapture ? "pipe" : "ignore";
+        const shellCommand = shell ? resolveShellCommand(cmd, args) : null;
         const bunCmd = shellCommand ? [shellCommand.cmd, ...shellCommand.args] : [cmd, ...args];
         const proc = bunGlobal.Bun.spawn({
             cmd: bunCmd,
             cwd: cmdCwd,
+            detached: detachedProcessGroup,
             env: clearEnv ? cmdEnv ?? {} : cmdEnv,
             stdout: bunStdio,
             stderr: bunStdio,
         });
-        const timeout = createProcessTimeout(effectiveTimeoutMs, () => proc.kill?.("SIGTERM"), () => proc.kill?.("SIGKILL"));
+        const windowsPlatform = isWindowsPlatform();
+        const directSignal = (terminationSignal) => proc.kill?.(terminationSignal);
+        const signalChild = (terminationSignal) => windowsPlatform
+            ? signalWindowsTreeWithBun(bunGlobal.Bun, proc.pid, terminationSignal === "SIGKILL", directSignal)
+            : signalProcessTree(proc.pid, terminationSignal, detachedProcessGroup, (processGroupId, groupSignal) => {
+                if (!runtimeProcess)
+                    throw new Error("Runtime process unavailable");
+                runtimeProcess.kill(processGroupId, groupSignal);
+            }, directSignal);
+        const captures = {};
+        const guard = createProcessGuard(effectiveTimeoutMs, signal, () => signalChild("SIGTERM"), () => signalChild("SIGKILL"), () => {
+            const reason = new Error("Command capture closed after forced termination");
+            captures.stdout?.cancel(reason);
+            captures.stderr?.cancel(reason);
+        });
+        const captureBudget = createCaptureBudget(maxOutputBytes, () => guard.stop("output-limit"));
+        captures.stdout = shouldCapture && proc.stdout
+            ? captureStreamToString(proc.stdout, captureBudget)
+            : undefined;
+        captures.stderr = shouldCapture && proc.stderr
+            ? captureStreamToString(proc.stderr, captureBudget)
+            : undefined;
         try {
             const [code, stdout, stderr] = await Promise.all([
                 proc.exited,
-                capture && proc.stdout ? readStreamToString(proc.stdout) : Promise.resolve(undefined),
-                capture && proc.stderr ? readStreamToString(proc.stderr) : Promise.resolve(undefined),
+                captures.stdout?.result ?? Promise.resolve(undefined),
+                captures.stderr?.result ?? Promise.resolve(undefined),
             ]);
-            if (timeout.hasTimedOut()) {
-                return createTimeoutResult(effectiveTimeoutMs ?? 0, stdout, stderr);
+            const reason = guard.reason();
+            if (reason) {
+                return createTerminationResult(reason, reason === "timeout" ? effectiveTimeoutMs ?? 0 : maxOutputBytes, stdout, stderr, captureBudget.exceeded);
             }
             return { success: code === 0, code, stdout, stderr };
         }
         finally {
-            timeout.clear();
+            if (terminateProcessTreeOnExit && guard.reason() === null) {
+                tryForceSettledProcessTree(signalChild);
+            }
+            guard.clear();
         }
     }
     if (!runtimeProcess)
         return { success: false, code: 1 };
     const process = runtimeProcess;
     const { spawn } = await dynamicImport("node:child_process");
+    if (signal && isAbortSignalAborted(signal)) {
+        return createTerminationResult("abort", 0);
+    }
     const nodeStdio = inherit
         ? ["inherit", "inherit", "inherit"]
         : capture
@@ -165,41 +453,68 @@ export async function runCommand(cmd, options = {}) {
             env: clearEnv ? cmdEnv ?? {} : cmdEnv ? { ...process.env, ...cmdEnv } : undefined,
             stdio: nodeStdio,
             shell,
+            detached: detachedProcessGroup,
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const windowsPlatform = isWindowsPlatform();
+        const directSignal = (terminationSignal) => child.kill(terminationSignal);
+        const signalChild = (terminationSignal) => windowsPlatform
+            ? signalWindowsTreeWithNode(spawn, child.pid, terminationSignal === "SIGKILL", directSignal)
+            : signalProcessTree(child.pid, terminationSignal, detachedProcessGroup, (processGroupId, groupSignal) => process.kill(processGroupId, groupSignal), directSignal);
+        const guard = createProcessGuard(effectiveTimeoutMs, signal, () => signalChild("SIGTERM"), () => signalChild("SIGKILL"), () => {
+            child.stdout?.destroy();
+            child.stderr?.destroy();
         });
-        let stdout = "";
-        let stderr = "";
-        const decoder = new TextDecoder();
-        const timeout = createProcessTimeout(effectiveTimeoutMs, () => child.kill("SIGTERM"), () => child.kill("SIGKILL"));
-        if (capture) {
+        const captureBudget = createCaptureBudget(maxOutputBytes, () => guard.stop("output-limit"));
+        let resultSettled = false;
+        const settleProcessOwnership = () => {
+            if (resultSettled)
+                return false;
+            resultSettled = true;
+            if (terminateProcessTreeOnExit && guard.reason() === null) {
+                tryForceSettledProcessTree(signalChild);
+            }
+            guard.clear();
+            return true;
+        };
+        if (shouldCapture) {
             child.stdout?.on("data", (data) => {
-                stdout += decoder.decode(data);
+                captureChunk(stdoutChunks, data, captureBudget);
             });
             child.stderr?.on("data", (data) => {
-                stderr += decoder.decode(data);
+                captureChunk(stderrChunks, data, captureBudget);
             });
         }
         child.on("close", (code) => {
-            timeout.clear();
-            if (timeout.hasTimedOut()) {
-                resolve(createTimeoutResult(effectiveTimeoutMs ?? 0, capture ? stdout : undefined, capture ? stderr : undefined));
+            if (!settleProcessOwnership())
+                return;
+            const stdout = shouldCapture ? decodeChunks(stdoutChunks) : undefined;
+            const stderr = shouldCapture ? decodeChunks(stderrChunks) : undefined;
+            const reason = guard.reason();
+            if (reason) {
+                resolve(createTerminationResult(reason, reason === "timeout" ? effectiveTimeoutMs ?? 0 : maxOutputBytes, stdout, stderr, captureBudget.exceeded));
                 return;
             }
             resolve({
                 success: code === 0,
                 code: code ?? 1,
-                stdout: capture ? stdout : undefined,
-                stderr: capture ? stderr : undefined,
+                stdout,
+                stderr,
             });
         });
         child.on("error", (spawnError) => {
-            timeout.clear();
+            if (!settleProcessOwnership())
+                return;
+            const stdout = shouldCapture ? decodeChunks(stdoutChunks) : undefined;
+            const stderr = shouldCapture ? decodeChunks(stderrChunks) : undefined;
             // Include the spawn error message so callers can distinguish ENOENT
             // ("command not found"), EACCES ("permission denied"), etc.
             resolve({
                 success: false,
                 code: 1,
-                stdout: capture ? stdout : undefined,
-                stderr: capture
+                stdout,
+                stderr: shouldCapture
                     ? (stderr
                         ? `${stderr}\nSpawn error: ${spawnError.message}`
                         : `Spawn error: ${spawnError.message}`)

package/esm/src/platform/compat/process/env.d.ts

@@ -1,3 +1,4 @@
+import type { ProjectEnvSnapshot } from "./project-env-contract.js";
 export type EnvOverlayStorage = {
     getStore: () => unknown;
     run?: <T>(store: unknown, fn: () => T) => T;
@@ -10,6 +11,16 @@ export declare function env(): Record<string, string>;
  * Use this for framework-owned runtime configuration that should not be shadowed by tenant env.
  */
 export declare function getHostEnv(key: string): string | undefined;
+/**
+ * Register the server-owned project environment snapshot bridge.
+ *
+ * Kept out of the public process barrel so project code cannot replace the
+ * callback through a supported package export. Re-registering a different
+ * function is rejected rather than silently widening an isolation boundary.
+ */
+export declare function registerTrustedProjectEnvSnapshot(getter: () => ProjectEnvSnapshot | undefined): void;
+/** Return the active server-owned project env snapshot, if registered. */
+export declare function getTrustedProjectEnvSnapshot(): ProjectEnvSnapshot | undefined;
 /** Read an environment variable from the active project scope. */
 export declare function getEnv(key: string): string | undefined;
 export interface EnvBooleanOptions {

package/esm/src/platform/compat/process/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/compat/process/env.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC,CAAC;AAoBF,oDAAoD;AACpD,wBAAgB,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoB5C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqB1D;AAqCD,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWtD;AAKD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAUD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AAOpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AAUpE,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,UAAQ,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAmBT;AAED,gBAAgB;AAChB,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAiBvD;AAED,6CAA6C;AAC7C,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiB3C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAS/D"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/compat/process/env.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAKpE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,OAAO,CAAC;IACxB,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtC,CAAC;AAoBF,oDAAoD;AACpD,wBAAgB,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoB5C;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAqB1D;AAID;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,MAAM,kBAAkB,GAAG,SAAS,GAC3C,IAAI,CAKN;AAED,0EAA0E;AAC1E,wBAAgB,4BAA4B,IAAI,kBAAkB,GAAG,SAAS,CAE7E;AAED,kEAAkE;AAClE,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAWtD;AAKD,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAUD,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AAOpE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAC9D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;AAapE,wBAAgB,aAAa,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,UAAQ,EAChB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAmBT;AAED,gBAAgB;AAChB,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAiBvD;AAED,6CAA6C;AAC7C,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiB3C;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAS/D"}