@socketsecurity/lib 6.0.2 → 6.0.3

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.3](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.3) - 2026-05-26
+
+### Added
+
+- **`paths/walk` — `walkUp(from, { cwd, stopAt })`.** Lazy generator yielding a path then each ancestor up to (and including) the filesystem root or a `stopAt` boundary. `fs/find-up` now builds on it.
+- **`fs/access` — `canAccess` / `canRead` / `canWrite` / `canExecute`.** Sync boolean permission checks over `fs.accessSync` (F_OK / R_OK / W_OK / X_OK). For "I'm about to write" prefer attempting the write over a pre-check (TOCTOU); use these when the answer drives a branch.
+- **`fs/resolve-module` — `requireResolveFrom(fromDir, specifier)` / `requireResolveFromCwd(specifier)`.** `require.resolve` anchored at an arbitrary directory (e.g. "the `typescript` THIS project would load"). `nothrow: true` returns `undefined` instead of throwing.
+- **`releases/github-retry-config` — `GITHUB_RETRY_CONFIG`, `resolveBaseDelayMs()`, `DEFAULT_BASE_DELAY_MS`.** Shared backoff config for the GitHub release helpers. The base retry delay is overridable via the `SOCKET_GITHUB_RETRY_BASE_DELAY_MS` env var (default 5000ms; set `0` for near-instant retries) — useful in CI / tests to skip the exponential-backoff wait.
+- **`smol/path` — `getSmolPath()`.** Lazy accessor for socket-btm's `node:smol-path` native binding; `undefined` on stock Node. `walkUp`, `canAccess`, and `findUp` now prefer the native fast path (`dirname` / `access` / batched find-up) when running on a smol binary and fall back to the JS implementation otherwise — transparent to callers.
+
+### Changed (breaking)
+
+- **`ai/profiles` exports a single `AI_PROFILE` capability ladder** instead of the four standalone `*_PROFILE` constants. The tiers are `AI_PROFILE.read` ⊂ `.edit` ⊂ `.create` ⊂ `.full`, ordered least-to-most capable. Migration: `READ_ONLY_PROFILE` → `AI_PROFILE.read`; `EDIT_ONLY_PROFILE` → `AI_PROFILE.create` (the old `EDIT_ONLY` allowed `Write`/`MultiEdit`); `FULL_FIX_PROFILE` → `AI_PROFILE.full`. New `AI_PROFILE.edit` is the narrowest fix tier — `Edit` on existing files only, no `Write`/`MultiEdit` — for lint autofix and in-place codemods.
+
+### Changed
+
+- **Every `AI_PROFILE` tier now denies `Agent`.** Sub-agent spawning is blocked across all profiles, since a sub-agent can escape the parent's tool restrictions.
+
 ## [6.0.2](https://github.com/SocketDev/socket-lib/releases/tag/v6.0.2) - 2026-05-26
 
 ### Added

package/dist/ai/profiles.d.mts

@@ -2,38 +2,61 @@
  * @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:
+ *   --add-dir cwd). `AI_PROFILE` is a capability ladder — each tier permits
+ *   everything the tier above it does, plus one more capability. Spread a tier
+ *   and override per call (`tools`/`disallow` to tighten further, `model`,
+ *   `addDirs`). Choose the LEAST-capable tier that gets the job done:
  *
