@socketsecurity/lib 6.0.6 → 6.0.7

package/CHANGELOG.md

@@ -5,11 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.0.7](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.7) - 2026-06-03
+
+### Added
+
+- **`external-tools/python` — zero-host-dependency Python.** `resolvePython` (PATH → python-build-standalone download), `downloadPipPackage` (bundle-safe `pip install --target`), `resolvePipPackagePin` (hash-pinned closure), and the `dlxPipInstall` / `dlxPipPin` one-call wrappers. Removes the unused `external-tools/uv`.
+- **`constants/platform` — `getOs`, `getLibc`, `getTarget`.** OS, libc (`glibc`/`musl`/`undefined`), and the pnpm `pack-app` host token `<os>-<arch>[-<libc>]`.
+- **`http-request` decompresses `gzip` / `br` response bodies.** Buffered requests advertise `Accept-Encoding: gzip, br` and now decode the body by its `Content-Encoding` before resolving. 6.0.6 sent the header but never decompressed, so a compressed response reached callers as raw deflated bytes. Streamed requests (`stream: true`, e.g. `httpDownload`) skip the header so piped-to-disk payloads stay raw and checksum cleanly. Callers can override with `'identity'`.
+- **`crypto/hash` blob content-address helpers.** `blobHashOf(bytes)` returns Socket's content-addressed blob hash (`Q` + base64url(sha256)), and `verifyBlobHash(hash, bytes)` throws when bytes don't hash to the expected address. Both build on the fast one-shot `hash()`; the `S` file-stream discriminator verifies against the same digest body. Lets blob consumers (the SDK, MCP server) verify integrity against one canonical implementation instead of re-deriving the scheme.
+- **`integrity` — unified checksum/integrity surface.** `checksumToIntegrity(hex, algorithm?)` and `integrityToChecksum(sri)` convert between the two named hash flavors and are idempotent on the destination format (pass an SRI to `checksumToIntegrity`, get it back unchanged). `isIntegrity(s)` and `isChecksum(s)` are the predicates. `parseIntegrity(s)` returns `{ algorithm, body }` for the SRI structure. Replaces the `src/ssri/` directory (`hexToSsri`, `ssriToHex`, `isValidHex`, `isValidSsri`, `parseSsri`) — SSRI is just another name for Subresource Integrity, so the duplication confused readers. `isIntegrity` now accepts the full W3C SRI set (`sha256` / `sha384` / `sha512`) — the previous predicate hardcoded `sha512` only, which mismatched the contract `external-tools/manifest.ts` already promised and rejected the fleet's `sha256-<base64>` integrity strings.
+- **`process/spawn/kill-tree` — cross-platform process-tree termination.** `killProcessTree(target, { detached?, signal? })` walks and signals the whole descendant tree of a `pid` or `ChildProcess`: POSIX uses `process.kill(-pid, signal)` against the detached child's process group; Windows shells out to `taskkill /T /F /pid <pid>`. `isProcessAlive(pid)` probes liveness with `process.kill(pid, 0)`. Both helpers are best-effort and never throw — `ESRCH` (process gone) or `EPERM` (not ours) returns `false` so cleanup kills can't mask the caller's control flow.
+
+### Changed
+
+- **dlx + pin API renamed (breaking).** `downloadPackage` → `downloadNpmPackage`, `generatePackagePin` → `resolveNpmPackagePin`, the `package` option → `spec`. `downloadNpmPackage` gains an optional `hash` for tarball integrity.
+- **`packages/operations` split by concern (breaking).** The grab-bag `@socketsecurity/lib/packages/operations` export is gone; its members move to focused subpaths: `readPackageJson`/`readPackageJsonSync` → `packages/read`, the fetcher + GitHub tarball resolver → `packages/fetch`, `extractPackage`/`packPackage` → `packages/tarball`, the dependency-metadata override lookup → `packages/metadata-extensions`, and the name/spec helpers → `packages/specs`. `findUpPackageJson` now lives at `packages/find` (the `packages/find-up` subpath is removed). The `fs/find-up` subpath is renamed `fs/find`, and `fs/path-cache` is renamed `fs/allowed-dirs-cache` (it caches the safe-delete allowed-directories set, not arbitrary paths).
+
+### Fixed
+
+- **Python downloads now work on Windows and Alpine.** python-build-standalone resolution previously returned no asset on `win32` and musl hosts; both now resolve.
+- **`debug` — namespace `SOCKET_DEBUG` values enable debug output.** `envAsBoolean(getSocketDebug())` returned false for `SOCKET_DEBUG=*` or `SOCKET_DEBUG=socket:foo` — those aren't boolean literals, so debug output was silently suppressed for the common namespace-selection shape. The new `isSocketDebugEnabled()` helper treats any non-empty value other than `0`/`false`/`no` (case-insensitive) as enabled.
+- **`external-tools/skillspector` pipx detection on Windows.** The PATH-tier resolver normalizes the resolved binary path with `normalizePath` and matches a forward-slash-only `pipx/venvs/` pattern, instead of `path.normalize` plus a dual-separator regex. On Windows the old form left backslashes in the path and missed pipx-installed binaries, tagging them `source: 'path'` rather than `source: 'pipx'`.
+
+### Removed
+
+- **`@socketsecurity/lib/ssri/{convert,parse,validate}` package exports.** Folded into `@socketsecurity/lib/integrity` (see Added). No fleet consumers were using the `ssri` subpath imports — verified by grep across socket-\* fleet repos.
+
 ## [6.0.6](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.6) - 2026-06-01
 
 ### Added
 
