@socketsecurity/lib 5.18.1 → 5.19.0

package/CHANGELOG.md

@@ -5,6 +5,55 @@ 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).
 
+## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
+
+### Added — dlx/integrity (new module)
+
+- `HashSpec`, `NormalizedHash`, `ComputedHashes` types. `HashSpec` accepts a bare string (sha512 SRI or sha256 hex, sniffed) or an explicit `{ type, value }` object
+- `normalizeHash()`, `computeHashes()`, `verifyHash()` — `verifyHash` uses `crypto.timingSafeEqual` for constant-time comparison
+- `DlxHashMismatchError` — carries `expected` + `actual` for diagnostics
+
+### Added — dlx/arborist (new module)
+
+- `safeIdealTree()`, `safeReify()` — hardened `@npmcli/arborist` wrappers mirroring socket-cli v1.1.79 `SafeArborist` overrides (`audit: false`, `fund: false`, `ignoreScripts: true`, `progress: false`, `saveBundle: false`, `silent: true`)
+- `writeSafeNpmrc()` — defense-in-depth `.npmrc` writer matching the Arborist overrides
+- Optional `before?: Date` on `safeIdealTree` for release-age enforcement during resolution
+
+### Added — dlx/lockfile (new module)
+
+- `generatePackagePin({ package, minReleaseDays?, minReleaseMins? })` — returns `PinDetails { name, version, hash: ComputedHashes, packageJson, lockfile }`. Runs Arborist in `packageLockOnly: true` mode against a tmp directory and auto-cleans
+- **Default `minReleaseDays: 7`** — resolution refuses to select versions published in the last week. Pass `0` to disable. `minReleaseMins` is a pnpm-style alias (mutually exclusive with `minReleaseDays`)
+- `LockfileSpec` type — export for use as the new `lockfile` option on `downloadPackage`
+
+### Added — dlx existing modules
+
+- `DlxPackageOptions.hash?: HashSpec` and `DlxPackageOptions.lockfile?: LockfileSpec` — passing a lockfile materializes it into the install dir (path → `fs.copyFileSync`, content → `fs.writeFileSync`) and drops a hardened `.npmrc` alongside before Arborist runs
+- `DlxBinaryOptions.hash?: HashSpec` — ergonomic alternative to the lower-level `integrity` and `sha256` fields (both still accepted)
+
+### Fixed — external
+
+- `pacote` shim now exposes `tarball`, `manifest`, `packument` alongside `extract`. **Fixes a latent runtime crash** in `src/packages/manifest.ts` callers (`fetchPackageManifest` / `fetchPackagePackument` called `.manifest(...)` / `.packument(...)` on a shim that previously only had `extract`, raising `TypeError: not a function`)
+
+### Changed — build (bundle size)
+
+- `dist/external/npm-pack.js`: 2,526,598 → 1,755,460 bytes (−771 KB, −30.5%). New `STUB_MAP` entries for code paths our callers never reach:
+  - `@sigstore/{bundle,core,protobuf-specs,sign,tuf,verify}`, `sigstore`, `tuf-js`, `@tufjs/{canonical-json,models}` — Sigstore attestation, only reached via `arb.audit()`
+  - `@npmcli/metavuln-calculator` — audit-only
+  - `@npmcli/query`, `postcss-selector-parser` — `arb.query()` unused
+  - `@npmcli/run-script`, `@npmcli/node-gyp` — guarded out by `ignoreScripts: true`
+  - `@npmcli/git`, `pacote/lib/{git,file,dir,remote}.js` — registry specs only
+  - arborist `audit-report.js`, `yarn-lock.js`, `isolated-reifier.js`, `query-selector-all.js`, `printable.js` — each gated or unused
+  - `cacache/lib/verify.js` — `cacache.verify` (npm cache verify) unused
+  - `proggy` — progress tracker, gated by `progress: false`
+  - `debug/src/browser.js` — Node-only bundle
+- `dist/external/zod.js`: 597,238 → 291,430 bytes (−306 KB, −51.2%). Stubbed `zod/v4/{core,classic,mini}`'s eager `locales/index.cjs` barrel (40+ translation modules). Opt-in via `z.config(z.locales.xx())` is never called by us
+
+## [5.18.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.2) - 2026-04-14
+
+### Removed
+
+- Remove unused `plugins/` directory and `./plugins/babel-plugin-inline-require-calls` export — no downstream consumers; socket-cli maintains its own local copies
+
 ## [5.18.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.1) - 2026-04-14
 
 ### Changed — build

