@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/arrays/unique.js

@@ -0,0 +1,34 @@
+"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 unique_exports = {};
+__export(unique_exports, {
+  arrayUnique: () => arrayUnique
+});
+module.exports = __toCommonJS(unique_exports);
+var import_map_set = require("../primordials/map-set");
+// @__NO_SIDE_EFFECTS__
+function arrayUnique(arr) {
+  return [...new import_map_set.SetCtor(arr)];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  arrayUnique
+});

package/dist/bin/_internal.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file Private internals for `bin/*` modules — lazy `fs` / `path` accessors
+ *   and the binary-resolution caches. Underscore prefix keeps this file out of
+ *   the public exports map (see the `dist/<dir>/_<file>` ignore in
+ *   scripts/fix/generate-package-exports.mts). Two caches:
+ *
+ *   1. `binPathCache` — maps a binary name to its first resolved path. Validated
+ *      with `existsSync` before reuse so a stale cache doesn't survive a tool
+ *      reinstall mid-session.
+ *   2. `binPathAllCache` — same shape but stores all-match arrays for callers that
+ *      pass `{ all: true }`. Separate cache because the two return shapes can't
+ *      be reconciled without losing type info.
+ *   3. `voltaBinCache` — maps a `${voltaPath}:${basename}` composite key to the
+ *      resolved Volta-managed binary path. Volta resolves npm / pnpm / yarn
+ *      through a layered tools/image directory and the lookup is expensive
+ *      enough that caching is worth the memory.
+ */
+export declare const binPathCache: Map<string, string>;
+export declare const binPathAllCache: Map<string, string[]>;
+export declare const voltaBinCache: Map<string, string>;
+export { getNodeFs as getFs } from '../node/fs';
+export { getNodePath as getPath } from '../node/path';

package/dist/bin/_internal.js

@@ -0,0 +1,43 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  binPathAllCache: () => binPathAllCache,
+  binPathCache: () => binPathCache,
+  getFs: () => import_fs.getNodeFs,
+  getPath: () => import_path.getNodePath,
+  voltaBinCache: () => voltaBinCache
+});
+module.exports = __toCommonJS(internal_exports);
+var import_map_set = require("../primordials/map-set");
+var import_fs = require("../node/fs");
+var import_path = require("../node/path");
+const binPathCache = new import_map_set.MapCtor();
+const binPathAllCache = new import_map_set.MapCtor();
+const voltaBinCache = new import_map_set.MapCtor();
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  binPathAllCache,
+  binPathCache,
+  getFs,
+  getPath,
+  voltaBinCache
+});

package/dist/bin/check-primordials.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file `socket-lib check primordials` handler. Loads a JSON config from disk
+ *   (default `primordials-coverage.config.json` at the repo root, override with
+ *   `--config <path>`), runs the drift check, and renders the result.
+ *   socket-lib check primordials socket-lib check primordials --config
+ *   ./primordials.config.json socket-lib check primordials --json #
+ *   machine-readable output socket-lib check primordials --explain # one
+ *   detailed line per finding socket-lib check primordials --silent # silent on
+ *   success Exit codes: 0 — no drift 1 — drift detected (or config / lookup
+ *   error)
+ */
+import { type PrimordialsCheckConfig, type PrimordialsCheckResult, type PrimordialsFinding } from '../checks/primordials';
+interface ParsedArgs {
+    readonly config: string | undefined;
+    readonly json: boolean;
+    readonly explain: boolean;
+    readonly silent: boolean;
+    readonly help: boolean;
+}
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/**
+ * Pick the config file. Returns the explicit `--config` argument when given
+ * (even if it doesn't exist — the caller will surface the error with the path
+ * they typed). Otherwise probes the fallback list in order and returns the
+ * first hit. Returns the head of the list when none exist, so the caller's
+ * "config file not found" error message names the canonical default.
+ */
+export declare function resolveConfigPath(explicit: string | undefined): string;
+export declare function printHelp(): void;
+export declare function loadConfig(configPath: string): PrimordialsCheckConfig;
+interface SerializedFinding {
+    kind: PrimordialsFinding['kind'];
+    name: string;
+    files: readonly string[];
+    hint: string;
+}
+export declare function serialize(result: PrimordialsCheckResult): {
+    ok: boolean;
+    used: number;
+    findings: SerializedFinding[];
+};
+export declare function renderHuman(result: PrimordialsCheckResult, args: ParsedArgs): void;
+export declare function runCheckPrimordials(argv: readonly string[]): Promise<number>;
+export {};

package/dist/bin/check-primordials.js

