@socketsecurity/lib 2.8.3 → 2.8.4

package/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.4](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.4) - 2025-10-30
+
+### Added
+
+- **DLX binary helper functions mirror dlx-package pattern**
+  - `downloadBinary`: Download binary with caching (without execution)
+  - `executeBinary`: Execute cached binary without re-downloading
+  - Renamed internal `downloadBinary` to `downloadBinaryFile` to avoid naming conflicts
+  - Maintains feature parity with `downloadPackage`/`executePackage` from dlx-package
+
 ## [2.8.3](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.3) - 2025-10-30
 
 ### Fixed

package/dist/dlx-binary.d.ts

@@ -30,6 +30,28 @@ export declare function cleanDlxCache(maxAge?: number): Promise<number>;
  * Download and execute a binary from a URL with caching.
  */
 export declare function dlxBinary(args: readonly string[] | string[], options?: DlxBinaryOptions | undefined, spawnExtra?: SpawnExtra | undefined): Promise<DlxBinaryResult>;
+/**
+ * Download a binary from a URL with caching (without execution).
+ * Similar to downloadPackage from dlx-package.
+ *
+ * @returns Object containing the path to the cached binary and whether it was downloaded
+ */
+export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOptions'>): Promise<{
+    binaryPath: string;
+    downloaded: boolean;
+}>;
+/**
+ * Execute a cached binary without re-downloading.
+ * Similar to executePackage from dlx-package.
+ * Binary must have been previously downloaded via downloadBinary or dlxBinary.
+ *
+ * @param binaryPath Path to the cached binary (from downloadBinary result)
+ * @param args Arguments to pass to the binary
+ * @param spawnOptions Spawn options for execution
+ * @param spawnExtra Extra spawn configuration
+ * @returns The spawn promise for the running process
+ */
+export declare function executeBinary(binaryPath: string, args: readonly string[] | string[], spawnOptions?: SpawnOptions | undefined, spawnExtra?: SpawnExtra | undefined): ReturnType<typeof spawn>;
 /**
  * Get the DLX binary cache directory path.
  * Returns normalized path for cross-platform compatibility.

package/dist/dlx-binary.js

@@ -1,3 +1,3 @@
 /* Socket Lib - Built with esbuild */