- *   - `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.
+ *   - `AI_PROFILE.read` — research / scanning. Read + Grep + Glob + WebFetch +
+ *     WebSearch. No Edit, no Write, no Bash. Static-analysis skills
+ *     (scanning-quality, scanning-security).
+ *   - `AI_PROFILE.edit` — in-place edits only. Read + Edit + Grep + Glob. NO
+ *     Write (can't create files), NO MultiEdit, NO Bash. Lint autofix /
+ *     codemods constrained to existing files.
+ *   - `AI_PROFILE.create` — edit AND create files. Adds MultiEdit + Write on top
+ *     of `.edit`. Still no Bash. Codegen, adding a test, refactors that split
+ *     modules.
+ *   - `AI_PROFILE.full` — `.create` plus Bash, allowlisted to git / pnpm / node.
+ *     Skills that commit, run tests, install deps. No "wide open" tier exists
+ *     by design — letting an agent run arbitrary tools is the lockdown rule's
+ *     exact failure mode. The ladder is read ⊂ edit ⊂ create ⊂ full: each
+ *     tier's tool set is a superset of the one above.
  */
 import type { PermissionMode } from './types.mts';
-interface Profile {
+export interface AiProfile {
     readonly allow: readonly string[];
     readonly disallow: readonly string[];
     readonly permissionMode: PermissionMode;
     readonly tools: readonly string[];
 }
 /**
- * Read-only research / scanning. No mutation.
+ * Capability ladder of lockdown profiles, ordered least → most capable. Key
+ * order documents the ladder; each tier is a strict superset of the previous
+ * tier's tool surface.
  */
-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 {};
+export declare const AI_PROFILE: {
+    readonly read: {
+        readonly allow: readonly [];
+        readonly disallow: readonly ["Agent", "Bash", "Edit", "MultiEdit", "Write"];
+        readonly permissionMode: 'dontAsk';
+        readonly tools: readonly ["Glob", "Grep", "Read", "WebFetch", "WebSearch"];
+    };
+    readonly edit: {
+        readonly allow: readonly [];
+        readonly disallow: readonly ["Agent", "Bash", "MultiEdit", "WebFetch", "WebSearch", "Write"];
+        readonly permissionMode: 'acceptEdits';
+        readonly tools: readonly ["Edit", "Glob", "Grep", "Read"];
+    };
+    readonly create: {
+        readonly allow: readonly [];
+        readonly disallow: readonly ["Agent", "Bash", "WebFetch", "WebSearch"];
+        readonly permissionMode: 'acceptEdits';
+        readonly tools: readonly ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"];
+    };
+    readonly full: {
+        readonly allow: readonly ["Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(node:*)", "Bash(pnpm exec:*)", "Bash(pnpm run:*)", "Bash(pnpm test:*)"];
+        readonly disallow: readonly ["Agent", "WebFetch", "WebSearch"];
+        readonly permissionMode: 'acceptEdits';
+        readonly tools: readonly ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"];
+    };
+};

package/dist/ai/profiles.js

@@ -20,42 +20,49 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var profiles_exports = {};
 __export(profiles_exports, {
-  EDIT_ONLY_PROFILE: () => EDIT_ONLY_PROFILE,
-  FULL_FIX_PROFILE: () => FULL_FIX_PROFILE,
-  READ_ONLY_PROFILE: () => READ_ONLY_PROFILE
+  AI_PROFILE: () => AI_PROFILE
 });
 module.exports = __toCommonJS(profiles_exports);
-const READ_ONLY_PROFILE = {
-  allow: [],
-  disallow: ["Bash", "Edit", "MultiEdit", "Write"],
-  permissionMode: "dontAsk",
-  tools: ["Glob", "Grep", "Read", "WebFetch", "WebSearch"]
-};
-const EDIT_ONLY_PROFILE = {
-  allow: [],
-  disallow: ["Bash", "WebFetch", "WebSearch"],
-  permissionMode: "acceptEdits",
-  tools: ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
-};
-const FULL_FIX_PROFILE = {
-  allow: [
-    "Bash(git status:*)",
-    "Bash(git diff:*)",
-    "Bash(git log:*)",
-    "Bash(git add:*)",
-    "Bash(git commit:*)",
-    "Bash(node:*)",
-    "Bash(pnpm exec:*)",
-    "Bash(pnpm run:*)",
-    "Bash(pnpm test:*)"
-  ],
-  disallow: ["WebFetch", "WebSearch"],
-  permissionMode: "acceptEdits",
-  tools: ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+const AI_PROFILE = {
+  read: {
+    allow: [],
+    disallow: ["Agent", "Bash", "Edit", "MultiEdit", "Write"],
+    permissionMode: "dontAsk",
+    tools: ["Glob", "Grep", "Read", "WebFetch", "WebSearch"]
+  },
+  // No Write / MultiEdit: edits land in existing files, never create new ones.
+  edit: {
+    allow: [],
+    disallow: ["Agent", "Bash", "MultiEdit", "WebFetch", "WebSearch", "Write"],
+    permissionMode: "acceptEdits",
+    tools: ["Edit", "Glob", "Grep", "Read"]
+  },
+  // MultiEdit + Write added: may create files. Bash still denied.
+  create: {
+    allow: [],
+    disallow: ["Agent", "Bash", "WebFetch", "WebSearch"],
+    permissionMode: "acceptEdits",
+    tools: ["Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+  },
+  // Bash allowlisted to git / pnpm / node only; anything else is denied.
+  full: {
+    allow: [
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(node:*)",
+      "Bash(pnpm exec:*)",
+      "Bash(pnpm run:*)",
+      "Bash(pnpm test:*)"
+    ],
+    disallow: ["Agent", "WebFetch", "WebSearch"],
+    permissionMode: "acceptEdits",
+    tools: ["Bash", "Edit", "Glob", "Grep", "MultiEdit", "Read", "Write"]
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  EDIT_ONLY_PROFILE,
-  FULL_FIX_PROFILE,
-  READ_ONLY_PROFILE
+  AI_PROFILE
 });

package/dist/ai/spawn.d.mts

@@ -30,11 +30,11 @@ export declare function pickAgent(requested: AiAgentName | undefined, cwd: strin
  *
  * @example
  *   ```ts
