@socketsecurity/lib 5.15.0 → 5.17.0

package/dist/packages/operations.d.ts

@@ -1,31 +1,65 @@
 import type { ExtractOptions, NormalizeOptions, PackageJson, PacoteOptions, ReadPackageJsonOptions } from '../packages';
 /**
  * Extract a package to a destination directory.
+ *
+ * @example
+ * ```typescript
+ * await extractPackage('lodash@4.17.21', { dest: '/tmp/lodash' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function extractPackage(pkgNameOrId: string, options?: ExtractOptions, callback?: (destPath: string) => Promise<unknown>): Promise<void>;
 /**
  * Find package extensions for a given package.
+ *
+ * @example
+ * ```typescript
+ * const extensions = findPackageExtensions('my-pkg', '1.0.0')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function findPackageExtensions(pkgName: string, pkgVer: string): unknown;
 /**
  * Get the release tag for a version.
+ *
+ * @example
+ * ```typescript
+ * getReleaseTag('lodash@latest')    // 'latest'
+ * getReleaseTag('@scope/pkg@beta')  // 'beta'
+ * getReleaseTag('lodash')           // ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getReleaseTag(spec: string): string;
 /**
  * Pack a package tarball using pacote.
+ *
+ * @example
+ * ```typescript
+ * const tarball = await packPackage('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function packPackage(spec: string, options?: PacoteOptions): Promise<unknown>;
 /**
  * Read and parse a package.json file asynchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = await readPackageJson('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function readPackageJson(filepath: string, options?: ReadPackageJsonOptions): Promise<PackageJson | undefined>;
 /**
  * Read and parse package.json from a file path synchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = readPackageJsonSync('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function readPackageJsonSync(filepath: string, options?: NormalizeOptions & {
@@ -34,11 +68,22 @@ export declare function readPackageJsonSync(filepath: string, options?: Normaliz
 }): PackageJson | undefined;
 /**
  * Resolve GitHub tarball URL for a package specifier.
+ *
+ * @example
+ * ```typescript
+ * const url = await resolveGitHubTgzUrl('my-pkg@1.0.0', '/tmp/my-project')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveGitHubTgzUrl(pkgNameOrId: string, where?: unknown): Promise<string>;
 /**
  * Resolve full package name from a PURL object with custom delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageName({ name: 'core', namespace: '@babel' })  // '@babel/core'
+ * resolvePackageName({ name: 'lodash' })                     // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolvePackageName(purlObj: {
@@ -47,6 +92,12 @@ export declare function resolvePackageName(purlObj: {
 }, delimiter?: string): string;
 /**
  * Convert npm package name to Socket registry format with delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolveRegistryPackageName('@babel/core') // 'babel__core'
+ * resolveRegistryPackageName('lodash')      // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function resolveRegistryPackageName(pkgName: string): string;

package/dist/packages/provenance.d.ts

@@ -1,10 +1,21 @@
 import type { ProvenanceOptions } from '../packages';
 /**
  * Convert raw attestation data to user-friendly provenance details.
+ *
+ * @example
+ * ```typescript
+ * const details = getProvenanceDetails(attestationData)
+ * // { level: 'trusted', repository: '...', commitSha: '...' }
+ * ```
  */
 export declare function getProvenanceDetails(attestationData: unknown): unknown;
 /**
  * Fetch package provenance information from npm registry.
+ *
+ * @example
+ * ```typescript
+ * const provenance = await fetchPackageProvenance('lodash', '4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function fetchPackageProvenance(pkgName: string, pkgVersion: string, options?: ProvenanceOptions): Promise<unknown>;

package/dist/packages/specs.d.ts

@@ -1,5 +1,11 @@
 /**
  * Extract user and project from GitHub repository URL.
+ *
+ * @example
+ * ```typescript
+ * getRepoUrlDetails('https://github.com/lodash/lodash.git')
+ * // { user: 'lodash', project: 'lodash' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getRepoUrlDetails(repoUrl?: string): {
@@ -8,21 +14,45 @@ export declare function getRepoUrlDetails(repoUrl?: string): {
 };
 /**
  * Generate GitHub API URL for a tag reference.
+ *
+ * @example
+ * ```typescript
+ * gitHubTagRefUrl('lodash', 'lodash', 'v4.17.21')
+ * // 'https://api.github.com/repos/lodash/lodash/git/ref/tags/v4.17.21'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function gitHubTagRefUrl(user: string, project: string, tag: string): string;
 /**
  * Generate GitHub tarball download URL for a commit SHA.
+ *
+ * @example
+ * ```typescript
+ * gitHubTgzUrl('lodash', 'lodash', 'abc123')
+ * // 'https://github.com/lodash/lodash/archive/abc123.tar.gz'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function gitHubTgzUrl(user: string, project: string, sha: string): string;
 /**
  * Check if a package specifier is a GitHub tarball URL.
+ *
+ * @example
+ * ```typescript
+ * isGitHubTgzSpec('https://github.com/user/repo/archive/abc123.tar.gz') // true
+ * isGitHubTgzSpec('lodash@4.17.21')                                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isGitHubTgzSpec(spec: unknown, where?: string): boolean;
 /**
  * Check if a package specifier is a GitHub URL with committish.
+ *
+ * @example
+ * ```typescript
+ * isGitHubUrlSpec('github:user/repo#v1.0.0') // true
+ * isGitHubUrlSpec('lodash@4.17.21')           // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isGitHubUrlSpec(spec: unknown, where?: string): boolean;

package/dist/packages/validation.d.ts

@@ -1,15 +1,33 @@
 /**
  * Check if package name is a blessed Socket.dev package.
+ *
+ * @example
+ * ```typescript
+ * isBlessedPackageName('@socketregistry/is-number') // true
+ * isBlessedPackageName('lodash')                    // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isBlessedPackageName(name: unknown): boolean;
 /**
  * Check if a type string represents a registry fetcher type.
+ *
+ * @example
+ * ```typescript
+ * isRegistryFetcherType('range')   // true
+ * isRegistryFetcherType('git')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isRegistryFetcherType(type: string): boolean;
 /**
  * Check if a package name is valid according to npm naming rules.
+ *
+ * @example
+ * ```typescript
+ * isValidPackageName('my-package')   // true
+ * isValidPackageName('.invalid')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isValidPackageName(name: string): boolean;

package/dist/paths/normalize.d.ts

@@ -141,6 +141,75 @@ export declare function isPath(pathLike: string | Buffer | URL): boolean;
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isRelative(pathLike: string | Buffer | URL): boolean;
+/**
+ * Check if a path uses MSYS/Git Bash Unix-style drive letter notation.
+ *
+ * Detects paths in the format `/c/...` where a single letter after the leading
+ * slash represents a Windows drive letter. These paths are produced by MSYS2,
+ * Git Bash, and `command -v` on Windows.
+ *
+ * Detection rules:
+ * - Must start with `/` followed by a single ASCII letter (a-z, A-Z)
+ * - The letter must be followed by `/` or be at the end of the string
+ * - Examples: `/c/tools/bin`, `/d/projects`, `/c`
+ * - Non-matches: `/tmp`, `/usr/local`, `C:/Windows`
+ *
+ * @param {string | Buffer | URL} pathLike - The path to check
+ * @returns {boolean} `true` if the path uses MSYS drive letter notation
+ *
+ * @example
+ * ```typescript
+ * // MSYS drive letter paths
+ * isUnixPath('/c/tools/bin')         // true
+ * isUnixPath('/d/projects/app')       // true
+ * isUnixPath('/c')                    // true
+ * isUnixPath('/C/Windows')            // true
+ *
+ * // Not MSYS drive paths
+ * isUnixPath('/tmp/build')            // false
+ * isUnixPath('/usr/local/bin')        // false
+ * isUnixPath('C:/Windows')            // false
+ * isUnixPath('./relative')            // false
+ * isUnixPath('')                      // false
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isUnixPath(pathLike: string | Buffer | URL): boolean;
+/**
+ * Convert Unix-style POSIX paths to native Windows paths.
+ *
+ * This is the inverse of {@link toUnixPath}. On Windows, MSYS-style paths use
+ * `/c/` notation for drive letters and forward slashes, which PowerShell and
+ * cmd.exe cannot resolve. This function converts them to native Windows format
+ * with backslashes and proper drive letters.
+ *
+ * Conversion rules:
+ * - On Windows: Converts drive notation and separators to native format
+ *   - `/c/path/to/file` becomes `C:\path\to\file`
+ *   - `/d/projects/app` becomes `D:\projects\app`
+ *   - Forward slashes become backslashes
+ *   - Drive letters are always uppercase in the output
+ * - On Unix: Returns the normalized path unchanged (forward slashes preserved)
+ *
+ * @param {string | Buffer | URL} pathLike - The MSYS/Unix-style path to convert
+ * @returns {string} Native Windows path (e.g., `C:\path\to\file`) or normalized Unix path
+ *
+ * @example
+ * ```typescript
+ * // MSYS drive letter paths (Windows)
+ * fromUnixPath('/c/projects/app/file.txt')    // 'C:\\projects\\app\\file.txt'
+ * fromUnixPath('/d/projects/foo/bar')         // 'D:\\projects\\foo\\bar'
+ * fromUnixPath('/c')                          // 'C:\\'
+ *
+ * // Forward-slash paths (Windows)
+ * fromUnixPath('C:/Windows/System32')         // 'C:\\Windows\\System32'
+ *
+ * // Unix (unchanged, forward slashes preserved)
+ * fromUnixPath('/tmp/build/output')           // '/tmp/build/output'
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function fromUnixPath(pathLike: string | Buffer | URL): string;
 /**
  * Normalize a path by converting backslashes to forward slashes and collapsing segments.
  *
@@ -154,6 +223,7 @@ export declare function isRelative(pathLike: string | Buffer | URL): boolean;
  * - Returns `.` for empty or collapsed paths
  *
  * Special handling:
+ * - MSYS drive letters (Windows only): `/c/path` becomes `C:/path`
  * - UNC paths: Maintains double leading slashes for `//server/share` format
  * - Windows namespaces: Preserves `//./` and `//?/` prefixes
  * - Leading `..` segments: Preserved in relative paths without prefix
@@ -180,6 +250,10 @@ export declare function isRelative(pathLike: string | Buffer | URL): boolean;
  * normalizePath('C:\\Users\\username\\file.txt') // 'C:/Users/username/file.txt'
  * normalizePath('foo\\bar\\baz')                 // 'foo/bar/baz'
  *
+ * // MSYS drive letters (Windows only)
+ * normalizePath('/c/projects/app')              // 'C:/projects/app' (on Windows)
+ * normalizePath('/d/tools/bin')                 // 'D:/tools/bin' (on Windows)
+ *
  * // UNC paths
  * normalizePath('\\\\server\\share\\file')   // '//server/share/file'
  *
@@ -348,21 +422,23 @@ export declare function trimLeadingDotSlash(pathLike: string | Buffer | URL): st
 /*@__NO_SIDE_EFFECTS__*/
 export declare function relativeResolve(from: string, to: string): string;
 /**
- * Convert Windows paths to Unix-style POSIX paths for Git Bash tools.
+ * Convert Windows paths to MSYS/Unix-style POSIX paths for Git Bash tools.
  *
- * Git for Windows tools (like tar, git, etc.) expect POSIX-style paths with
- * forward slashes and Unix drive letter notation (/c/ instead of C:\).
+ * Git for Windows and MSYS2 tools (like tar, git, etc.) expect POSIX-style
+ * paths with forward slashes and Unix drive letter notation (/c/ instead of C:\).
  * This function handles the conversion for cross-platform compatibility.
  *
+ * This is the inverse of {@link fromUnixPath}.
+ *
  * Conversion rules:
  * - On Windows: Normalizes separators and converts drive letters
  *   - `C:\path\to\file` becomes `/c/path/to/file`
- *   - `D:/Users/name` becomes `/d/Users/name`
+ *   - `D:/projects/app` becomes `/d/projects/app`
  *   - Drive letters are always lowercase in the output
  * - On Unix: Returns the path unchanged (passes through normalization)
  *
  * This is particularly important for:
- * - Git Bash tools that interpret `D:\` as a remote hostname
+ * - MSYS2/Git Bash tools that interpret `D:\` as a remote hostname
  * - Cross-platform build scripts using tar, git archive, etc.
  * - CI/CD environments where Git for Windows is used
  *

package/dist/paths/normalize.js

@@ -19,10 +19,12 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var normalize_exports = {};
 __export(normalize_exports, {
+  fromUnixPath: () => fromUnixPath,
   isAbsolute: () => isAbsolute,
   isNodeModules: () => isNodeModules,
   isPath: () => isPath,
   isRelative: () => isRelative,
+  isUnixPath: () => isUnixPath,
   normalizePath: () => normalizePath,
   pathLikeToString: () => pathLikeToString,
   relativeResolve: () => relativeResolve,
@@ -40,6 +42,7 @@ const CHAR_LOWERCASE_A = 97;
 const CHAR_LOWERCASE_Z = 122;
 const CHAR_UPPERCASE_A = 65;
 const CHAR_UPPERCASE_Z = 90;
+const msysDriveRegExp = /^\/([a-zA-Z])(\/|$)/;
 const slashRegExp = /[/\\]/;
 const nodeModulesPathRegExp = /(?:^|[/\\])node_modules(?:[/\\]|$)/;
 // @__NO_SIDE_EFFECTS__
@@ -66,6 +69,15 @@ function getUrl() {
   }
   return _url;
 }
+function msysDriveToNative(normalized) {
+  if (import_platform.WIN32) {
+    return normalized.replace(
+      msysDriveRegExp,
+      (_, letter, sep) => `${letter.toUpperCase()}:${sep || "/"}`
+    );
+  }
+  return normalized;
+}
 // @__NO_SIDE_EFFECTS__
 function isNodeModules(pathLike) {
   const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
@@ -130,6 +142,19 @@ function isRelative(pathLike) {
   return !/* @__PURE__ */ isAbsolute(filepath);
 }
 // @__NO_SIDE_EFFECTS__
