@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/paths/socket.d.ts

@@ -1,101 +1,200 @@
 /**
- * @fileoverview Path utilities for Socket ecosystem directories.
- * Provides platform-aware path resolution for Socket tools' shared directory structure.
- *
- * Directory Structure:
- * ~/.socket/
- * ├── _cacache/           # Content-addressable cache for npm packages
- * ├── _dlx/               # DLX installations (content-addressed by hash)
- * │   ├── <hash>/         # npm package installs (dlx-package)
- * │   └── <hash>/         # binary downloads (dlx-binary)
- * ├── _socket/            # Socket CLI app directory
- * ├── _registry/          # Socket Registry app directory
- * └── _sfw/               # Socket Firewall app directory
+ * @file Path utilities for Socket ecosystem directories. Provides
+ *   platform-aware path resolution for Socket tools' shared directory
+ *   structure. Directory Structure: ~/.socket/ ├── _cacache/ #
+ *   Content-addressable cache for npm packages ├── _dlx/ # DLX installations
+ *   (content-addressed by hash) │ ├── <hash>/ # npm package installs
+ *   (dlx-package) │ └── <hash>/ # binary downloads (dlx-binary) ├── _socket/ #
+ *   Socket CLI app directory ├── _registry/ # Socket Registry app directory └──
+ *   _sfw/ # Socket Firewall app directory.
  */
 /**
- * Get the OS home directory.
- * Can be overridden in tests using setPath('homedir', ...) from paths/rewire.
+ * Get the OS home directory. Can be overridden in tests using
+ * setPath('homedir', ...) from paths/rewire.
  */
 export declare function getOsHomeDir(): string;
 /**
- * Get the OS temporary directory.
- * Can be overridden in tests using setPath('tmpdir', ...) from paths/rewire.
+ * Get the OS temporary directory. Can be overridden in tests using
+ * setPath('tmpdir', ...) from paths/rewire.
+ */
+/**
+ * Get the OS temporary directory. Can be overridden in tests using
+ * setPath('tmpdir', ...) from paths/rewire.
  */
 export declare function getOsTmpDir(): string;
+/**
+ * Get a Socket app cache directory (~/.socket/_<appName>/cache).
+ */
 /**
  * Get a Socket app cache directory (~/.socket/_<appName>/cache).
  */
 export declare function getSocketAppCacheDir(appName: string): string;
+/**
+ * Get a Socket app TTL cache directory (~/.socket/_<appName>/cache/ttl).
+ */
 /**
  * Get a Socket app TTL cache directory (~/.socket/_<appName>/cache/ttl).
  */
 export declare function getSocketAppCacheTtlDir(appName: string): string;
+/**
+ * Get a Socket app directory (~/.socket/_<appName>).
+ */
 /**
  * Get a Socket app directory (~/.socket/_<appName>).
  */
 export declare function getSocketAppDir(appName: string): string;
 /**
- * Get the Socket cacache directory (~/.socket/_cacache).
- * Can be overridden with SOCKET_CACACHE_DIR environment variable or via setPath() for testing.
- * Result is cached via getPathValue for performance.
+ * Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
+ * SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
+ * is cached via getPathValue for performance.
+ *
+ * Priority order:
+ *
+ * 1. Test override via setPath('socket-cacache-dir', ...)
+ * 2. SOCKET_CACACHE_DIR - Full override of cacache directory
+ * 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+ */
+/**
+ * Get the Socket cacache directory (~/.socket/_cacache). Can be overridden with
+ * SOCKET_CACACHE_DIR environment variable or via setPath() for testing. Result
+ * is cached via getPathValue for performance.
  *
  * Priority order:
- *   1. Test override via setPath('socket-cacache-dir', ...)
- *   2. SOCKET_CACACHE_DIR - Full override of cacache directory
- *   3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
+ *
+ * 1. Test override via setPath('socket-cacache-dir', ...)
+ * 2. SOCKET_CACACHE_DIR - Full override of cacache directory
+ * 3. Default: $SOCKET_HOME/_cacache or $HOME/.socket/_cacache
  */
 export declare function getSocketCacacheDir(): string;
