@socketsecurity/lib 6.0.7 → 6.0.9

package/dist/paths/conversion.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_constants_platform = require('../constants/platform.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_constants_platform = require('../constants/platform.js');
 const require_paths__internal = require('./_internal.js');
 const require_paths_normalize = require('./normalize.js');
 

package/dist/paths/dirnames.d.ts

@@ -7,5 +7,6 @@ export declare const DOT_GITHUB = ".github";
 export declare const DOT_SOCKET_DIR = ".socket";
 export declare const CACHE_DIR = "cache";
 export declare const CACHE_TTL_DIR = "ttl";
+export declare const RUN_DIR = "run";
 export declare const NODE_MODULES_GLOB_RECURSIVE = "**/node_modules";
 export declare const SLASH_NODE_MODULES_SLASH = "/node_modules/";

package/dist/paths/dirnames.js

@@ -12,6 +12,7 @@ const DOT_GITHUB = ".github";
 const DOT_SOCKET_DIR = ".socket";
 const CACHE_DIR = "cache";
 const CACHE_TTL_DIR = "ttl";
+const RUN_DIR = "run";
 const NODE_MODULES_GLOB_RECURSIVE = "**/node_modules";
 const SLASH_NODE_MODULES_SLASH = "/node_modules/";
 
@@ -23,4 +24,5 @@ exports.DOT_GIT_DIR = DOT_GIT_DIR;
 exports.DOT_SOCKET_DIR = DOT_SOCKET_DIR;
 exports.NODE_MODULES = NODE_MODULES;
 exports.NODE_MODULES_GLOB_RECURSIVE = NODE_MODULES_GLOB_RECURSIVE;
+exports.RUN_DIR = RUN_DIR;
 exports.SLASH_NODE_MODULES_SLASH = SLASH_NODE_MODULES_SLASH;

package/dist/paths/normalize.js

@@ -1,8 +1,8 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_constants_platform = require('../constants/platform.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_constants_platform = require('../constants/platform.js');
 const require_strings_search = require('../strings/search.js');
 const require_paths__internal = require('./_internal.js');
 const require_paths_conversion = require('./conversion.js');

package/dist/paths/predicates.js

@@ -1,8 +1,9 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_constants_platform = require('../constants/platform.js');
 const require_primordials_string = require('../primordials/string.js');
+const require_constants_platform = require('../constants/platform.js');
+const require_constants_encoding = require('../constants/encoding.js');
 const require_paths__internal = require('./_internal.js');
 const require_primordials_regexp = require('../primordials/regexp.js');
 

package/dist/paths/resolve.js

@@ -1,11 +1,6 @@
 "use strict";
 /* Socket Lib - Built with rolldown */
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_constants_platform = require('../constants/platform.js');
-const require_primordials_string = require('../primordials/string.js');
-const require_paths__internal = require('./_internal.js');
-const require_paths_predicates = require('./predicates.js');
-const require_paths_normalize = require('./normalize.js');
 
 //#region src/paths/resolve.ts
 /**
@@ -44,7 +39,7 @@ function relative(from, to) {
 	const actualTo = resolve(to);
 	if (actualFrom === actualTo) return "";
 	/* c8 ignore start - Windows-only case-insensitive comparison. */
-	if (require_constants_platform.WIN32) {
+	if (WIN32) {
 		if (actualFrom.toLowerCase() === actualTo.toLowerCase()) return "";
 	}
 	/* c8 ignore stop */
@@ -57,32 +52,32 @@ function relative(from, to) {
 	let lastCommonSep = -1;
 	let i = 0;
 	for (; i < length; i += 1) {
-		let fromCode = require_primordials_string.StringPrototypeCharCodeAt(actualFrom, fromStart + i);
-		let toCode = require_primordials_string.StringPrototypeCharCodeAt(actualTo, toStart + i);
+		let fromCode = StringPrototypeCharCodeAt(actualFrom, fromStart + i);
+		let toCode = StringPrototypeCharCodeAt(actualTo, toStart + i);
 		/* c8 ignore start - Windows-only case folding. */
-		if (require_constants_platform.WIN32) {
-			if (fromCode >= 65 && fromCode <= 90) fromCode += 32;
-			if (toCode >= 65 && toCode <= 90) toCode += 32;
+		if (WIN32) {
+			if (fromCode >= CHAR_UPPERCASE_A && fromCode <= CHAR_UPPERCASE_Z) fromCode += 32;
+			if (toCode >= CHAR_UPPERCASE_A && toCode <= CHAR_UPPERCASE_Z) toCode += 32;
 		}
 		/* c8 ignore stop */
 		if (fromCode !== toCode) break;
-		if (require_paths_predicates.isPathSeparator(require_primordials_string.StringPrototypeCharCodeAt(actualFrom, fromStart + i))) lastCommonSep = i;
+		if (isPathSeparator(StringPrototypeCharCodeAt(actualFrom, fromStart + i))) lastCommonSep = i;
 	}
 	/* c8 ignore start */
 	if (i === length) {
 		if (toLen > length) {
-			if (require_paths_predicates.isPathSeparator(require_primordials_string.StringPrototypeCharCodeAt(actualTo, toStart + i))) return actualTo.slice(toStart + i + 1);
+			if (isPathSeparator(StringPrototypeCharCodeAt(actualTo, toStart + i))) return actualTo.slice(toStart + i + 1);
 			if (i === 0) return actualTo.slice(toStart + i);
 		} else if (fromLen > length) {
-			if (require_paths_predicates.isPathSeparator(require_primordials_string.StringPrototypeCharCodeAt(actualFrom, fromStart + i))) lastCommonSep = i;
+			if (isPathSeparator(StringPrototypeCharCodeAt(actualFrom, fromStart + i))) lastCommonSep = i;
 			else if (i === 0) lastCommonSep = 0;
 		}
 	}
 	/* c8 ignore stop */
 	let out = "";
 	for (i = fromStart + lastCommonSep + 1; i <= fromEnd; i += 1) {
-		const code = require_primordials_string.StringPrototypeCharCodeAt(actualFrom, i);
-		if (i === fromEnd || require_paths_predicates.isPathSeparator(code)) out += out.length === 0 ? ".." : "/..";
+		const code = StringPrototypeCharCodeAt(actualFrom, i);
+		if (i === fromEnd || isPathSeparator(code)) out += out.length === 0 ? ".." : "/..";
 	}
 	return out + actualTo.slice(toStart + lastCommonSep);
 }
@@ -108,7 +103,7 @@ function relative(from, to) {
 function relativeResolve(from, to) {
 	const rel = relative(from, to);
 	if (rel === "") return "";
-	return require_paths_normalize.normalizePath(rel);
+	return normalizePath(rel);
 }
 /**
 * Resolve an absolute path from path segments.
@@ -137,11 +132,11 @@ function resolve(...segments) {
 		/* c8 ignore start */
 		if (typeof segment !== "string" || segment.length === 0) continue;
 		resolvedPath = segment + (resolvedPath.length === 0 ? "" : `/${resolvedPath}`);
-		resolvedAbsolute = require_paths_predicates.isAbsolute(segment);
+		resolvedAbsolute = isAbsolute(segment);
 	}
 	if (!resolvedAbsolute) resolvedPath = /* @__PURE__ */ require("node:process").cwd() + (resolvedPath.length === 0 ? "" : `/${resolvedPath}`);
 	/* c8 ignore stop */
-	return require_paths_normalize.normalizePath(resolvedPath);
+	return normalizePath(resolvedPath);
 }
 
 //#endregion

package/dist/paths/rewire.d.ts

@@ -7,6 +7,11 @@
  *   - Automatic cache invalidation for path-dependent modules
  *   - Thread-safe for concurrent test execution
  */
+export interface PathRewireState {
+    testOverrides: Map<string, string | undefined>;
+    valueCache: Map<string, string>;
+    cacheInvalidationCallbacks: Array<() => void>;
+}
 /**
  * Clear a specific path override.
  */

package/dist/paths/socket.d.ts

@@ -1,12 +1,13 @@
 /**
- * @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.
+ * @file Path utilities for Socket ecosystem directories. Platform-aware
+ *   resolution for the shared ~/.socket/ layout. The `_`-prefixed entries are
+ *   Socket-managed DIRS (not apps): `_cacache` content-addressable cache;
+ *   `_dlx/<hash>/` name+version binary store (node, jre, python, sfw, …);
+ *   `_state/<app>/` version-LESS persistent app state (daemon socket + lock +
+ *   OAuth refresh; mirrors pnpm `state-dir` / XDG_STATE_HOME), with
+ *   `_state/<app>/run/` for a daemon's socket/lock/pid; `_wheelhouse`
+ *   cross-fleet shared bin. Generic per-app dirs (`getSocketAppDir('<name>')`)
+ *   nest under the same `_`-prefix.
  */
 /**
  * Get the OS home directory. Can be overridden in tests using
@@ -22,6 +23,26 @@ export declare function getOsHomeDir(): string;
  * setPath('tmpdir', ...) from paths/rewire.
  */
 export declare function getOsTmpDir(): string;
+/**
+ * Resolve the runtime socket path for a local daemon named `name`. Distinct
+ * from getSocketAppRuntimeDir (the persistent ~/.socket/_state/<app>/run/
+ * home): the SOCKET endpoint itself belongs in the ephemeral, owner-only XDG
+ * runtime dir — correctly permissioned and auto-cleaned on logout — while the
+ * downloaded daemon binary + durable token cache live under ~/.socket. The
+ * daemon and every client MUST compute the identical path (1 path, 1
+ * reference), so this is the single resolver both sides call.
+ *
+ * Resolution:
+ *
+ * - Windows: `\\.\pipe\<name>-sock` (named pipe; Unix sockets are unavailable
+ *   pre-Win10 1803, same framing/semantics). Returned raw — a pipe path is not
+ *   a filesystem path and must not be slash-normalized.
+ * - `$XDG_RUNTIME_DIR/<name>.sock` when XDG_RUNTIME_DIR is set (systemd
+ *   `/run/user/<uid>/`).
+ * - Else `$TMPDIR/<name>-<uid>.sock` (the `<uid>` suffix avoids collisions when
+ *   TMPDIR is shared across users on a multi-tenant box).
+ */
+export declare function getRuntimeSocketPath(name: string): string;
 /**
  * Get a Socket app cache directory (~/.socket/_<appName>/cache).
  */
@@ -37,67 +58,56 @@ export declare function getSocketAppCacheDir(appName: string): string;
  */
 export declare function getSocketAppCacheTtlDir(appName: string): string;
 /**
- * Get a Socket app directory (~/.socket/_<appName>).
+ * Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+ * here; pass the bare app name (e.g. 'socket', 'registry').
  */
 /**
- * Get a Socket app directory (~/.socket/_<appName>).
+ * Get a Socket app directory (~/.socket/_<appName>). The `_` prefix is applied
+ * here; pass the bare app name (e.g. 'socket', 'registry').
  */
 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.
- *
- * 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). Override precedence:
+ * setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+ * $SOCKET_HOME/_cacache → $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
+ * Get an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+ * daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+ * the socket path is stable across binary upgrades.
  */
-export declare function getSocketCacacheDir(): string;
+export declare function getSocketAppRuntimeDir(appName: string): string;
 /**
- * Get the Socket CLI directory (~/.socket/_socket).
+ * Get the Socket user directory (~/.socket). Override precedence:
+ * setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+ * /tmp/.socket (Unix) or %TEMP%.socket (Windows).
  */
 /**
- * Get the Socket CLI directory (~/.socket/_socket).
+ * Get an app's persistent state directory (~/.socket/_state/<app>/). The
+ * `<app>` is a real app (proteus, acorn) nesting its version-less state inside
+ * the `_state` infra dir.
  */
-export declare function getSocketCliDir(): string;
+export declare function getSocketAppStateDir(appName: string): 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.
- *
- * 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 an app's runtime directory (~/.socket/_state/<app>/run/) — the home for a
+ * daemon's Unix socket + `concurrency.lock` + `<socket>.pid`. Version-less so
+ * the socket path is stable across binary upgrades.
  */
 /**
- * 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 cacache directory (~/.socket/_cacache). Override precedence:
+ * setPath('socket-cacache-dir', …) → SOCKET_CACACHE_DIR env →
+ * $SOCKET_HOME/_cacache → $HOME/.socket/_cacache.
+ */
+export declare function getSocketCacacheDir(): string;
+/**
+ * Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+ * (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+ * …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
+ */
+/**
+ * Get the Socket DLX directory (~/.socket/_dlx) — the name+version binary store
+ * (node, jre, python, sfw, …). Override precedence: setPath('socket-dlx-dir',
+ * …) → SOCKET_DLX_DIR env → $SOCKET_HOME/_dlx → $HOME/.socket/_dlx.
  */
 export declare function getSocketDlxDir(): string;
 /**
@@ -110,91 +120,95 @@ export declare function getSocketDlxDir(): string;
  */
 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).
- */
-export declare function getSocketRegistryGithubCacheDir(): string;
-/**
- * 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)
+ * Get the Wheelhouse rack directory (~/.socket/_wheelhouse/rack) — the tool
+ * STORE. Every `_wheelhouse`-managed CLI tool keeps its real binaries here,
+ * racked by name + version as `<rack>/<tool>/<version>/…` (the wheelhouse
+ * analog of Homebrew's `Cellar/`). The handles on PATH live in
+ * `<wheelhouse>/bin` (getSocketWheelhouseBinDir) and point into the rack.
+ * Inherits the `_wheelhouse` override chain (SOCKET_HOME /
+ * setPath('socket-wheelhouse-dir')).
+ */
+export declare function getSocketRackDir(): string;
+/**
+ * Get a racked tool's version directory (~/.socket/_wheelhouse/rack/<tool>/
+ * <version>) — the per-tool, per-version home under the rack. The
+ * 1-path-1-reference owner of a tool install destination: installers resolve
+ * their extract/copy target through this, and the `<wheelhouse>/bin/<tool>`
+ * shim points at a binary inside it.
+ */
+export declare function getSocketRackToolDir(options: {
+    tool: string;
+    version: string;
+}): string;
+/**
+ * Get the Wheelhouse repo-clones directory (~/.socket/_wheelhouse/repo-clones).
+ * Sits beside the per-tool dirs (sfw, codedb, janus, bin) under `_wheelhouse`.
+ * The home for reference clones of EXTERNAL repos an agent reviews, each as
+ * `<org>-<repo>` lowercased + dash-cased (e.g. `justrach-codedb`).
+ *
+ * Smallest-practical clone form (smallest disk + fastest initial fetch without
+ * the treeless tax): git clone --depth=1 --single-branch --filter=blob:none
+ * <url> <dest> `--depth=1` truncates history, `--single-branch` skips other
+ * refs, and `--filter=blob:none` (a BLOBLESS partial clone) fetches file blobs
+ * lazily on first access — so the initial download is tree-metadata only.
+ * (Treeless `--filter=tree:0` is smaller still but refetches trees on every
+ * walk, which is slow + breaks offline, so it is NOT the default.)
+ *
+ * Deliberately OUTSIDE `~/projects/` so the fleet's sibling-walk tooling (e.g.
+ * cascade `--all`) never mistakes a reference clone for a fleet member
+ * checkout. Disposable: a reference cache, not a working tree. Inherits the
+ * `_wheelhouse` override chain (SOCKET_HOME /
+ * setPath('socket-wheelhouse-dir')).
+ */
+export declare function getSocketRepoClonesDir(): string;
+/**
+ * Get the Socket state directory (~/.socket/_state) — version-LESS persistent
+ * app state (the home for daemon sockets, locks, OAuth refresh, durable caches
+ * that survive version bumps; mirrors pnpm `state-dir` / XDG_STATE_HOME).
+ * Override precedence: setPath('socket-state-dir', …) → SOCKET_STATE_DIR env →
+ * $SOCKET_HOME/_state → $HOME/.socket/_state.
+ */
+export declare function getSocketStateDir(): string;
+/**
+ * Get the Socket user directory (~/.socket). Override precedence:
+ * setPath('socket-user-dir', …) → SOCKET_HOME env → $HOME/.socket →
+ * /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.
- *
- * 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 Wheelhouse bin directory (~/.socket/_wheelhouse/bin) — the single
+ * directory placed on PATH. Holds only flat handles (thin exec shims or
+ * symlinks), one per tool, each pointing at a real binary racked under
+ * `<wheelhouse>/rack/<tool>/<version>/…` (getSocketRackToolDir). The shim IS
+ * the bin, the npm `prefix/bin` / Homebrew `bin/` model: PATH lookup does not
+ * recurse, so this dir stays flat (never a `bin/<tool>/` subdir). Inherits the
+ * `_wheelhouse` override chain (SOCKET_HOME /
+ * setPath('socket-wheelhouse-dir')).
  */
+export declare function getSocketWheelhouseBinDir(): string;
 /**
  * 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
+ * sfw, etc.) rack their resolved executables under
+ * `<wheelhouse>/rack/<tool>/<version>/…` (getSocketRackToolDir) and expose a
+ * handle in `<wheelhouse>/bin` (getSocketWheelhouseBinDir); consumers add that
+ * one `bin/` to PATH. Override precedence: setPath('socket-wheelhouse-dir', …)
+ * → $SOCKET_HOME/_wheelhouse → $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:
+ * Get the user's home directory. Uses environment variables directly to support
+ * test mocking. Falls back to temporary directory if home is not available.
  *
- * 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)
+ * Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+ * getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
  */
 /**
  * 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)
+ * Priority order: 1. HOME (Unix) 2. USERPROFILE (Windows) 3.
+ * getNodeOs().homedir() 4. Fallback: getNodeOs().tmpdir() (restricted envs).
  */
 export declare function getUserHomeDir(): string;