@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/bin/resolve.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Resolve a binary path to the underlying script file. Wrapper-script
+ *   unwrapping: a binary like `npm` is rarely an executable — on Windows it's
+ *   `npm.cmd` / `npm.ps1` / extensionless `npm` shell script. Each wrapper
+ *   variant has a fixed format generated by either the npm CLI build (npm/npx
+ *   specific) or by `cmd-shim` for arbitrary package binaries. We pattern-match
+ *   each format and extract the relative path to the underlying `.js` so
+ *   callers can spawn Node with that path directly (cheaper than re-launching a
+ *   shell wrapper). Volta managed installs: Volta layers binaries through
+ *   `~/.volta/tools/{image,user}/...` with version-pinned subdirs. We detect
+ *   the `.volta/` segment in the path and walk into the image directory to find
+ *   the real CLI script. Caching: per-Volta-key cache + a final `realpathSync`
+ *   to dedupe symlinked installations. Both caches live in `_internal.ts` so
+ *   `which.ts` can flush them when its own cache eviction fires. Cycles with
+ *   `which.ts`: `resolveRealBinSync` calls `whichRealSync` to handle relative
+ *   input paths. ESM tolerates the cycle since both sides expose only functions
+ *   (no eager top-level evaluation that needs the other module's bindings).
+ */
+/**
+ * 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.
+ *
+ * @example
+ *   ;```typescript
+ *   const realPath = resolveRealBinSync('/usr/local/bin/npm')
+ *   // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ *   ```
+ */
+export declare function resolveRealBinSync(binPath: string): string;

package/dist/bin/resolve.js

@@ -0,0 +1,249 @@
+"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 resolve_exports = {};
+__export(resolve_exports, {
+  resolveRealBinSync: () => resolveRealBinSync
+});
+module.exports = __toCommonJS(resolve_exports);
+var import_platform = require("../constants/platform");
+var import_read_json = require("../fs/read-json");
+var import_normalize = require("../paths/normalize");
+var import_string = require("../primordials/string");
+var import_internal = require("./_internal");
+var import_which = require("./which");
+// @__NO_SIDE_EFFECTS__
+function resolveRealBinSync(binPath) {
+  const fs = (0, import_internal.getFs)();
+  const path = (0, import_internal.getPath)();
+  if (!path.isAbsolute(binPath)) {
+    try {
+      const resolved = (0, import_which.whichRealSync)(binPath);
+      if (resolved) {
+        binPath = resolved;
+      }
+    } catch {
+    }
+  }
+  binPath = (0, import_normalize.normalizePath)(binPath);
+  if (binPath === ".") {
+    return binPath;
+  }
+  const ext = path.extname(binPath);
+  const extLowered = ext.toLowerCase();
+  const basename = path.basename(binPath, ext);
+  const voltaIndex = basename === "node" ? -1 : /(?<=\/)\.volta\//i.exec(binPath)?.index ?? -1;
+  if (voltaIndex !== -1) {
+    const voltaPath = binPath.slice(0, voltaIndex);
+    const voltaCacheKey = `${voltaPath}:${basename}`;
+    const cachedVolta = import_internal.voltaBinCache.get(voltaCacheKey);
+    if (cachedVolta) {
+      if (fs.existsSync(cachedVolta)) {
+        return cachedVolta;
+      }
+      import_internal.voltaBinCache.delete(voltaCacheKey);
+    }
+    const voltaToolsPath = path.join(voltaPath, "tools");
+    const voltaImagePath = path.join(voltaToolsPath, "image");
+    const voltaUserPath = path.join(voltaToolsPath, "user");
+    const voltaPlatform = (0, import_read_json.readJsonSync)(
+      path.join(voltaUserPath, "platform.json"),
+      { throws: false }
+    );
+    const voltaNodeVersion = voltaPlatform?.node?.runtime;
+    const voltaNpmVersion = voltaPlatform?.node?.npm;
+    let voltaBinPath = "";
+    if (basename === "npm" || basename === "npx") {
+      if (voltaNpmVersion) {
+        const relCliPath = `bin/${basename}-cli.js`;
+        voltaBinPath = path.join(
+          voltaImagePath,
+          `npm/${voltaNpmVersion}/${relCliPath}`
+        );
+        if (voltaNodeVersion && !fs.existsSync(voltaBinPath)) {
+          voltaBinPath = path.join(
+            voltaImagePath,
+            `node/${voltaNodeVersion}/lib/node_modules/npm/${relCliPath}`
+          );
+          if (!fs.existsSync(voltaBinPath)) {
+            voltaBinPath = "";
+          }
+        }
+      }
+    } else {
+      const voltaUserBinPath = path.join(voltaUserPath, "bin");
+      const binInfo = (0, import_read_json.readJsonSync)(
+        path.join(voltaUserBinPath, `${basename}.json`),
+        { throws: false }
+      );
+      const binPackage = binInfo?.package;
+      if (binPackage) {
+        voltaBinPath = path.join(
+          voltaImagePath,
+          `packages/${binPackage}/bin/${basename}`
+        );
+        if (!fs.existsSync(voltaBinPath)) {
+          voltaBinPath = `${voltaBinPath}.cmd`;
+          if (!fs.existsSync(voltaBinPath)) {
+            voltaBinPath = "";
+          }
+        }
+      }
+    }
+    if (voltaBinPath) {
+      let resolvedVoltaPath = voltaBinPath;
+      try {
+        resolvedVoltaPath = (0, import_normalize.normalizePath)(fs.realpathSync.native(voltaBinPath));
+      } catch {
+      }
+      import_internal.voltaBinCache.set(voltaCacheKey, resolvedVoltaPath);
+      return resolvedVoltaPath;
+    }
+  }
+  if (import_platform.WIN32) {
+    const hasKnownExt = extLowered === "" || extLowered === ".cmd" || extLowered === ".exe" || extLowered === ".ps1";
+    const isNpmOrNpx = basename === "npm" || basename === "npx";
+    const isPnpmOrYarn = basename === "pnpm" || basename === "yarn";
+    if (hasKnownExt && isNpmOrNpx) {
+      const quickPath = path.join(
+        path.dirname(binPath),
+        `node_modules/npm/bin/${basename}-cli.js`
+      );
+      if (fs.existsSync(quickPath)) {
+        try {
+          return fs.realpathSync.native(quickPath);
+        } catch {
+        }
+        return quickPath;
+      }
+    }
+    let relPath = "";
+    if (hasKnownExt && // Only parse shell scripts and batch files, not actual executables.
+    // .exe files are already executables and don't need path resolution from wrapper scripts.
+    extLowered !== ".exe" && // Check if file exists before attempting to read it to avoid ENOENT errors.
+    fs.existsSync(binPath)) {
+      const source = fs.readFileSync(binPath, "utf8");
+      if (isNpmOrNpx) {
+        if (extLowered === ".cmd") {
+          relPath = basename === "npm" ? /(?<="NPM_CLI_JS=%~dp0\\).*(?=")/.exec(source)?.[0] || "" : /(?<="NPX_CLI_JS=%~dp0\\).*(?=")/.exec(source)?.[0] || "";
+        } else if (extLowered === "") {
+          relPath = basename === "npm" ? /(?<=NPM_CLI_JS="\$CLI_BASEDIR\/).*(?=")/.exec(source)?.[0] || "" : /(?<=NPX_CLI_JS="\$CLI_BASEDIR\/).*(?=")/.exec(source)?.[0] || "";
+        } else if (extLowered === ".ps1") {
+          relPath = basename === "npm" ? /(?<=\$NPM_CLI_JS="\$PSScriptRoot\/).*(?=")/.exec(
+            source
+          )?.[0] || "" : /(?<=\$NPX_CLI_JS="\$PSScriptRoot\/).*(?=")/.exec(
+            source
+          )?.[0] || "";
+        }
+      } else if (isPnpmOrYarn) {
+        if (extLowered === ".cmd") {
+          relPath = /(?<=node\s+")%~dp0\\([^"]+)(?="\s+%\*)/.exec(source)?.[1] || "";
+          if (!relPath) {
+            relPath = /(?<="%~dp0\\[^"]*node[^"]*"\s+")%~dp0\\([^"]+)(?="\s+%\*)/.exec(
+              source
+            )?.[1] || "";
+          }
+          if (!relPath) {
+            relPath = /(?<="%dp0%\\).*(?=" %\*\r\n)/.exec(source)?.[0] || "";
+          }
+        } else if (extLowered === "") {
+          relPath = /(?<="\$basedir\/)\.tools\/pnpm\/[^"]+(?="\s+"\$@")/.exec(
+            source
+          )?.[0] || "";
+          if (!relPath) {
+            relPath = /(?<=exec\s+node\s+"\$basedir\/)\.tools\/pnpm\/[^"]+(?="\s+"\$@")/.exec(
+              source
+            )?.[0] || "";
+          }
+          if (!relPath) {
+            relPath = /(?<="\$basedir\/).*(?=" "\$@"\n)/.exec(source)?.[0] || "";
+          }
+        } else if (extLowered === ".ps1") {
+          relPath = /(?<="\$basedir\/).*(?=" $args\n)/.exec(source)?.[0] || "";
+        }
+      } else if (extLowered === ".cmd") {
+        relPath = /(?<="%dp0%\\).*(?=" %\*\r\n)/.exec(source)?.[0] || "";
+      } else if (extLowered === "") {
+        relPath = /(?<="$basedir\/).*(?=" "\$@"\n)/.exec(source)?.[0] || "";
+      } else if (extLowered === ".ps1") {
+        relPath = /(?<="\$basedir\/).*(?=" $args\n)/.exec(source)?.[0] || "";
+      }
+      if (relPath) {
+        binPath = (0, import_normalize.normalizePath)(path.resolve(path.dirname(binPath), relPath));
+      }
+    }
+  } else {
+    let hasNoExt = extLowered === "";
+    const isPnpmOrYarn = basename === "pnpm" || basename === "yarn";
+    const isNpmOrNpx = basename === "npm" || basename === "npx";
+    if (isPnpmOrYarn && binPath.includes("/.bin/pnpm/bin/")) {
+      const binIndex = binPath.indexOf("/.bin/pnpm");
+      if (binIndex !== -1) {
+        const baseBinPath = binPath.slice(0, binIndex + "/.bin/pnpm".length);
+        try {
+          const stats = fs.statSync(baseBinPath);
+          if (stats.isFile()) {
+            binPath = (0, import_normalize.normalizePath)(baseBinPath);
+            hasNoExt = !path.extname(binPath);
+          }
+        } catch {
+        }
+      }
+    }
+    if (hasNoExt && (isPnpmOrYarn || isNpmOrNpx) && // For extensionless files (Unix shell scripts), verify existence before reading.
+    // This prevents ENOENT errors when the bin path doesn't exist.
+    fs.existsSync(binPath)) {
+      const source = fs.readFileSync(binPath, "utf8");
+      let relPath = "";
+      if (isPnpmOrYarn) {
+        relPath = /(?<="\$basedir\/)\.tools\/[^"]+(?="\s+"\$@")/.exec(source)?.[0] || "";
+        if (!relPath) {
+          relPath = /(?<="\$basedir\/)[^"]+(?="\s+"\$@")/.exec(source)?.[0] || "";
+        }
+        if (!relPath) {
+          const match = /exec\s+node\s+"?\$basedir\/([^"]+)"?\s+"\$@"/.exec(
+            source
+          );
+          if (match) {
+            relPath = match[1] || "";
+          }
+        }
+        if (relPath && basename === "pnpm" && (0, import_string.StringPrototypeStartsWith)(relPath, "pnpm/")) {
+          relPath = `../${relPath}`;
+        }
+      } else if (isNpmOrNpx) {
+        relPath = basename === "npm" ? /(?<=NPM_CLI_JS="\$CLI_BASEDIR\/).*(?=")/.exec(source)?.[0] || "" : /(?<=NPX_CLI_JS="\$CLI_BASEDIR\/).*(?=")/.exec(source)?.[0] || "";
+      }
+      if (relPath) {
+        binPath = (0, import_normalize.normalizePath)(path.resolve(path.dirname(binPath), relPath));
+      }
+    }
+  }
+  try {
+    const realPath = fs.realpathSync.native(binPath);
+    return (0, import_normalize.normalizePath)(realPath);
+  } catch {
+  }
+  return (0, import_normalize.normalizePath)(binPath);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolveRealBinSync
+});

