@socketsecurity/lib 6.0.0 → 6.0.1

package/CHANGELOG.md

@@ -5,6 +5,77 @@ 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).
 
+## [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
+
+- **`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`).
+
+### 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.

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-98%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/ai/discover.js

@@ -44,9 +44,9 @@ 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_logger = require("../logger/logger");
+var import_default = require("../logger/default");
 var import_json = require("../primordials/json");
-const logger = (0, import_logger.getDefaultLogger)();
+const logger = (0, import_default.getDefaultLogger)();
 const KNOWN_AGENTS = [
   "claude",
   "codex",

package/dist/ai/spawn.js

@@ -29,8 +29,8 @@ __export(spawn_exports, {
 module.exports = __toCommonJS(spawn_exports);
 var import_message = require("../errors/message");
 var import_object = require("../primordials/object");
-var import_spawn = require("../spawn/spawn");
-var import_errors = require("../spawn/errors");
+var import_child = require("../process/spawn/child");
+var import_errors = require("../process/spawn/errors");
 var import_discover = require("./discover");
 const MAX_ATTEMPTS = 3;
 const BACKOFF_BASE_MS = 5e3;
@@ -163,7 +163,7 @@ async function spawnAiAgent(opts) {
     stderr = "";
     exitCode = 0;
     try {
-      const child = (0, import_spawn.spawn)(agent, args, {
+      const child = (0, import_child.spawn)(agent, args, {
         cwd: opts.cwd,
         stdio: "pipe",
         stdioString: true,

package/dist/ai/worktree.js

@@ -42,15 +42,15 @@ module.exports = __toCommonJS(worktree_exports);
 var import_node_fs = require("node:fs");
 var import_node_path = __toESM(require("node:path"), 1);
 var import_message = require("../errors/message");
-var import_spawn = require("../spawn/spawn");
-var import_errors = require("../spawn/errors");
+var import_child = require("../process/spawn/child");
+var import_errors = require("../process/spawn/errors");
 const DEFAULT_CONCURRENCY = 4;
 const MAX_CONCURRENCY = 8;
 function currentBranch(repo) {
   return git(repo, "symbolic-ref", "--short", "HEAD");
 }
 function git(cwd, ...args) {
-  const result = (0, import_spawn.spawnSync)("git", args, {
+  const result = (0, import_child.spawnSync)("git", args, {
     cwd,
     stdio: "pipe",
     stdioString: true

package/dist/argv/parse-args-string.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Tokenize a shell-style command string into an argv array. Modernized
+ *   port of the `string-argv` npm package (MIT) — same regex-driven recognizer,
+ *   native ES module shape, typed signature, no env/file prepend baggage.
+ *   Supports bare tokens, single + double quoted tokens, and mixed tokens like
+ *   `key="value"`. No backslash-escape processing — `\"` inside a double-quoted
+ *   segment is two literal characters, not an escaped quote. No env-var
+ *   expansion, no command substitution, no pipes / redirects / `&&` chains;
+ *   this is purely a tokenizer. Common use case: turning a `string`
+ *   representation of a command (e.g. from a config file, a `bin` field, or a
+ *   shellout test fixture) into an argv array that `execFileSync` /
+ *   `child_process.spawn` accepts directly — bypassing the platform shell + its
+ *   quoting differences (`cmd.exe` vs `bash`).
+ */
+/**
+ * Tokenize a shell-style command string into argv. Single + double quote pairs
+ * are recognized; the quote characters are stripped from the resulting token.
+ * Whitespace outside of quotes separates tokens.
+ *
+ * @example
+ *   parseArgsString('git commit -m "hello world"')
+ *   // → ['git', 'commit', '-m', 'hello world']
+ *
+ *   parseArgsString('foo --bar="x y" baz')
+ *   // → ['foo', '--bar=x y', 'baz']
+ *
+ *   parseArgsString("echo 'one two' three")
+ *   // → ['echo', 'one two', 'three']
+ */
+export declare function parseArgsString(cmd: string): string[];

package/dist/argv/parse-args-string.js

@@ -0,0 +1,42 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var parse_args_string_exports = {};
+__export(parse_args_string_exports, {
+  parseArgsString: () => parseArgsString
+});
+module.exports = __toCommonJS(parse_args_string_exports);
+const TOKEN_REGEXP = /([^\s'"]([^\s'"]*(['"])([^]*?)\3)+[^\s'"]*)|[^\s'"]+|(['"])([^]*?)\5/g;
+function parseArgsString(cmd) {
+  const argv = [];
+  let match;
+  TOKEN_REGEXP.lastIndex = 0;
+  while ((match = TOKEN_REGEXP.exec(cmd)) !== null) {
+    const token = match[1] ?? match[6] ?? match[0];
+    if (typeof token === "string") {
+      argv.push(token);
+    }
+  }
+  return argv;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseArgsString
+});

package/dist/bin/check-primordials.js

@@ -43,14 +43,15 @@ var import_node_fs = require("node:fs");
 var import_node_path = __toESM(require("node:path"));
 var import_node_process = __toESM(require("node:process"));
 var import_message = require("../errors/message");
-var import_logger = require("../logger/logger");
+var import_default = require("../logger/default");
 var import_array = require("../primordials/array");
 var import_error = require("../primordials/error");
 var import_json = require("../primordials/json");
 var import_object = require("../primordials/object");
+var import_primordials_defaults = require("../checks/primordials-defaults");
 var import_primordials = require("../checks/primordials");
 var import_parse = require("../argv/parse");
-const logger = (0, import_logger.getDefaultLogger)();
+const logger = (0, import_default.getDefaultLogger)();
 const DEFAULT_CONFIG_PATH = ".socket-lib.json";
 const FALLBACK_CONFIG_PATHS = [
   ".socket-lib.json",
@@ -109,14 +110,16 @@ function printHelp() {
   logger.log("Config (.socket-lib.json \u2014 primordials section):");
   logger.log("  {");
   logger.log('    "primordials": {');
-  logger.log('      "aliasMap":         { "Array": "ArrayCtor" },');
-  logger.log('      "nodeInternalOnly": ["SafeMap", "SafeSet"],');
   logger.log(
     '      "scanDirs":         ["src", "additions/source-patched/lib"]'
   );
   logger.log("    }");
   logger.log("  }");
   logger.log("");
+  logger.log("Only `scanDirs` is required. `aliasMap` and `nodeInternalOnly`");
+  logger.log("default to the fleet-canonical sets and only need entries when");
+  logger.log("your repo extends or overrides them.");
+  logger.log("");
   logger.log("A bare object (no `primordials` section) is also accepted for");
   logger.log("repos that only run this one check.");
 }
@@ -152,14 +155,16 @@ function loadConfig(configPath) {
   if (raw.nodeInternalOnly !== void 0 && !(0, import_array.ArrayIsArray)(raw.nodeInternalOnly)) {
     throw new import_error.ErrorCtor("config.nodeInternalOnly must be an array of strings");
   }
-  const aliasMap = new Map(
-    (0, import_object.ObjectEntries)(raw.aliasMap ?? {})
-  );
-  const nodeInternalOnly = new Set(
-    (raw.nodeInternalOnly ?? []).filter(
+  const aliasMap = new Map([
+    ...(0, import_object.ObjectEntries)(import_primordials_defaults.DEFAULT_ALIAS_MAP),
+    ...(0, import_object.ObjectEntries)(raw.aliasMap ?? {})
+  ]);
+  const nodeInternalOnly = /* @__PURE__ */ new Set([
+    ...import_primordials_defaults.DEFAULT_NODE_INTERNAL_ONLY,
+    ...(raw.nodeInternalOnly ?? []).filter(
       (x) => typeof x === "string"
     )
-  );
+  ]);
   return {
     scanDirs: raw.scanDirs,
     aliasMap,

package/dist/bin/check.js

@@ -24,9 +24,9 @@ __export(check_exports, {
   runCheck: () => runCheck
 });
 module.exports = __toCommonJS(check_exports);
-var import_logger = require("../logger/logger");
+var import_default = require("../logger/default");
 var import_check_primordials = require("./check-primordials");
-const logger = (0, import_logger.getDefaultLogger)();
+const logger = (0, import_default.getDefaultLogger)();
 const CHECKS = /* @__PURE__ */ new Map([
   ["primordials", "primordials"],
   ["prim", "primordials"]

package/dist/bin/exec.d.ts

@@ -17,7 +17,7 @@
  *   4. On not-found, throw a typed `ENOENT` error with operator guidance — far
  *      more useful than a bare "command not found".
  */
-import type { SpawnOptions } from '../spawn/types';
+import type { SpawnOptions } from '../process/spawn/types';
 /**
  * Execute a binary with the given arguments.
  *

package/dist/bin/exec.js

@@ -27,7 +27,7 @@ var import_platform = require("../constants/platform");
 var import_normalize = require("../paths/normalize");
 var import_array = require("../primordials/array");
 var import_error = require("../primordials/error");
-var import_spawn = require("../spawn/spawn");
+var import_child = require("../process/spawn/child");
 var import_internal = require("./_internal");
 var import_resolve = require("./resolve");
 var import_which = require("./which");
@@ -68,7 +68,7 @@ To resolve:
     throw error;
   }
   const binCommand = (0, import_array.ArrayIsArray)(resolvedPath) ? resolvedPath[0] : resolvedPath;
-  return await (0, import_spawn.spawn)(binCommand, args ?? [], {
+  return await (0, import_child.spawn)(binCommand, args ?? [], {
     shell: import_platform.WIN32,
     ...options
   });

package/dist/bin/socket-lib.js

@@ -36,9 +36,9 @@ __export(socket_lib_exports, {
 });
 module.exports = __toCommonJS(socket_lib_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_logger = require("../logger/logger");
+var import_default = require("../logger/default");
 var import_check = require("./check");
-const logger = (0, import_logger.getDefaultLogger)();
+const logger = (0, import_default.getDefaultLogger)();
 function printHelp() {
   logger.log("socket-lib \u2014 fleet-wide static-analysis CLI");
   logger.log("");

package/dist/{ttl-cache/cache.js → cache/ttl/store.js}

@@ -28,21 +28,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var cache_exports = {};
-__export(cache_exports, {
+var store_exports = {};
+__export(store_exports, {
   createTtlCache: () => createTtlCache
 });
-module.exports = __toCommonJS(cache_exports);
-var import_clear = require("../cacache/clear");
-var import_read = require("../cacache/read");
-var import_write = require("../cacache/write");
-var import_date = require("../primordials/date");
-var import_error = require("../primordials/error");
-var import_json = require("../primordials/json");
-var import_map_set = require("../primordials/map-set");
-var import_math = require("../primordials/math");
-var import_regexp = require("../primordials/regexp");
-var import_string = require("../primordials/string");
+module.exports = __toCommonJS(store_exports);
+var import_clear = require("../../cacache/clear");
+var import_read = require("../../cacache/read");
+var import_write = require("../../cacache/write");
+var import_date = require("../../primordials/date");
+var import_error = require("../../primordials/error");
+var import_json = require("../../primordials/json");
+var import_map_set = require("../../primordials/map-set");
+var import_math = require("../../primordials/math");
+var import_regexp = require("../../primordials/regexp");
+var import_string = require("../../primordials/string");
 const DEFAULT_TTL_MS = 5 * 60 * 1e3;
 const DEFAULT_PREFIX = "ttl-cache";
 const DEFAULT_MEMO_MAX_SIZE = 1e3;
@@ -158,8 +158,8 @@ function createTtlCache(options) {
         results.set(originalKey, entry.data);
       }
     }
-    const cacheDir = (await import("../paths/socket")).getSocketCacacheDir();
-    const cacacheModule = await import("../cacache/_internal");
+    const cacheDir = (await import("../../paths/socket")).getSocketCacacheDir();
+    const cacacheModule = await import("../../cacache/_internal");
     const stream = cacacheModule.getCacache().ls.stream(cacheDir);
     for await (const cacheEntry of stream) {
       if (!cacheEntry.key.startsWith(`${opts.prefix}:`)) {

package/dist/{ttl-cache → cache/ttl}/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * @file Public type surface for `ttl-cache/*` modules — the `TtlCache`
+ * @file Public type surface for `cache/ttl/*` modules — the `TtlCache`
  *   interface (the seven-method API returned by `createTtlCache`), the
  *   `TtlCacheEntry` storage shape, and the `TtlCacheOptions` / `ClearOptions`
  *   configuration records. Pure types, no runtime side effects.

package/dist/checks/primordials-defaults.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file GENERATED — do not edit by hand. Run `node
+ *   scripts/fix/generate-primordials-defaults.mts` (also runs as part of `pnpm
+ *   run build`) to regenerate from the `globals` npm package's globals.json
+ *   crossed against src/primordials/*.ts `Ctor` exports. Source:
+ *   globals@<bumped via taze>, env = builtin ∪ node. Filter: identifiers
+ *   socket-lib exports as `<name>Ctor`.
+ */
+/**
+ * Fleet-canonical alias map: socket-lib mirrors standard JS + Node globals with
+ * a `Ctor` suffix. Downstream repos that destructure raw `primordials` use this
+ * map to resolve the source-side name to socket-lib's export.
+ */
+export declare const DEFAULT_ALIAS_MAP: Readonly<Record<string, string>>;
+/**
+ * Names that exist in Node's internal `primordials` but are intentionally NOT
+ * mirrored to socket-lib (mostly Safe* wrappers and prototype-method aliases).
+ * Adding to this set is a per-name decision; the list is hand-maintained.
+ */
+export declare const DEFAULT_NODE_INTERNAL_ONLY: readonly string[];

package/dist/checks/primordials-defaults.js

@@ -0,0 +1,92 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var primordials_defaults_exports = {};
+__export(primordials_defaults_exports, {
+  DEFAULT_ALIAS_MAP: () => DEFAULT_ALIAS_MAP,
+  DEFAULT_NODE_INTERNAL_ONLY: () => DEFAULT_NODE_INTERNAL_ONLY
+});
+module.exports = __toCommonJS(primordials_defaults_exports);
+var import_object = require("../primordials/object");
+const DEFAULT_ALIAS_MAP = (0, import_object.ObjectFreeze)(
+  {
+    __proto__: null,
+    AggregateError: "AggregateErrorCtor",
+    Array: "ArrayCtor",
+    ArrayBuffer: "ArrayBufferCtor",
+    BigInt: "BigIntCtor",
+    Boolean: "BooleanCtor",
+    Buffer: "BufferCtor",
+    DataView: "DataViewCtor",
+    Date: "DateCtor",
+    Error: "ErrorCtor",
+    EvalError: "EvalErrorCtor",
+    Float32Array: "Float32ArrayCtor",
+    Float64Array: "Float64ArrayCtor",
+    Int16Array: "Int16ArrayCtor",
+    Int32Array: "Int32ArrayCtor",
+    Int8Array: "Int8ArrayCtor",
+    Map: "MapCtor",
+    Number: "NumberCtor",
+    Object: "ObjectCtor",
+    Promise: "PromiseCtor",
+    Proxy: "ProxyCtor",
+    RangeError: "RangeErrorCtor",
+    ReferenceError: "ReferenceErrorCtor",
+    RegExp: "RegExpCtor",
+    Set: "SetCtor",
+    SharedArrayBuffer: "SharedArrayBufferCtor",
+    String: "StringCtor",
+    Symbol: "SymbolCtor",
+    SyntaxError: "SyntaxErrorCtor",
+    TypeError: "TypeErrorCtor",
+    URIError: "URIErrorCtor",
+    URL: "URLCtor",
+    URLSearchParams: "URLSearchParamsCtor",
+    Uint16Array: "Uint16ArrayCtor",
+    Uint32Array: "Uint32ArrayCtor",
+    Uint8Array: "Uint8ArrayCtor",
+    Uint8ClampedArray: "Uint8ClampedArrayCtor",
+    WeakMap: "WeakMapCtor",
+    WeakRef: "WeakRefCtor",
+    WeakSet: "WeakSetCtor",
+    atob: "GlobalAtob",
+    btoa: "GlobalBtoa",
+    decodeURIComponent: "GlobalDecodeURIComponent",
+    encodeURIComponent: "GlobalEncodeURIComponent",
+    globalThis: "GlobalThis"
+  }
+);
+const DEFAULT_NODE_INTERNAL_ONLY = (0, import_object.ObjectFreeze)([
+  "DataViewPrototypeGetInt32",
+  "DataViewPrototypeGetUint32",
+  "SafeMap",
+  "SafePromise",
+  "SafePromiseAllReturnVoid",
+  "SafePromiseAllSettled",
+  "SafeSet",
+  "SafeWeakMap",
+  "SafeWeakSet"
+]);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_ALIAS_MAP,
+  DEFAULT_NODE_INTERNAL_ONLY
+});

package/dist/colors/socket-palette.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file Socket terminal-color palette — mirrors the CSS design tokens defined
+ *   in the fleet's `template/styles/tokens.css` (light / dark / synthwave
+ *   themes). Each helper returns the input string wrapped in a 24-bit ANSI
+ *   escape sequence so the rendered hex matches the brand exactly; no rounding
+ *   to the legacy 8-color palette. Picocolors / yoctocolors only ship a fixed
+ *   8-color ANSI set, which would collapse `#8c50ff` to a generic "magenta".
+ *   This module sidesteps that by emitting `\x1b[38;2;R;G;Bm…\x1b[39m`
+ *   directly. Zero runtime dependencies. Usage: import { getPalette } from
+ *   '@socketsecurity/lib/colors/socket-palette' const palette =
+ *   getPalette('dark') console.log(palette.success('Done')) // Or read raw hex
+ *   values for callers building their own escape codes.
+ *   console.log(palette.hex.socketPurple) // "#8c50ff" Pick a theme by passing
+ *   `'light' | 'dark' | 'synthwave'`. Defaults to `'dark'` since terminals are
+ *   dark-on-light far less often than the opposite.
+ */
+/**
+ * Available palette themes — kept in sync with the CSS theme blocks in
+ * template/styles/tokens.css.
+ */
+export type SocketPaletteTheme = 'dark' | 'light' | 'synthwave';
+/**
+ * Hex-color value for each named slot. Exposed so callers can build their own
+ * ANSI escapes (e.g. for backgrounds, which this module doesn't wrap).
+ */
+export interface SocketPaletteHex {
+    alert: string;
+    error: string;
+    info: string;
+    socketPink: string;
+    socketPurple: string;
+    success: string;
+    warning: string;
+}
+/**
+ * Color-application helpers. Each takes a string and returns it wrapped in the
+ * matching 24-bit ANSI escape.
+ */
+export interface SocketPalette {
+    alert: (s: string) => string;
+    error: (s: string) => string;
+    hex: SocketPaletteHex;
+    info: (s: string) => string;
+    socketPink: (s: string) => string;
+    socketPurple: (s: string) => string;
+    success: (s: string) => string;
+    warning: (s: string) => string;
+}
+/**
+ * Build an ANSI-wrapping function for a single hex color. Emits the 24-bit
+ * sequence rather than rounding to the legacy 8-color palette so the rendered
+ * output matches the CSS token byte-for-byte (modulo terminal gamut).
+ * `\x1b[39m` resets fg to the terminal default — using `[0m` would also clear
+ * bg / styles, which the caller may have set deliberately.
+ */
+export declare function colorizer(hex: string): (s: string) => string;
+/**
+ * Resolve a Socket palette for the requested theme. Defaults to `'dark'` — the
+ * common case for terminal output.
+ *
+ * @example
+ *   ;```typescript
+ *   import { getPalette } from '@socketsecurity/lib/colors/socket-palette'
+ *
+ *   const palette = getPalette('dark')
+ *   process.stdout.write(palette.success('Build complete\n'))
+ *   ```
+ */
+export declare function getPalette(theme?: SocketPaletteTheme): SocketPalette;