@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/process/spawn/child.js

@@ -0,0 +1,216 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var child_exports = {};
+__export(child_exports, {
+  spawn: () => spawn,
+  spawnSync: () => spawnSync
+});
+module.exports = __toCommonJS(child_exports);
+var import_node_process = __toESM(require("node: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_default = require("../../spinner/default");
+var import_internal = require("./_internal");
+var import_errors = require("./errors");
+var import_stdio = require("./stdio");
+const abortSignal = (0, import_abort.getAbortSignal)();
+const spinner = (0, import_default.getDefaultSpinner)();
+function spawn(cmd, args, options, extra) {
+  const {
+    spinner: optionsSpinner = spinner,
+    stripAnsi: shouldStripAnsi = true,
+    ...rawSpawnOptions
+  } = { __proto__: null, ...options };
+  const spinnerInstance = optionsSpinner;
+  const spawnOptions = { __proto__: null, ...rawSpawnOptions };
+  const { env, shell, stdio, stdioString = true } = spawnOptions;
+  const cwd = spawnOptions.cwd ? String(spawnOptions.cwd) : void 0;
+  let actualCmd = cmd;
+  if (!(0, import_normalize.isPath)(cmd)) {
+    const fs = (0, import_fs.getNodeFs)();
+    const cached = import_internal.spawnBinPathCache.get(cmd);
+    if (cached) {
+      if (fs.existsSync(cached)) {
+        actualCmd = cached;
+      } else {
+        import_internal.spawnBinPathCache.delete(cmd);
+      }
+    }
+    if (actualCmd === cmd) {
+      const resolved = (0, import_which.whichSync)(cmd, { cwd, nothrow: true });
+      if (resolved && typeof resolved === "string") {
+        actualCmd = resolved;
+        import_internal.spawnBinPathCache.set(cmd, resolved);
+      }
+    }
+  }
+  const WIN32 = import_node_process.default.platform === "win32";
+  if (WIN32 && shell && (0, import_regexp.RegExpPrototypeTest)(import_internal.windowsScriptExtRegExp, actualCmd)) {
+    if (!(0, import_normalize.isPath)(actualCmd)) {
+      actualCmd = (0, import_path.getNodePath)().basename(
+        actualCmd,
+        (0, import_path.getNodePath)().extname(actualCmd)
+      );
+    }
+  }
+  const wasSpinning = !!spinnerInstance?.isSpinning;
+  const shouldStopSpinner = wasSpinning && !(0, import_stdio.isStdioType)(stdio, "ignore") && !(0, import_stdio.isStdioType)(stdio, "pipe");
+  const shouldRestartSpinner = shouldStopSpinner;
+  if (shouldStopSpinner) {
+    spinnerInstance.stop();
+  }
+  const envToUse = env ? {
+    __proto__: null,
+    ...import_node_process.default.env,
+    ...env
+  } : import_node_process.default.env;
+  const promiseSpawnOpts = {
+    __proto__: null,
+    cwd: typeof spawnOptions.cwd === "string" ? spawnOptions.cwd : void 0,
+    env: envToUse,
+    signal: abortSignal,
+    stdio: spawnOptions.stdio,
+    stdioString,
+    shell: spawnOptions.shell,
+    windowsVerbatimArguments: spawnOptions.windowsVerbatimArguments,
+    timeout: spawnOptions.timeout,
+    uid: spawnOptions.uid,
+    gid: spawnOptions.gid
+  };
+  const npmCliPromiseSpawn = (0, import_internal.getNpmCliPromiseSpawn)();
+  const spawnPromise = npmCliPromiseSpawn(
+    actualCmd,
+    args ? [...args] : [],
+    promiseSpawnOpts,
+    extra
+  );
+  const oldSpawnPromise = spawnPromise;
+  let newSpawnPromise;
+  if (shouldStripAnsi && stdioString) {
+    newSpawnPromise = (async () => {
+      try {
+        const result = await spawnPromise;
+        const strippedResult = (0, import_internal.stripAnsiFromSpawnResult)(result);
+        if ("code" in strippedResult) {
+          ;
+          strippedResult.exitCode = strippedResult.code;
+        }
+        return strippedResult;
+      } catch (error) {
+        const strippedError = (0, import_internal.stripAnsiFromSpawnResult)(error);
+        throw (0, import_errors.enhanceSpawnError)(strippedError);
+      }
+    })();
+  } else {
+    newSpawnPromise = (async () => {
+      try {
+        const result = await spawnPromise;
+        if (result !== null && typeof result === "object" && "code" in result) {
+          const res = result;
+          res.exitCode = res.code;
+          return res;
+        }
+        return result;
+      } catch (error) {
+        throw (0, import_errors.enhanceSpawnError)(error);
+      }
+    })();
+  }
+  if (shouldRestartSpinner) {
+    const prevPromise = newSpawnPromise;
+    newSpawnPromise = (async () => {
+      try {
+        return await prevPromise;
+      } finally {
+        spinnerInstance.start();
+      }
+    })();
+  }
+  ;
+  newSpawnPromise.process = oldSpawnPromise.process;
+  newSpawnPromise.stdin = oldSpawnPromise.stdin;
+  return newSpawnPromise;
+}
+function spawnSync(cmd, args, options) {
+  let actualCmd = cmd;
+  if (!(0, import_normalize.isPath)(cmd)) {
+    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_inspect.getOwn)(options, "shell");
+  const WIN32 = import_node_process.default.platform === "win32";
+  if (WIN32 && shell && (0, import_regexp.RegExpPrototypeTest)(import_internal.windowsScriptExtRegExp, actualCmd)) {
+    if (!(0, import_normalize.isPath)(actualCmd)) {
+      actualCmd = (0, import_path.getNodePath)().basename(
+        actualCmd,
+        (0, import_path.getNodePath)().extname(actualCmd)
+      );
+    }
+  }
+  const { stripAnsi: shouldStripAnsi = true, ...rawSpawnOptions } = {
+    __proto__: null,
+    ...options
+  };
+  const { stdioString: rawStdioString = true } = rawSpawnOptions;
+  const rawEncoding = rawStdioString ? "utf8" : "buffer";
+  const spawnOptions = {
+    encoding: rawEncoding,
+    ...rawSpawnOptions
+  };
+  const stdioString = spawnOptions.encoding !== "buffer";
+  const result = (0, import_child_process.getNodeChildProcess)().spawnSync(actualCmd, args, spawnOptions);
+  if (stdioString) {
+    const { stderr, stdout } = result;
+    if (stdout) {
+      result.stdout = stdout.toString().trim();
+    }
+    if (stderr) {
+      result.stderr = stderr.toString().trim();
+    }
+  }
+  return shouldStripAnsi && stdioString ? (0, import_internal.stripAnsiFromSpawnResult)(result) : result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  spawn,
+  spawnSync
+});

package/dist/process/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/process/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/process/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/process/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
+});