@socketsecurity/lib 3.4.0 → 4.0.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v4.0.0) - 2025-11-15
+
+### Changed
+
+- **paths**: Reorganized path utilities into dedicated `paths/*` submodules for improved modularity
+- **imports**: Converted lazy require() calls to ES6 static imports for better tree-shaking and bundler compatibility
+
+## [3.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.5.0) - 2025-11-14
+
+### Added
+
+- **argv/quote**: New utilities for quoting command-line arguments when using `spawn()` with `shell: true`
+  - `posixQuote(arg)`: Quote arguments for POSIX shells (bash, sh, zsh) using single quotes
+  - `win32Quote(arg)`: Quote arguments for Windows cmd.exe using double quotes
+
 ## [3.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.4.0) - 2025-11-14
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-83.06%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-83.95%25-brightgreen)
 
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
@@ -31,13 +31,13 @@ spinner.stop()
 
 ## What's Inside
 
-- **Visual Effects** → Spinners, themes, logger
-- **File System** → fs, paths, globs
-- **Package Management** → npm, pnpm, yarn, dlx
-- **Process & Spawn** → Safe process spawning
-- **Environment** → 68 typed env getters
-- **Constants** → Node.js, npm, platform
-- **Utilities** → Arrays, objects, strings, promises
+- **Visual Effects** → logger, spinner, themes
+- **File System** → fs, globs, paths
+- **Package Management** → dlx, npm, pnpm, yarn
+- **Process & Spawn** → process spawning
+- **Environment** → env getters
+- **Constants** → node, npm, platform
+- **Utilities** → arrays, objects, promises, strings
 
 ## Development
 

package/dist/agent.js

@@ -34,8 +34,10 @@ __export(agent_exports, {
   isPnpmLoglevelFlag: () => isPnpmLoglevelFlag
 });
 module.exports = __toCommonJS(agent_exports);
-var import_ci = require("#env/ci");
+var import_agents = require("#constants/agents");
+var import_node = require("#constants/node");
 var import_platform = require("#constants/platform");
+var import_ci = require("#env/ci");
 var import_bin = require("./bin");
 var import_debug = require("./debug");
 var import_fs = require("./fs");
@@ -86,7 +88,7 @@ function execNpm(args, options) {
     // one level quieter.
     useDebug || npmArgs.some(isNpmLoglevelFlag) ? [] : ["--loglevel", "warn"]
   );
