@socketsecurity/lib 5.20.1 → 5.23.0

package/CHANGELOG.md

@@ -5,92 +5,120 @@ 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.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
+## [5.23.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.23.0) - 2026-04-22
 
-### Fixed
+### Added
 
-- `src/ipc.ts`: harden stub-file writes against local symlink/TOCTOU. Previously `writeIpcStub` used `mkdir {recursive, mode: 0o700}` + `writeFile`, which on multi-user Linux (`/tmp` sticky-bit but world-writable) let a pre-positioned attacker-owned `.socket-ipc/<app>/` survive the mode argument and redirect the subsequent `writeFile` through symlinks to victim files. Now validates directory ownership + mode on POSIX after `mkdir`, then opens the stub with `O_CREAT | O_WRONLY | O_EXCL | O_NOFOLLOW` so pre-existing inodes trigger EEXIST and final-component symlinks trigger ELOOP rather than silent file overwrite
-- `src/cache-with-ttl.ts` `getOrFetch()` — the inflight-map check ran _after_ `await get(key)`, so two concurrent cold-cache callers both suspended on the same disk read, both saw no cached value, both skipped the inflight check, and both fired `fetcher()`. Moves the inflight check before the persistent-cache lookup (with a re-check afterward) so the advertised dedupe guarantee actually holds
-- `src/cache-with-ttl.ts` — cap the in-memory `memoCache` with LRU eviction (`memoMaxSize`, default 1000). Previously a long-running process (devserver, editor extension) querying many distinct keys grew memory without bound — expired entries were only reclaimed when the same key was read again
-- `src/memoization.ts` `memoizeAsync()` — `entry.timestamp` was set when a cache miss STARTED its `fn(...)` call, so a fn taking longer than `ttl` produced a value classified as expired the moment it resolved; every subsequent caller past the first ttl window re-fetched instead of hitting the cache. Now refreshes the timestamp in the resolve handler. Also bumps `accessOrder` on the stale-dedup branch so an entry mid-refresh isn't evicted while a peer is computing on its behalf
-- `src/tables.ts` — `displayWidth` measured columns by `.length` of the ANSI-stripped string, i.e. UTF-16 code units rather than rendered terminal cells. CJK, emoji, and combined code points misaligned tables. Routes measurement through `stringWidth` (Intl.Segmenter + East Asian Width)
-- `src/paths/packages.ts` — `resolvePackageJsonDirname` / `resolvePackageJsonPath` gated on `filepath.endsWith('package.json')`, which misidentified any file whose name ended in that suffix (e.g. `/foo/my-package.json`) as a manifest. Now checks for the literal final segment
-- `src/json/edit.ts` — `@example` for `getEditableJsonClass` imported from `@socketsecurity/lib/json`, which is not a package export; fixed to `@socketsecurity/lib/json/edit`
+- `@socketsecurity/lib/errors` `isError(value)` — spec-compliant ES2025 [`Error.isError`](https://tc39.es/ecma262/#sec-error.iserror) with an `@@toStringTag`-based shim for older engines. Recognizes cross-realm Errors (worker threads, vm contexts, iframes) that same-realm `instanceof Error` misses
+- `@socketsecurity/lib/errors` `errorMessage(value)` — extracts a readable message from any caught value (Error with cause chain via `messageWithCauses`, primitive, plain object, or nullish) with the shared `UNKNOWN_ERROR` (`'Unknown error'`) fallback. Replaces the `e instanceof Error ? e.message : String(e)` pattern
+- `@socketsecurity/lib/errors` `errorStack(value)` — companion helper returning the cause-aware stack for Error instances (via `stackWithCauses`) and `undefined` otherwise
+- `@socketsecurity/lib/errors` `isErrnoException(value)` — narrows to `NodeJS.ErrnoException` (an Error with a non-empty uppercase-prefixed `.code`, matching the libuv `UV_E*` / Node `ERR_*` conventions), cross-realm safe
+- `@socketsecurity/lib/errors` re-exports `UNKNOWN_ERROR` from `constants/core` so callers don't need a separate import
 
-## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
+### Changed
+
+- `@socketsecurity/lib/errors` pony-cause `messageWithCauses` / `stackWithCauses` / `findCauseByReference` / `getErrorCause` — patched to use `isError` internally so cross-realm Errors are recognized (previously returned `''` for any Error thrown in a different realm)
+
+## [5.22.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.22.0) - 2026-04-21
+
+### Changed
+
+- `@socketsecurity/lib/releases/socket-btm` `getPlatformArch()` / `getBinaryAssetName()` — aligned with pnpm pack-app's `<os>-<arch>[-<libc>]` target format. The Windows OS segment is now `win32` (was `win`); `getPlatformArch('win32', 'x64')` returns `'win32-x64'` and `getBinaryAssetName('node', 'win32', 'x64')` returns `'node-win32-x64.exe'`. Callers that string-match on the output need updates
+
+## [5.21.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.21.0) - 2026-04-20
+
+### Added
 
-### Added — validation
+- `@socketsecurity/lib/schema/validate` — non-throwing Zod/TypeBox validator returning `{ ok, value } | { ok, errors }` with normalized paths
+- `@socketsecurity/lib/schema/parse` — throwing variant for fail-fast trust boundaries
+- `@socketsecurity/lib/schema/types` — `Schema<T>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema`, `Infer<S>`
+- `@socketsecurity/lib/promises` `withResolvers()` — spec-compliant [`Promise.withResolvers`](https://tc39.es/ecma262/#sec-promise.withResolvers) helper with `PromiseWithResolvers<T>` type. Uses the native implementation when available
 
-- `@socketsecurity/lib/validation/validate-schema` — universal validator that accepts any Zod-style schema (Zod v3/v4, or any `safeParse`-shaped duck type) and returns a tagged `{ ok: true, value } | { ok: false, errors }` result with normalized `{ path, message }` issues. Type inference flows through: callers get `z.infer<…>`, no casts. Zod is detected purely structurally via `.safeParse` — no runtime import of the `zod` package required
-- `parseSchema(schema, data)` — throwing twin of `validateSchema` for fail-fast trust-boundary validation
-- `Infer<S>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema` — supporting types exported alongside the helpers
+### Changed
+
+- `@socketsecurity/lib/regexps` `escapeRegExp()` — now spec-compliant with TC39 [`RegExp.escape`](https://tc39.es/ecma262/#sec-regexp.escape); uses the native implementation when available. **Caller-visible shape change**: escaped output now uses `\xHH` for many characters that previously passed through literally (e.g. `escapeRegExp('a')` is now `'\x61'`). Functional equivalence (the compiled regex matches the original input) is preserved; only callers that string-match on escape output need updates
+- `@socketsecurity/lib/memoization` `MemoizeOptions<Args>` — dropped the unused second type parameter. Consumers who wrote `MemoizeOptions<Args, Result>` must drop the second argument
+- `@socketsecurity/lib/packages/specs` `getRepoUrlDetails()` — now accepts `git+https://` / `git+ssh://` GitHub URLs and rejects lookalike hosts (`githubXcom`, `fake-github.com.attacker.tld`). scp-style `git@github.com:…` URLs (no `://`) now return `{ user: '', project: '' }` — callers must normalize to https/ssh upstream
+- `@socketsecurity/lib/url` `urlSearchParamAsBoolean()` — accepts the same truthy vocabulary as `envAsBoolean` (`1` / `true` / `yes` / `on`, case-insensitive). Empty-string input now falls through to `defaultValue` instead of returning `false`
+
+### Removed
+
+- `@socketsecurity/lib/validation/*` subpath retired — exports re-homed:
+  - `validateSchema` / `parseSchema` → `@socketsecurity/lib/schema/validate` / `@socketsecurity/lib/schema/parse`
+  - `safeJsonParse` → `@socketsecurity/lib/json/parse`
+  - Types → `@socketsecurity/lib/schema/types` and `@socketsecurity/lib/json/types`
+- `memoizeDebounced` from `@socketsecurity/lib/memoization` — was misnamed and had no consumers. Use `memoize` / `memoizeAsync` with a `ttl` instead
 
 ### Fixed
 
-- `src/promise-queue.ts`: wrap `task.fn()` invocation via `Promise.resolve().then()` so a **synchronous** throw inside a queued task converts to a proper rejection on `task.reject` instead of escaping as an uncaught exception
-- `src/stdio/progress.ts` `formatTime()`: clamp negative milliseconds so an over-ticking or clock-skewed progress bar no longer renders a negative ETA like `-1m59s`
-- `src/dlx/lockfile.ts`: wrap the scratch-directory cleanup in `finally` with its own `try/catch` so a cleanup failure cannot clobber the real exception from the main try-block
-- `src/dlx/package.ts` `parsePackageSpec`: normalize a bare trailing `@` (e.g. `"pkg@"`) to `version: undefined` so downstream "no version provided" checks behave consistently
-- `src/stdio/prompts.ts`: tighten the `selectModule` destructure type to the two properties actually used (`default`, `Separator`) instead of an `as any` cast
-- `src/http-request.ts`: hoist `CHECKSUM_BSD_RE` and `CHECKSUM_GNU_RE` regex literals to module scope so `parseChecksums()` no longer re-declares them once per line inside its loop
-- `src/dlx/manifest.ts`: correct the `@fileoverview` "Primary API" list to match the actual `DlxManifest` methods (`get/set/clear/clearAll/isFresh/getManifestEntry`) and flag `setPackageEntry` / `setBinaryEntry` as deprecated
+- `@socketsecurity/lib/versions` `maxVersion()` / `minVersion()` — return the latest/earliest prerelease for all-prerelease inputs (previously returned `undefined`)
+- `@socketsecurity/lib/fs` `findUp()` / `findUpSync()` — traverse up to and **including** the filesystem root (previously missed matches at `/.foo`)
+- `@socketsecurity/lib/words` `capitalize()` — safe for non-BMP characters (emoji, astral-plane scripts); previously produced broken surrogate pairs
+- `@socketsecurity/lib/words` `determineArticle()` — case-insensitive vowel match (`Apple` → `an Apple`)
+- `@socketsecurity/lib/archives` `extractZip()` / `extractTar()` / `extractTarGz()` — missing-archive errors now uniformly surface as `ENOENT` with `code` / `path` / message (previously `extractZip` surfaced adm-zip's generic `"Invalid filename"`)
+- `@socketsecurity/lib/promise-queue` — bounded queue now rejects the newest submission when full, preserving in-flight work
+- `@socketsecurity/lib/cacache` / `@socketsecurity/lib/cache-with-ttl` — wildcard key deletion anchors both ends of the pattern (`deleteAll('foo*bar')` no longer sweeps `foo123bar-extra`)
+- `@socketsecurity/lib/process-lock` — sub-second `staleMs` values now honored at full precision; TOCTOU window on lock acquisition closed
+- `@socketsecurity/lib/suppress-warnings` `withSuppressedWarnings()` — no longer wipes concurrent suppressions on exit
+- Unbounded LRU caches in `@socketsecurity/lib/dlx` capped (binary path, package.json path); negative package.json lookups now expire after 10s
+- Glob cache keys for array-valued options (e.g. `ignore`) are order-insensitive
 
-## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
+### Performance
 
-### Fixed — stdio (restore accidentally-dropped modules)
+- `@socketsecurity/lib/memoization` — `memoize()` / `memoizeAsync()` cache-hit bookkeeping dropped from O(n) to O(1). Noticeable on caches with many entries
+- `@socketsecurity/lib/cacache` — wildcard `clear()` no longer recompiles the match regex per streamed entry
 
-5.19.0 shipped a breaking change that was not called out in its changelog or version bump: a refactor commit removed `stdio/prompts`, `stdio/progress`, `stdio/clear`, and the vendored `external/@inquirer/*` shims. socket-cli and other consumers import `stdio/prompts` directly and broke on upgrade.
+## [5.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
 
-Restored:
+### Fixed
 
-- `@socketsecurity/lib/stdio/prompts` — inquirer wrappers (`password`, `confirm`, `input`, `select`, `checkbox`, `search`)
-- `@socketsecurity/lib/stdio/progress` — progress-bar utility (`ProgressBar` class)
-- `@socketsecurity/lib/stdio/clear` — terminal line/screen/cursor helpers
-- `src/external/@inquirer/{checkbox,confirm,input,password,search,select}.js` vendor shims
-- Corresponding test suites
+- `@socketsecurity/lib/ipc` — harden stub-file writes against symlink/TOCTOU attacks on shared-tmp filesystems (POSIX ownership + mode validation, `O_EXCL | O_NOFOLLOW` open)
+- `@socketsecurity/lib/cache-with-ttl` `getOrFetch()` — close concurrent-caller race that let two cold-cache awaits both skip the inflight-dedupe check and fire the fetcher twice
+- `@socketsecurity/lib/cache-with-ttl` — cap the in-memory memo layer with LRU eviction (`memoMaxSize`, default 1000); long-running processes no longer grow unbounded
+- `@socketsecurity/lib/memoization` `memoizeAsync()` — refresh cache entry timestamp on resolve so slow fetches (longer than `ttl`) aren't classified as expired the moment they land
+- `@socketsecurity/lib/tables` — `displayWidth` now measures rendered terminal cells (via `stringWidth`) instead of UTF-16 code units; CJK / emoji / combining marks align correctly
+- `@socketsecurity/lib/paths/packages` — `resolvePackageJsonDirname` / `resolvePackageJsonPath` no longer mis-identify files like `/foo/my-package.json` as package manifests
+- `@socketsecurity/lib/json/edit` — `@example` import path corrected
 
-## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
+## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
+
+### Added
 
-### Added — dlx/integrity (new module)
+- `@socketsecurity/lib/validation/validate-schema` — universal Zod-style schema validator with `validateSchema` (tagged result) and `parseSchema` (throwing); `Infer<S>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema` types. No runtime `zod` dependency
 
-- `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
+> **Deprecated in 5.21.0**: moved to `@socketsecurity/lib/schema/*`.
 
-### Added — dlx/arborist (new module)
+### Fixed
 
-- `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
+- `@socketsecurity/lib/promise-queue` — synchronous throws inside a queued task now convert to proper rejections instead of escaping as uncaught exceptions
+- `@socketsecurity/lib/stdio/progress` `formatTime()` — clamp negative milliseconds so over-ticking / clock-skewed bars don't render negative ETAs
+- `@socketsecurity/lib/dlx/lockfile` — scratch-directory cleanup can no longer clobber the real exception from the main block
+- `@socketsecurity/lib/dlx/package` `parsePackageSpec` — normalize a bare trailing `@` (e.g. `"pkg@"`) to `version: undefined`
+- `@socketsecurity/lib/stdio/prompts` — tighten an internal destructure type away from `as any`
+- `@socketsecurity/lib/http-request` — hoist checksum regex literals out of a per-line loop
 
-### Added — dlx/lockfile (new module)
+## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
 
-- `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`
+### Fixed
 
-### Added — dlx existing modules
+Restore `@socketsecurity/lib/stdio/prompts`, `@socketsecurity/lib/stdio/progress`, and `@socketsecurity/lib/stdio/clear` — accidentally removed in 5.19.0 without a major-bump callout. Downstream consumers that import `stdio/prompts` directly are unbroken.
 
-- `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)
+## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
 
-### Fixed — external
+### Added
 
-- `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`)
+- `@socketsecurity/lib/dlx/integrity` — hash verification utilities: `HashSpec`, `NormalizedHash`, `ComputedHashes`, `normalizeHash()`, `computeHashes()`, `verifyHash()` (constant-time via `crypto.timingSafeEqual`), `DlxHashMismatchError`
+- `@socketsecurity/lib/dlx/arborist` — hardened `@npmcli/arborist` wrappers: `safeIdealTree()`, `safeReify()`, `writeSafeNpmrc()`. Locks down `audit`, `fund`, `ignoreScripts`, `saveBundle`, etc. Supports `before?: Date` for release-age enforcement
+- `@socketsecurity/lib/dlx/lockfile` — `generatePackagePin()` returns `{ name, version, hash, packageJson, lockfile }` for a resolved package. Default `minReleaseDays: 7` refuses versions published in the last week (`0` to disable); `minReleaseMins` accepted as pnpm-style alias
+- `DlxPackageOptions.hash`, `DlxPackageOptions.lockfile`, `DlxBinaryOptions.hash` — first-class integrity + lockfile options on the dlx entry points
 
-### Changed — build (bundle size)
+### Fixed
 
-- `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
+- `pacote` shim — exposes `tarball`, `manifest`, `packument` alongside `extract`. Fixes a latent runtime crash in `fetchPackageManifest` / `fetchPackagePackument` callers
+
+### Changed
+
+Reduced bundle size of `dist/external/npm-pack.js` (−771 KB, −30.5%) and `dist/external/zod.js` (−306 KB, −51.2%) by stubbing code paths our callers never reach (Sigstore attestation, arborist audit/query, zod locale translations, etc.)
 
 ## [5.18.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.2) - 2026-04-14
 
@@ -100,70 +128,63 @@ Restored:
 
 ## [5.18.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.1) - 2026-04-14
 
-### Changed — build
+### Changed
 
-- Dedup npm-pack.js bundle via pnpm overrides: pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive npm packages (npm-bundled, npm-normalize-package-bin, json-parse-even-better-errors, @npmcli/installed-package-contents, @npmcli/name-from-folder, @npmcli/promise-spawn, @npmcli/redact)
-- npm-pack.js: 69,738 → 66,443 lines (2.59MB → 2.46MB), 22 duplicate packages removed
+- Deduplicated the `dist/external/npm-pack` bundle via `pnpm overrides` (pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive `@npmcli/*` packages) — 22 duplicate packages removed, ~130 KB smaller
 
 ## [5.18.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.0) - 2026-04-14
 
-### Added — dlx
+### Added
 
-- Socket Firewall API check before package downloads — resolves dependency tree via `buildIdealTree`, checks all packages against `firewall-api.socket.dev/purl` in parallel, blocks on critical/high severity alerts
+- `@socketsecurity/lib/dlx` — Socket Firewall API check before package downloads. Resolves the dependency tree and blocks on critical/high severity alerts
 
-### Changed — http-request
+### Changed
 
-- Default `User-Agent` header updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
+- `@socketsecurity/lib/http-request` — default `User-Agent` updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
 
 ## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `isUnixPath()` — detect MSYS/Git Bash drive letter notation (`/c/...`)
+- `@socketsecurity/lib/paths` `isUnixPath()` — detect MSYS/Git Bash drive-letter notation (`/c/...`)
 
-### Changed — paths
+### Changed
 
-- `normalizePath()` now converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
-- `fromUnixPath()` now produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
+- `@socketsecurity/lib/paths` `normalizePath()` — converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
 
 ## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
 
-### Fixed — dlx
+### Fixed
 
-- Normalize dlx directory path in `isInSocketDlx` for Windows compatibility
+- `@socketsecurity/lib/dlx` `isInSocketDlx` — normalize the dlx directory path for Windows compatibility
 
 ## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
 
-### Added — http-request
-
-- `stream` option on `HttpRequestOptions` — resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
-- `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
-
-### Changed — http-request
+### Added
 
-- `httpDownload` now uses `httpRequest` with `stream: true` internally, eliminating ~120 lines of duplicated HTTP plumbing
+- `@socketsecurity/lib/http-request` — `stream` option on `HttpRequestOptions` resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
+- `@socketsecurity/lib/http-request` — `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
 
 ## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
 
-### Added — http-request
+### Added
 
-- `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled, carries the full `HttpResponse`
-- `throwOnError` option on `HttpRequestOptions` — non-2xx responses throw instead of resolving with `ok: false`, enabling retry of HTTP errors
-- `onRetry` callback on `HttpRequestOptions` — customize retry behavior per-attempt (return `false` to stop, a `number` to override delay, `undefined` for default backoff)
-- Streaming body support — `body` accepts `Readable` streams (incl. `form-data` npm package), auto-merges `getHeaders()` when present
-- `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 `Retry-After` header parser (strict integer seconds + HTTP-date formats)
-- `sanitizeHeaders()` — redact sensitive headers (`authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `proxy-authenticate`, `www-authenticate`) for safe logging
+- `@socketsecurity/lib/http-request`:
+  - `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled; carries the full `HttpResponse`
+  - `throwOnError` option — non-2xx responses throw instead of resolving with `ok: false`
+  - `onRetry` callback — customize retry behavior per-attempt (`false` to stop, a `number` to override delay, `undefined` for default backoff)
+  - Streaming body support — `body` accepts `Readable` streams (incl. `form-data`), auto-merges `getHeaders()` when present
+  - `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 parser
+  - `sanitizeHeaders()` — redact sensitive headers for safe logging
 
-### Changed — http-request
+### Changed
 
-- `HttpRequestOptions.body` type widened from `Buffer | string` to `Buffer | Readable | string`
-- Redirect responses now drained via `res.resume()` to free sockets
-- `maxResponseSize` exceeded now cleans up both response and request
-- `onResponse` hooks wrapped in try/catch — user hook errors can no longer leave promises pending
+- `@socketsecurity/lib/http-request` — `HttpRequestOptions.body` widened to `Buffer | Readable | string`; `onResponse` hook errors no longer leave promises pending
 
 ## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
 

package/README.md

@@ -7,219 +7,62 @@
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
-Core infrastructure library for [Socket.dev](https://socket.dev/) security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
-
-## Prerequisites
-
-**Node.js 22 or higher** is required.
+Core utilities for [Socket.dev](https://socket.dev/) tools: file system, processes, HTTP, env detection, logging, spinners, and more. Tree-shakeable, TypeScript-first, cross-platform.
 
 ## Install
 
 ```bash
-# Using pnpm (recommended)
 pnpm add @socketsecurity/lib
-
-# Using npm
-npm install @socketsecurity/lib
-
-# Using yarn
-yarn add @socketsecurity/lib
 ```
 
 ## Quick Start
 
 ```typescript
 import { Spinner } from '@socketsecurity/lib/spinner'
-import { getDefaultLogger } from '@socketsecurity/lib/logger'
 import { readJson } from '@socketsecurity/lib/fs'
 
-const logger = getDefaultLogger()
-const spinner = Spinner({ text: 'Loading package.json...' })
-
+const spinner = Spinner({ text: 'Loading…' })
 spinner.start()
 const pkg = await readJson('./package.json')
-spinner.successAndStop('Loaded successfully')
-
-logger.success(`Package: ${pkg.name}@${pkg.version}`)
+spinner.successAndStop(`Loaded ${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
-- [HTTP Utilities](./docs/http-utilities.md) - Making requests, downloading files, and retry logic
-- [Process Utilities](./docs/process-utilities.md) - Spawning processes, IPC, and locks
-- [Package Management](./docs/package-management.md) - npm/pnpm/yarn detection and operations
-- [Environment](./docs/environment.md) - CI detection, env getters, and platform checks
-- [Constants](./docs/constants.md) - Node versions, npm URLs, and platform values
-- [Examples](./docs/examples.md) - Real-world usage patterns
-- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
-
-## What's Inside
-
-### Visual Effects
-
-Spinners, colored loggers, themes, progress bars, and terminal output formatting.
-
-- `Spinner` - Animated CLI spinners with progress tracking
-- `getDefaultLogger()` - Colored console logger with symbols
-- `LOG_SYMBOLS` - Colored terminal symbols (✓, ✗, ⚠, ℹ, →)
-- `setTheme()` - Customize colors across the library
-
-### File System
-
-Cross-platform file operations with safe deletion and convenient wrappers.
-
-- `readFileUtf8()`, `readFileBinary()` - Read files as text or binary
-- `readJson()`, `writeJson()` - Parse and format JSON files
-- `safeDelete()` - Protected deletion with safety checks
-- `findUp()`, `findUpSync()` - Traverse up to find files
-- `safeMkdir()` - Create directories without EEXIST errors
-- `validateFiles()` - Check file readability (useful for Yarn PnP, pnpm)
-
-### HTTP Utilities
-
-Native Node.js HTTP/HTTPS requests with retry logic and redirects.
-
-- `httpJson()` - Fetch and parse JSON from APIs
-- `httpText()` - Fetch text/HTML content
-- `httpDownload()` - Download files with progress callbacks
-- `httpRequest()` - Full control over requests and responses
-- Automatic redirects, exponential backoff retries, timeout support
-
-### Process Management
-
-Spawn child processes safely with cross-platform support.
-
-- `spawn()` - Promise-based process spawning with output capture
-- `spawnSync()` - Synchronous version for blocking operations
-- Array-based arguments prevent command injection
-- Automatic Windows `.cmd`/`.bat` handling
-- `processLock.withLock()` / `processLock.acquire()` / `processLock.release()` - Ensure only one instance runs at a time
-- `writeIpcStub()` / `getIpcStubPath()` - Filesystem-based inter-process data handoff
-
-### Environment Detection
-
-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 (cross-platform, with Windows `USERPROFILE` fallback)
-- Test rewiring with `setEnv()`, `resetEnv()`
-
-### Package Management
-
-Detect and work with npm, pnpm, and yarn.
-
-- `detectPackageManager()` - Identify running package manager from `npm_config_user_agent` / binary path
-- Package manifest operations
-- Lock file management
-
-### Constants
-
-Pre-defined values for Node.js, npm, and platform detection.
-
-- `getNodeMajorVersion()` - Get current Node.js major version
-- `WIN32`, `DARWIN` - Platform booleans (use `!WIN32 && !DARWIN` for Linux)
-- `getAbortSignal()` - Global abort signal
-
-### Utilities
-
-Helpers for arrays, objects, strings, promises, sorting, and more.
-
-- Arrays, objects, strings manipulation
-- Promise utilities and queues
-- Natural sorting
-- Version comparison
-- Error handling with causes
-
-## Features
-
-- **Tree-shakeable exports** - Import only what you need
-- **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** - 6000+ tests across 139+ test files
-- **Security-focused** - Safe defaults, command injection protection
-- **CommonJS output** - Compatible with Node.js tooling
-
-## Common Use Cases
-
-### Running Shell Commands
+Every export lives under a subpath — pick what you need:
 
 ```typescript
 import { spawn } from '@socketsecurity/lib/spawn'
-
-const result = await spawn('git', ['status'])
-console.log(result.stdout)
-```
-
-### Making API Requests
-
-```typescript
 import { httpJson } from '@socketsecurity/lib/http-request'
-
-const data = await httpJson('https://api.example.com/data')
-```
-
-### Visual Feedback
-
-```typescript
-import { Spinner } from '@socketsecurity/lib/spinner'
-
-const spinner = Spinner({ text: 'Processing...' })
-spinner.start()
-// ... do work ...
-spinner.successAndStop('Complete!')
-```
-
-### Safe File Deletion
-
-```typescript
 import { safeDelete } from '@socketsecurity/lib/fs'
-
-// Protected against deleting parent directories
-await safeDelete('./build')
-```
-
-## Troubleshooting
-
-**Module not found**: Verify you're importing from the correct path:
-
-```typescript
-// Correct
-import { Spinner } from '@socketsecurity/lib/spinner'
-
-// Wrong
-import { Spinner } from '@socketsecurity/lib'
 ```
 
-**Node version error**: This library requires Node.js 22+. Check your version:
+## Documentation
 
-```bash
-node --version
-```
+Start with the [API Index](./docs/api-index.md) — every subpath export with a one-line description.
 
-For more issues, see the [Troubleshooting Guide](./docs/troubleshooting.md).
+- [Getting Started](./docs/getting-started.md) – install + first examples
+- [Visual Effects](./docs/visual-effects.md) – spinners, loggers, themes
+- [File System](./docs/file-system.md) – files, globs, paths, safe deletion
+- [HTTP Utilities](./docs/http-utilities.md) – requests, downloads, retries
+- [Process Utilities](./docs/process-utilities.md) – spawn, IPC, locks
+- [Package Management](./docs/package-management.md) – npm/pnpm/yarn detection
+- [Environment](./docs/environment.md) – CI/platform detection, env getters
+- [Constants](./docs/constants.md) – Node versions, npm URLs, platform values
+- [Examples](./docs/examples.md) – real-world patterns
+- [Troubleshooting](./docs/troubleshooting.md) – common issues
 
 ## Development
 
 ```bash
-pnpm install    # Install dependencies
-pnpm build      # Build the library
-pnpm test       # Run tests
-pnpm run cover  # Run tests with coverage
-pnpm dev        # Watch mode
-pnpm run lint   # Check code style
-pnpm run fix    # Fix formatting issues
+pnpm install          # install
+pnpm build            # build
+pnpm test             # run tests
+pnpm run cover        # tests with coverage
+pnpm dev              # watch mode
+pnpm run lint         # check style
+pnpm run fix          # auto-fix formatting
 ```
 
-## Contributing
-
-Contributions are welcome! Please read the [CLAUDE.md](./CLAUDE.md) file for development guidelines and coding standards.
+See [CLAUDE.md](./CLAUDE.md) for contributor guidelines.
 
 ## License
 

package/dist/archives.js

@@ -80,6 +80,16 @@ function validatePathWithinBase(targetPath, baseDir, entryName) {
     );
   }
 }
+function assertArchiveExists(archivePath) {
+  if (!(0, import_node_fs.existsSync)(archivePath)) {
+    const err = new Error(
+      `ENOENT: no such file or directory, open '${archivePath}'`
+    );
+    err.code = "ENOENT";
+    err.path = archivePath;
+    throw err;
+  }
+}
 function detectArchiveFormat(filePath) {
   const lower = filePath.toLowerCase();
   if (lower.endsWith(".tar.gz")) {
@@ -116,6 +126,7 @@ async function extractArchive(archivePath, outputDir, options = {}) {
   }
 }
 async function extractTar(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -207,6 +218,7 @@ async function extractTar(archivePath, outputDir, options = {}) {
   }
 }
 async function extractTarGz(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -298,6 +310,7 @@ async function extractTarGz(archivePath, outputDir, options = {}) {
   }
 }
 async function extractZip(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,

package/dist/cacache.js

@@ -41,17 +41,14 @@ __export(cacache_exports, {
 module.exports = __toCommonJS(cacache_exports);
 var import_cacache = __toESM(require("./external/cacache"));
 var import_socket = require("./paths/socket");
-function matchesPattern(key, pattern) {
+function createPatternMatcher(pattern) {
   if (!pattern.includes("*")) {
-    return key.startsWith(pattern);
+    return (key) => key.startsWith(pattern);
   }
-  const regex = patternToRegex(pattern);
-  return regex.test(key);
-}
-function patternToRegex(pattern) {
   const escaped = pattern.replaceAll(/[.+?^${}()|[\]\\]/g, "\\$&");
   const regexPattern = escaped.replaceAll("*", ".*");
-  return new RegExp(`^${regexPattern}`);
+  const regex = new RegExp(`^${regexPattern}$`);
+  return (key) => regex.test(key);
 }
 async function clear(options) {
   const opts = { __proto__: null, ...options };
@@ -84,9 +81,10 @@ async function clear(options) {
     return removed2;
   }
   let removed = 0;
+  const matches = createPatternMatcher(opts.prefix);
   const stream = cacache2.ls.stream(cacheDir);
   for await (const entry of stream) {
-    if (matchesPattern(entry.key, opts.prefix)) {
+    if (matches(entry.key)) {
       try {
         await cacache2.rm.entry(cacheDir, entry.key);
         removed++;