-- **`http-request` now negotiates and decompresses `gzip` / `br` response bodies.** Buffered requests advertise `Accept-Encoding: gzip, br` and transparently decompress responses by `Content-Encoding`. Node's HTTP client does neither, so a compressed Socket API response previously reached callers as raw deflated bytes. Streamed requests (`stream: true`, e.g. `httpDownload`) intentionally skip the `Accept-Encoding` header so piped-to-disk payloads stay raw and checksum cleanly. Callers can override (e.g. `'identity'`).
 - **`http-request/headers` — `basicAuthHeader(token)`.** Builds the Socket API Basic-auth shape (token-as-username, empty password) so call sites stop hand-rolling `Basic ${base64(token + ':')}`.
 - **`http-request` retry instrumentation.** Adds `Retry-Attempt`, `Retry-Max`, and `Retry-After` request headers on retried attempts so server-side logs can correlate a retry chain.
 - **`prim` CLI bin.** `prim` is now published as a `bin` entry (`dist/bin/prim.cjs`); installs from `@socketsecurity/lib` make `npx prim` work. Also new in this release: `prim --diff` for unified line-diffs in dry-run mode, multi-hop cycle detection in `validateRewrites`, and a two-phase apply with cross-batch validation.

package/dist/ai/discover.d.mts

