@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/sorts/natural.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Locale-aware + numeric-aware comparison via `Intl.Collator`, plus the
+ *   `naturalSorter` helper that wires the fast-sort engine to the natural
+ *   comparator. Collator instances are lazy-created and cached because `new
+ *   Intl.Collator()` is 10-14ms in Node — too expensive to call
+ *   per-comparison.
+ */
+import type { FastSortFunction } from './types';
+/**
+ * Compare two strings using locale-aware comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   localeCompare('a', 'b') // -1
+ *   localeCompare('b', 'a') // 1
+ *   localeCompare('a', 'a') // 0
+ *   ```
+ */
+export declare function localeCompare(x: string, y: string): number;
+/**
+ * Compare two strings using natural sorting (numeric-aware, case-insensitive).
+ *
+ * @example
+ *   ;```typescript
+ *   naturalCompare('file2', 'file10') // negative (file2 before file10)
+ *   naturalCompare('img10', 'img2') // positive (img10 after img2)
+ *   ```
+ */
+export declare function naturalCompare(x: string, y: string): number;
+/**
+ * Sort an array using natural comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   naturalSorter(['file10', 'file2', 'file1']).asc()
+ *   // ['file1', 'file2', 'file10']
+ *   ```
+ */
+export declare function naturalSorter<T>(arrayToSort: T[]): ReturnType<FastSortFunction>;

package/dist/{sorts.js → sorts/natural.js}