+/**
+ * Get the Socket CLI directory (~/.socket/_socket).
+ */
 /**
  * Get the Socket CLI directory (~/.socket/_socket).
  */
 export declare function getSocketCliDir(): string;
 /**
- * Get the Socket DLX directory (~/.socket/_dlx).
- * Can be overridden with SOCKET_DLX_DIR environment variable or via setPath() for testing.
- * Result is cached via getPathValue for performance.
+ * Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
+ * SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
+ * cached via getPathValue for performance.
+ *
+ * Priority order:
+ *
+ * 1. Test override via setPath('socket-dlx-dir', ...)
+ * 2. SOCKET_DLX_DIR - Full override of DLX cache directory
+ * 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
+ * 4. Default: $HOME/.socket/_dlx
+ * 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
+ */
+/**
+ * Get the Socket DLX directory (~/.socket/_dlx). Can be overridden with
+ * SOCKET_DLX_DIR environment variable or via setPath() for testing. Result is
+ * cached via getPathValue for performance.
  *
  * Priority order:
- *   1. Test override via setPath('socket-dlx-dir', ...)
- *   2. SOCKET_DLX_DIR - Full override of DLX cache directory
- *   3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
- *   4. Default: $HOME/.socket/_dlx
- *   5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%\.socket\_dlx (Windows)
+ *
+ * 1. Test override via setPath('socket-dlx-dir', ...)
+ * 2. SOCKET_DLX_DIR - Full override of DLX cache directory
+ * 3. SOCKET_HOME/_dlx - Base directory override (inherits from getSocketUserDir)
+ * 4. Default: $HOME/.socket/_dlx
+ * 5. Fallback: /tmp/.socket/_dlx (Unix) or %TEMP%.socket_dlx (Windows)
  */
 export declare function getSocketDlxDir(): string;
 /**
- * Get the Socket home directory (~/.socket).
- * Alias for getSocketUserDir() for consistency across Socket projects.
+ * Get the Socket home directory (~/.socket). Alias for getSocketUserDir() for
+ * consistency across Socket projects.
+ */
+/**
+ * Get the Socket home directory (~/.socket). Alias for getSocketUserDir() for
+ * consistency across Socket projects.
  */
 export declare function getSocketHomePath(): string;
