@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/bin/check.js

@@ -20,12 +20,13 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var check_exports = {};
 __export(check_exports, {
+  printHelp: () => printHelp,
   runCheck: () => runCheck
 });
 module.exports = __toCommonJS(check_exports);
-var import_logger = require("../logger");
+var import_default = require("../logger/default");
 var import_check_primordials = require("./check-primordials");
-const logger = (0, import_logger.getDefaultLogger)();
+const logger = (0, import_default.getDefaultLogger)();
 const CHECKS = /* @__PURE__ */ new Map([
   ["primordials", "primordials"],
   ["prim", "primordials"]
@@ -62,6 +63,8 @@ async function runCheck(args) {
   switch (canonical) {
     case "primordials":
       return await (0, import_check_primordials.runCheckPrimordials)(args.slice(1));
+    // Unreachable; CHECKS map is exhaustive.
+    /* c8 ignore start */
     default:
       logger.error(`socket-lib check: missing handler for '${canonical}'`);
       return 1;
@@ -69,5 +72,6 @@ async function runCheck(args) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  printHelp,
   runCheck
 });

package/dist/bin/exec.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @file `execBin` — spawn a binary with PATH resolution, wrapper-script
+ *   unwrapping, and Windows shell handling. Order of operations:
+ *
+ *   1. If the input looks like a path (absolute or relative), `resolveRealBinSync`
+ *      it directly so we can spawn the underlying script rather than a
+ *      wrapper.
+ *   2. Otherwise treat it as a binary name and:
+ *
+ *   - Hit `binPathCache`. If valid (`existsSync`), use the cached path; if stale,
+ *     evict.
+ *   - Fall through to `whichReal` for a fresh PATH search; cache the result on
+ *     success.
+ *
+ *   3. Spawn with `shell: WIN32` so `.cmd` wrappers work on Windows; POSIX bypass
+ *      since direct `execve` is faster.
+ *   4. On not-found, throw a typed `ENOENT` error with operator guidance — far
+ *      more useful than a bare "command not found".
+ */
+import type { SpawnOptions } from '../process/spawn/types';
+/**
+ * Execute a binary with the given arguments.
+ *
+ * @example
+ *   ;```typescript
+ *   await execBin('pnpm', ['install'])
+ *   await execBin('/usr/local/bin/node', ['script.js'], { cwd: '/tmp' })
+ *   ```
+ */
+export declare function execBin(binPath: string, args?: string[], options?: SpawnOptions): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer<ArrayBufferLike>;
+    stderr: string | Buffer<ArrayBufferLike>;
+}>;

package/dist/bin/exec.js

@@ -0,0 +1,79 @@
+"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 exec_exports = {};
+__export(exec_exports, {
+  execBin: () => execBin
+});
+module.exports = __toCommonJS(exec_exports);
+var import_platform = require("../constants/platform");
+var import_normalize = require("../paths/normalize");
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_child = require("../process/spawn/child");
+var import_internal = require("./_internal");
+var import_resolve = require("./resolve");
+var import_which = require("./which");
+// @__NO_SIDE_EFFECTS__
+async function execBin(binPath, args, options) {
+  let resolvedPath;
+  if ((0, import_normalize.isPath)(binPath)) {
+    resolvedPath = (0, import_resolve.resolveRealBinSync)(binPath);
+  } else {
+    const cached = import_internal.binPathCache.get(binPath);
+    if (cached) {
+      if ((0, import_internal.getFs)().existsSync(cached)) {
+        resolvedPath = cached;
+      } else {
+        import_internal.binPathCache.delete(binPath);
+      }
+    }
+    if (!resolvedPath) {
+      resolvedPath = await (0, import_which.whichReal)(binPath);
+      if (typeof resolvedPath === "string") {
+        import_internal.binPathCache.set(binPath, resolvedPath);
+      }
+    }
+  }
+  if (!resolvedPath) {
+    const error = new import_error.ErrorCtor(
+      `Binary not found: ${binPath}
+Possible causes:
+  - Binary "${binPath}" is not installed or not in PATH
+  - Binary name is incorrect or misspelled
+  - Installation directory is not in system PATH
+To resolve:
+  1. Verify "${binPath}" is installed: which ${binPath} (Unix) or where ${binPath} (Windows)
+  2. Install the binary if missing, ex: npm install -g ${binPath}
+  3. Check PATH environment variable includes the binary location`
+    );
+    error.code = "ENOENT";
+    throw error;
+  }
+  const binCommand = (0, import_array.ArrayIsArray)(resolvedPath) ? resolvedPath[0] : resolvedPath;
+  return await (0, import_child.spawn)(binCommand, args ?? [], {
+    shell: import_platform.WIN32,
+    ...options
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  execBin
+});

package/dist/bin/find.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @file Find specific package-manager binaries with platform- aware fallbacks.
+ *   `findRealBin` tries common platform paths in order, then falls back to a
+ *   `which` PATH search filtered to skip shadow-bin directories (any path
+ *   containing `node_modules/.bin`). The shadow-bin filter matters because
+ *   tools like ts-node and tsx install fake `npm` / `pnpm` / `yarn` shims into
+ *   the project's `.bin` to intercept the call — those aren't the user's real
+ *   package manager. Per-tool helpers (`findRealNpm`, `findRealPnpm`,
+ *   `findRealYarn`) encode the canonical install layouts:
+ *
+ *   - npm: alongside `process.execPath` first (Node bundles it), then
+ *     `%APPDATA%\npm` on Windows or `/usr/local/bin` / `/usr/bin` on POSIX.
+ *   - pnpm: `~/.local/share/pnpm` (XDG) or `~/.pnpm` on POSIX,
+ *     `%APPDATA%\npm\pnpm` or `%LOCALAPPDATA%\pnpm\pnpm` on Windows.
+ *   - yarn: similar to npm but also `~/.yarn/bin/yarn` on POSIX. Each helper
+ *     returns an empty string when no candidate exists so the caller can fall
+ *     through to `which` on PATH.
+ */
+/**
+ * Find the real executable for a binary, bypassing shadow bins.
+ *
+ * @example
+ *   ;```typescript
+ *   const npmPath = findRealBin('npm', ['/usr/local/bin/npm'])
+ *   const gitPath = findRealBin('git')
+ *   ```
+ */
+export declare function findRealBin(binName: string, commonPaths?: string[]): string | undefined;
+/**
+ * Find the real npm executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ *   ;```typescript
+ *   const npmPath = findRealNpm()
+ *   // e.g. '/usr/local/bin/npm'
+ *   ```
+ */
+export declare function findRealNpm(): string;
+/**
+ * Find the real pnpm executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ *   ;```typescript
+ *   const pnpmPath = findRealPnpm()
+ *   // e.g. '/usr/local/bin/pnpm'
+ *   ```
+ */
+export declare function findRealPnpm(): string;
+/**
+ * Find the real yarn executable, bypassing any aliases and shadow bins.
+ *
+ * @example
+ *   ;```typescript
+ *   const yarnPath = findRealYarn()
+ *   // e.g. '/usr/local/bin/yarn'
+ *   ```
+ */
+export declare function findRealYarn(): string;

package/dist/bin/find.js

@@ -0,0 +1,143 @@
+"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 find_exports = {};
+__export(find_exports, {
+  findRealBin: () => findRealBin,
+  findRealNpm: () => findRealNpm,
+  findRealPnpm: () => findRealPnpm,
+  findRealYarn: () => findRealYarn
+});
+module.exports = __toCommonJS(find_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_platform = require("../constants/platform");
+var import_home = require("../env/home");
+var import_windows = require("../env/windows");
+var import_xdg = require("../env/xdg");
+var import_which = __toESM(require("../external/which"));
+var import_array = require("../primordials/array");
+var import_internal = require("./_internal");
+var import_shadow = require("./shadow");
+var import_which2 = require("./which");
+function findRealBin(binName, commonPaths = []) {
+  const fs = (0, import_internal.getFs)();
+  const path = (0, import_internal.getPath)();
+  for (const binPath of commonPaths) {
+    if (fs.existsSync(binPath)) {
+      return binPath;
+    }
+  }
+  const allPaths = import_which.default.sync(binName, { all: true, nothrow: true }) || [];
+  const pathsArray = (0, import_array.ArrayIsArray)(allPaths) ? allPaths : typeof allPaths === "string" ? [allPaths] : [];
+  if (pathsArray.length === 0) {
+    return void 0;
+  }
+  for (const binPath of pathsArray) {
+    const binDir = path.dirname(binPath);
+    if (!(0, import_shadow.isShadowBinPath)(binDir)) {
+      return binPath;
+    }
+  }
+  return pathsArray[0];
+}
+function findRealNpm() {
+  const fs = (0, import_internal.getFs)();
+  const path = (0, import_internal.getPath)();
+  const nodeDir = path.dirname(import_node_process.default.execPath);
+  const nodeDirCandidates = import_platform.WIN32 ? [path.join(nodeDir, "npm.cmd"), path.join(nodeDir, "npm")] : [path.join(nodeDir, "npm")];
+  for (const candidate of nodeDirCandidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  const appdata = (0, import_windows.getAppdata)();
+  const commonPaths = import_platform.WIN32 ? [
+    appdata ? path.join(appdata, "npm", "npm.cmd") : "",
+    appdata ? path.join(appdata, "npm", "npm") : "",
+    "C:\\Program Files\\nodejs\\npm.cmd",
+    "C:\\Program Files\\nodejs\\npm"
+  ].filter(Boolean) : ["/usr/local/bin/npm", "/usr/bin/npm"];
+  const result = findRealBin("npm", commonPaths);
+  if (result && fs.existsSync(result)) {
+    return result;
+  }
+  const npmPath = (0, import_which2.whichRealSync)("npm", { nothrow: true });
+  if (npmPath && typeof npmPath === "string" && fs.existsSync(npmPath)) {
+    return npmPath;
+  }
+  return "npm";
+}
+function findRealPnpm() {
+  const path = (0, import_internal.getPath)();
+  const home = (0, import_home.getHome)();
+  const appdata = (0, import_windows.getAppdata)();
+  const localappdata = (0, import_windows.getLocalappdata)();
+  const xdgDataHome = (0, import_xdg.getXdgDataHome)();
+  const commonPaths = import_platform.WIN32 ? [
+    appdata ? path.join(appdata, "npm", "pnpm.cmd") : "",
+    appdata ? path.join(appdata, "npm", "pnpm") : "",
+    localappdata ? path.join(localappdata, "pnpm", "pnpm.cmd") : "",
+    localappdata ? path.join(localappdata, "pnpm", "pnpm") : "",
+    "C:\\Program Files\\nodejs\\pnpm.cmd",
+    "C:\\Program Files\\nodejs\\pnpm"
+  ].filter(Boolean) : [
+    "/usr/local/bin/pnpm",
+    "/usr/bin/pnpm",
+    xdgDataHome ? path.join(xdgDataHome, "pnpm/pnpm") : home ? path.join(home, ".local/share/pnpm/pnpm") : "",
+    home ? path.join(home, ".pnpm/pnpm") : ""
+  ].filter(Boolean);
+  return findRealBin("pnpm", commonPaths) ?? "";
+}
+function findRealYarn() {
+  const path = (0, import_internal.getPath)();
+  const home = (0, import_home.getHome)();
+  const appdata = (0, import_windows.getAppdata)();
+  const commonPaths = import_platform.WIN32 ? [
+    appdata ? path.join(appdata, "npm", "yarn.cmd") : "",
+    appdata ? path.join(appdata, "npm", "yarn") : "",
+    home ? path.join(home, ".yarn/bin/yarn.cmd") : "",
+    home ? path.join(home, ".yarn/bin/yarn") : "",
+    "C:\\Program Files\\nodejs\\yarn.cmd",
+    "C:\\Program Files\\nodejs\\yarn"
+  ].filter(Boolean) : [
+    "/usr/local/bin/yarn",
+    "/usr/bin/yarn",
+    home ? path.join(home, ".yarn/bin/yarn") : "",
+    home ? path.join(home, ".config/yarn/global/node_modules/.bin/yarn") : ""
+  ].filter(Boolean);
+  return findRealBin("yarn", commonPaths) ?? "";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findRealBin,
+  findRealNpm,
+  findRealPnpm,
+  findRealYarn
+});

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;