@socketsecurity/lib 5.14.0 → 5.16.0

package/dist/releases/github.d.ts

@@ -75,6 +75,13 @@ export declare const SOCKET_BTM_REPO: {
  *
  * @param pattern - Pattern to match (string glob, prefix/suffix object, or RegExp)
  * @returns Function that tests if a string matches the pattern
+ *
+ * @example
+ * ```typescript
+ * const isMatch = createAssetMatcher('tool-*-linux-x64')
+ * isMatch('tool-v1.0-linux-x64')  // true
+ * isMatch('tool-v1.0-darwin-arm64')  // false
+ * ```
  */
 export declare function createAssetMatcher(pattern: string | {
     prefix: string;
@@ -85,6 +92,16 @@ export declare function createAssetMatcher(pattern: string | {
  *
  * @param config - Download configuration
  * @returns Path to the downloaded binary
+ *
+ * @example
+ * ```typescript
+ * const binaryPath = await downloadGitHubRelease({
+ *   owner: 'SocketDev', repo: 'socket-btm',
+ *   toolName: 'lief', toolPrefix: 'lief-',
+ *   assetName: 'lief-linux-x64', binaryName: 'lief',
+ *   platformArch: 'linux-x64',
+ * })
+ * ```
  */
 export declare function downloadGitHubRelease(config: DownloadGitHubReleaseConfig): Promise<string>;
 /**
@@ -96,6 +113,14 @@ export declare function downloadGitHubRelease(config: DownloadGitHubReleaseConfi
  * @param outputPath - Path to write the downloaded file
  * @param repoConfig - Repository configuration (owner/repo)
  * @param options - Additional options
+ *
+ * @example
+ * ```typescript
+ * await downloadReleaseAsset(
+ *   'v1.0.0', 'tool-linux-x64', '/tmp/tool',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadReleaseAsset(tag: string, assetPattern: string | AssetPattern, outputPath: string, repoConfig: RepoConfig, options?: {
     quiet?: boolean;
@@ -105,6 +130,12 @@ export declare function downloadReleaseAsset(tag: string, assetPattern: string |
  * Checks GH_TOKEN or GITHUB_TOKEN environment variables.
  *
  * @returns Headers object with Authorization header if token exists.
+ *
+ * @example
+ * ```typescript
+ * const headers = getAuthHeaders()
+ * // { Accept: 'application/vnd.github+json', Authorization: 'Bearer ...' }
+ * ```
  */
 export declare function getAuthHeaders(): Record<string, string>;
 /**
@@ -116,6 +147,14 @@ export declare function getAuthHeaders(): Record<string, string>;
  * @param options - Additional options
  * @param options.assetPattern - Optional pattern to filter releases by matching asset
  * @returns Latest release tag or null if not found
+ *
+ * @example
+ * ```typescript
+ * const tag = await getLatestRelease('lief-', {
+ *   owner: 'SocketDev', repo: 'socket-btm',
+ * })
+ * console.log(tag) // 'lief-2025-01-15-abc1234'
+ * ```
  */
 export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoConfig, options?: {
     assetPattern?: AssetPattern;
@@ -130,6 +169,14 @@ export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoCon
  * @param repoConfig - Repository configuration (owner/repo)
  * @param options - Additional options
  * @returns Browser download URL for the asset
+ *
+ * @example
+ * ```typescript
+ * const url = await getReleaseAssetUrl(
+ *   'v1.0.0', 'tool-linux-x64',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function getReleaseAssetUrl(tag: string, assetPattern: string | AssetPattern, repoConfig: RepoConfig, options?: {
     quiet?: boolean;
@@ -146,6 +193,14 @@ export declare function getReleaseAssetUrl(tag: string, assetPattern: string | A
  * @param options.quiet - Suppress log messages
  * @param options.cleanup - Remove downloaded zip file after extraction (default: true)
  * @returns Path to the extraction directory
+ *
+ * @example
+ * ```typescript
+ * const outputDir = await downloadAndExtractZip(
+ *   'v1.0.0', 'models-*.zip', '/tmp/models',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadAndExtractZip(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
     cleanup?: boolean;
@@ -166,6 +221,14 @@ export declare function downloadAndExtractZip(tag: string, assetPattern: string
  * @param options.strip - Strip leading path components (like tar --strip-components)
  * @param options.format - Archive format (auto-detected if not specified)
  * @returns Path to the extraction directory
+ *
+ * @example
+ * ```typescript
+ * const outputDir = await downloadAndExtractArchive(
+ *   'v1.0.0', 'data-*.tar.gz', '/tmp/data',
+ *   { owner: 'SocketDev', repo: 'socket-btm' },
+ * )
+ * ```
  */
 export declare function downloadAndExtractArchive(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
     cleanup?: boolean;

package/dist/releases/socket-btm.d.ts

@@ -65,6 +65,12 @@ export type SocketBtmReleaseConfig = SocketBtmBinaryConfig | SocketBtmAssetConfi
  * Returns undefined for non-Linux platforms.
  *
  * @returns 'musl', 'glibc', or undefined (for non-Linux)
+ *
+ * @example
+ * ```typescript
+ * const libc = detectLibc()
+ * console.log(libc) // 'glibc', 'musl', or undefined
+ * ```
  */
 export declare function detectLibc(): Libc | undefined;
 /**
@@ -73,6 +79,13 @@ export declare function detectLibc(): Libc | undefined;
  * @param tool - Tool/package name for release matching (e.g., 'lief', 'curl')
  * @param options - Download configuration
  * @returns Path to the downloaded file
+ *
+ * @example
+ * ```typescript
+ * const binPath = await downloadSocketBtmRelease('lief', {
+ *   downloadDir: '/tmp/build/downloaded',
+ * })
+ * ```
  */
 export declare function downloadSocketBtmRelease(tool: string, options: SocketBtmReleaseConfig | undefined): Promise<string>;
 /**
@@ -83,6 +96,12 @@ export declare function downloadSocketBtmRelease(tool: string, options: SocketBt
  * @param arch - Target architecture
  * @param libc - Linux libc variant (optional)
  * @returns Asset name (e.g., 'binject-darwin-arm64', 'node-linux-x64-musl')
+ *
+ * @example
+ * ```typescript
+ * getBinaryAssetName('lief', 'linux', 'x64', 'musl')
+ * // 'lief-linux-x64-musl'
+ * ```
  */
 export declare function getBinaryAssetName(binaryBaseName: string, platform: Platform, arch: Arch, libc?: Libc | undefined): string;
 /**
@@ -91,6 +110,12 @@ export declare function getBinaryAssetName(binaryBaseName: string, platform: Pla
  * @param binaryBaseName - Binary basename (e.g., 'node', 'binject')
  * @param platform - Target platform
  * @returns Binary filename (e.g., 'node', 'node.exe')
+ *
+ * @example
+ * ```typescript
+ * getBinaryName('node', 'win32')  // 'node.exe'
+ * getBinaryName('node', 'linux')  // 'node'
+ * ```
  */
 export declare function getBinaryName(binaryBaseName: string, platform: Platform): string;
 /**
@@ -101,5 +126,11 @@ export declare function getBinaryName(binaryBaseName: string, platform: Platform
  * @param arch - Target architecture
  * @param libc - Linux libc variant (optional)
  * @returns Platform-arch identifier (e.g., 'darwin-arm64', 'linux-x64-musl', 'win-x64')
+ *
+ * @example
+ * ```typescript
+ * getPlatformArch('linux', 'x64', 'musl')  // 'linux-x64-musl'
+ * getPlatformArch('darwin', 'arm64')  // 'darwin-arm64'
+ * ```
  */
 export declare function getPlatformArch(platform: Platform, arch: Arch, libc?: Libc | undefined): string;

package/dist/sea.d.ts

@@ -1,10 +1,25 @@
 /**
  * Get the current SEA binary path.
  * Only valid when running as a SEA binary.
+ *
+ * @example
+ * ```typescript
+ * const binPath = getSeaBinaryPath()
+ * if (binPath) {
+ *   console.log(`Running as SEA binary: ${binPath}`)
+ * }
+ * ```
  */
 export declare function getSeaBinaryPath(): string | undefined;
 /**
  * Detect if the current process is running as a SEA binary.
  * Uses Node.js 24+ native API with caching for performance.
+ *
+ * @example
+ * ```typescript
+ * if (isSeaBinary()) {
+ *   console.log('Running as a Single Executable Application')
+ * }
+ * ```
  */
 export declare function isSeaBinary(): boolean;

package/dist/shadow.d.ts

@@ -13,5 +13,12 @@ export interface ShadowInstallationOptions {
  * @param options.cwd - Current working directory path to check
  * @param options.win32 - Whether running on Windows
  * @returns true if shadow installation should be skipped
+ *
+ * @example
+ * ```typescript
+ * if (shouldSkipShadow(binPath, { cwd: process.cwd() })) {
+ *   console.log('Skipping shadow binary installation')
+ * }
+ * ```
  */
 export declare function shouldSkipShadow(binPath: string, options?: ShadowInstallationOptions | undefined): boolean;

package/dist/signal-exit.d.ts

@@ -1,5 +1,11 @@
 /**
  * Load signal handlers and hook into process exit events.
+ *
+ * @example
+ * ```typescript
+ * load()
+ * // Signal handlers are now active
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function load(): void;
@@ -8,16 +14,37 @@ export interface OnExitOptions {
 }
 /**
  * Register a callback to run on process exit or signal.
+ *
+ * @example
+ * ```typescript
+ * const remove = onExit((code, signal) => {
+ *   console.log(`Exiting with code ${code}, signal ${signal}`)
+ * })
+ * // Later, to unregister:
+ * remove()
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function onExit(cb: (code: number | null, signal: string | null) => void, options?: OnExitOptions | undefined): () => void;
 /**
  * Get the list of signals that are currently being monitored.
+ *
+ * @example
+ * ```typescript
+ * const sigs = signals()
+ * console.log(sigs) // ['SIGABRT', 'SIGALRM', 'SIGHUP', ...]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function signals(): string[];
 /**
  * Unload signal handlers and restore original process behavior.
+ *
+ * @example
+ * ```typescript
+ * unload()
+ * // Signal handlers are now removed
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function unload(): void;

package/dist/sorts.d.ts

@@ -1,20 +1,47 @@
 /**
  * Compare semantic versions.
+ *
+ * @example
+ * ```typescript
+ * compareSemver('1.0.0', '2.0.0')  // -1
+ * compareSemver('2.0.0', '1.0.0')  // 1
+ * compareSemver('1.0.0', '1.0.0')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function compareSemver(a: string, b: string): number;
 /**
  * Simple string comparison.
+ *
+ * @example
+ * ```typescript
+ * compareStr('a', 'b')  // -1
+ * compareStr('b', 'a')  // 1
+ * compareStr('a', 'a')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function compareStr(a: string, b: string): number;
 /**
  * Compare two strings using locale-aware comparison.
+ *
+ * @example
+ * ```typescript
+ * localeCompare('a', 'b')  // -1
+ * localeCompare('b', 'a')  // 1
+ * localeCompare('a', 'a')  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function localeCompare(x: string, y: string): number;
 /**
  * Compare two strings using natural sorting (numeric-aware, case-insensitive).
+ *
+ * @example
+ * ```typescript
+ * naturalCompare('file2', 'file10')  // negative (file2 before file10)
+ * naturalCompare('img10', 'img2')    // positive (img10 after img2)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function naturalCompare(x: string, y: string): number;
@@ -22,6 +49,12 @@ export declare function naturalCompare(x: string, y: string): number;
 type FastSortFunction = ReturnType<typeof import('fast-sort').createNewSortInstance>;
 /**
  * Sort an array using natural comparison.
+ *
+ * @example
+ * ```typescript
+ * naturalSorter(['file10', 'file2', 'file1']).asc()
+ * // ['file1', 'file2', 'file10']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function naturalSorter<T>(arrayToSort: T[]): ReturnType<FastSortFunction>;

package/dist/spawn.d.ts

@@ -161,6 +161,15 @@ export interface SpawnSyncReturns<T> {
 /**
  * Enhances spawn error with better context.
  * Converts generic "command failed" to detailed error with command, exit code, and stderr.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await spawn('git', ['status'])
+ * } catch (err) {
+ *   throw enhanceSpawnError(err)
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function enhanceSpawnError(error: unknown): unknown;

package/dist/stdio/mask.d.ts

@@ -91,6 +91,12 @@ export interface OutputMask {
  * Create an output mask for controlling command output visibility.
  * The mask tracks whether output should be shown or hidden (buffered).
  * When hidden, output is buffered and a spinner is shown instead.
+ *
+ * @example
+ * ```typescript
+ * const mask = createOutputMask({ showOutput: false })
+ * console.log(mask.verbose)  // false
+ * ```
  */
 export declare function createOutputMask(options?: OutputMaskOptions): OutputMask;
 /**
@@ -99,6 +105,13 @@ export declare function createOutputMask(options?: OutputMaskOptions): OutputMas
  * - ctrl+o: Toggle between showing and hiding output.
  * - ctrl+c: Cancel the running process.
  * The handler manipulates terminal state using ANSI escape sequences.
+ *
+ * @example
+ * ```typescript
+ * const handler = createKeyboardHandler(mask, childProcess, {
+ *   message: 'Testing...',
+ * })
+ * ```
  */
 type ReadlineKey = {
     ctrl?: boolean;
@@ -113,6 +126,12 @@ export declare function createKeyboardHandler(mask: OutputMask, child: ChildProc
  * - Buffers stdout/stderr when not in verbose mode.
  * - Shows a spinner when output is masked.
  * - Allows toggling between masked and unmasked output with ctrl+o.
+ *
+ * @example
+ * ```typescript
+ * const child = spawn("pnpm", ["test"], { stdio: ["inherit", "pipe", "pipe"] })
+ * const exitCode = await attachOutputMask(child, { message: 'Running tests' })
+ * ```
  */
 export declare function attachOutputMask(child: ChildProcess, options?: OutputMaskOptions): Promise<number>;
 /**
@@ -120,6 +139,13 @@ export declare function attachOutputMask(child: ChildProcess, options?: OutputMa
  * Convenience wrapper around spawn + attachOutputMask.
  * Spawns a child process and attaches the output masking system to it.
  * stdin is inherited, stdout and stderr are piped for masking control.
+ *
+ * @example
+ * ```typescript
+ * const exitCode = await runWithMask('pnpm', ['test'], {
+ *   message: 'Running tests',
+ * })
+ * ```
  */
 export declare function runWithMask(command: string, args?: string[], options?: OutputMaskOptions & SpawnOptions): Promise<number>;
 export {};

package/dist/streams.d.ts

@@ -1,16 +1,44 @@
 import type { IterationOptions } from './promises';
 /**
  * Execute a function for each item in an iterable in parallel.
+ *
+ * @example
+ * ```typescript
+ * const urls = ['https://a.io', 'https://b.io']
+ * await parallelEach(urls, async (url) => {
+ *   await fetch(url)
+ * }, { concurrency: 4 })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function parallelEach<T>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<unknown>, options?: number | IterationOptions): Promise<void>;
 /**
  * Map over an iterable in parallel with concurrency control.
+ *
+ * @example
+ * ```typescript
+ * const ids = [1, 2, 3]
+ * for await (const result of parallelMap(ids, async (id) => {
+ *   return await fetchData(id)
+ * }, 4)) {
+ *   console.log(result)
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function parallelMap<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;
 /**
  * Transform an iterable with a function.
+ *
+ * @example
+ * ```typescript
+ * const lines = ['hello', 'world']
+ * for await (const upper of transform(lines, async (line) => {
+ *   return line.toUpperCase()
+ * })) {
+ *   console.log(upper)  // 'HELLO', 'WORLD'
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function transform<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;

package/dist/suppress-warnings.d.ts

@@ -37,6 +37,13 @@ export declare function setMaxEventTargetListeners(target: EventTarget | AbortSi
 /**
  * Restore the original process.emitWarning function.
  * Call this to re-enable all warnings after suppressing them.
+ *
+ * @example
+ * ```typescript
+ * suppressMaxListenersWarning()
+ * // ... do work ...
+ * restoreWarnings() // Re-enable all warnings
+ * ```
  */
 export declare function restoreWarnings(): void;
 /**

package/dist/temporary-executor.d.ts

@@ -5,5 +5,12 @@
  * When package managers run commands via exec/npx/dlx, they execute in temporary directories
  * that are cleaned up after execution. Creating persistent shadows or modifying PATH
  * in these contexts can break subsequent package manager commands.
+ *
+ * @example
+ * ```typescript
+ * if (isRunningInTemporaryExecutor()) {
+ *   console.log('Running in a temporary executor context')
+ * }
+ * ```
  */
 export declare function isRunningInTemporaryExecutor(cwd?: string): boolean;

package/dist/url.d.ts

@@ -1,15 +1,34 @@
 /**
  * Check if a value is a valid URL.
+ *
+ * @example
+ * ```typescript
+ * isUrl('https://example.com') // true
+ * isUrl('not a url')           // false
+ * isUrl(null)                  // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isUrl(value: string | URL | null | undefined): boolean;
 /**
  * Parse a value as a URL.
+ *
+ * @example
+ * ```typescript
+ * parseUrl('https://example.com')  // URL { href: 'https://example.com/' }
+ * parseUrl('invalid')              // undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function parseUrl(value: string | URL): URL | undefined;
 /**
  * Convert a URL search parameter to an array.
+ *
+ * @example
+ * ```typescript
+ * urlSearchParamAsArray('a, b, c') // ['a', 'b', 'c']
+ * urlSearchParamAsArray(null)      // []
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsArray(value: string | null | undefined): string[];
@@ -18,11 +37,24 @@ export interface UrlSearchParamAsBooleanOptions {
 }
 /**
  * Convert a URL search parameter to a boolean.
+ *
+ * @example
+ * ```typescript
+ * urlSearchParamAsBoolean('true') // true
+ * urlSearchParamAsBoolean('0')    // false
+ * urlSearchParamAsBoolean(null)   // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsBoolean(value: string | null | undefined, options?: UrlSearchParamAsBooleanOptions | undefined): boolean;
 /**
  * Helper to get array from URLSearchParams.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('tags=a,b,c')
+ * urlSearchParamsGetArray(params, 'tags') // ['a', 'b', 'c']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamsGetArray(params: URLSearchParams | null | undefined, key: string): string[];
@@ -31,6 +63,13 @@ export interface UrlSearchParamsGetBooleanOptions {
 }
 /**
  * Helper to get boolean from URLSearchParams.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('debug=true')
+ * urlSearchParamsGetBoolean(params, 'debug') // true
+ * urlSearchParamsGetBoolean(params, 'other') // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamsGetBoolean(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamsGetBooleanOptions | undefined): boolean;
@@ -39,6 +78,12 @@ export interface CreateRelativeUrlOptions {
 }
 /**
  * Create a relative URL for testing.
+ *
+ * @example
+ * ```typescript
+ * createRelativeUrl('/api/test')                                    // 'api/test'
+ * createRelativeUrl('/api/test', { base: 'https://example.com' })  // 'https://example.com/api/test'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function createRelativeUrl(path: string, options?: CreateRelativeUrlOptions | undefined): string;
@@ -47,6 +92,13 @@ export interface UrlSearchParamAsStringOptions {
 }
 /**
  * Get string value from URLSearchParams with a default.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('name=socket')
+ * urlSearchParamAsString(params, 'name')  // 'socket'
+ * urlSearchParamAsString(params, 'other') // ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsString(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsStringOptions | undefined): string;
@@ -55,6 +107,13 @@ export interface UrlSearchParamAsNumberOptions {
 }
 /**
  * Get number value from URLSearchParams with a default.
+ *
+ * @example
+ * ```typescript
+ * const params = new URLSearchParams('limit=10')
+ * urlSearchParamAsNumber(params, 'limit') // 10
+ * urlSearchParamAsNumber(params, 'other') // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsNumber(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsNumberOptions | undefined): number;