@socketsecurity/lib 5.19.1 → 5.21.0

package/CHANGELOG.md

@@ -5,62 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
+## [5.21.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.21.0) - 2026-04-20
+
+### Added
 
-### Fixed — stdio (restore accidentally-dropped modules)
+- `@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
 
-5.19.0 shipped a breaking change that was not called out in its changelog or version bump: a refactor commit removed `stdio/prompts`, `stdio/progress`, `stdio/clear`, and the vendored `external/@inquirer/*` shims. socket-cli and other consumers import `stdio/prompts` directly and broke on upgrade.
+### Changed
 
-Restored:
+- `@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`
 
-- `@socketsecurity/lib/stdio/prompts` — inquirer wrappers (`password`, `confirm`, `input`, `select`, `checkbox`, `search`)
-- `@socketsecurity/lib/stdio/progress` — progress-bar utility (`ProgressBar` class)
-- `@socketsecurity/lib/stdio/clear` — terminal line/screen/cursor helpers
-- `src/external/@inquirer/{checkbox,confirm,input,password,search,select}.js` vendor shims
-- Corresponding test suites
+### Removed
 
-## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
+- `@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
 
-### Added — dlx/integrity (new module)
+### 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
 
-- `HashSpec`, `NormalizedHash`, `ComputedHashes` types. `HashSpec` accepts a bare string (sha512 SRI or sha256 hex, sniffed) or an explicit `{ type, value }` object
-- `normalizeHash()`, `computeHashes()`, `verifyHash()` — `verifyHash` uses `crypto.timingSafeEqual` for constant-time comparison
-- `DlxHashMismatchError` — carries `expected` + `actual` for diagnostics
+### Performance
 
-### Added — dlx/arborist (new module)
+- `@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
 
-- `safeIdealTree()`, `safeReify()` — hardened `@npmcli/arborist` wrappers mirroring socket-cli v1.1.79 `SafeArborist` overrides (`audit: false`, `fund: false`, `ignoreScripts: true`, `progress: false`, `saveBundle: false`, `silent: true`)
-- `writeSafeNpmrc()` — defense-in-depth `.npmrc` writer matching the Arborist overrides
-- Optional `before?: Date` on `safeIdealTree` for release-age enforcement during resolution
+## [5.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
 
-### Added — dlx/lockfile (new module)
+### Fixed
 
-- `generatePackagePin({ package, minReleaseDays?, minReleaseMins? })` — returns `PinDetails { name, version, hash: ComputedHashes, packageJson, lockfile }`. Runs Arborist in `packageLockOnly: true` mode against a tmp directory and auto-cleans
-- **Default `minReleaseDays: 7`** — resolution refuses to select versions published in the last week. Pass `0` to disable. `minReleaseMins` is a pnpm-style alias (mutually exclusive with `minReleaseDays`)
-- `LockfileSpec` type — export for use as the new `lockfile` option on `downloadPackage`
+- `@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
 
-### Added — dlx existing modules
+## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
 
-- `DlxPackageOptions.hash?: HashSpec` and `DlxPackageOptions.lockfile?: LockfileSpec` — passing a lockfile materializes it into the install dir (path → `fs.copyFileSync`, content → `fs.writeFileSync`) and drops a hardened `.npmrc` alongside before Arborist runs
-- `DlxBinaryOptions.hash?: HashSpec` — ergonomic alternative to the lower-level `integrity` and `sha256` fields (both still accepted)
+### Added
 
-### Fixed — external
+- `@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
 
-- `pacote` shim now exposes `tarball`, `manifest`, `packument` alongside `extract`. **Fixes a latent runtime crash** in `src/packages/manifest.ts` callers (`fetchPackageManifest` / `fetchPackagePackument` called `.manifest(...)` / `.packument(...)` on a shim that previously only had `extract`, raising `TypeError: not a function`)
+> **Deprecated in 5.21.0**: moved to `@socketsecurity/lib/schema/*`.
 
-### Changed — build (bundle size)
+### Fixed
 
-- `dist/external/npm-pack.js`: 2,526,598 → 1,755,460 bytes (−771 KB, −30.5%). New `STUB_MAP` entries for code paths our callers never reach:
-  - `@sigstore/{bundle,core,protobuf-specs,sign,tuf,verify}`, `sigstore`, `tuf-js`, `@tufjs/{canonical-json,models}` — Sigstore attestation, only reached via `arb.audit()`
-  - `@npmcli/metavuln-calculator` — audit-only
-  - `@npmcli/query`, `postcss-selector-parser` — `arb.query()` unused
-  - `@npmcli/run-script`, `@npmcli/node-gyp` — guarded out by `ignoreScripts: true`
-  - `@npmcli/git`, `pacote/lib/{git,file,dir,remote}.js` — registry specs only
-  - arborist `audit-report.js`, `yarn-lock.js`, `isolated-reifier.js`, `query-selector-all.js`, `printable.js` — each gated or unused
-  - `cacache/lib/verify.js` — `cacache.verify` (npm cache verify) unused
-  - `proggy` — progress tracker, gated by `progress: false`
-  - `debug/src/browser.js` — Node-only bundle
-- `dist/external/zod.js`: 597,238 → 291,430 bytes (−306 KB, −51.2%). Stubbed `zod/v4/{core,classic,mini}`'s eager `locales/index.cjs` barrel (40+ translation modules). Opt-in via `z.config(z.locales.xx())` is never called by us
+- `@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
+
+## [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.
+
+## [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
+
+### Fixed
+
+- `pacote` shim — exposes `tarball`, `manifest`, `packument` alongside `extract`. Fixes a latent runtime crash in `fetchPackageManifest` / `fetchPackagePackument` callers
+
+### Changed
+
+Reduced bundle size of `dist/external/npm-pack.js` (−771 KB, −30.5%) and `dist/external/zod.js` (−306 KB, −51.2%) by stubbing code paths our callers never reach (Sigstore attestation, arborist audit/query, zod locale translations, etc.)
 
 ## [5.18.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.2) - 2026-04-14
 
@@ -70,70 +108,63 @@ Restored:
 
 ## [5.18.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.1) - 2026-04-14
 
-### Changed — build
+### Changed
 
-- Dedup npm-pack.js bundle via pnpm overrides: pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive npm packages (npm-bundled, npm-normalize-package-bin, json-parse-even-better-errors, @npmcli/installed-package-contents, @npmcli/name-from-folder, @npmcli/promise-spawn, @npmcli/redact)
-- npm-pack.js: 69,738 → 66,443 lines (2.59MB → 2.46MB), 22 duplicate packages removed
+- Deduplicated the `dist/external/npm-pack` bundle via `pnpm overrides` (pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive `@npmcli/*` packages) — 22 duplicate packages removed, ~130 KB smaller
 
 ## [5.18.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.0) - 2026-04-14
 
-### Added — dlx
+### Added
 
-- Socket Firewall API check before package downloads — resolves dependency tree via `buildIdealTree`, checks all packages against `firewall-api.socket.dev/purl` in parallel, blocks on critical/high severity alerts
+- `@socketsecurity/lib/dlx` — Socket Firewall API check before package downloads. Resolves the dependency tree and blocks on critical/high severity alerts
 
-### Changed — http-request
+### Changed
 
-- Default `User-Agent` header updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
+- `@socketsecurity/lib/http-request` — default `User-Agent` updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
 
 ## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `isUnixPath()` — detect MSYS/Git Bash drive letter notation (`/c/...`)
+- `@socketsecurity/lib/paths` `isUnixPath()` — detect MSYS/Git Bash drive-letter notation (`/c/...`)
 
-### Changed — paths
+### Changed
 
-- `normalizePath()` now converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
-- `fromUnixPath()` now produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
+- `@socketsecurity/lib/paths` `normalizePath()` — converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
 
 ## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
 
-### Fixed — dlx
+### Fixed
 
-- Normalize dlx directory path in `isInSocketDlx` for Windows compatibility
+- `@socketsecurity/lib/dlx` `isInSocketDlx` — normalize the dlx directory path for Windows compatibility
 
 ## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
 
-### Added — http-request
-
-- `stream` option on `HttpRequestOptions` — resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
-- `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
-
-### Changed — http-request
+### Added
 
-- `httpDownload` now uses `httpRequest` with `stream: true` internally, eliminating ~120 lines of duplicated HTTP plumbing
+- `@socketsecurity/lib/http-request` — `stream` option on `HttpRequestOptions` resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
+- `@socketsecurity/lib/http-request` — `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
 
 ## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
 
-### Added — http-request
+### Added
 
-- `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled, carries the full `HttpResponse`
-- `throwOnError` option on `HttpRequestOptions` — non-2xx responses throw instead of resolving with `ok: false`, enabling retry of HTTP errors
-- `onRetry` callback on `HttpRequestOptions` — customize retry behavior per-attempt (return `false` to stop, a `number` to override delay, `undefined` for default backoff)
-- Streaming body support — `body` accepts `Readable` streams (incl. `form-data` npm package), auto-merges `getHeaders()` when present
-- `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 `Retry-After` header parser (strict integer seconds + HTTP-date formats)
-- `sanitizeHeaders()` — redact sensitive headers (`authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `proxy-authenticate`, `www-authenticate`) for safe logging
+- `@socketsecurity/lib/http-request`:
+  - `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled; carries the full `HttpResponse`
+  - `throwOnError` option — non-2xx responses throw instead of resolving with `ok: false`
+  - `onRetry` callback — customize retry behavior per-attempt (`false` to stop, a `number` to override delay, `undefined` for default backoff)
+  - Streaming body support — `body` accepts `Readable` streams (incl. `form-data`), auto-merges `getHeaders()` when present
+  - `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 parser
+  - `sanitizeHeaders()` — redact sensitive headers for safe logging
 
-### Changed — http-request
+### Changed
 
-- `HttpRequestOptions.body` type widened from `Buffer | string` to `Buffer | Readable | string`
-- Redirect responses now drained via `res.resume()` to free sockets
-- `maxResponseSize` exceeded now cleans up both response and request
-- `onResponse` hooks wrapped in try/catch — user hook errors can no longer leave promises pending
+- `@socketsecurity/lib/http-request` — `HttpRequestOptions.body` widened to `Buffer | Readable | string`; `onResponse` hook errors no longer leave promises pending
 
 ## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
 

package/dist/archives.js

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

package/dist/cacache.js

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

package/dist/cache-with-ttl.d.ts

@@ -126,6 +126,13 @@ export interface TtlCacheOptions {
      * @default true
      */
     memoize?: boolean | undefined;
