@socketsecurity/lib 5.25.1 → 5.26.1

package/CHANGELOG.md

@@ -5,1573 +5,1002 @@ 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.26.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.1) - 2026-05-01
+
+### Added
+
+- `crypto` (new export) — `hash(algorithm, data, encoding)` one-shot helper that prefers Node's native `crypto.hash` (added v21.7.0 / v20.12.0; ~30% faster than `createHash().update().digest()` on small inputs) with a streaming fallback. `getNativeHash` exposed as `@internal` for tests
+- `promises` `fromAsync<T>(source)` — drains an async iterable into an array, per [TC39 Array.fromAsync](https://tc39.es/proposal-array-from-async/). Backed by the new `ArrayFromAsync` primordial (Node 22+) with a `for await` + push fallback
+- `primordials` `ArrayFromAsync` — ES2024 primordial. Unbound, matching `ArrayFrom`
+- `globs` `glob` / `globSync` route through `node:fs.glob` / `node:fs.globSync` (Node 22+) when caller options reduce to `cwd` + `ignore` (mapped to `exclude`); fall back to fast-glob for the wider option surface. Output paths are normalized to forward slashes on Windows to match fast-glob's contract
+- `effects/shimmer` — pure-functional shimmer engine
+- `effects/shimmer-terminal` — terminal (ANSI) renderer for the engine
+- `effects/shimmer-keyframes` — SVG keyframe batcher for the engine
+- `releases/github-types`, `github-assets`, `github-auth`, `github-api`, `github-downloads`, `github-archives` — six focused submodules replacing the single `releases/github` export
+
+### Changed
+
+- `http-request` retry/backoff sites use `setTimeout` from `node:timers/promises` instead of hand-rolled `new Promise(r => setTimeout(r, ms))`
+- `dlx/cache`, `dlx/integrity`, `dlx/binary` — 4 one-shot hash sites switched to the new `crypto.hash()` helper
+- `package.json` — pin `publishConfig: {access: "public", provenance: true}` so attestation is a property of the package, not a property of the workflow's `--provenance` CLI flag. Survives any direct-publish path that bypasses `provenance.yml`. `access: "public"` also load-bears for first-publish of `@scoped` packages on a fresh npm registry session.
+- `promise-queue.runNext` — replace the `PromiseResolve().then().catch().finally()` chain with an async IIFE + try/catch/finally. Same semantics (defers `task.fn()` by one microtask so synchronous throws become rejections), more explicit about the success/error/cleanup flow.
+- `packages/isolation.resolveRealPath` — replace `realpath().catch(fallback)` with try/await/catch. Same fall-back-on-ENOENT behavior, clearer that the catch is intentional.
+- **BREAKING**: `spinner` `ShimmerInfo` shape — `{ direction, speed, frame }` (was: `currentDir`, `mode`, `speed`, `step`). User-facing `ShimmerConfig` is unchanged
+- `getLatestRelease` / `getReleaseAssetUrl` return `undefined` (was: `null`) when no result is found, and no longer log on success/retry — errors throw, success returns
+
+### Removed
+
+- **BREAKING**: `effects/text-shimmer`, `effects/ultra`, `effects/types` subpath exports. Migrate to `effects/shimmer` (+ `effects/shimmer-terminal`); `RAINBOW_GRADIENT` now lives in `themes/utils`
+- **BREAKING**: `themes` barrel export. Import from `themes/themes`, `themes/context`, `themes/utils`, or `themes/types`
+- **BREAKING**: `releases/github` subpath export. Migrate to the focused submodules (see Added)
+- `getLatestRelease({ quiet })` / `getReleaseAssetUrl({ quiet })` — the helpers no longer log
+
+### Fixed
+
+- `globs` `getGlobMatcher` — narrow the `path.matchesGlob` fast-path that an earlier draft introduced. `path.matchesGlob` doesn't honor the picomatch defaults (`dot: true`, `nocase: true`) that callers expect, so taking the fast-path under those defaults silently changed observable behavior — including breaking the case-insensitive default everywhere a single-pattern matcher was used. The fast-path now activates only when the caller has explicitly opted out of both defaults (`nocase: false` AND `dot: false`), signaling "I want strict, case-sensitive, no-dotfile-match" — exactly what `path.matchesGlob` provides
+- `globs` `glob` / `globSync` — normalize results to forward slashes via `paths/normalize.normalizePath` regardless of which backend (`node:fs.glob` or `fast-glob`) was used. Restores fast-glob's forward-slash contract on Windows, where `node:fs.glob` returns native-OS separators
+- `globs` `glob` / `globSync` / `globStreamLicenses` — strip a trailing `/` from `ignore` patterns before passing them to fast-glob. The gitignore convention of writing directory entries as `dist/` was silently dropped at the deep-filter level (fast-glob walked the entire subtree before discarding results), which on a large `dist/` could push memory past the limit. fast-glob v3.3.3 and the unreleased v4 both have the bug; tracked at [mrmlnc/fast-glob#437](https://github.com/mrmlnc/fast-glob/issues/437). Same workaround as [SocketDev/socket-cli#1288](https://github.com/SocketDev/socket-cli/pull/1288).
+- `releases/github-api` `getLatestRelease` and `getReleaseAssetUrl` transparently fall back to GraphQL when GitHub REST returns 200 + empty body (search-degraded incident shape)
+- `github` `resolveRefToSha` and `fetchGhsaDetails` get the same GraphQL fallback for the same incident shape
+- All fallbacks only fire on the empty-body signature; real 404s, rate-limits, and 5xx still propagate
+
+## [5.26.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.0) - 2026-04-27
+
+### Added
+
+- `github` `GitHubEmptyBodyError` — exported error class for GitHub's "search degraded" 200 OK + empty body incident shape
+- `nothrow` option on `getLatestRelease` and `getReleaseAssetUrl` — return `undefined` instead of throwing when both REST and GraphQL backends are degraded
+
+### Changed
+
+- `getLatestRelease` / `getReleaseAssetUrl` return `undefined` (was: `null`) when no result is found, and no longer log on success/retry — errors throw, success returns
+- `fetchGhsaDetails` GraphQL fallback normalizes severity to lowercase to match REST shape
+
+### Removed
+
+- `getLatestRelease({ quiet })` / `getReleaseAssetUrl({ quiet })` — no longer accepted (the helpers don't log anymore)
+
+### Fixed
+
+- `releases/github` `getLatestRelease` and `getReleaseAssetUrl` fall back to GraphQL on the empty-body incident shape
+- `github` `resolveRefToSha` and `fetchGhsaDetails` get the same GraphQL fallback
+- All fallbacks fire only on `GitHubEmptyBodyError`; real 404s / rate-limits / 5xx still propagate
+
 ## [5.25.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.25.1) - 2026-04-27
 
 ### Fixed
 
-- `@socketsecurity/lib/primordials` `StringPrototypeReplace` / `StringPrototypeReplaceAll` — `replaceValue` parameter now accepts the callback form (`(substring, ...args) => string`) in addition to a literal string, matching `String.prototype.replace`'s actual signature
+- `primordials` `StringPrototypeReplace` / `StringPrototypeReplaceAll` — `replaceValue` accepts the callback form, matching `String.prototype.replace`
 
 ## [5.25.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.25.0) - 2026-04-26
 
 ### Added
 
-- `@socketsecurity/lib/primordials` — new public module exposing safe references to ~100 built-in constructors, static methods, and prototype methods captured at module-load time. Mirrors the Node.js-internal primordials convention: static methods retain their name (`ObjectKeys`, `ArrayIsArray`, `JSONParse`, `ReflectApply`); prototype methods are uncurried via `uncurryThis` (`StringPrototypeSlice(str, 0, 3)` instead of `str.slice(0, 3)`); constructors get a `Ctor` suffix (`MapCtor`, `SetCtor`, `ErrorCtor`, …) to avoid shadowing the capital-case global. Library internals migrated to use these helpers so prototype-pollution attacks on the caller realm can't redirect them. Surface includes `Function`, `Math`, and the full Error subclass set (`TypeErrorCtor`, `RangeErrorCtor`, `SyntaxErrorCtor`, `ReferenceErrorCtor`, `URIErrorCtor`, `EvalErrorCtor`, `AggregateErrorCtor`) after audit-driven coverage passes
+- `primordials` — public module exposing ~100 safe references to built-in constructors, static methods, and prototype methods captured at load time. Static methods keep their name (`ObjectKeys`, `JSONParse`); prototype methods are uncurried (`StringPrototypeSlice(str, 0, 3)`); constructors use a `Ctor` suffix (`MapCtor`, `ErrorCtor`)
 
 ## [5.24.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.24.0) - 2026-04-22
 
 ### Removed
 
-- `@socketsecurity/lib/env/socket-cli-shadow` — deleted. Unused after Socket CLI's shadow infrastructure was removed
+- `env/socket-cli-shadow` — deleted (unused)
 
 ### Fixed
 
-- `packPackage()` / `extractPackage()` now work for non-registry specs (local dir/tarball, remote tarball URL, git). The bundled pacote fetchers (`dir.js`, `file.js`, `remote.js`, `git.js`) were over-stubbed and broke every non-registry path
-- `EditablePackageJson.prepare()` no longer throws `git.find is not a function`. `@npmcli/git` is reached from `normalize.gitHead`, not just `arb.audit()`, so it can't be stubbed
-- `packPackage(<dir>)` now runs `prepack` / `postpack` scripts instead of throwing `runScript is not a function`. `@npmcli/run-script` is reachable whenever `ignoreScripts` isn't set
+- `packPackage()` / `extractPackage()` work for non-registry specs (local dir/tarball, remote tarball, git)
+- `EditablePackageJson.prepare()` no longer throws `git.find is not a function`
+- `packPackage(<dir>)` runs `prepack` / `postpack` scripts instead of throwing
 
 ## [5.23.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.23.0) - 2026-04-22
 
 ### Added
 
-- `@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
+- `errors` `isError(value)` — spec-compliant ES2025 [`Error.isError`](https://tc39.es/ecma262/#sec-error.iserror), cross-realm safe
+- `errors` `errorMessage(value)` — readable message from any caught value (Error, primitive, object, nullish) with cause-chain support
+- `errors` `errorStack(value)` — cause-aware stack or `undefined`
+- `errors` `isErrnoException(value)` — narrows to `NodeJS.ErrnoException`, cross-realm safe
+- `errors` re-exports `UNKNOWN_ERROR`
 
 ### 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)
+- pony-cause `messageWithCauses` / `stackWithCauses` / `findCauseByReference` / `getErrorCause` use `isError` internally — cross-realm Errors are recognized (previously returned `''`)
 
 ## [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
+- `releases/socket-btm` `getPlatformArch()` / `getBinaryAssetName()` — aligned with pnpm pack-app's `<os>-<arch>[-<libc>]` format. Windows OS segment is now `win32` (was `win`)
 
 ## [5.21.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.21.0) - 2026-04-20
 
 ### Added
 
-- `@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
+- `schema/validate` — non-throwing Zod/TypeBox validator returning `{ ok, value } | { ok, errors }`
+- `schema/parse` — throwing variant for fail-fast trust boundaries
+- `schema/types` — `Schema<T>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema`, `Infer<S>`
+- `promises` `withResolvers()` — spec-compliant [`Promise.withResolvers`](https://tc39.es/ecma262/#sec-promise.withResolvers); uses native when available
 
 ### 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`
+- `regexps` `escapeRegExp()` — now spec-compliant with TC39 [`RegExp.escape`](https://tc39.es/ecma262/#sec-regexp.escape). **Output shape changed**: many characters now escape to `\xHH` (e.g. `'a'` → `'\x61'`); compiled regex behavior is preserved
+- `memoization` `MemoizeOptions<Args>` — dropped unused second type parameter
+- `packages/specs` `getRepoUrlDetails()` — accepts `git+https://` / `git+ssh://` GitHub URLs; rejects lookalike hosts. scp-style `git@github.com:…` returns `{ user: '', project: '' }`
+- `url` `urlSearchParamAsBoolean()` — accepts the same truthy vocabulary as `envAsBoolean` (`1` / `true` / `yes` / `on`); empty string falls through to `defaultValue`
 
 ### 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
+- `validation/*` subpath retired — exports re-homed: `validateSchema` / `parseSchema` → `schema/validate` / `schema/parse`; `safeJsonParse` → `json/parse`; types → `schema/types` and `json/types`
+- `memoization` `memoizeDebounced` — use `memoize` / `memoizeAsync` with a `ttl` instead
 
 ### Fixed
 
-- `@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
+- `versions` `maxVersion()` / `minVersion()` — return latest/earliest prerelease for all-prerelease inputs
+- `fs` `findUp()` / `findUpSync()` — traverse up to and including the filesystem root
+- `words` `capitalize()` — safe for non-BMP characters (emoji, astral-plane scripts)
+- `words` `determineArticle()` — case-insensitive vowel match
+- `archives` `extractZip` / `extractTar` / `extractTarGz` — missing-archive errors uniformly surface as `ENOENT`
+- `promise-queue` — bounded queue rejects newest submission when full, preserving in-flight work
+- `cacache` / `cache-with-ttl` — wildcard key deletion anchors both ends of the pattern
+- `process-lock` — sub-second `staleMs` values honored at full precision; TOCTOU window on acquisition closed
+- `suppress-warnings` `withSuppressedWarnings()` — no longer wipes concurrent suppressions on exit
+- `dlx` LRU caches capped (binary path, package.json path); negative package.json lookups expire after 10s
+- Glob cache keys for array-valued options are order-insensitive
 
 ### Performance
 
-- `@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
+- `memoization` cache-hit bookkeeping is now O(1) (was O(n))
+- `cacache` wildcard `clear()` no longer recompiles the match regex per entry
 
 ## [5.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
 
 ### Fixed
 
-- `@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
+- `ipc` — stub-file writes hardened against symlink/TOCTOU attacks (`O_EXCL | O_NOFOLLOW`, ownership + mode validation)
+- `cache-with-ttl` `getOrFetch()` — closes concurrent-caller race that fired the fetcher twice
+- `cache-with-ttl` — in-memory memo layer capped via LRU (`memoMaxSize`, default 1000)
+- `memoization` `memoizeAsync()` — refreshes entry timestamp on resolve so slow fetches aren't immediately classified as expired
+- `tables` — `displayWidth` measures rendered terminal cells via `stringWidth` (CJK / emoji / combining marks align correctly)
+- `paths/packages` — `resolvePackageJsonDirname` / `resolvePackageJsonPath` no longer mis-identify files like `/foo/my-package.json`
 
 ## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
 
 ### Added
 
-- `@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
+- `validation/validate-schema` — universal Zod-style schema validator with `validateSchema` (tagged result) and `parseSchema` (throwing). No runtime `zod` dep
 
-> **Deprecated in 5.21.0**: moved to `@socketsecurity/lib/schema/*`.
+> **Deprecated in 5.21.0**: moved to `schema/*`.
 
 ### Fixed
 
-- `@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
+- `promise-queue` — sync throws inside a queued task convert to proper rejections (no longer escape as uncaught)
+- `stdio/progress` `formatTime()` — clamps negative milliseconds (no negative ETAs)
+- `dlx/lockfile` — scratch-directory cleanup no longer clobbers the real exception
+- `dlx/package` `parsePackageSpec` — bare trailing `@` (e.g. `"pkg@"`) normalizes to `version: undefined`
 
 ## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
 
 ### Fixed
 
-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.
+- Restored `stdio/prompts`, `stdio/progress`, and `stdio/clear` — accidentally removed in 5.19.0
 
 ## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
 
 ### Added
 
-- `@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
+- `dlx/integrity` — hash verification utilities (`normalizeHash`, `computeHashes`, `verifyHash` with constant-time compare, `DlxHashMismatchError`)
+- `dlx/arborist` — hardened `@npmcli/arborist` wrappers (`safeIdealTree`, `safeReify`, `writeSafeNpmrc`). Locks down audit/fund/scripts/etc. Supports `before?: Date` for release-age enforcement
+- `dlx/lockfile` `generatePackagePin()` — returns `{ name, version, hash, packageJson, lockfile }`. Default `minReleaseDays: 7` refuses versions published in the last week
+- `DlxPackageOptions.hash`, `.lockfile`, `DlxBinaryOptions.hash` — integrity + lockfile options on dlx entry points
 
 ### Fixed
 
-- `pacote` shim — exposes `tarball`, `manifest`, `packument` alongside `extract`. Fixes a latent runtime crash in `fetchPackageManifest` / `fetchPackagePackument` callers
+- `pacote` shim exposes `tarball`, `manifest`, `packument` alongside `extract`
 
 ### 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.)
+- `dist/external/npm-pack.js` 30% smaller; `dist/external/zod.js` 51% smaller (unused code paths stubbed)
 
 ## [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
+- `plugins/` directory + `./plugins/babel-plugin-inline-require-calls` — unused
 
 ## [5.18.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.1) - 2026-04-14
 
 ### Changed
 
-- 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
+- `dist/external/npm-pack` deduplicated via `pnpm overrides` — 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
 
-- `@socketsecurity/lib/dlx` — Socket Firewall API check before package downloads. Resolves the dependency tree and blocks on critical/high severity alerts
+- `dlx` — Socket Firewall API check before package downloads. Resolves the dependency tree and blocks on critical/high alerts
 
 ### Changed
 
-- `@socketsecurity/lib/http-request` — default `User-Agent` updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
+- `http-request` default `User-Agent` is now `socketsecurity-lib/{version}` (was `socket-registry/1.0`)
 
 ## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
 
 ### Added
 
-- `@socketsecurity/lib/paths` `isUnixPath()` — detect MSYS/Git Bash drive-letter notation (`/c/...`)
+- `paths` `isUnixPath()` — detects MSYS/Git Bash drive-letter notation (`/c/...`)
 
 ### Changed
 
-- `@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()`
+- `paths` `normalizePath()` converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `paths` `fromUnixPath()` produces native Windows paths with backslashes (`/c/path` → `C:\path`)
 
 ## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
 
 ### Added
 
-- `@socketsecurity/lib/paths` `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
+- `paths` `fromUnixPath()` — convert MSYS/Git Bash paths back to native Windows format (#168)
 
 ### Fixed
 
-- `@socketsecurity/lib/dlx` `isInSocketDlx` — normalize the dlx directory path for Windows compatibility
+- `dlx` `isInSocketDlx` normalizes the dlx directory path on Windows
 
 ## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
 
 ### Added
 
-- `@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`
+- `http-request` `stream` option — resolves immediately after headers arrive, leaving the body unconsumed for piping
+- `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
 
-- `@socketsecurity/lib/http-request`:
-  - `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled; carries the full `HttpResponse`
+- `http-request`:
+  - `HttpResponseError` — thrown on non-2xx when `throwOnError` is set
   - `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
+  - `onRetry` callback — customize retry per attempt
+  - Streaming body support — `body` accepts `Readable` streams (incl. `form-data`)
+  - `parseRetryAfterHeader()` — RFC 7231 §7.1.3 parser
+  - `sanitizeHeaders()` — redact sensitive headers for logging
 
 ### Changed
 
-- `@socketsecurity/lib/http-request` — `HttpRequestOptions.body` widened to `Buffer | Readable | string`; `onResponse` hook errors no longer leave promises pending
+- `http-request` `HttpRequestOptions.body` widened to `Buffer | Readable | string`; `onResponse` errors no longer leave promises pending
 
 ## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
 
-### Added — http-request
+### Added
 
-- `readIncomingResponse()` — reads and buffers a Node.js `IncomingResponse` into an `HttpResponse` (#143)
-  - Useful for converting raw responses from code that bypasses `httpRequest()` (e.g. multipart form-data uploads) into the standard `HttpResponse` interface
-- `IncomingResponse` type alias — disambiguates `IncomingMessage` as a client-side response
-- `IncomingRequest` type alias — disambiguates `IncomingMessage` as a server-side request
+- `http-request` `readIncomingResponse()` — reads and buffers a Node.js response into an `HttpResponse` (#143)
+- `http-request` `IncomingResponse` / `IncomingRequest` type aliases — disambiguate `IncomingMessage` direction
 
-### Changed — http-request
+### Changed
 
-- Internal `httpRequestAttempt` callbacks now use `IncomingResponse` type
 - `HttpResponse.rawResponse` type narrowed from `IncomingMessage` to `IncomingResponse`
 
 ## [5.12.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.12.0) - 2026-04-04
 
-### Added — http-request
+### Added
 
-- Lifecycle hooks (`onRequest`/`onResponse`) on `HttpRequestOptions` (#133)
-  - Fire per-attempt — retries and redirects each trigger separate hook calls
-  - `HttpHooks`, `HttpHookRequestInfo`, `HttpHookResponseInfo` types exported
-- `maxResponseSize` option to reject responses exceeding a byte limit
-  - Works through redirects, `httpJson`, and `httpText`
-- `rawResponse` property on `HttpResponse` exposing the underlying `IncomingMessage`
-- `enrichErrorMessage()` exported for reusable error enrichment
+- `http-request` lifecycle hooks (`onRequest` / `onResponse`) on `HttpRequestOptions` — fire per-attempt; retries and redirects each trigger separate calls (#133)
+- `http-request` `maxResponseSize` option — reject responses exceeding a byte limit (works through redirects, `httpJson`, `httpText`)
+- `http-request` `HttpResponse.rawResponse` — underlying `IncomingMessage`
+- `http-request` `enrichErrorMessage()` exported
 
-### Changed — http-request
+### Changed
 
-- Error messages now include HTTP method and URL for easier debugging
-- `HttpResponse.headers` type changed from `Record<string, string | string[] | undefined>` to `IncomingHttpHeaders`
+- Error messages now include HTTP method and URL
+- `HttpResponse.headers` type changed to `IncomingHttpHeaders`
 
 ## [5.11.4](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.4) - 2026-03-28
 
-### Changed
+### Performance
 
-- **perf**: Lazy-load heavy external sub-bundles across 7 modules (#119)
-  - `sorts.ts`: Defer semver (2.5 MB via npm-pack) and fastSort until first use
-  - `versions.ts`: Defer semver until first use
-  - `archives.ts`: Defer adm-zip (102 KB) and tar-fs (105 KB) until extraction
-  - `globs.ts`: Defer fast-glob and picomatch (260 KB via pico-pack) until glob execution
-  - `fs.ts`: Defer del (260 KB via pico-pack) until safeDelete call
-  - `spawn.ts`: Defer @npmcli/promise-spawn (17 KB) until async spawn
-  - `strings.ts`: Defer get-east-asian-width (10 KB) until stringWidth call
-- Importing lightweight exports (isObject, httpJson, localeCompare, readJsonSync, stripAnsi) no longer loads heavy externals at module init time
+- Lazy-load heavy external sub-bundles across 7 modules (#119) — `sorts`, `versions`, `archives`, `globs`, `fs`, `spawn`, `strings`. Lightweight imports no longer load heavy externals at init
 
 ## [5.11.3](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.3) - 2026-03-26
 
 ### Fixed
 
-- **build**: Deduplicate shared deps across external bundles (#110)
-- **quality**: Comprehensive quality scan fixes across codebase (#111)
-- **releases**: Add in-memory TTL cache for GitHub API responses
-- **releases**: Guard against missing assets in GitHub release response (#112)
-- **process-lock**: Fix Windows path separator handling for lock directory creation (#112)
+- `releases` — in-memory TTL cache for GitHub API responses; guard against missing assets in release response (#112)
+- `process-lock` — Windows path separator handling for lock directory creation (#112)
 
 ## [5.11.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.2) - 2026-03-24
 
 ### Added
 
-- **http-request**: Custom CA certificate support for TLS connections
-  - `httpRequest`, `httpJson`, `httpText` accept `ca` option for custom certificate authorities
-  - `httpDownload` accepts `ca` option, threaded through redirects and retries
-  - `fetchChecksums` accepts `ca` option, passed through to underlying request
-  - Enables SSL_CERT_FILE support when NODE_EXTRA_CA_CERTS is unavailable at process startup
+- `http-request` — custom CA certificate support (`ca` option on `httpRequest`, `httpJson`, `httpText`, `httpDownload`, `fetchChecksums`). Enables `SSL_CERT_FILE` support when `NODE_EXTRA_CA_CERTS` is unavailable at process startup
 
 ## [5.11.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.1) - 2026-03-24
 
 ### Added
 
-- **dlx/binary**: Added `sha256` option to `dlxBinary()`, `downloadBinary()`, and `downloadBinaryFile()`
-  - Enables SHA-256 checksum verification for binary downloads via httpDownload
-  - Verification happens during download (fails early if checksum mismatches)
-  - Complements existing `integrity` option (SRI sha512 format, verified post-download)
+- `dlx/binary` — `sha256` option on `dlxBinary()`, `downloadBinary()`, `downloadBinaryFile()`. Verification happens during download (fails early on mismatch). Complements the existing `integrity` (SRI sha512) option
 
 ## [5.11.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.11.0) - 2026-03-23
 
 ### Added
 
-- **http-request**: Checksum verification for secure downloads
-  - `parseChecksums(text)`: Parse checksums file text into filename→hash map
-    - Supports GNU style (`hash  filename`), BSD style (`SHA256 (file) = hash`), and single-space format
-    - Handles Windows CRLF and Unix LF line endings
-    - Returns null-prototype object to prevent prototype pollution
-  - `fetchChecksums(url, options?)`: Fetch and parse checksums from URL
-    - Supports `headers` and `timeout` options
-  - `httpDownload` now accepts `sha256` option to verify downloaded files
-    - Verification happens before atomic rename (file not saved if hash mismatches)
-    - Accepts uppercase hashes (normalized to lowercase internally)
+- `http-request` `parseChecksums(text)` — parse GNU / BSD / single-space checksum file formats; CRLF and LF line endings; null-prototype map
+- `http-request` `fetchChecksums(url, options?)` — fetch and parse checksums from URL; supports `headers` and `timeout`
+- `http-request` `httpDownload` `sha256` option — verifies before atomic rename (file not saved on mismatch); accepts uppercase hashes
 
 ## [5.10.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.10.0) - 2026-03-14
 
 ### Changed
 
-- **releases/socket-btm**: Refactored `downloadSocketBtmRelease()` API for caller-controlled download paths
-  - Tool name moved from config object to required first parameter
-  - Config object is now optional second parameter (was required)
-  - Removed automatic `/${toolName}/${platformArch}` directory nesting - callers now have full control over download directory structure
-  - All optional parameters in config types now explicitly typed as `| undefined`
-  - Migration example:
-    - Before: `downloadSocketBtmRelease({ tool: 'lief', downloadDir: 'build' })`
-    - After: `downloadSocketBtmRelease('lief', { downloadDir: 'build' })`
-  - Rationale: Previous automatic path nesting created unexpected directory structures (e.g., `build/downloaded/lief/darwin-arm64/lief/assets/`) making it impossible for callers to predict exact file locations
+- **BREAKING**: `releases/socket-btm` `downloadSocketBtmRelease()` — tool name moved to required first parameter; config object now optional second parameter. Automatic `/${toolName}/${platformArch}` directory nesting removed (callers now control the full path).
+  - Before: `downloadSocketBtmRelease({ tool: 'lief', downloadDir: 'build' })`
+  - After: `downloadSocketBtmRelease('lief', { downloadDir: 'build' })`
 
 ## [5.9.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.9.1) - 2026-03-14
 
 ### Fixed
 
-- **fs**: `safeDelete()` and `safeDeleteSync()` now properly implement retry logic
-  - Previously `maxRetries` was incorrectly passed as `concurrency` to del (parallelism, not retries)
-  - `safeDelete()` now wraps `deleteAsync()` with `pRetry()` for exponential backoff
-  - `safeDeleteSync()` implements sync retry loop with `Atomics.wait()` for non-blocking sleep
-  - Both use `backoffFactor: 2` (delay doubles each retry: 200ms → 400ms → 800ms by default)
-  - `maxRetries` and `retryDelay` options in `RemoveOptions` now work as documented
+- `fs` `safeDelete()` and `safeDeleteSync()` now properly implement retry logic. Previously `maxRetries` was incorrectly passed as `concurrency` to `del`. Both now use exponential backoff (`backoffFactor: 2`); `maxRetries` and `retryDelay` in `RemoveOptions` work as documented
 
 ## [5.9.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.9.0) - 2026-03-14
 
 ### Changed
 
-- **releases/socket-btm**: `getPlatformArch()` now normalizes Windows platform to `win` instead of `win32`
-  - Returns `win-x64`, `win-arm64` instead of `win32-x64`, `win32-arm64`
-  - Consistent with `getBinaryAssetName()` which already uses `win` for Windows assets
-  - Aligns with socket-btm and Node.js convention: use `win` for file/folder names, `win32` for platform checks (`process.platform`)
-  - Added `PLATFORM_MAP` for explicit platform name mapping (darwin, linux, win32 → win)
-  - Now throws `Error: Unsupported platform` for unknown platform values
+- **BREAKING**: `releases/socket-btm` `getPlatformArch()` normalizes Windows to `win` (was `win32`) — returns `win-x64`, `win-arm64`. Throws on unknown platforms. (Reverted in 5.22.0 back to `win32`)
 
 ## [5.8.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.8.2) - 2026-03-13
 
 ### Fixed
 
-- **http-request**: Download to temp file then atomically rename to prevent corruption
-  - Downloads now write to `{destPath}.download` temp file first
-  - On success, atomically renames to the destination path
-  - On failure, cleans up temp file and preserves any existing file at destination
-  - Prevents partial/corrupted files from CI caching causing extraction failures
+- `http-request` — downloads write to `{destPath}.download` temp file then atomically rename. Prevents partial/corrupted files from CI caching causing extraction failures
 
 ## [5.8.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.8.1) - 2026-03-11
 
 ### Performance
 
-- **windows**: Add comprehensive caching for expensive PATH resolution operations
-  - `getBinPath()`, `getBinPathSync()`: Cache binary path lookups
-  - `findRealBin()`: Cache `all:true` lookups and use single `whichSync({ all: true })` call
-  - `getVoltaBinPath()`: Cache Volta binary resolution
-  - `spawn()`: Cache binary path resolution before spawning
-  - `getGitPath()`: Cache git binary path
-  - `getCachedRealpath()`: New helper caching `realpathSync()` calls for git operations
-  - `findGitRoot()`: Cache git root directory lookups
-  - `findPackageJson()`: Cache package.json path lookups
-  - `readPackageJson()`: Cache parsed package.json content
-  - `resolveBinaryPath()`: Cache binary path resolution with Windows extension handling
-  - `NPM_BIN_PATH`, `NPM_REAL_EXEC_PATH`: Share npm path resolution to avoid duplicate `which.sync()` calls
-  - `ProcessLockManager.isStale()`: Use single `statSync({ throwIfNoEntry: false })` instead of `existsSync()` + `statSync()`
-  - All caches validate entries with `existsSync()` and remove stale entries automatically
+- Comprehensive caching for expensive PATH/realpath/git/package.json lookups across `bin`, `spawn`, `git`, `paths`, and `process-lock`. All caches validate entries via `existsSync()` and evict stale ones
 
 ## [5.8.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.8.0) - 2026-03-10
 
 ### Added
 
-- **archives**: Added secure archive extraction utilities with support for ZIP, TAR, TAR.GZ, and TGZ formats
-  - Configurable limits: `maxFileSize` (default 100MB), `maxTotalSize` (default 1GB)
-  - Cross-platform path normalization
-  - External dependencies: adm-zip@0.5.16, tar-fs@3.1.2 (bundled, +212KB)
-  - Security features: path traversal protection, file size limits, total size limits, symlink blocking
-  - Strip option to remove leading path components (like tar `--strip-components`)
-  - `detectArchiveFormat()` - Detect archive type from file extension
-  - `extractArchive()` - Generic extraction with auto-format detection
-  - `extractTar()`, `extractTarGz()`, `extractZip()` - Format-specific extractors
-
-- **releases/github**: Added archive extraction support for GitHub releases
-  - Auto-detects format from asset filename
-  - Enhanced `downloadAndExtractZip()` to use generic archive helpers
-  - Supports ZIP, TAR, TAR.GZ, and TGZ assets
-  - `downloadAndExtractArchive()` - Generic archive download and extraction
+- `archives` — secure archive extraction for ZIP / TAR / TAR.GZ / TGZ. Configurable `maxFileSize` (100MB) and `maxTotalSize` (1GB). Path-traversal protection, symlink blocking, strip option. Exports: `detectArchiveFormat`, `extractArchive`, `extractTar`, `extractTarGz`, `extractZip`
+- `releases/github` `downloadAndExtractArchive()` — generic archive download and extract; auto-detects format
 
 ### Changed
 
-- **dependencies**: Deduplicated 14 external bundle packages to single versions using pnpm overrides and patches
+- 14 external bundle packages deduplicated via pnpm overrides + patches
 
 ## [5.7.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.7.0) - 2026-02-12
 
 ### Added
 
-- **env**: Added `isInEnv()` helper function to check if an environment variable key exists, regardless of its value
-  - Returns `true` even for empty strings, `"false"`, `"0"`, etc.
-  - Follows same override resolution order as `getEnvValue()` (isolated overrides → shared overrides → process.env)
-  - Useful for detecting presence of environment variables independent of their value
-
-- **dlx**: Added new exported helper functions
-  - `downloadBinaryFile()` - Downloads a binary file from a URL to the dlx cache directory
-  - `ensurePackageInstalled()` - Ensures an npm package is installed and cached via Arborist
-  - `getBinaryCacheMetadataPath()` - Gets the file path to dlx binary cache metadata (`.dlx-metadata.json`)
-  - `isBinaryCacheValid()` - Checks if a cached dlx binary is still valid based on TTL and timestamp
-  - `makePackageBinsExecutable()` - Makes npm package binaries executable on Unix systems
-  - `parsePackageSpec()` - Parses npm package spec strings (e.g., `pkg@1.0.0`) into name and version
-  - `resolveBinaryPath()` - Resolves the absolute path to a binary within an installed package
-  - `writeBinaryCacheMetadata()` - Writes dlx binary cache metadata with integrity, size, and source info
-
-- **releases**: Added `createAssetMatcher()` utility function for GitHub release asset pattern matching
-  - Creates matcher functions that test strings against glob patterns, prefix/suffix, or RegExp
-  - Used for dynamic asset discovery in GitHub releases (e.g., matching platform-specific binaries)
+- `env` `isInEnv(key)` — `true` whenever the key exists, regardless of value (empty string, `"false"`, `"0"` all count)
+- `dlx` helpers exposed: `downloadBinaryFile`, `ensurePackageInstalled`, `getBinaryCacheMetadataPath`, `isBinaryCacheValid`, `makePackageBinsExecutable`, `parsePackageSpec`, `resolveBinaryPath`, `writeBinaryCacheMetadata`
+- `releases` `createAssetMatcher()` — matcher fn for glob / prefix-suffix / RegExp asset patterns
 
 ### Changed
 
-- **env**: Updated `getCI()` to use `isInEnv()` for more accurate CI detection
-  - Now returns `true` whenever the `CI` key exists in the environment, not just when truthy
-  - Matches standard CI detection behavior where the presence of the key (not its value) indicates a CI environment
+- `env` `getCI()` now uses `isInEnv('CI')` — `true` whenever the key exists, matching standard CI-detection convention
 
 ### Fixed
 
-- **github**: Fixed JSON parsing crash vulnerability by adding try-catch around `JSON.parse()` in GitHub API responses
-  - Prevents crashes on malformed, incomplete, or binary responses
-  - Error messages now include the response URL for better debugging
-
-- **dlx/binary**: Fixed clock skew vulnerabilities in cache validation
-  - Cache entries with future timestamps (clock skew) are now treated as expired
-  - Metadata writes now use atomic write-then-rename pattern to prevent corruption
-  - Added TOCTOU race protection by re-checking binary existence after metadata read
-
-- **dlx/cache cleanup**: Fixed handling of future timestamps during cache cleanup
-  - Entries with future timestamps (due to clock skew) are now properly treated as expired
-
-- **dlx/package**: Fixed scoped package parsing bug where `@scope/package` was incorrectly parsed
-  - Changed condition from `startsWith('@')` to `atIndex === 0` for more precise detection
-  - Fixes installation failures for scoped packages like `@socketregistry/lib`
-
-- **cache-with-ttl**: Added clock skew detection to TTL cache
-  - Far-future `expiresAt` values (>2x TTL) are now treated as expired
-  - Protects against cache poisoning from clock skew
-
-- **packages/specs**: Fixed unconditional `.git` truncation in Git URL parsing
-  - Now only removes `.git` suffix when URL actually ends with `.git`
-  - Prevents incorrect truncation of URLs containing `.git` in the middle
-
-- **releases/github**: Fixed TOCTOU race condition in binary download verification
-  - Re-checks binary existence after reading version file
-  - Ensures binary is re-downloaded if missing despite version file presence
-
-- **provenance**: Fixed incorrect package name in provenance workflow
-  - Changed from `@socketregistry/lib` to `@socketsecurity/lib`
+- `github` — try/catch around `JSON.parse()` in API responses; error messages include the response URL
+- `dlx/binary` — clock-skew protection (future timestamps treated as expired); atomic metadata write-then-rename; TOCTOU re-check of binary existence after metadata read
+- `dlx/cache` — future-timestamped entries treated as expired during cleanup
+- `dlx/package` — scoped-package parsing uses `atIndex === 0` (was `startsWith('@')`); fixes `@scope/pkg` installation failures
+- `cache-with-ttl` — clock-skew detection (far-future `expiresAt` > 2x TTL treated as expired)
+- `packages/specs` — only strips `.git` when URL actually ends with it (no more mid-URL truncation)
+- `releases/github` — TOCTOU on binary download verification (re-checks after reading version file)
+- `provenance` workflow — corrected package name `@socketregistry/lib` → `@socketsecurity/lib`
 
 ## [5.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.6.0) - 2026-02-08
 
 ### Added
 
-- **http-request**: Added automatic default headers for JSON and text requests
-  - `httpJson()` now automatically sets `Accept: application/json` header
-  - `httpJson()` automatically sets `Content-Type: application/json` when body is present
-  - `httpText()` now automatically sets `Accept: text/plain` header
-  - `httpText()` automatically sets `Content-Type: text/plain` when body is present
-  - User-provided headers always override defaults
-  - Simplifies API usage - no need to manually set common headers
+- `http-request` `httpJson()` / `httpText()` automatically set `Accept` and `Content-Type` headers (when body present); user headers override
 
 ### Changed
 
-- **http-request**: Renamed HTTP helper functions to support all HTTP methods (BREAKING CHANGE)
-  - `httpGetJson()` → `httpJson()` - Now supports GET, POST, PUT, DELETE, PATCH, etc.
-  - `httpGetText()` → `httpText()` - Now supports all HTTP methods via `method` option
-  - Functions now accept `method` parameter in options (defaults to 'GET')
-  - More flexible API that matches modern fetch-style conventions
-  - **Migration**: Replace `httpGetJson()` calls with `httpJson()` and `httpGetText()` with `httpText()`
+- **BREAKING**: `http-request` `httpGetJson()` → `httpJson()` and `httpGetText()` → `httpText()`. Functions now accept `method` (defaults to `'GET'`), supporting all HTTP verbs
 
 ### Fixed
 
-- **http-request**: Fixed Content-Type header incorrectly sent with empty string body
-  - Empty string body (`""`) no longer triggers Content-Type header
-  - Changed condition from `if (body !== undefined)` to `if (body)` for semantic correctness
-  - Empty string represents "no content" and should not declare a Content-Type
-  - Affects `httpJson()` and `httpText()` functions
-  - Fixes potential API compatibility issues with servers expecting no Content-Type for empty bodies
-  - Added comprehensive test coverage for empty string edge case
+- `http-request` — empty-string body no longer triggers `Content-Type`
 
 ## [5.5.3](https://github.com/SocketDev/socket-lib/releases/tag/v5.5.3) - 2026-01-20
 
 ### Fixed
 
-- **deps**: Added patch for execa@2.1.0 to fix signal-exit v4 compatibility. The package was using default import syntax with signal-exit v4, which now exports onExit as a named export.
+- Patched `execa@2.1.0` for `signal-exit` v4 compatibility (named export)
 
 ## [5.5.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.5.2) - 2026-01-20
 
 ### Changed
 
-- **dlx/package**: Use `getSocketCacacheDir()` instead of `getPacoteCachePath()` for Arborist cache configuration
-  - Ensures consistent use of Socket's shared cacache directory (`~/.socket/_cacache`)
-  - Removes dependency on pacote cache path extraction which could fail
-  - Simplifies cache configuration by using reliable Socket path utility
+- `dlx/package` uses `getSocketCacacheDir()` (was `getPacoteCachePath()`) for Arborist cache config — removes dependency on pacote cache-path extraction
 
 ## [5.5.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.5.1) - 2026-01-12
 
 ### Fixed
 
-- Fixed dotenvx compatibility with pre-commit hooks
-- Fixed empty releases being returned when finding latest release
+- dotenvx compatibility with pre-commit hooks
+- Empty releases being returned by latest-release lookup
 
 ## [5.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.5.0) - 2026-01-12
 
 ### Added
 
-- **dlx/detect**: Executable type detection utilities for DLX cache and local file paths
-  - `detectDlxExecutableType()`: Detects Node.js packages vs native binaries in DLX cache by checking for node_modules/ directory
-  - `detectExecutableType()`: Generic entry point that routes to appropriate detection strategy
-  - `detectLocalExecutableType()`: Detects executables on local filesystem by checking package.json bin field or file extension
-  - `isJsFilePath()`: Validates if a file path has .js, .mjs, or .cjs extension
-  - `isNativeBinary()`: Simplified helper that returns true for native binary executables
-  - `isNodePackage()`: Simplified helper that returns true for Node.js packages
+- `dlx/detect` — `detectDlxExecutableType`, `detectExecutableType`, `detectLocalExecutableType`, `isJsFilePath`, `isNativeBinary`, `isNodePackage`. Distinguishes Node packages from native binaries in DLX cache and on local filesystem
 
 ### Fixed
 
-- **releases/github**: Sort releases by published_at to reliably find latest release instead of relying on creation order
+- `releases/github` — sort releases by `published_at` to reliably find latest (was relying on creation order)
 
 ## [5.4.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.4.1) - 2026-01-10
 
 ### Fixed
 
-- **build**: Removed debug module stub to bundle real debug package. The stub was missing `enable()` and `disable()` methods, causing errors when downstream projects re-bundled the lib.
+- Removed `debug` module stub to bundle the real package — stub was missing `enable()` / `disable()`
 
 ## [5.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.4.0) - 2026-01-07
 
 ### Added
 
-- **releases/github**: Extended release functions to accept glob patterns for asset discovery
-  - `getReleaseAssetUrl()` now accepts glob patterns: `'yoga-sync-*.mjs'`, `'models-*.tar.gz'`
-  - `downloadReleaseAsset()` now accepts glob patterns for automatic asset discovery
-  - `getLatestRelease()` now accepts asset patterns to find releases with matching assets
-  - Supports wildcards, brace expansion, RegExp patterns, and prefix/suffix objects
-  - Uses picomatch for robust glob pattern matching
-
-- **releases/socket-btm**: Extended `downloadSocketBtmRelease()` to accept glob patterns
-  - `asset` parameter now accepts wildcards: `'yoga-sync-*.mjs'`, `'models-*.tar.gz'`
-  - Automatically discovers and downloads latest matching asset
-  - Eliminates need for hardcoded asset names in build scripts
+- `releases/github` — `getReleaseAssetUrl()`, `downloadReleaseAsset()`, `getLatestRelease()` accept glob patterns (wildcards, brace expansion, RegExp) via picomatch
+- `releases/socket-btm` `downloadSocketBtmRelease()` — `asset` parameter accepts glob patterns
 
 ## [5.3.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.3.0) - 2026-01-07
 
 ### Added
 
-- **releases/socket-btm**: Exported helper functions for external use
-  - `detectLibc()`: Detect musl vs glibc on Linux systems
-  - `getBinaryAssetName()`: Get GitHub asset name for platform/arch
-  - `getBinaryName()`: Get binary filename with platform-appropriate extension
-  - `getPlatformArch()`: Get platform-arch identifier for directory structure
-
-- **releases/github**: Exported `getAuthHeaders()` for GitHub API authentication
-  - Returns headers with `Accept`, `X-GitHub-Api-Version`, and optional `Authorization`
-  - Checks `GH_TOKEN` and `GITHUB_TOKEN` environment variables
+- `releases/socket-btm` exports: `detectLibc`, `getBinaryAssetName`, `getBinaryName`, `getPlatformArch`
+- `releases/github` exports `getAuthHeaders()` — checks `GH_TOKEN` / `GITHUB_TOKEN`
 
 ## [5.2.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.2.1) - 2026-01-06
 
 ### Fixed
 
-- **releases**: Fixed "Text file busy" errors when executing downloaded binaries
-  - Changed `downloadGitHubRelease()` to use synchronous `chmodSync()` instead of async `chmod()`
-  - Ensures file system operations complete before binary execution
-  - Prevents race conditions in CI/CD environments where async operations may not fully flush to disk
+- `releases` — `downloadGitHubRelease()` uses sync `chmodSync()` to prevent "Text file busy" race in CI
 
 ## [5.2.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.2.0) - 2026-01-06
 
 ### Added
 
-- **releases**: Added GitHub release download utilities for cross-project use
-  - Added `downloadGitHubRelease()` for downloading releases from any GitHub repository
-  - Added `downloadSocketBtmRelease()` specialized wrapper for socket-btm releases
-  - Features version caching with `.version` files to avoid redundant downloads
-  - Supports cross-platform binary downloads (darwin, linux, win32) with automatic platform/arch detection
-  - Includes Linux musl/glibc support with musl as default for broader compatibility
-  - Automatically removes macOS quarantine attributes from downloaded binaries
-  - Supports generic asset downloads (WASM files, models, etc.)
-  - API inspired by industry tools: `brew`, `cargo`, `gh` for intuitive usage
-  - Package exports: `@socketsecurity/lib/releases/github` and `@socketsecurity/lib/releases/socket-btm`
+- `releases/github` — `downloadGitHubRelease()` for any GitHub repo
+- `releases/socket-btm` — `downloadSocketBtmRelease()` wrapper. Version caching via `.version` files; cross-platform with auto platform/arch detection; Linux musl/glibc support; macOS quarantine attribute auto-removal; generic asset downloads (WASM, models)
 
 ## [5.1.4](https://github.com/SocketDev/socket-lib/releases/tag/v5.1.4) - 2025-12-30
 
 ### Fixed
 
-- **dependencies**: Removed unnecessary `http2` module dependency from `@sigstore/sign@4.1.0`
-  - Added pnpm override to force `@sigstore/sign@4.1.0` across all dependencies
-  - Created patch to inline HTTP header and status constants instead of importing `http2` module
-  - Eliminates loading of Node.js `http2` module for HTTP/1.1-only operations
+- Removed unnecessary `http2` module dependency from `@sigstore/sign@4.1.0` via pnpm override + patch — eliminates loading `node:http2` for HTTP/1.1-only operations
 
 ## [5.1.3](https://github.com/SocketDev/socket-lib/releases/tag/v5.1.3) - 2025-12-29
 
 ### Fixed
 
-- **http-request**: Fixed `httpDownload()` to properly handle HTTP redirects (3xx status codes)
-  - Added `followRedirects` option (default: `true`) to enable automatic redirect following
-  - Added `maxRedirects` option (default: `5`) to limit redirect chain length
-  - Now supports downloading from services that use CDN redirects, such as GitHub release assets
-  - Prevents GitHub API quota exhaustion by following `browser_download_url` redirects instead of using API endpoints
-  - Resolves "Request quota exhausted" errors when downloading GitHub release assets
+- `http-request` `httpDownload()` follows 3xx redirects. New `followRedirects` (default `true`) and `maxRedirects` (default `5`) options. Resolves "Request quota exhausted" when downloading GitHub release assets
 
 ## [5.1.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.1.2) - 2025-12-28
 
 ### Fixed
 
-- **paths**: Fixed missing `getPathValue()` caching in `getSocketDlxDir()`
-  - Now uses `getPathValue()` for performance, consistent with `getSocketUserDir()` and `getSocketCacacheDir()`
-  - Adds test override support via `setPath('socket-dlx-dir', ...)`
-  - Test helper `mockHomeDir()` now properly invalidates path cache with `resetPaths()` calls
-  - Resolves cache persistence issues in test environments
+- `paths` — `getSocketDlxDir()` now uses `getPathValue()` caching consistent with the other Socket-dir helpers. Adds test override via `setPath('socket-dlx-dir', ...)`
 
 ## [5.1.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.1.1) - 2025-12-28
 
 ### Added
 
-- **paths**: Added `SOCKET_HOME` environment variable support to customize Socket base directory
-  - `getSocketUserDir()` now checks `SOCKET_HOME` before defaulting to `~/.socket`
-  - `getSocketDlxDir()` inherits `SOCKET_HOME` support (priority: `SOCKET_DLX_DIR` > `SOCKET_HOME/_dlx` > `~/.socket/_dlx`)
-  - Enables flexible directory configuration for restricted or custom environments
+- `paths` `SOCKET_HOME` env var support — customize Socket base directory. Priority: `SOCKET_DLX_DIR` > `SOCKET_HOME/_dlx` > `~/.socket/_dlx`
 
 ### Changed
 
-- **paths**: Enhanced directory resolution with temporary directory fallback
-  - `getUserHomeDir()` now falls back to `os.tmpdir()` when home directory is unavailable
-  - Improves resilience in containerized and restricted environments
-  - Priority order: `HOME` > `USERPROFILE` > `os.homedir()` > `os.tmpdir()`
+- `paths` `getUserHomeDir()` falls back to `os.tmpdir()` when home dir is unavailable. Priority: `HOME` > `USERPROFILE` > `os.homedir()` > `os.tmpdir()`
 
 ## [5.1.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.1.0) - 2025-12-17
 
 ### Added
 
-- **types**: Added `ALPM` and `VSCODE` to `PURL_Type` enum
-  - `ALPM`: Arch Linux Package Manager ecosystem
-  - `VSCODE`: Visual Studio Code extensions ecosystem
+- `types` `PURL_Type` — added `ALPM` (Arch Linux) and `VSCODE` (VS Code extensions)
 
 ## [5.0.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.0.2) - 2025-12-15
 
 ### Changed
 
-- **signal-exit**: `signals()` now auto-initializes its internal state
-  - Commit: [`8cb0576`](https://github.com/SocketDev/socket-lib/commit/8cb0576)
+- `signal-exit` `signals()` auto-initializes its internal state
 
 ## [5.0.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.0.1) - 2025-12-11
 
 ### Added
 
-- **http-request**: Enhanced `httpDownload()` with automatic progress logging via Logger integration
-  - New `logger` option: Pass a Logger instance for automatic progress tracking
-  - New `progressInterval` option: Configure progress reporting frequency (default: 10%)
-  - Progress format: `Progress: XX% (Y.Y MB / Z.Z MB)`
-  - `onProgress` callback takes precedence over `logger` when both are provided
-  - Commit: [`91e5db5`](https://github.com/SocketDev/socket-lib/commit/91e5db5)
+- `http-request` `httpDownload()` automatic progress logging — `logger` option for a Logger instance, `progressInterval` option (default `10%`). `onProgress` callback takes precedence over `logger`
 
 ## [5.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.0.0) - 2025-12-04
 
 ### Added
 
-- **json/edit**: New `EditableJson` base class for generic JSON file manipulation with formatting preservation
-  - Extracted from `EditablePackageJson` to enable code reuse via composition pattern
-  - Supports reading, modifying, and writing JSON files while preserving formatting
-  - Export: `@socketsecurity/lib/json/edit`
-
-- **json/format**: New JSON formatting utilities for consistent JSON manipulation
-  - Functions for analyzing and preserving JSON formatting patterns
-  - Export: `@socketsecurity/lib/json/format`
-
-- **json/parse**: New JSON parsing utilities
-  - `isJsonPrimitive()`: Check if value is a JSON primitive type
-  - `jsonParse()`: Parse JSON with error handling
-  - Export: `@socketsecurity/lib/json/parse`
-
-- **json/types**: New JSON type definitions and interfaces
-  - Export: `@socketsecurity/lib/json/types`
-
-- **dlx/cache**: New DLX cache utilities
-  - `generateCacheKey()`: Generate cache keys for DLX packages
-  - Export: `@socketsecurity/lib/dlx/cache`
-
-- **dlx/dir**: New DLX directory management utilities
-  - `clearDlx()`, `clearDlxSync()`: Clear DLX directory
-  - `dlxDirExists()`, `dlxDirExistsAsync()`: Check if DLX directory exists
-  - `ensureDlxDir()`, `ensureDlxDirSync()`: Ensure DLX directory exists
-  - Export: `@socketsecurity/lib/dlx/dir`
-
-- **dlx/packages**: New DLX package management utilities
-  - `isDlxPackageInstalled()`, `isDlxPackageInstalledAsync()`: Check if package is installed
-  - `listDlxPackages()`, `listDlxPackagesAsync()`: List installed packages
-  - `removeDlxPackage()`, `removeDlxPackageSync()`: Remove installed packages
-  - Export: `@socketsecurity/lib/dlx/packages`
-
-- **dlx/paths**: New DLX path utilities
-  - `getDlxPackageDir()`: Get package directory path
-  - `getDlxInstalledPackageDir()`: Get installed package directory path
-  - `getDlxPackageJsonPath()`: Get package.json path
-  - `getDlxPackageNodeModulesDir()`: Get node_modules directory path
-  - `isInSocketDlx()`: Check if path is in DLX directory
-  - Export: `@socketsecurity/lib/dlx/paths`
+- `json/edit` `EditableJson` — base class for generic JSON file manipulation with formatting preservation
+- `json/format` — JSON formatting utilities
+- `json/parse` — `isJsonPrimitive`, `jsonParse` (with error handling)
+- `json/types` — JSON type definitions
+- `dlx/cache` `generateCacheKey()` — DLX package cache keys
+- `dlx/dir` — `clearDlx`, `clearDlxSync`, `dlxDirExists`, `dlxDirExistsAsync`, `ensureDlxDir`, `ensureDlxDirSync`
+- `dlx/packages` — `isDlxPackageInstalled`, `listDlxPackages`, `removeDlxPackage` (+ async/sync variants)
+- `dlx/paths` — `getDlxPackageDir`, `getDlxInstalledPackageDir`, `getDlxPackageJsonPath`, `getDlxPackageNodeModulesDir`, `isInSocketDlx`
 
 ### Changed
 
-- **BREAKING**: Reorganized module paths for better structure and discoverability
-  - `@socketsecurity/lib/json/editable` → `@socketsecurity/lib/json/edit`
-  - `@socketsecurity/lib/packages/editable` → `@socketsecurity/lib/packages/edit`
-  - `@socketsecurity/lib/maintained-node-versions` → `@socketsecurity/lib/constants/maintained-node-versions`
-  - `@socketsecurity/lib/package-default-node-range` → `@socketsecurity/lib/constants/package-default-node-range`
-  - `@socketsecurity/lib/package-default-socket-categories` → `@socketsecurity/lib/constants/package-default-socket-categories`
-  - `@socketsecurity/lib/lifecycle-script-names` → `@socketsecurity/lib/constants/lifecycle-script-names`
-  - `@socketsecurity/lib/dlx` → Split into `@socketsecurity/lib/dlx/cache`, `@socketsecurity/lib/dlx/dir`, `@socketsecurity/lib/dlx/packages`, `@socketsecurity/lib/dlx/paths`
-  - `@socketsecurity/lib/dlx-binary` → `@socketsecurity/lib/dlx/binary`
-  - `@socketsecurity/lib/dlx-manifest` → `@socketsecurity/lib/dlx/manifest`
-  - `@socketsecurity/lib/dlx-package` → `@socketsecurity/lib/dlx/package`
-
-- **json**: Reorganized JSON utilities into modular submodules (json/edit, json/format, json/parse, json/types)
-  - Removed barrel index file in favor of direct submodule imports
-  - Better separation of concerns and tree-shaking
-
-- **dlx**: Split monolithic DLX module into focused submodules (cache, dir, packages, paths)
-  - Improved modularity and maintainability
-  - Better code organization and discoverability
+- **BREAKING**: Module path reorganization:
+  - `json/editable` → `json/edit`
+  - `packages/editable` → `packages/edit`
+  - `maintained-node-versions`, `package-default-node-range`, `package-default-socket-categories`, `lifecycle-script-names` → moved under `constants/`
+  - `dlx` → split into `dlx/cache`, `dlx/dir`, `dlx/packages`, `dlx/paths`
+  - `dlx-binary` → `dlx/binary`; `dlx-manifest` → `dlx/manifest`; `dlx-package` → `dlx/package`
 
 ## [4.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v4.4.0) - 2025-11-25
 
 ### Added
 
-- **fs**: Exported `normalizeEncoding()` function for robust encoding string normalization
-  - Handles case-insensitive encoding names (e.g., 'UTF-8', 'utf8', 'UTF8')
-  - Supports encoding aliases (e.g., 'binary' → 'latin1', 'ucs-2' → 'utf16le')
-  - Fast-path optimization for common encodings
-  - Defaults to 'utf8' for invalid or null encodings
-  - Export: `@socketsecurity/lib/fs`
+- `fs` `normalizeEncoding()` — case-insensitive encoding normalization with aliases (`binary` → `latin1`, `ucs-2` → `utf16le`); defaults to `utf8`
 
 ### Fixed
 
-- **fs**: `safeReadFile()` and `safeReadFileSync()` type signatures and encoding handling
-  - Corrected type overloads: `encoding: null` → `Buffer | undefined`, no encoding → `string | undefined` (UTF-8 default)
-  - Fixed implementation to properly handle `encoding: null` for Buffer returns
-
-- **suppress-warnings**: `withSuppressedWarnings()` now properly restores warning state
-  - Fixed state restoration to only remove warning types that were added by the function
-  - Prevents accidental removal of warnings that were already suppressed
-  - Ensures correct cleanup behavior when warning types are nested or reused
+- `fs` `safeReadFile` / `safeReadFileSync` — corrected type overloads (`encoding: null` → `Buffer`; no encoding → `string`)
+- `suppress-warnings` `withSuppressedWarnings()` — properly restores state, only removing warnings the function added
 
 ## [4.3.0](https://github.com/SocketDev/socket-lib/releases/tag/v4.3.0) - 2025-11-20
 
 ### Added
 
-- **globs**: New `glob()` and `globSync()` wrapper functions for fast-glob
-  - Provides convenient wrappers around fast-glob with normalized options
-  - Maintains consistent API with existing glob functionality
-  - Export: `@socketsecurity/lib/globs`
+- `globs` `glob()` / `globSync()` — wrapper functions for fast-glob with normalized options
 
 ## [4.1.0](https://github.com/SocketDev/socket-lib/releases/tag/v4.1.0) - 2025-11-17
 
 ### Added
 
-- **constants/node**: New version helper functions for cleaner version detection
-  - `getNodeMinorVersion()`: Extract minor version number
-  - `getNodePatchVersion()`: Extract patch version number
+- `constants/node` — `getNodeMinorVersion()`, `getNodePatchVersion()`
 
 ### Fixed
 
-- **constants/node**: Improve Node.js flag management in `getNodeHardenFlags()`
-  - Properly guard `--experimental-permission` for Node 20-23 only
-  - Properly guard `--permission` for Node 24+ only
-  - Properly guard `--force-node-api-uncaught-exceptions-policy` for Node 22+ (was incorrectly applied to all versions)
-  - Automatically include permission grants from `getNodePermissionFlags()` for Node 24+
-  - Remove `--experimental-policy` flag (no policy file provided)
+- `constants/node` `getNodeHardenFlags()` — `--experimental-permission` guarded for Node 20-23; `--permission` for Node 24+; `--force-node-api-uncaught-exceptions-policy` for Node 22+. Removed `--experimental-policy`
 
 ## [4.0.1](https://github.com/SocketDev/socket-lib/releases/tag/v4.0.1) - 2025-11-17
 
 ### Changed
 
-- Removed # path imports and replaced with relative paths
+- Replaced `#`-path imports with relative paths
 
 ## [4.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v4.0.0) - 2025-11-15
 
 ### Changed
 
-- **paths**: Reorganized path utilities into dedicated `paths/*` submodules for improved modularity
-- **imports**: Converted lazy require() calls to ES6 static imports for better tree-shaking and bundler compatibility
+- **BREAKING**: `paths` reorganized into dedicated `paths/*` submodules
+- Lazy `require()` calls converted to ES6 static imports for better tree-shaking
 
 ## [3.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.5.0) - 2025-11-14
 
 ### Added
 
-- **argv/quote**: New utilities for quoting command-line arguments when using `spawn()` with `shell: true`
-  - `posixQuote(arg)`: Quote arguments for POSIX shells (bash, sh, zsh) using single quotes
-  - `win32Quote(arg)`: Quote arguments for Windows cmd.exe using double quotes
+- `argv/quote` — `posixQuote(arg)` (single-quote for bash/sh/zsh) and `win32Quote(arg)` (double-quote for cmd.exe). Use when invoking `spawn()` with `shell: true`
 
 ## [3.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.4.0) - 2025-11-14
 
 ### Added
 
-- **Spinner**: New `skip()` and `skipAndStop()` methods for displaying skipped operations
-  - `skip(text)`: Display skip message alongside spinner (e.g., "Skipping optional step...")
-  - `skipAndStop(text)`: Display skip message and stop spinner in one call
-  - Uses cyan ↻ (refresh/reload) symbol with @ ASCII fallback
-  - Normalizes text formatting consistently with other spinner methods
-  - Useful for communicating skipped steps during long-running operations
-
-- **Logger**: New `skip()` method and symbol for skipped operations
-  - `LOG_SYMBOLS.skip`: New cyan ↻ symbol for skip output (@ ASCII fallback)
-  - `skip(message)`: Display skip messages with dedicated symbol
-  - Complements existing info/step/success/error/warning/reason methods
+- `Spinner` `skip(text)` / `skipAndStop(text)` — display skip messages with cyan ↻ symbol
+- `Logger` `skip(message)` and `LOG_SYMBOLS.skip`
 
 ## [3.3.11](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.11) - 2025-11-14
 
 ### Fixed
 
-- **prompts**: Fix "inquirerPrompt is not a function" error in interactive prompts
-  - Properly handle inquirer modules with multiple exports (select, search)
+- `prompts` — "inquirerPrompt is not a function" when inquirer modules expose multiple exports (select, search)
 
 ## [3.3.10](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.10) - 2025-11-14
 
 ### Fixed
 
-- **deps**: Add string-width and wrap-ansi overrides for bundling compatibility
-  - Forces string-width@8.1.0 and wrap-ansi@9.0.2 for compatibility with strip-ansi@7.1.2
+- `string-width@8.1.0` and `wrap-ansi@9.0.2` overrides for `strip-ansi@7.1.2` compatibility
 
 ## [3.3.9](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.9) - 2025-11-14
 
 ### Fixed
 
-- **deps**: Add strip-ansi override to fix bundling compatibility
-  - Forces strip-ansi@7.1.2 for compatibility with ansi-regex@6.2.2
+- `strip-ansi@7.1.2` override for `ansi-regex@6.2.2` compatibility
 
 ## [3.3.8](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.8) - 2025-11-14
 
 ### Fixed
 
-- **spinner**: Clear remaining artifacts after withSpinner stops
-  - Fixed rogue spinner characters persisting after spinner completes
+- `spinner` — clear remaining artifacts after `withSpinner` stops (rogue spinner characters)
 
 ## [3.3.7](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.7) - 2025-11-13
 
 ### Changed
 
-- **refactor**: Add explicit `.js` extensions to external require calls
-  - Improves module resolution clarity and compatibility with modern bundlers
-  - Updated 18 require calls across 10 source files
+- Explicit `.js` extensions on external `require()` calls for modern bundler compat
 
 ## [3.3.6](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.6) - 2025-11-13
 
 ### Changed
 
-- **deps**: Add pnpm overrides to consolidate package versions
-  - Force single versions: `@npmcli/arborist@9.1.6`, `@npmcli/run-script@10.0.0`, `semver@7.7.2`, `ansi-regex@6.2.2`, `lru-cache@11.2.2`
-  - Update patch from `@npmcli/run-script@9.1.0` to `@npmcli/run-script@10.0.0`
-  - Reduces duplicate dependencies and potential version conflicts
+- pnpm overrides consolidate `@npmcli/arborist@9.1.6`, `@npmcli/run-script@10.0.0`, `semver@7.7.2`, `ansi-regex@6.2.2`, `lru-cache@11.2.2` to single versions
 
 ## [3.3.5](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.5) - 2025-11-13
 
 ### Fixed
 
-- **build**: Add patches to prevent node-gyp bundling issues
+- Patches to prevent `node-gyp` bundling issues
 
 ## [3.3.4](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.4) - 2025-11-13
 
 ### Fixed
 
-- **build**: Mark node-gyp as external in npm-pack bundle
+- `node-gyp` marked external in `npm-pack` bundle
 
 ## [3.3.3](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.3) - 2025-11-13
 
 ### Fixed
 
-- **build**: Break node-gyp string to prevent bundler issues with ESM/CJS interop
+- `node-gyp` string broken to prevent bundler ESM/CJS interop issues
 
 ## [3.3.2](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.2) - 2025-11-13
 
 ### Changed
 
-- **dlx**: Install package dependencies after download
-- **external**: Optimize npm package bundle sizes (~3MB reduction)
+- `dlx` installs package dependencies after download
+- npm package bundle sizes reduced ~3 MB
 
 ## [3.3.1](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.1) - 2025-11-11
 
 ### Added
 
-- Added `SOCKET_DOCS_CONTACT_URL` constant for documentation contact support page
-- Added `checkbox` prompt support
+- `SOCKET_DOCS_CONTACT_URL` constant
+- `checkbox` prompt support
 
 ## [3.3.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.3.0) - 2025-11-07
 
 ### Added
 
-- **Spinner**: New `reason()` and `reasonAndStop()` methods for displaying working/thinking output
-  - `reason(text)`: Display reason text alongside spinner (e.g., "Analyzing dependencies...")
-  - `reasonAndStop(text)`: Display reason text and stop spinner in one call
-  - Normalizes text formatting consistently with other spinner methods
-  - Useful for communicating progress steps during long-running operations
-
-- **Logger**: New `reason()` method and symbol for working/thinking output
-  - `LOG_SYMBOLS.reason`: New symbol for reason output (distinct from info/step symbols)
-  - `reason(message)`: Display reason messages with dedicated symbol
-  - Complements existing info/step/success/error/warning methods
+- `Spinner` `reason(text)` / `reasonAndStop(text)` — display working/thinking output
+- `Logger` `reason(message)` and `LOG_SYMBOLS.reason`
 
 ## [3.2.8](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.8) - 2025-11-05
 
 ### Fixed
 
-- **build**: Fix CommonJS export script edge cases
-  - Fixed stray semicolons after comment placeholders in transformed modules
-  - Fixed incorrect transformation of `module.exports.default` to `module.module.exports`
-  - Ensures external dependencies and default exports work correctly
+- CommonJS export script edge cases (stray semicolons after comment placeholders; incorrect `module.exports.default` → `module.module.exports`)
 
 ## [3.2.7](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.7) - 2025-11-05
 
 ### Fixed
 
-- **build-externals**: Disable minification to preserve exports
-  - External dependencies are no longer minified during bundling
-  - Prevents export name mangling that breaks CommonJS interop
-  - Fixes `semver.parse()` and `semver.major()` being undefined
-
-- **build**: Fix CommonJS export interop for TypeScript default exports
-  - Modules with `export default` now work without requiring `.default` accessor
-
-### Changed
-
-- **docs**: Moved packages README to correct location (`src/packages/README.md`)
+- External dependency minification disabled to preserve exports (was breaking `semver.parse()`, `semver.major()`)
+- CommonJS export interop for TypeScript `export default` no longer needs `.default` accessor
 
 ## [3.2.6](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.6) - 2025-11-05
 
 ### Fixed
 
-- **logger**: Replace yoctocolors-cjs rgb() with manual ANSI codes
-  - The yoctocolors-cjs package doesn't have an rgb() method
-  - Manually construct ANSI escape sequences for RGB colors (ESC[38;2;r;g;bm...ESC[39m)
-  - Affects `src/logger.ts` and `src/stdio/prompts.ts` applyColor() functions
+- `logger` and `stdio/prompts` — manual ANSI escape sequences for RGB colors (yoctocolors-cjs has no `rgb()` method)
 
 ## [3.2.5](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.5) - 2025-11-05
 
 ### Added
 
-- **scripts**: Add path alias resolution script (`fix-path-aliases.mjs`)
-  - Resolves internal path aliases (`#lib/*`, `#constants/*`, etc.) to relative paths in built CommonJS files
-
-- **build**: Integrate path alias resolution into build pipeline
-  - Add path alias plugin to esbuild config
-  - Integrate `fix-path-aliases.mjs` into build process
-  - Ensures path aliases work correctly in compiled CommonJS output
+- Path alias resolution in build pipeline — `#lib/*` / `#constants/*` aliases resolve to relative paths in compiled CommonJS
 
 ## [3.2.4](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.4) - 2025-11-04
 
 ### Added
 
-- **Logger**: New `time()` method for timing operations with automatic duration reporting
-  - Starts a named timer and returns a `stop()` function
-  - Automatically logs completion with formatted duration (e.g., "Operation completed in 1.23s")
-  - Useful for performance monitoring and debugging
+- `Logger` `time()` — start a named timer; returns `stop()` that logs completion with formatted duration
 
 ### Fixed
 
-- **Spinner effects**: Fixed star spinner frames by adding trailing space for consistent spacing
-- **Build system**: Fixed external dependency bundling issues
-  - Bundle `@npmcli/package-json` with subpath exports support
-  - Use `src/external` files as bundle entry points for proper module resolution
-  - Bundle libnpmexec from npm instead of using vendored version
-  - Prevent circular dependencies with `createForceNodeModulesPlugin()` to force resolution from node_modules
-
-## [3.2.3](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.3) - 2025-11-03
-
-### Internal
-
-- **Build system**: Added stub infrastructure for external dependency bundling
-  - Created organized `scripts/build-externals/stubs/` directory with utility and active stubs
-  - Added conservative stubs for unused dependencies: `encoding`/`iconv-lite` and `debug`
-  - Reduces external bundle size by ~18KB (9KB from encoding stubs, 9KB from debug stubs)
+- Star spinner frames — added trailing space for consistent spacing
 
 ## [3.2.2](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.2) - 2025-11-03
 
 ### Added
 
-- **DLX**: Binary permission management with chmod 0o755 for all package binaries
-  - New `makePackageBinsExecutable()` function ensures all binaries in installed packages are executable
-  - Aligns with npm's cmd-shim approach for binary permissions
-  - Handles both single and multiple binary packages
-  - No-op on Windows (permissions not needed)
-
-- **DLX**: npm-compatible bin resolution via vendored `getBinFromManifest`
-  - Cherry-picked `getBinFromManifest` from libnpmexec@10.1.8 (~1.5 KB)
-  - Avoids 1.1 MB bundle by vendoring single function instead of full package
-  - Provides battle-tested npm bin resolution strategy
-  - Maintains user-friendly fallbacks for edge cases
-
-### Changed
-
-- **DLX**: Enhanced `findBinaryPath()` with npm's resolution strategy
-  - Primary: npm's `getBinFromManifest` (handles standard cases and aliases)
-  - Fallback: user-provided `binaryName` parameter
-  - Fallback: last segment of package name
-  - Last resort: first binary in list
+- `dlx` `makePackageBinsExecutable()` — chmod 0o755 on all package binaries (no-op on Windows)
+- `dlx` `findBinaryPath()` adopts npm's resolution strategy (vendored `getBinFromManifest` from libnpmexec)
 
 ### Performance
 
-- **Optimized package size**: Reduced bundle size through strategic export minimization and vendoring
-  - Vendored `getBinFromManifest` function instead of bundling full libnpmexec (~1.1 MB savings)
-  - Minimized external module exports for better tree-shaking:
-    - `fast-sort`: Now exports only `{ createNewSortInstance }` (2.1 KB, 96% reduction from ~56 KB)
-    - `fast-glob`: Now exports only `{ globStream }` (82 KB bundle)
-    - `del`: Now exports only `{ deleteAsync, deleteSync }` (100 KB bundle)
-    - `streaming-iterables`: Now exports only `{ parallelMap, transform }` (11 KB, 93% reduction from ~168 KB)
-  - Total savings: ~1.3 MB (1.1 MB from vendoring + 211 KB from minimized exports)
-  - Establishes pattern for future external module additions
+- Bundle size reduced ~1.3 MB total — vendored `getBinFromManifest` (1.1 MB savings) + minimized exports for `fast-sort`, `fast-glob`, `del`, `streaming-iterables`
 
 ## [3.2.1](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.1) - 2025-11-02
 
 ### Changed
 
-- **Logger/Spinner**: Use module-level constants to prevent duplicate and rogue spinner indicators
-  - Call `getDefaultLogger()` and `getDefaultSpinner()` once at module scope instead of repeated calls
-  - Prevents multiple spinner instances that can cause duplicate or lingering indicators in terminal output
-  - Applied in `src/dlx-manifest.ts`, `src/stdio/mask.ts`, and `src/spinner.ts`
-  - Follows DRY principle and aligns with socket-registry/socket-sdk-js patterns
-
-### Fixed
-
-- **Scripts**: Fixed undefined logger variable in update script
-  - Replaced undefined `log` references with `_logger` throughout `scripts/update.mjs`
-  - Resolves ESLint errors that blocked test execution
-- **Tests**: Improved stdout test stability by checking call delta instead of absolute counts
-  - Fixed flaky CI failures where spy call count was 101 instead of expected 100
-  - More robust approach handles potential state leakage between tests
-- **Tests**: Removed unnecessary 10ms delay in cache-with-ttl test
-  - Cache with memoization enabled updates in-memory storage synchronously
-  - Delay was insufficient in CI and unnecessary given synchronous behavior
-  - Resolves flaky CI failures where cached values returned undefined
+- `Logger` / `Spinner` — call `getDefaultLogger()` / `getDefaultSpinner()` once at module scope to prevent duplicate spinner indicators
 
 ## [3.2.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.2.0) - 2025-11-02
 
 ### Added
 
-- **DLX**: Unified manifest for packages and binaries
-  - Centralized manifest system for tracking DLX-compatible packages
-  - Simplifies package and binary lookups for dependency-free execution
+- `dlx` — unified manifest for packages and binaries
 
 ## [3.1.3](https://github.com/SocketDev/socket-lib/releases/tag/v3.1.3) - 2025-11-02
 
 ### Changed
 
-- **Dependencies**: Updated `@socketregistry/packageurl-js` to 1.3.5
+- `@socketregistry/packageurl-js` updated to 1.3.5
 
 ## [3.1.2](https://github.com/SocketDev/socket-lib/releases/tag/v3.1.2) - 2025-11-02
 
 ### Fixed
 
-- **External dependencies**: Fixed incorrectly marked external dependencies to use wrapper pattern
-  - Updated `src/constants/agents.ts` to use `require('../external/which')` instead of direct imports
-  - Updated `src/zod.ts` to export from `./external/zod'` instead of direct imports
-  - Maintains zero dependencies policy by ensuring all runtime dependencies go through the external wrapper pattern
-- **Spinner**: Fixed undefined properties in setShimmer by handling defaults correctly
+- `Spinner` `setShimmer` — handle undefined properties via defaults
+- External deps now go through the wrapper pattern (`require('../external/which')`, etc.) — maintains zero-deps policy
 
 ## [3.1.1](https://github.com/SocketDev/socket-lib/releases/tag/v3.1.1) - 2025-11-02
 
 ### Fixed
 
-- **Cache TTL**: Fixed flaky test by handling persistent cache write failures gracefully
-  - Wrapped `cacache.put` in try/catch to prevent failures when persistent cache writes fail or are slow
-  - In-memory cache is updated synchronously before the persistent write, so immediate reads succeed regardless of persistent cache state
-  - Improves reliability in test environments and when cache directory has issues
+- `cache-with-ttl` — `cacache.put` wrapped in try/catch so persistent-cache write failures don't break in-memory reads
 
 ## [3.1.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.1.0) - 2025-11-01
 
 ### Changed
 
-- **File system utilities**: `safeMkdir` and `safeMkdirSync` now default to `recursive: true`
-  - Nested directories are created by default, simplifying common usage patterns
+- `fs` `safeMkdir` / `safeMkdirSync` default to `recursive: true`
 
 ## [3.0.6](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.6) - 2025-11-01
 
 ### Added
 
-- **Build validation**: Added guard against `link:` protocol dependencies in package.json
-  - New `validate-no-link-deps.mjs` script automatically runs during `pnpm run check`
-  - Prevents accidental publication with `link:` dependencies which can cause issues
-  - Recommends using `workspace:` for monorepos or `catalog:` for centralized version management
-  - Validates all dependency fields: dependencies, devDependencies, peerDependencies, optionalDependencies
+- Build validation — guard against `link:` protocol dependencies in `package.json` (`validate-no-link-deps.mjs` runs during `pnpm run check`)
 
 ### Changed
 
-- **Dependencies**: Updated `@socketregistry/packageurl-js` to 1.3.3
-- **Git hooks**: Committed pre-commit and pre-push hook configurations for version control
-- **Scripts**: Removed shebang from `validate-no-link-deps` script (Node.js script, not shell)
+- `@socketregistry/packageurl-js` updated to 1.3.3
 
 ## [3.0.5](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.5) - 2025-11-01
 
 ### Fixed
 
-- **Critical: Prompts API breaking changes**: Restored working prompts implementation that was accidentally replaced with non-functional stub in v3.0.0
-  - Consolidated all prompts functionality into `src/stdio/prompts.ts`
-  - Removed unimplemented stub from `src/prompts/` that was throwing "not yet implemented" errors
-  - Removed `./prompts` package export (use `@socketsecurity/lib/stdio/prompts` instead)
-  - Restored missing exports: `password`, `search`, `Separator`, and added `createSeparator()` helper
-  - Fixed `Choice` type to use correct `name` property (matching `@inquirer` API, not erroneous `label`)
+- **Critical**: prompts API restored — non-functional stub from v3.0.0 replaced with working implementation. `@socketsecurity/lib/stdio/prompts` exports `password`, `search`, `Separator`, `createSeparator()`. `Choice.name` (was erroneously `label`)
 
 ### Added
 
-- **Theme integration for prompts**: Prompts now automatically use the active theme colors
-  - Prompt messages styled with `colors.prompt`
-  - Descriptions and disabled items styled with `colors.textDim`
-  - Answers and highlights styled with `colors.primary`
-  - Error messages styled with `colors.error`
-  - Success indicators styled with `colors.success`
-  - Exported `createInquirerTheme()` function for converting Socket themes to @inquirer format
-  - Consistent visual experience with Logger and Spinner theme integration
-
-- **Theme parameter support**: Logger, Prompts, and text effects now accept optional `theme` parameter
-  - Pass theme names (`'socket'`, `'sunset'`, `'terracotta'`, `'lush'`, `'ultra'`) or Theme objects
-  - **Logger**: `new Logger({ theme: 'sunset' })` - uses theme-specific symbol colors
-  - **Prompts**: `await input({ message: 'Name:', theme: 'ultra' })` - uses theme for prompt styling
-  - **Text effects**: `applyShimmer(text, state, { theme: 'terracotta' })` - uses theme for shimmer colors
-  - Instance-specific themes override global theme context when provided
-  - Falls back to global theme context when no instance theme specified
-  - **Note**: Spinner already had theme parameter support in v3.0.0
+- Prompts adopt the active theme (`colors.prompt`, `textDim`, `primary`, `error`, `success`); `createInquirerTheme()` exported
+- Theme parameter support — `Logger`, prompts, and text effects accept `theme: 'socket' | 'sunset' | 'terracotta' | 'lush' | 'ultra'` (or a Theme object)
 
 ### Removed
 
-- **Unused index entrypoint**: Removed `src/index.ts` and package exports for `"."` and `"./index"`
-  - This was a leftover from socket-registry and not needed for this library
-  - Users should import specific modules directly (e.g., `@socketsecurity/lib/logger`)
-  - Breaking: `import { getDefaultLogger } from '@socketsecurity/lib'` no longer works
-  - Use: `import { getDefaultLogger } from '@socketsecurity/lib/logger'` instead
+- **BREAKING**: `src/index.ts` deleted; main index `"."` / `"./index"` exports gone. Import specific modules: `@socketsecurity/lib/logger` instead of `@socketsecurity/lib`
 
 ## [3.0.4](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.4) - 2025-11-01
 
 ### Changed
 
-- **Sunset theme**: Updated colors from azure blue to warm orange/purple gradient matching Coana branding
-- **Terracotta theme**: Renamed from `brick` to `terracotta` for better clarity
+- Sunset theme — azure blue → warm orange/purple gradient (Coana branding)
+- `brick` theme renamed to `terracotta`
 
 ## [3.0.3](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.3) - 2025-11-01
 
 ### Fixed
 
-- **Critical: Node.js ESM/CJS interop completely fixed**: Disabled minification to ensure proper ESM named import detection
-  - Root cause: esbuild minification was breaking Node.js ESM's CJS named export detection
-  - Solution: Disabled minification entirely (`minify: false` in esbuild config)
-  - Libraries should not be minified - consumers minify during their own build process
-  - Unminified esbuild output uses clear `__export` patterns that Node.js ESM natively understands
-  - Removed `fix-commonjs-exports.mjs` build script - no longer needed with unminified code
-  - ESM imports now work reliably: `import { getDefaultLogger } from '@socketsecurity/lib/logger'`
-  - Verified with real-world ESM module testing (`.mjs` files importing from CJS `.js` dist)
+- **Critical**: Node.js ESM/CJS interop — disabled esbuild minification (was breaking ESM named-import detection from CJS dist). ESM imports now work reliably
 
 ## [3.0.2](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.2) - 2025-11-01
 
 ### Fixed
 
-- **Critical: Node.js ESM named imports from CommonJS**: Fixed build output to ensure Node.js ESM can properly detect named exports from CommonJS modules
-  - Previously, esbuild's minified export pattern placed `module.exports` before variable definitions, causing "Cannot access before initialization" errors
-  - Build script now uses `@babel/parser` + `magic-string` for safe AST parsing and transformation
-  - Exports are now correctly placed at end of files after all variable definitions
-  - Enables proper ESM named imports: `import { getDefaultLogger, Logger } from '@socketsecurity/lib/logger'`
-  - Fixes socket-cli issue where named imports were failing with obscure initialization errors
+- **Critical**: Node.js ESM named imports from CommonJS — `module.exports` placed before variable defs caused "Cannot access before initialization". Build now uses `@babel/parser` + `magic-string` to position exports at end of file
 
 ## [3.0.1](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.1) - 2025-11-01
 
 ### Added
 
-- **Convenience exports from main index**: Added logger and spinner exports to ease v2→v3 migration
-  - Logger: `getDefaultLogger()`, `Logger`, `LOG_SYMBOLS` now available from `@socketsecurity/lib`
-  - Spinner: `getDefaultSpinner()`, `Spinner` now available from `@socketsecurity/lib`
-  - Both main index (`@socketsecurity/lib`) and subpath (`@socketsecurity/lib/logger`, `@socketsecurity/lib/spinner`) imports now work
-  - Both import paths return the same singleton instances
+- Convenience re-exports of `getDefaultLogger`, `Logger`, `LOG_SYMBOLS`, `getDefaultSpinner`, `Spinner` from main index for v2→v3 migration
 
 ### Fixed
 
-- **Critical: Spinner crashes when calling logger**: Fixed spinner internal calls to use `getDefaultLogger()` instead of removed `logger` export
-  - Spinner methods (`start()`, `stop()`, `success()`, `fail()`, etc.) no longer crash with "logger is not defined" errors
-  - All 5 internal logger access points updated to use the correct v3 API
-  - Resolves runtime errors when using spinners with hoisted variables
-
-### Changed
-
-- **Migration path improvement**: Users can now import logger/spinner from either main index or subpaths, reducing breaking change impact from v3.0.0
+- **Critical**: Spinner internal calls to removed `logger` export — use `getDefaultLogger()` (5 call sites)
 
 ## [3.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v3.0.0) - 2025-11-01
 
 ### Added
 
-- Theme system with 5 built-in themes: `socket`, `sunset`, `terracotta`, `lush`, `ultra`
-- `setTheme()`, `getTheme()`, `withTheme()`, `withThemeSync()` for theme management
-- `createTheme()`, `extendTheme()`, `resolveColor()` helper functions
-- `onThemeChange()` event listener for theme reactivity
-- `link()` function for themed terminal hyperlinks in `@socketsecurity/lib/links`
-- Logger and spinner now inherit theme colors automatically
-- Spinner methods: `enableShimmer()`, `disableShimmer()`, `setShimmer()`, `updateShimmer()`
-- DLX cross-platform binary resolution (`.cmd`, `.bat`, `.ps1` on Windows)
-- DLX programmatic options aligned with CLI conventions (`force`, `quiet`, `package`)
+- Theme system — 5 built-in themes (`socket`, `sunset`, `terracotta`, `lush`, `ultra`); `setTheme`, `getTheme`, `withTheme`, `withThemeSync`, `createTheme`, `extendTheme`, `resolveColor`, `onThemeChange`
+- `links` `link()` — themed terminal hyperlinks
+- Logger and spinner inherit theme colors
+- Spinner methods: `enableShimmer`, `disableShimmer`, `setShimmer`, `updateShimmer`
+- `dlx` cross-platform binary resolution (`.cmd`, `.bat`, `.ps1` on Windows)
 
 ### Changed
 
-- Theme context uses AsyncLocalStorage instead of manual stack management
-- Promise retry options renamed: `factor` → `backoffFactor`, `minTimeout` → `baseDelayMs`, `maxTimeout` → `maxDelayMs`
+- Theme context uses `AsyncLocalStorage` instead of manual stack
+- **BREAKING**: Promise retry options renamed — `factor` → `backoffFactor`, `minTimeout` → `baseDelayMs`, `maxTimeout` → `maxDelayMs`
 
 ### Removed
 
-**BREAKING CHANGES:**
-
-- `pushTheme()` and `popTheme()` - use `withTheme()` or `withThemeSync()` instead
-- `logger` export - use `getDefaultLogger()` instead
-- `spinner` export - use `getDefaultSpinner()` instead
-- `download-lock.ts` - use `process-lock.ts` instead
+- **BREAKING**: `pushTheme()` / `popTheme()` — use `withTheme()` / `withThemeSync()`
+- **BREAKING**: `logger` / `spinner` exports — use `getDefaultLogger()` / `getDefaultSpinner()`
+- **BREAKING**: `download-lock.ts` — use `process-lock.ts`
 - Promise option aliases: `factor`, `minTimeout`, `maxTimeout`
 
----
-
-# Changelog
-
-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).
-
 ## [2.10.3](https://github.com/SocketDev/socket-lib/releases/tag/v2.10.3) - 2025-10-31
 
 ### Fixed
 
-- Updated `@socketregistry/packageurl-js` to 1.3.1 to resolve an unintended external dependency
-- **Documentation**: Corrected JSDoc `@example` import paths from `@socketsecurity/registry` to `@socketsecurity/lib` across utility modules
-  - Updated examples in `memoization.ts`, `performance.ts`, `spinner.ts`, `suppress-warnings.ts`, and `tables.ts`
-  - Ensures documentation reflects correct package name after v1.0.0 rename
+- `@socketregistry/packageurl-js` updated to 1.3.1 (resolves unintended external dep)
+- JSDoc `@example` import paths corrected after v1.0.0 rename (`@socketsecurity/registry` → `@socketsecurity/lib`)
 
 ## [2.10.2](https://github.com/SocketDev/socket-lib/releases/tag/v2.10.2) - 2025-10-31
 
 ### Changed
 
-- **Package spec parsing**: Refactored to use official `npm-package-arg` library for robust handling of all npm package specification formats (versions, ranges, tags, git URLs)
-  - Improves reliability when parsing complex package specs
-  - Better handles edge cases in version ranges and scoped packages
-  - Falls back to simple parsing if npm-package-arg fails
+- Package spec parsing uses official `npm-package-arg` library for full npm spec support (versions, ranges, tags, git URLs); falls back to simple parsing if it fails
 
 ### Fixed
 
-- **Scoped package version parsing**: Fixed critical bug where parsePackageSpec was stripping the `@` prefix from scoped packages with versions
-  - Example: `@coana-tech/cli@~14.12.51` was incorrectly parsed as `coana-tech/cli@~14.12.51`
-  - Caused package installation failures for scoped packages in DLX system
+- **Critical**: `parsePackageSpec` no longer strips the `@` prefix from scoped+versioned specs (e.g., `@coana-tech/cli@~14.12.51`)
 
 ## [2.10.1](https://github.com/SocketDev/socket-lib/releases/tag/v2.10.1) - 2025-10-31
 
 ### Fixed
 
-- **Process lock directory creation**: Use recursive mkdir to ensure parent directories exist when creating lock directory
-- **Node.js debug flags**: Remove buggy `getNodeDebugFlags()` function that returned debug flags without required argument values
+- Process lock — recursive mkdir for parent dirs
+- Removed buggy `getNodeDebugFlags()` (returned flags without required argument values)
 
 ## [2.10.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.10.0) - 2025-10-30
 
 ### Added
 
-- **Unified DLX metadata schema**: Standardized `.dlx-metadata.json` format across TypeScript and C++ implementations
-  - Exported `DlxMetadata` interface as canonical schema reference
-  - Core fields: `version`, `cache_key`, `timestamp`, `checksum`, `checksum_algorithm`, `platform`, `arch`, `size`, `source`
-  - Support for `source` tracking (download vs decompression origin)
-  - Reserved `extra` field for implementation-specific data
-  - Comprehensive documentation with examples for both download and decompression use cases
+- Unified `.dlx-metadata.json` schema — `DlxMetadata` interface exported. Fields: `version`, `cache_key`, `timestamp`, `checksum`, `checksum_algorithm`, `platform`, `arch`, `size`, `source` (`{ type, url }`); reserved `extra` for impl-specific data
 
 ### Changed
 
-- **DLX binary metadata structure**: Updated `writeBinaryCacheMetadata()` to use unified schema with additional fields
-  - Now includes `cache_key` (first 16 chars of SHA-512 hash)
-  - Added `size` field for cached binary size
-  - Added `checksum_algorithm` field (currently "sha256")
-  - Restructured to use `source.type` and `source.url` for origin tracking
-  - Maintains backward compatibility in `listDlxCache()` reader
+- `dlx` `writeBinaryCacheMetadata()` adopts the unified schema (`cache_key` = SHA-512 prefix, `size`, `checksum_algorithm`, `source.type`/`source.url`)
 
 ## [2.9.1](https://github.com/SocketDev/socket-lib/releases/tag/v2.9.1) - 2025-10-30
 
 ### Added
 
-- **Smart binary detection in dlxPackage**: Automatically finds the correct binary even when package name doesn't match binary name
-  - If package has single binary, uses it automatically regardless of name
-  - Resolves packages like `@socketsecurity/cli` (binary: `socket`) without manual configuration
-  - Falls back to intelligent name matching for multi-binary packages
-- **Optional binaryName parameter**: Added `binaryName` option to `DlxPackageOptions` for explicit binary selection when auto-detection isn't sufficient
+- `dlxPackage` smart binary detection — uses single-binary packages directly regardless of name. Optional `binaryName` for explicit selection on multi-binary packages
 
 ### Fixed
 
-- **Binary resolution for scoped packages**: Fixed issue where `dlxPackage` couldn't find binaries when package name didn't match binary name (e.g., `@socketsecurity/cli` with `bin: { socket: '...' }`)
+- Binary resolution for scoped packages where package name ≠ binary name (e.g., `@socketsecurity/cli` exposes `bin: { socket: '...' }`)
 
 ## [2.9.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.9.0) - 2025-10-30
 
 ### Added
 
-- **Socket.dev URL constants**: Added centralized URL constants for Socket.dev services
-  - `SOCKET_WEBSITE_URL`: Main Socket.dev website
-  - `SOCKET_CONTACT_URL`: Contact page
-  - `SOCKET_DASHBOARD_URL`: Dashboard homepage
-  - `SOCKET_API_TOKENS_URL`: API tokens settings page
-  - `SOCKET_PRICING_URL`: Pricing information
-  - `SOCKET_STATUS_URL`: Service status page
-  - `SOCKET_DOCS_URL`: Documentation site
-  - Available via `@socketsecurity/lib/constants/socket`
+- `constants/socket` URL constants — `SOCKET_WEBSITE_URL`, `SOCKET_CONTACT_URL`, `SOCKET_DASHBOARD_URL`, `SOCKET_API_TOKENS_URL`, `SOCKET_PRICING_URL`, `SOCKET_STATUS_URL`, `SOCKET_DOCS_URL`
 
 ### Changed
 
-- **Enhanced error messages across library**: Comprehensive audit and improvement of error handling
-  - Added actionable error messages with resolution steps throughout modules
-  - Improved file system operation errors (permissions, read-only filesystems, path issues)
-  - Enhanced DLX error messages with clear troubleshooting guidance
-  - Better error context in process locking, binary downloads, and package operations
-  - Consistent error formatting with helpful user guidance
-- **Consolidated process locking**: Standardized on directory-based lock format across all modules
-  - All locking operations now use `process-lock` module exclusively
-  - Lock directories provide atomic guarantees across all filesystems including NFS
-  - Consistent mtime-based stale detection with 5-second timeout (aligned with npm npx)
-  - Automatic cleanup on process exit with proper signal handling
+- Error messages across the library — actionable resolution steps for fs, dlx, process-lock, downloads
+- All locking consolidated on `process-lock` (atomic mkdir-based; 5s stale timeout aligned with npm npx)
 
 ## [2.8.4](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.4) - 2025-10-30
 
 ### Added
 
-- **DLX binary helper functions mirror dlx-package pattern**
-  - `downloadBinary`: Download binary with caching (without execution)
-  - `executeBinary`: Execute cached binary without re-downloading
-  - Renamed internal `downloadBinary` to `downloadBinaryFile` to avoid naming conflicts
-  - Maintains feature parity with `downloadPackage`/`executePackage` from dlx-package
+- `dlx` `downloadBinary` (cache without execution) and `executeBinary` (run cached binary). Internal `downloadBinary` renamed to `downloadBinaryFile` to avoid the naming conflict
 
 ## [2.8.3](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.3) - 2025-10-30
 
 ### Fixed
 
-- **Logger now fully defers all console access for Node.js internal bootstrap compatibility**: Completed lazy initialization to prevent ERR_CONSOLE_WRITABLE_STREAM errors
-  - Deferred `Object.getOwnPropertySymbols(console)` call until first logger use
-  - Deferred `kGroupIndentationWidth` symbol lookup
-  - Deferred `Object.entries(console)` and prototype method initialization
-  - Ensures logger can be safely imported in Node.js internal bootstrap contexts (e.g., `lib/internal/bootstrap/*.js`) before stdout is initialized
-  - Builds on v2.8.2 console deferring to complete early bootstrap compatibility
+- `Logger` defers `Object.getOwnPropertySymbols(console)`, `kGroupIndentationWidth`, and `Object.entries(console)` until first use — safe to import in Node.js internal bootstrap contexts
 
 ## [2.8.2](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.2) - 2025-10-29
 
 ### Changed
 
-- Enhanced Logger class to defer Console creation until first use
-  - Eliminates early bootstrap errors when importing logger before stdout is ready
-  - Enables safe logger imports during Node.js early initialization phase
-  - Simplified internal storage with WeakMap-only pattern for constructor args
+- `Logger` defers `Console` creation until first use — eliminates early-bootstrap errors when imported before stdout is ready
 
 ## [2.8.1](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.1) - 2025-10-29
 
 ### Changed
 
-- **Consolidated DLX cache key generation**: Extracted `generateCacheKey` function to shared `dlx.ts` module
-  - Eliminates code duplication between `dlx-binary.ts` and `dlx-package.ts`
-  - Enables consistent cache key generation across the Socket ecosystem
-  - Exports function for use in dependent packages (e.g., socket-cli)
-  - Maintains SHA-512 truncated to 16 chars strategy from v2.8.0
+- `dlx` — `generateCacheKey` extracted to shared module. Exported for downstream consumers (e.g. socket-cli)
 
 ## [2.8.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.8.0) - 2025-10-29
 
 ### Changed
 
-- **Enhanced DLX cache key generation with npm/npx compatibility**: Updated cache key strategy to align with npm/npx ecosystem patterns
-  - Changed from SHA-256 (64 chars) to SHA-512 truncated to 16 chars (matching npm/npx)
-  - Optimized for Windows MAX_PATH compatibility (260 character limit)
-  - Accepts collision risk for shorter paths (~1 in 18 quintillion with 1000 entries)
-  - Added support for PURL-style package specifications (e.g., `npm:prettier@3.0.0`, `pypi:requests@2.31.0`)
-  - Documented Socket's shorthand format (without `pkg:` prefix) handled by `@socketregistry/packageurl-js`
-  - References npm/cli v11.6.2 implementation for consistency
+- `dlx` cache keys — SHA-512 truncated to 16 chars (was SHA-256 / 64 chars), matching npm/npx. Better Windows `MAX_PATH` compatibility. Supports PURL specs (`npm:prettier@3.0.0`, `pypi:requests@2.31.0`)
 
 ## [2.7.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.7.0) - 2025-10-28
 
 ### Added
 
-- **DLX cache locking for concurrent installation protection**: Added process-lock protection to dlx-package installation operations
-  - Lock file created at `~/.socket/_dlx/<hash>/.lock` (similar to npm npx's `concurrency.lock`)
-  - Prevents concurrent installations from corrupting the same package cache
-  - Uses 5-second stale timeout and 2-second periodic touching (aligned with npm npx)
-  - Double-check pattern verifies installation after acquiring lock to avoid redundant work
-  - Completes 100% alignment with npm's npx locking strategy
+- `dlx` cache locking — `~/.socket/_dlx/<hash>/.lock` (npm-npx-style `concurrency.lock`). Prevents concurrent installations from corrupting the same package cache. 5s stale timeout, 2s periodic touch
 
 ## [2.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.6.0) - 2025-10-28
 
 ### Changed
 
-- **Process locking aligned with npm npx**: Enhanced process-lock module to match npm's npx locking strategy
-  - Reduced stale timeout from 10 seconds to 5 seconds (matches npm npx)
-  - Added periodic lock touching (2-second interval) to prevent false stale detection during long operations
-  - Implemented second-level granularity for mtime comparison to avoid APFS floating-point precision issues
-  - Added automatic touch timer cleanup on process exit
-  - Timers use `unref()` to prevent keeping process alive
-  - Aligns with npm's npx implementation per https://github.com/npm/cli/pull/8512
+- `process-lock` aligned with npm npx — 5s stale timeout (was 10s), 2s periodic touch, second-level mtime comparison (avoids APFS float precision), `unref()` timers, automatic cleanup on exit
 
 ## [2.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.5.0) - 2025-10-28
 
 ### Added
 
-- **Process locking utilities**: Added `ProcessLockManager` class providing cross-platform inter-process synchronization using file-system based locks
-  - Atomic lock acquisition via `mkdir()` for thread-safe operations
-  - Stale lock detection with automatic cleanup (default 10 seconds, aligned with npm's npx strategy)
-  - Exponential backoff with jitter for retry attempts
-  - Process exit handlers for guaranteed cleanup even on abnormal termination
-  - Three main APIs: `acquire()`, `release()`, and `withLock()` (recommended)
-  - Comprehensive test suite with `describe.sequential` for proper isolation
-  - Export: `@socketsecurity/lib/process-lock`
+- `process-lock` `ProcessLockManager` — cross-platform inter-process sync via filesystem locks. Atomic `mkdir()` acquisition; stale-lock detection (10s default); exponential backoff with jitter; exit-handler cleanup. APIs: `acquire`, `release`, `withLock` (recommended)
 
 ### Changed
 
-- **Script refactoring**: Renamed `spinner.succeed()` to `spinner.success()` for consistency
-- **Script cleanup**: Removed redundant spinner cleanup in interactive-runner
+- `spinner.succeed()` renamed to `spinner.success()`
 
 ## [2.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.4.0) - 2025-10-28
 
 ### Changed
 
-- **Download locking aligned with npm**: Reduced default `staleTimeout` in `downloadWithLock()` from 300 seconds to 10 seconds to align with npm's npx locking strategy
-  - Prevents stale locks from blocking downloads for extended periods
-  - Matches npm's battle-tested timeout range (5-10 seconds)
-  - Binary downloads now protected against concurrent corruption
-- **Binary download protection**: `dlxBinary.downloadBinary()` now uses `downloadWithLock()` to prevent corruption when multiple processes download the same binary concurrently
-  - Eliminates race conditions during parallel binary downloads
-  - Maintains checksum verification and executable permissions
+- `downloadWithLock()` default `staleTimeout` 300s → 10s (aligns with npm npx)
+- `dlxBinary.downloadBinary()` uses `downloadWithLock()` to prevent corruption from concurrent binary downloads
 
 ## [2.3.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.3.0) - 2025-10-28
 
 ### Added
 
-- **Binary utility wrapper functions**: Added `which()` and `whichSync()` wrapper functions to `bin` module
-  - Cross-platform binary lookup that respects PATH environment variable
-  - Synchronous and asynchronous variants for different use cases
-  - Integrates with existing binary resolution utilities
+- `bin` `which()` / `whichSync()` — cross-platform binary lookup respecting `PATH`
 
 ## [2.2.1](https://github.com/SocketDev/socket-lib/releases/tag/v2.2.1) - 2025-10-28
 
 ### Fixed
 
-- **Logger write() method**: Fixed `write()` to bypass Console formatting when outputting raw text
-  - Previously, `write()` used Console's internal `_stdout` stream which applied unintended formatting like group indentation
-  - Now stores a reference to the original stdout stream in a dedicated private field (`#originalStdout`) during construction
-  - The `write()` method uses this stored reference to write directly to the raw stream, bypassing all Console formatting layers
-  - Ensures raw text output without any formatting applied, fixing test failures in CI environments where writes after `indent()` were unexpectedly formatted
+- `Logger` `write()` bypasses Console formatting (group indentation, etc.) — now writes directly to the raw stdout reference captured at construction
 
 ## [2.2.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.2.0) - 2025-10-28
 
 ### Added
 
-- **Logger step symbol**: `logger.step()` now displays a cyan arrow symbol (→ or > in ASCII) before step messages for improved visual separation
-  - New `LOG_SYMBOLS.step` symbol added to the symbol palette
-  - Automatic stripping of existing symbols from step messages
-  - Maintains existing blank line behavior for clear step separation
+- `Logger` `step()` — cyan arrow `→` prefix (or `>` in ASCII fallback). New `LOG_SYMBOLS.step`
 
 ## [2.1.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.1.0) - 2025-10-28
 
 ### Added
 
-- Package manager detection utilities (`detectPackageManager()`, `getPackageManagerInfo()`, `getPackageManagerUserAgent()`)
-- `isInSocketDlx()` utility to check if file path is within `~/.socket/_dlx/`
-- `downloadPackage()` and `executePackage()` functions for separate download and execution of packages
+- Package manager detection — `detectPackageManager()`, `getPackageManagerInfo()`, `getPackageManagerUserAgent()`
+- `isInSocketDlx()` — check if a path is under `~/.socket/_dlx/`
+- `downloadPackage()` / `executePackage()` — separate download and execution
 
 ## [2.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.0.0) - 2025-10-27
 
-### Breaking Changes
-
-**Environment Variable System Refactor**
-
-This release completely refactors the environment variable system, consolidating 60+ individual env constant files into grouped getter modules with AsyncLocalStorage-based test rewiring.
-
-**Consolidated env files** - Individual files replaced with grouped modules:
-
-- `env/github.ts` - All GitHub-related env vars (GITHUB_TOKEN, GH_TOKEN, GITHUB_API_URL, etc.)
-- `env/socket.ts` - Socket-specific env vars (SOCKET_API_TOKEN, SOCKET_CACACHE_DIR, etc.)
-- `env/socket-cli.ts` - Socket CLI env vars (SOCKET_CLI_API_TOKEN, SOCKET_CLI_CONFIG, etc.)
-- `env/npm.ts` - NPM-related env vars
-- `env/locale.ts` - Locale env vars (LANG, LC_ALL, LC_MESSAGES)
-- `env/windows.ts` - Windows-specific env vars (USERPROFILE, LOCALAPPDATA, APPDATA, COMSPEC)
-- `env/xdg.ts` - XDG base directory env vars
-- `env/temp-dir.ts` - Temp directory env vars (TEMP, TMP, TMPDIR)
-- `env/test.ts` - Test framework env vars (VITEST, JEST_WORKER_ID)
-
-**Constants → Getter functions** - All env constants converted to functions:
-
-```typescript
-// Before (v1.x):
-import { GITHUB_TOKEN } from '#env/github-token'
-
-// After (v2.x):
-import { getGithubToken } from '#env/github'
-```
-
-**Deleted files** - Removed 60+ individual env constant files:
+### Changed
 
-- `env/github-token.ts`, `env/socket-api-token.ts`, etc. → Consolidated into grouped files
-- `env/getters.ts` → Functions moved to their respective grouped files
+- **BREAKING**: Environment variable system refactor — 60+ individual `env/<NAME>.ts` files consolidated into grouped getter modules:
+  - `env/github`, `env/socket`, `env/socket-cli`, `env/npm`, `env/locale`, `env/windows`, `env/xdg`, `env/temp-dir`, `env/test`
+  - All env constants converted to functions: `import { GITHUB_TOKEN } from '#env/github-token'` → `import { getGithubToken } from '#env/github'`
 
 ### Added
 
-**AsyncLocalStorage-Based Test Rewiring**
-
-New `env/rewire.ts` and `path/rewire.ts` modules provides context-isolated environment variable overrides for testing:
-
-```typescript
-import { withEnv, setEnv, resetEnv, getEnvValue } from '#env/rewire'
-
-// Option 1: Isolated context with AsyncLocalStorage
-await withEnv({ CI: '1', NODE_ENV: 'test' }, async () => {
-  // CI env var is '1' only within this block
-  // Concurrent tests don't interfere
-})
-
-// Option 2: Traditional beforeEach/afterEach pattern
-beforeEach(() => {
-  setEnv('CI', '1')
-})
-
-afterEach(() => {
-  resetEnv()
-})
-```
-
-**Features:**
-
-- Allows toggling between snapshot and live behavior
-- Compatible with `vi.stubEnv()` as fallback
-
-### Changed
-
-- Updated all dynamic `require()` statements to use path aliases (`#constants/*`, `#packages/*`)
-- Improved logger blank line tracking per stream (separate stderr/stdout tracking)
-- Exported `getCacache()` function for external use
+- `env/rewire` and `paths/rewire` — AsyncLocalStorage-based env/path overrides for testing. `withEnv({...}, async () => {})` for isolated context, or `setEnv` / `resetEnv` for `beforeEach`/`afterEach`
+- `getCacache()` exported
 
 ## [1.3.6](https://github.com/SocketDev/socket-lib/releases/tag/v1.3.6) - 2025-10-26
 
 ### Fixed
 
-- Fixed `debug` module functions being incorrectly tree-shaken as no-ops in bundled output
-  - Removed incorrect `/*@__NO_SIDE_EFFECTS__*/` annotations from `debug()`, `debugDir()`, `debugLog()`, and their `*Ns` variants
-  - These functions have side effects (logging output, spinner manipulation) and should not be removed by bundlers
-  - Fixes issue where `debugLog()` and `debugDir()` were compiled to empty no-op functions
+- `debug` functions no longer tree-shaken as no-ops — removed incorrect `/*@__NO_SIDE_EFFECTS__*/` annotations on `debug`, `debugDir`, `debugLog` (+ `*Ns` variants)
 
 ## [1.3.5](https://github.com/SocketDev/socket-lib/releases/tag/v1.3.5) - 2025-10-26
 
 ### Added
 
-- Added `createEnvProxy()` utility function to `env` module for Windows-compatible environment variable access
-  - Provides case-insensitive environment variable access (e.g., PATH, Path, path all work)
-  - Smart priority system: overrides > exact match > case-insensitive fallback
-  - Full Proxy implementation with proper handlers for get, set, has, ownKeys, getOwnPropertyDescriptor
-  - Opt-in helper for users who need Windows env var compatibility
-  - Well-documented with usage examples and performance notes
-- Added `findCaseInsensitiveEnvKey()` utility function to `env` module
-  - Searches for environment variable keys using case-insensitive matching
-  - Optimized with length fast path to minimize expensive `toUpperCase()` calls
-  - Useful for cross-platform env var access where case may vary (e.g., PATH vs Path vs path)
-- Added comprehensive test suite for `env` module with 71 tests
-  - Covers `envAsBoolean()`, `envAsNumber()`, `envAsString()` conversion utilities
-  - Tests `createEnvProxy()` with Windows environment variables and edge cases
-  - Validates `findCaseInsensitiveEnvKey()` optimization and behavior
+- `env` `createEnvProxy()` — Windows-compatible case-insensitive env var access (`PATH`, `Path`, `path` all work). Priority: overrides > exact match > case-insensitive fallback
+- `env` `findCaseInsensitiveEnvKey()` — case-insensitive key search with length fast-path
 
 ### Fixed
 
-- Fixed `spawn` module to preserve Windows `process.env` Proxy behavior
-  - When no custom environment variables are provided, use `process.env` directly instead of spreading it
-  - Preserves Windows case-insensitive environment variable access (PATH vs Path)
-  - Fixes empty CLI output issue on Windows CI runners
-  - Only spreads `process.env` when merging custom environment variables
+- `spawn` preserves Windows `process.env` Proxy behavior (uses `process.env` directly when no custom env merges, keeping Windows case-insensitive access)
 
 ## [1.3.4](https://github.com/SocketDev/socket-lib/releases/tag/v1.3.4) - 2025-10-26
 
 ### Added
 
-- Added Node.js SIGUSR1 signal handler prevention utilities in `constants/node` module
-  - `supportsNodeDisableSigusr1Flag()`: Detects if Node supports `--disable-sigusr1` flag (v22.14+, v23.7+, v24.8+)
-  - `getNodeDisableSigusr1Flags()`: Returns appropriate flags to prevent debugger attachment
-    - Returns `['--disable-sigusr1']` on supported versions (prevents Signal I/O Thread creation)
-    - Falls back to `['--no-inspect']` on Node 18+ (blocks debugger but still creates thread)
-  - Enables production CLI environments to prevent SIGUSR1 debugger signal handling for security
+- `constants/node` — `supportsNodeDisableSigusr1Flag()`, `getNodeDisableSigusr1Flags()`. Returns `['--disable-sigusr1']` on Node 22.14+/23.7+/24.8+, falls back to `['--no-inspect']` on Node 18+
 
 ## [1.3.3](https://github.com/SocketDev/socket-lib/releases/tag/v1.3.3) - 2025-10-24
 
 ### Fixed
 
-- Fixed lazy getter bug in `objects` module where `defineGetter`, `defineLazyGetter`, and `defineLazyGetters` had incorrect `/*@__NO_SIDE_EFFECTS__*/` annotations
-  - These functions mutate objects by defining properties, so marking them as side-effect-free caused esbuild to incorrectly tree-shake the calls during bundling
-  - Lazy getters were returning `undefined` instead of their computed values
-  - Removed double wrapping in `defineLazyGetters` where `createLazyGetter` was being called unnecessarily
+- `objects` `defineGetter`, `defineLazyGetter`, `defineLazyGetters` — removed incorrect `/*@__NO_SIDE_EFFECTS__*/` annotations (these mutate objects). Lazy getters were returning `undefined` after esbuild tree-shaking
 
 ## [1.3.2](https://github.com/SocketDev/socket-lib/releases/tag/v1.3.2) - 2025-10-24
 
@@ -1583,10 +1012,7 @@ afterEach(() => {
 
 ### Fixed
 
-- Fixed @inquirer modules (`input`, `password`, `search`) not being properly bundled into `dist/external/`
-  - Resolves build failures in downstream packages (socket-cli) that depend on socket-lib
-  - Added missing packages to bundling configuration in `scripts/build-externals.mjs`
-  - All @inquirer packages now ship as zero-dependency bundles
+- `@inquirer` modules (`input`, `password`, `search`) properly bundled into `dist/external/` — fixes build failures in downstream socket-cli
 
 ### Added
 
@@ -1599,96 +1025,72 @@ afterEach(() => {
 
 ### Added
 
-- Added `validateFiles()` utility function to `fs` module for defensive file access validation
-  - Returns `ValidateFilesResult` with `validPaths` and `invalidPaths` arrays
-  - Filters out unreadable files before processing (common with Yarn Berry PnP virtual filesystem, pnpm symlinks)
-  - Prevents ENOENT errors when files exist in glob results but are not accessible
-  - Comprehensive test coverage for all validation scenarios
+- `fs` `validateFiles()` — returns `{ validPaths, invalidPaths }`. Filters unreadable files before processing (Yarn Berry PnP, pnpm symlinks)
 
 ## [1.2.0](https://github.com/SocketDev/socket-lib/releases/tag/v1.2.0) - 2025-10-23
 
 ### Added
 
-- Added `dlx-package` module for installing and executing npm packages directly
-  - Content-addressed caching using SHA256 hash (like npm's \_npx)
-  - Auto-force for version ranges (^, ~, >, <) to get latest within range
-  - Cross-platform support with comprehensive tests (30 tests)
-  - Parses scoped and unscoped package specs correctly
-  - Resolves binaries from package.json bin field
+- `dlx-package` — install and execute npm packages directly. Content-addressed cache (SHA256). Auto-force for version ranges (`^`, `~`, `>`, `<`). Resolves binaries from `package.json` `bin`
 
 ### Changed
 
-- Unified DLX storage under `~/.socket/_dlx/` directory
-  - Binary downloads now use `~/.socket/_dlx/` instead of non-existent cache path
-  - Both npm packages and binaries share parent directory with content-addressed hashing
-- Updated paths.ts documentation to clarify unified directory structure
+- Unified DLX storage under `~/.socket/_dlx/` (binary downloads + npm packages share content-addressed parent)
 
 ## [1.1.2] - 2025-10-23
 
 ### Fixed
 
-- Fixed broken relative import paths in `packages/isolation.ts` and `packages/provenance.ts` that prevented bundling by external tools
+- Broken relative import paths in `packages/isolation.ts` / `packages/provenance.ts`
 
 ## [1.1.1] - 2025-10-23
 
 ### Fixed
 
-- Fixed shimmer text effects not respecting CI environment detection (now disabled in CI to prevent ANSI escape codes in logs)
+- Shimmer text effects respect CI detection (disabled in CI to avoid ANSI escapes in logs)
 
 ## [1.1.0] - 2025-10-23
 
 ### Added
 
-- Added `filterOutput` option to `stdio/mask` for filtering output chunks before display/buffering
-- Added `overrideExitCode` option to `stdio/mask` for customizing exit codes based on captured output
-- Added comprehensive JSDoc documentation across entire library for enhanced VSCode IntelliSense
-  - Detailed @param, @returns, @template, @throws tags
-  - Practical @example blocks with real-world usage patterns
-  - @default tags showing default values
-  - Enhanced interface property documentation
-
-### Changed
-
-- Improved TypeScript type hints and tooltips throughout library
-- Enhanced documentation for all core utilities (arrays, fs, git, github, http-request, json, logger, objects, path, promises, spawn, spinner, strings)
-- Enhanced documentation for stdio utilities (clear, divider, footer, header, mask, progress, prompts, stderr, stdout)
-- Enhanced documentation for validation utilities (json-parser, types)
+- `stdio/mask` — `filterOutput` (filter output chunks before display) and `overrideExitCode` (customize exit codes from captured output)
+- Comprehensive JSDoc across the library for IntelliSense (`@param`, `@returns`, `@example`, `@default`)
 
 ## [1.0.5] - 2025-10-22
 
 ### Added
 
-- Added support for custom retry delays from onRetry callback
+- Custom retry delays from `onRetry` callback
 
 ## [1.0.4] - 2025-10-21
 
 ### Fixed
 
-- Fixed external dependency paths in root-level source files (corrected require paths from `../external/` to `./external/` in bin, cacache, fs, globs, spawn, spinner, and streams modules)
+- External dep paths in root-level dist files (`../external/` → `./external/`)
 
 ## [1.0.3] - 2025-10-21
 
 ### Fixed
 
-- Fixed external dependency import paths in packages and stdio modules (corrected require paths from `../../external/` to `../external/`)
+- External dep import paths in `packages/` and `stdio/` modules (`../../external/` → `../external/`)
 
 ## [1.0.2] - 2025-10-21
 
 ### Fixed
 
-- Fixed module resolution error in packages/normalize module (corrected require path from `../../constants/socket` to `../constants/socket`)
+- `packages/normalize` module resolution (`../../constants/socket` → `../constants/socket`)
 
 ## [1.0.1] - 2025-10-21
 
 ### Fixed
 
-- Fixed relative import paths in compiled CommonJS output (changed `require("../external/...")` to `require("./external/...")` for root-level dist files)
+- Relative imports in compiled CommonJS — root-level dist files use `./external/...`
 
 ## [1.0.0] - 2025-10-20
 
 ### Changed
 
-- Consolidated parseArgs into argv/parse module
+- `parseArgs` consolidated into `argv/parse`
 
 ---
 
@@ -1696,254 +1098,12 @@ afterEach(() => {
 
 ---
 
-## [1.5.3] - 2025-10-07
-
-### Added
-
-- Fix bad build and add validation to prevent in future
-
-## [1.5.2] - 2025-10-07
-
-### Added
-
-- Added coverage utilities to parse v8 and type coverage reports
-
-### Fixed
-
-- Fixed `isPath` function to exclude URLs with protocols
-- Fixed `isolatePackage` to handle file: URLs and npm-package-arg paths correctly
-
-## [1.5.1] - 2025-10-05
-
-### Added
-
-- Added `isolatePackage` to `lib/packages/isolation` for creating isolated package test environments
-
-### Changed
-
-- Removed `dependencies/index` barrel file to prevent eager loading of all dependency modules
+These entries cover versions 1.0.0 → 1.5.3 of the previous package name (`@socketsecurity/registry`, Sep 2025 – Oct 2025). The version-number line restarted at 1.0.0 when the package was renamed to `@socketsecurity/lib`, so the current 1.x and 5.x lines do **not** continue from these old versions. Listed here for archival reference only.
 
-## [1.5.0] - 2025-10-05
+### Highlights
 
-### Added
-
-- Added support for testing local development packages in addition to socket-registry packages
-- Exposed isolation module as part of public API via `lib/packages`
-
-### Changed
-
-- Renamed `setupPackageTest` to `isolatePackage` for clearer intent
-- Refactored `installPackageForTesting` to accept explicit `sourcePath` and `packageName` parameters
-- Simplified package installation logic by removing path detection from low-level function
-- Consolidated `setupPackageTest` and `setupMultiEntryTest` into single `isolatePackage` function with options
-
-## [1.4.6] - 2025-10-05
-
-### Added
-
-- Added comprehensive package.json exports validation tests
-
-## [1.4.5] - 2025-10-05
-
-### Added
-
-- Added performance monitoring utilities with timer, measurement, and reporting functions
-- Added memoization utilities with LRU, TTL, weak references, and promise deduplication support
-- Added table formatting utilities (`formatTable`, `formatSimpleTable`) for CLI output
-- Added progress tracking to spinner with `updateProgress()` and `incrementProgress()` methods
-- Added `isDir` and `safeStats` async helpers to fs module
-
-### Changed
-
-- Removed `platform` and `arch` options from `dlxBinary` function as cross-platform binary execution is not supported
-
-### Fixed
-
-- Fixed Windows shell execution in `dlxBinary` by adding cache directory to PATH
-
-## [1.4.4] - 2025-10-05
-
-### Fixed
-
-- Fixed subpath exports
-
-## [1.4.3] - 2025-10-04
-
-### Added
-
-- Spinner lifecycle utilities (`withSpinner`, `withSpinnerRestore`, `withSpinnerSync`) for automatic spinner cleanup with try/finally blocks
-
-## [1.4.2] - 2025-10-04
-
-### Added
-
-- Added `GITHUB_API_BASE_URL` constant for GitHub API endpoint configuration
-- Added `SOCKET_API_BASE_URL` constant for Socket API endpoint configuration
-- Added generic TTL cache utility (`createTtlCache`) with in-memory memoization and persistent storage support
-
-### Changed
-
-- Refactored GitHub caching to use the new `cache-with-ttl` utility for better performance and consistency
-
-## [1.4.1] - 2025-10-04
-
-### Changed
-
-- Update maintained Node.js versions of `constants.maintainedNodeVersions`
-
-## [1.4.0] - 2025-10-04
-
-### Added
-
-- Added `PromiseQueue` utility for controlled concurrency operations
-- Added lazy dependency loaders and test utilities
-- Added HTTP utilities with retry logic and download locking
-- Added `.claude` directory for scratch documents
-- Added `noUnusedLocals` and `noUnusedParameters` to TypeScript config
-
-### Changed
-
-- Refactored all library functions to use options objects for better API consistency
-  - `lib/strings.ts` - String manipulation functions
-  - `lib/url.ts` - URL handling functions
-  - `lib/words.ts` - Word manipulation functions
-- Refactored `lib/packages` module into specialized submodules for improved code organization
-  - `lib/packages/editable.ts` - Package editing functionality
-  - `lib/packages/exports.ts` - Export resolution utilities
-  - `lib/packages/licenses.ts` - License handling and validation
-  - `lib/packages/manifest.ts` - Manifest data operations
-  - `lib/packages/normalize.ts` - Path normalization utilities
-  - `lib/packages/operations.ts` - Package installation and modification operations
-  - `lib/packages/paths.ts` - Package path utilities
-  - `lib/packages/provenance.ts` - Package provenance verification
-  - `lib/packages/specs.ts` - Package spec parsing
-  - `lib/packages/validation.ts` - Package validation utilities
-- Moved configuration files (vitest, eslint, knip, oxlint, taze) to `.config` directory
-- Replaced `fetch()` with Node.js native `http`/`https` modules for better reliability
-- Replaced `any` types with meaningful types across library utilities
-- Improved pnpm security with build script allowlist
-- Updated vitest coverage thresholds to 80%
-- Consolidated test files to reduce duplication
-- Note: Public API remains unchanged; these are internal organizational improvements
-
-### Fixed
-
-- Fixed resource leaks and race conditions in socket-registry
-- Fixed `yarn-cache-path` constant to return string type consistently
-- Fixed Yarn Windows temp path detection in `shouldSkipShadow`
-- Fixed path normalization for Windows compatibility across all path utilities
-- Fixed cache path tests for Windows case sensitivity
-- Fixed type errors in promises, parse-args, logger, and specs tests
-- Fixed GitHub tests to mock `httpRequest` correctly
-- Fixed SEA build tests to mock `httpRequest`
-- Decoded URL percent-encoding in `pathLikeToString` fallback
-
-## [1.3.10] - 2025-10-03
-
-### Added
-
-- New utility modules for DLX, shadow, SEA, cacache, and versions functionality
-- getSocketHomePath alias to paths module
-- del dependency and external wrapper for safer file deletion
-- @fileoverview tags to lib modules
-- camelCase expansion for kebab-case arguments in parseArgs
-- Coerce and configuration options to parseArgs
-
-### Changed
-
-- Updated file removal to use del package for safer deletion
-- Normalized path returns in fs and Socket directory utilities
-- Removed default exports from git and parse-args modules
-- Enhanced test coverage across multiple modules (parse-args, prompts, strings, env, spawn, json)
-
-## [1.3.9] - 2025-10-03
-
-### Changed
-
-- Internal build and distribution updates
-
-## [1.3.8] - 2025-10-03
-
-### Added
-
-- Added unified directory structure for Socket ecosystem tools
-- New path utilities module for cross-platform directory resolution
-- Directory structure constants for Socket CLI, Registry, Firewall, and DLX
-
-## [1.3.7] - 2025-10-02
-
-### Changed
-
-- Updated manifest.json entries
-
-## [1.3.6] - 2025-10-01
-
-### Fixed
-
-- Fixed indent-string interoperability with older v1 and v2 versions
-
-## [1.3.5] - 2025-10-01
-
-### Added
-
-- Added lib/git utilities module
-
-### Fixed
-
-- Fixed invalid manifest entries
-- Fixed parseArgs strip-aliased bug
-
-## [1.3.4] - 2025-10-01
-
-### Changed
-
-- Updated various package override versions
-
-## [1.3.3] - 2025-10-01
-
-### Fixed
-
-- Fixed normalizePath collapsing multiple leading `..` segments incorrectly
-
-## [1.3.2] - 2025-10-01
-
-### Added
-
-- Added 'sfw' to isBlessedPackageName method check
-- Added ENV.DEBUG normalization for debug package compatibility
-  - `DEBUG='1'` or `DEBUG='true'` automatically expands to `DEBUG='*'` (enables all namespaces)
-  - `DEBUG='0'` or `DEBUG='false'` automatically converts to empty string (disables all output)
-  - Namespace patterns like `DEBUG='app:*'` are preserved unchanged
-
-## [1.3.1] - 2025-09-30
-
-### Changed
-
-- Renamed debug functions from *Complex to *Ns
-
-### Fixed
-
-- Fixed regression with lib/prompts module imports
-
-## [1.3.0] - 2025-09-29
-
-### Changed
-
-- Updated registry subpath exports
-
-### Fixed
-
-- Fixed Node.js built-in module imports in CommonJS output
-
-## [1.2.2] - 2025-09-29
-
-### Changed
-
-- Internal improvements to module structure
-
-## [1.2.1] - 2025-09-29
-
-### Changed
+- **1.5.x** (Oct 2025) — `isolatePackage` for isolated package test environments; v8 coverage utilities; `dependencies/index` barrel removed
+- **1.4.x** (Oct 2025) — Performance monitoring + memoization utilities; table formatting (`formatTable`, `formatSimpleTable`); spinner progress; `isDir`, `safeStats` async fs helpers
+- **1.3.x** (Sep–Oct 2025) — Initial constants restructure, build configuration, package exports
 
-- Restructured constants module with new architecture
-- Updated build configuration and package exports
+For full details, see git history under the `@socketsecurity/registry` package name.