-var H=Object.create;var x=Object.defineProperty;var L=Object.getOwnPropertyDescriptor;var z=Object.getOwnPropertyNames;var F=Object.getPrototypeOf,W=Object.prototype.hasOwnProperty;var Y=(t,n)=>{for(var e in n)x(t,e,{get:n[e],enumerable:!0})},O=(t,n,e,i)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of z(n))!W.call(t,r)&&r!==e&&x(t,r,{get:()=>n[r],enumerable:!(i=L(n,r))||i.enumerable});return t};var T=(t,n,e)=>(e=t!=null?H(F(t)):{},O(n||!t||!t.__esModule?x(e,"default",{value:t,enumerable:!0}):e,t)),q=t=>O(x({},"__esModule",{value:!0}),t);var Q={};Y(Q,{cleanDlxCache:()=>V,dlxBinary:()=>X,getDlxCachePath:()=>P,listDlxCache:()=>G});module.exports=q(Q);var _=require("node:crypto"),s=require("node:fs"),D=T(require("node:os")),l=T(require("node:path")),A=require("#constants/platform"),C=require("./dlx"),S=require("./download-lock"),o=require("./fs"),B=require("./objects"),R=require("./path"),$=require("./paths"),I=require("./spawn");function g(t){return l.default.join(t,".dlx-metadata.json")}async function J(t,n){try{const e=g(t);if(!(0,s.existsSync)(e))return!1;const i=await(0,o.readJson)(e,{throws:!1});if(!(0,B.isObjectObject)(i))return!1;const r=Date.now(),a=i.timestamp;return typeof a!="number"||a<=0?!1:r-a<n}catch{return!1}}async function K(t,n,e){await(0,S.downloadWithLock)(t,n,{staleTimeout:1e4,lockTimeout:12e4});const i=await s.promises.readFile(n),r=(0,_.createHash)("sha256");r.update(i);const a=r.digest("hex");if(e&&a!==e)throw await(0,o.safeDelete)(n),new Error(`Checksum mismatch: expected ${e}, got ${a}`);return A.WIN32||await s.promises.chmod(n,493),a}async function M(t,n,e){const i=g(t),r={arch:D.default.arch(),checksum:e,platform:D.default.platform(),timestamp:Date.now(),url:n,version:"1.0.0"};await s.promises.writeFile(i,JSON.stringify(r,null,2))}async function V(t=require("#constants/time").DLX_BINARY_CACHE_TTL){const n=P();if(!(0,s.existsSync)(n))return 0;let e=0;const i=Date.now(),r=await s.promises.readdir(n);for(const a of r){const c=l.default.join(n,a),m=g(c);try{if(!await(0,o.isDir)(c))continue;const f=await(0,o.readJson)(m,{throws:!1});if(!f||typeof f!="object"||Array.isArray(f))continue;const u=f.timestamp;(typeof u=="number"&&u>0?i-u:Number.POSITIVE_INFINITY)>t&&(await(0,o.safeDelete)(c,{force:!0,recursive:!0}),e+=1)}catch{try{(await s.promises.readdir(c)).length||(await(0,o.safeDelete)(c),e+=1)}catch{}}}return e}async function X(t,n,e){const{cacheTtl:i=require("#constants/time").DLX_BINARY_CACHE_TTL,checksum:r,force:a=!1,name:c,spawnOptions:m,url:f}={__proto__:null,...n},u=P(),p=c||`binary-${process.platform}-${D.default.arch()}`,k=`${f}:${p}`,d=(0,C.generateCacheKey)(k),h=l.default.join(u,d),b=(0,R.normalizePath)(l.default.join(h,p));let w=!1,j=r;if(!a&&(0,s.existsSync)(h)&&await J(h,i))try{const E=g(h),y=await(0,o.readJson)(E,{throws:!1});y&&typeof y=="object"&&!Array.isArray(y)&&typeof y.checksum=="string"?j=y.checksum:w=!0}catch{w=!0}else w=!0;w&&(await s.promises.mkdir(h,{recursive:!0}),j=await K(f,b,r),await M(h,f,j||""));const N=A.WIN32&&/\.(?:bat|cmd|ps1)$/i.test(b)?{...m,env:{...m?.env,PATH:`${h}${l.default.delimiter}${process.env.PATH||""}`},shell:!0}:m,v=(0,I.spawn)(b,t,N,e);return{binaryPath:b,downloaded:w,spawnPromise:v}}function P(){return(0,$.getSocketDlxDir)()}async function G(){const t=P();if(!(0,s.existsSync)(t))return[];const n=[],e=Date.now(),i=await s.promises.readdir(t);for(const r of i){const a=l.default.join(t,r);try{if(!await(0,o.isDir)(a))continue;const c=g(a),m=await(0,o.readJson)(c,{throws:!1});if(!m||typeof m!="object"||Array.isArray(m))continue;const u=(await s.promises.readdir(a)).find(p=>!p.startsWith("."));if(u){const p=l.default.join(a,u),k=await s.promises.stat(p),d=m;n.push({age:e-(d.timestamp||0),arch:d.arch||"unknown",checksum:d.checksum||"",name:u,platform:d.platform||"unknown",size:k.size,url:d.url||""})}}catch{}}return n}0&&(module.exports={cleanDlxCache,dlxBinary,getDlxCachePath,listDlxCache});
+var z=Object.create;var k=Object.defineProperty;var Y=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var K=Object.getPrototypeOf,W=Object.prototype.hasOwnProperty;var X=(t,n)=>{for(var e in n)k(t,e,{get:n[e],enumerable:!0})},S=(t,n,e,i)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of q(n))!W.call(t,r)&&r!==e&&k(t,r,{get:()=>n[r],enumerable:!(i=Y(n,r))||i.enumerable});return t};var j=(t,n,e)=>(e=t!=null?z(K(t)):{},S(n||!t||!t.__esModule?k(e,"default",{value:t,enumerable:!0}):e,t)),J=t=>S(k({},"__esModule",{value:!0}),t);var Z={};X(Z,{cleanDlxCache:()=>M,dlxBinary:()=>V,downloadBinary:()=>G,executeBinary:()=>Q,getDlxCachePath:()=>D,listDlxCache:()=>U});module.exports=J(Z);var B=require("node:crypto"),s=require("node:fs"),b=j(require("node:os")),l=j(require("node:path")),_=require("#constants/platform"),$=require("./dlx"),C=require("./download-lock"),f=require("./fs"),R=require("./objects"),A=require("./path"),v=require("./paths"),O=require("./spawn");function x(t){return l.default.join(t,".dlx-metadata.json")}async function E(t,n){try{const e=x(t);if(!(0,s.existsSync)(e))return!1;const i=await(0,f.readJson)(e,{throws:!1});if(!(0,R.isObjectObject)(i))return!1;const r=Date.now(),a=i.timestamp;return typeof a!="number"||a<=0?!1:r-a<n}catch{return!1}}async function N(t,n,e){await(0,C.downloadWithLock)(t,n,{staleTimeout:1e4,lockTimeout:12e4});const i=await s.promises.readFile(n),r=(0,B.createHash)("sha256");r.update(i);const a=r.digest("hex");if(e&&a!==e)throw await(0,f.safeDelete)(n),new Error(`Checksum mismatch: expected ${e}, got ${a}`);return _.WIN32||await s.promises.chmod(n,493),a}async function I(t,n,e){const i=x(t),r={arch:b.default.arch(),checksum:e,platform:b.default.platform(),timestamp:Date.now(),url:n,version:"1.0.0"};await s.promises.writeFile(i,JSON.stringify(r,null,2))}async function M(t=require("#constants/time").DLX_BINARY_CACHE_TTL){const n=D();if(!(0,s.existsSync)(n))return 0;let e=0;const i=Date.now(),r=await s.promises.readdir(n);for(const a of r){const o=l.default.join(n,a),c=x(o);try{if(!await(0,f.isDir)(o))continue;const u=await(0,f.readJson)(c,{throws:!1});if(!u||typeof u!="object"||Array.isArray(u))continue;const p=u.timestamp;(typeof p=="number"&&p>0?i-p:Number.POSITIVE_INFINITY)>t&&(await(0,f.safeDelete)(o,{force:!0,recursive:!0}),e+=1)}catch{try{(await s.promises.readdir(o)).length||(await(0,f.safeDelete)(o),e+=1)}catch{}}}return e}async function V(t,n,e){const{cacheTtl:i=require("#constants/time").DLX_BINARY_CACHE_TTL,checksum:r,force:a=!1,name:o,spawnOptions:c,url:u}={__proto__:null,...n},p=D(),m=o||`binary-${process.platform}-${b.default.arch()}`,w=`${u}:${m}`,d=(0,$.generateCacheKey)(w),h=l.default.join(p,d),P=(0,A.normalizePath)(l.default.join(h,m));let y=!1,T=r;if(!a&&(0,s.existsSync)(h)&&await E(h,i))try{const F=x(h),g=await(0,f.readJson)(F,{throws:!1});g&&typeof g=="object"&&!Array.isArray(g)&&typeof g.checksum=="string"?T=g.checksum:y=!0}catch{y=!0}else y=!0;y&&(await s.promises.mkdir(h,{recursive:!0}),T=await N(u,P,r),await I(h,u,T||""));const H=_.WIN32&&/\.(?:bat|cmd|ps1)$/i.test(P)?{...c,env:{...c?.env,PATH:`${h}${l.default.delimiter}${process.env.PATH||""}`},shell:!0}:c,L=(0,O.spawn)(P,t,H,e);return{binaryPath:P,downloaded:y,spawnPromise:L}}async function G(t){const{cacheTtl:n=require("#constants/time").DLX_BINARY_CACHE_TTL,checksum:e,force:i=!1,name:r,url:a}={__proto__:null,...t},o=D(),c=r||`binary-${process.platform}-${b.default.arch()}`,u=`${a}:${c}`,p=(0,$.generateCacheKey)(u),m=l.default.join(o,p),w=(0,A.normalizePath)(l.default.join(m,c));let d=!1;if(!i&&(0,s.existsSync)(m)&&await E(m,n))d=!1;else{await s.promises.mkdir(m,{recursive:!0});const h=await N(a,w,e);await I(m,a,h||""),d=!0}return{binaryPath:w,downloaded:d}}function Q(t,n,e,i){const r=_.WIN32&&/\.(?:bat|cmd|ps1)$/i.test(t),a=l.default.dirname(t),o=r?{...e,env:{...e?.env,PATH:`${a}${l.default.delimiter}${process.env.PATH||""}`},shell:!0}:e;return(0,O.spawn)(t,n,o,i)}function D(){return(0,v.getSocketDlxDir)()}async function U(){const t=D();if(!(0,s.existsSync)(t))return[];const n=[],e=Date.now(),i=await s.promises.readdir(t);for(const r of i){const a=l.default.join(t,r);try{if(!await(0,f.isDir)(a))continue;const o=x(a),c=await(0,f.readJson)(o,{throws:!1});if(!c||typeof c!="object"||Array.isArray(c))continue;const p=(await s.promises.readdir(a)).find(m=>!m.startsWith("."));if(p){const m=l.default.join(a,p),w=await s.promises.stat(m),d=c;n.push({age:e-(d.timestamp||0),arch:d.arch||"unknown",checksum:d.checksum||"",name:p,platform:d.platform||"unknown",size:w.size,url:d.url||""})}}catch{}}return n}0&&(module.exports={cleanDlxCache,dlxBinary,downloadBinary,executeBinary,getDlxCachePath,listDlxCache});
 //# sourceMappingURL=dlx-binary.js.map