@@ -28,8 +28,8 @@ export declare function cachePathFor(repoRoot: string): string;
  *   `'claude' in agents` for the existence check.
  */
 export declare function discoverAiAgents(options?: {
-    readonly refresh?: boolean;
-    readonly repoRoot?: string;
+    readonly refresh?: boolean | undefined;
+    readonly repoRoot?: string | undefined;
 }): Promise<DiscoveredAgents>;
 export declare function discoverFresh(): DiscoveredAgents;
 /**

package/dist/ai/discover.js

@@ -41,7 +41,7 @@ const KNOWN_AGENTS = [
 const CACHE_TTL_MS = 3600 * 1e3;
 let inProcessCache;
 function cachePathFor(repoRoot) {
-	return node_path.default.join(repoRoot, ".cache", "agent-discovery.json");
+	return node_path.default.join(repoRoot, "node_modules", ".cache", "agent-discovery.json");
 }
 /**
 * Discover which AI agent CLIs are installed.
@@ -73,7 +73,8 @@ async function discoverAiAgents(options = {}) {
 }
 function discoverFresh() {
 	const out = {};
-	for (const name of KNOWN_AGENTS) {
+	for (let i = 0, { length } = KNOWN_AGENTS; i < length; i += 1) {
+		const name = KNOWN_AGENTS[i];
 		const found = require_bin_which.whichSync(name);
 		if (typeof found === "string" && found) out[name] = found;
 	}

package/dist/ai/spawn.js

@@ -52,6 +52,7 @@ function buildArgs(agent, opts) {
 			];
 			for (const dir of opts.addDirs ?? []) args.push("--add-dir", dir);
 			if (opts.model) args.push("--model", opts.model);
+			if (opts.effort) args.push("--effort", opts.effort);
 			if (allAllowed.length > 0) args.push("--allowedTools", ...allAllowed);
 			if (opts.disallow.length > 0) args.push("--disallowedTools", ...opts.disallow);
 			if (opts.extraArgs) args.push(...opts.extraArgs);
@@ -159,7 +160,7 @@ async function spawnAiAgent(opts) {
 			stderr = String(result.stderr ?? "");
 			exitCode = result.code ?? 0;
 		} catch (e) {
-			if (/* @__PURE__ */ require_process_spawn_errors.isSpawnError(e)) {
+			if (require_process_spawn_errors.isSpawnError(e)) {
 				stdout = String(e.stdout ?? "");
 				stderr = String(e.stderr ?? "");
 				exitCode = e.code ?? 1;

package/dist/ai/types.d.mts

@@ -25,6 +25,13 @@ export type AiAgentName = 'claude' | 'codex' | 'gemini' | 'opencode';
  *   tools that mutate state.
  */
 export type PermissionMode = 'acceptEdits' | 'dontAsk' | 'plan';
+/**
+ * Reasoning-effort level for the agent session. Maps to the claude CLI
+ * `--effort <level>` flag (claude-specific; other agents ignore it). Pair a
+ * cheap model with low effort for mechanical work and reserve high/max for
+ * tasks that genuinely need deeper reasoning.
+ */
+export type AiEffort = 'high' | 'low' | 'max' | 'medium' | 'xhigh';
 /**
  * Result of an agent spawn. Consumers should inspect `exitCode` before using
  * `stdout` — non-zero usually means the agent's CLI itself rejected, not just
@@ -55,27 +62,32 @@ export interface SpawnAiAgentOptions {
     /**
      * Optional explicit agent. Defaults to claude when discovered.
      */
-    readonly agent?: AiAgentName;
+    readonly agent?: AiAgentName | undefined;
     /**
      * Allow-list extras (Bash glob patterns, MCP tools, etc.).
      */
-    readonly allow?: readonly string[];
+    readonly allow?: readonly string[] | undefined;
     /**
      * Extra dirs the agent can read (e.g. parent of cwd for monorepo).
      */
-    readonly addDirs?: readonly string[];
+    readonly addDirs?: readonly string[] | undefined;
     /**
      * Tool denylist — required to enforce the lockdown.
      */
     readonly disallow: readonly string[];
+    /**
+     * Reasoning-effort level (claude `--effort`); agent default if absent.
+     * claude-specific — other agents ignore it.
+     */
+    readonly effort?: AiEffort | undefined;
     /**
      * Override the agent's flag list (rare; for one-off advanced cases).
      */
-    readonly extraArgs?: readonly string[];
+    readonly extraArgs?: readonly string[] | undefined;
     /**
      * Model name override; agent default if absent.
      */
-    readonly model?: string;
+    readonly model?: string | undefined;
     /**
      * Permission mode — see PermissionMode docstring.
      */
@@ -91,7 +103,7 @@ export interface SpawnAiAgentOptions {
     /**
      * Per-call timeout (ms). Caller should set for predictable bounds.
      */
-    readonly timeoutMs?: number;
+    readonly timeoutMs?: number | undefined;
     /**
      * Tool allowlist. Required to enforce the lockdown.
      */

package/dist/ai/worktree.d.mts

@@ -22,23 +22,23 @@ export interface WorktreeRunOptions {
     /**
      * Branch to merge results into. Default: current branch of baseRepo.
      */
-    readonly branch?: string;
+    readonly branch?: string | undefined;
     /**
      * Cleanup policy. Default 'always'.
      */
-    readonly cleanup?: WorktreeCleanup;
+    readonly cleanup?: WorktreeCleanup | undefined;
     /**
      * Parallel cap. Default 4, max 8.
      */
-    readonly concurrency?: number;
+    readonly concurrency?: number | undefined;
     /**
      * Prefix for worktree branch + dir names. Default 'agent-task'.
      */
-    readonly namePrefix?: string;
+    readonly namePrefix?: string | undefined;
     /**
      * Where worktrees live on disk. Default: `${tmpdir}/${prefix}-<n>`.
      */
-    readonly worktreeRoot?: string;
+    readonly worktreeRoot?: string | undefined;
 }
 export interface WorktreeRunContext {
     /**
@@ -56,7 +56,7 @@ export interface WorktreeRunContext {
 }
 export interface WorktreeRunSettled<T> {
     readonly cleanup: 'removed' | 'kept';
-    readonly error?: unknown;
+    readonly error?: unknown | undefined;
     readonly merged: boolean;
     readonly status: 'fulfilled' | 'rejected';
     readonly value?: T | undefined;

package/dist/ai/worktree.js

@@ -161,7 +161,7 @@ function tryGit(cwd, ...args) {
 			output: git(cwd, ...args)
 		};
 	} catch (e) {
-		if (/* @__PURE__ */ require_process_spawn_errors.isSpawnError(e)) return {
+		if (require_process_spawn_errors.isSpawnError(e)) return {
 			ok: false,
 			output: String(e.stderr ?? e.stdout ?? "")
 		};

package/dist/ansi/strip.d.ts

@@ -19,7 +19,7 @@
  *   ```
  */
 export declare function ansiRegex(options?: {
-    onlyFirst?: boolean;
+    onlyFirst?: boolean | undefined;
 }): RegExp;
 /**
  * Strip ANSI escape codes from text. Uses the inlined ansi-regex for matching.

package/dist/ansi/strip.js

@@ -26,7 +26,6 @@ const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
 *   ansiRegex({ onlyFirst: true }) // matches only the first code
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function ansiRegex(options) {
 	const { onlyFirst } = options ?? {};
 	return new require_primordials_regexp.RegExpCtor(`(?:\\u001B\\][\\s\\S]*?(?:\\u0007|\\u001B\\u005C|\\u009C))|[\\u001B\\u009B][[\\]()#;?]*(?:\\d{1,4}(?:[;:]\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]`, onlyFirst ? void 0 : "g");
@@ -40,7 +39,6 @@ function ansiRegex(options) {
 *   stripAnsi('\u001b[1mBold\u001b[0m') // 'Bold'
 *   ```
 */
-/*@__NO_SIDE_EFFECTS__*/
 function stripAnsi(text) {
 	return require_primordials_string.StringPrototypeReplace(text, ANSI_REGEX, "");
 }

package/dist/archives/_internal.js

@@ -15,8 +15,8 @@ let node_fs = require("node:fs");
 const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024;
 const DEFAULT_MAX_TOTAL_SIZE = 1024 * 1024 * 1024;
 const DEFAULT_MAX_ENTRIES = 1e5;
-let _AdmZip;
-let _tarFs;
+let admZip;
+let tarFs;
 /**
 * Assert that an archive file exists on disk before handing it to the
 * underlying extractor. Normalizes the "missing archive" surface across all
@@ -38,15 +38,13 @@ function assertArchiveExists(archivePath) {
 		throw err;
 	}
 }
-/*@__NO_SIDE_EFFECTS__*/
 function getAdmZip() {
-	if (_AdmZip === void 0) _AdmZip = /*@__PURE__*/ require("../external/adm-zip.js");
-	return _AdmZip;
+	if (admZip === void 0) admZip = /*@__PURE__*/ require("../external/adm-zip.js");
+	return admZip;
 }
-/*@__NO_SIDE_EFFECTS__*/
 function getTarFs() {
-	if (_tarFs === void 0) _tarFs = /*@__PURE__*/ require("../external/tar-fs.js");
-	return _tarFs;
+	if (tarFs === void 0) tarFs = /*@__PURE__*/ require("../external/tar-fs.js");
+	return tarFs;
 }
 /**
 * Validate that a resolved path is within the target directory. Prevents path
@@ -61,7 +59,7 @@ function getTarFs() {
 * @throws Error if path is outside the base directory
 */
 function validatePathWithinBase(targetPath, baseDir, entryName) {
-	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const path = require_node_path.getNodePath();
 	const resolvedTarget = path.resolve(targetPath);
 	const resolvedBase = path.resolve(baseDir);
 	if (!require_primordials_string.StringPrototypeStartsWith(resolvedTarget, resolvedBase + path.sep) && resolvedTarget !== resolvedBase) throw new require_primordials_error.ErrorCtor(`Path traversal attempt detected: entry "${entryName}" would extract to "${resolvedTarget}" outside target directory "${resolvedBase}"`);

package/dist/archives/extract.js

@@ -31,7 +31,7 @@ const require_archives_zip = require('./zip.js');
 async function extractArchive(archivePath, outputDir, options = {}) {
 	const format = require_archives_detect.detectArchiveFormat(archivePath);
 	if (!format) {
-		const ext = (/* @__PURE__ */ require_node_path.getNodePath()).extname(archivePath).toLowerCase();
+		const ext = require_node_path.getNodePath().extname(archivePath).toLowerCase();
 		throw new require_primordials_error.ErrorCtor(`Unsupported archive format${ext ? ` (extension: ${ext})` : ""}: ${archivePath}. Supported formats: .zip, .tar, .tar.gz, .tgz`);
 	}
 	switch (format) {

package/dist/archives/tar.js

@@ -42,12 +42,12 @@ let node_zlib = require("node:zlib");
 async function extractTar(archivePath, outputDir, options = {}) {
 	require_archives__internal.assertArchiveExists(archivePath);
 	const { maxEntries = require_archives__internal.DEFAULT_MAX_ENTRIES, maxFileSize = require_archives__internal.DEFAULT_MAX_FILE_SIZE, maxTotalSize = require_archives__internal.DEFAULT_MAX_TOTAL_SIZE, strip = 0 } = options;
-	const normalizedOutputDir = /* @__PURE__ */ require_paths_normalize.normalizePath(outputDir);
+	const normalizedOutputDir = require_paths_normalize.normalizePath(outputDir);
 	await require_fs_safe.safeMkdir(normalizedOutputDir);
 	let totalExtractedSize = 0;
 	let entryCount = 0;
 	let destroyScheduled = false;
-	const extractStream = (/* @__PURE__ */ require_archives__internal.getTarFs()).extract(normalizedOutputDir, {
+	const extractStream = require_archives__internal.getTarFs().extract(normalizedOutputDir, {
 		map: (header) => {
 			/* c8 ignore start - destroyScheduled is set by the same map() when a
 			security limit trips; only fires after the schedule. */
@@ -73,7 +73,7 @@ async function extractTar(archivePath, outputDir, options = {}) {
 				});
 				return header;
 			}
-			if (header.type === "symlink" || header.type === "link") {
+			if (header.type === "link" || header.type === "symlink") {
 				destroyScheduled = true;
 				node_process.default.nextTick(() => {
 					extractStream.destroy(new require_primordials_error.ErrorCtor(`Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`));
@@ -127,12 +127,12 @@ async function extractTar(archivePath, outputDir, options = {}) {
 async function extractTarGz(archivePath, outputDir, options = {}) {
 	require_archives__internal.assertArchiveExists(archivePath);
 	const { maxEntries = require_archives__internal.DEFAULT_MAX_ENTRIES, maxFileSize = require_archives__internal.DEFAULT_MAX_FILE_SIZE, maxTotalSize = require_archives__internal.DEFAULT_MAX_TOTAL_SIZE, strip = 0 } = options;
-	const normalizedOutputDir = /* @__PURE__ */ require_paths_normalize.normalizePath(outputDir);
+	const normalizedOutputDir = require_paths_normalize.normalizePath(outputDir);
 	await require_fs_safe.safeMkdir(normalizedOutputDir);
 	let totalExtractedSize = 0;
 	let entryCount = 0;
 	let destroyScheduled = false;
-	const extractStream = (/* @__PURE__ */ require_archives__internal.getTarFs()).extract(normalizedOutputDir, {
+	const extractStream = require_archives__internal.getTarFs().extract(normalizedOutputDir, {
 		map: (header) => {
 			/* c8 ignore start - destroyScheduled is set by the same map() when a
 			security limit trips; only fires after the schedule. */
@@ -158,7 +158,7 @@ async function extractTarGz(archivePath, outputDir, options = {}) {
 				});
 				return header;
 			}
-			if (header.type === "symlink" || header.type === "link") {
+			if (header.type === "link" || header.type === "symlink") {
 				destroyScheduled = true;
 				node_process.default.nextTick(() => {
 					extractStream.destroy(new require_primordials_error.ErrorCtor(`Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`));

package/dist/archives/zip.js

@@ -32,10 +32,10 @@ const require_fs_safe = require('../fs/safe.js');
 async function extractZip(archivePath, outputDir, options = {}) {
 	require_archives__internal.assertArchiveExists(archivePath);
 	const { maxEntries = require_archives__internal.DEFAULT_MAX_ENTRIES, maxFileSize = require_archives__internal.DEFAULT_MAX_FILE_SIZE, maxTotalSize = require_archives__internal.DEFAULT_MAX_TOTAL_SIZE, strip = 0 } = options;
-	const normalizedOutputDir = /* @__PURE__ */ require_paths_normalize.normalizePath(outputDir);
+	const normalizedOutputDir = require_paths_normalize.normalizePath(outputDir);
 	await require_fs_safe.safeMkdir(normalizedOutputDir);
-	const zip = new (/* @__PURE__ */ require_archives__internal.getAdmZip())(archivePath);
-	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const zip = new (require_archives__internal.getAdmZip())(archivePath);
+	const path = require_node_path.getNodePath();
 	const entries = zip.getEntries();
 	/* c8 ignore start */
 	if (entries.length > maxEntries) throw new require_primordials_error.ErrorCtor(`Archive has too many entries: ${entries.length} (limit: ${maxEntries})`);
@@ -60,8 +60,6 @@ async function extractZip(archivePath, outputDir, options = {}) {
 		for (const entry of entries) if (!entry.isDirectory) require_archives__internal.validatePathWithinBase(path.join(normalizedOutputDir, entry.entryName), normalizedOutputDir, entry.entryName);
 		zip.extractAllTo(normalizedOutputDir, true);
 	} else {
-		const path = /* @__PURE__ */ require_node_path.getNodePath();
-		const entries = zip.getEntries();
 		const dirsToCreate = new require_primordials_map_set.SetCtor();
 		for (const entry of entries) {
 			if (entry.isDirectory) continue;

package/dist/argv/flag-predicates.d.ts

@@ -11,6 +11,18 @@
  *      accepts both `--quiet` and `--silent`).
  */
 import type { FlagInput } from './flag-types';
+/**
+ * Get the appropriate log level based on flags. Returns 'silent', 'error',
+ * 'warn', 'info', 'verbose', or 'debug'.
+ *
+ * @example
+ *   ;```typescript
+ *   getLogLevel() // 'info' (default)
+ *   getLogLevel({ quiet: true }) // 'silent'
+ *   getLogLevel(['--debug']) // 'debug'
+ *   ```
+ */
+export declare function getLogLevel(input?: FlagInput): string;
 /**
  * Build a flag predicate that accepts `FlagValues`, `string[]`, or `undefined`
  * (in which case it consults the frozen `processArg`).
@@ -165,15 +177,3 @@ export declare const isVerbose: (input?: FlagInput) => boolean;
  *   ```
  */
 export declare const isWatch: (input?: FlagInput) => boolean;
-/**
- * Get the appropriate log level based on flags. Returns 'silent', 'error',
- * 'warn', 'info', 'verbose', or 'debug'.
- *
- * @example
- *   ;```typescript
- *   getLogLevel() // 'info' (default)
- *   getLogLevel({ quiet: true }) // 'silent'
- *   getLogLevel(['--debug']) // 'debug'
- *   ```
- */
-export declare function getLogLevel(input?: FlagInput): string;

package/dist/argv/flag-predicates.js

@@ -21,6 +21,23 @@ node_process = require_runtime.__toESM(node_process);
 */
 const processArg = [...node_process.default.argv];
 /**
+* Get the appropriate log level based on flags. Returns 'silent', 'error',
+* 'warn', 'info', 'verbose', or 'debug'.
+*
+* @example
+*   ;```typescript
+*   getLogLevel() // 'info' (default)
+*   getLogLevel({ quiet: true }) // 'silent'
+*   getLogLevel(['--debug']) // 'debug'
+*   ```
+*/
+function getLogLevel(input) {
+	if (isQuiet(input)) return "silent";
+	if (isDebug(input)) return "debug";
+	if (isVerbose(input)) return "verbose";
+	return "info";
+}
+/**
 * Build a flag predicate that accepts `FlagValues`, `string[]`, or `undefined`
 * (in which case it consults the frozen `processArg`).
 *
@@ -183,23 +200,6 @@ const isVerbose = makeFlagPredicate(["--verbose"]);
 *   ```
 */
 const isWatch = makeFlagPredicate(["--watch"], ["-w"]);
-/**
-* Get the appropriate log level based on flags. Returns 'silent', 'error',
-* 'warn', 'info', 'verbose', or 'debug'.
-*
-* @example
-*   ;```typescript
-*   getLogLevel() // 'info' (default)
-*   getLogLevel({ quiet: true }) // 'silent'
-*   getLogLevel(['--debug']) // 'debug'
-*   ```
-*/
-function getLogLevel(input) {
-	if (isQuiet(input)) return "silent";
-	if (isDebug(input)) return "debug";
-	if (isVerbose(input)) return "verbose";
-	return "info";
-}
 
 //#endregion
 exports.getLogLevel = getLogLevel;

package/dist/argv/flag-types.d.ts

@@ -8,22 +8,22 @@
  */
 export interface FlagValues {
     [key: string]: unknown;
-    quiet?: boolean;
-    silent?: boolean;
-    verbose?: boolean;
-    help?: boolean;
-    all?: boolean;
-    fix?: boolean;
-    force?: boolean;
-    'dry-run'?: boolean;
-    json?: boolean;
-    debug?: boolean;
-    watch?: boolean;
-    coverage?: boolean;
-    cover?: boolean;
-    update?: boolean;
-    staged?: boolean;
-    changed?: boolean;
+    quiet?: boolean | undefined;
+    silent?: boolean | undefined;
+    verbose?: boolean | undefined;
+    help?: boolean | undefined;
+    all?: boolean | undefined;
+    fix?: boolean | undefined;
+    force?: boolean | undefined;
+    'dry-run'?: boolean | undefined;
+    json?: boolean | undefined;
+    debug?: boolean | undefined;
+    watch?: boolean | undefined;
+    coverage?: boolean | undefined;
+    cover?: boolean | undefined;
+    update?: boolean | undefined;
+    staged?: boolean | undefined;
+    changed?: boolean | undefined;
 }
 /**
  * Accepted input types for flag checking functions. Can be parsed flag values,
@@ -45,12 +45,12 @@ export declare const COMMON_FLAGS: {
         default: boolean;
         description: string;
     };
-    coverage: {
+    cover: {
         type: 'boolean';
         default: boolean;
         description: string;
     };
-    cover: {
+    coverage: {
         type: 'boolean';
         default: boolean;
         description: string;

package/dist/argv/flag-types.js

@@ -18,15 +18,15 @@ const COMMON_FLAGS = {
 		default: false,
 		description: "Target changed files"
 	},
-	coverage: {
+	cover: {
 		type: "boolean",
 		default: false,
-		description: "Run with coverage"
+		description: "Run with coverage (alias)"
 	},
-	cover: {
+	coverage: {
 		type: "boolean",
 		default: false,
-		description: "Run with coverage (alias)"
+		description: "Run with coverage"
 	},
 	debug: {
 		type: "boolean",

package/dist/argv/parse.d.ts

@@ -8,7 +8,7 @@
  */
 interface YargsArguments extends Record<string, unknown> {
     _: string[];
-    $0?: string;
+    $0?: string | undefined;
 }
 /**
  * Options for configuring argument parsing, similar to Node.js util.parseArgs.

package/dist/arrays/_internal.js

@@ -1,6 +1,7 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_intl = require('../primordials/intl.js');
 
 //#region src/arrays/_internal.ts
 /**
@@ -8,8 +9,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 *   instances for conjunction (and) and disjunction (or) joins. Constructed
 *   lazily because `new Intl.ListFormat(...)` is a measurable startup cost.
 */
-let _conjunctionFormatter;
-let _disjunctionFormatter;
+let conjunctionFormatter;
+let disjunctionFormatter;
 /**
 * Get a cached Intl.ListFormat instance for conjunction (and) formatting.
 *
@@ -28,15 +29,14 @@ let _disjunctionFormatter;
 * @returns Cached Intl.ListFormat instance configured for conjunction
 *   formatting.
 */
-/*@__NO_SIDE_EFFECTS__*/
 function getConjunctionFormatter() {
-	if (_conjunctionFormatter === void 0)
- /* c8 ignore start */
-	_conjunctionFormatter = new Intl.ListFormat("en", {
+	if (conjunctionFormatter === void 0)
+ /* c8 ignore start - lazy singleton init runs once; not worth a dedicated test */
+	conjunctionFormatter = new require_primordials_intl.IntlListFormat("en", {
 		style: "long",
 		type: "conjunction"
 	});
-	return _conjunctionFormatter;
+	return conjunctionFormatter;
 }
 /**
 * Get a cached Intl.ListFormat instance for disjunction (or) formatting.
@@ -56,15 +56,14 @@ function getConjunctionFormatter() {
 * @returns Cached Intl.ListFormat instance configured for disjunction
 *   formatting.
 */
-/*@__NO_SIDE_EFFECTS__*/
 function getDisjunctionFormatter() {
-	if (_disjunctionFormatter === void 0)
- /* c8 ignore start */
-	_disjunctionFormatter = new Intl.ListFormat("en", {
+	if (disjunctionFormatter === void 0)
+ /* c8 ignore start - lazy singleton init runs once; not worth a dedicated test */
+	disjunctionFormatter = new require_primordials_intl.IntlListFormat("en", {
 		style: "long",
 		type: "disjunction"
 	});
-	return _disjunctionFormatter;
+	return disjunctionFormatter;
 }
 
 //#endregion

package/dist/arrays/chunk.js

@@ -40,7 +40,6 @@ const require_primordials_error = require('../primordials/error.js');
 *
 * @throws {Error} If chunk size is less than or equal to 0
 */
-/*@__NO_SIDE_EFFECTS__*/
 function arrayChunk(arr, size) {
 	const chunkSize = size ?? 2;
 	if (chunkSize <= 0) throw new require_primordials_error.ErrorCtor("Chunk size must be greater than 0");

package/dist/arrays/join.d.ts

@@ -1,13 +1,17 @@
 /**
  * @file Grammatical list joiners via `Intl.ListFormat` — Oxford-comma aware and
- *   locale-correct. `joinAnd` ("a, b, and c"), `joinOr` ("a, b, or c").
+ *   locale-correct. `joinList` (generalized), `joinAnd` ("a, b, and c"),
+ *   `joinOr` ("a, b, or c").
  */
+export interface JoinListOptions {
+    with?: string | undefined;
+}
 /**
  * Join array elements with proper "and" conjunction formatting.
  *
  * Formats an array of strings into a grammatically correct list using "and" as
  * the conjunction. Uses `Intl.ListFormat` for proper English formatting with
- * Oxford comma support.
+ * Oxford comma support. Delegates to `joinList`.
  *
  * @example
  *   ```ts
@@ -38,12 +42,42 @@
  * @returns Formatted string with proper "and" conjunction
  */
 export declare function joinAnd(arr: string[] | readonly string[]): string;
+/**
+ * Generalized list joiner covering bare join, comma-list, and
+ * conjunction/disjunction via `Intl.ListFormat`.
+ *
+ * - No options: bare concatenation (`'abc'`)
+ * - `{ with: 'and' }`: Oxford-comma "and" list via `Intl.ListFormat` (`'a, b, and
+ *   c'`)
+ * - `{ with: 'or' }`: Oxford-comma "or" list via `Intl.ListFormat` (`'a, b, or
+ *   c'`)
+ * - `{ with: <any other string> }`: `items.join(sep)` — e.g. `','` → `'a,b,c'`,
+ *   `', '` → `'a, b, c'`, `' '` → `'a b c'`
+ *
+ * Each item is coerced via `String()` before formatting.
+ *
+ * @example
+ *   ;```ts
+ *   joinList(['a', 'b', 'c'])                  // 'abc'
+ *   joinList(['a', 'b', 'c'], { with: ', ' })  // 'a, b, c'
+ *   joinList(['a', 'b', 'c'], { with: ' ' })   // 'a b c'
+ *   joinList(['a', 'b', 'c'], { with: 'and' }) // 'a, b, and c'
+ *   joinList(['a', 'b', 'c'], { with: 'or' })  // 'a, b, or c'
+ *   joinList([1, 2, 3], { with: 'and' })        // '1, 2, and 3'
+ *   ```
+ *
+ * @param items - Items to join (can be readonly, any type)
+ * @param options - Formatting options (optional)
+ *
+ * @returns Formatted string
+ */
+export declare function joinList(items: readonly unknown[], options?: JoinListOptions): string;
 /**
  * Join array elements with proper "or" disjunction formatting.
  *
  * Formats an array of strings into a grammatically correct list using "or" as
  * the disjunction. Uses `Intl.ListFormat` for proper English formatting with
- * Oxford comma support.
+ * Oxford comma support. Delegates to `joinList`.
  *
  * @example
  *   ```ts