@socketsecurity/lib 5.5.3 → 5.7.0

package/dist/dlx/detect.d.ts

@@ -5,6 +5,14 @@ export interface ExecutableDetectionResult {
     packageJsonPath?: string;
     inDlxCache?: boolean;
 }
+/**
+ * Detect executable type for paths in DLX cache.
+ * Uses filesystem structure (node_modules/ presence).
+ *
+ * @param filePath - Path within DLX cache (~/.socket/_dlx/)
+ * @returns Detection result
+ */
+export declare function detectDlxExecutableType(filePath: string): ExecutableDetectionResult;
 /**
  * Detect if a path is a Node.js package or native binary executable.
  * Works for both DLX cache paths and local filesystem paths.
@@ -27,14 +35,6 @@ export interface ExecutableDetectionResult {
  * ```
  */
 export declare function detectExecutableType(filePath: string): ExecutableDetectionResult;
-/**
- * Detect executable type for paths in DLX cache.
- * Uses filesystem structure (node_modules/ presence).
- *
- * @param filePath - Path within DLX cache (~/.socket/_dlx/)
- * @returns Detection result
- */
-export declare function detectDlxExecutableType(filePath: string): ExecutableDetectionResult;
 /**
  * Detect executable type for local filesystem paths.
  * Uses package.json and file extension checks.

package/dist/dlx/detect.js

@@ -46,11 +46,19 @@ function getPath() {
   return _path;
 }
 const NODE_JS_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs"]);
-function detectExecutableType(filePath) {
-  if ((0, import_paths.isInSocketDlx)(filePath)) {
-    return detectDlxExecutableType(filePath);
+function findPackageJson(filePath) {
+  const fs = /* @__PURE__ */ getFs();
+  const path = /* @__PURE__ */ getPath();
+  let currentDir = path.dirname(path.resolve(filePath));
+  const root = path.parse(currentDir).root;
+  while (currentDir !== root) {
+    const packageJsonPath = path.join(currentDir, "package.json");
+    if (fs.existsSync(packageJsonPath)) {
+      return packageJsonPath;
+    }
+    currentDir = path.dirname(currentDir);
   }
-  return detectLocalExecutableType(filePath);
+  return void 0;
 }
 function detectDlxExecutableType(filePath) {
   const fs = /* @__PURE__ */ getFs();
@@ -73,6 +81,12 @@ function detectDlxExecutableType(filePath) {
     inDlxCache: true
   };
 }
+function detectExecutableType(filePath) {
+  if ((0, import_paths.isInSocketDlx)(filePath)) {
+    return detectDlxExecutableType(filePath);
+  }
+  return detectLocalExecutableType(filePath);
+}
 function detectLocalExecutableType(filePath) {
   const fs = /* @__PURE__ */ getFs();
   const packageJsonPath = findPackageJson(filePath);
@@ -103,20 +117,6 @@ function detectLocalExecutableType(filePath) {
     inDlxCache: false
   };
 }
