@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/dlx/binary.d.ts

@@ -1,285 +1,56 @@
-/** @fileoverview DLX binary execution utilities for Socket ecosystem. */
-import { getSocketDlxDir } from '../paths/socket';
-import { spawn } from '../spawn';
-import type { HashSpec } from './integrity';
-import type { SpawnExtra, SpawnOptions } from '../spawn';
-export interface DlxBinaryOptions {
-    /**
-     * URL to download the binary from.
-     */
-    url: string;
-    /**
-     * Optional name for the cached binary (defaults to URL hash).
-     */
-    name?: string | undefined;
-    /**
-     * Expected hash for verification. Accepts either:
-     * - A bare sha512 SRI string (`sha512-<base64>`), sniffed as integrity.
-     * - A bare sha256 hex string (64 hex chars), sniffed as checksum.
-     * - An explicit `{ type: 'integrity' | 'checksum', value }` object.
-     *
-     * This is the preferred field. `integrity` and `sha256` remain as
-     * lower-level escapes; if both `hash` and one of those is set, `hash`
-     * wins for the matching flavor.
-     */
-    hash?: HashSpec | undefined;
-    /**
-     * Expected SRI integrity hash (sha512-<base64>) for verification.
-     * Lower-level alternative to `hash`.
-     */
-    integrity?: string | undefined;
-    /**
-     * Expected SHA-256 hex checksum for verification.
-     * Passed to httpDownload for inline verification during download.
-     * This is more secure than post-download verification as it fails early.
-     * Lower-level alternative to `hash`.
-     */
-    sha256?: string | undefined;
-    /**
-     * Cache TTL in milliseconds (default: 7 days).
-     */
-    cacheTtl?: number | undefined;
-    /**
-     * Force re-download even if cached.
-     * Aligns with npm/npx --force flag.
-     */
-    force?: boolean | undefined;
-    /**
-     * Skip confirmation prompts (auto-approve).
-     * Aligns with npx --yes/-y flag.
-     */
-    yes?: boolean | undefined;
-    /**
-     * Suppress output (quiet mode).
-     * Aligns with npx --quiet/-q and pnpm --silent/-s flags.
-     */
-    quiet?: boolean | undefined;
-    /**
-     * Additional spawn options.
-     */
-    spawnOptions?: SpawnOptions | undefined;
-}
-export interface DlxBinaryResult {
-    /** Path to the cached binary. */
-    binaryPath: string;
-    /** Whether the binary was newly downloaded. */
-    downloaded: boolean;
-    /** The spawn promise for the running process. */
-    spawnPromise: ReturnType<typeof spawn>;
-}
 /**
- * Metadata structure for cached binaries (.dlx-metadata.json).
- * Unified schema shared across TypeScript (dlxBinary) and C++ stub extractor.
+ * @file DLX binary execution utilities for Socket ecosystem. High-level entry
+ *   points for downloading standalone URL-hosted binaries (not npm packages —
+ *   see `./package` for those) and executing them with cross-platform shell
+ *   handling.
  *
- * Fields:
- * - version: Schema version (currently "1.0.0")
- * - cache_key: First 16 chars of SHA-512 hash (matches directory name)
- * - timestamp: Unix timestamp in milliseconds
- * - integrity: SRI hash (sha512-<base64>, aligned with npm)
- * - size: Size of cached binary in bytes
- * - source: Origin information
- *   - type: "download" | "extract" | "package"
- *   - url: Download URL (if type is "download")
- *   - path: Source binary path (if type is "extract")
- *   - spec: Package spec (if type is "package")
- * - update_check: Update checking metadata (optional)
- *   - last_check: Timestamp of last update check
- *   - last_notification: Timestamp of last user notification
- *   - latest_known: Latest known version string
- *
- * Example:
- * ```json
- * {
- *   "version": "1.0.0",
- *   "cache_key": "a1b2c3d4e5f67890",
- *   "timestamp": 1730332800000,
- *   "integrity": "sha512-abc123base64...",
- *   "size": 15000000,
- *   "source": {
- *     "type": "download",
- *     "url": "https://example.com/binary"
- *   },
- *   "update_check": {
- *     "last_check": 1730332800000,
- *     "last_notification": 1730246400000,
- *     "latest_known": "2.1.0"
- *   }
- * }
- * ```
- *
- * @internal This interface documents the metadata file format.
- */
-export interface DlxMetadata {
-    version: string;
-    cache_key: string;
-    timestamp: number;
-    integrity: string;
-    size: number;
-    source?: {
-        type: 'download' | 'extract' | 'package';
-        url?: string;
-        path?: string;
-        spec?: string;
-    };
-    update_check?: {
-        last_check: number;
-        last_notification: number;
-        latest_known: string;
-    };
-}
-/**
- * Clean expired entries from the DLX cache.
- *
- * @example
- * ```typescript
- * // Remove cache entries older than the default TTL
- * const removed = await cleanDlxCache()
- *
- * // Remove entries older than 1 hour
- * const removed2 = await cleanDlxCache(60 * 60 * 1000)
- * ```
+ *   - `dlxBinary` — download (if needed) + execute
+ *   - `executeBinary` — execute an already-cached binary Supporting surface lives
+ *     in sibling leaves and is re-exported here so existing `dlx/binary`
+ *     importers keep working unchanged:
+ *   - lazy `node:fs` / `node:path` / `node:crypto` + LRU cache — `./_internal`
+ *   - types — `./binary-types`
+ *   - on-disk cache metadata — `./binary-cache`
+ *   - download + integrity verification — `./binary-download`
  */