-  const npmBin = require("#constants/agents").NPM_BIN_PATH;
+  const npmBin = import_agents.NPM_BIN_PATH;
   return (0, import_spawn.spawn)(
     npmBin,
     [
@@ -227,40 +229,25 @@ function execScript(scriptName, args, options) {
   if (spawnOptions.shell === true) {
     return (0, import_spawn.spawn)(scriptName, resolvedArgs, spawnOptions);
   }
-  const useNodeRun = !prepost && /* @__PURE__ */ require("#constants/node").supportsNodeRun();
+  const useNodeRun = !prepost && (0, import_node.supportsNodeRun)();
   const cwd = (0, import_objects.getOwn)(spawnOptions, "cwd") ?? process.cwd();
-  const pnpmLockPath = (0, import_fs.findUpSync)(
-    /*@__INLINE__*/
-    require("#constants/agents").PNPM_LOCK_YAML,
-    { cwd }
-  );
+  const pnpmLockPath = (0, import_fs.findUpSync)(import_agents.PNPM_LOCK_YAML, { cwd });
   if (pnpmLockPath) {
     return execPnpm(["run", scriptName, ...resolvedArgs], spawnOptions);
   }
-  const packageLockPath = (0, import_fs.findUpSync)(
-    /*@__INLINE__*/
-    require("#constants/agents").PACKAGE_LOCK_JSON,
-    { cwd }
-  );
+  const packageLockPath = (0, import_fs.findUpSync)(import_agents.PACKAGE_LOCK_JSON, { cwd });
   if (packageLockPath) {
     return execNpm(["run", scriptName, ...resolvedArgs], spawnOptions);
   }
-  const yarnLockPath = (0, import_fs.findUpSync)(
-    /*@__INLINE__*/
-    require("#constants/agents").YARN_LOCK,
-    { cwd }
-  );
+  const yarnLockPath = (0, import_fs.findUpSync)(import_agents.YARN_LOCK, { cwd });
   if (yarnLockPath) {
     return execYarn(["run", scriptName, ...resolvedArgs], spawnOptions);
   }
   return (0, import_spawn.spawn)(
-    /* @__PURE__ */ require("#constants/node").getExecPath(),
+    (0, import_node.getExecPath)(),
     [
-      .../* @__PURE__ */ require("#constants/node").getNodeNoWarningsFlags(),
-      ...useNodeRun ? ["--run"] : [
-        require("#constants/agents").NPM_REAL_EXEC_PATH,
-        "run"
-      ],
+      ...(0, import_node.getNodeNoWarningsFlags)(),
+      ...useNodeRun ? ["--run"] : [import_agents.NPM_REAL_EXEC_PATH, "run"],
       scriptName,
       ...resolvedArgs
     ],

package/dist/bin.d.ts

@@ -1,15 +1,9 @@
-/**
- * Execute a binary with the given arguments.
- */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function execBin(binPath: string, args?: string[], options?: import('./spawn').SpawnOptions): Promise<{
-    cmd: string;
-    args: string[] | readonly string[];
-    code: number;
-    signal: NodeJS.Signals;
-    stdout: string | Buffer<ArrayBufferLike>;
-    stderr: string | Buffer<ArrayBufferLike>;
-}>;
+// ============================================================================
+// Private Helper Functions
+// ============================================================================
+// ============================================================================
+// Types and Interfaces
+// ============================================================================
 /**
  * Options for the which function.
  */
@@ -24,54 +18,117 @@ export interface WhichOptions {
     pathExt?: string | undefined;
     /** Environment variables to use. */
     env?: Record<string, string | undefined> | undefined;
+    /** Current working directory for resolving relative paths. */
+    cwd?: string | undefined;
 }
+// ============================================================================
+// Public API (alphabetically sorted)
+// ============================================================================
 /**
- * Find an executable in the system PATH asynchronously.
- * Wrapper around the which package for lazy loading.
+ * Execute a binary with the given arguments.
  */
-/* c8 ignore start */
-export declare function which(binName: string, options?: WhichOptions): Promise<string | string[] | undefined>;
-/* c8 ignore stop */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function execBin(binPath: string, args?: string[], options?: import('./spawn').SpawnOptions): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals;
+    stdout: string | Buffer<ArrayBufferLike>;
+    stderr: string | Buffer<ArrayBufferLike>;
+}>;
 /**
- * Find an executable in the system PATH synchronously.
- * Wrapper around the which package for lazy loading.
+ * Find the real executable for a binary, bypassing shadow bins.
  */
-/* c8 ignore start */
-export declare function whichSync(binName: string, options?: WhichOptions): string | string[] | undefined;
-/* c8 ignore stop */
+export declare function findRealBin(binName: string, commonPaths?: string[]): string | undefined;
 /**
- * Find and resolve a binary in the system PATH asynchronously.
- * @throws {Error} If the binary is not found and nothrow is false.
+ * Find the real npm executable, bypassing any aliases and shadow bins.
  */
-export declare function whichBin(binName: string, options?: WhichOptions): Promise<string | string[] | undefined>;
+export declare function findRealNpm(): string;
 /**
- * Find and resolve a binary in the system PATH synchronously.
- * @throws {Error} If the binary is not found and nothrow is false.
+ * Find the real pnpm executable, bypassing any aliases and shadow bins.
  */
-export declare function whichBinSync(binName: string, options?: WhichOptions): string | string[] | undefined;
+export declare function findRealPnpm(): string;
+/**
+ * Find the real yarn executable, bypassing any aliases and shadow bins.
+ */
+export declare function findRealYarn(): string;
 /**
  * Check if a directory path contains any shadow bin patterns.
  */
 export declare function isShadowBinPath(dirPath: string | undefined): boolean;
+/*@__NO_SIDE_EFFECTS__*/
 /**
- * Find the real executable for a binary, bypassing shadow bins.
+ * Resolve a binary path to the real underlying script file.
+ * Handles Windows .cmd wrappers and Unix shell scripts, resolving them to the actual .js files they execute.
  */
-export declare function findRealBin(binName: string, commonPaths?: string[]): string | undefined;
+export declare function resolveRealBinSync(binPath: string): string;
 /**
- * Find the real npm executable, bypassing any aliases and shadow bins.
+ * Find an executable in the system PATH asynchronously.
+ *
+ * This function resolves binary names to their full paths by searching the system PATH.
+ * It should only be used for binary names (not paths). If the input is already a path
+ * (absolute or relative), it will be returned as-is without PATH resolution.
+ *
+ * Binary name vs. path detection:
+ * - Binary names: 'npm', 'git', 'node' - will be resolved via PATH
+ * - Absolute paths: '/usr/bin/node', 'C:\\Program Files\\nodejs\\node.exe' - returned as-is
+ * - Relative paths: './node', '../bin/npm' - returned as-is
+ *
+ * @param {string} binName - The binary name to resolve (e.g., 'npm', 'git')
+ * @param {WhichOptions | undefined} options - Options for resolution
+ * @returns {Promise<string | string[] | null>} Promise resolving to the full path, the original path, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Resolve binary names
+ * await which('node')              // '/usr/local/bin/node'
+ * await which('npm')               // '/usr/local/bin/npm'
+ * await which('nonexistent')       // null
+ *
+ * // Paths are returned as-is
+ * await which('/usr/bin/node')     // '/usr/bin/node'
+ * await which('./local-script')    // './local-script'
+ * ```
  */
-export declare function findRealNpm(): string;
+export declare function which(binName: string, options?: WhichOptions): Promise<string | string[] | null>;
 /**
- * Find the real pnpm executable, bypassing any aliases and shadow bins.
+ * Find a binary in the system PATH and resolve to the real underlying script asynchronously.
+ * Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
+ * @throws {Error} If the binary is not found and nothrow is false.
  */
-export declare function findRealPnpm(): string;
+export declare function whichReal(binName: string, options?: WhichOptions): Promise<string | string[] | undefined>;
 /**
- * Find the real yarn executable, bypassing any aliases and shadow bins.
+ * Find a binary in the system PATH and resolve to the real underlying script synchronously.
+ * Resolves wrapper scripts (.cmd, .ps1, shell scripts) to the actual .js files they execute.
+ * @throws {Error} If the binary is not found and nothrow is false.
  */
-export declare function findRealYarn(): string;
-/*@__NO_SIDE_EFFECTS__*/
+export declare function whichRealSync(binName: string, options?: WhichOptions): string | string[] | undefined;
 /**
- * Resolve a binary path to its actual executable file.
- * Handles Windows .cmd wrappers and Unix shell scripts.
+ * Find an executable in the system PATH synchronously.
+ *
+ * This function resolves binary names to their full paths by searching the system PATH.
+ * It should only be used for binary names (not paths). If the input is already a path
+ * (absolute or relative), it will be returned as-is without PATH resolution.
+ *
+ * Binary name vs. path detection:
+ * - Binary names: 'npm', 'git', 'node' - will be resolved via PATH
+ * - Absolute paths: '/usr/bin/node', 'C:\\Program Files\\nodejs\\node.exe' - returned as-is
+ * - Relative paths: './node', '../bin/npm' - returned as-is
+ *
+ * @param {string} binName - The binary name to resolve (e.g., 'npm', 'git')
+ * @param {WhichOptions | undefined} options - Options for resolution
+ * @returns {string | string[] | null} The full path to the binary, the original path if input is a path, or null if not found
+ *
+ * @example
+ * ```typescript
+ * // Resolve binary names
+ * whichSync('node')              // '/usr/local/bin/node'
+ * whichSync('npm')               // '/usr/local/bin/npm'
+ * whichSync('nonexistent')       // null
+ *
+ * // Paths are returned as-is
+ * whichSync('/usr/bin/node')     // '/usr/bin/node'
+ * whichSync('./local-script')    // './local-script'
+ * ```
  */
-export declare function resolveBinPathSync(binPath: string): string;
+export declare function whichSync(binName: string, options?: WhichOptions): string | string[] | null;