package/dist/bin/shadow.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file Shadow-bin detection. A "shadow bin" is a binary exposed by a
+ *   transitively-installed `node_modules/.bin` directory rather than the system
+ *   installation. Callers (`findRealBin`) deliberately walk past these to find
+ *   the real interpreter.
+ */
+/**
+ * Check if a directory path contains any shadow bin patterns.
+ *
+ * @example
+ *   ;```typescript
+ *   isShadowBinPath('/tmp/project/node_modules/.bin') // true
+ *   isShadowBinPath('/usr/local/bin') // false
+ *   ```
+ */
+export declare function isShadowBinPath(dirPath: string | undefined): boolean;

package/dist/bin/shadow.js

@@ -0,0 +1,36 @@
+"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 shadow_exports = {};
+__export(shadow_exports, {
+  isShadowBinPath: () => isShadowBinPath
+});
+module.exports = __toCommonJS(shadow_exports);
+function isShadowBinPath(dirPath) {
+  if (!dirPath) {
+    return false;
+  }
+  const normalized = dirPath.replace(/\\/g, "/");
+  return normalized.includes("node_modules/.bin");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isShadowBinPath
+});

package/dist/bin/socket-lib.d.ts

@@ -1,17 +1,13 @@
 #!/usr/bin/env node
 /**
- * @fileoverview `socket-lib` CLI entry point — top-level dispatcher.
- *
- *   socket-lib                          — print help, list commands
- *   socket-lib check <name> [opts...]   — run a fleet-wide check
- *
- * Subcommands live as siblings under `src/bin/`; each is its own
- * file so a misbehaving check can't crash other commands at parse
- * time. The dispatcher just routes; subcommands own their own arg
- * parsing.
- *
- * The CLI is shipped via the `bin` field in package.json and
- * intended to be invoked as `pnpm exec socket-lib <command>` from
- * any consumer that has `@socketsecurity/lib` as a (dev)dependency.
+ * @file `socket-lib` CLI entry point — top-level dispatcher. socket-lib — print
+ *   help, list commands socket-lib check <name> [opts...] — run a fleet-wide
+ *   check Subcommands live as siblings under `src/bin/`; each is its own file
+ *   so a misbehaving check can't crash other commands at parse time. The
+ *   dispatcher just routes; subcommands own their own arg parsing. The CLI is
+ *   shipped via the `bin` field in package.json and intended to be invoked as
+ *   `pnpm exec socket-lib <command>` from any consumer that has
+ *   `@socketsecurity/lib` as a (dev)dependency.
  */