@@ -18,52 +18,17 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var sorts_exports = {};
-__export(sorts_exports, {
-  compareSemver: () => compareSemver,
-  compareStr: () => compareStr,
+var natural_exports = {};
+__export(natural_exports, {
   localeCompare: () => localeCompare,
   naturalCompare: () => naturalCompare,
   naturalSorter: () => naturalSorter
 });
-module.exports = __toCommonJS(sorts_exports);
-let _fastSort;
+module.exports = __toCommonJS(natural_exports);
+var import_internal = require("./_internal");
 let _localeCompare;
 let _naturalCompare;
 let _naturalSorter;
-let _semver;
-function getFastSort() {
-  if (_fastSort === void 0) {
-    _fastSort = require("./external/fast-sort.js");
-  }
-  return _fastSort;
-}
-function getSemver() {
-  if (_semver === void 0) {
-    _semver = require("./external/semver.js");
-  }
-  return _semver;
-}
-// @__NO_SIDE_EFFECTS__
-function compareSemver(a, b) {
-  const semver = getSemver();
-  const validA = semver.valid(a);
-  const validB = semver.valid(b);
-  if (!validA && !validB) {
-    return 0;
-  }
-  if (!validA) {
-    return -1;
-  }
-  if (!validB) {
-    return 1;
-  }
-  return semver.compare(a, b);
-}
-// @__NO_SIDE_EFFECTS__
-function compareStr(a, b) {
-  return a < b ? -1 : a > b ? 1 : 0;
-}
 // @__NO_SIDE_EFFECTS__
 function localeCompare(x, y) {
   if (_localeCompare === void 0) {
@@ -94,7 +59,7 @@ function naturalCompare(x, y) {
 // @__NO_SIDE_EFFECTS__
 function naturalSorter(arrayToSort) {
   if (_naturalSorter === void 0) {
-    const fastSort = getFastSort();
+    const fastSort = (0, import_internal.getFastSort)();
     _naturalSorter = fastSort.createNewSortInstance({
       comparer: naturalCompare
     });
@@ -103,8 +68,6 @@ function naturalSorter(arrayToSort) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  compareSemver,
-  compareStr,
   localeCompare,
   naturalCompare,
   naturalSorter

package/dist/sorts/semver.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Semver-aware string comparison. Wraps the vendored `external/semver`
+ *   accessor so callers don't have to thread the lazy-load themselves.
+ */
+/**
+ * Compare semantic versions.
+ *
+ * @example
+ *   ;```typescript
+ *   compareSemver('1.0.0', '2.0.0') // -1
+ *   compareSemver('2.0.0', '1.0.0') // 1
+ *   compareSemver('1.0.0', '1.0.0') // 0
+ *   ```
+ */
+export declare function compareSemver(a: string, b: string): number;

package/dist/sorts/semver.js

@@ -0,0 +1,46 @@
+"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 semver_exports = {};
+__export(semver_exports, {
+  compareSemver: () => compareSemver
+});
+module.exports = __toCommonJS(semver_exports);
+var import_internal = require("./_internal");
+// @__NO_SIDE_EFFECTS__
+function compareSemver(a, b) {
+  const semver = (0, import_internal.getSemver)();
+  const validA = semver.valid(a);
+  const validB = semver.valid(b);
+  if (!validA && !validB) {
+    return 0;
+  }
+  if (!validA) {
+    return -1;
+  }
+  if (!validB) {
+    return 1;
+  }
+  return semver.compare(a, b);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compareSemver
+});

package/dist/sorts/strings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Plain string comparison. The straight-ASCII three-way compare, no
+ *   locale/numeric awareness — use `localeCompare` / `naturalCompare` from the
+ *   sibling files when those matter.
+ */
+/**
+ * Simple string comparison.
+ *
+ * @example
+ *   ;```typescript
+ *   compareStr('a', 'b') // -1
+ *   compareStr('b', 'a') // 1
+ *   compareStr('a', 'a') // 0
+ *   ```
+ */
+export declare function compareStr(a: string, b: string): number;

package/dist/sorts/strings.js

@@ -0,0 +1,33 @@
+"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 strings_exports = {};
+__export(strings_exports, {
+  compareStr: () => compareStr
+});
+module.exports = __toCommonJS(strings_exports);
+// @__NO_SIDE_EFFECTS__
+function compareStr(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compareStr
+});

package/dist/sorts/types.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Public type surface for `sorts/*` modules — the `FastSortFunction`
+ *   shape returned by `naturalSorter`. Pure types, no runtime side effects.
+ */
+import type * as fastSortType from '../external/fast-sort';
+export type FastSortFunction = ReturnType<typeof import('fast-sort').createNewSortInstance>;
+export type { fastSortType };

package/dist/sorts/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);

package/dist/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/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/spawn/errors.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Spawn error classification and enhancement. `isSpawnError` is a
+ *   type-guard for shaping unknown errors that crossed an `await spawn(...)`.
+ *   It checks for the `code` / `errno` / `syscall` properties that Node's
+ *   child_process tags onto `ENOENT` / `EACCES` / process-exit failures.
+ *   `enhanceSpawnError` rewrites the upstream `@npmcli/promise-spawn` "command
+ *   failed" placeholder message into something the operator can actually act
+ *   on: command + args (truncated at 100 chars), exit code or signal, and the
+ *   first stderr line (truncated at 200 chars). The stack is computed lazily on
+ *   first access via a per-error WeakMap so non-error paths don't pay the
+ *   `stackWithCauses` cost.
+ */
+import type { SpawnError } from './types';
+/**
+ * Enhances spawn error with better context. Converts generic "command failed"
+ * to detailed error with command, exit code, and stderr.
+ *
+ * @example
+ *   ;```typescript
+ *   try {
+ *     await spawn('git', ['status'])
+ *   } catch (e) {
+ *     throw enhanceSpawnError(e)
+ *   }
+ *   ```
+ */
+export declare function enhanceSpawnError(error: unknown): unknown;
+/**
+ * Check if a value is a spawn error with expected error properties. Tests for
+ * common error properties from child process failures.
+ *
+ * @example
+ *   try {
+ *     await spawn('nonexistent-command')
+ *   } catch (e) {
+ *     if (isSpawnError(e)) {
+ *       console.error(`Spawn failed: ${e.code}`)
+ *     }
+ *   }
+ *
+ * @param {unknown} value - Value to check.
+ *
+ * @returns {boolean} `true` if the value has spawn error properties
+ */
+export declare function isSpawnError(value: unknown): value is SpawnError;

package/dist/spawn/errors.js

@@ -0,0 +1,118 @@
+"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 errors_exports = {};
+__export(errors_exports, {
+  enhanceSpawnError: () => enhanceSpawnError,
+  isSpawnError: () => isSpawnError
+});
+module.exports = __toCommonJS(errors_exports);
+var import_stack = require("../errors/stack");
+var import_predicates = require("../objects/predicates");
+var import_error = require("../primordials/error");
+var import_object = require("../primordials/object");
+var import_reflect = require("../primordials/reflect");
+var import_internal = require("./_internal");
+// @__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_object.ObjectDefineProperty)(err, "message", {
+      __proto__: null,
+      value: enhancedMessage,
+      writable: true,
+      enumerable: false,
+      configurable: true
+    });
+    return err;
+  }
+  const enhancedError = new import_error.ErrorCtor(enhancedMessage, {
+    cause: err
+  });
+  const descriptors = (0, import_object.ObjectGetOwnPropertyDescriptors)(err);
+  (0, import_reflect.ReflectDeleteProperty)(descriptors, "message");
+  (0, import_reflect.ReflectDeleteProperty)(descriptors, "stack");
+  (0, import_object.ObjectDefineProperties)(enhancedError, descriptors);
+  (0, import_object.ObjectDefineProperty)(enhancedError, "stack", {
+    __proto__: null,
+    configurable: true,
+    enumerable: false,
+    get() {
+      let stack = import_internal.stackCache.get(enhancedError);
+      if (stack === void 0) {
+        try {
+          stack = (0, import_stack.stackWithCauses)(err);
+        } catch {
+          stack = err.stack ?? new import_error.ErrorCtor().stack ?? "";
+        }
+        import_internal.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_predicates.hasOwn)(err, "code") && typeof err["code"] !== "undefined" || (0, import_predicates.hasOwn)(err, "errno") && typeof err["errno"] !== "undefined" || (0, import_predicates.hasOwn)(err, "syscall") && typeof err["syscall"] === "string";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  enhanceSpawnError,
+  isSpawnError
+});

package/dist/spawn/spawn.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>;