+/**
+ * Get the Socket Registry directory (~/.socket/_registry).
+ */
 /**
  * Get the Socket Registry directory (~/.socket/_registry).
  */
 export declare function getSocketRegistryDir(): string;
 /**
- * Get the Socket Registry GitHub cache directory (~/.socket/_registry/cache/ttl/github).
+ * Get the Socket Registry GitHub cache directory
+ * (~/.socket/_registry/cache/ttl/github).
+ */
+/**
+ * Get the Socket Registry GitHub cache directory
+ * (~/.socket/_registry/cache/ttl/github).
  */
 export declare function getSocketRegistryGithubCacheDir(): string;
 /**
- * Get the Socket user directory (~/.socket).
- * Can be overridden with SOCKET_HOME environment variable or via setPath() for testing.
- * Result is cached via getPathValue for performance.
+ * Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
+ * cross-fleet location for binaries that every fleet member can reach without
+ * each one re-downloading and re-extracting per-repo. Tool installers (janus,
+ * sfw, etc.) drop their resolved executables under
+ * `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
+ * appropriate `bin/` to PATH or invoke the binary by absolute path.
+ *
+ * Priority order:
+ *
+ * 1. Test override via setPath('socket-wheelhouse-dir', ...)
+ * 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
+ *    getSocketUserDir)
+ * 3. Default: $HOME/.socket/_wheelhouse
+ */
+/**
+ * Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
+ * environment variable or via setPath() for testing. Result is cached via
+ * getPathValue for performance.
  *
  * Priority order:
- *   1. Test override via setPath('socket-user-dir', ...)
- *   2. SOCKET_HOME - Base directory override
- *   3. Default: $HOME/.socket
- *   4. Fallback: /tmp/.socket (Unix) or %TEMP%\.socket (Windows)
+ *
+ * 1. Test override via setPath('socket-user-dir', ...)
+ * 2. SOCKET_HOME - Base directory override
+ * 3. Default: $HOME/.socket
+ * 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
  */
 export declare function getSocketUserDir(): string;
 /**
- * Get the user's home directory.
- * Uses environment variables directly to support test mocking.
- * Falls back to temporary directory if home is not available.
+ * Get the user's home directory. Uses environment variables directly to support
+ * test mocking. Falls back to temporary directory if home is not available.
+ *
+ * Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
+ * environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
+ * getNodeOs().tmpdir() (rarely used, for restricted environments)
+ */
+/**
+ * Get the Socket Wheelhouse directory (~/.socket/_wheelhouse). Shared
+ * cross-fleet location for binaries that every fleet member can reach without
+ * each one re-downloading and re-extracting per-repo. Tool installers (janus,
+ * sfw, etc.) drop their resolved executables under
+ * `<wheelhouse>/<tool>/<version>/<platform-arch>/`; consumers add the
+ * appropriate `bin/` to PATH or invoke the binary by absolute path.
  *
  * Priority order:
- *   1. HOME environment variable (Unix)
- *   2. USERPROFILE environment variable (Windows)
- *   3. getOs().homedir()
- *   4. Fallback: getOs().tmpdir() (rarely used, for restricted environments)
+ *
+ * 1. Test override via setPath('socket-wheelhouse-dir', ...)
+ * 2. SOCKET_HOME/_wheelhouse - Base directory override (inherits from
+ *    getSocketUserDir)
+ * 3. Default: $HOME/.socket/_wheelhouse
+ */
+export declare function getSocketWheelhouseDir(): string;
+/**
+ * Get the Socket user directory (~/.socket). Can be overridden with SOCKET_HOME
+ * environment variable or via setPath() for testing. Result is cached via
+ * getPathValue for performance.
+ *
+ * Priority order:
+ *
+ * 1. Test override via setPath('socket-user-dir', ...)
+ * 2. SOCKET_HOME - Base directory override
+ * 3. Default: $HOME/.socket
+ * 4. Fallback: /tmp/.socket (Unix) or %TEMP%.socket (Windows)
+ */
+/**
+ * Get the user's home directory. Uses environment variables directly to support
+ * test mocking. Falls back to temporary directory if home is not available.
+ *
+ * Priority order: 1. HOME environment variable (Unix) 2. USERPROFILE
+ * environment variable (Windows) 3. getNodeOs().homedir() 4. Fallback:
+ * getNodeOs().tmpdir() (rarely used, for restricted environments)
  */
 export declare function getUserHomeDir(): string;

package/dist/paths/socket.js

@@ -32,6 +32,7 @@ __export(socket_exports, {
   getSocketRegistryDir: () => getSocketRegistryDir,
   getSocketRegistryGithubCacheDir: () => getSocketRegistryGithubCacheDir,
   getSocketUserDir: () => getSocketUserDir,
+  getSocketWheelhouseDir: () => getSocketWheelhouseDir,
   getUserHomeDir: () => getUserHomeDir
 });
 module.exports = __toCommonJS(socket_exports);
@@ -43,39 +44,25 @@ var import_windows = require("../env/windows");
 var import_dirnames = require("./dirnames");
 var import_normalize = require("./normalize");
 var import_rewire = require("./rewire");
