@socketsecurity/lib 0.0.0 → 1.0.0

package/dist/spawn.d.ts

@@ -0,0 +1,207 @@
+// Define BufferEncoding type for TypeScript compatibility.
+type BufferEncoding = globalThis.BufferEncoding;
+// Type for promise-spawn options.
+export type PromiseSpawnOptions = {
+    cwd?: string | undefined;
+    stdioString?: boolean | undefined;
+    stdio?: StdioType | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    shell?: boolean | string | undefined;
+    signal?: AbortSignal | undefined;
+    timeout?: number | undefined;
+    uid?: number | undefined;
+    gid?: number | undefined;
+};
+// Type for promise-spawn result.
+export type PromiseSpawnResult = Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+}> & {
+    process: ChildProcessType;
+    stdin: WritableStreamType | null;
+};
+/**
+ * Check if a value is a spawn error.
+ */
+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;
+};
+export type SpawnErrorWithOutputString = SpawnError & {
+    stdout: string;
+    stderr: string;
+};
+export type SpawnErrorWithOutputBuffer = SpawnError & {
+    stdout: Buffer;
+    stderr: Buffer;
+};
+export type SpawnExtra = Record<string, unknown>;
+export type IOType = 'pipe' | 'ignore' | 'inherit' | 'overlapped';
+export type StdioType = IOType | 'ipc' | Array<IOType | 'ipc'>;
+export interface SpawnSyncReturns<T> {
+    pid: number;
+    output: Array<T | null>;
+    stdout: T;
+    stderr: T;
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    error?: Error | undefined;
+}
+/**
+ * Check if a value is a spawn error with expected properties.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isSpawnError(value: unknown): value is SpawnError;
+/**
+ * Check if stdio configuration matches a specific type.
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isStdioType(stdio: string | string[], type?: StdioType | undefined): boolean;
+/*@__NO_SIDE_EFFECTS__*/
+// Duplicated from Node.js child_process.SpawnOptions
+// These are the options passed to child_process.spawn()
+interface NodeSpawnOptions {
+    cwd?: string | URL | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    argv0?: string | undefined;
+    // biome-ignore lint/suspicious/noExplicitAny: Stdio can be complex union of types from Node.js.
+    stdio?: any;
+    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;
+}
+// Duplicated from Node.js child_process.ChildProcess
+// This represents a spawned child process
+interface ChildProcessType {
+    stdin: NodeJS.WritableStream | null;
+    stdout: NodeJS.ReadableStream | null;
+    stderr: NodeJS.ReadableStream | null;
+    // biome-ignore lint/suspicious/noExplicitAny: IPC channel type from Node.js.
+    readonly channel?: any;
+    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;
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message type from Node.js.
+    send(message: any, callback?: (error: Error | null) => void): boolean;
+    send(
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message and handle types from Node.js.
+    message: any, 
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message and handle types from Node.js.
+    sendHandle?: any | undefined, callback?: (error: Error | null) => void): boolean;
+    send(
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.
+    message: any, 
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.
+    sendHandle?: any | undefined, 
+    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.
+    options?: any | undefined, callback?: (error: Error | null) => void): boolean;
+    disconnect(): void;
+    unref(): void;
+    ref(): void;
+}
+// Duplicated from Node.js stream.Writable
+interface WritableStreamType {
+    writable: boolean;
+    writableEnded: boolean;
+    writableFinished: boolean;
+    writableHighWaterMark: number;
+    writableLength: number;
+    writableObjectMode: boolean;
+    writableCorked: number;
+    destroyed: boolean;
+    write(
+    // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.
+    chunk: any, encoding?: BufferEncoding | undefined, callback?: (error?: Error | null) => void): boolean;
+    // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.
+    write(chunk: any, callback?: (error?: Error | null) => void): boolean;
+    end(cb?: () => void): this;
+    // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.
+    end(chunk: any, cb?: () => void): this;
+    // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.
+    end(chunk: any, encoding?: BufferEncoding | undefined, cb?: () => void): this;
+    cork(): void;
+    uncork(): void;
+    destroy(error?: Error | undefined): this;
+}
+/**
+ * Spawn a child process with enhanced error handling and output capture.
+ */
+export type SpawnOptions = import('./objects').Remap<NodeSpawnOptions & {
+    spinner?: import('./spinner').Spinner | undefined;
+    stdioString?: boolean;
+    stripAnsi?: boolean;
+}>;
+export type SpawnResult = PromiseSpawnResult;
+export type SpawnStdioResult = {
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+};
+/**
+ * Spawn a child process and return a promise that resolves when it completes.
+ *
+ * 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 cmd - Command to execute (not user-controlled)
+ * @param args - Array of arguments (safe even with user input due to array-based passing)
+ * @param options - Spawn options
+ * @param extra - Extra options for promise-spawn
+ *
+ * @example
+ * // ✔ DO THIS - Array-based arguments
+ * spawn('git', ['commit', '-m', userMessage])
+ * // Each argument is properly escaped, even if userMessage = "foo; rm -rf /"
+ *
+ * @example
+ * // ✖ NEVER DO THIS - String concatenation
+ * spawn(`git commit -m "${userMessage}"`, { shell: true })
+ * // Vulnerable to injection if userMessage = '"; rm -rf / #'
+ */
+export declare function spawn(cmd: string, args?: string[] | readonly string[], options?: SpawnOptions | undefined, extra?: SpawnExtra | undefined): SpawnResult;
+/*@__NO_SIDE_EFFECTS__*/
+/**
+ * Synchronously spawn a child process.
+ */
+export type SpawnSyncOptions = Omit<SpawnOptions, 'spinner'>;
+export declare function spawnSync(cmd: string, args?: string[] | readonly string[], options?: SpawnSyncOptions | undefined): SpawnSyncReturns<string | Buffer>;
+export {};