package/README.md

@@ -45,6 +45,7 @@ logger.success(`Package: ${pkg.name}@${pkg.version}`)
 
 ## Documentation
 
+- [API Index](./docs/api-index.md) - Every subpath export with a one-line description (start here)
 - [Getting Started](./docs/getting-started.md) - Prerequisites, installation, and first examples
 - [Visual Effects](./docs/visual-effects.md) - Spinners, loggers, themes, and progress indicators
 - [File System](./docs/file-system.md) - File operations, globs, paths, and safe deletion
@@ -96,8 +97,8 @@ Spawn child processes safely with cross-platform support.
 - `spawnSync()` - Synchronous version for blocking operations
 - Array-based arguments prevent command injection
 - Automatic Windows `.cmd`/`.bat` handling
-- `ProcessLock` - Ensure only one instance runs at a time
-- `setupIPC()` - Inter-process communication
+- `processLock.withLock()` / `processLock.acquire()` / `processLock.release()` - Ensure only one instance runs at a time
+- `writeIpcStub()` / `getIpcStubPath()` - Filesystem-based inter-process data handoff
 
 ### Environment Detection
 
@@ -106,14 +107,14 @@ Type-safe environment variable access and platform detection.
 - `getCI()` - Detect CI environment
 - `getNodeEnv()` - Get NODE_ENV value
 - `isTest()` - Check if running tests
-- `getHome()` - Home directory (Unix/Linux/macOS)
+- `getHome()` - Home directory (cross-platform, with Windows `USERPROFILE` fallback)
 - Test rewiring with `setEnv()`, `resetEnv()`
 
 ### Package Management
 
 Detect and work with npm, pnpm, and yarn.
 
-- `detectPackageManager()` - Identify package manager from lock files
+- `detectPackageManager()` - Identify running package manager from `npm_config_user_agent` / binary path
 - Package manifest operations
 - Lock file management
 
@@ -141,7 +142,7 @@ Helpers for arrays, objects, strings, promises, sorting, and more.
 - **Cross-platform** - Works on Windows, macOS, and Linux
 - **TypeScript-first** - Full type safety with .d.ts files
 - **Zero dependencies** (for core HTTP - uses Node.js native modules)
-- **Well-tested** - 6600+ tests across 145 test files
+- **Well-tested** - 6000+ tests across 139+ test files
 - **Security-focused** - Safe defaults, command injection protection
 - **CommonJS output** - Compatible with Node.js tooling
 

package/dist/abort.d.ts

