@fixy/adapter-utils 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { buildInheritedEnv, ensurePathInEnv, redactEnvForLogs, resolveCommand, runChildProcess, appendWithCap, MAX_CAPTURE_BYTES, } from './server-utils.js';
+export type { RunChildOpts, RunChildResult } from './server-utils.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { buildInheritedEnv, ensurePathInEnv, redactEnvForLogs, resolveCommand, runChildProcess, appendWithCap, MAX_CAPTURE_BYTES, } from './server-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,aAAa,EACb,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}

package/dist/server-utils.d.ts

@@ -0,0 +1,58 @@
+export declare const MAX_CAPTURE_BYTES: number;
+export interface RunChildOpts {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+    stdin?: string;
+    signal?: AbortSignal;
+    onLog?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+    onSpawn?: (pid: number) => void;
+    timeoutMs?: number;
+}
+export interface RunChildResult {
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Appends `chunk` to `prev`, keeping the combined string within `cap` bytes.
+ * When the cap is exceeded the oldest bytes are dropped (tail is preserved).
+ */
+export declare function appendWithCap(prev: string, chunk: string, cap?: number): string;
+/**
+ * Builds an env record that inherits from `process.env`, ensures critical
+ * keys (`HOME`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PATH`) are preserved
+ * untouched from the current process, strips Claude Code nesting-guard vars,
+ * and finally layers caller-supplied `overrides` on top.
+ */
+export declare function buildInheritedEnv(overrides?: Record<string, string>): Record<string, string>;
+/**
+ * Ensures the env record has a non-empty `PATH`.
+ * If it is already set, returns the record unchanged.
+ * Otherwise injects a sensible macOS/Linux default.
+ */
+export declare function ensurePathInEnv(env: Record<string, string>): Record<string, string>;
+/**
+ * Returns a shallow copy of `env` where any key matching `SENSITIVE_ENV_KEY`
+ * has its value replaced with `'***REDACTED***'`.
+ */
+export declare function redactEnvForLogs(env: Record<string, string>): Record<string, string>;
+/**
+ * Resolves the absolute path of `command` using `which` (or `where` on
+ * Windows). Throws if the command is not found.
+ */
+export declare function resolveCommand(command: string): Promise<string>;
+/**
+ * Spawns a child process and captures its output.
+ *
+ * - Inherits env via `ensurePathInEnv({ ...process.env, ...opts.env })` with
+ *   Claude nesting vars stripped.
+ * - Captures up to `MAX_CAPTURE_BYTES` of stdout/stderr each.
+ * - Streams data to `opts.onLog` in real time.
+ * - Supports optional `AbortSignal` and timeout.
+ */
+export declare function runChildProcess(opts: RunChildOpts): Promise<RunChildResult>;
+//# sourceMappingURL=server-utils.d.ts.map

package/dist/server-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-utils.d.ts","sourceRoot":"","sources":["../src/server-utils.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AAgBjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAoB,GAAG,MAAM,CAG1F;AAiBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmC5F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMpF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQrE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAgJ3E"}

package/dist/server-utils.js

@@ -0,0 +1,265 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024; // 4MB cap per stream
+const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+/** Claude Code nesting-guard env vars that prevent nested spawns from starting. */
+const CLAUDE_NESTING_VARS = [
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SESSION',
+    'CLAUDE_CODE_PARENT_SESSION',
+];
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Appends `chunk` to `prev`, keeping the combined string within `cap` bytes.
+ * When the cap is exceeded the oldest bytes are dropped (tail is preserved).
+ */
+export function appendWithCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+    const combined = prev + chunk;
+    return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+function stripClaudeNestingVars(env) {
+    const blocked = new Set(CLAUDE_NESTING_VARS);
+    const result = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (!blocked.has(k)) {
+            result[k] = v;
+        }
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Exported helpers
+// ---------------------------------------------------------------------------
+/**
+ * Builds an env record that inherits from `process.env`, ensures critical
+ * keys (`HOME`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PATH`) are preserved
+ * untouched from the current process, strips Claude Code nesting-guard vars,
+ * and finally layers caller-supplied `overrides` on top.
+ */
+export function buildInheritedEnv(overrides) {
+    // Start from process.env, filtering out undefined values.
+    const base = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined) {
+            base[k] = v;
+        }
+    }
+    // Restore critical keys from process.env (no-op if already present, but
+    // ensures overrides cannot accidentally clobber them before we re-pin).
+    const pinKeys = ['HOME', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'PATH'];
+    for (const key of pinKeys) {
+        const val = process.env[key];
+        if (val !== undefined) {
+            base[key] = val;
+        }
+    }
+    // Strip nesting guards so spawned Claude processes don't refuse to start.
+    const stripped = stripClaudeNestingVars(base);
+    // Layer caller overrides on top (they cannot override pinned keys because
+    // we re-pin below).
+    const merged = { ...stripped, ...(overrides ?? {}) };
+    // Re-pin critical keys so overrides cannot change them.
+    for (const key of pinKeys) {
+        const val = process.env[key];
+        if (val !== undefined) {
+            merged[key] = val;
+        }
+    }
+    return merged;
+}
+/**
+ * Ensures the env record has a non-empty `PATH`.
+ * If it is already set, returns the record unchanged.
+ * Otherwise injects a sensible macOS/Linux default.
+ */
+export function ensurePathInEnv(env) {
+    if (env['PATH'] && env['PATH'].length > 0) {
+        return env;
+    }
+    return {
+        ...env,
+        PATH: '/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin',
+    };
+}
+/**
+ * Returns a shallow copy of `env` where any key matching `SENSITIVE_ENV_KEY`
+ * has its value replaced with `'***REDACTED***'`.
+ */
+export function redactEnvForLogs(env) {
+    const result = {};
+    for (const [k, v] of Object.entries(env)) {
+        result[k] = SENSITIVE_ENV_KEY.test(k) ? '***REDACTED***' : v;
+    }
+    return result;
+}
+/**
+ * Resolves the absolute path of `command` using `which` (or `where` on
+ * Windows). Throws if the command is not found.
+ */
+export async function resolveCommand(command) {
+    const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+    try {
+        const { stdout } = await execFileAsync(whichCmd, [command]);
+        return stdout.trim();
+    }
+    catch {
+        throw new Error(`Command not found: ${command}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Core child-process runner
+// ---------------------------------------------------------------------------
+/**
+ * Spawns a child process and captures its output.
+ *
+ * - Inherits env via `ensurePathInEnv({ ...process.env, ...opts.env })` with
+ *   Claude nesting vars stripped.
+ * - Captures up to `MAX_CAPTURE_BYTES` of stdout/stderr each.
+ * - Streams data to `opts.onLog` in real time.
+ * - Supports optional `AbortSignal` and timeout.
+ */
+export function runChildProcess(opts) {
+    return new Promise((resolve, reject) => {
+        // Merge env: process.env base, then caller overrides, then ensure PATH.
+        const rawEnv = {};
+        for (const [k, v] of Object.entries(process.env)) {
+            if (v !== undefined)
+                rawEnv[k] = v;
+        }
+        const mergedEnv = ensurePathInEnv(stripClaudeNestingVars({ ...rawEnv, ...opts.env }));
+        const stdinMode = opts.stdin != null ? 'pipe' : 'ignore';
+        const child = spawn(opts.command, opts.args, {
+            cwd: opts.cwd,
+            env: mergedEnv,
+            stdio: [stdinMode, 'pipe', 'pipe'],
+            detached: true,
+            shell: false,
+        });
+        let stdoutBuf = '';
+        let stderrBuf = '';
+        let timedOut = false;
+        let settled = false;
+        // -----------------------------------------------------------------------
+        // stdin
+        // -----------------------------------------------------------------------
+        if (opts.stdin != null && child.stdin) {
+            child.stdin.write(opts.stdin);
+            child.stdin.end();
+        }
+        // -----------------------------------------------------------------------
+        // onSpawn
+        // -----------------------------------------------------------------------
+        child.on('spawn', () => {
+            if (typeof child.pid === 'number' && child.pid > 0) {
+                opts.onSpawn?.(child.pid);
+            }
+        });
+        // -----------------------------------------------------------------------
+        // stdout / stderr capture
+        // -----------------------------------------------------------------------
+        child.stdout?.on('data', (chunk) => {
+            const text = chunk.toString();
+            stdoutBuf = appendWithCap(stdoutBuf, text);
+            opts.onLog?.('stdout', text);
+        });
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString();
+            stderrBuf = appendWithCap(stderrBuf, text);
+            opts.onLog?.('stderr', text);
+        });
+        // -----------------------------------------------------------------------
+        // Kill helper (SIGTERM → SIGKILL after 5 s)
+        // -----------------------------------------------------------------------
+        function killChild() {
+            try {
+                // Negative PID kills the entire process group (detached: true).
+                if (typeof child.pid === 'number') {
+                    process.kill(-child.pid, 'SIGTERM');
+                }
+                else {
+                    child.kill('SIGTERM');
+                }
+            }
+            catch {
+                // Process may have already exited — ignore.
+            }
+            setTimeout(() => {
+                try {
+                    if (typeof child.pid === 'number') {
+                        process.kill(-child.pid, 'SIGKILL');
+                    }
+                    else {
+                        child.kill('SIGKILL');
+                    }
+                }
+                catch {
+                    // Ignore.
+                }
+            }, 5_000).unref();
+        }
+        // -----------------------------------------------------------------------
+        // AbortSignal support
+        // -----------------------------------------------------------------------
+        let abortListener;
+        if (opts.signal) {
+            abortListener = () => {
+                if (!settled)
+                    killChild();
+            };
+            if (opts.signal.aborted) {
+                // Already aborted before spawn.
+                killChild();
+            }
+            else {
+                opts.signal.addEventListener('abort', abortListener);
+            }
+        }
+        // -----------------------------------------------------------------------
+        // Timeout support
+        // -----------------------------------------------------------------------
+        let timeoutHandle;
+        if (opts.timeoutMs != null && opts.timeoutMs > 0) {
+            timeoutHandle = setTimeout(() => {
+                if (!settled) {
+                    timedOut = true;
+                    killChild();
+                }
+            }, opts.timeoutMs);
+        }
+        // -----------------------------------------------------------------------
+        // close / error
+        // -----------------------------------------------------------------------
+        child.on('close', (exitCode, exitSignal) => {
+            settled = true;
+            if (timeoutHandle !== undefined)
+                clearTimeout(timeoutHandle);
+            if (abortListener && opts.signal) {
+                opts.signal.removeEventListener('abort', abortListener);
+            }
+            resolve({
+                exitCode,
+                signal: exitSignal,
+                timedOut,
+                stdout: stdoutBuf,
+                stderr: stderrBuf,
+            });
+        });
+        child.on('error', (err) => {
+            settled = true;
+            if (timeoutHandle !== undefined)
+                clearTimeout(timeoutHandle);
+            if (abortListener && opts.signal) {
+                opts.signal.removeEventListener('abort', abortListener);
+            }
+            reject(new Error(`Failed to spawn "${opts.command}": ${err.message}`, { cause: err }));
+        });
+    });
+}
+//# sourceMappingURL=server-utils.js.map

package/dist/server-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-utils.js","sourceRoot":"","sources":["../src/server-utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@fixy/adapter-utils",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export {
+  buildInheritedEnv,
+  ensurePathInEnv,
+  redactEnvForLogs,
+  resolveCommand,
+  runChildProcess,
+  appendWithCap,
+  MAX_CAPTURE_BYTES,
+} from './server-utils.js';
+
+export type { RunChildOpts, RunChildResult } from './server-utils.js';

package/src/server-utils.ts

@@ -0,0 +1,315 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024; // 4MB cap per stream
+
+const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+
+/** Claude Code nesting-guard env vars that prevent nested spawns from starting. */
+const CLAUDE_NESTING_VARS = [
+  'CLAUDECODE',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'CLAUDE_CODE_SESSION',
+  'CLAUDE_CODE_PARENT_SESSION',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RunChildOpts {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  stdin?: string;
+  signal?: AbortSignal;
+  onLog?: (stream: 'stdout' | 'stderr', chunk: string) => void;
+  onSpawn?: (pid: number) => void;
+  timeoutMs?: number;
+}
+
+export interface RunChildResult {
+  exitCode: number | null;
+  signal: string | null;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Appends `chunk` to `prev`, keeping the combined string within `cap` bytes.
+ * When the cap is exceeded the oldest bytes are dropped (tail is preserved).
+ */
+export function appendWithCap(prev: string, chunk: string, cap = MAX_CAPTURE_BYTES): string {
+  const combined = prev + chunk;
+  return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+
+function stripClaudeNestingVars(env: Record<string, string>): Record<string, string> {
+  const blocked = new Set<string>(CLAUDE_NESTING_VARS);
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    if (!blocked.has(k)) {
+      result[k] = v;
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Exported helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds an env record that inherits from `process.env`, ensures critical
+ * keys (`HOME`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `PATH`) are preserved
+ * untouched from the current process, strips Claude Code nesting-guard vars,
+ * and finally layers caller-supplied `overrides` on top.
+ */
+export function buildInheritedEnv(overrides?: Record<string, string>): Record<string, string> {
+  // Start from process.env, filtering out undefined values.
+  const base: Record<string, string> = {};
+  for (const [k, v] of Object.entries(process.env)) {
+    if (v !== undefined) {
+      base[k] = v;
+    }
+  }
+
+  // Restore critical keys from process.env (no-op if already present, but
+  // ensures overrides cannot accidentally clobber them before we re-pin).
+  const pinKeys = ['HOME', 'CLAUDE_CONFIG_DIR', 'CODEX_HOME', 'PATH'] as const;
+  for (const key of pinKeys) {
+    const val = process.env[key];
+    if (val !== undefined) {
+      base[key] = val;
+    }
+  }
+
+  // Strip nesting guards so spawned Claude processes don't refuse to start.
+  const stripped = stripClaudeNestingVars(base);
+
+  // Layer caller overrides on top (they cannot override pinned keys because
+  // we re-pin below).
+  const merged = { ...stripped, ...(overrides ?? {}) };
+
+  // Re-pin critical keys so overrides cannot change them.
+  for (const key of pinKeys) {
+    const val = process.env[key];
+    if (val !== undefined) {
+      merged[key] = val;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Ensures the env record has a non-empty `PATH`.
+ * If it is already set, returns the record unchanged.
+ * Otherwise injects a sensible macOS/Linux default.
+ */
+export function ensurePathInEnv(env: Record<string, string>): Record<string, string> {
+  if (env['PATH'] && env['PATH'].length > 0) {
+    return env;
+  }
+  return {
+    ...env,
+    PATH: '/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin',
+  };
+}
+
+/**
+ * Returns a shallow copy of `env` where any key matching `SENSITIVE_ENV_KEY`
+ * has its value replaced with `'***REDACTED***'`.
+ */
+export function redactEnvForLogs(env: Record<string, string>): Record<string, string> {
+  const result: Record<string, string> = {};
+  for (const [k, v] of Object.entries(env)) {
+    result[k] = SENSITIVE_ENV_KEY.test(k) ? '***REDACTED***' : v;
+  }
+  return result;
+}
+
+/**
+ * Resolves the absolute path of `command` using `which` (or `where` on
+ * Windows). Throws if the command is not found.
+ */
+export async function resolveCommand(command: string): Promise<string> {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const { stdout } = await execFileAsync(whichCmd, [command]);
+    return stdout.trim();
+  } catch {
+    throw new Error(`Command not found: ${command}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core child-process runner
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawns a child process and captures its output.
+ *
+ * - Inherits env via `ensurePathInEnv({ ...process.env, ...opts.env })` with
+ *   Claude nesting vars stripped.
+ * - Captures up to `MAX_CAPTURE_BYTES` of stdout/stderr each.
+ * - Streams data to `opts.onLog` in real time.
+ * - Supports optional `AbortSignal` and timeout.
+ */
+export function runChildProcess(opts: RunChildOpts): Promise<RunChildResult> {
+  return new Promise((resolve, reject) => {
+    // Merge env: process.env base, then caller overrides, then ensure PATH.
+    const rawEnv: Record<string, string> = {};
+    for (const [k, v] of Object.entries(process.env)) {
+      if (v !== undefined) rawEnv[k] = v;
+    }
+    const mergedEnv = ensurePathInEnv(stripClaudeNestingVars({ ...rawEnv, ...opts.env }));
+
+    const stdinMode = opts.stdin != null ? 'pipe' : 'ignore';
+
+    const child = spawn(opts.command, opts.args, {
+      cwd: opts.cwd,
+      env: mergedEnv,
+      stdio: [stdinMode, 'pipe', 'pipe'],
+      detached: true,
+      shell: false,
+    });
+
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    let timedOut = false;
+    let settled = false;
+
+    // -----------------------------------------------------------------------
+    // stdin
+    // -----------------------------------------------------------------------
+    if (opts.stdin != null && child.stdin) {
+      child.stdin.write(opts.stdin);
+      child.stdin.end();
+    }
+
+    // -----------------------------------------------------------------------
+    // onSpawn
+    // -----------------------------------------------------------------------
+    child.on('spawn', () => {
+      if (typeof child.pid === 'number' && child.pid > 0) {
+        opts.onSpawn?.(child.pid);
+      }
+    });
+
+    // -----------------------------------------------------------------------
+    // stdout / stderr capture
+    // -----------------------------------------------------------------------
+    child.stdout?.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      stdoutBuf = appendWithCap(stdoutBuf, text);
+      opts.onLog?.('stdout', text);
+    });
+
+    child.stderr?.on('data', (chunk: Buffer) => {
+      const text = chunk.toString();
+      stderrBuf = appendWithCap(stderrBuf, text);
+      opts.onLog?.('stderr', text);
+    });
+
+    // -----------------------------------------------------------------------
+    // Kill helper (SIGTERM → SIGKILL after 5 s)
+    // -----------------------------------------------------------------------
+    function killChild(): void {
+      try {
+        // Negative PID kills the entire process group (detached: true).
+        if (typeof child.pid === 'number') {
+          process.kill(-child.pid, 'SIGTERM');
+        } else {
+          child.kill('SIGTERM');
+        }
+      } catch {
+        // Process may have already exited — ignore.
+      }
+
+      setTimeout(() => {
+        try {
+          if (typeof child.pid === 'number') {
+            process.kill(-child.pid, 'SIGKILL');
+          } else {
+            child.kill('SIGKILL');
+          }
+        } catch {
+          // Ignore.
+        }
+      }, 5_000).unref();
+    }
+
+    // -----------------------------------------------------------------------
+    // AbortSignal support
+    // -----------------------------------------------------------------------
+    let abortListener: (() => void) | undefined;
+    if (opts.signal) {
+      abortListener = () => {
+        if (!settled) killChild();
+      };
+      if (opts.signal.aborted) {
+        // Already aborted before spawn.
+        killChild();
+      } else {
+        opts.signal.addEventListener('abort', abortListener);
+      }
+    }
+
+    // -----------------------------------------------------------------------
+    // Timeout support
+    // -----------------------------------------------------------------------
+    let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    if (opts.timeoutMs != null && opts.timeoutMs > 0) {
+      timeoutHandle = setTimeout(() => {
+        if (!settled) {
+          timedOut = true;
+          killChild();
+        }
+      }, opts.timeoutMs);
+    }
+
+    // -----------------------------------------------------------------------
+    // close / error
+    // -----------------------------------------------------------------------
+    child.on('close', (exitCode: number | null, exitSignal: NodeJS.Signals | null) => {
+      settled = true;
+
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+      if (abortListener && opts.signal) {
+        opts.signal.removeEventListener('abort', abortListener);
+      }
+
+      resolve({
+        exitCode,
+        signal: exitSignal,
+        timedOut,
+        stdout: stdoutBuf,
+        stderr: stderrBuf,
+      });
+    });
+
+    child.on('error', (err: Error) => {
+      settled = true;
+
+      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle);
+      if (abortListener && opts.signal) {
+        opts.signal.removeEventListener('abort', abortListener);
+      }
+
+      reject(new Error(`Failed to spawn "${opts.command}": ${err.message}`, { cause: err }));
+    });
+  });
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}