-let _os;
-let _path;
-// @__NO_SIDE_EFFECTS__
-function getOs() {
-  if (_os === void 0) {
-    _os = require("node:os");
-  }
-  return _os;
-}
-// @__NO_SIDE_EFFECTS__
-function getPath() {
-  if (_path === void 0) {
-    _path = require("node:path");
-  }
-  return _path;
-}
+var import_os = require("../node/os");
+var import_path = require("../node/path");
 function getOsHomeDir() {
-  return (0, import_rewire.getPathValue)("homedir", () => (/* @__PURE__ */ getOs()).homedir());
+  return (0, import_rewire.getPathValue)("homedir", () => (0, import_os.getNodeOs)().homedir());
 }
 function getOsTmpDir() {
-  return (0, import_rewire.getPathValue)("tmpdir", () => (/* @__PURE__ */ getOs()).tmpdir());
+  return (0, import_rewire.getPathValue)("tmpdir", () => (0, import_os.getNodeOs)().tmpdir());
 }
 function getSocketAppCacheDir(appName) {
-  return (0, import_normalize.normalizePath)((/* @__PURE__ */ getPath()).join(getSocketAppDir(appName), import_dirnames.CACHE_DIR));
+  return (0, import_normalize.normalizePath)((0, import_path.getNodePath)().join(getSocketAppDir(appName), import_dirnames.CACHE_DIR));
 }
 function getSocketAppCacheTtlDir(appName) {
   return (0, import_normalize.normalizePath)(
-    (/* @__PURE__ */ getPath()).join(getSocketAppCacheDir(appName), import_dirnames.CACHE_TTL_DIR)
+    (0, import_path.getNodePath)().join(getSocketAppCacheDir(appName), import_dirnames.CACHE_TTL_DIR)
   );
 }
 function getSocketAppDir(appName) {
   return (0, import_normalize.normalizePath)(
-    (/* @__PURE__ */ getPath()).join(getSocketUserDir(), `${import_socket.SOCKET_APP_PREFIX}${appName}`)
+    (0, import_path.getNodePath)().join(getSocketUserDir(), `${import_socket.SOCKET_APP_PREFIX}${appName}`)
   );
 }
 function getSocketCacacheDir() {
@@ -84,7 +71,7 @@ function getSocketCacacheDir() {
       return (0, import_normalize.normalizePath)((0, import_socket2.getSocketCacacheDirEnv)());
     }
     return (0, import_normalize.normalizePath)(
-      (/* @__PURE__ */ getPath()).join(getSocketUserDir(), `${import_socket.SOCKET_APP_PREFIX}cacache`)
+      (0, import_path.getNodePath)().join(getSocketUserDir(), `${import_socket.SOCKET_APP_PREFIX}cacache`)
     );
   });
 }