@@ -15,6 +15,9 @@ export declare function createCompositeAbortSignal(...signals: Array<AbortSignal
 /**
  * Create an AbortSignal that triggers after a timeout.
  *
+ * @throws {TypeError} If `ms` is not a number, is NaN, is not finite, or is not
+ *   positive.
+ *
  * @example
  * ```typescript
  * const signal = createTimeoutSignal(5000) // aborts after 5 seconds

package/dist/abort.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/agent.d.ts

@@ -1,4 +1,34 @@
+/**
+ * @fileoverview Package manager agent for executing npm, pnpm, and yarn commands.
+ * Provides cross-platform utilities with optimized flags and security defaults.
+ *
+ * SECURITY: Array-Based Arguments Prevent Command Injection
+ *
+ * All functions in this module (execNpm, execPnpm, execYarn) use array-based
+ * arguments when calling spawn(). This is the PRIMARY DEFENSE against command
+ * injection attacks.
+ *
+ * When arguments are passed as an array:
+ *   spawn(cmd, ['install', packageName, '--flag'], options)
+ *
+ * Node.js handles escaping automatically. Each argument is passed directly to
+ * the OS without shell interpretation. Shell metacharacters like ; | & $ ( )
+ * are treated as LITERAL STRINGS, not as commands.
+ *
+ * Example: If packageName = "lodash; rm -rf /", the package manager will try to
+ * install a package literally named "lodash; rm -rf /" (which doesn't exist),
+ * rather than executing the malicious command.
+ *
+ * This approach is secure even when shell: true is used on Windows for .cmd
+ * file resolution, because Node.js properly escapes each array element.
+ */
 import type { SpawnOptions } from './spawn';
+export interface PnpmOptions extends SpawnOptions {
+    allowLockfileUpdate?: boolean;
+}
+export interface ExecScriptOptions extends SpawnOptions {
+    prepost?: boolean | undefined;
+}
 /**
  * Execute npm commands with optimized flags and settings.
  *
@@ -12,9 +42,6 @@ import type { SpawnOptions } from './spawn';
  * ```
  */
 export declare function execNpm(args: string[], options?: SpawnOptions | undefined): import("./spawn").PromiseSpawnResult;
-export interface PnpmOptions extends SpawnOptions {
-    allowLockfileUpdate?: boolean;
-}
 /**
  * Execute pnpm commands with optimized flags and settings.
  *
@@ -31,9 +58,28 @@ export declare function execPnpm(args: string[], options?: PnpmOptions | undefin
     cmd: string;
     args: string[] | readonly string[];
     code: number;
-    signal: NodeJS.Signals;
-    stdout: string | Buffer<ArrayBufferLike>;
-    stderr: string | Buffer<ArrayBufferLike>;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+}>;
+/**
+ * Execute a package.json script using the detected package manager.
+ * Picks pnpm, npm, or yarn by walking up to the nearest lockfile; falls back
+ * to running `node --run` or `npm run` directly when no lockfile is found.
+ * Honors `shell: true` by passing through to `spawn()` unchanged.
+ *
+ * @param scriptName - The package.json script to run
+ * @param args - Either the script arguments or an options object
+ * @param options - Spawn options plus `prepost` to force npm-style pre/post scripts
+ * @returns The spawned `ChildProcess`-like promise from the underlying runner.
+ */
+export declare function execScript(scriptName: string, args?: string[] | readonly string[] | ExecScriptOptions | undefined, options?: ExecScriptOptions | undefined): Promise<{
+    cmd: string;
+    args: string[] | readonly string[];
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
 }>;
 /**
  * Execute yarn commands with optimized flags and settings.
@@ -51,9 +97,9 @@ export declare function execYarn(args: string[], options?: import('./spawn').Spa
     cmd: string;
     args: string[] | readonly string[];
     code: number;
-    signal: NodeJS.Signals;
-    stdout: string | Buffer<ArrayBufferLike>;
-    stderr: string | Buffer<ArrayBufferLike>;
+    signal: NodeJS.Signals | null;
+    stdout: string | Buffer;
+    stderr: string | Buffer;
 }>;
 /**
  * Check if a command argument is an npm audit flag.
@@ -65,7 +111,6 @@ export declare function execYarn(args: string[], options?: import('./spawn').Spa
  * isNpmAuditFlag('--save')      // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmAuditFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm fund flag.
@@ -77,7 +122,6 @@ export declare function isNpmAuditFlag(cmdArg: string): boolean;
  * isNpmFundFlag('--save')     // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmFundFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm loglevel flag.
@@ -90,7 +134,6 @@ export declare function isNpmFundFlag(cmdArg: string): boolean;
  * isNpmLoglevelFlag('--save')      // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmLoglevelFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm node-options flag.
@@ -102,7 +145,6 @@ export declare function isNpmLoglevelFlag(cmdArg: string): boolean;
  * isNpmNodeOptionsFlag('--save')                                   // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmNodeOptionsFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is an npm progress flag.
@@ -114,32 +156,29 @@ export declare function isNpmNodeOptionsFlag(cmdArg: string): boolean;
  * isNpmProgressFlag('--save')         // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isNpmProgressFlag(cmdArg: string): boolean;
 /**
- * Check if a command argument is a pnpm ignore-scripts flag.
+ * Check if a command argument is a pnpm frozen-lockfile flag.
  *
  * @example
  * ```typescript
- * isPnpmIgnoreScriptsFlag('--ignore-scripts')     // true
- * isPnpmIgnoreScriptsFlag('--no-ignore-scripts')  // true
- * isPnpmIgnoreScriptsFlag('--save')               // false
+ * isPnpmFrozenLockfileFlag('--frozen-lockfile')     // true
+ * isPnpmFrozenLockfileFlag('--no-frozen-lockfile')  // true
+ * isPnpmFrozenLockfileFlag('--save')                // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean;
+export declare function isPnpmFrozenLockfileFlag(cmdArg: string): boolean;
 /**
- * Check if a command argument is a pnpm frozen-lockfile flag.
+ * Check if a command argument is a pnpm ignore-scripts flag.
  *
  * @example
  * ```typescript
- * isPnpmFrozenLockfileFlag('--frozen-lockfile')     // true
- * isPnpmFrozenLockfileFlag('--no-frozen-lockfile')  // true
- * isPnpmFrozenLockfileFlag('--save')                // false
+ * isPnpmIgnoreScriptsFlag('--ignore-scripts')     // true
+ * isPnpmIgnoreScriptsFlag('--no-ignore-scripts')  // true
+ * isPnpmIgnoreScriptsFlag('--save')               // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function isPnpmFrozenLockfileFlag(cmdArg: string): boolean;
+export declare function isPnpmIgnoreScriptsFlag(cmdArg: string): boolean;
 /**
  * Check if a command argument is a pnpm install command.
  *
@@ -150,30 +189,8 @@ export declare function isPnpmFrozenLockfileFlag(cmdArg: string): boolean;
  * isPnpmInstallCommand('run')      // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isPnpmInstallCommand(cmdArg: string): boolean;
 /**
- * Alias for isNpmLoglevelFlag for pnpm usage.
+ * Alias for isNpmLoglevelFlag — pnpm uses the same `--loglevel` surface.
  */
 export declare const isPnpmLoglevelFlag: typeof isNpmLoglevelFlag;
-/**
- * Execute a package.json script using the appropriate package manager.
- * Automatically detects pnpm, yarn, or npm based on lockfiles.
- *
- * @example
- * ```typescript
- * await execScript('build')
- * await execScript('test', ['--coverage'], { cwd: '/tmp/project' })
- * ```
- */
-export interface ExecScriptOptions extends SpawnOptions {
-    prepost?: boolean | undefined;
-}
-export declare function execScript(scriptName: string, args?: string[] | readonly string[] | ExecScriptOptions | undefined, options?: ExecScriptOptions | undefined): Promise<{
-    cmd: string;
-    args: string[] | readonly string[];
-    code: number;
-    signal: NodeJS.Signals;
-    stdout: string | Buffer<ArrayBufferLike>;
-    stderr: string | Buffer<ArrayBufferLike>;
-}>;

package/dist/agent.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -45,12 +46,12 @@ __export(agent_exports, {
 });
 module.exports = __toCommonJS(agent_exports);
 var import_node_process = __toESM(require("node:process"));
+var import_bin = require("./bin");
 var import_agents = require("./constants/agents");
 var import_node = require("./constants/node");
 var import_platform = require("./constants/platform");
-var import_ci = require("./env/ci");
-var import_bin = require("./bin");
 var import_debug = require("./debug");
+var import_ci = require("./env/ci");
 var import_fs = require("./fs");
 var import_objects = require("./objects");
 var import_spawn = require("./spawn");
@@ -158,6 +159,50 @@ function execPnpm(args, options) {
     extBinOpts
   );
 }