@@ -0,0 +1,245 @@
+"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 check_primordials_exports = {};
+__export(check_primordials_exports, {
+  loadConfig: () => loadConfig,
+  parseArgs: () => parseArgs,
+  printHelp: () => printHelp,
+  renderHuman: () => renderHuman,
+  resolveConfigPath: () => resolveConfigPath,
+  runCheckPrimordials: () => runCheckPrimordials,
+  serialize: () => serialize
+});
+module.exports = __toCommonJS(check_primordials_exports);
+var import_node_fs = require("node:fs");
+var import_node_path = __toESM(require("node:path"));
+var import_node_process = __toESM(require("node:process"));
+var import_message = require("../errors/message");
+var import_logger = require("../logger/logger");
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_object = require("../primordials/object");
+var import_primordials = require("../checks/primordials");
+var import_parse = require("../argv/parse");
+const logger = (0, import_logger.getDefaultLogger)();
+const DEFAULT_CONFIG_PATH = ".socket-lib.json";
+const FALLBACK_CONFIG_PATHS = [
+  ".socket-lib.json",
+  ".config/socket-lib.json"
+];
+const CONFIG_SECTION = "primordials";
+function parseArgs(argv) {
+  const { values } = (0, import_parse.parseArgs)({
+    args: argv,
+    strict: false,
+    options: {
+      config: { type: "string", short: "c" },
+      explain: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      json: { type: "boolean" },
+      silent: { type: "boolean" }
+    }
+  });
+  const explicitConfig = values["config"];
+  return {
+    config: typeof explicitConfig === "string" ? explicitConfig : void 0,
+    json: Boolean(values["json"]),
+    explain: Boolean(values["explain"]),
+    silent: Boolean(values["silent"]),
+    help: Boolean(values["help"])
+  };
+}
+function resolveConfigPath(explicit) {
+  if (explicit !== void 0) {
+    return explicit;
+  }
+  for (const candidate of FALLBACK_CONFIG_PATHS) {
+    if ((0, import_node_fs.existsSync)(import_node_path.default.resolve(candidate))) {
+      return candidate;
+    }
+  }
+  return FALLBACK_CONFIG_PATHS[0];
+}
+function printHelp() {
+  logger.log("socket-lib check primordials \u2014 primordials drift check");
+  logger.log("");
+  logger.log("Usage:");
+  logger.log("  socket-lib check primordials [opts]");
+  logger.log("  socket-lib check prim        [opts]    # short alias");
+  logger.log("");
+  logger.log("Options:");
+  logger.log(
+    `  --config, -c <path>   Config file. Default: ${DEFAULT_CONFIG_PATH}`
+  );
+  logger.log(`                        (falls back to .config/socket-lib.json)`);
+  logger.log("  --explain             Print one detailed line per finding.");
+  logger.log("  --json                Machine-readable JSON output.");
+  logger.log("  --silent              Silent on success.");
+  logger.log("  --help, -h            Print this help.");
+  logger.log("");
+  logger.log("Config (.socket-lib.json \u2014 primordials section):");
+  logger.log("  {");
+  logger.log('    "primordials": {');
+  logger.log('      "aliasMap":         { "Array": "ArrayCtor" },');
+  logger.log('      "nodeInternalOnly": ["SafeMap", "SafeSet"],');
+  logger.log(
+    '      "scanDirs":         ["src", "additions/source-patched/lib"]'
+  );
+  logger.log("    }");
+  logger.log("  }");
+  logger.log("");
+  logger.log("A bare object (no `primordials` section) is also accepted for");
+  logger.log("repos that only run this one check.");
+}
+function loadConfig(configPath) {
+  if (!(0, import_node_fs.existsSync)(configPath)) {
+    throw new import_error.ErrorCtor(`config file not found: ${configPath}`);
+  }
+  let parsed;
+  try {
+    parsed = (0, import_json.JSONParse)((0, import_node_fs.readFileSync)(configPath, "utf8"));
+  } catch (e) {
+    throw new import_error.ErrorCtor(`config file is not valid JSON: ${(0, import_message.errorMessage)(e)}`);
+  }
+  if (typeof parsed !== "object" || parsed === null || (0, import_array.ArrayIsArray)(parsed)) {
+    throw new import_error.ErrorCtor("config root must be an object");
+  }
+  const root = parsed;
+  const sectional = root[CONFIG_SECTION];
+  const raw = sectional !== void 0 ? sectional : root;
+  if (!(0, import_array.ArrayIsArray)(raw.scanDirs)) {
+    throw new import_error.ErrorCtor(
+      `config.scanDirs must be an array of strings (got ${typeof raw.scanDirs})`
+    );
+  }
+  for (const [i, v] of raw.scanDirs.entries()) {
+    if (typeof v !== "string") {
+      throw new import_error.ErrorCtor(`config.scanDirs[${i}] must be a string`);
+    }
+  }
+  if (raw.aliasMap !== void 0 && (typeof raw.aliasMap !== "object" || raw.aliasMap === null || (0, import_array.ArrayIsArray)(raw.aliasMap))) {
+    throw new import_error.ErrorCtor("config.aliasMap must be an object of source\u2192target");
+  }
+  if (raw.nodeInternalOnly !== void 0 && !(0, import_array.ArrayIsArray)(raw.nodeInternalOnly)) {
+    throw new import_error.ErrorCtor("config.nodeInternalOnly must be an array of strings");
+  }
+  const aliasMap = new Map(
+    (0, import_object.ObjectEntries)(raw.aliasMap ?? {})
+  );
+  const nodeInternalOnly = new Set(
+    (raw.nodeInternalOnly ?? []).filter(
+      (x) => typeof x === "string"
+    )
+  );
+  return {
+    scanDirs: raw.scanDirs,
+    aliasMap,
+    nodeInternalOnly,
+    socketLibPrimordialsPath: typeof raw.socketLibPrimordialsPath === "string" ? raw.socketLibPrimordialsPath : void 0,
+    repoRoot: import_node_process.default.cwd()
+  };
+}
+function serialize(result) {
+  return {
+    ok: result.findings.length === 0,
+    used: result.used.size,
+    findings: result.findings.map((f) => ({
+      kind: f.kind,
+      name: f.name,
+      files: f.files,
+      hint: f.hint
+    }))
+  };
+}
+function renderHuman(result, args) {
+  if (result.findings.length === 0) {
+    if (!args.silent) {
+      logger.success(
+        `Primordials coverage OK \u2014 ${result.used.size} names used, all accounted for.`
+      );
+    }
+    return;
+  }
+  logger.error(
+    `Primordials drift detected \u2014 ${result.findings.length} unaccounted name(s):`
+  );
+  for (const f of result.findings) {
+    logger.error(`  ${f.name}`);
+    if (args.explain) {
+      logger.error(`    ${f.hint}`);
+      if (f.files.length > 0) {
+        logger.error(`    files: ${f.files.join(", ")}`);
+      }
+    }
+  }
+  if (!args.explain) {
+    logger.error("");
+    logger.error("Run with --explain for fix instructions and file references.");
+  }
+}
+async function runCheckPrimordials(argv) {
+  const args = parseArgs(argv);
+  if (args.help) {
+    printHelp();
+    return 0;
+  }
+  let config;
+  try {
+    config = loadConfig(import_node_path.default.resolve(resolveConfigPath(args.config)));
+  } catch (e) {
+    logger.error(`socket-lib check primordials: ${(0, import_message.errorMessage)(e)}`);
+    return 1;
+  }
+  let result;
+  try {
+    result = (0, import_primordials.checkPrimordials)(config);
+  } catch (e) {
+    logger.error(`socket-lib check primordials: ${(0, import_message.errorMessage)(e)}`);
+    return 1;
+  }
+  if (args.json) {
+    logger.log((0, import_json.JSONStringify)(serialize(result), null, 2));
+  } else {
+    renderHuman(result, args);
+  }
+  return result.findings.length === 0 ? 0 : 1;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  loadConfig,
+  parseArgs,
+  printHelp,
+  renderHuman,
+  resolveConfigPath,
+  runCheckPrimordials,
+  serialize
+});

