@socketsecurity/lib 5.6.0 → 5.7.0

package/dist/dlx/manifest.js

@@ -47,12 +47,12 @@ function getPath() {
 }
 const logger = (0, import_logger.getDefaultLogger)();
 const MANIFEST_FILE_NAME = ".dlx-manifest.json";
-function isPackageEntry(entry) {
-  return entry.type === "package";
-}
 function isBinaryEntry(entry) {
   return entry.type === "binary";
 }
+function isPackageEntry(entry) {
+  return entry.type === "package";
+}
 class DlxManifest {
   manifestPath;
   lockPath;
@@ -62,6 +62,7 @@ class DlxManifest {
   }
   /**
    * Read the entire manifest file.
+   * @private
    */
   readManifest() {
     try {
@@ -81,61 +82,9 @@ class DlxManifest {
       return /* @__PURE__ */ Object.create(null);
     }
   }
-  /**
-   * Get a manifest entry by spec (e.g., "@socketsecurity/cli@^2.0.11").
-   */
-  getManifestEntry(spec) {
-    const data = this.readManifest();
-    const entry = data[spec];
-    if (entry && "type" in entry) {
-      return entry;
-    }
-    return void 0;
-  }
-  /**
-   * Get cached update information for a package (legacy format).
-   * @deprecated Use getManifestEntry() for new code.
-   */
-  get(name) {
-    const data = this.readManifest();
-    const entry = data[name];
-    if (entry && !("type" in entry)) {
-      return entry;
-    }
-    return void 0;
-  }
-  /**
-   * Set a package manifest entry.
-   */
-  async setPackageEntry(spec, cacheKey, details) {
-    await import_process_lock.processLock.withLock(this.lockPath, async () => {
-      const data = this.readManifest();
-      data[spec] = {
-        type: "package",
-        cache_key: cacheKey,
-        timestamp: Date.now(),
-        details
-      };
-      await this.writeManifest(data);
-    });
-  }
-  /**
-   * Set a binary manifest entry.
-   */
-  async setBinaryEntry(spec, cacheKey, details) {
-    await import_process_lock.processLock.withLock(this.lockPath, async () => {
-      const data = this.readManifest();
-      data[spec] = {
-        type: "binary",
-        cache_key: cacheKey,
-        timestamp: Date.now(),
-        details
-      };
-      await this.writeManifest(data);
-    });
-  }
   /**
    * Write the manifest file atomically.
+   * @private
    */
   async writeManifest(data) {
     const manifestDir = (/* @__PURE__ */ getPath()).dirname(this.manifestPath);
@@ -167,56 +116,6 @@ class DlxManifest {
       throw error;
     }
   }
-  /**
-   * Store update information for a package (legacy format).
-   * @deprecated Use setPackageEntry() for new code.
-   */
-  async set(name, record) {
-    await import_process_lock.processLock.withLock(this.lockPath, async () => {
-      let data = /* @__PURE__ */ Object.create(null);
-      try {
-        if ((/* @__PURE__ */ getFs()).existsSync(this.manifestPath)) {
-          const content2 = (/* @__PURE__ */ getFs()).readFileSync(this.manifestPath, "utf8");
-          if (content2.trim()) {
-            data = JSON.parse(content2);
-          }
-        }
-      } catch (error) {
-        logger.warn(
-          `Failed to read existing manifest: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-      data[name] = record;
-      const manifestDir = (/* @__PURE__ */ getPath()).dirname(this.manifestPath);
-      try {
-        (0, import_fs.safeMkdirSync)(manifestDir, { recursive: true });
-      } catch (error) {
-        logger.warn(
-          `Failed to create manifest directory: ${error instanceof Error ? error.message : String(error)}`
-        );
-      }
-      const content = JSON.stringify(data, null, 2);
-      const tempPath = `${this.manifestPath}.tmp`;
-      try {
-        (/* @__PURE__ */ getFs()).writeFileSync(tempPath, content, "utf8");
-        (/* @__PURE__ */ getFs()).writeFileSync(this.manifestPath, content, "utf8");
-        try {
-          if ((/* @__PURE__ */ getFs()).existsSync(tempPath)) {
-            (/* @__PURE__ */ getFs()).unlinkSync(tempPath);
-          }
-        } catch {
-        }
-      } catch (error) {
-        try {
-          if ((/* @__PURE__ */ getFs()).existsSync(tempPath)) {
-            (/* @__PURE__ */ getFs()).unlinkSync(tempPath);
-          }
-        } catch {
-        }
-        throw error;
-      }
-    });
-  }
   /**
    * Clear cached data for a specific entry.
    */
@@ -258,14 +157,16 @@ class DlxManifest {
     });
   }
   /**
-   * Check if cached data is fresh based on TTL.
+   * Get cached update information for a package (legacy format).
+   * @deprecated Use getManifestEntry() for new code.
    */
-  isFresh(record, ttlMs) {
-    if (!record) {
-      return false;
+  get(name) {
+    const data = this.readManifest();
+    const entry = data[name];
+    if (entry && !("type" in entry)) {
+      return entry;
     }
-    const age = Date.now() - record.timestampFetch;
-    return age < ttlMs;
+    return void 0;
   }
   /**
    * Get all cached package names.
@@ -289,6 +190,107 @@ class DlxManifest {
       return [];
     }
   }
+  /**
+   * Get a manifest entry by spec (e.g., "@socketsecurity/cli@^2.0.11").
+   */
+  getManifestEntry(spec) {
+    const data = this.readManifest();
+    const entry = data[spec];
+    if (entry && "type" in entry) {
+      return entry;
+    }
+    return void 0;
+  }
+  /**
+   * Check if cached data is fresh based on TTL.
+   */
+  isFresh(record, ttlMs) {
+    if (!record) {
+      return false;
+    }
+    const age = Date.now() - record.timestampFetch;
+    return age < ttlMs;
+  }
+  /**
+   * Store update information for a package (legacy format).
+   * @deprecated Use setPackageEntry() for new code.
+   */
+  async set(name, record) {
+    await import_process_lock.processLock.withLock(this.lockPath, async () => {
+      let data = /* @__PURE__ */ Object.create(null);
+      try {
+        if ((/* @__PURE__ */ getFs()).existsSync(this.manifestPath)) {
+          const content2 = (/* @__PURE__ */ getFs()).readFileSync(this.manifestPath, "utf8");
+          if (content2.trim()) {
+            data = JSON.parse(content2);
+          }
+        }
+      } catch (error) {
+        logger.warn(
+          `Failed to read existing manifest: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      data[name] = record;
+      const manifestDir = (/* @__PURE__ */ getPath()).dirname(this.manifestPath);
+      try {
+        (0, import_fs.safeMkdirSync)(manifestDir, { recursive: true });
+      } catch (error) {
+        logger.warn(
+          `Failed to create manifest directory: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+      const content = JSON.stringify(data, null, 2);
+      const tempPath = `${this.manifestPath}.tmp`;
+      try {
+        (/* @__PURE__ */ getFs()).writeFileSync(tempPath, content, "utf8");
+        (/* @__PURE__ */ getFs()).writeFileSync(this.manifestPath, content, "utf8");
+        try {
+          if ((/* @__PURE__ */ getFs()).existsSync(tempPath)) {
+            (/* @__PURE__ */ getFs()).unlinkSync(tempPath);
+          }
+        } catch {
+        }
+      } catch (error) {
+        try {
+          if ((/* @__PURE__ */ getFs()).existsSync(tempPath)) {
+            (/* @__PURE__ */ getFs()).unlinkSync(tempPath);
+          }
+        } catch {
+        }
+        throw error;
+      }
+    });
+  }
+  /**
+   * Set a binary manifest entry.
+   */
+  async setBinaryEntry(spec, cacheKey, details) {
+    await import_process_lock.processLock.withLock(this.lockPath, async () => {
+      const data = this.readManifest();
+      data[spec] = {
+        type: "binary",
+        cache_key: cacheKey,
+        timestamp: Date.now(),
+        details
+      };
+      await this.writeManifest(data);
+    });
+  }
+  /**
+   * Set a package manifest entry.
+   */
+  async setPackageEntry(spec, cacheKey, details) {
+    await import_process_lock.processLock.withLock(this.lockPath, async () => {
+      const data = this.readManifest();
+      data[spec] = {
+        type: "package",
+        cache_key: cacheKey,
+        timestamp: Date.now(),
+        details
+      };
+      await this.writeManifest(data);
+    });
+  }
 }
 const dlxManifest = new DlxManifest();
 // Annotate the CommonJS export names for ESM import in node:

package/dist/dlx/package.d.ts

@@ -99,6 +99,15 @@ export declare function dlxPackage(args: readonly string[] | string[], options?:
  * ```
  */
 export declare function downloadPackage(options: DlxPackageOptions): Promise<DownloadPackageResult>;
+/**
+ * Install package to ~/.socket/_dlx/<hash>/ if not already installed.
+ * Uses pacote for installation (no npm CLI required).
+ * Protected by process lock to prevent concurrent installation corruption.
+ */
+export declare function ensurePackageInstalled(packageName: string, packageSpec: string, force: boolean): Promise<{
+    installed: boolean;
+    packageDir: string;
+}>;
 /**
  * Execute a package's binary with cross-platform shell handling.
  * The package must already be installed (use downloadPackage first).
@@ -118,3 +127,49 @@ export declare function downloadPackage(options: DlxPackageOptions): Promise<Dow
  * ```
  */
 export declare function executePackage(binaryPath: string, args: readonly string[] | string[], spawnOptions?: SpawnOptions | undefined, spawnExtra?: SpawnExtra | undefined): ReturnType<typeof spawn>;
+/**
+ * Find the binary path for an installed package.
+ * Uses npm's bin resolution strategy with user-friendly fallbacks.
+ * Resolves platform-specific wrappers (.cmd, .ps1, etc.) on Windows.
+ *
+ * Resolution strategy (cherry-picked from libnpmexec):
+ * 1. Use npm's getBinFromManifest (handles aliases and standard cases)
+ * 2. Fall back to user-provided binaryName if npm's strategy fails
+ * 3. Try last segment of package name as final fallback
+ * 4. Use first binary as last resort
+ */
+export declare function findBinaryPath(packageDir: string, packageName: string, binaryName?: string): string;
+/**
+ * Make all binaries in an installed package executable.
+ * Reads the package.json bin field and makes all binaries executable (chmod 0o755).
+ * Handles both single binary (string) and multiple binaries (object) formats.
+ *
+ * Aligns with npm's approach:
+ * - Uses 0o755 permission (matches npm's cmd-shim)
+ * - Reads bin field from package.json (matches npm's bin-links and libnpmexec)
+ * - Handles both string and object bin formats
+ *
+ * References:
+ * - npm cmd-shim: https://github.com/npm/cmd-shim/blob/main/lib/index.js
+ * - npm getBinFromManifest: https://github.com/npm/libnpmexec/blob/main/lib/get-bin-from-manifest.js
+ */
+export declare function makePackageBinsExecutable(packageDir: string, packageName: string): void;
+/**
+ * Parse package spec into name and version using npm-package-arg.
+ * Examples:
+ * - 'lodash@4.17.21' → { name: 'lodash', version: '4.17.21' }
+ * - '@scope/pkg@1.0.0' → { name: '@scope/pkg', version: '1.0.0' }
+ * - 'lodash' → { name: 'lodash', version: undefined }
+ */
+export declare function parsePackageSpec(spec: string): {
+    name: string;
+    version: string | undefined;
+};
+/**
+ * Resolve binary path with cross-platform wrapper support.
+ * On Windows, checks for .cmd, .bat, .ps1, .exe wrappers in order.
+ * On Unix, uses path directly.
+ *
+ * Aligns with npm/npx binary resolution strategy.
+ */
+export declare function resolveBinaryPath(basePath: string): string;

package/dist/dlx/package.js

@@ -31,7 +31,12 @@ var package_exports = {};
 __export(package_exports, {
   dlxPackage: () => dlxPackage,
   downloadPackage: () => downloadPackage,
-  executePackage: () => executePackage
+  ensurePackageInstalled: () => ensurePackageInstalled,
+  executePackage: () => executePackage,
+  findBinaryPath: () => findBinaryPath,
+  makePackageBinsExecutable: () => makePackageBinsExecutable,
+  parsePackageSpec: () => parsePackageSpec,
+  resolveBinaryPath: () => resolveBinaryPath
 });
 module.exports = __toCommonJS(package_exports);
 var import_platform = require("../constants/platform");
@@ -61,24 +66,45 @@ function getPath() {
   return _path;
 }
 const rangeOperatorsRegExp = /[~^><=xX* ]|\|\|/;
-function parsePackageSpec(spec) {
-  try {
-    const parsed = (0, import_npm_package_arg.default)(spec);
-    const version = parsed.type === "tag" ? parsed.fetchSpec : parsed.type === "version" || parsed.type === "range" ? parsed.fetchSpec : void 0;
-    return {
-      name: parsed.name || spec,
-      version
-    };
-  } catch {
-    const atIndex = spec.lastIndexOf("@");
-    if (atIndex === -1 || spec.startsWith("@")) {
-      return { name: spec, version: void 0 };
-    }
-    return {
-      name: spec.slice(0, atIndex),
-      version: spec.slice(atIndex + 1)
-    };
-  }
+async function dlxPackage(args, options, spawnExtra) {
+  const downloadResult = await downloadPackage(options);
+  const spawnPromise = executePackage(
+    downloadResult.binaryPath,
+    args,
+    options?.spawnOptions,
+    spawnExtra
+  );
+  return {
+    ...downloadResult,
+    spawnPromise
+  };
+}
+async function downloadPackage(options) {
+  const {
+    binaryName,
+    force: userForce,
+    package: packageSpec,
+    yes
+  } = {
+    __proto__: null,
+    ...options
+  };
+  const { name: packageName, version: packageVersion } = parsePackageSpec(packageSpec);
+  const isVersionRange = packageVersion !== void 0 && rangeOperatorsRegExp.test(packageVersion);
+  const force = userForce !== void 0 ? userForce : yes === true ? true : isVersionRange;
+  const fullPackageSpec = packageVersion ? `${packageName}@${packageVersion}` : packageName;
+  const { installed, packageDir } = await ensurePackageInstalled(
+    packageName,
+    fullPackageSpec,
+    force
+  );
+  const binaryPath = findBinaryPath(packageDir, packageName, binaryName);
+  makePackageBinsExecutable(packageDir, packageName);
+  return {
+    binaryPath,
+    installed,
+    packageDir
+  };
 }
 async function ensurePackageInstalled(packageName, packageSpec, force) {
   const fs = /* @__PURE__ */ getFs();
@@ -172,19 +198,13 @@ Check npm registry connectivity or package name.`,
     }
   );
 }
-function resolveBinaryPath(basePath) {
-  if (!import_platform.WIN32) {
-    return basePath;
-  }
-  const fs = /* @__PURE__ */ getFs();
-  const extensions = [".cmd", ".bat", ".ps1", ".exe", ""];
-  for (const ext of extensions) {
-    const testPath = basePath + ext;
-    if (fs.existsSync(testPath)) {
-      return testPath;
-    }
-  }
-  return basePath;
+function executePackage(binaryPath, args, spawnOptions, spawnExtra) {
+  const needsShell = import_platform.WIN32 && /\.(?:bat|cmd|ps1)$/i.test(binaryPath);
+  const finalOptions = needsShell ? {
+    ...spawnOptions,
+    shell: true
+  } : spawnOptions;
+  return (0, import_spawn.spawn)(binaryPath, args, finalOptions, spawnExtra);
 }
 function findBinaryPath(packageDir, packageName, binaryName) {
   const path = /* @__PURE__ */ getPath();
@@ -240,19 +260,6 @@ function findBinaryPath(packageDir, packageName, binaryName) {
   const rawPath = (0, import_normalize.normalizePath)(path.join(installedDir, binPath));
   return resolveBinaryPath(rawPath);
 }
-async function dlxPackage(args, options, spawnExtra) {
-  const downloadResult = await downloadPackage(options);
-  const spawnPromise = executePackage(
-    downloadResult.binaryPath,
-    args,
-    options?.spawnOptions,
-    spawnExtra
-  );
-  return {
-    ...downloadResult,
-    spawnPromise
-  };
-}
 function makePackageBinsExecutable(packageDir, packageName) {
   if (import_platform.WIN32) {
     return;
@@ -288,44 +295,47 @@ function makePackageBinsExecutable(packageDir, packageName) {
   } catch {
   }
 }
-async function downloadPackage(options) {
-  const {
-    binaryName,
-    force: userForce,
-    package: packageSpec,
-    yes
-  } = {
-    __proto__: null,
-    ...options
-  };
-  const { name: packageName, version: packageVersion } = parsePackageSpec(packageSpec);
-  const isVersionRange = packageVersion !== void 0 && rangeOperatorsRegExp.test(packageVersion);
-  const force = userForce !== void 0 ? userForce : yes === true ? true : isVersionRange;
-  const fullPackageSpec = packageVersion ? `${packageName}@${packageVersion}` : packageName;
-  const { installed, packageDir } = await ensurePackageInstalled(
-    packageName,
-    fullPackageSpec,
-    force
-  );
-  const binaryPath = findBinaryPath(packageDir, packageName, binaryName);
-  makePackageBinsExecutable(packageDir, packageName);
-  return {
-    binaryPath,
-    installed,
-    packageDir
-  };
+function parsePackageSpec(spec) {
+  try {
+    const parsed = (0, import_npm_package_arg.default)(spec);
+    const version = parsed.type === "tag" ? parsed.fetchSpec : parsed.type === "version" || parsed.type === "range" ? parsed.fetchSpec : void 0;
+    return {
+      name: parsed.name || spec,
+      version
+    };
+  } catch {
+    const atIndex = spec.lastIndexOf("@");
+    if (atIndex === -1 || atIndex === 0) {
+      return { name: spec, version: void 0 };
+    }
+    return {
+      name: spec.slice(0, atIndex),
+      version: spec.slice(atIndex + 1)
+    };
+  }
 }
-function executePackage(binaryPath, args, spawnOptions, spawnExtra) {
-  const needsShell = import_platform.WIN32 && /\.(?:bat|cmd|ps1)$/i.test(binaryPath);
-  const finalOptions = needsShell ? {
-    ...spawnOptions,
-    shell: true
-  } : spawnOptions;
-  return (0, import_spawn.spawn)(binaryPath, args, finalOptions, spawnExtra);
+function resolveBinaryPath(basePath) {
+  if (!import_platform.WIN32) {
+    return basePath;
+  }
+  const fs = /* @__PURE__ */ getFs();
+  const extensions = [".cmd", ".bat", ".ps1", ".exe", ""];
+  for (const ext of extensions) {
+    const testPath = basePath + ext;
+    if (fs.existsSync(testPath)) {
+      return testPath;
+    }
+  }
+  return basePath;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   dlxPackage,
   downloadPackage,
-  executePackage
+  ensurePackageInstalled,
+  executePackage,
+  findBinaryPath,
+  makePackageBinsExecutable,
+  parsePackageSpec,
+  resolveBinaryPath
 });

package/dist/env/ci.js

@@ -22,11 +22,10 @@ __export(ci_exports, {
   getCI: () => getCI
 });
 module.exports = __toCommonJS(ci_exports);
-var import_helpers = require("./helpers");
 var import_rewire = require("./rewire");
 // @__NO_SIDE_EFFECTS__
 function getCI() {
-  return (0, import_helpers.envAsBoolean)((0, import_rewire.getEnvValue)("CI"));
+  return (0, import_rewire.isInEnv)("CI");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/env/rewire.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Clear a specific environment variable override.
+ */
+export declare function clearEnv(key: string): void;
 /**
  * Get an environment variable value, checking overrides first.
  *
@@ -9,6 +13,35 @@
  * @internal Used by env getters to support test rewiring
  */
 export declare function getEnvValue(key: string): string | undefined;
+/**
+ * Check if an environment variable has been overridden.
+ */
+export declare function hasOverride(key: string): boolean;
+/**
+ * Check if an environment variable exists (has a key), checking overrides first.
+ *
+ * Resolution order:
+ * 1. Isolated overrides (temporary - set via withEnv/withEnvSync)
+ * 2. Shared overrides (persistent - set via setEnv in beforeEach)
+ * 3. process.env (including vi.stubEnv modifications)
+ *
+ * @internal Used by env getters to check for key presence (not value truthiness)
+ */
+export declare function isInEnv(key: string): boolean;
+/**
+ * Clear all environment variable overrides.
+ * Useful in afterEach hooks to ensure clean test state.
+ *
+ * @example
+ * ```typescript
+ * import { resetEnv } from './rewire'
+ *
+ * afterEach(() => {
+ *   resetEnv()
+ * })
+ * ```
+ */
+export declare function resetEnv(): void;
 /**
  * Set an environment variable override for testing.
  * This does not modify process.env, only affects env getters.
@@ -35,28 +68,6 @@ export declare function getEnvValue(key: string): string | undefined;
  * ```
  */
 export declare function setEnv(key: string, value: string | undefined): void;
-/**
- * Clear a specific environment variable override.
- */
-export declare function clearEnv(key: string): void;
-/**
- * Clear all environment variable overrides.
- * Useful in afterEach hooks to ensure clean test state.
- *
- * @example
- * ```typescript
- * import { resetEnv } from './rewire'
- *
- * afterEach(() => {
- *   resetEnv()
- * })
- * ```
- */
-export declare function resetEnv(): void;
-/**
- * Check if an environment variable has been overridden.
- */
-export declare function hasOverride(key: string): boolean;
 /**
  * Run code with environment overrides in an isolated AsyncLocalStorage context.
  * Creates true context isolation - overrides don't leak to concurrent code.

package/dist/env/rewire.js

@@ -22,12 +22,14 @@ __export(rewire_exports, {
   clearEnv: () => clearEnv,
   getEnvValue: () => getEnvValue,
   hasOverride: () => hasOverride,
+  isInEnv: () => isInEnv,
   resetEnv: () => resetEnv,
   setEnv: () => setEnv,
   withEnv: () => withEnv,
   withEnvSync: () => withEnvSync
 });
 module.exports = __toCommonJS(rewire_exports);
+var import_objects = require("../objects");
 var import_helpers = require("./helpers");
 let _async_hooks;
 // @__NO_SIDE_EFFECTS__
@@ -47,6 +49,9 @@ if (isVitestEnv && !globalThis[sharedOverridesSymbol]) {
   globalThis[sharedOverridesSymbol] = /* @__PURE__ */ new Map();
 }
 const sharedOverrides = globalThis[sharedOverridesSymbol];
+function clearEnv(key) {
+  sharedOverrides?.delete(key);
+}
 function getEnvValue(key) {
   const isolatedOverrides = isolatedOverridesStorage.getStore();
   if (isolatedOverrides?.has(key)) {
@@ -57,18 +62,25 @@ function getEnvValue(key) {
   }
   return process.env[key];
 }
-function setEnv(key, value) {
-  sharedOverrides?.set(key, value);
+function hasOverride(key) {
+  const isolatedOverrides = isolatedOverridesStorage.getStore();
+  return !!(isolatedOverrides?.has(key) || sharedOverrides?.has(key));
 }
-function clearEnv(key) {
-  sharedOverrides?.delete(key);
+function isInEnv(key) {
+  const isolatedOverrides = isolatedOverridesStorage.getStore();
+  if (isolatedOverrides?.has(key)) {
+    return true;
+  }
+  if (sharedOverrides?.has(key)) {
+    return true;
+  }
+  return (0, import_objects.hasOwn)(process.env, key);
 }
 function resetEnv() {
   sharedOverrides?.clear();
 }
-function hasOverride(key) {
-  const isolatedOverrides = isolatedOverridesStorage.getStore();
-  return !!(isolatedOverrides?.has(key) || sharedOverrides?.has(key));
+function setEnv(key, value) {
+  sharedOverrides?.set(key, value);
 }
 async function withEnv(overrides, fn) {
   const map = new Map(Object.entries(overrides));
@@ -83,6 +95,7 @@ function withEnvSync(overrides, fn) {
   clearEnv,
   getEnvValue,
   hasOverride,
+  isInEnv,
   resetEnv,
   setEnv,
   withEnv,