+function execScript(scriptName, args, options) {
+  let resolvedOptions;
+  let resolvedArgs;
+  if (!Array.isArray(args) && args !== null && typeof args === "object") {
+    resolvedOptions = args;
+    resolvedArgs = [];
+  } else {
+    resolvedOptions = options;
+    resolvedArgs = args || [];
+  }
+  const { prepost, ...spawnOptions } = {
+    __proto__: null,
+    ...resolvedOptions
+  };
+  if (spawnOptions.shell === true) {
+    return (0, import_spawn.spawn)(scriptName, resolvedArgs, spawnOptions);
+  }
+  const useNodeRun = !prepost && (0, import_node.supportsNodeRun)();
+  const cwd = (0, import_objects.getOwn)(spawnOptions, "cwd") ?? import_node_process.default.cwd();
+  const pnpmLockPath = (0, import_fs.findUpSync)(import_agents.PNPM_LOCK_YAML, { cwd });
+  if (pnpmLockPath) {
+    return execPnpm(["run", scriptName, ...resolvedArgs], spawnOptions);
+  }
+  const packageLockPath = (0, import_fs.findUpSync)(import_agents.PACKAGE_LOCK_JSON, { cwd });
+  if (packageLockPath) {
+    return execNpm(["run", scriptName, ...resolvedArgs], spawnOptions);
+  }
+  const yarnLockPath = (0, import_fs.findUpSync)(import_agents.YARN_LOCK, { cwd });
+  if (yarnLockPath) {
+    return execYarn(["run", scriptName, ...resolvedArgs], spawnOptions);
+  }
+  return (0, import_spawn.spawn)(
+    (0, import_node.getExecPath)(),
+    [
+      ...(0, import_node.getNodeNoWarningsFlags)(),
+      ...useNodeRun ? ["--run"] : [import_agents.NPM_REAL_EXEC_PATH, "run"],
+      scriptName,
+      ...resolvedArgs
+    ],
+    {
+      ...spawnOptions
+    }
+  );
+}
 function execYarn(args, options) {
   const useDebug = (0, import_debug.isDebug)();
   const terminatorPos = args.indexOf("--");
@@ -211,62 +256,18 @@ function isNpmProgressFlag(cmdArg) {
   return /^--(no-)?progress(=.*)?$/.test(cmdArg);
 }
 // @__NO_SIDE_EFFECTS__
-function isPnpmIgnoreScriptsFlag(cmdArg) {
-  return pnpmIgnoreScriptsFlags.has(cmdArg);
-}
-// @__NO_SIDE_EFFECTS__
 function isPnpmFrozenLockfileFlag(cmdArg) {
   return pnpmFrozenLockfileFlags.has(cmdArg);
 }
 // @__NO_SIDE_EFFECTS__
+function isPnpmIgnoreScriptsFlag(cmdArg) {
+  return pnpmIgnoreScriptsFlags.has(cmdArg);
+}
+// @__NO_SIDE_EFFECTS__
 function isPnpmInstallCommand(cmdArg) {
   return pnpmInstallCommands.has(cmdArg);
 }
 const isPnpmLoglevelFlag = isNpmLoglevelFlag;
-function execScript(scriptName, args, options) {
-  let resolvedOptions;
-  let resolvedArgs;
-  if (!Array.isArray(args) && args !== null && typeof args === "object") {
-    resolvedOptions = args;
-    resolvedArgs = [];
-  } else {
-    resolvedOptions = options;
-    resolvedArgs = args || [];
-  }
-  const { prepost, ...spawnOptions } = {
-    __proto__: null,
-    ...resolvedOptions
-  };
-  if (spawnOptions.shell === true) {
-    return (0, import_spawn.spawn)(scriptName, resolvedArgs, spawnOptions);
-  }
-  const useNodeRun = !prepost && (0, import_node.supportsNodeRun)();
-  const cwd = (0, import_objects.getOwn)(spawnOptions, "cwd") ?? import_node_process.default.cwd();
-  const pnpmLockPath = (0, import_fs.findUpSync)(import_agents.PNPM_LOCK_YAML, { cwd });
-  if (pnpmLockPath) {
-    return execPnpm(["run", scriptName, ...resolvedArgs], spawnOptions);
-  }
-  const packageLockPath = (0, import_fs.findUpSync)(import_agents.PACKAGE_LOCK_JSON, { cwd });
-  if (packageLockPath) {
-    return execNpm(["run", scriptName, ...resolvedArgs], spawnOptions);
-  }
-  const yarnLockPath = (0, import_fs.findUpSync)(import_agents.YARN_LOCK, { cwd });
-  if (yarnLockPath) {
-    return execYarn(["run", scriptName, ...resolvedArgs], spawnOptions);
-  }
-  return (0, import_spawn.spawn)(
-    (0, import_node.getExecPath)(),
-    [
-      ...(0, import_node.getNodeNoWarningsFlags)(),
-      ...useNodeRun ? ["--run"] : [import_agents.NPM_REAL_EXEC_PATH, "run"],
-      scriptName,
-      ...resolvedArgs
-    ],
-    {
-      ...spawnOptions
-    }
-  );
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   execNpm,

package/dist/ansi.d.ts

@@ -2,13 +2,12 @@
  * @fileoverview ANSI escape code utilities.
  * Provides constants and helpers for terminal formatting.
  */
-// ANSI escape codes - commonly used sequences.
-export declare const ANSI_RESET = "\u001B[0m";
 export declare const ANSI_BOLD = "\u001B[1m";
 export declare const ANSI_DIM = "\u001B[2m";
 export declare const ANSI_ITALIC = "\u001B[3m";
-export declare const ANSI_UNDERLINE = "\u001B[4m";
+export declare const ANSI_RESET = "\u001B[0m";
 export declare const ANSI_STRIKETHROUGH = "\u001B[9m";
+export declare const ANSI_UNDERLINE = "\u001B[4m";
 /**
  * Create a regular expression for matching ANSI escape codes.
  *
@@ -24,7 +23,6 @@ export declare const ANSI_STRIKETHROUGH = "\u001B[9m";
  * ansiRegex({ onlyFirst: true })           // matches only the first code
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function ansiRegex(options?: {
     onlyFirst?: boolean;
 }): RegExp;
@@ -38,5 +36,4 @@ export declare function ansiRegex(options?: {
  * stripAnsi('\u001b[1mBold\u001b[0m')    // 'Bold'
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function stripAnsi(text: string): string;

package/dist/ansi.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -29,12 +30,12 @@ __export(ansi_exports, {
   stripAnsi: () => stripAnsi
 });
 module.exports = __toCommonJS(ansi_exports);
-const ANSI_RESET = "\x1B[0m";
 const ANSI_BOLD = "\x1B[1m";
 const ANSI_DIM = "\x1B[2m";
 const ANSI_ITALIC = "\x1B[3m";
-const ANSI_UNDERLINE = "\x1B[4m";
+const ANSI_RESET = "\x1B[0m";
 const ANSI_STRIKETHROUGH = "\x1B[9m";
+const ANSI_UNDERLINE = "\x1B[4m";
 const ANSI_REGEX = /\x1b\[[0-9;]*m/g;
 // @__NO_SIDE_EFFECTS__
 function ansiRegex(options) {

package/dist/archives.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Generic archive extraction utilities.
+ * Supports zip, tar, tar.gz, and tgz formats.
+ */
 /**
  * Archive format type.
  */
@@ -7,15 +11,15 @@ export type ArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip';
  */
 export interface ExtractOptions {
     /** Suppress log messages */
-    quiet?: boolean;
+    quiet?: boolean | undefined;
     /** Strip leading path components (like tar --strip-components) */
-    strip?: number;
+    strip?: number | undefined;
     /** Maximum number of entries to extract (default: 100,000) */
-    maxEntries?: number;
+    maxEntries?: number | undefined;
     /** Maximum size of a single extracted file in bytes (default: 100MB) */
-    maxFileSize?: number;
+    maxFileSize?: number | undefined;
     /** Maximum total extracted size in bytes (default: 1GB) */
-    maxTotalSize?: number;
+    maxTotalSize?: number | undefined;
 }
 /**
  * Detect archive format from file path.
@@ -31,6 +35,22 @@ export interface ExtractOptions {
  * ```
  */
 export declare function detectArchiveFormat(filePath: string): ArchiveFormat | null;
+/**
+ * Extract an archive to a directory.
+ * Automatically detects format from file extension.
+ *
+ * @param archivePath - Path to archive file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ * @throws Error if archive format is not supported
+ *
+ * @example
+ * ```typescript
+ * await extractArchive('/tmp/package.tar.gz', '/tmp/output')
+ * await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
+ * ```
+ */
+export declare function extractArchive(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
 /**
  * Extract a tar archive to a directory.
  *
@@ -73,19 +93,3 @@ export declare function extractTarGz(archivePath: string, outputDir: string, opt
  * ```
  */
 export declare function extractZip(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
-/**
- * Extract an archive to a directory.
- * Automatically detects format from file extension.
- *
- * @param archivePath - Path to archive file
- * @param outputDir - Directory to extract to
- * @param options - Extraction options
- * @throws Error if archive format is not supported
- *
- * @example
- * ```typescript
- * await extractArchive('/tmp/package.tar.gz', '/tmp/output')
- * await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
- * ```
- */
-export declare function extractArchive(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;