package/dist/dlx-binary.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/dlx-binary.ts"],
-  "sourcesContent": ["/** @fileoverview DLX binary execution utilities for Socket ecosystem. */\n\nimport { createHash } from 'node:crypto'\nimport { existsSync, promises as fs } from 'node:fs'\nimport os from 'node:os'\nimport path from 'node:path'\n\nimport { WIN32 } from '#constants/platform'\n\nimport { generateCacheKey } from './dlx'\nimport { downloadWithLock } from './download-lock'\nimport { isDir, readJson, safeDelete } from './fs'\nimport { isObjectObject } from './objects'\nimport { normalizePath } from './path'\nimport { getSocketDlxDir } from './paths'\nimport type { SpawnExtra, SpawnOptions } from './spawn'\nimport { spawn } from './spawn'\n\nexport interface DlxBinaryOptions {\n  /** URL to download the binary from. */\n  url: string\n  /** Optional name for the cached binary (defaults to URL hash). */\n  name?: string | undefined\n  /** Expected checksum (sha256) for verification. */\n  checksum?: string | undefined\n  /** Cache TTL in milliseconds (default: 7 days). */\n  cacheTtl?: number | undefined\n  /** Force re-download even if cached. */\n  force?: boolean | undefined\n  /** Additional spawn options. */\n  spawnOptions?: SpawnOptions | undefined\n}\n\nexport interface DlxBinaryResult {\n  /** Path to the cached binary. */\n  binaryPath: string\n  /** Whether the binary was newly downloaded. */\n  downloaded: boolean\n  /** The spawn promise for the running process. */\n  spawnPromise: ReturnType<typeof spawn>\n}\n\n/**\n * Get metadata file path for a cached binary.\n */\nfunction getMetadataPath(cacheEntryPath: string): string {\n  return path.join(cacheEntryPath, '.dlx-metadata.json')\n}\n\n/**\n * Check if a cached binary is still valid.\n */\nasync function isCacheValid(\n  cacheEntryPath: string,\n  cacheTtl: number,\n): Promise<boolean> {\n  try {\n    const metaPath = getMetadataPath(cacheEntryPath)\n    if (!existsSync(metaPath)) {\n      return false\n    }\n\n    const metadata = await readJson(metaPath, { throws: false })\n    if (!isObjectObject(metadata)) {\n      return false\n    }\n    const now = Date.now()\n    const timestamp = (metadata as Record<string, unknown>)['timestamp']\n    // If timestamp is missing or invalid, cache is invalid\n    if (typeof timestamp !== 'number' || timestamp <= 0) {\n      return false\n    }\n    const age = now - timestamp\n\n    return age < cacheTtl\n  } catch {\n    return false\n  }\n}\n\n/**\n * Download a file from a URL with integrity checking and concurrent download protection.\n * Uses downloadWithLock to prevent multiple processes from downloading the same binary simultaneously.\n */\nasync function downloadBinary(\n  url: string,\n  destPath: string,\n  checksum?: string | undefined,\n): Promise<string> {\n  // Use downloadWithLock to handle concurrent download protection.\n  // This prevents corruption when multiple processes try to download the same binary.\n  await downloadWithLock(url, destPath, {\n    // Align with npm's npx locking strategy.\n    staleTimeout: 10_000,\n    // Allow up to 2 minutes for large binary downloads.\n    lockTimeout: 120_000,\n  })\n\n  // Compute checksum of downloaded file.\n  const fileBuffer = await fs.readFile(destPath)\n  const hasher = createHash('sha256')\n  hasher.update(fileBuffer)\n  const actualChecksum = hasher.digest('hex')\n\n  // Verify checksum if provided.\n  if (checksum && actualChecksum !== checksum) {\n    // Clean up invalid file.\n    await safeDelete(destPath)\n    throw new Error(\n      `Checksum mismatch: expected ${checksum}, got ${actualChecksum}`,\n    )\n  }\n\n  // Make executable on POSIX systems.\n  if (!WIN32) {\n    await fs.chmod(destPath, 0o755)\n  }\n\n  return actualChecksum\n}\n\n/**\n * Write metadata for a cached binary.\n */\nasync function writeMetadata(\n  cacheEntryPath: string,\n  url: string,\n  checksum: string,\n): Promise<void> {\n  const metaPath = getMetadataPath(cacheEntryPath)\n  const metadata = {\n    arch: os.arch(),\n    checksum,\n    platform: os.platform(),\n    timestamp: Date.now(),\n    url,\n    version: '1.0.0',\n  }\n  await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2))\n}\n\n/**\n * Clean expired entries from the DLX cache.\n */\nexport async function cleanDlxCache(\n  maxAge: number = /*@__INLINE__*/ require('#constants/time').DLX_BINARY_CACHE_TTL,\n): Promise<number> {\n  const cacheDir = getDlxCachePath()\n\n  if (!existsSync(cacheDir)) {\n    return 0\n  }\n\n  let cleaned = 0\n  const now = Date.now()\n  const entries = await fs.readdir(cacheDir)\n\n  for (const entry of entries) {\n    const entryPath = path.join(cacheDir, entry)\n    const metaPath = getMetadataPath(entryPath)\n\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      if (!(await isDir(entryPath))) {\n        continue\n      }\n\n      // eslint-disable-next-line no-await-in-loop\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        !metadata ||\n        typeof metadata !== 'object' ||\n        Array.isArray(metadata)\n      ) {\n        continue\n      }\n      const timestamp = (metadata as Record<string, unknown>)['timestamp']\n      // If timestamp is missing or invalid, treat as expired (age = infinity)\n      const age =\n        typeof timestamp === 'number' && timestamp > 0\n          ? now - timestamp\n          : Number.POSITIVE_INFINITY\n\n      if (age > maxAge) {\n        // Remove entire cache entry directory.\n        // eslint-disable-next-line no-await-in-loop\n        await safeDelete(entryPath, { force: true, recursive: true })\n        cleaned += 1\n      }\n    } catch {\n      // If we can't read metadata, check if directory is empty or corrupted.\n      try {\n        // eslint-disable-next-line no-await-in-loop\n        const contents = await fs.readdir(entryPath)\n        if (!contents.length) {\n          // Remove empty directory.\n          // eslint-disable-next-line no-await-in-loop\n          await safeDelete(entryPath)\n          cleaned += 1\n        }\n      } catch {}\n    }\n  }\n\n  return cleaned\n}\n\n/**\n * Download and execute a binary from a URL with caching.\n */\nexport async function dlxBinary(\n  args: readonly string[] | string[],\n  options?: DlxBinaryOptions | undefined,\n  spawnExtra?: SpawnExtra | undefined,\n): Promise<DlxBinaryResult> {\n  const {\n    cacheTtl = /*@__INLINE__*/ require('#constants/time').DLX_BINARY_CACHE_TTL,\n    checksum,\n    force = false,\n    name,\n    spawnOptions,\n    url,\n  } = { __proto__: null, ...options } as DlxBinaryOptions\n\n  // Generate cache paths similar to pnpm/npx structure.\n  const cacheDir = getDlxCachePath()\n  const binaryName = name || `binary-${process.platform}-${os.arch()}`\n  // Create spec from URL and binary name for unique cache identity.\n  const spec = `${url}:${binaryName}`\n  const cacheKey = generateCacheKey(spec)\n  const cacheEntryDir = path.join(cacheDir, cacheKey)\n  const binaryPath = normalizePath(path.join(cacheEntryDir, binaryName))\n\n  let downloaded = false\n  let computedChecksum = checksum\n\n  // Check if we need to download.\n  if (\n    !force &&\n    existsSync(cacheEntryDir) &&\n    (await isCacheValid(cacheEntryDir, cacheTtl))\n  ) {\n    // Binary is cached and valid, read the checksum from metadata.\n    try {\n      const metaPath = getMetadataPath(cacheEntryDir)\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        metadata &&\n        typeof metadata === 'object' &&\n        !Array.isArray(metadata) &&\n        typeof (metadata as Record<string, unknown>)['checksum'] === 'string'\n      ) {\n        computedChecksum = (metadata as Record<string, unknown>)[\n          'checksum'\n        ] as string\n      } else {\n        // If metadata is invalid, re-download.\n        downloaded = true\n      }\n    } catch {\n      // If we can't read metadata, re-download.\n      downloaded = true\n    }\n  } else {\n    downloaded = true\n  }\n\n  if (downloaded) {\n    // Ensure cache directory exists.\n    await fs.mkdir(cacheEntryDir, { recursive: true })\n\n    // Download the binary.\n    computedChecksum = await downloadBinary(url, binaryPath, checksum)\n    await writeMetadata(cacheEntryDir, url, computedChecksum || '')\n  }\n\n  // Execute the binary.\n  // On Windows, script files (.bat, .cmd, .ps1) require shell: true because\n  // they are not executable on their own and must be run through cmd.exe.\n  // Note: .exe files are actual binaries and don't need shell mode.\n  const needsShell = WIN32 && /\\.(?:bat|cmd|ps1)$/i.test(binaryPath)\n  // Windows cmd.exe PATH resolution behavior:\n  // When shell: true on Windows with .cmd/.bat/.ps1 files, spawn will automatically\n  // strip the full path down to just the basename without extension (e.g.,\n  // C:\\cache\\test.cmd becomes just \"test\"). Windows cmd.exe then searches for \"test\"\n  // in directories listed in PATH, trying each extension from PATHEXT environment\n  // variable (.COM, .EXE, .BAT, .CMD, etc.) until it finds a match.\n  //\n  // Since our binaries are downloaded to a custom cache directory that's not in PATH\n  // (unlike system package managers like npm/pnpm/yarn which are already in PATH),\n  // we must prepend the cache directory to PATH so cmd.exe can locate the binary.\n  //\n  // This approach is consistent with how other tools handle Windows command execution:\n  // - npm's promise-spawn: uses which.sync() to find commands in PATH\n  // - cross-spawn: spawns cmd.exe with escaped arguments\n  // - Node.js spawn with shell: true: delegates to cmd.exe which uses PATH\n  const finalSpawnOptions = needsShell\n    ? {\n        ...spawnOptions,\n        env: {\n          ...spawnOptions?.env,\n          PATH: `${cacheEntryDir}${path.delimiter}${process.env['PATH'] || ''}`,\n        },\n        shell: true,\n      }\n    : spawnOptions\n  const spawnPromise = spawn(binaryPath, args, finalSpawnOptions, spawnExtra)\n\n  return {\n    binaryPath,\n    downloaded,\n    spawnPromise,\n  }\n}\n\n/**\n * Get the DLX binary cache directory path.\n * Returns normalized path for cross-platform compatibility.\n * Uses same directory as dlx-package for unified DLX storage.\n */\nexport function getDlxCachePath(): string {\n  return getSocketDlxDir()\n}\n\n/**\n * Get information about cached binaries.\n */\nexport async function listDlxCache(): Promise<\n  Array<{\n    age: number\n    arch: string\n    checksum: string\n    name: string\n    platform: string\n    size: number\n    url: string\n  }>\n> {\n  const cacheDir = getDlxCachePath()\n\n  if (!existsSync(cacheDir)) {\n    return []\n  }\n\n  const results = []\n  const now = Date.now()\n  const entries = await fs.readdir(cacheDir)\n\n  for (const entry of entries) {\n    const entryPath = path.join(cacheDir, entry)\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      if (!(await isDir(entryPath))) {\n        continue\n      }\n\n      const metaPath = getMetadataPath(entryPath)\n      // eslint-disable-next-line no-await-in-loop\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        !metadata ||\n        typeof metadata !== 'object' ||\n        Array.isArray(metadata)\n      ) {\n        continue\n      }\n\n      // Find the binary file in the directory.\n      // eslint-disable-next-line no-await-in-loop\n      const files = await fs.readdir(entryPath)\n      const binaryFile = files.find(f => !f.startsWith('.'))\n\n      if (binaryFile) {\n        const binaryPath = path.join(entryPath, binaryFile)\n        // eslint-disable-next-line no-await-in-loop\n        const binaryStats = await fs.stat(binaryPath)\n\n        const metaObj = metadata as Record<string, unknown>\n        results.push({\n          age: now - ((metaObj['timestamp'] as number) || 0),\n          arch: (metaObj['arch'] as string) || 'unknown',\n          checksum: (metaObj['checksum'] as string) || '',\n          name: binaryFile,\n          platform: (metaObj['platform'] as string) || 'unknown',\n          size: binaryStats.size,\n          url: (metaObj['url'] as string) || '',\n        })\n      }\n    } catch {}\n  }\n\n  return results\n}\n"],
-  "mappings": "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",
-  "names": ["dlx_binary_exports", "__export", "cleanDlxCache", "dlxBinary", "getDlxCachePath", "listDlxCache", "__toCommonJS", "import_node_crypto", "import_node_fs", "import_node_os", "import_node_path", "import_platform", "import_dlx", "import_download_lock", "import_fs", "import_objects", "import_path", "import_paths", "import_spawn", "getMetadataPath", "cacheEntryPath", "path", "isCacheValid", "cacheTtl", "metaPath", "metadata", "now", "timestamp", "downloadBinary", "url", "destPath", "checksum", "fileBuffer", "fs", "hasher", "actualChecksum", "writeMetadata", "os", "maxAge", "cacheDir", "cleaned", "entries", "entry", "entryPath", "args", "options", "spawnExtra", "force", "name", "spawnOptions", "binaryName", "spec", "cacheKey", "cacheEntryDir", "binaryPath", "downloaded", "computedChecksum", "finalSpawnOptions", "spawnPromise", "results", "binaryFile", "f", "binaryStats", "metaObj"]
+  "sourcesContent": ["/** @fileoverview DLX binary execution utilities for Socket ecosystem. */\n\nimport { createHash } from 'node:crypto'\nimport { existsSync, promises as fs } from 'node:fs'\nimport os from 'node:os'\nimport path from 'node:path'\n\nimport { WIN32 } from '#constants/platform'\n\nimport { generateCacheKey } from './dlx'\nimport { downloadWithLock } from './download-lock'\nimport { isDir, readJson, safeDelete } from './fs'\nimport { isObjectObject } from './objects'\nimport { normalizePath } from './path'\nimport { getSocketDlxDir } from './paths'\nimport type { SpawnExtra, SpawnOptions } from './spawn'\nimport { spawn } from './spawn'\n\nexport interface DlxBinaryOptions {\n  /** URL to download the binary from. */\n  url: string\n  /** Optional name for the cached binary (defaults to URL hash). */\n  name?: string | undefined\n  /** Expected checksum (sha256) for verification. */\n  checksum?: string | undefined\n  /** Cache TTL in milliseconds (default: 7 days). */\n  cacheTtl?: number | undefined\n  /** Force re-download even if cached. */\n  force?: boolean | undefined\n  /** Additional spawn options. */\n  spawnOptions?: SpawnOptions | undefined\n}\n\nexport interface DlxBinaryResult {\n  /** Path to the cached binary. */\n  binaryPath: string\n  /** Whether the binary was newly downloaded. */\n  downloaded: boolean\n  /** The spawn promise for the running process. */\n  spawnPromise: ReturnType<typeof spawn>\n}\n\n/**\n * Get metadata file path for a cached binary.\n */\nfunction getMetadataPath(cacheEntryPath: string): string {\n  return path.join(cacheEntryPath, '.dlx-metadata.json')\n}\n\n/**\n * Check if a cached binary is still valid.\n */\nasync function isCacheValid(\n  cacheEntryPath: string,\n  cacheTtl: number,\n): Promise<boolean> {\n  try {\n    const metaPath = getMetadataPath(cacheEntryPath)\n    if (!existsSync(metaPath)) {\n      return false\n    }\n\n    const metadata = await readJson(metaPath, { throws: false })\n    if (!isObjectObject(metadata)) {\n      return false\n    }\n    const now = Date.now()\n    const timestamp = (metadata as Record<string, unknown>)['timestamp']\n    // If timestamp is missing or invalid, cache is invalid\n    if (typeof timestamp !== 'number' || timestamp <= 0) {\n      return false\n    }\n    const age = now - timestamp\n\n    return age < cacheTtl\n  } catch {\n    return false\n  }\n}\n\n/**\n * Download a file from a URL with integrity checking and concurrent download protection.\n * Uses downloadWithLock to prevent multiple processes from downloading the same binary simultaneously.\n * Internal helper function for downloading binary files.\n */\nasync function downloadBinaryFile(\n  url: string,\n  destPath: string,\n  checksum?: string | undefined,\n): Promise<string> {\n  // Use downloadWithLock to handle concurrent download protection.\n  // This prevents corruption when multiple processes try to download the same binary.\n  await downloadWithLock(url, destPath, {\n    // Align with npm's npx locking strategy.\n    staleTimeout: 10_000,\n    // Allow up to 2 minutes for large binary downloads.\n    lockTimeout: 120_000,\n  })\n\n  // Compute checksum of downloaded file.\n  const fileBuffer = await fs.readFile(destPath)\n  const hasher = createHash('sha256')\n  hasher.update(fileBuffer)\n  const actualChecksum = hasher.digest('hex')\n\n  // Verify checksum if provided.\n  if (checksum && actualChecksum !== checksum) {\n    // Clean up invalid file.\n    await safeDelete(destPath)\n    throw new Error(\n      `Checksum mismatch: expected ${checksum}, got ${actualChecksum}`,\n    )\n  }\n\n  // Make executable on POSIX systems.\n  if (!WIN32) {\n    await fs.chmod(destPath, 0o755)\n  }\n\n  return actualChecksum\n}\n\n/**\n * Write metadata for a cached binary.\n */\nasync function writeMetadata(\n  cacheEntryPath: string,\n  url: string,\n  checksum: string,\n): Promise<void> {\n  const metaPath = getMetadataPath(cacheEntryPath)\n  const metadata = {\n    arch: os.arch(),\n    checksum,\n    platform: os.platform(),\n    timestamp: Date.now(),\n    url,\n    version: '1.0.0',\n  }\n  await fs.writeFile(metaPath, JSON.stringify(metadata, null, 2))\n}\n\n/**\n * Clean expired entries from the DLX cache.\n */\nexport async function cleanDlxCache(\n  maxAge: number = /*@__INLINE__*/ require('#constants/time').DLX_BINARY_CACHE_TTL,\n): Promise<number> {\n  const cacheDir = getDlxCachePath()\n\n  if (!existsSync(cacheDir)) {\n    return 0\n  }\n\n  let cleaned = 0\n  const now = Date.now()\n  const entries = await fs.readdir(cacheDir)\n\n  for (const entry of entries) {\n    const entryPath = path.join(cacheDir, entry)\n    const metaPath = getMetadataPath(entryPath)\n\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      if (!(await isDir(entryPath))) {\n        continue\n      }\n\n      // eslint-disable-next-line no-await-in-loop\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        !metadata ||\n        typeof metadata !== 'object' ||\n        Array.isArray(metadata)\n      ) {\n        continue\n      }\n      const timestamp = (metadata as Record<string, unknown>)['timestamp']\n      // If timestamp is missing or invalid, treat as expired (age = infinity)\n      const age =\n        typeof timestamp === 'number' && timestamp > 0\n          ? now - timestamp\n          : Number.POSITIVE_INFINITY\n\n      if (age > maxAge) {\n        // Remove entire cache entry directory.\n        // eslint-disable-next-line no-await-in-loop\n        await safeDelete(entryPath, { force: true, recursive: true })\n        cleaned += 1\n      }\n    } catch {\n      // If we can't read metadata, check if directory is empty or corrupted.\n      try {\n        // eslint-disable-next-line no-await-in-loop\n        const contents = await fs.readdir(entryPath)\n        if (!contents.length) {\n          // Remove empty directory.\n          // eslint-disable-next-line no-await-in-loop\n          await safeDelete(entryPath)\n          cleaned += 1\n        }\n      } catch {}\n    }\n  }\n\n  return cleaned\n}\n\n/**\n * Download and execute a binary from a URL with caching.\n */\nexport async function dlxBinary(\n  args: readonly string[] | string[],\n  options?: DlxBinaryOptions | undefined,\n  spawnExtra?: SpawnExtra | undefined,\n): Promise<DlxBinaryResult> {\n  const {\n    cacheTtl = /*@__INLINE__*/ require('#constants/time').DLX_BINARY_CACHE_TTL,\n    checksum,\n    force = false,\n    name,\n    spawnOptions,\n    url,\n  } = { __proto__: null, ...options } as DlxBinaryOptions\n\n  // Generate cache paths similar to pnpm/npx structure.\n  const cacheDir = getDlxCachePath()\n  const binaryName = name || `binary-${process.platform}-${os.arch()}`\n  // Create spec from URL and binary name for unique cache identity.\n  const spec = `${url}:${binaryName}`\n  const cacheKey = generateCacheKey(spec)\n  const cacheEntryDir = path.join(cacheDir, cacheKey)\n  const binaryPath = normalizePath(path.join(cacheEntryDir, binaryName))\n\n  let downloaded = false\n  let computedChecksum = checksum\n\n  // Check if we need to download.\n  if (\n    !force &&\n    existsSync(cacheEntryDir) &&\n    (await isCacheValid(cacheEntryDir, cacheTtl))\n  ) {\n    // Binary is cached and valid, read the checksum from metadata.\n    try {\n      const metaPath = getMetadataPath(cacheEntryDir)\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        metadata &&\n        typeof metadata === 'object' &&\n        !Array.isArray(metadata) &&\n        typeof (metadata as Record<string, unknown>)['checksum'] === 'string'\n      ) {\n        computedChecksum = (metadata as Record<string, unknown>)[\n          'checksum'\n        ] as string\n      } else {\n        // If metadata is invalid, re-download.\n        downloaded = true\n      }\n    } catch {\n      // If we can't read metadata, re-download.\n      downloaded = true\n    }\n  } else {\n    downloaded = true\n  }\n\n  if (downloaded) {\n    // Ensure cache directory exists.\n    await fs.mkdir(cacheEntryDir, { recursive: true })\n\n    // Download the binary.\n    computedChecksum = await downloadBinaryFile(url, binaryPath, checksum)\n    await writeMetadata(cacheEntryDir, url, computedChecksum || '')\n  }\n\n  // Execute the binary.\n  // On Windows, script files (.bat, .cmd, .ps1) require shell: true because\n  // they are not executable on their own and must be run through cmd.exe.\n  // Note: .exe files are actual binaries and don't need shell mode.\n  const needsShell = WIN32 && /\\.(?:bat|cmd|ps1)$/i.test(binaryPath)\n  // Windows cmd.exe PATH resolution behavior:\n  // When shell: true on Windows with .cmd/.bat/.ps1 files, spawn will automatically\n  // strip the full path down to just the basename without extension (e.g.,\n  // C:\\cache\\test.cmd becomes just \"test\"). Windows cmd.exe then searches for \"test\"\n  // in directories listed in PATH, trying each extension from PATHEXT environment\n  // variable (.COM, .EXE, .BAT, .CMD, etc.) until it finds a match.\n  //\n  // Since our binaries are downloaded to a custom cache directory that's not in PATH\n  // (unlike system package managers like npm/pnpm/yarn which are already in PATH),\n  // we must prepend the cache directory to PATH so cmd.exe can locate the binary.\n  //\n  // This approach is consistent with how other tools handle Windows command execution:\n  // - npm's promise-spawn: uses which.sync() to find commands in PATH\n  // - cross-spawn: spawns cmd.exe with escaped arguments\n  // - Node.js spawn with shell: true: delegates to cmd.exe which uses PATH\n  const finalSpawnOptions = needsShell\n    ? {\n        ...spawnOptions,\n        env: {\n          ...spawnOptions?.env,\n          PATH: `${cacheEntryDir}${path.delimiter}${process.env['PATH'] || ''}`,\n        },\n        shell: true,\n      }\n    : spawnOptions\n  const spawnPromise = spawn(binaryPath, args, finalSpawnOptions, spawnExtra)\n\n  return {\n    binaryPath,\n    downloaded,\n    spawnPromise,\n  }\n}\n\n/**\n * Download a binary from a URL with caching (without execution).\n * Similar to downloadPackage from dlx-package.\n *\n * @returns Object containing the path to the cached binary and whether it was downloaded\n */\nexport async function downloadBinary(\n  options: Omit<DlxBinaryOptions, 'spawnOptions'>,\n): Promise<{ binaryPath: string; downloaded: boolean }> {\n  const {\n    cacheTtl = /*@__INLINE__*/ require('#constants/time').DLX_BINARY_CACHE_TTL,\n    checksum,\n    force = false,\n    name,\n    url,\n  } = { __proto__: null, ...options } as DlxBinaryOptions\n\n  // Generate cache paths similar to pnpm/npx structure.\n  const cacheDir = getDlxCachePath()\n  const binaryName = name || `binary-${process.platform}-${os.arch()}`\n  // Create spec from URL and binary name for unique cache identity.\n  const spec = `${url}:${binaryName}`\n  const cacheKey = generateCacheKey(spec)\n  const cacheEntryDir = path.join(cacheDir, cacheKey)\n  const binaryPath = normalizePath(path.join(cacheEntryDir, binaryName))\n\n  let downloaded = false\n\n  // Check if we need to download.\n  if (\n    !force &&\n    existsSync(cacheEntryDir) &&\n    (await isCacheValid(cacheEntryDir, cacheTtl))\n  ) {\n    // Binary is cached and valid.\n    downloaded = false\n  } else {\n    // Ensure cache directory exists.\n    await fs.mkdir(cacheEntryDir, { recursive: true })\n\n    // Download the binary.\n    const computedChecksum = await downloadBinaryFile(url, binaryPath, checksum)\n    await writeMetadata(cacheEntryDir, url, computedChecksum || '')\n    downloaded = true\n  }\n\n  return {\n    binaryPath,\n    downloaded,\n  }\n}\n\n/**\n * Execute a cached binary without re-downloading.\n * Similar to executePackage from dlx-package.\n * Binary must have been previously downloaded via downloadBinary or dlxBinary.\n *\n * @param binaryPath Path to the cached binary (from downloadBinary result)\n * @param args Arguments to pass to the binary\n * @param spawnOptions Spawn options for execution\n * @param spawnExtra Extra spawn configuration\n * @returns The spawn promise for the running process\n */\nexport function executeBinary(\n  binaryPath: string,\n  args: readonly string[] | string[],\n  spawnOptions?: SpawnOptions | undefined,\n  spawnExtra?: SpawnExtra | undefined,\n): ReturnType<typeof spawn> {\n  // On Windows, script files (.bat, .cmd, .ps1) require shell: true because\n  // they are not executable on their own and must be run through cmd.exe.\n  // Note: .exe files are actual binaries and don't need shell mode.\n  const needsShell = WIN32 && /\\.(?:bat|cmd|ps1)$/i.test(binaryPath)\n\n  // Windows cmd.exe PATH resolution behavior:\n  // When shell: true on Windows with .cmd/.bat/.ps1 files, spawn will automatically\n  // strip the full path down to just the basename without extension. Windows cmd.exe\n  // then searches for the binary in directories listed in PATH.\n  //\n  // Since our binaries are downloaded to a custom cache directory that's not in PATH,\n  // we must prepend the cache directory to PATH so cmd.exe can locate the binary.\n  const cacheEntryDir = path.dirname(binaryPath)\n  const finalSpawnOptions = needsShell\n    ? {\n        ...spawnOptions,\n        env: {\n          ...spawnOptions?.env,\n          PATH: `${cacheEntryDir}${path.delimiter}${process.env['PATH'] || ''}`,\n        },\n        shell: true,\n      }\n    : spawnOptions\n\n  return spawn(binaryPath, args, finalSpawnOptions, spawnExtra)\n}\n\n/**\n * Get the DLX binary cache directory path.\n * Returns normalized path for cross-platform compatibility.\n * Uses same directory as dlx-package for unified DLX storage.\n */\nexport function getDlxCachePath(): string {\n  return getSocketDlxDir()\n}\n\n/**\n * Get information about cached binaries.\n */\nexport async function listDlxCache(): Promise<\n  Array<{\n    age: number\n    arch: string\n    checksum: string\n    name: string\n    platform: string\n    size: number\n    url: string\n  }>\n> {\n  const cacheDir = getDlxCachePath()\n\n  if (!existsSync(cacheDir)) {\n    return []\n  }\n\n  const results = []\n  const now = Date.now()\n  const entries = await fs.readdir(cacheDir)\n\n  for (const entry of entries) {\n    const entryPath = path.join(cacheDir, entry)\n    try {\n      // eslint-disable-next-line no-await-in-loop\n      if (!(await isDir(entryPath))) {\n        continue\n      }\n\n      const metaPath = getMetadataPath(entryPath)\n      // eslint-disable-next-line no-await-in-loop\n      const metadata = await readJson(metaPath, { throws: false })\n      if (\n        !metadata ||\n        typeof metadata !== 'object' ||\n        Array.isArray(metadata)\n      ) {\n        continue\n      }\n\n      // Find the binary file in the directory.\n      // eslint-disable-next-line no-await-in-loop\n      const files = await fs.readdir(entryPath)\n      const binaryFile = files.find(f => !f.startsWith('.'))\n\n      if (binaryFile) {\n        const binaryPath = path.join(entryPath, binaryFile)\n        // eslint-disable-next-line no-await-in-loop\n        const binaryStats = await fs.stat(binaryPath)\n\n        const metaObj = metadata as Record<string, unknown>\n        results.push({\n          age: now - ((metaObj['timestamp'] as number) || 0),\n          arch: (metaObj['arch'] as string) || 'unknown',\n          checksum: (metaObj['checksum'] as string) || '',\n          name: binaryFile,\n          platform: (metaObj['platform'] as string) || 'unknown',\n          size: binaryStats.size,\n          url: (metaObj['url'] as string) || '',\n        })\n      }\n    } catch {}\n  }\n\n  return results\n}\n"],
+  "mappings": "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",
+  "names": ["dlx_binary_exports", "__export", "cleanDlxCache", "dlxBinary", "downloadBinary", "executeBinary", "getDlxCachePath", "listDlxCache", "__toCommonJS", "import_node_crypto", "import_node_fs", "import_node_os", "import_node_path", "import_platform", "import_dlx", "import_download_lock", "import_fs", "import_objects", "import_path", "import_paths", "import_spawn", "getMetadataPath", "cacheEntryPath", "path", "isCacheValid", "cacheTtl", "metaPath", "metadata", "now", "timestamp", "downloadBinaryFile", "url", "destPath", "checksum", "fileBuffer", "fs", "hasher", "actualChecksum", "writeMetadata", "os", "maxAge", "cacheDir", "cleaned", "entries", "entry", "entryPath", "args", "options", "spawnExtra", "force", "name", "spawnOptions", "binaryName", "spec", "cacheKey", "cacheEntryDir", "binaryPath", "downloaded", "computedChecksum", "finalSpawnOptions", "spawnPromise", "needsShell", "results", "binaryFile", "f", "binaryStats", "metaObj"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "2.8.3",
+  "version": "2.8.4",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [