@socketsecurity/lib 5.28.0 → 6.0.1

package/CHANGELOG.md

@@ -5,46 +5,146 @@ 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.28.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.28.0) - 2026-05-06
+## [6.0.1](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.1) - 2026-05-25
+
+Five additive features plus public-surface polish on top of 6.0.0. The path renames drop doubled-name leaves (`spawn/spawn`, `ttl-cache/cache`, `globs/glob`, `links/link`, `promise-queue/queue`) and regroup three top-level directories whose contents were the same concept (process events) under a new `events/` umbrella. Renames are path-only; no symbol renames or behavior changes.
 
 ### Added
 
-- **`compression` (new export)** — brotli + gzip helpers with three calling shapes (in-memory `Buffer`, file-to-file, raw streams) and a single `{ inPlace: true }` option for compress/decompress-in-place. 28 named exports total:
-  - In-memory: `compressBrotli`, `decompressBrotli`, `compressGzip`, `decompressGzip`
-  - File-to-file: `compressBrotliFile`, `decompressBrotliFile`, `compressGzipFile`, `decompressGzipFile` — each with three overloads (explicit dest, in-place, options object). The gzip in-place path follows `.tgz` → `.tar` convention so a round-trip is lossless
-  - Streams: `createBrotliCompressor`, `createBrotliDecompressor`, `createGzipCompressor`, `createGzipDecompressor`
-  - Detection: `isBrotliCompressed(buffer)` / `isGzipCompressed(buffer)` (magic-byte sniffing)
-  - Path classification: `hasBrotliExt(filePath)` / `hasGzipExt(filePath)` — case-insensitive `path.extname` match against `.br` / `.brotli` / `.gz` / `.gzip` / `.tgz`
-  - Helpers: `BROTLI_EXTS` / `GZIP_EXTS` `ReadonlySet<string>` constants; `stripExt(filePath, exts)` for trimming a recognized extension from a path; `resolveBrotliOptions` / `resolveGzipOptions` for translating `CompressOptions` into the underlying zlib option shapes
-  - `CompressOptions` / `CompressFileOptions` interfaces
-- **`socket-lib` CLI (new `bin` entry)** — fleet-wide static-analysis dispatcher invoked via `pnpm exec socket-lib <command>`. Initial subcommand: `check primordials` (alias `check prim`) — diffs every name destructured from `primordials` in scanned source against `@socketsecurity/lib`'s exposed primordials set, emitting unmapped or missing-from-lib findings. Reads sectional config from `.socket-lib.json` (with `.config/socket-lib.json` as a fallback) or a bare object for single-check setups. Flags: `--config / -c <path>` (defaults to `.socket-lib.json`, falls back to `.config/socket-lib.json`), `--explain`, `--json`, `--silent`, `--help`. Lifted from socket-btm's `scripts/check-primordials-coverage.mts` so the same drift gate now ships to every consumer.
-- **`dlx/package` `installRoot` option** — new `EnsurePackageInstallOptions` (and `DlxPackageOptions`) field overriding the install root passed to Arborist. Default remains `~/.socket/_dlx/<cacheKey>/`; when set, the value is used verbatim. Lets build pipelines colocate the install with their own gitignored outputs (e.g. ink-builder bundling ink via esbuild). Caller owns per-spec separation; see JSDoc for the full contract.
+- **`colors/socket-palette`** — Socket-branded 24-bit ANSI palette. Three themes (`'light' | 'dark' | 'synthwave'`) expose status colors (`success` / `warning` / `alert` / `error` / `info`) plus the Socket brand constants (`socketPurple` `#8c50ff`, `socketPink` `#ff00aa`). Each helper emits `\x1b[38;2;R;G;Bm` directly rather than rounding to the legacy 8-color palette, so truecolor terminals render the brand hex byte-for-byte. Hex values exposed via `palette.hex.*` for callers building their own escapes. Default theme is `'dark'`.
+- **`logger/browser`** — minimal `console`-backed `Logger` mirroring the public `success` / `fail` / `warn` / `error` / `info` / `log` surface, with no `node:process` / `node:console` / `node:os` imports. Usable from Chrome MV3 service workers, content scripts, and popups. Importing `@socketsecurity/lib/logger` in a bundler that resolves the `'browser'` export condition (rolldown, vite, esbuild) automatically picks up this shim; Node consumers continue to get the full `Logger` class.
+- **`'browser'` export condition** on 40 leaf modules. 35 zero-Node leaf utilities (`arrays`, `colors`, `errors`, `objects`, `regexps`, `strings`, `url`, `versions`, `words` families) carry a `'browser'` condition signalling browser-safety to bundlers. Five leaves with dedicated browser implementations (`logger/browser`, `http-request/browser`, `http-request/browser-fetch`) route to the alternate file. Browser-incompatible modules (`fs`, `archives`, `bin`, subprocess / TTY / OS-secrets surfaces) deliberately omit the condition. Full compatibility matrix in [`docs/browser-compatibility.md`](./docs/browser-compatibility.md).
+- **`http-request` `signal` option (Node-side parity).** `HttpRequestOptions.signal?: AbortSignal | undefined` is now plumbed through `request-attempt` → `httpModule.request()`. An aborted signal short-circuits the retry loop (caller cancel is not retryable). Brings the Node side to parity with the browser side, which already exposes `signal` via `AbortController` on `fetch()`.
+- **Default-on read-result cache for `fs/read-json` `readJson` / `readJsonSync`.** Process-scoped LRU cache keyed on `path + ino + size + mtimeMs`. Safe by four guards: stat-validated keys (re-read on stat mismatch), defensive clone on both insert and hit (caller mutations can't poison the entry), reviver opt-out (function identity isn't safely hashable), and per-call `cache: false` escape hatch. Cap defaults to 256 entries (env `SOCKET_LIB_READ_JSON_CACHE_MAX` or `setReadJsonCacheMax()`); TTL defaults to 5 min (env `SOCKET_LIB_READ_JSON_CACHE_TTL_MS` or `setReadJsonCacheTtlMs()`; set to `0` to disable TTL). `clearReadJsonCache()` + `getReadJsonCacheStats()` exported for tests and long-running daemons.
+- **`argv/parse-args-string`** — `parseArgsString(cmd)` tokenizes a shell-style command string into an argv array. Recognizes bare tokens, single + double quoted tokens, and mixed `key="value"` tokens. Use for turning a string representation of a command (from config, a `bin` field, a test fixture) into argv that `child_process.spawn` / `execFileSync` accepts directly, bypassing platform shell quoting differences (`cmd.exe` vs `bash`).
 
-## [5.27.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.27.0) - 2026-05-04
+### Changed (breaking)
+
+- **`spawn/*` → `process/spawn/*`.** Directory moved under `process/` (which already housed `process/abort`); the function leaf renames from `spawn/spawn` to `process/spawn/child` (the spawned child is what `spawn()` returns). Sibling files keep their names: `process/spawn/{errors,stdio,types,_internal}`.
+- **`signal-exit/*` → `events/exit/*`.** Directory merged into a new `events/` umbrella. Entry leaf renames from `signal-exit/register` to `events/exit/handler`. Sibling files unchanged: `events/exit/{intercept,lifecycle,signals,types,_internal}`.
+- **`warnings/*` → `events/warning/*`.** Sibling of `events/exit/` under the new `events/` umbrella. Entry leaf renames from `warnings/event-target` to `events/warning/handler`; `warnings/suppress` becomes `events/warning/suppress`.
+- **`ttl-cache/*` → `cache/ttl/*`.** Directory renamed; entry leaf renames from `ttl-cache/cache` to `cache/ttl/store`. `ttl-cache/types` becomes `cache/ttl/types`.
+- **`promise-queue/*` folded into existing `promises/`.** `promise-queue/queue` becomes `promises/queue`; `promise-queue/types` merges into the existing `promises/types`.
+- **`spinner/registry` → `spinner/default`.** Matches the `getDefaultSpinner()` naming pattern — the leaf is "the default spinner", not "the registry of spinners".
+- **`logger/logger` → `logger/default`.** Matches the `getDefaultLogger()` naming pattern; drops the doubled segment.
+- **`globs/glob` → `globs/match`.** Drops the doubled segment; `match` describes what the function does (pattern-match files), not what type the file is.
+- **`links/link` → `links/create`.** Drops the doubled segment; `create` describes the verb (`createSymlink`).
+- **`exports` map refreshed** for all renamed/moved leaves. The `./promises/types` entry stays unchanged — `promise-queue/types` content was folded into it.
+
+### Removed (breaking)
+
+- **Top-level directories `spawn/`, `signal-exit/`, `warnings/`, `ttl-cache/`, `promise-queue/`.** All five disappear in favor of the regrouped layouts above. No backcompat aliases.
+
+### Migration
+
+```diff
+- import { spawn, spawnSync } from '@socketsecurity/lib/spawn/spawn'
+- import { isSpawnError, SpawnError } from '@socketsecurity/lib/spawn/errors'
+- import type { SpawnOptions } from '@socketsecurity/lib/spawn/types'
++ import {
++   spawn,
++   spawnSync,
++   isSpawnError,
++   SpawnError,
++ } from '@socketsecurity/lib/process/spawn/child'
++ import type { SpawnOptions } from '@socketsecurity/lib/process/spawn/types'
+
+- import { onExit } from '@socketsecurity/lib/signal-exit/register'
++ import { onExit } from '@socketsecurity/lib/events/exit/handler'
+
+- import { suppressDeprecationWarnings } from '@socketsecurity/lib/warnings/suppress'
++ import { suppressDeprecationWarnings } from '@socketsecurity/lib/events/warning/suppress'
+
+- import { createTtlCache, TtlCache } from '@socketsecurity/lib/ttl-cache/cache'
++ import { createTtlCache, TtlCache } from '@socketsecurity/lib/cache/ttl/store'
+
+- import { getDefaultSpinner } from '@socketsecurity/lib/spinner/registry'
++ import { getDefaultSpinner } from '@socketsecurity/lib/spinner/default'
+
+- import { getDefaultLogger } from '@socketsecurity/lib/logger/logger'
++ import { getDefaultLogger } from '@socketsecurity/lib/logger/default'
+
+- import { PromiseQueue } from '@socketsecurity/lib/promise-queue/queue'
++ import { PromiseQueue } from '@socketsecurity/lib/promises/queue'
+
+- import { glob } from '@socketsecurity/lib/globs/glob'
++ import { glob } from '@socketsecurity/lib/globs/match'
+
+- import { createSymlink } from '@socketsecurity/lib/links/link'
++ import { createSymlink } from '@socketsecurity/lib/links/create'
+```
+
+No symbol names changed. No behavior changes.
+
+## [6.0.0](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.0) - 2026-05-20
+
+Public-surface reshape. All top-level barrels are gone; import from named leaf subpaths instead. `@socketsecurity/lib/logger` and `@socketsecurity/lib/errors` stay as aliases.
+
+### Removed (breaking)
+
+- **All top-level barrel modules.** Replace with leaf subpaths — e.g. `fs` → `fs/safe`, `http-request` → `http-request/convenience`, `packages` → `packages/operations`, `versions` → `versions/compare`. Affects `fs`, `http-request`, `spinner`, `git`, `github`, `spawn`, `bin`, `primordials`, `objects`, `strings`, `promises`, `arrays`, `url`, `packages`, `cacache`, `signal-exit`, `compression`, `archives`, `globs`, `regexps`, `ssri`, `colors`, `ansi`, `crypto`, `abort`, `streams`, `links`, `shadow`, `ipc`, `ipc-cli`, `errors`, `words`, `tables`, `sorts`, `env`, `debug`, `versions`, `types`.
+- **`agent` removed.** Per-tool helpers under `eco/npm/<tool>/{exec,flags}` (`bun`, `npm`, `pnpm`, `vlt`, `yarnpkg/yarn`).
+- **`types/` removed.** Schema types under `eco/purl` and `eco/types`.
+- **Subdir renames.** `memoization/` → `memo/`, `performance/` → `perf/`, `suppress-warnings/` → `warnings/`, `cache-with-ttl/` → `ttl-cache/`, `process-lock/` → `process/`, `package-extensions/` → `pkg-ext/`, `temporary-executor/` → `process/transient` (`isRunningInTemporaryExecutor` → `isTransientProcess`).
+- **`SOCKET_LIB_USER_AGENT` + `SOCKET_LIB_URL` removed.** Use `getSocketCallerUserAgent()` from `http-request/user-agent` — see Added.
+
+### Changed (breaking)
+
+- **`versions` API renamed.** `compareVersions` → `compare`, `isEqual` → `eq` (+ new `neq`), `isLessThan(OrEqual)` → `lt`/`lte`, `isGreaterThan(OrEqual)` → `gt`/`gte`, `sortVersions` → `sort`, `sortVersionsDesc` → `rsort`. Runs through `node:smol-versions` when present, falls back to `semver`.
+- **`dlx/manifest` `ManifestEntry` → `DlxManifestEntry`** (disambiguates from `eco/types` `ManifestEntry`).
+- **`dlx/arborist getBaseArboristOptions`** second arg is now `{ quiet }` instead of positional `quiet: boolean`.
+- **Predicates renamed for scope clarity** — cwd/process-scoped predicates now carry the scope in the name.
+- **Default `User-Agent` header** now `socketsecurity-lib/<version> node/<node-version> <platform>/<arch>` (was `socketsecurity-lib/<version> (<url>)`).
 
 ### Added
 
-- **45 new `primordials` exports** rounding out the surface to 296 total:
-  - `BigIntCtor`
-  - Math: 24 methods (Acos, Atan2, Hypot, Pow, etc.) + 8 constants (E, PI, SQRT2, etc.); `MathF16round` typed `| undefined` for ES2025
-  - Number constants: `EPSILON`, `MAX_SAFE_INTEGER`, `MAX_VALUE`, `MIN_SAFE_INTEGER`, `MIN_VALUE`, `NEGATIVE_INFINITY`, `POSITIVE_INFINITY`
-  - Symbol: 10 well-knowns (`HasInstance`, `KeyFor`, `Match`, `Species`, etc.); `SymbolAsyncDispose` / `SymbolDispose` typed `| undefined` for ES2024; prototype helpers (`Description`, `ToString`, `ValueOf`)
-  - Function: `FunctionPrototypeToString`
-  - Array (ES2023 Change Array By Copy): `ArrayPrototypeToSpliced`, `ArrayPrototypeWith`
-  - Globals: `InfinityValue`, `NaNValue`, `globalThisRef`
-  - Object (annex B): `ObjectPrototype{Define,Lookup}{Getter,Setter}`
-  - Error (V8 stack-trace API, `| undefined`): `ErrorCaptureStackTrace`, `ErrorPrepareStackTrace`, `ErrorStackTraceLimit` (function-shaped, reads live value)
+- **`http-request/user-agent`** — `buildUserAgent({ name, version }, caller?)` for the canonical three-token UA, and `getSocketCallerUserAgent()` for the lib's own outbound requests. Set `SOCKET_CALLER_USER_AGENT` to append your own identifier to the lib UA (empty/whitespace is ignored).
+- **`packages/operations#pkgNameToSlug(name)`** — `@scope/name` → `scope-name`, plain names unchanged.
+- **`secrets/socket-api-token`** — `readSocketApiToken()` / `readSocketApiTokenSync()` resolve the Socket API token from keychain → `SOCKET_API_TOKEN` (canonical) → `SOCKET_API_KEY` (legacy). Pass `{ allowEnvOnly }` to skip keychain in headless contexts.
+- **`ai/discover` + `ai/spawn`** — locked-down spawn helpers for Claude / Codex / Gemini / OpenCode CLIs. Type-level enforcement of the four lockdown flags (`tools`, `allowedTools`, `disallowedTools`, `permissionMode: 'dontAsk'`). Retries HTTP 529 / "Overloaded" with 5 s / 15 s / 45 s backoff.
+- **`socket-lib check primordials --fix`** — applies suggested rewrites for `.socket-lib.json`-tracked drift.
+- **9 new primordial exports** (305 total) — Array.prototype: `ToLocaleString`, `ToString`. String.prototype: `IsWellFormed` (ES2024), `ToString`, `ToWellFormed` (ES2024), `ValueOf`. Number.prototype: `ToExponential`, `ToPrecision`, `ValueOf`. `StringPrototypeIsWellFormed` routes through `node:smol-primordial` on the smol Node binary — ASCII strings short-circuit to `true` without an O(n) lone-surrogate scan.
+
+### Fixed
+
+- **pnpm v9 `isDev` derivation.** Snapshot entries were stuck at `depType: 'prod'` because v9 dropped the per-snapshot `dev` marker. Now derived per-package across all importer blocks; ties go to prod, matching pnpm's resolver.
+- **yarn `dependenciesMeta` inversion.** A child's `optional: true` was flipping the parent's `isOptional`; flags now refer to the child as declared.
+- **pnpm v9 phantom PackageRef.** Block-shape importer entries emitted a parent ref with `version: ''` before the indented `version:` was consumed.
+- **pnpm v9 protocol filter.** `workspace:`, `file:`, and `link:` importer values are no longer surfaced as registry refs.
+- **npm v1 alias extraction.** Aliased installs (`"alias": { "version": "npm:<real>@<ver>" }`) now surface the real `{ name, version }`; the alias key is preserved on `_index`.
+- **npm v2/v3 workspace + alias name preference.** Path-keyed workspace entries and aliased installs honor the explicit `pkg.name` over the path-derived fallback.
+
+### Migration
+
+```diff
+- import { safeDelete, readJson } from '@socketsecurity/lib/fs'
++ import { safeDelete } from '@socketsecurity/lib/fs/safe'
++ import { readJson } from '@socketsecurity/lib/fs/read-json'
+
+- import { httpJson } from '@socketsecurity/lib/http-request'
++ import { httpJson } from '@socketsecurity/lib/http-request/convenience'
 
-- **`smol/*` (new exports)** — feature-detect + lazy-loaders for socket-btm's smol Node binary:
-  - `smol/detect` — `isSmol()`: memoized boolean, mirrors `isSeaBinary()`
-  - `smol/util` — `getSmolUtil()`: native `uncurryThis` / `applyBind` (~2x faster), or `undefined`
-  - `smol/primordial` — `getSmolPrimordial()`: V8 Fast API typed `Math.*` / `Number.is*` (~30-50% faster on hot loops), or `undefined`
-  - `primordials` transparently routes through these on smol; **zero call-site changes**, identical behavior on stock Node, smol, browsers, Deno, Bun
+- import { compareVersions, isLessThan, sortVersions } from '@socketsecurity/lib/versions'
+- compareVersions(a, b); isLessThan(a, b); sortVersions(arr)
++ import { compare, lt, sort } from '@socketsecurity/lib/versions/compare'
++ compare(a, b); lt(a, b); sort(arr)
+```
+
+## [5.28.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.28.0) - 2026-05-06
+
+### Added
+
+- **`compression` (new)** — brotli + gzip helpers with in-memory `Buffer`, file-to-file (with `{ inPlace: true }`), and stream-creator shapes. Detection (`isBrotliCompressed` / `isGzipCompressed` magic-byte sniffing), extension classification (`hasBrotliExt` / `hasGzipExt`), `BROTLI_EXTS` / `GZIP_EXTS` constants, `stripExt(path, exts)`, and `CompressOptions` / `CompressFileOptions` types.
+- **`socket-lib` CLI** — `pnpm exec socket-lib <command>` dispatcher. First subcommand: `check primordials` (alias `check prim`) diffs source-destructured primordials against the lib's set. Reads `.socket-lib.json` (or `.config/socket-lib.json`). Flags: `--config`, `--explain`, `--json`, `--silent`, `--help`.
+- **`dlx/package` `installRoot`** option overrides the Arborist install root (default `~/.socket/_dlx/<cacheKey>/`). Useful for colocating installs with consumer-owned build outputs.
+
+## [5.27.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.27.0) - 2026-05-04
+
+### Added
 
-- **`node/*` (new exports)** — per-builtin lazy-loaders for `node:*` modules. Each is `/*@__NO_SIDE_EFFECTS__*/`-marked so bundlers tree-shake the `require()` when unused:
-  - `node/fs` (`getNodeFs`), `node/path` (`getNodePath`), `node/crypto` (`getNodeCrypto`), `node/http` (`getNodeHttp`), `node/https` (`getNodeHttps`), `node/os` (`getNodeOs`), `node/util` (`getNodeUtil`), `node/url` (`getNodeUrl`), `node/events` (`getNodeEvents`)
-  - `node/child-process` (`getNodeChildProcess`), `node/async-hooks` (`getNodeAsyncHooks`), `node/fs-promises` (`getNodeFsPromises`), `node/timers-promises` (`getNodeTimersPromises`)
-  - Replaces ~30 ad-hoc copies of the same lazy-loader boilerplate previously scattered across `http-request.ts`, `spawn.ts`, `fs.ts`, `crypto.ts`, etc.
+- **45 new `primordials` exports** (296 total) — `BigIntCtor`; 24 `Math.*` methods + 8 constants (`MathF16round` typed `| undefined` for ES2025); 7 `Number` constants; 10 `Symbol` well-knowns + 3 prototype helpers (`SymbolAsyncDispose` / `SymbolDispose` typed `| undefined`); `FunctionPrototypeToString`; ES2023 array-copy (`ArrayPrototypeToSpliced`, `ArrayPrototypeWith`); `InfinityValue` / `NaNValue` / `globalThisRef`; `ObjectPrototype{Define,Lookup}{Getter,Setter}`; V8 stack-trace API.
+- **`smol/*`** — feature-detect for socket-btm's smol Node binary. `smol/detect` (`isSmol()`), `smol/util` (`getSmolUtil()` — native `uncurryThis` / `applyBind`), `smol/primordial` (`getSmolPrimordial()` — V8 Fast API typed `Math.*` / `Number.is*`). `primordials` routes through these on smol transparently; no call-site changes.
+- **`node/*`** — per-builtin lazy-loaders, side-effect-free for tree-shaking: `node/fs`, `node/path`, `node/crypto`, `node/http`, `node/https`, `node/os`, `node/util`, `node/url`, `node/events`, `node/child-process`, `node/async-hooks`, `node/fs-promises`, `node/timers-promises`.
 
 ## [5.26.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.1) - 2026-05-01
 
@@ -78,12 +178,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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
+- `globs` `getGlobMatcher` — `path.matchesGlob` fast-path only activates when the caller opts out of both picomatch defaults (`nocase: false` AND `dot: false`); previously took the fast-path under default options and silently broke case-insensitive matching.
+- `globs` `glob` / `globSync` — results normalized to forward slashes on Windows regardless of backend (`node:fs.glob` returns native-OS separators).
+- `globs` `glob` / `globSync` / `globStreamLicenses` — trailing `/` stripped from `ignore` patterns before passing to fast-glob (gitignore-style `dist/` was silently dropped at the deep-filter level). Workaround for [mrmlnc/fast-glob#437](https://github.com/mrmlnc/fast-glob/issues/437).
+- GitHub helpers (`releases/github-api`, `github/resolveRefToSha`, `fetchGhsaDetails`) fall back to GraphQL on the "search-degraded" 200 OK + empty body shape. Real 404s / rate-limits / 5xx still propagate.
 
 ## [5.26.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.26.0) - 2026-04-27
 

package/README.md

@@ -2,20 +2,24 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/lib)](https://socket.dev/npm/package/@socketsecurity/lib)
 [![CI](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-lib/actions/workflows/ci.yml)
-![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-99%25-brightgreen)
 
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
 Core utilities for [Socket.dev](https://socket.dev/) tools: file system, processes, HTTP, env detection, logging, spinners, and more. Tree-shakeable, TypeScript-first, cross-platform.
 
+## Why this repo exists
+
+`@socketsecurity/lib` is the shared utility layer for every Socket.dev tool (the CLI, SDK, registry, MCP server, build infrastructure). It exists so we ship one battle-tested implementation of "spawn a child", "fetch JSON with retries", "delete a path safely on Windows + POSIX", etc. — rather than ten subtly different ones across the fleet. Every export is reachable via a subpath import, so tree-shaking keeps your bundle lean.
+
 ## Install
 
-```bash
+```sh
 pnpm add @socketsecurity/lib
 ```
 
-## Quick Start
+## Usage
 
 ```typescript
 import { Spinner } from '@socketsecurity/lib/spinner'
@@ -35,24 +39,14 @@ import { httpJson } from '@socketsecurity/lib/http-request'
 import { safeDelete } from '@socketsecurity/lib/fs'
 ```
 
-## Documentation
-
 Start with the [API Index](./docs/api-index.md) — every subpath export with a one-line description.
 
-- [Getting Started](./docs/getting-started.md) – install + first examples
-- [Visual Effects](./docs/visual-effects.md) – spinners, loggers, themes
-- [File System](./docs/file-system.md) – files, globs, paths, safe deletion
-- [HTTP Utilities](./docs/http-utilities.md) – requests, downloads, retries
-- [Process Utilities](./docs/process-utilities.md) – spawn, IPC, locks
-- [Package Management](./docs/package-management.md) – npm/pnpm/yarn detection
-- [Environment](./docs/environment.md) – CI/platform detection, env getters
-- [Constants](./docs/constants.md) – Node versions, npm URLs, platform values
-- [Examples](./docs/examples.md) – real-world patterns
-- [Troubleshooting](./docs/troubleshooting.md) – common issues
-
 ## Development
 
-```bash
+<details>
+<summary>Contributor commands</summary>
+
+```sh
 pnpm install          # install
 pnpm build            # build
 pnpm test             # run tests
@@ -64,6 +58,21 @@ pnpm run fix          # auto-fix formatting
 
 See [CLAUDE.md](./CLAUDE.md) for contributor guidelines.
 
+### Documentation map
+
+- [Getting Started](./docs/getting-started.md) – install + first examples
+- [Visual Effects](./docs/visual-effects.md) – spinners, loggers, themes
+- [File System](./docs/file-system.md) – files, globs, paths, safe deletion
+- [HTTP Utilities](./docs/http-utilities.md) – requests, downloads, retries
+- [Process Utilities](./docs/process-utilities.md) – spawn, IPC, locks
+- [Package Management](./docs/package-management.md) – npm/pnpm/yarn detection
+- [Environment](./docs/environment.md) – CI/platform detection, env getters
+- [Constants](./docs/constants.md) – Node versions, npm URLs, platform values
+- [Examples](./docs/examples.md) – real-world patterns
+- [Troubleshooting](./docs/troubleshooting.md) – common issues
+
+</details>
+
 ## License
 
 MIT

package/dist/abort/signal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Abort signal utilities — composite signal construction from multiple
+ *   sources and timeout-driven signal creation.
+ */
+/**
+ * Create a composite AbortSignal from multiple signals.
+ *
+ * @example
+ *   ;```typescript
+ *   const ac1 = new AbortController()
+ *   const ac2 = new AbortController()
+ *   const signal = createCompositeAbortSignal(ac1.signal, ac2.signal)
+ *   ```
+ */
+export declare function createCompositeAbortSignal(...signals: Array<AbortSignal | null | undefined>): AbortSignal;
+/**
+ * Create an AbortSignal that triggers after a timeout.
+ *
+ * @example
+ *   ;```typescript
+ *   const signal = createTimeoutSignal(5000) // aborts after 5 seconds
+ *   fetch('https://example.com', { signal })
+ *   ```
+ *
+ * @throws {TypeError} If `ms` is not a number, is NaN, is not finite, or is not
+ *   positive.
+ */
+export declare function createTimeoutSignal(ms: number): AbortSignal;

