@socketsecurity/lib/dist/dlx-package.d.ts

Core utilities and infrastructure for Socket.dev security tools

import type { SpawnExtra, SpawnOptions } from './spawn';
import { spawn } from './spawn';
export interface DownloadPackageResult {
    /** Path to the installed package directory. */
    packageDir: string;
    /** Path to the binary. */
    binaryPath: string;
    /** Whether the package was newly installed. */
    installed: boolean;
}
export interface DlxPackageOptions {
    /**
     * Package to install (e.g., '@cyclonedx/cdxgen@10.0.0').
     * Aligns with npx --package flag.
     */
    package: string;
    /**
     * Binary name to execute (optional - auto-detected in most cases).
     *
     * Auto-detection logic:
     * 1. If package has only one binary, uses it automatically
     * 2. Tries user-provided binaryName
     * 3. Tries last segment of package name (e.g., 'cli' from '@socketsecurity/cli')
     * 4. Falls back to first binary
     *
     * Only needed when package has multiple binaries and auto-detection fails.
     *
     * @example
     * // Auto-detected (single binary)
     * { package: '@socketsecurity/cli' }  // Finds 'socket' binary automatically
     *
     * // Explicit (multiple binaries)
     * { package: 'some-tool', binaryName: 'specific-tool' }
     */
    binaryName?: string | undefined;
    /**
     * Force reinstallation even if package exists.
     * Aligns with npx --yes/-y flag behavior.
     */
    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 for the execution.
     */
    spawnOptions?: SpawnOptions | undefined;
}
export interface DlxPackageResult {
    /** Path to the installed package directory. */
    packageDir: string;
    /** Path to the binary that was executed. */
    binaryPath: string;
    /** Whether the package was newly installed. */
    installed: boolean;
    /** The spawn promise for the running process. */
    spawnPromise: ReturnType<typeof spawn>;
}
/**
 * Execute a package via DLX - install if needed and run its binary.
 *
 * This is the Socket equivalent of npx/pnpm dlx/yarn dlx, but using
 * our own cache directory (~/.socket/_dlx) and installation logic.
 *
 * Auto-forces reinstall for version ranges to get latest within range.
 *
 * @example
 * ```typescript
 * // Download and execute cdxgen
 * const result = await dlxPackage(
 *   ['--version'],
 *   { package: '@cyclonedx/cdxgen@10.0.0' }
 * )
 * await result.spawnPromise
 * ```
 */
export declare function dlxPackage(args: readonly string[] | string[], options?: DlxPackageOptions | undefined, spawnExtra?: SpawnExtra | undefined): Promise<DlxPackageResult>;
/**
 * Download and install a package without executing it.
 * This is useful for self-update or when you need the package files
 * but don't want to run the binary immediately.
 *
 * @example
 * ```typescript
 * // Install @socketsecurity/cli without running it
 * const result = await downloadPackage({
 *   package: '@socketsecurity/cli@1.2.0',
 *   force: true
 * })
 * console.log('Installed to:', result.packageDir)
 * console.log('Binary at:', result.binaryPath)
 * ```
 */
export declare function downloadPackage(options: DlxPackageOptions): Promise<DownloadPackageResult>;
/**
 * Execute a package's binary with cross-platform shell handling.
 * The package must already be installed (use downloadPackage first).
 *
 * On Windows, script files (.bat, .cmd, .ps1) require shell: true.
 * Matches npm/npx execution behavior.
 *
 * @example
 * ```typescript
 * // Execute an already-installed package
 * const downloaded = await downloadPackage({ package: 'cowsay@1.5.0' })
 * const result = await executePackage(
 *   downloaded.binaryPath,
 *   ['Hello World'],
 *   { stdio: 'inherit' }
 * )
 * ```
 */
export declare function executePackage(binaryPath: string, args: readonly string[] | string[], spawnOptions?: SpawnOptions | undefined, spawnExtra?: SpawnExtra | undefined): ReturnType<typeof spawn>;