@@ -97,7 +84,7 @@ function getSocketDlxDir() {
       return (0, import_normalize.normalizePath)((0, import_socket2.getSocketDlxDirEnv)());
     }
     return (0, import_normalize.normalizePath)(
-      (/* @__PURE__ */ getPath()).join(
+      (0, import_path.getNodePath)().join(
         getSocketUserDir(),
         `${import_socket.SOCKET_APP_PREFIX}${import_socket.SOCKET_DLX_APP_NAME}`
       )
@@ -112,7 +99,7 @@ function getSocketRegistryDir() {
 }
 function getSocketRegistryGithubCacheDir() {
   return (0, import_normalize.normalizePath)(
-    (/* @__PURE__ */ getPath()).join(
+    (0, import_path.getNodePath)().join(
       getSocketAppCacheTtlDir(import_socket.SOCKET_REGISTRY_APP_NAME),
       import_github.CACHE_GITHUB_DIR
     )
@@ -124,7 +111,17 @@ function getSocketUserDir() {
     if (socketHome) {
       return (0, import_normalize.normalizePath)(socketHome);
     }
-    return (0, import_normalize.normalizePath)((/* @__PURE__ */ getPath()).join(getUserHomeDir(), import_dirnames.DOT_SOCKET_DIR));
+    return (0, import_normalize.normalizePath)((0, import_path.getNodePath)().join(getUserHomeDir(), import_dirnames.DOT_SOCKET_DIR));
+  });
+}
+function getSocketWheelhouseDir() {
+  return (0, import_rewire.getPathValue)("socket-wheelhouse-dir", () => {
+    return (0, import_normalize.normalizePath)(
+      (0, import_path.getNodePath)().join(
+        getSocketUserDir(),
+        `${import_socket.SOCKET_APP_PREFIX}${import_socket.SOCKET_WHEELHOUSE_APP_NAME}`
+      )
+    );
   });
 }
 function getUserHomeDir() {
@@ -159,5 +156,6 @@ function getUserHomeDir() {
   getSocketRegistryDir,
   getSocketRegistryGithubCacheDir,
   getSocketUserDir,
+  getSocketWheelhouseDir,
   getUserHomeDir
 });

package/dist/perf/_internal.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file Private internals for `perf/*` modules — the shared in-process metrics
+ *   array. Every recording function (timer, checkpoint, memory tracker) appends
+ *   here; readers (`metrics`, `report`) consume the same array.
+ */
+import type { PerformanceMetrics } from './types';
+/**
+ * Global metrics collection (only in debug mode).
+ */
+export declare const performanceMetrics: PerformanceMetrics[];

package/dist/perf/_internal.js

@@ -0,0 +1,30 @@
+"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 internal_exports = {};
+__export(internal_exports, {
+  performanceMetrics: () => performanceMetrics
+});
+module.exports = __toCommonJS(internal_exports);
+const performanceMetrics = [];
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  performanceMetrics
+});

package/dist/perf/enabled.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Feature-flag check — `isPerfEnabled()` returns true when `DEBUG=perf`
+ *   is set in the environment. Every recording entry (timer / checkpoint /
+ *   memory) bails out cheaply when this is false.
+ */
+/**
+ * Check if performance tracking is enabled.
+ *
+ * Reads `DEBUG` through `getEnvValue` so tests can mock the value via
+ * `setEnv('DEBUG', 'perf')` from `@socketsecurity/lib/env/rewire` without
+ * mutating `process.env`.
+ */
+export declare function isPerfEnabled(): boolean;

package/dist/perf/enabled.js

@@ -0,0 +1,33 @@
+"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 enabled_exports = {};
+__export(enabled_exports, {
+  isPerfEnabled: () => isPerfEnabled
+});
+module.exports = __toCommonJS(enabled_exports);
+var import_rewire = require("../env/rewire");
+function isPerfEnabled() {
+  return (0, import_rewire.getEnvValue)("DEBUG")?.includes("perf") || false;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isPerfEnabled
+});

package/dist/perf/metrics.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file Read-side helpers — `getPerformanceMetrics` returns a shallow copy of
+ *   the recorded rows, `getPerformanceSummary` rolls them up per operation
+ *   (count / total / avg / min / max), and `clearPerformanceMetrics` empties
+ *   the array in place.
+ */
+import type { PerformanceMetrics } from './types';
+/**
+ * Clear all collected performance metrics.
+ *
+ * @example
+ *   import { clearPerformanceMetrics } from '@socketsecurity/lib/perf/metrics'
+ *
+ *   clearPerformanceMetrics()
+ */
+export declare function clearPerformanceMetrics(): void;
+/**
+ * Get all collected performance metrics. Only available when DEBUG=perf is
+ * enabled.
+ *
+ * @example
+ *   import { getPerformanceMetrics } from '@socketsecurity/lib/perf/metrics'
+ *
+ *   const metrics = getPerformanceMetrics()
+ *   console.log(metrics)
+ *
+ * @returns Array of performance metrics
+ */
+export declare function getPerformanceMetrics(): PerformanceMetrics[];
+/**
+ * Get performance summary statistics.
+ *
+ * @example
+ *   import { getPerformanceSummary } from '@socketsecurity/lib/perf/metrics'
+ *
+ *   const summary = getPerformanceSummary()
+ *   console.log(summary)
+ *   // {
+ *   //   'api-call': { count: 5, total: 1234, avg: 246.8, min: 100, max: 500 },
+ *   //   'file-read': { count: 10, total: 50, avg: 5, min: 2, max: 15 }
+ *   // }
+ *
+ * @returns Summary of metrics grouped by operation
+ */
+export declare function getPerformanceSummary(): Record<string, {
+    count: number;
+    total: number;
+    avg: number;
+    min: number;
+    max: number;
+}>;