-function findPackageJson(filePath) {
-  const fs = /* @__PURE__ */ getFs();
-  const path = /* @__PURE__ */ getPath();
-  let currentDir = path.dirname(path.resolve(filePath));
-  const root = path.parse(currentDir).root;
-  while (currentDir !== root) {
-    const packageJsonPath = path.join(currentDir, "package.json");
-    if (fs.existsSync(packageJsonPath)) {
-      return packageJsonPath;
-    }
-    currentDir = path.dirname(currentDir);
-  }
-  return void 0;
-}
 function isJsFilePath(filePath) {
   const path = /* @__PURE__ */ getPath();
   const ext = path.extname(filePath).toLowerCase();

package/dist/dlx/manifest.d.ts

@@ -14,17 +14,23 @@ export interface PackageDetails {
  * Details for binary download entries.
  */
 export interface BinaryDetails {
-    checksum: string;
-    checksum_algorithm: ChecksumAlgorithm;
+    /** SRI integrity hash (sha512-<base64>, aligned with npm). */
+    integrity: string;
     platform: string;
     arch: string;
     size: number;
     source: {
-        type: 'download';
-        url: string;
+        type: 'download' | 'extract';
+        url?: string;
+        path?: string;
+    };
+    /** Update check metadata (same structure as packages). */
+    update_check?: {
+        last_check: number;
+        last_notification: number;
+        latest_known: string;
     };
 }
-export type ChecksumAlgorithm = 'sha256' | 'sha512';
 /**
  * Unified manifest entry for all cached items (packages and binaries).
  * Shared fields at root, type-specific fields in details.
@@ -35,18 +41,6 @@ export interface ManifestEntry {
     timestamp: number;
     details: PackageDetails | BinaryDetails;
 }
-/**
- * Type guard for package entries.
- */
-export declare function isPackageEntry(entry: ManifestEntry): entry is ManifestEntry & {
-    details: PackageDetails;
-};
-/**
- * Type guard for binary entries.
- */
-export declare function isBinaryEntry(entry: ManifestEntry): entry is ManifestEntry & {
-    details: BinaryDetails;
-};
 /**
  * Legacy store record format (deprecated, for migration).
  */
@@ -61,6 +55,18 @@ export interface DlxManifestOptions {
      */
     manifestPath?: string;
 }
+/**
+ * Type guard for binary entries.
+ */
+export declare function isBinaryEntry(entry: ManifestEntry): entry is ManifestEntry & {
+    details: BinaryDetails;
+};
+/**
+ * Type guard for package entries.
+ */
+export declare function isPackageEntry(entry: ManifestEntry): entry is ManifestEntry & {
+    details: PackageDetails;
+};
 /**
  * DLX manifest storage manager with atomic operations.
  * Supports both legacy format (package name keys) and new unified manifest format (spec keys).
@@ -71,47 +77,48 @@ export declare class DlxManifest {
     constructor(options?: DlxManifestOptions);
     /**
      * Read the entire manifest file.
+     * @private
      */
     private readManifest;
+    private writeManifest;
     /**
-     * Get a manifest entry by spec (e.g., "@socketsecurity/cli@^2.0.11").
+     * Clear cached data for a specific entry.
      */
-    getManifestEntry(spec: string): ManifestEntry | undefined;
+    clear(name: string): Promise<void>;
+    /**
+     * Clear all cached data.
+     */
+    clearAll(): Promise<void>;
     /**
      * Get cached update information for a package (legacy format).
      * @deprecated Use getManifestEntry() for new code.
      */
     get(name: string): StoreRecord | undefined;
     /**
-     * Set a package manifest entry.
+     * Get all cached package names.
      */
-    setPackageEntry(spec: string, cacheKey: string, details: PackageDetails): Promise<void>;
+    getAllPackages(): string[];
     /**
-     * Set a binary manifest entry.
+     * Get a manifest entry by spec (e.g., "@socketsecurity/cli@^2.0.11").
      */
-    setBinaryEntry(spec: string, cacheKey: string, details: BinaryDetails): Promise<void>;
-    private writeManifest;
+    getManifestEntry(spec: string): ManifestEntry | undefined;
+    /**
+     * Check if cached data is fresh based on TTL.
+     */
+    isFresh(record: StoreRecord | undefined, ttlMs: number): boolean;
     /**
      * Store update information for a package (legacy format).
      * @deprecated Use setPackageEntry() for new code.
      */
     set(name: string, record: StoreRecord): Promise<void>;
     /**
-     * Clear cached data for a specific entry.
-     */
-    clear(name: string): Promise<void>;
-    /**
-     * Clear all cached data.
-     */
-    clearAll(): Promise<void>;
-    /**
-     * Check if cached data is fresh based on TTL.
+     * Set a binary manifest entry.
      */
-    isFresh(record: StoreRecord | undefined, ttlMs: number): boolean;
+    setBinaryEntry(spec: string, cacheKey: string, details: BinaryDetails): Promise<void>;
     /**
-     * Get all cached package names.
+     * Set a package manifest entry.
      */
-    getAllPackages(): string[];
+    setPackageEntry(spec: string, cacheKey: string, details: PackageDetails): Promise<void>;
 }
 // Export singleton instance using default manifest location.
 export declare const dlxManifest: DlxManifest;

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;