package/dist/{abort.js → abort/signal.js}

@@ -18,13 +18,15 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var abort_exports = {};
-__export(abort_exports, {
+var signal_exports = {};
+__export(signal_exports, {
   createCompositeAbortSignal: () => createCompositeAbortSignal,
   createTimeoutSignal: () => createTimeoutSignal
 });
-module.exports = __toCommonJS(abort_exports);
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(signal_exports);
+var import_error = require("../primordials/error");
+var import_math = require("../primordials/math");
+var import_number = require("../primordials/number");
 function createCompositeAbortSignal(...signals) {
   const validSignals = signals.filter((s) => s != null);
   if (validSignals.length === 0) {
@@ -44,16 +46,16 @@ function createCompositeAbortSignal(...signals) {
   return controller.signal;
 }
 function createTimeoutSignal(ms) {
-  if (typeof ms !== "number" || (0, import_primordials.NumberIsNaN)(ms)) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a number");
+  if (typeof ms !== "number" || (0, import_number.NumberIsNaN)(ms)) {
+    throw new import_error.TypeErrorCtor("timeout must be a number");
   }
-  if (!(0, import_primordials.NumberIsFinite)(ms)) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a finite number");
+  if (!(0, import_number.NumberIsFinite)(ms)) {
+    throw new import_error.TypeErrorCtor("timeout must be a finite number");
   }
   if (ms <= 0) {
-    throw new import_primordials.TypeErrorCtor("timeout must be a positive number");
+    throw new import_error.TypeErrorCtor("timeout must be a positive number");
   }
-  return AbortSignal.timeout((0, import_primordials.MathCeil)(ms));
+  return AbortSignal.timeout((0, import_math.MathCeil)(ms));
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/ai/discover.d.mts

@@ -0,0 +1,50 @@
+/**
+ * @file Detect which AI agent CLIs are installed on PATH. Strategy:
+ *   which()-based lookup with a two-tier cache:
+ *
+ *   1. In-process Map — survives until the Node process exits.
+ *   2. On-disk JSON at `<repo>/.cache/agent-discovery.json`, TTL 1h — survives
+ *      across subprocess invocations (per-file ai-lint-fix batches) without
+ *      re-running which(). Cache invalidation: stale on-disk cache is detected
+ *      by mtime comparison; missing or expired → fresh which() pass + rewrite.
+ *      Why two tiers: hooks and skills spawn dozens of short-lived Node
+ *      processes per session. In-process alone misses the cross-process
+ *      speedup; on-disk alone hits the filesystem on every call. The
+ *      combination keeps repeated lookups under a millisecond after the
+ *      cold-start cost.
+ */
+import type { DiscoveredAgents } from './types.mts';
+export declare function cachePathFor(repoRoot: string): string;
+/**
+ * Discover which AI agent CLIs are installed.
+ *
+ * @param options.repoRoot - Where to read/write the on-disk cache. Defaults to
+ *   process.cwd(). Skill runners typically pass the target repo's root.
+ * @param options.refresh - When true, bypass both caches and re-run which().
+ *   Useful after `npm i -g <agent>` mid-session.
+ *
+ *   Returns a map of agent → absolute binary path. Agents that aren't installed
+ *   are absent from the map (not present-with-undefined), so callers can use
+ *   `'claude' in agents` for the existence check.
+ */
+export declare function discoverAiAgents(options?: {
+    readonly refresh?: boolean;
+    readonly repoRoot?: string;
+}): Promise<DiscoveredAgents>;
+export declare function discoverFresh(): DiscoveredAgents;
+/**
+ * Synchronous in-process lookup. Skips disk cache + which(). Returns undefined
+ * if discoverAiAgents() hasn't been called yet in this process, OR returns the
+ * most recent discovery result.
+ *
+ * Useful in fast paths where the caller has already populated the cache and
+ * just wants to read it back.
+ */
+export declare function getDiscoveredAiAgents(): DiscoveredAgents | undefined;
+export declare function readDiskCache(cachePath: string): DiscoveredAgents | undefined;
+/**
+ * Reset the in-process cache. Tests use this; production callers shouldn't need
+ * it (use `refresh: true` on discoverAiAgents()).
+ */
+export declare function resetAiAgentDiscoveryCache(): void;
+export declare function writeDiskCache(cachePath: string, agents: DiscoveredAgents): Promise<void>;

package/dist/ai/discover.js

@@ -0,0 +1,128 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var discover_exports = {};
+__export(discover_exports, {
+  cachePathFor: () => cachePathFor,
+  discoverAiAgents: () => discoverAiAgents,
+  discoverFresh: () => discoverFresh,
+  getDiscoveredAiAgents: () => getDiscoveredAiAgents,
+  readDiskCache: () => readDiskCache,
+  resetAiAgentDiscoveryCache: () => resetAiAgentDiscoveryCache,
+  writeDiskCache: () => writeDiskCache
+});
+module.exports = __toCommonJS(discover_exports);
+var import_node_fs = require("node:fs");
+var import_promises = require("node:fs/promises");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_which = require("../bin/which");
+var import_message = require("../errors/message");
+var import_default = require("../logger/default");
+var import_json = require("../primordials/json");
+const logger = (0, import_default.getDefaultLogger)();
+const KNOWN_AGENTS = [
+  "claude",
+  "codex",
+  "gemini",
+  "opencode"
+];
+const CACHE_TTL_MS = 60 * 60 * 1e3;
+let inProcessCache;
+function cachePathFor(repoRoot) {
+  return import_node_path.default.join(repoRoot, ".cache", "agent-discovery.json");
+}
+async function discoverAiAgents(options = {}) {
+  const { refresh = false, repoRoot = process.cwd() } = options;
+  if (!refresh && inProcessCache) {
+    return inProcessCache;
+  }
+  const cachePath = cachePathFor(repoRoot);
+  if (!refresh) {
+    const fromDisk = readDiskCache(cachePath);
+    if (fromDisk) {
+      inProcessCache = fromDisk;
+      return fromDisk;
+    }
+  }
+  const fresh = discoverFresh();
+  inProcessCache = fresh;
+  await writeDiskCache(cachePath, fresh);
+  return fresh;
+}
+function discoverFresh() {
+  const out = {};
+  for (const name of KNOWN_AGENTS) {
+    const found = (0, import_which.whichSync)(name);
+    if (typeof found === "string" && found) {
+      out[name] = found;
+    }
+  }
+  return out;
+}
+function getDiscoveredAiAgents() {
+  return inProcessCache;
+}
+function readDiskCache(cachePath) {
+  if (!(0, import_node_fs.existsSync)(cachePath)) {
+    return void 0;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(cachePath, "utf8");
+    const parsed = (0, import_json.JSONParse)(raw);
+    if (typeof parsed !== "object" || parsed === null || typeof parsed.writtenAt !== "number" || Date.now() - parsed.writtenAt > CACHE_TTL_MS) {
+      return void 0;
+    }
+    return parsed.agents;
+  } catch {
+    return void 0;
+  }
+}
+function resetAiAgentDiscoveryCache() {
+  inProcessCache = void 0;
+}
+async function writeDiskCache(cachePath, agents) {
+  try {
+    await (0, import_promises.mkdir)(import_node_path.default.dirname(cachePath), { recursive: true });
+    const payload = { agents, writtenAt: Date.now() };
+    (0, import_node_fs.writeFileSync)(cachePath, (0, import_json.JSONStringify)(payload, void 0, 2) + "\n");
+  } catch (e) {
+    logger.error(`discoverAiAgents: cache write failed (${(0, import_message.errorMessage)(e)})`);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cachePathFor,
+  discoverAiAgents,
+  discoverFresh,
+  getDiscoveredAiAgents,
+  readDiskCache,
+  resetAiAgentDiscoveryCache,
+  writeDiskCache
+});

package/dist/ai/profiles.d.mts

@@ -0,0 +1,39 @@
+/**
+ * @file Pre-built lockdown profiles for spawnAiAgent. Per CLAUDE.md
+ *   "Programmatic Claude calls" rule: every spawn must set tools / disallow /
+ *   permissionMode (and the helper always sets --no-session-persistence +
+ *   --add-dir cwd). These profiles are canonical safe defaults that callers
+ *   spread + override per call. Choose by capability:
+ *
+ *   - `READ_ONLY_PROFILE` — research / scanning. Read + Grep + Glob
+ *   - WebFetch + WebSearch. No Edit, no Write, no Bash. Use for static analysis
+ *     skills (scanning-quality, scanning-security).
+ *   - `EDIT_ONLY_PROFILE` — fix-mode. Read + Edit + Grep + Glob. Bash explicitly
+ *     denied. Use for skills that mutate source files but don't run arbitrary
+ *     shell (ai-lint-fix, refactor passes).
+ *   - `FULL_FIX_PROFILE` — fix-mode WITH Bash. Read + Edit + Write + Grep + Glob
+ *   - Bash (allowlisted to git/pnpm/node by default). Use for skills that need to
+ *     commit, run tests, install deps. No `WIDE_OPEN_PROFILE` exists by design
+ *     — letting an agent run arbitrary tools is the lockdown rule's exact
+ *     failure mode.
+ */
+import type { PermissionMode } from './types.mts';
+interface Profile {
+    readonly allow: readonly string[];
+    readonly disallow: readonly string[];
+    readonly permissionMode: PermissionMode;
+    readonly tools: readonly string[];
+}
+/**
+ * Read-only research / scanning. No mutation.
+ */
+export declare const READ_ONLY_PROFILE: Profile;
+/**
+ * Edit-mode without Bash. Mutates source but can't run shell.
+ */
+export declare const EDIT_ONLY_PROFILE: Profile;
+/**
+ * Fix-mode with Bash, allowlisted to git / pnpm / node.
+ */
+export declare const FULL_FIX_PROFILE: Profile;
+export {};