package/dist/perf/metrics.js

@@ -0,0 +1,74 @@
+"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 metrics_exports = {};
+__export(metrics_exports, {
+  clearPerformanceMetrics: () => clearPerformanceMetrics,
+  getPerformanceMetrics: () => getPerformanceMetrics,
+  getPerformanceSummary: () => getPerformanceSummary
+});
+module.exports = __toCommonJS(metrics_exports);
+var import_output = require("../debug/output");
+var import_math = require("../primordials/math");
+var import_object = require("../primordials/object");
+var import_internal = require("./_internal");
+function clearPerformanceMetrics() {
+  import_internal.performanceMetrics.length = 0;
+  (0, import_output.debugLog)("[perf] Cleared performance metrics");
+}
+function getPerformanceMetrics() {
+  return [...import_internal.performanceMetrics];
+}
+function getPerformanceSummary() {
+  const summary = { __proto__: null };
+  for (const metric of import_internal.performanceMetrics) {
+    const { duration, operation } = metric;
+    if (!summary[operation]) {
+      summary[operation] = {
+        count: 0,
+        total: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY
+      };
+    }
+    const stats = summary[operation];
+    stats.count++;
+    stats.total += duration;
+    stats.min = (0, import_math.MathMin)(stats.min, duration);
+    stats.max = (0, import_math.MathMax)(stats.max, duration);
+  }
+  const result = { __proto__: null };
+  for (const { 0: operation, 1: stats } of (0, import_object.ObjectEntries)(summary)) {
+    result[operation] = {
+      count: stats.count,
+      total: (0, import_math.MathRound)(stats.total * 100) / 100,
+      avg: (0, import_math.MathRound)(stats.total / stats.count * 100) / 100,
+      min: (0, import_math.MathRound)(stats.min * 100) / 100,
+      max: (0, import_math.MathRound)(stats.max * 100) / 100
+    };
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  clearPerformanceMetrics,
+  getPerformanceMetrics,
+  getPerformanceSummary
+});

package/dist/perf/report.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Report-side helpers — `generatePerformanceReport` returns a multi-line
+ *   ASCII-bordered report string; `printPerformanceSummary` writes a
+ *   one-line-per-op summary through `debugLog`. Both gate on `isPerfEnabled()`
+ *   and use the same `getPerformanceSummary` rollup.
+ */
+/**
+ * Create a performance report for the current execution. Only available when
+ * DEBUG=perf is enabled.
+ *
+ * @example
+ *   import { generatePerformanceReport } from '@socketsecurity/lib/perf/report'
+ *
+ *   console.log(generatePerformanceReport())
+ *   // ╔═══════════════════════════════════════════════╗
+ *   // ║         Performance Report                    ║
+ *   // ╚═══════════════════════════════════════════════╝
+ *   //
+ *   // api-call:
+ *   //   Calls: 5
+ *   //   Avg:   246.8ms
+ *   //   Min:   100ms
+ *   //   Max:   500ms
+ *   //   Total: 1234ms
+ *
+ * @returns Formatted performance report
+ */
+export declare function generatePerformanceReport(): string;
+/**
+ * Print performance summary to console. Only prints when DEBUG=perf is enabled.
+ *
+ * @example
+ *   import { printPerformanceSummary } from '@socketsecurity/lib/perf/report'
+ *
+ *   printPerformanceSummary()
+ *   // Performance Summary:
+ *   // api-call: 5 calls, avg 246.8ms (min 100ms, max 500ms, total 1234ms)
+ *   // file-read: 10 calls, avg 5ms (min 2ms, max 15ms, total 50ms)
+ */
+export declare function printPerformanceSummary(): void;