-export {};
+export declare function printHelp(): void;
+export declare function main(args?: readonly string[]): Promise<number>;

package/dist/bin/socket-lib.js

@@ -8,6 +8,10 @@ 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))
@@ -24,8 +28,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var socket_lib_exports = {};
+__export(socket_lib_exports, {
+  main: () => main,
+  printHelp: () => printHelp
+});
+module.exports = __toCommonJS(socket_lib_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_logger = require("../logger");
+var import_logger = require("../logger/logger");
 var import_check = require("./check");
 const logger = (0, import_logger.getDefaultLogger)();
 function printHelp() {
@@ -39,8 +50,7 @@ function printHelp() {
   logger.log("");
   logger.log("Run `socket-lib check --help` for the list of checks.");
 }
-async function main() {
-  const args = import_node_process.default.argv.slice(2);
+async function main(args = import_node_process.default.argv.slice(2)) {
   const command = args[0];
   if (!command || command === "--help" || command === "-h") {
     printHelp();
@@ -62,3 +72,8 @@ if (typeof require !== "undefined" && require.main === module) {
     import_node_process.default.exit(code);
   });
 }
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main,
+  printHelp
+});

package/dist/bin/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Public type surface for `bin/*` modules — the `WhichOptions` interface
+ *   that callers pass to `which`, `whichSync`, `whichReal`, and
+ *   `whichRealSync`. Pure types, no runtime side effects.
+ */
+/**
+ * Options for the which function.
+ */
+export interface WhichOptions {
+    /**
+     * If true, return all matches instead of just the first one.
+     */
+    all?: boolean | undefined;
+    /**
+     * If true, return null instead of throwing when no match is found.
+     */
+    nothrow?: boolean | undefined;
+    /**
+     * Path to search in.
+     */
+    path?: string | undefined;
+    /**
+     * Path separator character.
+     */
+    pathExt?: string | undefined;
+    /**
+     * Environment variables to use.
+     */
+    env?: Record<string, string | undefined> | undefined;
+    /**
+     * Current working directory for resolving relative paths.
+     */
+    cwd?: string | undefined;
+}

package/dist/bin/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/bin/which.d.ts

@@ -0,0 +1,111 @@
+/**
+ * @file Look up binaries on PATH. Two pairs of public functions: `which` /
+ *   `whichSync` — wrap the upstream `which` package, returning the first
+ *   matching path (or array with `{ all: true }`). Path-like inputs (absolute
+ *   paths, `./relative`, `../relative`) bypass PATH resolution and pass through
+ *   unchanged. Both are tolerant — they return `null` for not-found instead of
+ *   throwing. `whichReal` / `whichRealSync` — same but resolve the result
+ *   through `resolveRealBinSync` so the caller gets the underlying script path
+ *   (e.g., `npm-cli.js`) rather than the wrapper. Default `nothrow: true` so a
+ *   missing binary returns `undefined` instead of bubbling a `which` package
+ *   error. Caching matches `_internal.binPathCache` and `binPathAllCache`. Both
+ *   caches validate hits with `existsSync` so a tool reinstall mid-session
+ *   doesn't return a stale path.
+ */
+import type { WhichOptions } from './types';
+/**
+ * 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
+ *
+ * @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'
+ *   ```
+ *
+ * @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.
+ */
+export declare function which(binName: string, options?: WhichOptions): Promise<string | string[] | null>;
+/**
+ * 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.
+ *
+ * @example
+ *   ;```typescript
+ *   const npmPath = await whichReal('npm')
+ *   // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ *   ```
+ *
+ * @throws {Error} If the binary is not found and nothrow is false.
+ */
+export declare function whichReal(binName: string, options?: WhichOptions): Promise<string | string[] | undefined>;
+/**
+ * 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.
+ *
+ * @example
+ *   ;```typescript
+ *   const npmPath = whichRealSync('npm')
+ *   // e.g. '/usr/local/lib/node_modules/npm/bin/npm-cli.js'
+ *   ```
+ *
+ * @throws {Error} If the binary is not found and nothrow is false.
+ */
+export declare function whichRealSync(binName: string, options?: WhichOptions): string | string[] | undefined;
+/**
+ * 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
+ *
+ * @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'
+ *   ```
+ *
+ * @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.
+ */
+export declare function whichSync(binName: string, options?: WhichOptions): string | string[] | null;