- *   import { EDIT_ONLY_PROFILE } from '@socketsecurity/lib/ai/profiles'
+ *   import { AI_PROFILE } from '@socketsecurity/lib/ai/profiles'
  *   import { spawnAiAgent } from '@socketsecurity/lib/ai/spawn'
  *
  *   const result = await spawnAiAgent({
- *   ...EDIT_ONLY_PROFILE,
+ *   ...AI_PROFILE.edit,
  *   prompt: 'Fix the lint findings in src/foo.ts',
  *   cwd: process.cwd(),
  *   model: 'claude-sonnet-4-6',

package/dist/ai/types.d.mts

@@ -42,9 +42,9 @@ export interface AgentSpawnResult {
  *
  * Required: `prompt`, `cwd`, `tools`, `disallow`, `permissionMode`.
  *
- * Pre-built profiles in `profiles.ts` cover the common shapes
- * (READ_ONLY_PROFILE, EDIT_ONLY_PROFILE) — callers spread the profile and
- * override per-call (model, timeout, addDirs).
+ * Pre-built profiles in `profiles.ts` cover the common shapes (the `AI_PROFILE`
+ * capability ladder) — callers spread a tier and override per-call (model,
+ * timeout, addDirs).
  *
  * Why the lockdown fields are required (not defaulted to a permissive shape):
  * the CLAUDE.md rule says "all four lockdown flags MUST be set on every spawn."

package/dist/ai/worktree.d.mts

@@ -77,14 +77,14 @@ export declare function runOne<I, T>(item: I, index: number, worktreeBranch: str
  *   ;```ts
  *   import { spawnAiAgentsInWorktrees } from '@socketsecurity/lib/ai/worktree'
  *   import { spawnAiAgent } from '@socketsecurity/lib/ai/spawn'
- *   import { EDIT_ONLY_PROFILE } from '@socketsecurity/lib/ai/profiles'
+ *   import { AI_PROFILE } from '@socketsecurity/lib/ai/profiles'
  *
  *   const repos = ['socket-addon', 'socket-btm', 'socket-lib']
  *   const settled = await spawnAiAgentsInWorktrees(
  *     repos,
  *     async ({ cwd }) => {
  *       return await spawnAiAgent({
- *         ...EDIT_ONLY_PROFILE,
+ *         ...AI_PROFILE.create,
  *         prompt: 'Run the cleanup task',
  *         cwd,
  *       })

package/dist/constants/socket.js

@@ -77,7 +77,7 @@ const SOCKET_REGISTRY_APP_NAME = "registry";
 const SOCKET_WHEELHOUSE_APP_NAME = "wheelhouse";
 const SOCKET_APP_PREFIX = "_";
 const SOCKET_LIB_NAME = "@socketsecurity/lib";
-const SOCKET_LIB_VERSION = "6.0.2";
+const SOCKET_LIB_VERSION = "6.0.3";
 const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";
 const CACHE_SOCKET_API_DIR = "socket-api";
 const REGISTRY = "registry";

package/dist/dlx/detect.js

@@ -32,6 +32,7 @@ __export(detect_exports, {
 });
 module.exports = __toCommonJS(detect_exports);
 var import_paths = require("./paths");
+var import_find_up = require("../fs/find-up");
 var import_socket = require("../paths/socket");
 var import_date = require("../primordials/date");
 var import_json = require("../primordials/json");
@@ -72,18 +73,9 @@ function findPackageJson(filePath) {
       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)) {
-      packageJsonPathCacheSet(startDir, packageJsonPath);
-      return packageJsonPath;
-    }
-    currentDir = path.dirname(currentDir);
-  }
-  packageJsonPathCacheSet(startDir, void 0);
-  return void 0;
+  const packageJsonPath = (0, import_find_up.findUpSync)("package.json", { cwd: startDir });
+  packageJsonPathCacheSet(startDir, packageJsonPath);
+  return packageJsonPath;
 }
 function readPackageJson(packageJsonPath) {
   const fs = (0, import_fs.getNodeFs)();

package/dist/fs/access.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file Synchronous file-access predicates — boolean "can this process do X to
+ *   this path?" checks over `fs.accessSync`. Prefer these only where the answer
+ *   drives a user-facing decision (e.g. "is the cache dir writable, so I can
+ *   pick a fallback?"). For "I'm about to write, can I?" do NOT pre-check —
+ *   just attempt the write and handle the error; a check-then-act gap is a
+ *   TOCTOU race. `canAccess` (F_OK) overlaps `existsSync`; use `existsSync` for
+ *   plain existence, these for permission bits.
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Does the process have `mode` access to `path`? Wraps `fs.accessSync`,
+ * returning a boolean instead of throwing. Default mode is `F_OK` (existence).
+ *
+ * @param path - Path to check.
+ * @param mode - `fs.constants` bit (`F_OK` / `R_OK` / `W_OK` / `X_OK`).
+ *
+ * @returns True if the access check succeeds.
+ */
+export declare function canAccess(path: PathLike, mode?: number | undefined): boolean;
+/**
+ * Can the process execute `path`? (`X_OK`)
+ */
+export declare function canExecute(path: PathLike): boolean;
+/**
+ * Can the process read `path`? (`R_OK`)
+ */
+export declare function canRead(path: PathLike): boolean;
+/**
+ * Can the process write `path`? (`W_OK`)
+ */
+export declare function canWrite(path: PathLike): boolean;

package/dist/fs/access.js

@@ -0,0 +1,63 @@
+"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 access_exports = {};
+__export(access_exports, {
+  canAccess: () => canAccess,
+  canExecute: () => canExecute,
+  canRead: () => canRead,
+  canWrite: () => canWrite
+});
+module.exports = __toCommonJS(access_exports);
+var import_fs = require("../node/fs");
+var import_path = require("../smol/path");
+// @__NO_SIDE_EFFECTS__
+function canAccess(path, mode) {
+  const smolAccess = (0, import_path.getSmolPath)()?.access;
+  if (smolAccess) {
+    return smolAccess(path, mode);
+  }
+  const fs = (0, import_fs.getNodeFs)();
+  try {
+    fs.accessSync(path, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+// @__NO_SIDE_EFFECTS__
+function canExecute(path) {
+  return /* @__PURE__ */ canAccess(path, (0, import_fs.getNodeFs)().constants.X_OK);
+}
+// @__NO_SIDE_EFFECTS__
+function canRead(path) {
+  return /* @__PURE__ */ canAccess(path, (0, import_fs.getNodeFs)().constants.R_OK);
+}
+// @__NO_SIDE_EFFECTS__
+function canWrite(path) {
+  return /* @__PURE__ */ canAccess(path, (0, import_fs.getNodeFs)().constants.W_OK);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  canAccess,
+  canExecute,
+  canRead,
+  canWrite
+});

package/dist/fs/find-up.js

@@ -40,6 +40,8 @@ var import_abort = require("../process/abort");
 var import_fs = require("../node/fs");
 var import_path = require("../node/path");
 var import_normalize = require("../paths/normalize");
+var import_walk = require("../paths/walk");
+var import_path2 = require("../smol/path");
 const abortSignal = (0, import_abort.getAbortSignal)();
 // @__NO_SIDE_EFFECTS__
 async function findUp(name, options) {
@@ -59,10 +61,8 @@ async function findUp(name, options) {
   }
   const fs = (0, import_fs.getNodeFs)();
   const path = (0, import_path.getNodePath)();
-  let dir = path.resolve(cwd);
-  const { root } = path.parse(dir);
   const names = (0, import_predicates.isArray)(name) ? name : [name];
-  while (dir) {
+  for (const dir of (0, import_walk.walkUp)(cwd)) {
     for (const n of names) {
       if (signal?.aborted) {
         return void 0;
@@ -79,10 +79,6 @@ async function findUp(name, options) {
       } catch {
       }
     }
-    if (dir === root) {
-      break;
-    }
-    dir = path.dirname(dir);
   }
   return void 0;
 }
@@ -104,27 +100,13 @@ function findUpSync(name, options) {
   }
   const fs = (0, import_fs.getNodeFs)();
   const path = (0, import_path.getNodePath)();
-  let dir = path.resolve(cwd);
-  const { root } = path.parse(dir);
-  const stopDir = stopAt ? path.resolve(stopAt) : void 0;
   const names = (0, import_predicates.isArray)(name) ? name : [name];
-  while (dir) {
-    if (stopDir && dir === stopDir) {
-      for (const n of names) {
-        const thePath = path.join(dir, n);
-        try {
-          const stats = fs.statSync(thePath);
-          if (!onlyDirectories && stats.isFile()) {
-            return (0, import_normalize.normalizePath)(thePath);
-          }
-          if (!onlyFiles && stats.isDirectory()) {
-            return (0, import_normalize.normalizePath)(thePath);
-          }
-        } catch {
-        }
-      }
-      return void 0;
-    }
+  const smolFindUp = (0, import_path2.getSmolPath)()?.findUp;
+  if (smolFindUp && stopAt === void 0) {
+    const found = smolFindUp(path.resolve(cwd), names, { onlyDirectories });
+    return found === void 0 ? void 0 : (0, import_normalize.normalizePath)(found);
+  }
+  for (const dir of (0, import_walk.walkUp)(cwd, { stopAt })) {
     for (const n of names) {
       const thePath = path.join(dir, n);
       try {
@@ -138,10 +120,6 @@ function findUpSync(name, options) {
       } catch {
       }
     }
-    if (dir === root) {
-      break;
-    }
-    dir = path.dirname(dir);
   }
   return void 0;
 }

package/dist/fs/resolve-module.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file `require.resolve`-from-an-arbitrary-base. Node's bare
+ *   `require.resolve(spec)` resolves relative to the calling module; these
+ *   helpers resolve a specifier as if required from a DIFFERENT directory —
+ *   useful for "find the copy of `typescript` that THIS project would load,"
+ *   not the copy socket-lib itself loads. Returns the resolved absolute file
+ *   path, or (in `nothrow` form) `undefined` when the specifier can't be
+ *   resolved.
+ */
+/**
+ * Resolve a module specifier as if `require`'d from `fromDir`.
+ *
+ * Equivalent to running `require.resolve(specifier)` inside a module located at
+ * `fromDir`. Accepts package specifiers (`'typescript'`, `'pkg/sub/path'`) and
+ * relative paths (`'./foo'`).
+ *
+ * @example
+ *   ;```ts
+ *   // The `typescript` the project at /repo would load:
+ *   requireResolveFrom('/repo', 'typescript')
+ *   //=> '/repo/node_modules/typescript/lib/typescript.js'
+ *
+ *   requireResolveFrom('/repo', './missing', { nothrow: true })
+ *   //=> undefined
+ *   ```
+ *
+ * @param fromDir - Directory to resolve as if the require originated there.
+ * @param specifier - Module specifier or relative path to resolve.
+ * @param options - `nothrow: true` returns `undefined` instead of throwing.
+ *
+ * @returns Absolute resolved path (or `undefined` when `nothrow` and
+ *   unresolved).
+ *
+ * @throws When the specifier can't be resolved and `nothrow` is not set.
+ */
+export declare function requireResolveFrom(fromDir: string, specifier: string, options: {
+    nothrow: true;
+}): string | undefined;
+export declare function requireResolveFrom(fromDir: string, specifier: string, options?: {
+    nothrow?: false | undefined;
+} | undefined): string;
+/**
+ * Resolve a module specifier as if `require`'d from `process.cwd()`. Alias for
+ * {@link requireResolveFrom} anchored at the current directory.
+ *
+ * @param specifier - Module specifier or relative path to resolve.
+ * @param options - `nothrow: true` returns `undefined` instead of throwing.
+ *
+ * @returns Absolute resolved path (or `undefined` when `nothrow` and
+ *   unresolved).
+ */
+export declare function requireResolveFromCwd(specifier: string, options: {
+    nothrow: true;
+}): string | undefined;
+export declare function requireResolveFromCwd(specifier: string, options?: {
+    nothrow?: false | undefined;
+} | undefined): string;

package/dist/fs/resolve-module.js

@@ -0,0 +1,63 @@
+"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 resolve_module_exports = {};
+__export(resolve_module_exports, {
+  requireResolveFrom: () => requireResolveFrom,
+  requireResolveFromCwd: () => requireResolveFromCwd
+});
+module.exports = __toCommonJS(resolve_module_exports);
+var import_node_module = require("node:module");
+var import_node_process = __toESM(require("node:process"));
+var import_path = require("../node/path");
+function requireResolveFrom(fromDir, specifier, options) {
+  const { nothrow = false } = {
+    __proto__: null,
+    ...options
+  };
+  const path = (0, import_path.getNodePath)();
+  const anchor = path.join(path.resolve(fromDir), "noop.js");
+  try {
+    return (0, import_node_module.createRequire)(anchor).resolve(specifier);
+  } catch (e) {
+    if (nothrow) {
+      return void 0;
+    }
+    throw e;
+  }
+}
+function requireResolveFromCwd(specifier, options) {
+  return options && options.nothrow ? requireResolveFrom(import_node_process.default.cwd(), specifier, { nothrow: true }) : requireResolveFrom(import_node_process.default.cwd(), specifier);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  requireResolveFrom,
+  requireResolveFromCwd
+});

package/dist/fs/validate.js

@@ -23,18 +23,15 @@ __export(validate_exports, {
   validateFiles: () => validateFiles
 });
 module.exports = __toCommonJS(validate_exports);
-var import_fs = require("../node/fs");
+var import_access = require("./access");
 // @__NO_SIDE_EFFECTS__
 function validateFiles(filepaths) {
-  const fs = (0, import_fs.getNodeFs)();
   const validPaths = [];
   const invalidPaths = [];
-  const { R_OK } = fs.constants;
   for (const filepath of filepaths) {
-    try {
-      fs.accessSync(filepath, R_OK);
+    if ((0, import_access.canRead)(filepath)) {
       validPaths.push(filepath);
-    } catch {
+    } else {
       invalidPaths.push(filepath);
     }
   }

package/dist/paths/walk.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Walk parent directories. `walkUp` is the lazy ancestor generator that
+ *   `fs/find-up` and package-root lookups build on: given a starting path it
+ *   yields that path, then each parent, up to and INCLUDING the filesystem root
+ *   (or a caller-supplied `stopAt` boundary). Lazy so a caller can stop early
+ *   without computing the whole chain.
+ */
+export interface WalkUpOptions {
+    /**
+     * Starting directory. Relative `from` values are resolved against this.
+     * Defaults to `process.cwd()`.
+     */
+    cwd?: string | undefined;
+    /**
+     * Last directory to yield (INCLUSIVE). Traversal stops after this path is
+     * emitted. Defaults to the filesystem root.
+     */
+    stopAt?: string | undefined;
+}
+/**
+ * Lazily yield `from` and each of its ancestor directories, up to and including
+ * the filesystem root (or `stopAt`). Each yielded path is normalized to forward
+ * slashes.
+ *
+ * @example
+ *   ;```ts
+ *   for (const dir of walkUp('/a/b/c')) {
+ *     // '/a/b/c', '/a/b', '/a', '/'
+ *   }
+ *
+ *   // Stop at a boundary (inclusive):
+ *   [...walkUp('/a/b/c', { stopAt: '/a' })] // ['/a/b/c', '/a/b', '/a']
+ *   ```
+ *
+ * @param from - Path to start from. Relative values resolve against `cwd`.
+ * @param options - `cwd` and `stopAt` boundary.
+ *
+ * @returns Generator of normalized absolute directory paths.
+ */
+export declare function walkUp(from: string, options?: WalkUpOptions | undefined): Generator<string>;

package/dist/paths/walk.js

@@ -0,0 +1,63 @@
+"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 walk_exports = {};
+__export(walk_exports, {
+  walkUp: () => walkUp
+});
+module.exports = __toCommonJS(walk_exports);
+var import_node_process = __toESM(require("node:process"));
+var import_path = require("../node/path");
+var import_path2 = require("../smol/path");
+var import_normalize = require("./normalize");
+function* walkUp(from, options) {
+  const { cwd = import_node_process.default.cwd(), stopAt } = {
+    __proto__: null,
+    ...options
+  };
+  const path = (0, import_path.getNodePath)();
+  const smol = (0, import_path2.getSmolPath)();
+  const dirname = smol?.dirname ?? path.dirname;
+  let dir = path.resolve(cwd, from);
+  const stopDir = stopAt ? path.resolve(cwd, stopAt) : void 0;
+  let prev;
+  while (dir !== prev) {
+    yield (0, import_normalize.normalizePath)(dir);
+    if (stopDir !== void 0 && dir === stopDir) {
+      return;
+    }
+    prev = dir;
+    dir = dirname(dir);
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  walkUp
+});

package/dist/promises/_internal.d.ts

@@ -5,8 +5,14 @@
  */
 export declare const abortSignal: AbortSignal;
 /**
- * Get the timers/promises module. Uses lazy loading to avoid Webpack bundling
- * issues.
+ * Get the timers/promises module. Lazy `require` (not a top-level import) to
+ * avoid Webpack bundling issues.
+ *
+ * Intentionally NOT memoized: Node's module cache already makes the repeat
+ * `require` effectively free, and caching the reference breaks fake timers
+ * (`vi.useFakeTimers()` swaps the clock after this module loads; a cached
+ * reference would hold the pre-fake real `setTimeout`, burning real wallclock
+ * on retry backoff and starving the test worker pool).
  *
  * @private
  *

package/dist/promises/_internal.js

@@ -26,13 +26,9 @@ __export(internal_exports, {
 module.exports = __toCommonJS(internal_exports);
 var import_abort = require("../process/abort");
 const abortSignal = (0, import_abort.getAbortSignal)();
-let _timers;
 // @__NO_SIDE_EFFECTS__
 function getTimers() {
-  if (_timers === void 0) {
-    _timers = require("node:timers/promises");
-  }
-  return _timers;
+  return require("node:timers/promises");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/releases/github-asset-url.js

@@ -29,18 +29,9 @@ var import_retry = require("../promises/retry");
 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_github_assets = require("./github-assets");
 var import_github_auth = require("./github-auth");
-const RETRY_CONFIG = (0, import_object.ObjectFreeze)({
-  __proto__: null,
-  // Exponential backoff: delay doubles with each retry (5s, 10s, 20s).
-  backoffFactor: 2,
-  // Initial delay before first retry.
-  baseDelayMs: 5e3,
-  // Maximum number of retry attempts (excluding initial request).
-  retries: 2
-});
+var import_github_retry_config = require("./github-retry-config");
 async function fetchReleaseAssetsViaGraphQL(owner, repo, tag) {
   const response = await (0, import_request.httpRequest)("https://api.github.com/graphql", {
     body: (0, import_json.JSONStringify)({
@@ -143,7 +134,7 @@ async function getReleaseAssetUrl(tag, assetPattern, repoConfig, options = {}) {
       assets2 = release.assets;
     }
     return assets2;
-  }, RETRY_CONFIG);
+  }, import_github_retry_config.GITHUB_RETRY_CONFIG);
   if (!assets) {
     if (nothrow) {
       return void 0;

package/dist/releases/github-listing.js

@@ -31,19 +31,10 @@ var import_array = require("../primordials/array");
 var import_date = require("../primordials/date");
 var import_error = require("../primordials/error");
 var import_json = require("../primordials/json");
-var import_object = require("../primordials/object");
 var import_string = require("../primordials/string");
 var import_github_assets = require("./github-assets");
 var import_github_auth = require("./github-auth");
-const RETRY_CONFIG = (0, import_object.ObjectFreeze)({
-  __proto__: null,
-  // Exponential backoff: delay doubles with each retry (5s, 10s, 20s).
-  backoffFactor: 2,
-  // Initial delay before first retry.
-  baseDelayMs: 5e3,
-  // Maximum number of retry attempts (excluding initial request).
-  retries: 2
-});
+var import_github_retry_config = require("./github-retry-config");
 async function fetchReleasesViaGraphQL(owner, repo) {
   const response = await (0, import_request.httpRequest)("https://api.github.com/graphql", {
     body: (0, import_json.JSONStringify)({
@@ -161,7 +152,7 @@ async function getLatestRelease(toolPrefix, repoConfig, options = {}) {
     );
     const latestRelease = matchingReleases[0];
     return latestRelease.tag_name;
-  }, RETRY_CONFIG) ?? void 0;
+  }, import_github_retry_config.GITHUB_RETRY_CONFIG) ?? void 0;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/releases/github-retry-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file Shared retry configuration for the GitHub release helpers
+ *   (`github-listing`, `github-asset-url`). Exponential backoff over the
+ *   transient-failure / rate-limit surface. `baseDelayMs` is overridable via
+ *   `SOCKET_GITHUB_RETRY_BASE_DELAY_MS` — set it to `0` for near-instant
+ *   retries. Tests set it so the backoff sleep (5s + 10s of real wallclock)
+ *   doesn't run: pRetry's delay goes through `node:timers/promises`, which
+ *   `vi.useFakeTimers()` doesn't reliably intercept, so a zero base delay is
+ *   the robust, fake-timer-independent way to keep these tests fast. CI can
+ *   also dial it down. Default stays 5000ms for production resilience.
+ */
+/**
+ * Default base delay (ms) before the first retry when the env override is unset
+ * or non-numeric.
+ */
+export declare const DEFAULT_BASE_DELAY_MS = 5000;
+/**
+ * Resolve the retry base delay from `SOCKET_GITHUB_RETRY_BASE_DELAY_MS`,
+ * falling back to {@link DEFAULT_BASE_DELAY_MS}. Read live (not memoized) so
+ * it's unit-testable by mutating the env — and so a long-lived process that has
+ * the env changed under it picks up the new value on next read.
+ *
+ * @returns The configured base delay in milliseconds.
+ */
+export declare function resolveBaseDelayMs(): number;
+export declare const GITHUB_RETRY_CONFIG: Readonly<{
+    __proto__: null;
+    backoffFactor: 2;
+    baseDelayMs: number;
+    retries: 2;
+}>;

package/dist/releases/github-retry-config.js

@@ -0,0 +1,52 @@
+"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 github_retry_config_exports = {};
+__export(github_retry_config_exports, {
+  DEFAULT_BASE_DELAY_MS: () => DEFAULT_BASE_DELAY_MS,
+  GITHUB_RETRY_CONFIG: () => GITHUB_RETRY_CONFIG,
+  resolveBaseDelayMs: () => resolveBaseDelayMs
+});
+module.exports = __toCommonJS(github_retry_config_exports);
+var import_number = require("../env/number");
+var import_rewire = require("../env/rewire");
+var import_object = require("../primordials/object");
+const DEFAULT_BASE_DELAY_MS = 5e3;
+function resolveBaseDelayMs() {
+  return (0, import_number.envAsNumber)(
+    (0, import_rewire.getEnvValue)("SOCKET_GITHUB_RETRY_BASE_DELAY_MS"),
+    DEFAULT_BASE_DELAY_MS
+  );
+}
+const GITHUB_RETRY_CONFIG = (0, import_object.ObjectFreeze)({
+  __proto__: null,
+  // Exponential backoff: delay doubles with each retry (5s, 10s, 20s).
+  backoffFactor: 2,
+  // Initial delay before first retry. Overridable for tests / CI.
+  baseDelayMs: resolveBaseDelayMs(),
+  // Maximum number of retry attempts (excluding initial request).
+  retries: 2
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_BASE_DELAY_MS,
+  GITHUB_RETRY_CONFIG,
+  resolveBaseDelayMs
+});

package/dist/smol/path.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file Lazy-loader for socket-btm's `node:smol-path` — native fast paths for
+ *   the hot path-string primitives (`dirname`, `normalize`, …) and, per the
+ *   socket-btm `node-smol-path` Phase 4 plan, batched filesystem ops (`access`,
+ *   an in-C++ `findUp`). Returns `undefined` on stock Node, non-Node runtimes,
+ *   and on socket-btm binaries that haven't shipped the binding yet; callers
+ *   fall back to the JS implementation. Result is cached. The binding does not
+ *   exist yet (the plan is unbuilt) — this accessor is the seam so that when it
+ *   lands, only this file changes and `paths/walk`, `fs/access`, `fs/find-up`
+ *   light up natively. Today `getSmolPath()` is always `undefined` and the JS
+ *   paths run.
+ */
+import type { PathLike } from 'node:fs';
+/**
+ * Native path / filesystem fast-path surface. Only the operations socket-lib's
+ * helpers shim are typed; the binding may expose more. Every method is optional
+ * so a partial rollout (e.g. `dirname` ships before `access`) still type-checks
+ * at the shim sites.
+ */
+export interface SmolPathBinding {
+    /**
+     * `path.dirname` over the one-byte Fast API. ASCII fast path; two-byte inputs
+     * route to the equivalent of `path.dirname`.
+     */
+    dirname?: ((p: string) => string) | undefined;
+    /**
+     * `path.normalize` over the one-byte Fast API.
+     */
+    normalize?: ((p: string) => string) | undefined;
+    /**
+     * `fs.accessSync`-equivalent returning a boolean instead of throwing — skips
+     * the V8 error-object materialization the JS wrapper pays on every negative
+     * check. `mode` is an `fs.constants` bit.
+     */
+    access?: ((path: PathLike, mode?: number | undefined) => boolean) | undefined;
+    /**
+     * In-C++ find-up: walk `startDir`'s ancestors, return the first dir
+     * containing any of `names` (as a file unless `onlyDirectories`), or
+     * `undefined`. Collapses the N JS↔native crossings of the JS walk into one.
+     */
+    findUp?: ((startDir: string, names: readonly string[], options?: {
+        onlyDirectories?: boolean | undefined;
+    } | undefined) => string | undefined) | undefined;
+}
+/**
+ * Returns the `node:smol-path` binding when running on a smol Node binary that
+ * ships it; otherwise `undefined`. Cached across calls.
+ *
+ * @returns The native binding, or `undefined` to signal "use the JS fallback".
+ */
+export declare function getSmolPath(): SmolPathBinding | undefined;

package/dist/smol/path.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 path_exports = {};
+__export(path_exports, {
+  getSmolPath: () => getSmolPath
+});
+module.exports = __toCommonJS(path_exports);
+var import_module = require("../node/module");
+let _smolPath;
+let _smolPathProbed = false;
+// @__NO_SIDE_EFFECTS__
+function getSmolPath() {
+  if (!_smolPathProbed) {
+    _smolPathProbed = true;
+    if ((0, import_module.isNodeBuiltin)("node:smol-path")) {
+      _smolPath = require("node:smol-path");
+    }
+  }
+  return _smolPath;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getSmolPath
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [
     "Socket.dev",
@@ -1319,6 +1319,11 @@
       "types": "./dist/external-tools/uv/types.d.ts",
       "default": "./dist/external-tools/uv/types.js"
     },
+    "./fs/access": {
+      "source": "./src/fs/access.ts",
+      "types": "./dist/fs/access.d.ts",
+      "default": "./dist/fs/access.js"
+    },
     "./fs/encoding": {
       "source": "./src/fs/encoding.ts",
       "types": "./dist/fs/encoding.d.ts",
@@ -1359,6 +1364,11 @@
       "types": "./dist/fs/read-json-cache.d.ts",
       "default": "./dist/fs/read-json-cache.js"
     },
+    "./fs/resolve-module": {
+      "source": "./src/fs/resolve-module.ts",
+      "types": "./dist/fs/resolve-module.d.ts",
+      "default": "./dist/fs/resolve-module.js"
+    },
     "./fs/safe": {
       "source": "./src/fs/safe.ts",
       "types": "./dist/fs/safe.d.ts",
@@ -1990,6 +2000,11 @@
       "types": "./dist/paths/socket.d.ts",
       "default": "./dist/paths/socket.js"
     },
+    "./paths/walk": {
+      "source": "./src/paths/walk.ts",
+      "types": "./dist/paths/walk.d.ts",
+      "default": "./dist/paths/walk.js"
+    },
     "./perf/enabled": {
       "source": "./src/perf/enabled.ts",
       "types": "./dist/perf/enabled.d.ts",
@@ -2250,6 +2265,11 @@
       "types": "./dist/releases/github-listing.d.ts",
       "default": "./dist/releases/github-listing.js"
     },
+    "./releases/github-retry-config": {
+      "source": "./src/releases/github-retry-config.ts",
+      "types": "./dist/releases/github-retry-config.d.ts",
+      "default": "./dist/releases/github-retry-config.js"
+    },
     "./releases/github-types": {
       "source": "./src/releases/github-types.ts",
       "types": "./dist/releases/github-types.d.ts",
@@ -2350,6 +2370,11 @@
       "types": "./dist/smol/manifest.d.ts",
       "default": "./dist/smol/manifest.js"
     },
+    "./smol/path": {
+      "source": "./src/smol/path.ts",
+      "types": "./dist/smol/path.d.ts",
+      "default": "./dist/smol/path.js"
+    },
     "./smol/primordial": {
       "source": "./src/smol/primordial.ts",
       "types": "./dist/smol/primordial.d.ts",