@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/{spawn.js → spawn/spawn.js}

@@ -30,140 +30,25 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var spawn_exports = {};
 __export(spawn_exports, {
-  enhanceSpawnError: () => enhanceSpawnError,
-  isSpawnError: () => isSpawnError,
-  isStdioType: () => isStdioType,
   spawn: () => spawn,
   spawnSync: () => spawnSync
 });
 module.exports = __toCommonJS(spawn_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_arrays = require("./arrays");
-var import_bin = require("./bin");
-var import_process = require("./constants/process");
+var import_which = require("../bin/which");
+var import_abort = require("../process/abort");
+var import_child_process = require("../node/child-process");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+var import_inspect = require("../objects/inspect");
+var import_normalize = require("../paths/normalize");
+var import_regexp = require("../primordials/regexp");
+var import_registry = require("../spinner/registry");
+var import_internal = require("./_internal");
 var import_errors = require("./errors");
-var import_child_process = require("./node/child-process");
-var import_fs = require("./node/fs");
-var import_path = require("./node/path");
-var import_objects = require("./objects");
-var import_normalize = require("./paths/normalize");
-var import_spinner = require("./spinner");
-var import_strings = require("./strings");
-var import_primordials = require("./primordials");
-const abortSignal = (0, import_process.getAbortSignal)();
-const spinner = (0, import_spinner.getDefaultSpinner)();
-const stackCache = new import_primordials.WeakMapCtor();
-const spawnBinPathCache = new import_primordials.MapCtor();
-const windowsScriptExtRegExp = /\.(?:cmd|bat|ps1)$/i;
-let _npmCliPromiseSpawn;
-// @__NO_SIDE_EFFECTS__
-function getNpmCliPromiseSpawn() {
-  if (_npmCliPromiseSpawn === void 0) {
-    _npmCliPromiseSpawn = require("./external/@npmcli/promise-spawn");
-  }
-  return _npmCliPromiseSpawn;
-}
-// @__NO_SIDE_EFFECTS__
-function stripAnsiFromSpawnResult(result) {
-  const res = result;
-  const { stderr, stdout } = res;
-  if (typeof stdout === "string") {
-    res.stdout = (0, import_strings.stripAnsi)(stdout);
-  }
-  if (typeof stderr === "string") {
-    res.stderr = (0, import_strings.stripAnsi)(stderr);
-  }
-  return res;
-}
-// @__NO_SIDE_EFFECTS__
-function enhanceSpawnError(error) {
-  if (error === null || typeof error !== "object") {
-    return error;
-  }
-  if (!/* @__PURE__ */ isSpawnError(error)) {
-    return error;
-  }
-  const err = error;
-  const { args, cmd, code, signal, stderr } = err;
-  const stderrText = typeof stderr === "string" ? stderr : stderr?.toString() ?? "";
-  let enhancedMessage = `Command failed: ${cmd}`;
-  if (args && args.length > 0) {
-    const argsStr = args.join(" ");
-    if (argsStr.length < 100) {
-      enhancedMessage += ` ${argsStr}`;
-    } else {
-      enhancedMessage += ` ${argsStr.slice(0, 97)}...`;
-    }
-  }
-  if (signal) {
-    enhancedMessage += ` (terminated by ${signal})`;
-  } else if (code !== void 0) {
-    enhancedMessage += ` (exit code ${code})`;
-  }
-  const trimmedStderr = stderrText.trim();
-  if (trimmedStderr) {
-    const firstLine = trimmedStderr.split("\n")[0] ?? "";
-    if (firstLine.length < 200) {
-      enhancedMessage += `
-${firstLine}`;
-    } else {
-      enhancedMessage += `
-${firstLine.slice(0, 197)}...`;
-    }
-  }
-  const isSynthetic = err.message === "command failed";
-  if (isSynthetic) {
-    (0, import_primordials.ObjectDefineProperty)(err, "message", {
-      __proto__: null,
-      value: enhancedMessage,
-      writable: true,
-      enumerable: false,
-      configurable: true
-    });
-    return err;
-  }
-  const enhancedError = new import_primordials.ErrorCtor(enhancedMessage, {
-    cause: err
-  });
-  const descriptors = (0, import_primordials.ObjectGetOwnPropertyDescriptors)(err);
-  (0, import_primordials.ReflectDeleteProperty)(descriptors, "message");
-  (0, import_primordials.ReflectDeleteProperty)(descriptors, "stack");
-  (0, import_primordials.ObjectDefineProperties)(enhancedError, descriptors);
-  (0, import_primordials.ObjectDefineProperty)(enhancedError, "stack", {
-    __proto__: null,
-    configurable: true,
-    enumerable: false,
-    get() {
-      let stack = stackCache.get(enhancedError);
-      if (stack === void 0) {
-        try {
-          stack = (0, import_errors.stackWithCauses)(err);
-        } catch {
-          stack = err.stack ?? new Error().stack ?? "";
-        }
-        stackCache.set(enhancedError, stack);
-      }
-      return stack;
-    }
-  });
-  return enhancedError;
-}
-// @__NO_SIDE_EFFECTS__
-function isSpawnError(value) {
-  if (value === null || typeof value !== "object") {
-    return false;
-  }
-  const err = value;
-  return (0, import_objects.hasOwn)(err, "code") && typeof err["code"] !== "undefined" || (0, import_objects.hasOwn)(err, "errno") && typeof err["errno"] !== "undefined" || (0, import_objects.hasOwn)(err, "syscall") && typeof err["syscall"] === "string";
-}
-// @__NO_SIDE_EFFECTS__
-function isStdioType(stdio, type) {
-  if (arguments.length === 1) {
-    const validTypes = ["pipe", "ignore", "inherit", "overlapped"];
-    return typeof stdio === "string" && validTypes.includes(stdio);
-  }
-  return stdio === type || (stdio === null || stdio === void 0) && type === "pipe" || (0, import_arrays.isArray)(stdio) && stdio.length > 2 && stdio[0] === type && stdio[1] === type && stdio[2] === type;
-}
+var import_stdio = require("./stdio");
+const abortSignal = (0, import_abort.getAbortSignal)();
+const spinner = (0, import_registry.getDefaultSpinner)();
 function spawn(cmd, args, options, extra) {
   const {
     spinner: optionsSpinner = spinner,
@@ -177,24 +62,24 @@ function spawn(cmd, args, options, extra) {
   let actualCmd = cmd;
   if (!(0, import_normalize.isPath)(cmd)) {
     const fs = (0, import_fs.getNodeFs)();
-    const cached = spawnBinPathCache.get(cmd);
+    const cached = import_internal.spawnBinPathCache.get(cmd);
     if (cached) {
       if (fs.existsSync(cached)) {
         actualCmd = cached;
       } else {
-        spawnBinPathCache.delete(cmd);
+        import_internal.spawnBinPathCache.delete(cmd);
       }
     }
     if (actualCmd === cmd) {
-      const resolved = (0, import_bin.whichSync)(cmd, { cwd, nothrow: true });
+      const resolved = (0, import_which.whichSync)(cmd, { cwd, nothrow: true });
       if (resolved && typeof resolved === "string") {
         actualCmd = resolved;
-        spawnBinPathCache.set(cmd, resolved);
+        import_internal.spawnBinPathCache.set(cmd, resolved);
       }
     }
   }
   const WIN32 = import_node_process.default.platform === "win32";
-  if (WIN32 && shell && (0, import_primordials.RegExpPrototypeTest)(windowsScriptExtRegExp, actualCmd)) {
+  if (WIN32 && shell && (0, import_regexp.RegExpPrototypeTest)(import_internal.windowsScriptExtRegExp, actualCmd)) {
     if (!(0, import_normalize.isPath)(actualCmd)) {
       actualCmd = (0, import_path.getNodePath)().basename(
         actualCmd,
@@ -203,7 +88,7 @@ function spawn(cmd, args, options, extra) {
     }
   }
   const wasSpinning = !!spinnerInstance?.isSpinning;
-  const shouldStopSpinner = wasSpinning && !/* @__PURE__ */ isStdioType(stdio, "ignore") && !/* @__PURE__ */ isStdioType(stdio, "pipe");
+  const shouldStopSpinner = wasSpinning && !(0, import_stdio.isStdioType)(stdio, "ignore") && !(0, import_stdio.isStdioType)(stdio, "pipe");
   const shouldRestartSpinner = shouldStopSpinner;
   if (shouldStopSpinner) {
     spinnerInstance.stop();
@@ -226,7 +111,7 @@ function spawn(cmd, args, options, extra) {
     uid: spawnOptions.uid,
     gid: spawnOptions.gid
   };
-  const npmCliPromiseSpawn = /* @__PURE__ */ getNpmCliPromiseSpawn();
+  const npmCliPromiseSpawn = (0, import_internal.getNpmCliPromiseSpawn)();
   const spawnPromise = npmCliPromiseSpawn(
     actualCmd,
     args ? [...args] : [],
@@ -239,15 +124,15 @@ function spawn(cmd, args, options, extra) {
     newSpawnPromise = (async () => {
       try {
         const result = await spawnPromise;
-        const strippedResult = /* @__PURE__ */ stripAnsiFromSpawnResult(result);
+        const strippedResult = (0, import_internal.stripAnsiFromSpawnResult)(result);
         if ("code" in strippedResult) {
           ;
           strippedResult.exitCode = strippedResult.code;
         }
         return strippedResult;
       } catch (error) {
-        const strippedError = /* @__PURE__ */ stripAnsiFromSpawnResult(error);
-        throw /* @__PURE__ */ enhanceSpawnError(strippedError);
+        const strippedError = (0, import_internal.stripAnsiFromSpawnResult)(error);
+        throw (0, import_errors.enhanceSpawnError)(strippedError);
       }
     })();
   } else {
@@ -261,7 +146,7 @@ function spawn(cmd, args, options, extra) {
         }
         return result;
       } catch (error) {
-        throw /* @__PURE__ */ enhanceSpawnError(error);
+        throw (0, import_errors.enhanceSpawnError)(error);
       }
     })();
   }
@@ -283,17 +168,17 @@ function spawn(cmd, args, options, extra) {
 function spawnSync(cmd, args, options) {
   let actualCmd = cmd;
   if (!(0, import_normalize.isPath)(cmd)) {
-    const resolved = (0, import_bin.whichSync)(cmd, {
-      cwd: (0, import_objects.getOwn)(options, "cwd"),
+    const resolved = (0, import_which.whichSync)(cmd, {
+      cwd: (0, import_inspect.getOwn)(options, "cwd"),
       nothrow: true
     });
     if (resolved && typeof resolved === "string") {
       actualCmd = resolved;
     }
   }
-  const shell = (0, import_objects.getOwn)(options, "shell");
+  const shell = (0, import_inspect.getOwn)(options, "shell");
   const WIN32 = import_node_process.default.platform === "win32";
-  if (WIN32 && shell && (0, import_primordials.RegExpPrototypeTest)(windowsScriptExtRegExp, actualCmd)) {
+  if (WIN32 && shell && (0, import_regexp.RegExpPrototypeTest)(import_internal.windowsScriptExtRegExp, actualCmd)) {
     if (!(0, import_normalize.isPath)(actualCmd)) {
       actualCmd = (0, import_path.getNodePath)().basename(
         actualCmd,
@@ -322,13 +207,10 @@ function spawnSync(cmd, args, options) {
       result.stderr = stderr.toString().trim();
     }
   }
-  return shouldStripAnsi && stdioString ? /* @__PURE__ */ stripAnsiFromSpawnResult(result) : result;
+  return shouldStripAnsi && stdioString ? (0, import_internal.stripAnsiFromSpawnResult)(result) : result;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  enhanceSpawnError,
-  isSpawnError,
-  isStdioType,
   spawn,
   spawnSync
 });

package/dist/spawn/stdio.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Stdio configuration helpers for `spawn` callers. `isStdioType` is
+ *   dual-purpose:
+ *
+ *   - One arg: validate that a value is a known stdio mode (`'pipe'` / `'ignore'`
+ *     / `'inherit'` / `'overlapped'`).
+ *   - Two args: check whether the caller's stdio config matches a specific mode.
+ *     Useful in spinner-pause logic — the spinner only stops when the child
+ *     writes to a non-piped stream that would otherwise interleave with spinner
+ *     redraws. Two-arg behavior special-cases `null` / `undefined` ↔ `'pipe'`
+ *     because Node.js defaults unspecified entries to `'pipe'`. The
+ *     three-element-array branch handles the common `[in, out, err]` tuple
+ *     where all three streams use the same mode.
+ */
+import type { StdioType } from './types';
+/**
+ * Check if stdio configuration matches a specific type. When called with one
+ * argument, validates if it's a valid stdio type. When called with two
+ * arguments, checks if the stdio config matches the specified type.
+ *
+ * @example
+ *   // Check if valid stdio type
+ *   isStdioType('pipe') // true
+ *   isStdioType('invalid') // false
+ *
+ * @example
+ *   // Check if stdio matches specific type
+ *   isStdioType('pipe', 'pipe') // true
+ *   isStdioType(['pipe', 'pipe', 'pipe'], 'pipe') // true
+ *   isStdioType('ignore', 'pipe') // false
+ *
+ * @param {string | string[]} stdio - Stdio configuration to check.
+ * @param {StdioType | undefined} type - Expected stdio type (optional)
+ *
+ * @returns {boolean} `true` if stdio matches the type or is valid
+ */
+export declare function isStdioType(stdio: string | string[], type?: StdioType | undefined): boolean;

package/dist/spawn/stdio.js

@@ -0,0 +1,38 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stdio_exports = {};
+__export(stdio_exports, {
+  isStdioType: () => isStdioType
+});
+module.exports = __toCommonJS(stdio_exports);
+var import_predicates = require("../arrays/predicates");
+// @__NO_SIDE_EFFECTS__
+function isStdioType(stdio, type) {
+  if (arguments.length === 1) {
+    const validTypes = ["pipe", "ignore", "inherit", "overlapped"];
+    return typeof stdio === "string" && validTypes.includes(stdio);
+  }
+  return stdio === type || (stdio === null || stdio === void 0) && type === "pipe" || (0, import_predicates.isArray)(stdio) && stdio.length > 2 && stdio[0] === type && stdio[1] === type && stdio[2] === type;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isStdioType
+});

package/dist/spawn/types.d.ts

@@ -0,0 +1,325 @@
+/**
+ * @file Public type surface for `spawn/*` modules. Most of this is straight
+ *   Node.js child_process types duplicated so the lib doesn't carry a hard
+ *   `@types/node` requirement at the surface. The `Spawn*` types layer
+ *   Socket-specific options on top:
+ *
+ *   - `SpawnOptions.spinner` lets the caller pause an outer spinner while the
+ *     child runs (so progress output isn't smeared by the spinner's redraw
+ *     loop).
+ *   - `SpawnOptions.stripAnsi` defaults to true — most consumers want plain text
+ *     from captured output. Pass false only when the output is being forwarded
+ *     to a terminal directly.
+ *   - `SpawnOptions.stdioString` defaults to true — string output is ergonomic;
+ *     opt out for binary streams. `PromiseSpawnResult` is the upstream
+ *     `@npmcli/promise-spawn` shape: a Promise enriched with `process` +
+ *     `stdin` accessors so callers can reach into the running child without
+ *     re-spawning.
+ */
+import type { SendHandle, Serializable, StdioOptions } from 'node:child_process';
+import type { EventEmitter } from 'node:events';
+import type { Remap } from '../objects/types';
+import type { SpinnerInstance } from '../spinner/types';
+export type BufferEncoding = globalThis.BufferEncoding;
+/**
+ * Options for spawning a child process with promise-based completion.
+ *
+ * @property {string | undefined} cwd - Current working directory for the
+ *   process.
+ * @property {NodeJS.ProcessEnv | undefined} env - Environment variables for the
+ *   process.
+ * @property {number | undefined} gid - Group identity of the process (POSIX
+ *   only)
+ * @property {boolean | string | undefined} shell - Whether to run command in
+ *   shell, or path to shell.
+ * @property {AbortSignal | undefined} signal - Signal to abort the process.
+ * @property {StdioType | undefined} stdio - Stdio configuration (`'pipe'`,
+ *   `'ignore'`, `'inherit'`, or array)
+ * @property {boolean | undefined} stdioString - Convert stdio output to strings
+ *   (default: `true`)
+ * @property {number | undefined} timeout - Maximum time in milliseconds before
+ *   killing the process.
+ * @property {number | undefined} uid - User identity of the process (POSIX
+ *   only)
+ * @property {boolean | undefined} windowsVerbatimArguments - Don't quote or
+ *   escape arguments on Windows (requires shell: true). Use when you need exact
+ *   argument control. Default: false.
+ */
+export type PromiseSpawnOptions = {
+    cwd?: string | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    gid?: number | undefined;
+    shell?: boolean | string | undefined;
+    signal?: AbortSignal | undefined;
+    stdio?: StdioType | undefined;
+    stdioString?: boolean | undefined;
+    timeout?: number | undefined;
+    uid?: number | undefined;
+    windowsVerbatimArguments?: boolean | undefined;
+};
+/**
+ * Result returned by {@link spawn} when the child process completes. This is a
+ * Promise that resolves with process exit information and output, with
+ * additional properties for accessing the running process and stdin stream.
+ *
+ * @example
+ *   const result = spawn('echo', ['hello'])
+ *   result.stdin?.write('additional input\n')
+ *   const { code, stdout } = await result
+ *   console.log(stdout) // 'hello'
+ *
+ * @property {ChildProcess} process - The running child process instance.
+ * @property {WritableStreamType | null} stdin - Writable stream for process
+ *   stdin, or `null` if not piped.
+ */
+export type PromiseSpawnResult<T = string | Buffer> = Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: T;
+    stderr: T;
+}> & {
+    process: ChildProcess;
+    stdin: WritableStreamType | null;
+};
+/**
+ * Error object thrown when a spawned process fails. Extends the standard Error
+ * with process-specific information including exit code, signal, command
+ * details, and captured output.
+ *
+ * @example
+ *   try {
+ *     await spawn('exit', ['1'])
+ *   } catch (e) {
+ *     if (isSpawnError(e)) {
+ *       console.error(`Command failed with code ${e.code}`)
+ *       console.error(`stderr: ${e.stderr}`)
+ *     }
+ *   }
+ *
+ * @property {string[]} args - Arguments passed to the command.
+ * @property {string} cmd - Command that was executed.
+ * @property {number} code - Process exit code.
+ * @property {string} name - Error name (typically `'Error'`)
+ * @property {string} message - Error message describing the failure.
+ * @property {NodeJS.Signals | null} signal - Signal that terminated the
+ *   process, if any.
+ * @property {string} stack - Stack trace of the error.
+ * @property {string | Buffer} stderr - Standard error output from the process.
+ * @property {string | Buffer} stdout - Standard output from the process.
+ */
+export type SpawnError = {
+    args: string[];
+    cmd: string;
+    code: number;
+    name: string;
+    message: string;
+    signal: NodeJS.Signals | null;
+    stack: string;
+    stderr: string | Buffer;
+    stdout: string | Buffer;
+};
+/**
+ * Spawn error variant where stdout and stderr are guaranteed to be strings.
+ * This type is used when `stdioString: true` is set in spawn options.
+ *
+ * @property {string} stdout - Standard output as a string.
+ * @property {string} stderr - Standard error as a string.
+ */
+export type SpawnErrorWithOutputString = SpawnError & {
+    stdout: string;
+    stderr: string;
+};
+/**
+ * Spawn error variant where stdout and stderr are guaranteed to be Buffers.
+ * This type is used when `stdioString: false` is set in spawn options.
+ *
+ * @property {Buffer} stdout - Standard output as a Buffer.
+ * @property {Buffer} stderr - Standard error as a Buffer.
+ */
+export type SpawnErrorWithOutputBuffer = SpawnError & {
+    stdout: Buffer;
+    stderr: Buffer;
+};
+/**
+ * Extra options passed to the underlying promise-spawn implementation. This is
+ * an open-ended object for passing additional metadata or configuration.
+ */
+export type SpawnExtra = Record<string, unknown>;
+/**
+ * Valid values for individual stdio streams. - `'pipe'` - Creates a pipe
+ * between child and parent (default) - `'ignore'` - Ignores the stream -
+ * `'inherit'` - Uses parent's stream - `'overlapped'` - Windows-specific
+ * overlapped I/O.
+ */
+export type IOType = 'pipe' | 'ignore' | 'inherit' | 'overlapped';
+/**
+ * Configuration for process stdio (stdin, stdout, stderr) streams. Can be a
+ * single value applied to all streams, or an array specifying each stream
+ * individually. - `'ipc'` - Creates an IPC channel for communication with the
+ * parent.
+ *
+ * @example
+ *   // All streams piped
+ *   stdio: 'pipe'
+ *
+ * @example
+ *   // Custom configuration per stream: [stdin, stdout, stderr]
+ *   stdio: ['ignore', 'pipe', 'pipe']
+ */
+export type StdioType = IOType | 'ipc' | Array<IOType | 'ipc'>;
+/**
+ * Result object returned by {@link spawnSync} when the child process completes
+ * synchronously.
+ *
+ * @template T - Type of stdout/stderr (string or Buffer)
+ *
+ * @property {number} pid - Process ID of the spawned child.
+ * @property {(T | null)[]} output - Array containing stdout/stderr values.
+ * @property {T} stdout - Standard output from the process.
+ * @property {T} stderr - Standard error from the process.
+ * @property {number | null} status - Exit code, or `null` if killed by signal.
+ * @property {NodeJS.Signals | null} signal - Signal that terminated the
+ *   process, or `null`
+ * @property {Error | undefined} error - Error object if the spawn failed.
+ */
+export interface SpawnSyncReturns<T> {
+    pid: number;
+    output: Array<T | null>;
+    stdout: T;
+    stderr: T;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error | undefined;
+}
+export interface NodeSpawnOptions {
+    cwd?: string | URL | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    argv0?: string | undefined;
+    stdio?: StdioOptions | undefined;
+    detached?: boolean | undefined;
+    uid?: number | undefined;
+    gid?: number | undefined;
+    serialization?: 'json' | 'advanced' | undefined;
+    shell?: boolean | string | undefined;
+    windowsVerbatimArguments?: boolean | undefined;
+    windowsHide?: boolean | undefined;
+    signal?: AbortSignal | undefined;
+    timeout?: number | undefined;
+    killSignal?: NodeJS.Signals | number | undefined;
+}
+export interface NodeSpawnSyncOptions extends NodeSpawnOptions {
+    input?: string | NodeJS.ArrayBufferView | undefined;
+    maxBuffer?: number | undefined;
+    encoding?: BufferEncoding | 'buffer' | null | undefined;
+}
+export interface ChildProcess extends EventEmitter {
+    stdin: NodeJS.WritableStream | null;
+    stdout: NodeJS.ReadableStream | null;
+    stderr: NodeJS.ReadableStream | null;
+    readonly channel?: unknown;
+    readonly stdio: [
+        NodeJS.WritableStream | null,
+        NodeJS.ReadableStream | null,
+        NodeJS.ReadableStream | null,
+        NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined,
+        NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined
+    ];
+    readonly killed: boolean;
+    readonly pid?: number | undefined;
+    readonly connected: boolean;
+    readonly exitCode: number | null;
+    readonly signalCode: NodeJS.Signals | null;
+    readonly spawnargs: string[];
+    readonly spawnfile: string;
+    kill(signal?: NodeJS.Signals | number): boolean;
+    send(message: Serializable, callback?: (error: Error | null) => void): boolean;
+    send(message: Serializable, sendHandle?: SendHandle | undefined, callback?: (error: Error | null) => void): boolean;
+    send(message: Serializable, sendHandle?: SendHandle | undefined, options?: {
+        keepOpen?: boolean | undefined;
+    } | undefined, callback?: (error: Error | null) => void): boolean;
+    disconnect(): void;
+    unref(): void;
+    ref(): void;
+}
+export interface WritableStreamType {
+    writable: boolean;
+    writableEnded: boolean;
+    writableFinished: boolean;
+    writableHighWaterMark: number;
+    writableLength: number;
+    writableObjectMode: boolean;
+    writableCorked: number;
+    destroyed: boolean;
+    write(chunk: unknown, encoding?: BufferEncoding | undefined, callback?: (error?: Error | null) => void): boolean;
+    write(chunk: unknown, callback?: (error?: Error | null) => void): boolean;
+    end(cb?: () => void): this;
+    end(chunk: unknown, cb?: () => void): this;
+    end(chunk: unknown, encoding?: BufferEncoding | undefined, cb?: () => void): this;
+    cork(): void;
+    uncork(): void;
+    destroy(error?: Error | undefined): this;
+}
+/**
+ * Options for spawning a child process with {@link spawn}. Extends Node.js spawn
+ * options with additional Socket-specific functionality.
+ *
+ * @property {string | URL | undefined} cwd - Current working directory.
+ * @property {NodeJS.ProcessEnv | undefined} env - Environment variables.
+ * @property {number | undefined} gid - Group identity (POSIX)
+ * @property {boolean | string | undefined} shell - Run command in shell.
+ * @property {AbortSignal | undefined} signal - Abort signal.
+ * @property {import('../spinner/types').SpinnerInstance | undefined} spinner -
+ *   Spinner instance to pause during execution.
+ * @property {StdioType | undefined} stdio - Stdio configuration.
+ * @property {boolean | undefined} stdioString - Convert output to strings
+ *   (default: `true`)
+ * @property {boolean | undefined} stripAnsi - Remove ANSI codes from output
+ *   (default: `true`)
+ * @property {number | undefined} timeout - Timeout in milliseconds.
+ * @property {number | undefined} uid - User identity (POSIX)
+ * @property {boolean | undefined} windowsVerbatimArguments - Don't quote or
+ *   escape arguments on Windows (requires shell: true). Use when you need exact
+ *   argument control. Default: false.
+ */
+export type SpawnOptions = Remap<NodeSpawnOptions & {
+    spinner?: SpinnerInstance | undefined;
+    stdioString?: boolean;
+    stripAnsi?: boolean;
+}>;
+export type SpawnResult<T = string | Buffer> = PromiseSpawnResult<T>;
+/**
+ * Result object returned when a spawned process completes.
+ *
+ * @property {string} cmd - Command that was executed.
+ * @property {string[] | readonly string[]} args - Arguments passed to the
+ *   command.
+ * @property {number} code - Process exit code.
+ * @property {NodeJS.Signals | null} signal - Signal that terminated the
+ *   process, if any.
+ * @property {string | Buffer} stdout - Standard output (string if `stdioString:
+ *   true`, Buffer otherwise)
+ * @property {string | Buffer} stderr - Standard error (string if `stdioString:
+ *   true`, Buffer otherwise)
+ */
+export type SpawnStdioResult = {
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+};
+/**
+ * Options for synchronously spawning a child process with {@link spawnSync}.
+ *
+ * Mirrors {@link SpawnOptions} (stdioString, stripAnsi) but builds on Node's
+ * sync option shape ({@link NodeSpawnSyncOptions}) — which adds `input`,
+ * `maxBuffer`, and `encoding` that the async API doesn't have. The `spinner`
+ * field is excluded (not applicable for synchronous execution).
+ */
+export type SpawnSyncOptions = Remap<NodeSpawnSyncOptions & {
+    stdioString?: boolean;
+    stripAnsi?: boolean;
+}>;

package/dist/spawn/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);