package/dist/spawn.js

@@ -0,0 +1,201 @@
+/* Socket Lib - Built with esbuild */
+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 spawn_exports = {};
+__export(spawn_exports, {
+  isSpawnError: () => isSpawnError,
+  isStdioType: () => isStdioType,
+  spawn: () => spawn,
+  spawnSync: () => spawnSync
+});
+module.exports = __toCommonJS(spawn_exports);
+var import_process = require("#constants/process");
+var import_arrays = require("./arrays");
+var import_objects = require("./objects");
+var import_strings = require("./strings");
+const abortSignal = (0, import_process.getAbortSignal)();
+const spinner = (0, import_process.getSpinner)();
+const windowsScriptExtRegExp = /\.(?:cmd|bat|ps1)$/i;
+let _child_process;
+// @__NO_SIDE_EFFECTS__
+function getChildProcess() {
+  if (_child_process === void 0) {
+    _child_process = require("node:child_process");
+  }
+  return _child_process;
+}
+let _npmCliPromiseSpawn;
+// @__NO_SIDE_EFFECTS__
+function getNpmcliPromiseSpawn() {
+  if (_npmCliPromiseSpawn === void 0) {
+    _npmCliPromiseSpawn = require("../external/@npmcli/promise-spawn");
+  }
+  return _npmCliPromiseSpawn;
+}
+let _path;
+// @__NO_SIDE_EFFECTS__
+function getPath() {
+  if (_path === void 0) {
+    _path = require("node:path");
+  }
+  return _path;
+}
+// @__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;
+}
+// @__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;
+}
+function spawn(cmd, args, options, extra) {
+  const shell = (0, import_objects.getOwn)(options, "shell");
+  const WIN32 = process.platform === "win32";
+  let actualCmd = cmd;
+  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {
+    const path = /* @__PURE__ */ getPath();
+    actualCmd = path.basename(actualCmd, path.extname(actualCmd));
+  }
+  const {
+    spinner: optionsSpinner = spinner,
+    stripAnsi: shouldStripAnsi = true,
+    ...spawnOptions
+  } = { __proto__: null, ...options };
+  const spinnerInstance = optionsSpinner;
+  const { env, stdio, stdioString = true } = spawnOptions;
+  const wasSpinning = !!spinnerInstance?.isSpinning;
+  const shouldStopSpinner = wasSpinning && !/* @__PURE__ */ isStdioType(stdio, "ignore") && !/* @__PURE__ */ isStdioType(stdio, "pipe");
+  const shouldRestartSpinner = shouldStopSpinner;
+  if (shouldStopSpinner) {
+    spinnerInstance.stop();
+  }
+  const npmCliPromiseSpawn = /* @__PURE__ */ getNpmcliPromiseSpawn();
+  const promiseSpawnOpts = {
+    __proto__: null,
+    cwd: typeof spawnOptions.cwd === "string" ? spawnOptions.cwd : void 0,
+    env: {
+      __proto__: null,
+      ...process.env,
+      ...env
+    },
+    signal: abortSignal,
+    stdio: spawnOptions.stdio,
+    stdioString,
+    shell: spawnOptions.shell,
+    timeout: spawnOptions.timeout,
+    uid: spawnOptions.uid,
+    gid: spawnOptions.gid
+  };
+  const spawnPromise = npmCliPromiseSpawn(
+    actualCmd,
+    args ? [...args] : [],
+    promiseSpawnOpts,
+    extra
+  );
+  const oldSpawnPromise = spawnPromise;
+  let newSpawnPromise;
+  if (shouldStripAnsi && stdioString) {
+    newSpawnPromise = spawnPromise.then((result) => {
+      const strippedResult = /* @__PURE__ */ stripAnsiFromSpawnResult(result);
+      if ("code" in strippedResult) {
+        ;
+        strippedResult.exitCode = strippedResult.code;
+      }
+      return strippedResult;
+    }).catch((error) => {
+      throw /* @__PURE__ */ stripAnsiFromSpawnResult(error);
+    });
+  } else {
+    newSpawnPromise = spawnPromise.then((result) => {
+      if ("code" in result) {
+        const res = result;
+        res.exitCode = result.code;
+        return res;
+      }
+      return result;
+    });
+  }
+  if (shouldRestartSpinner) {
+    newSpawnPromise = newSpawnPromise.finally(() => {
+      spinnerInstance.start();
+    });
+  }
+  ;
+  newSpawnPromise.process = oldSpawnPromise.process;
+  newSpawnPromise.stdin = oldSpawnPromise.stdin;
+  return newSpawnPromise;
+}
+function spawnSync(cmd, args, options) {
+  const shell = (0, import_objects.getOwn)(options, "shell");
+  const WIN32 = process.platform === "win32";
+  let actualCmd = cmd;
+  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {
+    const path = /* @__PURE__ */ getPath();
+    actualCmd = path.basename(actualCmd, path.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 = (/* @__PURE__ */ getChildProcess()).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 ? /* @__PURE__ */ stripAnsiFromSpawnResult(result) : result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isSpawnError,
+  isStdioType,
+  spawn,
+  spawnSync
+});
+//# sourceMappingURL=spawn.js.map

package/dist/spawn.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/spawn.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Child process spawning utilities with cross-platform support.\n * Provides enhanced spawn functionality with stdio handling and error management.\n *\n * SECURITY: Array-Based Arguments Prevent Command Injection\n *\n * This module uses array-based arguments for all command execution, which is the\n * PRIMARY DEFENSE against command injection attacks. When you pass arguments as\n * an array to spawn():\n *\n *   spawn('npx', ['sfw', tool, ...args], { shell: true })\n *\n * Node.js handles escaping automatically. Each argument is passed directly to the\n * OS without shell interpretation. Shell metacharacters like ; | & $ ( ) ` are\n * treated as LITERAL STRINGS, not as commands. This approach is secure even when\n * shell: true is used on Windows for .cmd/.bat file resolution.\n *\n * UNSAFE ALTERNATIVE (not used in this codebase):\n *   spawn(`npx sfw ${tool} ${args.join(' ')}`, { shell: true })  // \u2716 VULNERABLE\n *\n * String concatenation allows injection. For example, if tool = \"foo; rm -rf /\",\n * the shell would execute both commands. Array-based arguments prevent this.\n *\n * References:\n * - https://nodejs.org/api/child_process.html#child_processspawncommand-args-options\n * - https://cheatsheetseries.owasp.org/cheatsheets/Nodejs_Security_Cheat_Sheet.html\n */\n\nimport { getAbortSignal, getSpinner } from '#constants/process'\n\nimport { isArray } from './arrays'\n\nconst abortSignal = getAbortSignal()\nconst spinner = getSpinner()\n\nimport { getOwn, hasOwn } from './objects'\nimport { stripAnsi } from './strings'\n\n// Define BufferEncoding type for TypeScript compatibility.\ntype BufferEncoding = globalThis.BufferEncoding\n\nconst windowsScriptExtRegExp = /\\.(?:cmd|bat|ps1)$/i\n\nlet _child_process: typeof import('node:child_process') | undefined\n/**\n * Lazily load the child_process module.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getChildProcess() {\n  if (_child_process === undefined) {\n    // Use non-'node:' prefixed require to avoid Webpack errors.\n\n    _child_process = /*@__PURE__*/ require('node:child_process')\n  }\n  return _child_process as typeof import('node:child_process')\n}\n\n// Type for promise-spawn options.\nexport type PromiseSpawnOptions = {\n  cwd?: string | undefined\n  stdioString?: boolean | undefined\n  stdio?: StdioType | undefined\n  env?: NodeJS.ProcessEnv | undefined\n  shell?: boolean | string | undefined\n  signal?: AbortSignal | undefined\n  timeout?: number | undefined\n  uid?: number | undefined\n  gid?: number | undefined\n}\n\n// Type for promise-spawn result.\nexport type PromiseSpawnResult = Promise<{\n  cmd: string\n  args: string[] | readonly string[]\n  code: number\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n}> & {\n  process: ChildProcessType\n  stdin: WritableStreamType | null\n}\n\nlet _npmCliPromiseSpawn:\n  | ((\n      cmd: string,\n      args: string[],\n      options?: PromiseSpawnOptions | undefined,\n      extra?: SpawnExtra | undefined,\n    ) => PromiseSpawnResult)\n  | undefined\n/**\n * Lazily load the promise-spawn module for async process spawning.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getNpmcliPromiseSpawn() {\n  if (_npmCliPromiseSpawn === undefined) {\n    _npmCliPromiseSpawn = /*@__PURE__*/ require('../external/@npmcli/promise-spawn')\n  }\n  return _npmCliPromiseSpawn as unknown as typeof import('@npmcli/promise-spawn')\n}\n\nlet _path: typeof import('node:path') | undefined\n/**\n * Lazily load the path module to avoid Webpack errors.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction getPath() {\n  if (_path === undefined) {\n    // Use non-'node:' prefixed require to avoid Webpack errors.\n\n    _path = /*@__PURE__*/ require('node:path')\n  }\n  return _path as typeof import('node:path')\n}\n\n/**\n * Check if a value is a spawn error.\n */\nexport type SpawnError = {\n  args: string[]\n  cmd: string\n  code: number\n  name: string\n  message: string\n  signal: NodeJS.Signals | null\n  stack: string\n  stderr: string | Buffer\n  stdout: string | Buffer\n}\n\nexport type SpawnErrorWithOutputString = SpawnError & {\n  stdout: string\n  stderr: string\n}\n\nexport type SpawnErrorWithOutputBuffer = SpawnError & {\n  stdout: Buffer\n  stderr: Buffer\n}\n\nexport type SpawnExtra = Record<string, unknown>\n\nexport type IOType = 'pipe' | 'ignore' | 'inherit' | 'overlapped'\nexport type StdioType = IOType | 'ipc' | Array<IOType | 'ipc'>\n\nexport interface SpawnSyncReturns<T> {\n  pid: number\n  output: Array<T | null>\n  stdout: T\n  stderr: T\n  status: number | null\n  signal: NodeJS.Signals | null\n  error?: Error | undefined\n}\n\n/**\n * Check if a value is a spawn error with expected properties.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function isSpawnError(value: unknown): value is SpawnError {\n  if (value === null || typeof value !== 'object') {\n    return false\n  }\n  // Check for spawn-specific error properties.\n  const err = value as Record<string, unknown>\n  return (\n    (hasOwn(err, 'code') && typeof err['code'] !== 'undefined') ||\n    (hasOwn(err, 'errno') && typeof err['errno'] !== 'undefined') ||\n    (hasOwn(err, 'syscall') && typeof err['syscall'] === 'string')\n  )\n}\n\n/**\n * Check if stdio configuration matches a specific type.\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function isStdioType(\n  stdio: string | string[],\n  type?: StdioType | undefined,\n): boolean {\n  // If called with one argument, check if it's a valid stdio type.\n  // biome-ignore lint/complexity/noArguments: Function overload detection for single vs two-arg calls.\n  if (arguments.length === 1) {\n    const validTypes = ['pipe', 'ignore', 'inherit', 'overlapped']\n    return typeof stdio === 'string' && validTypes.includes(stdio)\n  }\n  // Original two-argument behavior.\n  return (\n    stdio === type ||\n    ((stdio === null || stdio === undefined) && type === 'pipe') ||\n    (isArray(stdio) &&\n      stdio.length > 2 &&\n      stdio[0] === type &&\n      stdio[1] === type &&\n      stdio[2] === type)\n  )\n}\n\n/**\n * Strip ANSI escape codes from spawn result stdout and stderr.\n */\n/*@__NO_SIDE_EFFECTS__*/\nfunction stripAnsiFromSpawnResult(result: unknown): unknown {\n  const res = result as {\n    stdout?: string | Buffer\n    stderr?: string | Buffer\n  }\n  const { stderr, stdout } = res\n  if (typeof stdout === 'string') {\n    res.stdout = stripAnsi(stdout)\n  }\n  if (typeof stderr === 'string') {\n    res.stderr = stripAnsi(stderr)\n  }\n  return res\n}\n\n/*@__NO_SIDE_EFFECTS__*/\n// Duplicated from Node.js child_process.SpawnOptions\n// These are the options passed to child_process.spawn()\ninterface NodeSpawnOptions {\n  cwd?: string | URL | undefined\n  env?: NodeJS.ProcessEnv | undefined\n  argv0?: string | undefined\n  // biome-ignore lint/suspicious/noExplicitAny: Stdio can be complex union of types from Node.js.\n  stdio?: any\n  detached?: boolean | undefined\n  uid?: number | undefined\n  gid?: number | undefined\n  serialization?: 'json' | 'advanced' | undefined\n  shell?: boolean | string | undefined\n  windowsVerbatimArguments?: boolean | undefined\n  windowsHide?: boolean | undefined\n  signal?: AbortSignal | undefined\n  timeout?: number | undefined\n  killSignal?: NodeJS.Signals | number | undefined\n}\n\n// Duplicated from Node.js child_process.ChildProcess\n// This represents a spawned child process\ninterface ChildProcessType {\n  stdin: NodeJS.WritableStream | null\n  stdout: NodeJS.ReadableStream | null\n  stderr: NodeJS.ReadableStream | null\n  // biome-ignore lint/suspicious/noExplicitAny: IPC channel type from Node.js.\n  readonly channel?: any\n  readonly stdio: [\n    NodeJS.WritableStream | null,\n    NodeJS.ReadableStream | null,\n    NodeJS.ReadableStream | null,\n    NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined,\n    NodeJS.ReadableStream | NodeJS.WritableStream | null | undefined,\n  ]\n  readonly killed: boolean\n  readonly pid?: number | undefined\n  readonly connected: boolean\n  readonly exitCode: number | null\n  readonly signalCode: NodeJS.Signals | null\n  readonly spawnargs: string[]\n  readonly spawnfile: string\n  kill(signal?: NodeJS.Signals | number): boolean\n  // biome-ignore lint/suspicious/noExplicitAny: IPC message type from Node.js.\n  send(message: any, callback?: (error: Error | null) => void): boolean\n  send(\n    // biome-ignore lint/suspicious/noExplicitAny: IPC message and handle types from Node.js.\n    message: any,\n    // biome-ignore lint/suspicious/noExplicitAny: IPC message and handle types from Node.js.\n    sendHandle?: any | undefined,\n    callback?: (error: Error | null) => void,\n  ): boolean\n  send(\n    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.\n    message: any,\n    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.\n    sendHandle?: any | undefined,\n    // biome-ignore lint/suspicious/noExplicitAny: IPC message, handle, and options types from Node.js.\n    options?: any | undefined,\n    callback?: (error: Error | null) => void,\n  ): boolean\n  disconnect(): void\n  unref(): void\n  ref(): void\n}\n\n// Duplicated from Node.js stream.Writable\ninterface WritableStreamType {\n  writable: boolean\n  writableEnded: boolean\n  writableFinished: boolean\n  writableHighWaterMark: number\n  writableLength: number\n  writableObjectMode: boolean\n  writableCorked: number\n  destroyed: boolean\n  write(\n    // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.\n    chunk: any,\n    encoding?: BufferEncoding | undefined,\n    callback?: (error?: Error | null) => void,\n  ): boolean\n  // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.\n  write(chunk: any, callback?: (error?: Error | null) => void): boolean\n  end(cb?: () => void): this\n  // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.\n  end(chunk: any, cb?: () => void): this\n  // biome-ignore lint/suspicious/noExplicitAny: Stream chunk can be any type.\n  end(chunk: any, encoding?: BufferEncoding | undefined, cb?: () => void): this\n  cork(): void\n  uncork(): void\n  destroy(error?: Error | undefined): this\n}\n\n/**\n * Spawn a child process with enhanced error handling and output capture.\n */\nexport type SpawnOptions = import('./objects').Remap<\n  NodeSpawnOptions & {\n    spinner?: import('./spinner').Spinner | undefined\n    stdioString?: boolean\n    stripAnsi?: boolean\n  }\n>\nexport type SpawnResult = PromiseSpawnResult\nexport type SpawnStdioResult = {\n  cmd: string\n  args: string[] | readonly string[]\n  code: number\n  signal: NodeJS.Signals | null\n  stdout: string | Buffer\n  stderr: string | Buffer\n}\n\n/**\n * Spawn a child process and return a promise that resolves when it completes.\n *\n * SECURITY: This function uses array-based arguments which prevent command injection.\n * Arguments in the `args` array are passed directly to the OS without shell\n * interpretation. Shell metacharacters (;|&$()`) are treated as literal strings,\n * not as commands or operators. This is the PRIMARY SECURITY DEFENSE.\n *\n * Even when shell: true is used (on Windows for .cmd/.bat execution), the array-based\n * approach remains secure because Node.js properly escapes each argument before passing\n * to the shell.\n *\n * @param cmd - Command to execute (not user-controlled)\n * @param args - Array of arguments (safe even with user input due to array-based passing)\n * @param options - Spawn options\n * @param extra - Extra options for promise-spawn\n *\n * @example\n * // \u2714 DO THIS - Array-based arguments\n * spawn('git', ['commit', '-m', userMessage])\n * // Each argument is properly escaped, even if userMessage = \"foo; rm -rf /\"\n *\n * @example\n * // \u2716 NEVER DO THIS - String concatenation\n * spawn(`git commit -m \"${userMessage}\"`, { shell: true })\n * // Vulnerable to injection if userMessage = '\"; rm -rf / #'\n */\nexport function spawn(\n  cmd: string,\n  args?: string[] | readonly string[],\n  options?: SpawnOptions | undefined,\n  extra?: SpawnExtra | undefined,\n): SpawnResult {\n  // Windows cmd.exe command resolution for .cmd/.bat/.ps1 files:\n  //\n  // When shell: true is used on Windows with script files (.cmd, .bat, .ps1),\n  // cmd.exe can have issues executing full paths. The solution is to use just\n  // the command basename without extension and let cmd.exe find it via PATH.\n  //\n  // How cmd.exe resolves commands:\n  // 1. Searches current directory first\n  // 2. Then searches each directory in PATH environment variable\n  // 3. For each directory, tries extensions from PATHEXT (.COM, .EXE, .BAT, .CMD, etc.)\n  // 4. Executes the first match found\n  //\n  // Example: Given 'C:\\pnpm\\pnpm.cmd' with shell: true\n  // 1. Extract basename without extension: 'pnpm'\n  // 2. cmd.exe searches PATH directories for 'pnpm'\n  // 3. PATHEXT causes it to try 'pnpm.com', 'pnpm.exe', 'pnpm.bat', 'pnpm.cmd', etc.\n  // 4. Finds and executes 'C:\\pnpm\\pnpm.cmd'\n  //\n  // This approach is consistent with how other tools handle Windows execution:\n  // - npm's promise-spawn: uses which.sync() to find commands in PATH\n  // - cross-spawn: spawns cmd.exe with escaped arguments\n  // - execa: uses cross-spawn under the hood for Windows support\n  //\n  // See: https://github.com/nodejs/node/issues/3675\n  const shell = getOwn(options, 'shell')\n  // Inline WIN32 constant for coverage mode compatibility\n  const WIN32 = process.platform === 'win32'\n  let actualCmd = cmd\n  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {\n    const path = getPath()\n    // Extract just the command name without path and extension.\n    actualCmd = path.basename(actualCmd, path.extname(actualCmd))\n  }\n  const {\n    spinner: optionsSpinner = spinner,\n    stripAnsi: shouldStripAnsi = true,\n    ...spawnOptions\n  } = { __proto__: null, ...options } as SpawnOptions\n  const spinnerInstance = optionsSpinner\n  const { env, stdio, stdioString = true } = spawnOptions\n  // The stdio option can be a string or an array.\n  // https://nodejs.org/api/child_process.html#optionsstdio\n  const wasSpinning = !!spinnerInstance?.isSpinning\n  const shouldStopSpinner =\n    wasSpinning && !isStdioType(stdio, 'ignore') && !isStdioType(stdio, 'pipe')\n  const shouldRestartSpinner = shouldStopSpinner\n  if (shouldStopSpinner) {\n    spinnerInstance.stop()\n  }\n  const npmCliPromiseSpawn = getNpmcliPromiseSpawn()\n  // Use __proto__: null to prevent prototype pollution when passing to\n  // third-party code, Node.js built-ins, or JavaScript built-in methods.\n  // https://github.com/npm/promise-spawn\n  // https://github.com/nodejs/node/blob/v24.0.1/lib/child_process.js#L674-L678\n  const promiseSpawnOpts = {\n    __proto__: null,\n    cwd: typeof spawnOptions.cwd === 'string' ? spawnOptions.cwd : undefined,\n    env: {\n      __proto__: null,\n      ...process.env,\n      ...env,\n    } as unknown as NodeJS.ProcessEnv,\n    signal: abortSignal,\n    stdio: spawnOptions.stdio,\n    stdioString,\n    shell: spawnOptions.shell,\n    timeout: spawnOptions.timeout,\n    uid: spawnOptions.uid,\n    gid: spawnOptions.gid,\n  } as unknown as PromiseSpawnOptions\n  const spawnPromise = npmCliPromiseSpawn(\n    actualCmd,\n    args ? [...args] : [],\n    promiseSpawnOpts as Parameters<typeof npmCliPromiseSpawn>[2],\n    extra,\n  )\n  const oldSpawnPromise = spawnPromise\n  let newSpawnPromise: PromiseSpawnResult\n  if (shouldStripAnsi && stdioString) {\n    newSpawnPromise = spawnPromise\n      .then(result => {\n        const strippedResult = stripAnsiFromSpawnResult(result)\n        // Add exitCode as an alias for code.\n        if ('code' in (strippedResult as { code?: number })) {\n          ;(strippedResult as { code: number; exitCode: number }).exitCode = (\n            strippedResult as { code: number }\n          ).code\n        }\n        return strippedResult\n      })\n      .catch(error => {\n        throw stripAnsiFromSpawnResult(error)\n      }) as PromiseSpawnResult\n  } else {\n    newSpawnPromise = spawnPromise.then(result => {\n      // Add exitCode as an alias for code.\n      if ('code' in result) {\n        const res = result as typeof result & { exitCode: number }\n        res.exitCode = result.code\n        return res\n      }\n      return result\n    }) as PromiseSpawnResult\n  }\n  if (shouldRestartSpinner) {\n    newSpawnPromise = newSpawnPromise.finally(() => {\n      spinnerInstance.start()\n    }) as PromiseSpawnResult\n  }\n  // Copy process and stdin properties from original promise\n  ;(newSpawnPromise as unknown as PromiseSpawnResult).process =\n    oldSpawnPromise.process\n  ;(newSpawnPromise as unknown as PromiseSpawnResult).stdin = (\n    oldSpawnPromise as unknown as PromiseSpawnResult\n  ).stdin\n  return newSpawnPromise as SpawnResult\n}\n\n/*@__NO_SIDE_EFFECTS__*/\n/**\n * Synchronously spawn a child process.\n */\nexport type SpawnSyncOptions = Omit<SpawnOptions, 'spinner'>\nexport function spawnSync(\n  cmd: string,\n  args?: string[] | readonly string[],\n  options?: SpawnSyncOptions | undefined,\n): SpawnSyncReturns<string | Buffer> {\n  // Windows cmd.exe command resolution for .cmd/.bat/.ps1 files:\n  // See spawn() function above for detailed explanation of this approach.\n  const shell = getOwn(options, 'shell')\n  // Inline WIN32 constant for coverage mode compatibility\n  const WIN32 = process.platform === 'win32'\n  let actualCmd = cmd\n  if (WIN32 && shell && windowsScriptExtRegExp.test(actualCmd)) {\n    const path = getPath()\n    // Extract just the command name without path and extension.\n    actualCmd = path.basename(actualCmd, path.extname(actualCmd))\n  }\n  const { stripAnsi: shouldStripAnsi = true, ...rawSpawnOptions } = {\n    __proto__: null,\n    ...options,\n  } as SpawnSyncOptions\n  const { stdioString: rawStdioString = true } = rawSpawnOptions\n  const rawEncoding = rawStdioString ? 'utf8' : 'buffer'\n  const spawnOptions = {\n    encoding: rawEncoding,\n    ...rawSpawnOptions,\n  } as NodeSpawnOptions & { encoding: BufferEncoding | 'buffer' }\n  const stdioString = spawnOptions.encoding !== 'buffer'\n  const result = getChildProcess().spawnSync(actualCmd, args, spawnOptions)\n  if (stdioString) {\n    const { stderr, stdout } = result\n    if (stdout) {\n      result.stdout = stdout.toString().trim()\n    }\n    if (stderr) {\n      result.stderr = stderr.toString().trim()\n    }\n  }\n  return (\n    shouldStripAnsi && stdioString ? stripAnsiFromSpawnResult(result) : result\n  ) as SpawnSyncReturns<string | Buffer>\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/spinner.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview CLI spinner utilities for long-running operations.
+ * Provides animated progress indicators with CI environment detection.
+ */
+import type { Writable } from 'node:stream';
+import type { ShimmerColorGradient, ShimmerConfig, ShimmerDirection, ShimmerState } from './effects/text-shimmer';
+export type ColorName = 'black' | 'blue' | 'blueBright' | 'cyan' | 'cyanBright' | 'gray' | 'green' | 'greenBright' | 'magenta' | 'magentaBright' | 'red' | 'redBright' | 'white' | 'whiteBright' | 'yellow' | 'yellowBright';
+export type ColorInherit = 'inherit';
+export type ColorRgb = readonly [number, number, number];
+export type ColorValue = ColorName | ColorRgb;
+export type SymbolType = 'fail' | 'info' | 'success' | 'warn';
+export type ProgressInfo = {
+    current: number;
+    total: number;
+    unit?: string | undefined;
+};
+export type ShimmerInfo = ShimmerState & {
+    color: ColorInherit | ColorValue | ShimmerColorGradient;
+};
+export type Spinner = {
+    color: ColorRgb;
+    spinner: SpinnerStyle;
+    get isSpinning(): boolean;
+    clear(): Spinner;
+    debug(text?: string | undefined, ...extras: unknown[]): Spinner;
+    debugAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    error(text?: string | undefined, ...extras: unknown[]): Spinner;
+    errorAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    fail(text?: string | undefined, ...extras: unknown[]): Spinner;
+    failAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    // text property returns a method via _textMethod override
+    text(value: string): Spinner;
+    text(): string;
+    indent(spaces?: number | undefined): Spinner;
+    dedent(spaces?: number | undefined): Spinner;
+    info(text?: string | undefined, ...extras: unknown[]): Spinner;
+    infoAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    log(text?: string | undefined, ...extras: unknown[]): Spinner;
+    logAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    start(text?: string | undefined): Spinner;
+    stop(text?: string | undefined): Spinner;
+    stopAndPersist(text?: string | undefined): Spinner;
+    step(text?: string | undefined, ...extras: unknown[]): Spinner;
+    substep(text?: string | undefined, ...extras: unknown[]): Spinner;
+    success(text?: string | undefined, ...extras: unknown[]): Spinner;
+    successAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    done(text?: string | undefined, ...extras: unknown[]): Spinner;
+    doneAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+    progress(current: number, total: number, unit?: string | undefined): Spinner;
+    progressStep(amount?: number): Spinner;
+    shimmer(enabled: boolean): Spinner;
+    shimmer(config: Partial<ShimmerConfig> | ShimmerDirection): Spinner;
+    warn(text?: string | undefined, ...extras: unknown[]): Spinner;
+    warnAndStop(text?: string | undefined, ...extras: unknown[]): Spinner;
+};
+export type SpinnerOptions = {
+    readonly color?: ColorValue | undefined;
+    readonly shimmer?: ShimmerConfig | ShimmerDirection | undefined;
+    readonly spinner?: SpinnerStyle | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly stream?: Writable | undefined;
+    readonly text?: string | undefined;
+};
+export type SpinnerStyle = {
+    readonly frames: string[];
+    readonly interval?: number | undefined;
+};
+export declare const ciSpinner: SpinnerStyle;
+/**
+ * Get available CLI spinner styles or a specific style by name.
+ * Extends the standard cli-spinners collection with Socket custom spinners.
+ *
+ * @see https://github.com/sindresorhus/cli-spinners/blob/main/spinners.json
+ *
+ * Custom spinners:
+ * - `socket` (default): Socket pulse animation with sparkles and lightning
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function getCliSpinners(styleName?: string | undefined): SpinnerStyle | Record<string, SpinnerStyle> | undefined;
+/**
+ * Create a spinner instance for displaying loading indicators.
+ *
+ * AUTO-CLEAR BEHAVIOR:
+ * - All *AndStop() methods AUTO-CLEAR the spinner line via yocto-spinner.stop()
+ *   Examples: doneAndStop(), successAndStop(), failAndStop(), etc.
+ *
+ * - Methods WITHOUT "AndStop" do NOT clear (spinner keeps spinning)
+ *   Examples: done(), success(), fail(), etc.
+ *
+ * STREAM USAGE:
+ * - Spinner animation: stderr (yocto-spinner default)
+ * - Status methods (done, success, fail, info, warn, step, substep): stderr
+ * - Data methods (log): stdout
+ *
+ * COMPARISON WITH LOGGER:
+ * - logger.done() does NOT auto-clear (requires manual logger.clearLine())
+ * - spinner.doneAndStop() DOES auto-clear (built into yocto-spinner.stop())
+ * - Pattern: logger.clearLine().done() vs spinner.doneAndStop()
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function Spinner(options?: SpinnerOptions | undefined): Spinner;
+/**
+ * Get the default spinner instance.
+ * Lazily creates the spinner to avoid circular dependencies during module initialization.
+ */
+export declare function getDefaultSpinner(): ReturnType<typeof Spinner>;
+/**
+ * @deprecated Use `getDefaultSpinner()` function instead for better tree-shaking and to avoid circular dependencies.
+ */
+export declare const spinner: Spinner;
+export type WithSpinnerOptions<T> = {
+    message: string;
+    operation: () => Promise<T>;
+    spinner?: Spinner | undefined;
+};
+/**
+ * Execute an async operation with spinner lifecycle management.
+ * Ensures spinner.stop() is always called via try/finally, even if the operation throws.
+ *
+ * @param options - Configuration object
+ * @param options.message - Message to display while spinner is running
+ * @param options.operation - Async function to execute
+ * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
+ * @returns Result of the operation
+ * @throws Re-throws any error from operation after stopping spinner
+ *
+ * @example
+ * import { spinner, withSpinner } from '@socketsecurity/registry/lib/spinner'
+ *
+ * // With spinner instance
+ * await withSpinner({
+ *   message: 'Processing…',
+ *   operation: async () => {
+ *     return await processData()
+ *   },
+ *   spinner
+ * })
+ *
+ * // Without spinner instance (no-op)
+ * await withSpinner({
+ *   message: 'Processing…',
+ *   operation: async () => {
+ *     return await processData()
+ *   }
+ * })
+ */
+export declare function withSpinner<T>(options: WithSpinnerOptions<T>): Promise<T>;
+export type WithSpinnerRestoreOptions<T> = {
+    operation: () => Promise<T>;
+    spinner?: Spinner | undefined;
+    wasSpinning: boolean;
+};
+/**
+ * Execute an async operation with conditional spinner restart.
+ * Useful when you need to temporarily stop a spinner for an operation,
+ * then restore it to its previous state.
+ *
+ * @param options - Configuration object
+ * @param options.operation - Async function to execute
+ * @param options.spinner - Optional spinner instance to manage
+ * @param options.wasSpinning - Whether spinner was spinning before
+ * @returns Result of the operation
+ * @throws Re-throws any error from operation after restoring spinner state
+ *
+ * @example
+ * import { spinner, withSpinnerRestore } from '@socketsecurity/registry/lib/spinner'
+ *
+ * const wasSpinning = spinner.isSpinning
+ * spinner.stop()
+ *
+ * const result = await withSpinnerRestore({
+ *   operation: async () => {
+ *     // Do work without spinner
+ *     return await someOperation()
+ *   },
+ *   spinner,
+ *   wasSpinning
+ * })
+ */
+export declare function withSpinnerRestore<T>(options: WithSpinnerRestoreOptions<T>): Promise<T>;
+export type WithSpinnerSyncOptions<T> = {
+    message: string;
+    operation: () => T;
+    spinner?: Spinner | undefined;
+};
+/**
+ * Execute a synchronous operation with spinner lifecycle management.
+ * Ensures spinner.stop() is always called via try/finally, even if the operation throws.
+ *
+ * @param options - Configuration object
+ * @param options.message - Message to display while spinner is running
+ * @param options.operation - Function to execute
+ * @param options.spinner - Optional spinner instance (if not provided, no spinner is used)
+ * @returns Result of the operation
+ * @throws Re-throws any error from operation after stopping spinner
+ *
+ * @example
+ * import { spinner, withSpinnerSync} from '@socketsecurity/registry/lib/spinner'
+ *
+ * const result = withSpinnerSync({
+ *   message: 'Processing…',
+ *   operation: () => {
+ *     return processDataSync()
+ *   },
+ *   spinner
+ * })
+ */
+export declare function withSpinnerSync<T>(options: WithSpinnerSyncOptions<T>): T;