import type { SpawnExtra, SpawnOptions } from './spawn';
import { spawn } 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 checksum (sha256) for verification.
     */
    checksum?: 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++ (socket_macho_decompress).
 *
 * Core Fields (present in all implementations):
 * - version: Schema version (currently "1.0.0")
 * - cache_key: First 16 chars of SHA-512 hash (matches directory name)
 * - timestamp: Unix timestamp in milliseconds
 * - checksum: Full hash of cached binary (SHA-512 for C++, SHA-256 for TypeScript)
 * - checksum_algorithm: "sha512" or "sha256"
 * - platform: "darwin" | "linux" | "win32"
 * - arch: "x64" | "arm64"
 * - size: Size of cached binary in bytes
 * - source: Origin information
 *   - type: "download" (from URL) or "decompression" (from embedded binary)
 *   - url: Download URL (if type is "download")
 *   - path: Source binary path (if type is "decompression")
 *
 * Extra Fields (implementation-specific):
 * - For C++ decompression:
 *   - compressed_size: Size of compressed data in bytes
 *   - compression_algorithm: Brotli level (numeric)
 *   - compression_ratio: original_size / compressed_size
 *
 * Example (TypeScript download):
 * ```json
 * {
 *   "version": "1.0.0",
 *   "cache_key": "a1b2c3d4e5f67890",
 *   "timestamp": 1730332800000,
 *   "checksum": "sha256-abc123...",
 *   "checksum_algorithm": "sha256",
 *   "platform": "darwin",
 *   "arch": "arm64",
 *   "size": 15000000,
 *   "source": {
 *     "type": "download",
 *     "url": "https://example.com/binary"
 *   }
 * }
 * ```
 *
 * Example (C++ decompression):
 * ```json
 * {
 *   "version": "1.0.0",
 *   "cache_key": "0123456789abcdef",
 *   "timestamp": 1730332800000,
 *   "checksum": "sha512-def456...",
 *   "checksum_algorithm": "sha512",
 *   "platform": "darwin",
 *   "arch": "arm64",
 *   "size": 13000000,
 *   "source": {
 *     "type": "decompression",
 *     "path": "/usr/local/bin/socket"
 *   },
 *   "extra": {
 *     "compressed_size": 1700000,
 *     "compression_algorithm": 3,
 *     "compression_ratio": 7.647
 *   }
 * }
 * ```
 *
 * @internal This interface documents the metadata file format.
 */
export interface DlxMetadata {
    version: string;
    cache_key: string;
    timestamp: number;
    checksum: string;
    checksum_algorithm: string;
    platform: string;
    arch: string;
    size: number;
    source?: {
        type: 'download' | 'decompression';
        url?: string;
        path?: string;
    };
    extra?: Record<string, unknown>;
}
/**
 * Clean expired entries from the DLX cache.
 */
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.
 * Uses same directory as dlx-package for unified DLX storage.
 */
export declare function getDlxCachePath(): string;
/**
 * Get information about cached binaries.
 */
export declare function listDlxCache(): Promise<Array<{
    age: number;
    arch: string;
    checksum: string;
    name: string;
    platform: string;
    size: number;
    url: string;
}>>;
