@socketsecurity/lib 6.0.6 → 6.0.7

package/dist/promises/iterate.js

@@ -67,13 +67,12 @@ const require_arrays_chunk = require('../arrays/chunk.js');
 *
 * @returns Promise that resolves when all items are processed
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function pEach(array, callbackFn, options) {
-	const { concurrency, retries, signal } = /* @__PURE__ */ require_promises_options.normalizeIterationOptions(options);
-	const chunks = /* @__PURE__ */ require_arrays_chunk.arrayChunk(array, concurrency);
+	const { concurrency, retries, signal } = require_promises_options.normalizeIterationOptions(options);
+	const chunks = require_arrays_chunk.arrayChunk(array, concurrency);
 	for (const chunk of chunks) {
 		if (signal?.aborted) return;
-		await require_primordials_promise.PromiseAllSettled(chunk.map((item) => /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+		await require_primordials_promise.PromiseAllSettled(chunk.map((item) => require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
 			...retries,
 			args: [item],
 			signal
@@ -133,15 +132,14 @@ async function pEach(array, callbackFn, options) {
 *
 * @returns Promise that resolves when all chunks are processed
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function pEachChunk(array, callbackFn, options) {
 	const { chunkSize = 100, ...retryOpts } = options || {};
-	const chunks = /* @__PURE__ */ require_arrays_chunk.arrayChunk(array, chunkSize);
-	const normalizedRetryOpts = /* @__PURE__ */ require_promises_options.normalizeRetryOptions(retryOpts);
+	const chunks = require_arrays_chunk.arrayChunk(array, chunkSize);
+	const normalizedRetryOpts = require_promises_options.normalizeRetryOptions(retryOpts);
 	const { signal } = normalizedRetryOpts;
 	for (const chunk of chunks) {
 		if (signal?.aborted) return;
-		await /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+		await require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
 			...normalizedRetryOpts,
 			args: [chunk]
 		});
@@ -194,10 +192,9 @@ async function pEachChunk(array, callbackFn, options) {
 *
 * @returns Promise resolving to filtered array
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function pFilter(array, callbackFn, options) {
-	const iterOpts = /* @__PURE__ */ require_promises_options.normalizeIterationOptions(options);
-	return (await /* @__PURE__ */ pFilterChunk(/* @__PURE__ */ require_arrays_chunk.arrayChunk(array, iterOpts.concurrency), callbackFn, iterOpts.retries)).flat();
+	const iterOpts = require_promises_options.normalizeIterationOptions(options);
+	return (await pFilterChunk(require_arrays_chunk.arrayChunk(array, iterOpts.concurrency), callbackFn, iterOpts.retries)).flat();
 }
 /**
 * Filter chunked arrays with an async predicate.
@@ -222,20 +219,19 @@ async function pFilter(array, callbackFn, options) {
 *
 * @returns Promise resolving to array of filtered chunks
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function pFilterChunk(chunks, callbackFn, options) {
-	const retryOpts = /* @__PURE__ */ require_promises_options.normalizeRetryOptions(options);
+	const retryOpts = require_promises_options.normalizeRetryOptions(options);
 	const { signal } = retryOpts;
 	const { length } = chunks;
 	const filteredChunks = Array(length);
 	for (let i = 0; i < length; i += 1) if (signal?.aborted) filteredChunks[i] = [];
 	else {
 		const chunk = chunks[i];
-		const predicateResults = (await require_primordials_promise.PromiseAllSettled(chunk.map((value) => /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+		const predicateResults = (await require_primordials_promise.PromiseAllSettled(chunk.map((value) => require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
 			...retryOpts,
 			args: [value]
 		})))).map((r) => r.status === "fulfilled" ? r.value : false);
-		filteredChunks[i] = chunk.filter((_v, i) => predicateResults[i]);
+		filteredChunks[i] = chunk.filter((_value, index) => predicateResults[index]);
 	}
 	return filteredChunks;
 }

package/dist/promises/options.js

@@ -33,7 +33,6 @@ const require_promises__internal = require('./_internal.js');
 *
 * @returns Normalized options with concurrency, retries, and signal
 */
-/*@__NO_SIDE_EFFECTS__*/
 function normalizeIterationOptions(options) {
 	const { concurrency = 1, retries, signal = require_promises__internal.abortSignal } = {
 		__proto__: null,
@@ -42,9 +41,9 @@ function normalizeIterationOptions(options) {
 	return {
 		__proto__: null,
 		concurrency: require_primordials_math.MathMax(1, concurrency),
-		retries: /* @__PURE__ */ normalizeRetryOptions({
+		retries: normalizeRetryOptions({
 			signal,
-			.../* @__PURE__ */ resolveRetryOptions(retries)
+			...resolveRetryOptions(retries)
 		}),
 		signal
 	};
@@ -70,9 +69,8 @@ function normalizeIterationOptions(options) {
 *
 * @returns Normalized retry options with all properties set
 */
-/*@__NO_SIDE_EFFECTS__*/
 function normalizeRetryOptions(options) {
-	const { args = [], backoffFactor = 2, baseDelayMs = 200, jitter = true, maxDelayMs = 1e4, onRetry, onRetryCancelOnFalse = false, onRetryRethrow = false, retries = 0, signal = require_promises__internal.abortSignal } = /* @__PURE__ */ resolveRetryOptions(options);
+	const { args = [], backoffFactor = 2, baseDelayMs = 200, jitter = true, maxDelayMs = 1e4, onRetry, onRetryCancelOnFalse = false, onRetryRethrow = false, retries = 0, signal = require_promises__internal.abortSignal } = resolveRetryOptions(options);
 	return {
 		args,
 		backoffFactor,
@@ -105,7 +103,6 @@ function normalizeRetryOptions(options) {
 *
 * @returns Resolved retry options with defaults for basic properties
 */
-/*@__NO_SIDE_EFFECTS__*/
 function resolveRetryOptions(options) {
 	const defaults = {
 		__proto__: null,

package/dist/promises/retry.js

@@ -110,12 +110,11 @@ const require_promises_options = require('./options.js');
 *
 * @throws {Error} The last error if all retry attempts fail
 */
-/*@__NO_SIDE_EFFECTS__*/
 async function pRetry(callbackFn, options) {
-	const { args, backoffFactor, baseDelayMs, jitter, maxDelayMs, onRetry, onRetryCancelOnFalse, onRetryRethrow, retries, signal } = /* @__PURE__ */ require_promises_options.normalizeRetryOptions(options);
+	const { args, backoffFactor, baseDelayMs, jitter, maxDelayMs, onRetry, onRetryCancelOnFalse, onRetryRethrow, retries, signal } = require_promises_options.normalizeRetryOptions(options);
 	if (signal?.aborted) return;
 	if (retries === 0) return await callbackFn(...args || [], { signal });
-	const timers = /* @__PURE__ */ require_promises__internal.getTimers();
+	const timers = require_promises__internal.getTimers();
 	let attempts = retries;
 	let delay = baseDelayMs;
 	let error = void 0;
@@ -136,8 +135,8 @@ async function pRetry(callbackFn, options) {
 				const result = onRetry(retries - attempts, e, waitTime);
 				if (result === false && onRetryCancelOnFalse) break;
 				if (typeof result === "number" && result >= 0) waitTime = require_primordials_math.MathMin(result, maxDelayMs);
-			} catch (e) {
-				if (onRetryRethrow) throw e;
+			} catch (onRetryError) {
+				if (onRetryRethrow) throw onRetryError;
 			}
 			/* c8 ignore stop */
 			try {

package/dist/promises/timers.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Browser-compatible promise-based timer helpers. Uses
+ *   `globalThis.setTimeout` / `globalThis.queueMicrotask` directly so every
+ *   export works in browsers, Node.js, Deno, Bun, and Web Workers without
+ *   importing `node:timers/promises`. In Node.js test environments with
+ *   `vi.useFakeTimers()` / `clock.install()`, vitest/sinon replace
+ *   `globalThis.setTimeout` before this module loads, so fake timers advance
+ *   `sleep()` correctly — no special wiring needed. For Node-only
+ *   abort-signal-aware delays see `promises/_internal.ts`.
+ */
+/**
+ * Pause for `ms` milliseconds. Resolves with `undefined` when the timer fires.
+ * Negative values are clamped to 0.
+ *
+ * @example
+ *   await sleep(100)
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Yield to the event loop once. Resolves after the current call stack and any
+ * already-queued microtasks have completed — equivalent to `setTimeout(fn, 0)`
+ * as described in
+ * https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#late_timeouts.
+ * Useful for flushing microtask queues in tests or giving the browser a repaint
+ * opportunity between heavy operations.
+ *
+ * @example
+ *   await yieldToEventLoop()
+ */
+export declare function yieldToEventLoop(): Promise<void>;

package/dist/promises/timers.js

@@ -0,0 +1,48 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_promise = require('../primordials/promise.js');
+
+//#region src/promises/timers.ts
+/**
+* @file Browser-compatible promise-based timer helpers. Uses
+*   `globalThis.setTimeout` / `globalThis.queueMicrotask` directly so every
+*   export works in browsers, Node.js, Deno, Bun, and Web Workers without
+*   importing `node:timers/promises`. In Node.js test environments with
+*   `vi.useFakeTimers()` / `clock.install()`, vitest/sinon replace
+*   `globalThis.setTimeout` before this module loads, so fake timers advance
+*   `sleep()` correctly — no special wiring needed. For Node-only
+*   abort-signal-aware delays see `promises/_internal.ts`.
+*/
+/**
+* Pause for `ms` milliseconds. Resolves with `undefined` when the timer fires.
+* Negative values are clamped to 0.
+*
+* @example
+*   await sleep(100)
+*/
+function sleep(ms) {
+	return new require_primordials_promise.PromiseCtor((resolve) => {
+		setTimeout(resolve, ms > 0 ? ms : 0);
+	});
+}
+/**
+* Yield to the event loop once. Resolves after the current call stack and any
+* already-queued microtasks have completed — equivalent to `setTimeout(fn, 0)`
+* as described in
+* https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout#late_timeouts.
+* Useful for flushing microtask queues in tests or giving the browser a repaint
+* opportunity between heavy operations.
+*
+* @example
+*   await yieldToEventLoop()
+*/
+function yieldToEventLoop() {
+	return new require_primordials_promise.PromiseCtor((resolve) => {
+		setTimeout(resolve, 0);
+	});
+}
+
+//#endregion
+exports.sleep = sleep;
+exports.yieldToEventLoop = yieldToEventLoop;

package/dist/releases/github-archives.d.ts

@@ -34,10 +34,10 @@ import type { AssetPattern, RepoConfig } from './github-types';
  * @returns Path to the extraction directory
  */
 export declare function downloadAndExtractArchive(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
-    cleanup?: boolean;
-    format?: ArchiveFormat;
-    quiet?: boolean;
-    strip?: number;
+    cleanup?: boolean | undefined;
+    format?: ArchiveFormat | undefined;
+    quiet?: boolean | undefined;
+    strip?: number | undefined;
 }): Promise<string>;
 /**
  * Download and extract a zip file from a GitHub release. Automatically handles
@@ -66,6 +66,6 @@ export declare function downloadAndExtractArchive(tag: string, assetPattern: str
  * @returns Path to the extraction directory
  */
 export declare function downloadAndExtractZip(tag: string, assetPattern: string | AssetPattern, outputDir: string, repoConfig: RepoConfig, options?: {
-    cleanup?: boolean;
-    quiet?: boolean;
+    cleanup?: boolean | undefined;
+    quiet?: boolean | undefined;
 }): Promise<string>;

package/dist/releases/github-archives.js

@@ -46,7 +46,7 @@ const logger = require_logger_default.getDefaultLogger();
 */
 async function downloadAndExtractArchive(tag, assetPattern, outputDir, repoConfig, options = { __proto__: null }) {
 	const { cleanup = true, format, quiet = false, strip } = options;
-	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const path = require_node_path.getNodePath();
 	await require_fs_safe.safeMkdir(outputDir);
 	let ext = ".archive";
 	if (format) ext = format === "tar.gz" ? ".tar.gz" : `.${format}`;
@@ -104,7 +104,7 @@ async function downloadAndExtractArchive(tag, assetPattern, outputDir, repoConfi
 */
 async function downloadAndExtractZip(tag, assetPattern, outputDir, repoConfig, options = { __proto__: null }) {
 	const { cleanup = true, quiet = false } = options;
-	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const path = require_node_path.getNodePath();
 	await require_fs_safe.safeMkdir(outputDir);
 	const zipPath = path.join(outputDir, "__temp_download__.zip");
 	if (!quiet) logger.info(`Downloading zip asset from release ${tag}...`);

package/dist/releases/github-asset-url.d.ts

@@ -68,5 +68,5 @@ export declare function fetchReleaseAssetsViaGraphQL(owner: string, repo: string
  *   false.
  */
 export declare function getReleaseAssetUrl(tag: string, assetPattern: string | AssetPattern, repoConfig: RepoConfig, options?: {
-    nothrow?: boolean;
+    nothrow?: boolean | undefined;
 }): Promise<string | undefined>;

package/dist/releases/github-asset-url.js

@@ -123,10 +123,10 @@ async function getReleaseAssetUrl(tag, assetPattern, repoConfig, options = {}) {
 	/* c8 ignore start */
 	const isMatch = typeof assetPattern === "string" && !assetPattern.includes("*") && !assetPattern.includes("{") ? (input) => input === assetPattern : require_releases_github_assets.createAssetMatcher(assetPattern);
 	/* c8 ignore stop */
-	const assets = await /* @__PURE__ */ require_promises_retry.pRetry(async () => {
+	const assets = await require_promises_retry.pRetry(async () => {
 		const response = await require_http_request_request.httpRequest(`https://api.github.com/repos/${owner}/${repo}/releases/tags/${tag}`, { headers: require_releases_github_auth.getAuthHeaders() });
 		if (!response.ok) throw new require_primordials_error.ErrorCtor(`Failed to fetch ${owner}/${repo} release ${tag}: ${response.status}`);
-		let assets;
+		let resolvedAssets;
 		if (response.body.byteLength === 0) {
 			let fallbackAssets;
 			try {
@@ -142,7 +142,7 @@ async function getReleaseAssetUrl(tag, assetPattern, repoConfig, options = {}) {
 				if (nothrow) return;
 				throw new require_primordials_error.ErrorCtor(`Release ${tag} not found in ${owner}/${repo}`);
 			}
-			assets = fallbackAssets;
+			resolvedAssets = fallbackAssets;
 		} else {
 			let release;
 			try {
@@ -151,9 +151,9 @@ async function getReleaseAssetUrl(tag, assetPattern, repoConfig, options = {}) {
 				throw new require_primordials_error.ErrorCtor(`Failed to parse ${owner}/${repo} release ${tag} response`, { cause });
 			}
 			if (!require_primordials_array.ArrayIsArray(release.assets)) throw new require_primordials_error.ErrorCtor(`Release ${tag} has no assets in ${owner}/${repo}`);
-			assets = release.assets;
+			resolvedAssets = release.assets;
 		}
-		return assets;
+		return resolvedAssets;
 	}, require_releases_github_retry_config.GITHUB_RETRY_CONFIG);
 	if (!assets) {
 		if (nothrow) return;

package/dist/releases/github-downloads.d.ts

@@ -43,5 +43,5 @@ export declare function downloadGitHubRelease(config: DownloadGitHubReleaseConfi
  * @param options - Additional options.
  */
 export declare function downloadReleaseAsset(tag: string, assetPattern: string | AssetPattern, outputPath: string, repoConfig: RepoConfig, options?: {
-    quiet?: boolean;
+    quiet?: boolean | undefined;
 }): Promise<void>;

package/dist/releases/github-downloads.js

@@ -52,11 +52,11 @@ async function downloadGitHubRelease(config) {
 		if (!latestTag) throw new require_primordials_error.ErrorCtor(`No ${toolPrefix} release found in ${owner}/${repo}`);
 		tag = latestTag;
 	} else throw new require_primordials_error.ErrorCtor("Either toolPrefix or tag must be provided");
-	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const path = require_node_path.getNodePath();
 	const binaryDir = path.isAbsolute(downloadDir) ? downloadDir : path.join(cwd, downloadDir);
 	const binaryPath = path.join(binaryDir, binaryName);
 	const versionPath = path.join(binaryDir, ".version");
-	const fs = /* @__PURE__ */ require_node_fs.getNodeFs();
+	const fs = require_node_fs.getNodeFs();
 	if (fs.existsSync(versionPath) && fs.existsSync(binaryPath)) {
 		if ((await fs.promises.readFile(versionPath, "utf8")).trim() === tag && fs.existsSync(binaryPath)) {
 			if (!quiet) logger.info(`Using cached ${toolName} (${platformArch}): ${binaryPath}`);
@@ -109,7 +109,7 @@ async function downloadReleaseAsset(tag, assetPattern, outputPath, repoConfig, o
 		repo
 	});
 	if (!downloadUrl) throw new require_primordials_error.ErrorCtor(`Asset ${typeof assetPattern === "string" ? assetPattern : "matching pattern"} not found in release ${tag}`);
-	await require_fs_safe.safeMkdir((/* @__PURE__ */ require_node_path.getNodePath()).dirname(outputPath));
+	await require_fs_safe.safeMkdir(require_node_path.getNodePath().dirname(outputPath));
 	await require_http_request_download.httpDownload(downloadUrl, outputPath, {
 		logger: quiet ? void 0 : logger,
 		progressInterval: 10,

package/dist/releases/github-listing.d.ts

@@ -99,7 +99,16 @@ export declare function fetchReleasesViaRest(owner: string, repo: string): Promi
  *   false.
  */
 export declare function getLatestRelease(toolPrefix: string, repoConfig: RepoConfig, options?: {
-    assetPattern?: AssetPattern;
-    nothrow?: boolean;
+    assetPattern?: AssetPattern | undefined;
+    nothrow?: boolean | undefined;
 }): Promise<string | undefined>;
+/**
+ * Normalize an `httpRequest` response body to a parsed value. `body` may be a
+ * Buffer / string (older paths) OR — depending on the response's content-type
+ * handling — an already-parsed object/array. Calling `body.toString('utf8')` +
+ * JSON.parse on an already-parsed object yields `"[object Object]"` and throws
+ * (the "Failed to parse … releases response" build failure). Pass through
+ * non-string/Buffer bodies; parse the rest. Throws on genuine parse failure.
+ */
+export declare function parseResponseBody(body: unknown): unknown;
 export {};

package/dist/releases/github-listing.js

@@ -75,7 +75,7 @@ async function fetchReleasesViaGraphQL(owner, repo) {
 	if (!response.ok) throw new require_primordials_error.ErrorCtor(`Failed to fetch ${owner}/${repo} releases (GraphQL): ${response.status}`);
 	let parsed;
 	try {
-		parsed = require_primordials_json.JSONParse(response.body.toString("utf8"));
+		parsed = parseResponseBody(response.body);
 	} catch (cause) {
 		throw new require_primordials_error.ErrorCtor(`Failed to parse GitHub GraphQL response for ${owner}/${repo} releases`, { cause });
 	}
@@ -115,15 +115,15 @@ async function fetchReleasesViaGraphQL(owner, repo) {
 async function fetchReleasesViaRest(owner, repo) {
 	const response = await require_http_request_request.httpRequest(`https://api.github.com/repos/${owner}/${repo}/releases?per_page=100`, { headers: require_releases_github_auth.getAuthHeaders() });
 	if (!response.ok) throw new require_primordials_error.ErrorCtor(`Failed to fetch ${owner}/${repo} releases: ${response.status}`);
-	const text = response.body.toString("utf8");
-	if (text.length === 0) return [];
+	const body = response.body;
+	if (Buffer.isBuffer(body) && body.length === 0 || typeof body === "string" && body.length === 0) return [];
 	let parsed;
 	try {
-		parsed = require_primordials_json.JSONParse(text);
+		parsed = parseResponseBody(body);
 	} catch (cause) {
 		throw new require_primordials_error.ErrorCtor(`Failed to parse ${owner}/${repo} releases response`, { cause });
 	}
-	/* c8 ignore start */
+	/* c8 ignore start - non-array fallback only reachable via the GraphQL path's shape, not REST */
 	return require_primordials_array.ArrayIsArray(parsed) ? parsed : [];
 	/* c8 ignore stop */
 }
@@ -157,7 +157,7 @@ async function getLatestRelease(toolPrefix, repoConfig, options = {}) {
 	const { assetPattern, nothrow = false } = options;
 	const { owner, repo } = repoConfig;
 	const isMatch = assetPattern ? require_releases_github_assets.createAssetMatcher(assetPattern) : void 0;
-	return await /* @__PURE__ */ require_promises_retry.pRetry(async () => {
+	return await require_promises_retry.pRetry(async () => {
 		let releases = await fetchReleasesViaRest(owner, repo);
 		if (releases.length === 0) {
 			let graphqlReleases;
@@ -185,8 +185,21 @@ async function getLatestRelease(toolPrefix, repoConfig, options = {}) {
 		return matchingReleases[0].tag_name;
 	}, require_releases_github_retry_config.GITHUB_RETRY_CONFIG) ?? void 0;
 }
+/**
+* Normalize an `httpRequest` response body to a parsed value. `body` may be a
+* Buffer / string (older paths) OR — depending on the response's content-type
+* handling — an already-parsed object/array. Calling `body.toString('utf8')` +
+* JSON.parse on an already-parsed object yields `"[object Object]"` and throws
+* (the "Failed to parse … releases response" build failure). Pass through
+* non-string/Buffer bodies; parse the rest. Throws on genuine parse failure.
+*/
+function parseResponseBody(body) {
+	if (body !== null && typeof body === "object" && !Buffer.isBuffer(body)) return body;
+	return require_primordials_json.JSONParse(Buffer.isBuffer(body) ? body.toString("utf8") : typeof body === "string" ? body : String(body));
+}
 
 //#endregion
 exports.fetchReleasesViaGraphQL = fetchReleasesViaGraphQL;
 exports.fetchReleasesViaRest = fetchReleasesViaRest;
-exports.getLatestRelease = getLatestRelease;
+exports.getLatestRelease = getLatestRelease;
+exports.parseResponseBody = parseResponseBody;

package/dist/releases/github-retry-config.js

@@ -31,7 +31,7 @@ const DEFAULT_BASE_DELAY_MS = 5e3;
 * @returns The configured base delay in milliseconds.
 */
 function resolveBaseDelayMs() {
-	return /* @__PURE__ */ require_env_number.envAsNumber(require_env_rewire.getEnvValue("SOCKET_GITHUB_RETRY_BASE_DELAY_MS"), DEFAULT_BASE_DELAY_MS);
+	return require_env_number.envAsNumber(require_env_rewire.getEnvValue("SOCKET_GITHUB_RETRY_BASE_DELAY_MS"), DEFAULT_BASE_DELAY_MS);
 }
 const GITHUB_RETRY_CONFIG = require_primordials_object.ObjectFreeze({
 	__proto__: null,

package/dist/releases/github-types.d.ts

@@ -39,11 +39,11 @@ export interface DownloadGitHubReleaseConfig {
     /**
      * Working directory (defaults to process.cwd()).
      */
-    cwd?: string;
+    cwd?: string | undefined;
     /**
      * Download destination directory. @default 'build/downloaded'
      */
-    downloadDir?: string;
+    downloadDir?: string | undefined;
     /**
      * GitHub repository owner/organization.
      */
@@ -55,11 +55,11 @@ export interface DownloadGitHubReleaseConfig {
     /**
      * Suppress log messages. @default false.
      */
-    quiet?: boolean;
+    quiet?: boolean | undefined;
     /**
      * Remove macOS quarantine attribute after download. @default true.
      */
-    removeMacOSQuarantine?: boolean;
+    removeMacOSQuarantine?: boolean | undefined;
     /**
      * GitHub repository name.
      */
@@ -67,7 +67,7 @@ export interface DownloadGitHubReleaseConfig {
     /**
      * Specific release tag to download.
      */
-    tag?: string;
+    tag?: string | undefined;
     /**
      * Tool name for directory structure.
      */
@@ -75,7 +75,7 @@ export interface DownloadGitHubReleaseConfig {
     /**
      * Tool prefix for finding latest release.
      */
-    toolPrefix?: string;
+    toolPrefix?: string | undefined;
 }
 /**
  * Configuration for repository access.

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

@@ -0,0 +1,107 @@
+/**
+ * @file Socket-btm binary asset/platform-arch naming helpers.
+ */
+import type { Arch, Libc, Platform } from '../constants/platform';
+/**
+ * Get asset name for a socket-btm binary.
+ *
+ * @example
+ *   ;```typescript
+ *   getBinaryAssetName('lief', 'linux', 'x64', 'musl')
+ *   // 'lief-linux-x64-musl'
+ *   ```
+ *
+ * @param binaryBaseName - Binary basename (e.g., 'binject', 'node')
+ * @param platform - Target platform.
+ * @param arch - Target architecture.
+ * @param libc - Linux libc variant (optional)
+ *
+ * @returns Asset name (e.g., 'binject-darwin-arm64', 'node-linux-x64-musl')
+ */
+export declare function getBinaryAssetName(binaryBaseName: string, platform: Platform, arch: Arch, libc?: Libc | undefined): string;
+/**
+ * Get binary filename for output.
+ *
+ * @example
+ *   ;```typescript
+ *   getBinaryName('node', 'win32') // 'node.exe'
+ *   getBinaryName('node', 'linux') // 'node'
+ *   ```
+ *
+ * @param binaryBaseName - Binary basename (e.g., 'node', 'binject')
+ * @param platform - Target platform.
+ *
+ * @returns Binary filename (e.g., 'node', 'node.exe')
+ */
+export declare function getBinaryName(binaryBaseName: string, platform: Platform): string;
+/**
+ * Get platform-arch identifier for directory structure and asset names.
+ *
+ * # Format: `<os>-<arch>[-<libc>]`
+ *
+ * The OS segment is `process.platform` verbatim: `darwin` / `linux` / `win32`.
+ * The arch segment is `process.arch` verbatim: `x64` / `arm64`. The optional
+ * libc suffix is `-musl` (Linux only; the glibc default is unsuffixed to match
+ * Node.js's own linuxstatic convention).
+ *
+ * # Why these specific conventions
+ *
+ * ## Why `win32`, not `win`
+ *
+ * `win32` is what `process.platform` returns on every Windows host. Every npm
+ * package whose install-time platform filter uses the standard `os` / `cpu` /
+ * `libc` manifest fields must match `process.platform` strings exactly (npm
+ * compares them verbatim — there's no shorthand layer). Using `win` internally
+ * here would have forced a translation every time we constructed an install
+ * filter or a target triple, and reviewers would have to remember "we
+ * abbreviate on disk but not in package filters." Since the two now match,
+ * there's no translation step to get wrong.
+ *
+ * Pnpm's pack-app (v11+) accepts `<os>-<arch>[-<libc>]` target strings and its
+ * shards are `@pnpm/exe.<os>-<arch>` (with `win32`, not `win` — see
+ * pnpm#11314). Our naming matches so asset names we emit can flow directly into
+ * pack-app's `--target` arg, `pnpm.app.targets` config, and
+ * sibling-package-name construction without a translation map.
+ *
+ * ## Why `-musl` is the suffix (and glibc is unsuffixed)
+ *
+ * Node.js's own linuxstatic tarballs historically used the unqualified `linux`
+ * for glibc and a separate download channel for musl. The pnpm ecosystem
+ * codified that as `linux-<arch>` (glibc, default) and `linux-<arch>-musl` (the
+ * libc outlier), matching the asymmetric reality of Linux distros — glibc is
+ * the majority case, musl is Alpine-and-similar. Adding `-glibc` for the
+ * default would be redundant noise in the name.
+ *
+ * ## Why libc is only appended for Linux
+ *
+ * MacOS and Windows have exactly one system libc each (Apple libSystem,
+ * Microsoft UCRT). A hypothetical `darwin-arm64-libsystem` conveys no
+ * information. Node.js, npm, and pnpm all treat libc as a Linux-only axis; we
+ * follow the same convention so callers don't have to special- case
+ * `'darwin-arm64'.startsWith('darwin-arm64')` style matches.
+ *
+ * ## Why this function exists at all (vs. inlining)
+ *
+ * Two upstream APIs that socket-btm consumers end up calling — the npm manifest
+ * filter (`os`/`cpu`/`libc`) and pnpm's pack-app `--target` — both need the
+ * exact same triple format. Centralizing the construction here means a future
+ * schema change (e.g. Node introducing `riscv64`) gets one edit, and the error
+ * message for an unsupported platform is uniform across downloaders, pack-app
+ * invocations, and the `@socketbin/*` resolver logic.
+ *
+ * @example
+ *   ;```typescript
+ *   getPlatformArch('linux', 'x64', 'musl') // 'linux-x64-musl'
+ *   getPlatformArch('darwin', 'arm64') // 'darwin-arm64'
+ *   getPlatformArch('win32', 'x64') // 'win32-x64'
+ *   getPlatformArch('darwin', 'x64', 'musl') // 'darwin-x64' — libc ignored
+ *   ```
+ *
+ * @param platform - Target platform.
+ * @param arch - Target architecture.
+ * @param libc - Linux libc variant (optional; non-linux platforms ignore)
+ *
+ * @returns Platform-arch identifier (e.g., 'darwin-arm64', 'linux-x64-musl',
+ *   'win32-x64')
+ */
+export declare function getPlatformArch(platform: Platform, arch: Arch, libc?: Libc | undefined): string;