+function isUnixPath(pathLike) {
+  const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
+  return typeof filepath === "string" && msysDriveRegExp.test(filepath);
+}
+// @__NO_SIDE_EFFECTS__
+function fromUnixPath(pathLike) {
+  const normalized = /* @__PURE__ */ normalizePath(pathLike);
+  if (import_platform.WIN32) {
+    return normalized.replace(/\//g, "\\");
+  }
+  return normalized;
+}
+// @__NO_SIDE_EFFECTS__
 function normalizePath(pathLike) {
   const filepath = /* @__PURE__ */ pathLikeToString(pathLike);
   const { length } = filepath;
@@ -207,7 +232,7 @@ function normalizePath(pathLike) {
     if (segment === "..") {
       return prefix ? prefix.slice(0, -1) || "/" : "..";
     }
-    return prefix + segment;
+    return msysDriveToNative(prefix + segment);
   }
   let collapsed = "";
   let segmentCount = 0;
@@ -288,7 +313,7 @@ function normalizePath(pathLike) {
   if (collapsed.length === 0) {
     return prefix || ".";
   }
-  return prefix + collapsed;
+  return msysDriveToNative(prefix + collapsed);
 }
 // @__NO_SIDE_EFFECTS__
 function pathLikeToString(pathLike) {
@@ -448,10 +473,12 @@ function toUnixPath(pathLike) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  fromUnixPath,
   isAbsolute,
   isNodeModules,
   isPath,
   isRelative,
+  isUnixPath,
   normalizePath,
   pathLikeToString,
   relativeResolve,

package/dist/paths/rewire.js

@@ -28,9 +28,18 @@ __export(rewire_exports, {
   setPath: () => setPath
 });
 module.exports = __toCommonJS(rewire_exports);
-const testOverrides = /* @__PURE__ */ new Map();
-const valueCache = /* @__PURE__ */ new Map();
-const cacheInvalidationCallbacks = [];
+const stateSymbol = Symbol.for("@socketsecurity/lib/paths/rewire/state");
+if (!globalThis[stateSymbol]) {
+  globalThis[stateSymbol] = {
+    testOverrides: /* @__PURE__ */ new Map(),
+    valueCache: /* @__PURE__ */ new Map(),
+    cacheInvalidationCallbacks: []
+  };
+}
+const sharedState = globalThis[stateSymbol];
+const testOverrides = sharedState.testOverrides;
+const valueCache = sharedState.valueCache;
+const cacheInvalidationCallbacks = sharedState.cacheInvalidationCallbacks;
 function clearPath(key) {
   testOverrides.delete(key);
   invalidateCaches();

package/dist/regexps.d.ts

@@ -8,6 +8,13 @@
 // Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
 /**
  * Escape special characters in a string for use in a regular expression.
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp('foo.bar')     // 'foo\\.bar'
+ * escapeRegExp('a+b*c?')     // 'a\\+b\\*c\\?'
+ * new RegExp(escapeRegExp('[test]'))  // /\[test\]/
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function escapeRegExp(str: string): string;

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;