@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/{process-lock.js → process/lock-manager.js}

@@ -18,56 +18,44 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var process_lock_exports = {};
-__export(process_lock_exports, {
-  processLock: () => processLock
+var lock_manager_exports = {};
+__export(lock_manager_exports, {
+  ProcessLockManager: () => ProcessLockManager
 });
-module.exports = __toCommonJS(process_lock_exports);
-var import_errors = require("./errors");
-var import_fs = require("./fs");
-var import_logger = require("./logger");
-var import_promises = require("./promises");
-var import_signal_exit = require("./signal-exit");
-var import_primordials = require("./primordials");
-let _fs;
-// @__NO_SIDE_EFFECTS__
-function getFs() {
-  if (_fs === void 0) {
-    _fs = require("node:fs");
-  }
-  return _fs;
-}
-let _path;
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
-const logger = (0, import_logger.getDefaultLogger)();
+module.exports = __toCommonJS(lock_manager_exports);
+var import_message = require("../errors/message");
+var import_safe = require("../fs/safe");
+var import_default = require("../logger/default");
+var import_date = require("../primordials/date");
+var import_error = require("../primordials/error");
+var import_map_set = require("../primordials/map-set");
+var import_math = require("../primordials/math");
+var import_retry = require("../promises/retry");
+var import_handler = require("../events/exit/handler");
+var import_internal = require("./_internal");
+const logger = (0, import_default.getDefaultLogger)();
 class ProcessLockManager {
-  activeLocks = new import_primordials.SetCtor();
-  touchTimers = new import_primordials.MapCtor();
+  activeLocks = new import_map_set.SetCtor();
+  touchTimers = new import_map_set.MapCtor();
   exitHandlerRegistered = false;
   /**
-   * Ensure process exit handler is registered for cleanup.
-   * Registers a handler that cleans up all active locks when the process exits.
+   * Ensure process exit handler is registered for cleanup. Registers a handler
+   * that cleans up all active locks when the process exits.
    */
   ensureExitHandler() {
     if (this.exitHandlerRegistered) {
       return;
     }
-    (0, import_signal_exit.onExit)(() => {
+    (0, import_handler.onExit)(() => {
       for (const timer of this.touchTimers.values()) {
         clearInterval(timer);
       }
       this.touchTimers.clear();
-      const fs = /* @__PURE__ */ getFs();
+      const fs = (0, import_internal.getFs)();
       for (const lockPath of this.activeLocks) {
         try {
           if (fs.existsSync(lockPath)) {
-            (0, import_fs.safeDeleteSync)(lockPath, { recursive: true });
+            (0, import_safe.safeDeleteSync)(lockPath, { recursive: true });
           }
         } catch {
         }
@@ -76,28 +64,28 @@ class ProcessLockManager {
     this.exitHandlerRegistered = true;
   }
   /**
-   * Touch a lock file to update its mtime.
-   * This prevents the lock from being detected as stale during long operations.
+   * Touch a lock file to update its mtime. This prevents the lock from being
+   * detected as stale during long operations.
    *
-   * @param lockPath - Path to the lock directory
+   * @param lockPath - Path to the lock directory.
    */
   touchLock(lockPath) {
     try {
-      const fs = /* @__PURE__ */ getFs();
+      const fs = (0, import_internal.getFs)();
       if (fs.existsSync(lockPath)) {
-        const now = (0, import_primordials.DateNow)() / 1e3;
+        const now = (0, import_date.DateNow)() / 1e3;
         fs.utimesSync(lockPath, now, now);
       }
     } catch (e) {
-      logger.warn(`Failed to touch lock ${lockPath}: ${(0, import_errors.errorMessage)(e)}`);
+      logger.warn(`Failed to touch lock ${lockPath}: ${(0, import_message.errorMessage)(e)}`);
     }
   }
   /**
-   * Start periodic touching of a lock file.
-   * Aligned with npm npx strategy to prevent false stale detection.
+   * Start periodic touching of a lock file. Aligned with npm npx strategy to
+   * prevent false stale detection.
    *
-   * @param lockPath - Path to the lock directory
-   * @param intervalMs - Touch interval in milliseconds
+   * @param lockPath - Path to the lock directory.
+   * @param intervalMs - Touch interval in milliseconds.
    */
   startTouchTimer(lockPath, intervalMs) {
     if (intervalMs <= 0 || this.touchTimers.has(lockPath)) {
@@ -112,7 +100,7 @@ class ProcessLockManager {
   /**
    * Stop periodic touching of a lock file.
    *
-   * @param lockPath - Path to the lock directory
+   * @param lockPath - Path to the lock directory.
    */
   stopTouchTimer(lockPath) {
     const timer = this.touchTimers.get(lockPath);
@@ -122,47 +110,50 @@ class ProcessLockManager {
     }
   }
   /**
-   * Check if a lock is stale based on mtime.
-   * Uses second-level granularity to avoid APFS floating-point precision issues.
-   * Aligned with npm's npx locking strategy.
+   * Check if a lock is stale based on mtime. Uses second-level granularity to
+   * avoid APFS floating-point precision issues. Aligned with npm's npx locking
+   * strategy.
+   *
+   * @param lockPath - Path to the lock directory.
+   * @param staleMs - Stale timeout in milliseconds.
    *
-   * @param lockPath - Path to the lock directory
-   * @param staleMs - Stale timeout in milliseconds
    * @returns True if lock exists and is stale
    */
   isStale(lockPath, staleMs) {
     try {
-      const stats = (/* @__PURE__ */ getFs()).statSync(lockPath, { throwIfNoEntry: false });
+      const stats = (0, import_internal.getFs)().statSync(lockPath, { throwIfNoEntry: false });
       if (!stats) {
         return false;
       }
-      return (0, import_primordials.DateNow)() - stats.mtime.getTime() > staleMs;
+      return (0, import_date.DateNow)() - stats.mtime.getTime() > staleMs;
     } catch {
       return false;
     }
   }
   /**
-   * Acquire a lock using mkdir for atomic operation.
-   * Handles stale locks and includes exit cleanup.
+   * Acquire a lock using mkdir for atomic operation. Handles stale locks and
+   * includes exit cleanup.
    *
    * This method attempts to create a lock directory atomically. If the lock
    * already exists, it checks if it's stale and removes it before retrying.
    * Uses exponential backoff with jitter for retry attempts.
    *
-   * @param lockPath - Path to the lock directory
-   * @param options - Lock acquisition options
+   * @example
+   *   ;```typescript
+   *   const release = await processLock.acquire('/tmp/my-lock')
+   *   try {
+   *     // Critical section
+   *   } finally {
+   *     release()
+   *   }
+   *   ```
+   *
+   * @param lockPath - Path to the lock directory.
+   * @param options - Lock acquisition options.
+   *
    * @returns Release function to unlock
-   * @throws Error if lock cannot be acquired after all retries
    *
-   * @example
-   * ```typescript
-   * const release = await processLock.acquire('/tmp/my-lock')
-   * try {
-   *   // Critical section
-   * } finally {
-   *   release()
-   * }
-   * ```
+   * @throws Error if lock cannot be acquired after all retries
    */
   async acquire(lockPath, options = {}) {
     const {
@@ -173,18 +164,18 @@ class ProcessLockManager {
       touchIntervalMs = 2e3
     } = options;
     this.ensureExitHandler();
-    return await (0, import_promises.pRetry)(
+    return await (0, import_retry.pRetry)(
       async () => {
         try {
           if (this.isStale(lockPath, staleMs)) {
             logger.log(`Removing stale lock: ${lockPath}`);
             try {
-              (0, import_fs.safeDeleteSync)(lockPath, { recursive: true });
+              (0, import_safe.safeDeleteSync)(lockPath, { recursive: true });
             } catch {
             }
           }
-          const fs = /* @__PURE__ */ getFs();
-          const parent = (/* @__PURE__ */ getPath()).dirname(lockPath);
+          const fs = (0, import_internal.getFs)();
+          const parent = (0, import_internal.getPath)().dirname(lockPath);
           if (parent && parent !== "." && parent !== lockPath) {
             fs.mkdirSync(parent, { recursive: true });
           }
@@ -196,29 +187,29 @@ class ProcessLockManager {
           const code = e.code;
           if (code === "EEXIST") {
             if (this.isStale(lockPath, staleMs)) {
-              throw new import_primordials.ErrorCtor(`Stale lock detected: ${lockPath}`);
+              throw new import_error.ErrorCtor(`Stale lock detected: ${lockPath}`);
             }
-            throw new import_primordials.ErrorCtor(`Lock already exists: ${lockPath}`);
+            throw new import_error.ErrorCtor(`Lock already exists: ${lockPath}`);
           }
           if (code === "EACCES" || code === "EPERM") {
-            throw new import_primordials.ErrorCtor(
+            throw new import_error.ErrorCtor(
               `Permission denied creating lock: ${lockPath}. Check directory permissions or run with appropriate access.`,
               { cause: e }
             );
           }
           if (code === "EROFS") {
-            throw new import_primordials.ErrorCtor(
+            throw new import_error.ErrorCtor(
               `Cannot create lock on read-only filesystem: ${lockPath}`,
               { cause: e }
             );
           }
           if (code === "ENOTDIR") {
-            const lastSlashIndex = (0, import_primordials.MathMax)(
+            const lastSlashIndex = (0, import_math.MathMax)(
               lockPath.lastIndexOf("/"),
               lockPath.lastIndexOf("\\")
             );
             const parentDir = lastSlashIndex === -1 ? "." : lockPath.slice(0, lastSlashIndex);
-            throw new import_primordials.ErrorCtor(
+            throw new import_error.ErrorCtor(
               `Cannot create lock directory: ${lockPath}
 A path component is a file when it should be a directory.
 Parent path: ${parentDir}
@@ -230,12 +221,12 @@ To resolve:
             );
           }
           if (code === "ENOENT") {
-            const lastSlashIndex = (0, import_primordials.MathMax)(
+            const lastSlashIndex = (0, import_math.MathMax)(
               lockPath.lastIndexOf("/"),
               lockPath.lastIndexOf("\\")
             );
             const parentDir = lastSlashIndex === -1 ? "." : lockPath.slice(0, lastSlashIndex);
-            throw new import_primordials.ErrorCtor(
+            throw new import_error.ErrorCtor(
               `Cannot create lock directory: ${lockPath}
 Parent directory does not exist: ${parentDir}
 To resolve:
@@ -245,7 +236,7 @@ To resolve:
               { cause: e }
             );
           }
-          throw new import_primordials.ErrorCtor(`Failed to acquire lock: ${lockPath}`, {
+          throw new import_error.ErrorCtor(`Failed to acquire lock: ${lockPath}`, {
             cause: e
           });
         }
@@ -259,47 +250,49 @@ To resolve:
     );
   }
   /**
-   * Release a lock and remove from tracking.
-   * Stops periodic touching and removes the lock directory.
-   *
-   * @param lockPath - Path to the lock directory
+   * Release a lock and remove from tracking. Stops periodic touching and
+   * removes the lock directory.
    *
    * @example
-   * ```typescript
-   * processLock.release('/tmp/my-lock')
-   * ```
+   *   ;```typescript
+   *   processLock.release('/tmp/my-lock')
+   *   ```
+   *
+   * @param lockPath - Path to the lock directory.
    */
   release(lockPath) {
     this.stopTouchTimer(lockPath);
     try {
-      if ((/* @__PURE__ */ getFs()).existsSync(lockPath)) {
-        (0, import_fs.safeDeleteSync)(lockPath, { recursive: true });
+      if ((0, import_internal.getFs)().existsSync(lockPath)) {
+        (0, import_safe.safeDeleteSync)(lockPath, { recursive: true });
       }
       this.activeLocks.delete(lockPath);
     } catch (e) {
-      logger.warn(`Failed to release lock ${lockPath}: ${(0, import_errors.errorMessage)(e)}`);
+      logger.warn(`Failed to release lock ${lockPath}: ${(0, import_message.errorMessage)(e)}`);
     }
   }
   /**
-   * Execute a function with exclusive lock protection.
-   * Automatically handles lock acquisition, execution, and cleanup.
+   * Execute a function with exclusive lock protection. Automatically handles
+   * lock acquisition, execution, and cleanup.
    *
-   * This is the recommended way to use process locks, as it guarantees
-   * cleanup even if the callback throws an error.
+   * This is the recommended way to use process locks, as it guarantees cleanup
+   * even if the callback throws an error.
+   *
+   * @example
+   *   ;```typescript
+   *   const result = await processLock.withLock('/tmp/my-lock', async () => {
+   *     // Critical section
+   *     return someValue
+   *   })
+   *   ```
+   *
+   * @param lockPath - Path to the lock directory.
+   * @param fn - Function to execute while holding the lock.
+   * @param options - Lock acquisition options.
    *
-   * @param lockPath - Path to the lock directory
-   * @param fn - Function to execute while holding the lock
-   * @param options - Lock acquisition options
    * @returns Result of the callback function
-   * @throws Error from callback or lock acquisition failure
    *
-   * @example
-   * ```typescript
-   * const result = await processLock.withLock('/tmp/my-lock', async () => {
-   *   // Critical section
-   *   return someValue
-   * })
-   * ```
+   * @throws Error from callback or lock acquisition failure
    */
   async withLock(lockPath, fn, options) {
     const release = await this.acquire(lockPath, options);
@@ -310,8 +303,7 @@ To resolve:
     }
   }
 }
-const processLock = new ProcessLockManager();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  processLock
+  ProcessLockManager
 });

package/dist/process/lock-types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file Public type surface for `process/lock-*` modules — the
+ *   `ProcessLockOptions` bag accepted by `processLock.acquire` and
+ *   `processLock.withLock`. Pure types, no runtime side effects.
+ */
+/**
+ * Lock acquisition options.
+ */
+export interface ProcessLockOptions {
+    /**
+     * Maximum number of retry attempts.
+     *
+     * @default 3
+     */
+    retries?: number | undefined;
+    /**
+     * Base delay between retries in milliseconds.
+     *
+     * @default 100
+     */
+    baseDelayMs?: number | undefined;
+    /**
+     * Maximum delay between retries in milliseconds.
+     *
+     * @default 1000
+     */
+    maxDelayMs?: number | undefined;
+    /**
+     * Stale lock timeout in milliseconds. Locks older than this are considered
+     * abandoned and can be reclaimed. Aligned with npm's npx locking strategy (5
+     * seconds).
+     *
+     * @default 5000 (5 seconds)
+     */
+    staleMs?: number | undefined;
+    /**
+     * Interval for touching lock file to keep it fresh in milliseconds. Set to 0
+     * to disable periodic touching.
+     *
+     * @default 2000 (2 seconds)
+     */
+    touchIntervalMs?: number | undefined;
+}

package/dist/process/lock-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 lock_types_exports = {};
+module.exports = __toCommonJS(lock_types_exports);

package/dist/process/spawn/_internal.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file Private internals for `spawn/*` modules — the `@npmcli/promise-spawn`
+ *   lazy loader, the per-spawn ANSI-stripping helper, the WeakMap stack cache,
+ *   and the binary-path cache shared between `spawn` and `spawnSync`.
+ *   Underscore prefix excludes this file from the public exports map.
+ */
+export declare const stackCache: WeakMap<Error, string>;
+export declare const spawnBinPathCache: Map<string, string>;
+export declare const windowsScriptExtRegExp: RegExp;
+/**
+ * Lazily load the `@npmcli/promise-spawn` module to avoid Webpack bundling
+ * issues. Required because the upstream module uses CJS dynamic-require
+ * patterns that Webpack flags.
+ */
+export declare function getNpmCliPromiseSpawn(): any;
+/**
+ * Strip ANSI escape codes from spawn result stdout and stderr. Modifies the
+ * result object in place to remove color codes and formatting.
+ *
+ * @param {unknown} result - Spawn result object with stdout/stderr properties.
+ *
+ * @returns {unknown} The modified result object
+ */
+export declare function stripAnsiFromSpawnResult(result: unknown): unknown;

package/dist/process/spawn/_internal.js

@@ -0,0 +1,62 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  getNpmCliPromiseSpawn: () => getNpmCliPromiseSpawn,
+  spawnBinPathCache: () => spawnBinPathCache,
+  stackCache: () => stackCache,
+  stripAnsiFromSpawnResult: () => stripAnsiFromSpawnResult,
+  windowsScriptExtRegExp: () => windowsScriptExtRegExp
+});
+module.exports = __toCommonJS(internal_exports);
+var import_strip = require("../../ansi/strip");
+var import_map_set = require("../../primordials/map-set");
+const stackCache = new import_map_set.WeakMapCtor();
+const spawnBinPathCache = new import_map_set.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_strip.stripAnsi)(stdout);
+  }
+  if (typeof stderr === "string") {
+    res.stderr = (0, import_strip.stripAnsi)(stderr);
+  }
+  return res;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getNpmCliPromiseSpawn,
+  spawnBinPathCache,
+  stackCache,
+  stripAnsiFromSpawnResult,
+  windowsScriptExtRegExp
+});

package/dist/process/spawn/child.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @file Child process spawning utilities with cross-platform support. Provides
+ *   enhanced spawn functionality with stdio handling and error management.
+ *   SECURITY: Array-Based Arguments Prevent Command Injection This module uses
+ *   array-based arguments for all command execution, which is the PRIMARY
+ *   DEFENSE against command injection attacks. When you pass arguments as an
+ *   array to spawn(): spawn('npx', ['sfw', tool, ...args], { shell: true })
+ *   Node.js handles escaping automatically. Each argument is passed directly to
+ *   the OS without shell interpretation. Shell metacharacters like ; | & $ ( )
+ *   ` are treated as LITERAL STRINGS, not as commands. This approach is secure
+ *   even when shell: true is used on Windows for .cmd/.bat file resolution.
+ *   UNSAFE ALTERNATIVE (not used in this codebase): spawn(`npx sfw ${tool}
+ *   ${args.join(' ')}`, { shell: true }) // ✖ VULNERABLE String concatenation
+ *   allows injection. For example, if tool = "foo; rm -rf /", the shell would
+ *   execute both commands. Array-based arguments prevent this. References:
+ *
+ *   - https://nodejs.org/api/child_process.html#child_processspawncommand-args-options
+ *   - https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html
+ */
+import type { BufferEncoding, SpawnExtra, SpawnOptions, SpawnResult, SpawnSyncOptions, SpawnSyncReturns } from './types';
+/**
+ * Spawn a child process and return a promise that resolves when it completes.
+ * Provides enhanced error handling, output capture, and cross-platform
+ * support.
+ *
+ * SECURITY: This function uses array-based arguments which prevent command
+ * injection. Arguments in the `args` array are passed directly to the OS
+ * without shell interpretation. Shell metacharacters (;|&$()`) are treated as
+ * literal strings, not as commands or operators. This is the PRIMARY SECURITY
+ * DEFENSE.
+ *
+ * Even when shell: true is used (on Windows for .cmd/.bat execution), the
+ * array-based approach remains secure because Node.js properly escapes each
+ * argument before passing to the shell.
+ *
+ * @param {string} cmd - Command to execute (not user-controlled) @param
+ * {string[] | readonly string[] | undefined} args - Array of arguments (safe
+ * even with user input) @param {SpawnOptions | undefined} options - Spawn
+ * options for process configuration @param {SpawnExtra | undefined} extra -
+ * Extra options for promise-spawn @returns {SpawnResult} Promise that resolves
+ * with process exit information.
+ *
+ * @throws {SpawnError} When the process exits with non-zero code or is
+ * terminated by signal.
+ *
+ * @example // Basic usage - spawn and wait for completion const result = await
+ * spawn('git', ['status']) console.log(result.stdout)
+ *
+ * @example // With options - set working directory and environment const result
+ * = await spawn('npm', ['install'], { cwd: '/path/to/project', env: { NODE_ENV:
+ * 'production' } })
+ *
+ * @example // ✔ DO THIS - Array-based arguments (safe) spawn('git', ['commit',
+ * '-m', userMessage]) // Each argument is properly escaped, even if userMessage
+ * = "foo; rm -rf /"
+ *
+ * @example // ✖ NEVER DO THIS - String concatenation (vulnerable) spawn(`git
+ * commit -m "${userMessage}"`, { shell: true }) // Vulnerable to injection if
+ * userMessage = '"; rm -rf / #'
+ *
+ * @example // Access stdin for interactive processes const result =
+ * spawn('cat', []) result.stdin?.write('Hello\n') result.stdin?.end() const {
+ * stdout } = await result console.log(stdout) // 'Hello'
+ *
+ * @example // Handle errors with exit codes try { await spawn('exit', ['1']) }
+ * catch (e) { if (isSpawnError(e)) { console.error(`Failed with code
+ * ${e.code}`) console.error(e.stderr) } }
+ */
+export declare function spawn(cmd: string, args?: string[] | readonly string[]): SpawnResult<string>;
+export declare function spawn(cmd: string, args: string[] | readonly string[] | undefined, options: SpawnOptions & {
+    stdioString?: true | undefined;
+}, extra?: SpawnExtra | undefined): SpawnResult<string>;
+export declare function spawn(cmd: string, args: string[] | readonly string[] | undefined, options: SpawnOptions & {
+    stdioString: false;
+}, extra?: SpawnExtra | undefined): SpawnResult<Buffer>;
+export declare function spawn(cmd: string, args?: string[] | readonly string[], options?: SpawnOptions | undefined, extra?: SpawnExtra | undefined): SpawnResult;
+/**
+ * Synchronously spawn a child process and wait for it to complete. Blocks
+ * execution until the process exits, returning all output and exit
+ * information.
+ *
+ * WARNING: This function blocks the event loop. Use {@link spawn} for async
+ * operations.
+ *
+ * @example
+ *   // Basic synchronous spawn
+ *   const result = spawnSync('git', ['status'])
+ *   console.log(result.stdout)
+ *   console.log(result.status) // exit code
+ *
+ * @example
+ *   // With options
+ *   const result = spawnSync('npm', ['install'], {
+ *     cwd: '/path/to/project',
+ *     stdioString: true,
+ *   })
+ *   if (result.status !== 0) {
+ *     console.error(result.stderr)
+ *   }
+ *
+ * @example
+ *   // Get raw buffer output
+ *   const result = spawnSync('cat', ['binary-file'], {
+ *     stdioString: false,
+ *   })
+ *   console.log(result.stdout) // Buffer
+ *
+ * @example
+ *   // Handle process errors
+ *   const result = spawnSync('nonexistent-command')
+ *   if (result.error) {
+ *     console.error('Failed to spawn:', result.error)
+ *   }
+ *
+ * @param {string} cmd - Command to execute.
+ * @param {string[] | readonly string[] | undefined} args - Array of arguments.
+ * @param {SpawnSyncOptions | undefined} options - Spawn options for process
+ *   configuration.
+ *
+ * @returns {SpawnSyncReturns<string | Buffer>} Process result with exit code
+ *   and captured output.
+ */
+export declare function spawnSync(cmd: string, args?: string[] | readonly string[]): SpawnSyncReturns<string>;
+export declare function spawnSync(cmd: string, args: string[] | readonly string[] | undefined, options: SpawnSyncOptions & {
+    stdioString?: true | undefined;
+    encoding?: Exclude<BufferEncoding, never> | undefined;
+}): SpawnSyncReturns<string>;
+export declare function spawnSync(cmd: string, args: string[] | readonly string[] | undefined, options: SpawnSyncOptions & {
+    stdioString: false;
+}): SpawnSyncReturns<Buffer>;
+export declare function spawnSync(cmd: string, args: string[] | readonly string[] | undefined, options: SpawnSyncOptions & {
+    encoding: 'buffer' | null;
+}): SpawnSyncReturns<Buffer>;
+export declare function spawnSync(cmd: string, args?: string[] | readonly string[], options?: SpawnSyncOptions | undefined): SpawnSyncReturns<string | Buffer>;