-export declare function cleanDlxCache(maxAge?: number): Promise<number>;
+import { spawn } from '../spawn/spawn';
+import type { DlxBinaryOptions, DlxBinaryResult } from './binary-types';
+import type { SpawnExtra, SpawnOptions } from '../spawn/types';
 /**
  * Download and execute a binary from a URL with caching.
  *
  * @example
- * ```typescript
- * const result = await dlxBinary(['--version'], {
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * await result.spawnPromise
- * ```
+ *   ;```typescript
+ *   const result = await dlxBinary(['--version'], {
+ *     url: 'https://example.com/tool-linux-x64',
+ *     name: 'tool',
+ *   })
+ *   await result.spawnPromise
+ *   ```
  */
 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
- *
- * @example
- * ```typescript
- * const { binaryPath, downloaded } = await downloadBinary({
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * console.log(`Binary at: ${binaryPath}, fresh: ${downloaded}`)
- * ```
- */
-export declare function downloadBinary(options: Omit<DlxBinaryOptions, 'spawnOptions'>): Promise<{
-    binaryPath: string;
-    downloaded: boolean;
-}>;
-/**
- * Download a file from a URL with integrity checking and concurrent download protection.
- * Uses processLock to prevent multiple processes from downloading the same binary simultaneously.
- * Internal helper function for downloading binary files.
- *
- * Supports two integrity verification methods:
- * - sha256: Hex SHA-256 checksum (verified inline during download via httpDownload)
- * - integrity: SRI format sha512-<base64> (verified post-download)
- *
- * The sha256 option is preferred as it fails early during download if the checksum doesn't match.
+ * Execute a cached binary without re-downloading. Similar to executePackage
+ * from dlx/package. Binary must have been previously downloaded via
+ * downloadBinary or dlxBinary.
  *
  * @example
- * ```typescript
- * const integrity = await downloadBinaryFile(
- *   'https://example.com/tool-linux-x64',
- *   '/tmp/dlx-cache/tool'
- * )
- * console.log(`Integrity: ${integrity}`)
- * ```
- */
-export declare function downloadBinaryFile(url: string, destPath: string, integrity?: string | undefined, sha256?: string | undefined): Promise<string>;
-/**
- * Execute a cached binary without re-downloading.
- * Similar to executePackage from dlx-package.
- * Binary must have been previously downloaded via downloadBinary or dlxBinary.
+ *   ;```typescript
+ *   const { binaryPath } = await downloadBinary({
+ *     url: 'https://example.com/tool-linux-x64',
+ *     name: 'tool',
+ *   })
+ *   const result = executeBinary(binaryPath, ['--help'])
+ *   ```
  *
  * @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
+ * @param args Arguments to pass to the binary.
+ * @param spawnOptions Spawn options for execution.
+ * @param spawnExtra Extra spawn configuration.
  *
- * @example
- * ```typescript
- * const { binaryPath } = await downloadBinary({
- *   url: 'https://example.com/tool-linux-x64',
- *   name: 'tool',
- * })
- * const result = executeBinary(binaryPath, ['--help'])
- * ```
+ * @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 metadata file path for a cached binary.
- *
- * @example
- * ```typescript
- * const metaPath = getBinaryCacheMetadataPath('/tmp/dlx-cache/a1b2c3d4')
- * // '/tmp/dlx-cache/a1b2c3d4/.dlx-metadata.json'
- * ```
- */
-export declare function getBinaryCacheMetadataPath(cacheEntryPath: string): string;
-/**
- * Get the DLX binary cache directory path.
- * Alias of `getSocketDlxDir` — DLX binary cache uses the same directory
- * as dlx-package for unified DLX storage.
- *
- * @example
- * ```typescript
- * const cachePath = getDlxCachePath()
- * ```
- */
-export declare const getDlxCachePath: typeof getSocketDlxDir;
-/**
- * Check if a cached binary is still valid.
- *
- * @example
- * ```typescript
- * const ttl = 7 * 24 * 60 * 60 * 1000
- * const valid = await isBinaryCacheValid('/tmp/dlx-cache/a1b2c3d4', ttl)
- * if (!valid) {
- *   // Re-download the binary
- * }
- * ```
- */
-export declare function isBinaryCacheValid(cacheEntryPath: string, cacheTtl: number): Promise<boolean>;
-/**
- * Get information about cached binaries.
- *
- * @example
- * ```typescript
- * const entries = await listDlxCache()
- * for (const entry of entries) {
- *   console.log(`${entry.name}: ${entry.size} bytes`)
- * }
- * ```
- */
-export declare function listDlxCache(): Promise<Array<{
-    age: number;
-    integrity: string;
-    name: string;
-    size: number;
-    url: string;
-}>>;
-/**
- * Write metadata for a cached binary.
- * Uses unified schema shared with C++ decompressor and CLI dlxBinary.
- * Schema documentation: See DlxMetadata interface in this file (exported).
- *
- * @example
- * ```typescript
- * await writeBinaryCacheMetadata(
- *   '/tmp/dlx-cache/a1b2c3d4',
- *   'a1b2c3d4',
- *   'https://example.com/tool',
- *   'sha512-abc123...',
- *   15000000
- * )
- * ```
- */
-export declare function writeBinaryCacheMetadata(cacheEntryPath: string, cacheKey: string, url: string, integrity: string, size: number): Promise<void>;
+export { cleanDlxCache, getBinaryCacheMetadataPath, getDlxCachePath, isBinaryCacheValid, listDlxCache, writeBinaryCacheMetadata, } from './binary-cache';
+export { downloadBinary, downloadBinaryFile } from './binary-download';
+export type { DlxBinaryOptions, DlxBinaryResult, DlxMetadata, } from './binary-types';