+    /**
+     * Maximum number of entries to keep in the in-memory memo cache. When
+     * exceeded, the least-recently-used entry is evicted. The persistent
+     * (cacache) layer is unaffected.
+     * @default 1000
+     */
+    memoMaxSize?: number | undefined;
     /**
      * Custom cache key prefix.
      * Must not contain wildcards (*).

package/dist/cache-with-ttl.js

@@ -36,10 +36,12 @@ module.exports = __toCommonJS(cache_with_ttl_exports);
 var cacache = __toESM(require("./cacache"));
 const DEFAULT_TTL_MS = 5 * 60 * 1e3;
 const DEFAULT_PREFIX = "ttl-cache";
+const DEFAULT_MEMO_MAX_SIZE = 1e3;
 function createTtlCache(options) {
   const opts = {
     __proto__: null,
     memoize: true,
+    memoMaxSize: DEFAULT_MEMO_MAX_SIZE,
     prefix: DEFAULT_PREFIX,
     ttl: DEFAULT_TTL_MS,
     ...options
@@ -50,6 +52,18 @@ function createTtlCache(options) {
     );
   }
   const memoCache = /* @__PURE__ */ new Map();
+  const memoMaxSize = Math.max(1, opts.memoMaxSize ?? DEFAULT_MEMO_MAX_SIZE);
+  function memoSet(fullKey, entry) {
+    if (memoCache.has(fullKey)) {
+      memoCache.delete(fullKey);
+    } else if (memoCache.size >= memoMaxSize) {
+      const oldest = memoCache.keys().next().value;
+      if (oldest !== void 0) {
+        memoCache.delete(oldest);
+      }
+    }
+    memoCache.set(fullKey, entry);
+  }
   const ttl = opts.ttl ?? DEFAULT_TTL_MS;
   function buildKey(key) {
     return `${opts.prefix}:${key}`;
@@ -70,7 +84,7 @@ function createTtlCache(options) {
     }
     const escaped = fullPattern.replaceAll(/[.+?^${}()|[\]\\]/g, "\\$&");
     const regexPattern = escaped.replaceAll("*", ".*");
-    const regex = new RegExp(`^${regexPattern}`);
+    const regex = new RegExp(`^${regexPattern}$`);
     return (key) => regex.test(key);
   }
   async function get(key) {
@@ -83,6 +97,7 @@ function createTtlCache(options) {
     if (opts.memoize) {
       const memoEntry = memoCache.get(fullKey);
       if (memoEntry && !isExpired(memoEntry)) {
+        memoSet(fullKey, memoEntry);
         return memoEntry.data;
       }
       if (memoEntry) {
@@ -103,7 +118,7 @@ function createTtlCache(options) {
       }
       if (!isExpired(entry)) {
         if (opts.memoize) {
-          memoCache.set(fullKey, entry);
+          memoSet(fullKey, entry);
         }
         return entry.data;
       }
@@ -158,7 +173,7 @@ function createTtlCache(options) {
         }
         results.set(originalKey, parsed.data);
         if (opts.memoize) {
-          memoCache.set(cacheEntry.key, parsed);
+          memoSet(cacheEntry.key, parsed);
         }
       } catch {
       }
@@ -177,7 +192,7 @@ function createTtlCache(options) {
       expiresAt: Date.now() + ttl
     };
     if (opts.memoize) {
-      memoCache.set(fullKey, entry);
+      memoSet(fullKey, entry);
     }
     try {
       await cacache.put(fullKey, JSON.stringify(entry), {
@@ -188,14 +203,18 @@ function createTtlCache(options) {
   }
   const inflightRequests = /* @__PURE__ */ new Map();
   async function getOrFetch(key, fetcher) {
+    const fullKey = buildKey(key);
+    const preexisting = inflightRequests.get(fullKey);
+    if (preexisting) {
+      return await preexisting;
+    }
     const cached = await get(key);
     if (cached !== void 0) {
       return cached;
     }
-    const fullKey = buildKey(key);
-    const existing = inflightRequests.get(fullKey);
-    if (existing) {
-      return await existing;
+    const rechecked = inflightRequests.get(fullKey);
+    if (rechecked) {
+      return await rechecked;
     }
     const promise = (async () => {
       try {

package/dist/constants/socket.js

@@ -77,7 +77,7 @@ const SOCKET_FIREWALL_APP_NAME = "sfw";
 const SOCKET_REGISTRY_APP_NAME = "registry";
 const SOCKET_APP_PREFIX = "_";
 const SOCKET_LIB_NAME = "@socketsecurity/lib";
-const SOCKET_LIB_VERSION = "5.19.1";
+const SOCKET_LIB_VERSION = "5.21.0";
 const SOCKET_LIB_URL = "https://github.com/SocketDev/socket-lib";
 const SOCKET_LIB_USER_AGENT = `socketsecurity-lib/${SOCKET_LIB_VERSION} (${SOCKET_LIB_URL})`;
 const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";

package/dist/dlx/detect.js

@@ -33,7 +33,20 @@ var import_socket = require("../paths/socket");
 let _fs;
 let _path;
 const NODE_JS_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs"]);
+const PACKAGE_JSON_PATH_CACHE_MAX_SIZE = 200;
+const PACKAGE_JSON_NEGATIVE_TTL_MS = 1e4;
 const packageJsonPathCache = /* @__PURE__ */ new Map();
+function packageJsonPathCacheSet(key, value) {
+  if (packageJsonPathCache.has(key)) {
+    packageJsonPathCache.delete(key);
+  } else if (packageJsonPathCache.size >= PACKAGE_JSON_PATH_CACHE_MAX_SIZE) {
+    const oldest = packageJsonPathCache.keys().next().value;
+    if (oldest !== void 0) {
+      packageJsonPathCache.delete(oldest);
+    }
+  }
+  packageJsonPathCache.set(key, { path: value, at: Date.now() });
+}
 const packageJsonContentCache = /* @__PURE__ */ new Map();
 function findPackageJson(filePath) {
   const fs = /* @__PURE__ */ getFs();
@@ -41,25 +54,29 @@ function findPackageJson(filePath) {
   const startDir = path.dirname(path.resolve(filePath));
   const cached = packageJsonPathCache.get(startDir);
   if (cached !== void 0) {
-    if (cached === null) {
-      return void 0;
-    }
-    if (fs.existsSync(cached)) {
-      return cached;
+    if (cached.path === null) {
+      if (Date.now() - cached.at < PACKAGE_JSON_NEGATIVE_TTL_MS) {
+        return void 0;
+      }
+      packageJsonPathCache.delete(startDir);
+    } else if (fs.existsSync(cached.path)) {
+      packageJsonPathCacheSet(startDir, cached.path);
+      return cached.path;
+    } else {
+      packageJsonPathCache.delete(startDir);
     }
-    packageJsonPathCache.delete(startDir);
   }
   let currentDir = startDir;
   const root = path.parse(currentDir).root;
   while (currentDir !== root) {
     const packageJsonPath = path.join(currentDir, "package.json");
     if (fs.existsSync(packageJsonPath)) {
-      packageJsonPathCache.set(startDir, packageJsonPath);
+      packageJsonPathCacheSet(startDir, packageJsonPath);
       return packageJsonPath;
     }
     currentDir = path.dirname(currentDir);
   }
-  packageJsonPathCache.set(startDir, null);
+  packageJsonPathCacheSet(startDir, null);
   return void 0;
 }
 // @__NO_SIDE_EFFECTS__

package/dist/dlx/lockfile.js

@@ -128,7 +128,10 @@ async function generatePackagePin(options) {
       lockfile: ideal.lockfile
     };
   } finally {
-    await (0, import_fs.safeDelete)(scratch, { force: true });
+    try {
+      await (0, import_fs.safeDelete)(scratch, { force: true });
+    } catch {
+    }
   }
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/dlx/manifest.d.ts

@@ -3,10 +3,16 @@
  * Manages persistent caching of DLX package and binary metadata with TTL support
  * and atomic file operations.
  *
- * Key Functions:
- * - getManifestEntry: Retrieve manifest entry by spec
- * - setPackageEntry: Store npm package metadata
- * - setBinaryEntry: Store binary download metadata
+ * Primary API (on {@link DlxManifest}):
+ * - `getManifestEntry(spec)` — retrieve a manifest entry by spec
+ * - `setPackageEntry(spec, key, details)` — store npm package metadata
+ * - `setBinaryEntry(spec, key, details)` — store binary download metadata
+ * - `getAllPackages()` — enumerate cached package names
+ * - `clear(name)` / `clearAll()` — eviction
+ * - `isFresh(record, ttlMs)` — TTL check
+ *
+ * The bare `get(name)` / `set(name, record)` methods are deprecated
+ * legacy shims kept for backward compatibility with pre-5.x callers.
  *
  * Features:
  * - TTL-based cache expiration

package/dist/dlx/package.d.ts

@@ -136,7 +136,7 @@ export interface DlxPackageResult {
  * await result.spawnPromise
  * ```
  */
-export declare function dlxPackage(args: readonly string[] | string[], options?: DlxPackageOptions | undefined, spawnExtra?: SpawnExtra | undefined): Promise<DlxPackageResult>;
+export declare function dlxPackage(args: readonly string[] | string[], options: DlxPackageOptions, spawnExtra?: SpawnExtra | undefined): Promise<DlxPackageResult>;
 /**
  * Download and install a package without executing it.
  * This is useful for self-update or when you need the package files

package/dist/dlx/package.js

@@ -62,7 +62,19 @@ const FIREWALL_BLOCK_SEVERITIES = /* @__PURE__ */ new Set([
   "critical",
   "high"
 ]);
+const BINARY_PATH_CACHE_MAX_SIZE = 200;
 const binaryPathCache = /* @__PURE__ */ new Map();
+function binaryPathCacheSet(key, value) {
+  if (binaryPathCache.has(key)) {
+    binaryPathCache.delete(key);
+  } else if (binaryPathCache.size >= BINARY_PATH_CACHE_MAX_SIZE) {
+    const oldest = binaryPathCache.keys().next().value;
+    if (oldest !== void 0) {
+      binaryPathCache.delete(oldest);
+    }
+  }
+  binaryPathCache.set(key, value);
+}
 async function checkFirewallPurls(arb, requestedPackage) {
   const idealTree = arb.idealTree;
   if (!idealTree) {
@@ -141,7 +153,7 @@ async function dlxPackage(args, options, spawnExtra) {
   const spawnPromise = executePackage(
     downloadResult.binaryPath,
     args,
-    options?.spawnOptions,
+    options.spawnOptions,
     spawnExtra
   );
   return {
@@ -414,9 +426,12 @@ function parsePackageSpec(spec) {
     if (atIndex === -1 || atIndex === 0) {
       return { name: spec, version: void 0 };
     }
+    const sliced = spec.slice(atIndex + 1);
     return {
       name: spec.slice(0, atIndex),
-      version: spec.slice(atIndex + 1)
+      // A trailing `@` (e.g. `'pkg@'`) yields an empty slice — normalize
+      // to undefined so downstream "no version" checks behave.
+      version: sliced || void 0
     };
   }
 }
@@ -428,6 +443,7 @@ function resolveBinaryPath(basePath) {
   const cached = binaryPathCache.get(basePath);
   if (cached) {
     if (fs.existsSync(cached)) {
+      binaryPathCacheSet(basePath, cached);
       return cached;
     }
     binaryPathCache.delete(basePath);
@@ -436,7 +452,7 @@ function resolveBinaryPath(basePath) {
   for (const ext of extensions) {
     const testPath = basePath + ext;
     if (fs.existsSync(testPath)) {
-      binaryPathCache.set(basePath, testPath);
+      binaryPathCacheSet(basePath, testPath);
       return testPath;
     }
   }