package/dist/bin/check.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file `socket-lib check <name>` subcommand group. Routes to per-check
+ *   handlers by name. Each check resolves its config file and runs its check;
+ *   the group itself just dispatches and prints help. Available checks:
+ *   primordials Drift between a repo's `primordials` destructures and
+ *   socket-lib's userland mirror. Aliases let callers shorten the common ones:
+ *   prim → primordials.
+ */
+export declare function printHelp(): void;
+export declare function runCheck(args: readonly string[]): Promise<number>;

package/dist/bin/check.js

@@ -0,0 +1,77 @@
+"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 check_exports = {};
+__export(check_exports, {
+  printHelp: () => printHelp,
+  runCheck: () => runCheck
+});
+module.exports = __toCommonJS(check_exports);
+var import_logger = require("../logger/logger");
+var import_check_primordials = require("./check-primordials");
+const logger = (0, import_logger.getDefaultLogger)();
+const CHECKS = /* @__PURE__ */ new Map([
+  ["primordials", "primordials"],
+  ["prim", "primordials"]
+]);
+const ALIASES = /* @__PURE__ */ new Map([
+  ["primordials", ["prim"]]
+]);
+function printHelp() {
+  logger.log("socket-lib check \u2014 fleet-wide static-analysis checks");
+  logger.log("");
+  logger.log("Usage:");
+  logger.log("  socket-lib check <name> [...opts]");
+  logger.log("");
+  logger.log("Checks:");
+  for (const [canonical, aliases] of ALIASES) {
+    const aliasStr = aliases.length > 0 ? ` (alias: ${aliases.join(", ")})` : "";
+    logger.log(`  ${canonical}${aliasStr}`);
+  }
+  logger.log("");
+  logger.log("Run `socket-lib check <name> --help` for check-specific options.");
+}
+async function runCheck(args) {
+  const name = args[0];
+  if (!name || name === "--help" || name === "-h") {
+    printHelp();
+    return 0;
+  }
+  const canonical = CHECKS.get(name);
+  if (!canonical) {
+    logger.error(`socket-lib check: unknown check '${name}'`);
+    logger.error("Run `socket-lib check --help` for the list of checks.");
+    return 1;
+  }
+  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;
+  }
+}
+// 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 '../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_spawn = require("../spawn/spawn");
+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_spawn.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;