@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/effects/shimmer.js

@@ -38,39 +38,11 @@ __export(shimmer_exports, {
   solidColor: () => solidColor
 });
 module.exports = __toCommonJS(shimmer_exports);
-var import_primordials = require("../primordials");
+var import_array = require("../primordials/array");
+var import_error = require("../primordials/error");
+var import_math = require("../primordials/math");
 const DEFAULT_BASE_COLOR = [140, 82, 255];
 const WHITE = [255, 255, 255];
-function blendRgb(a, b, t) {
-  const k = t < 0 ? 0 : t > 1 ? 1 : t;
-  return [
-    (0, import_primordials.MathRound)(a[0] + (b[0] - a[0]) * k),
-    (0, import_primordials.MathRound)(a[1] + (b[1] - a[1]) * k),
-    (0, import_primordials.MathRound)(a[2] + (b[2] - a[2]) * k)
-  ];
-}
-function gradient(palette) {
-  if (palette.length === 0) {
-    throw new import_primordials.ErrorCtor("gradient palette must not be empty");
-  }
-  return (i) => palette[i % palette.length];
-}
-function solidColor(color) {
-  return () => color;
-}
-function blockKernel(halfWidth = 1) {
-  return (d, ctx) => (0, import_primordials.MathAbs)(d) <= halfWidth ? ctx.highlightColor : ctx.baseColor;
-}
-function smoothKernel(halfWidth = 2.5, falloff = 2.5) {
-  return (d, ctx) => {
-    const dist = (0, import_primordials.MathAbs)(d);
-    if (dist >= halfWidth) {
-      return ctx.baseColor;
-    }
-    const t = (1 - dist / halfWidth) ** falloff;
-    return blendRgb(ctx.baseColor, ctx.highlightColor, t);
-  };
-}
 function bidirectionalSweep(textLength, padding = 2) {
   const cycle = textLength + 2 * padding;
   const fullCycle = cycle * 2;
@@ -82,45 +54,16 @@ function bidirectionalSweep(textLength, padding = 2) {
     return textLength + padding - 1 - (f - cycle);
   };
 }
-function ltrSweep(textLength, padding = 2) {
-  const cycle = textLength + 2 * padding;
-  return (frame) => (frame % cycle + cycle) % cycle - padding;
-}
-function noSweep() {
-  return () => -Infinity;
-}
-function randomSweep(textLength, padding = 2, random = Math.random) {
-  const cycle = textLength + 2 * padding;
-  let dir = random() < 0.5 ? "ltr" : "rtl";
-  let lastCycleIndex = 0;
-  return (frame) => {
-    const f = (frame % (cycle * 2 ** 30) + cycle * 2 ** 30) % (cycle * 2 ** 30);
-    const cycleIndex = (0, import_primordials.MathFloor)(f / cycle);
-    if (cycleIndex !== lastCycleIndex) {
-      dir = random() < 0.5 ? "ltr" : "rtl";
-      lastCycleIndex = cycleIndex;
-    }
-    const inCycle = f % cycle;
-    return dir === "ltr" ? inCycle - padding : textLength + padding - 1 - inCycle;
-  };
-}
-function rtlSweep(textLength, padding = 2) {
-  const cycle = textLength + 2 * padding;
-  return (frame) => textLength + padding - 1 - (frame % cycle + cycle) % cycle;
+function blendRgb(a, b, t) {
+  const k = t < 0 ? 0 : t > 1 ? 1 : t;
+  return [
+    (0, import_math.MathRound)(a[0] + (b[0] - a[0]) * k),
+    (0, import_math.MathRound)(a[1] + (b[1] - a[1]) * k),
+    (0, import_math.MathRound)(a[2] + (b[2] - a[2]) * k)
+  ];
 }
-function directionToSweep(dir, textLength, padding) {
-  switch (dir) {
-    case "rtl":
-      return rtlSweep(textLength, padding);
-    case "bi":
-      return bidirectionalSweep(textLength, padding);
-    case "random":
-      return randomSweep(textLength, padding);
-    case "none":
-      return noSweep();
-    default:
-      return ltrSweep(textLength, padding);
-  }
+function blockKernel(halfWidth = 1) {
+  return (d, ctx) => (0, import_math.MathAbs)(d) <= halfWidth ? ctx.highlightColor : ctx.baseColor;
 }
 function configToSpec(config, textLength) {
   const dir = config.dir ?? "ltr";
@@ -137,14 +80,19 @@ function configToSpec(config, textLength) {
     highlightColor
   };
 }
-function resolvePalette(source, defaultColor) {
-  if (source === void 0) {
-    return solidColor(defaultColor);
-  }
-  if ((0, import_primordials.ArrayIsArray)(source[0])) {
-    return gradient(source);
+function directionToSweep(dir, textLength, padding) {
+  switch (dir) {
+    case "rtl":
+      return rtlSweep(textLength, padding);
+    case "bi":
+      return bidirectionalSweep(textLength, padding);
+    case "random":
+      return randomSweep(textLength, padding);
+    case "none":
+      return noSweep();
+    default:
+      return ltrSweep(textLength, padding);
   }
-  return solidColor(source);
 }
 function frameColors(spec, textLength, frame) {
   const wavePos = spec.positionAt(frame);
@@ -159,6 +107,60 @@ function frameColors(spec, textLength, frame) {
   }
   return out;
 }
+function gradient(palette) {
+  if (palette.length === 0) {
+    throw new import_error.ErrorCtor("gradient palette must not be empty");
+  }
+  return (i) => palette[i % palette.length];
+}
+function ltrSweep(textLength, padding = 2) {
+  const cycle = textLength + 2 * padding;
+  return (frame) => (frame % cycle + cycle) % cycle - padding;
+}
+function noSweep() {
+  return () => -Infinity;
+}
+function randomSweep(textLength, padding = 2, random = Math.random) {
+  const cycle = textLength + 2 * padding;
+  let dir = random() < 0.5 ? "ltr" : "rtl";
+  let lastCycleIndex = 0;
+  return (frame) => {
+    const f = (frame % (cycle * 2 ** 30) + cycle * 2 ** 30) % (cycle * 2 ** 30);
+    const cycleIndex = (0, import_math.MathFloor)(f / cycle);
+    if (cycleIndex !== lastCycleIndex) {
+      dir = random() < 0.5 ? "ltr" : "rtl";
+      lastCycleIndex = cycleIndex;
+    }
+    const inCycle = f % cycle;
+    return dir === "ltr" ? inCycle - padding : textLength + padding - 1 - inCycle;
+  };
+}
+function resolvePalette(source, defaultColor) {
+  if (source === void 0) {
+    return solidColor(defaultColor);
+  }
+  if ((0, import_array.ArrayIsArray)(source[0])) {
+    return gradient(source);
+  }
+  return solidColor(source);
+}
+function rtlSweep(textLength, padding = 2) {
+  const cycle = textLength + 2 * padding;
+  return (frame) => textLength + padding - 1 - (frame % cycle + cycle) % cycle;
+}
+function smoothKernel(halfWidth = 2.5, falloff = 2.5) {
+  return (d, ctx) => {
+    const dist = (0, import_math.MathAbs)(d);
+    if (dist >= halfWidth) {
+      return ctx.baseColor;
+    }
+    const t = (1 - dist / halfWidth) ** falloff;
+    return blendRgb(ctx.baseColor, ctx.highlightColor, t);
+  };
+}
+function solidColor(color) {
+  return () => color;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_BASE_COLOR,

package/dist/env/boolean.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file `envAsBoolean` — coerce an env-var-shaped value into a boolean. Accepts
+ *   a back-compat positional `defaultValue` or an options bag (with `trim`).
+ *   Truthy vocabulary is `'1'` / `'true'` / `'yes'` case-insensitively after
+ *   optional trim.
+ */
+import type { EnvAsBooleanOptions } from './types';
+/**
+ * Convert an environment variable value to a boolean.
+ *
+ * Back-compat overload: passing a bare boolean as the second argument is
+ * equivalent to `{ defaultValue: B }`.
+ *
+ * @example
+ *   ;```typescript
+ *   import { envAsBoolean } from '@socketsecurity/lib/env/boolean'
+ *
+ *   envAsBoolean('true') // true
+ *   envAsBoolean('1') // true
+ *   envAsBoolean('yes') // true
+ *   envAsBoolean('  true  ') // true (trimmed)
+ *   envAsBoolean('  true  ', { trim: false }) // false (strict)
+ *   envAsBoolean(undefined) // false
+ *   envAsBoolean(undefined, true) // true (legacy positional default)
+ *   ```
+ *
+ * @param value - The value to convert.
+ * @param defaultValueOrOptions - Default (boolean) or options object.
+ *
+ * @returns `true` if value is '1', 'true', or 'yes' (case-insensitive), `false`
+ *   otherwise.
+ */
+export declare function envAsBoolean(value: unknown, defaultValueOrOptions?: boolean | EnvAsBooleanOptions | undefined): boolean;

package/dist/env/boolean.js

@@ -0,0 +1,46 @@
+"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 boolean_exports = {};
+__export(boolean_exports, {
+  envAsBoolean: () => envAsBoolean
+});
+module.exports = __toCommonJS(boolean_exports);
+// @__NO_SIDE_EFFECTS__
+function envAsBoolean(value, defaultValueOrOptions = false) {
+  const opts = typeof defaultValueOrOptions === "boolean" ? { defaultValue: defaultValueOrOptions } : defaultValueOrOptions ?? {};
+  const { defaultValue = false, trim = true } = opts;
+  if (typeof value === "string") {
+    const candidate = trim ? value.trim() : value;
+    if (!candidate) {
+      return !!defaultValue;
+    }
+    const lower = candidate.toLowerCase();
+    return lower === "1" || lower === "true" || lower === "yes";
+  }
+  if (value === null || value === void 0) {
+    return !!defaultValue;
+  }
+  return !!value;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  envAsBoolean
+});

package/dist/env/case-insensitive.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Case-insensitive environment-variable key lookup —
+ *   `findCaseInsensitiveEnvKey` walks `Object.keys(env)` with an O(1)
+ *   length-prefilter before the (expensive) `toUpperCase` comparison. Used by
+ *   `createEnvProxy` for Windows-style PATH/Path/path access.
+ */
+/**
+ * Find a case-insensitive environment variable key match. Searches for an
+ * environment variable key that matches the given uppercase name, using
+ * optimized fast-path checks to minimize expensive toUpperCase() calls.
+ *
+ * **Use Cases:**
+ *
+ * - Finding PATH when env object has "Path" or "path"
+ * - Cross-platform env var access where case may vary
+ * - Custom case-insensitive env lookups
+ *
+ * **Performance:**
+ *
+ * - Fast path: Checks length first (O(1)) before toUpperCase (expensive)
+ * - Only converts to uppercase when length matches
+ * - Early exit on first match
+ *
+ * @example
+ *   // Find PATH regardless of case
+ *   const envObj = { Path: 'C:\\Windows', NODE_ENV: 'test' }
+ *   const key = findCaseInsensitiveEnvKey(envObj, 'PATH')
+ *   console.log(key) // 'Path'
+ *   console.log(envObj[key]) // 'C:\\Windows'
+ *
+ * @example
+ *   // Not found returns undefined
+ *   const key = findCaseInsensitiveEnvKey({}, 'MISSING')
+ *   console.log(key) // undefined
+ *
+ * @param env - Environment object or env-like record to search.
+ * @param upperEnvVarName - Uppercase environment variable name to find (e.g.,
+ *   'PATH')
+ *
+ * @returns The actual key from env that matches (e.g., 'Path'), or undefined
+ */
+export declare function findCaseInsensitiveEnvKey(env: Record<string, string | undefined>, upperEnvVarName: string): string | undefined;

package/dist/env/case-insensitive.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 case_insensitive_exports = {};
+__export(case_insensitive_exports, {
+  findCaseInsensitiveEnvKey: () => findCaseInsensitiveEnvKey
+});
+module.exports = __toCommonJS(case_insensitive_exports);
+var import_object = require("../primordials/object");
+function findCaseInsensitiveEnvKey(env, upperEnvVarName) {
+  const targetLength = upperEnvVarName.length;
+  for (const key of (0, import_object.ObjectKeys)(env)) {
+    if (key.length !== targetLength) {
+      continue;
+    }
+    if (key.toUpperCase() === upperEnvVarName) {
+      return key;
+    }
+  }
+  return void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findCaseInsensitiveEnvKey
+});

package/dist/env/ci.d.ts

@@ -1,21 +1,20 @@
 /**
- * @fileoverview CI environment variable getter.
- * Exports `getCI()`, which returns whether the `CI` environment variable is
- * present (using the rewire helper so tests can override without touching
- * `process.env`).
+ * @file CI environment variable getter. Exports `getCI()`, which returns
+ *   whether the `CI` environment variable is present (using the rewire helper
+ *   so tests can override without touching `process.env`).
  */
 /**
  * Returns whether the CI environment variable is set.
  *
- * @returns `true` if running in a CI environment, `false` otherwise
- *
  * @example
- * ```typescript
- * import { getCI } from '@socketsecurity/lib/env/ci'
+ *   ;```typescript
+ *   import { getCI } from '@socketsecurity/lib/env/ci'
  *
- * if (getCI()) {
- *   console.log('Running in CI')
- * }
- * ```
+ *   if (getCI()) {
+ *     console.log('Running in CI')
+ *   }
+ *   ```
+ *
+ * @returns `true` if running in a CI environment, `false` otherwise
  */
 export declare function getCI(): boolean;

package/dist/env/debug.d.ts

@@ -1,19 +1,19 @@
 /**
- * @fileoverview DEBUG environment variable getter.
- * Exports `getDebug()`, which returns the raw `DEBUG` filter string used by
- * the `debug` package (or `undefined` when unset).
+ * @file DEBUG environment variable getter. Exports `getDebug()`, which returns
+ *   the raw `DEBUG` filter string used by the `debug` package (or `undefined`
+ *   when unset).
  */
 /**
  * Returns the value of the DEBUG environment variable.
  *
- * @returns The debug filter string, or `undefined` if not set
- *
  * @example
- * ```typescript
- * import { getDebug } from '@socketsecurity/lib/env/debug'
+ *   ;```typescript
+ *   import { getDebug } from '@socketsecurity/lib/env/debug'
  *
- * const debug = getDebug()
- * // e.g. 'socket:*' or undefined
- * ```
+ *   const debug = getDebug()
+ *   // e.g. 'socket:*' or undefined
+ *   ```
+ *
+ * @returns The debug filter string, or `undefined` if not set
  */
 export declare function getDebug(): string | undefined;

package/dist/env/github.d.ts

@@ -1,124 +1,121 @@
 /**
- * @fileoverview GitHub Actions environment variable getters.
- * Provides access to GitHub Actions CI/CD environment variables.
+ * @file GitHub Actions environment variable getters. Provides access to GitHub
+ *   Actions CI/CD environment variables.
  */
 /**
- * GH_TOKEN environment variable.
- * Alternative GitHub authentication token for API access (used by GitHub CLI).
- *
- * @returns The GH CLI token, or `undefined` if not set
+ * GH_TOKEN environment variable. Alternative GitHub authentication token for
+ * API access (used by GitHub CLI).
  *
  * @example
- * ```typescript
- * import { getGhToken } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGhToken } from '@socketsecurity/lib/env/github'
  *
- * const token = getGhToken()
- * // e.g. 'gho_abc123...' or undefined
- * ```
+ *   const token = getGhToken()
+ *   // e.g. 'gho_abc123...' or undefined
+ *   ```
+ *
+ * @returns The GH CLI token, or `undefined` if not set
  */
 export declare function getGhToken(): string | undefined;
 /**
- * GITHUB_API_URL environment variable.
- * GitHub API URL (e.g., https://api.github.com).
- *
- * @returns The GitHub API URL, or `undefined` if not set
+ * GITHUB_API_URL environment variable. GitHub API URL (e.g.,
+ * https://api.github.com).
  *
  * @example
- * ```typescript
- * import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
  *
- * const apiUrl = getGithubApiUrl()
- * // e.g. 'https://api.github.com' or undefined
- * ```
+ *   const apiUrl = getGithubApiUrl()
+ *   // e.g. 'https://api.github.com' or undefined
+ *   ```
+ *
+ * @returns The GitHub API URL, or `undefined` if not set
  */
 export declare function getGithubApiUrl(): string | undefined;
 /**
- * GITHUB_BASE_REF environment variable.
- * GitHub pull request base branch.
- *
- * @returns The pull request base branch name, or `undefined` if not set
+ * GITHUB_BASE_REF environment variable. GitHub pull request base branch.
  *
  * @example
- * ```typescript
- * import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
  *
- * const baseRef = getGithubBaseRef()
- * // e.g. 'main' or undefined
- * ```
+ *   const baseRef = getGithubBaseRef()
+ *   // e.g. 'main' or undefined
+ *   ```
+ *
+ * @returns The pull request base branch name, or `undefined` if not set
  */
 export declare function getGithubBaseRef(): string | undefined;
 /**
- * GITHUB_REF_NAME environment variable.
- * GitHub branch or tag name.
- *
- * @returns The branch or tag name, or `undefined` if not set
+ * GITHUB_REF_NAME environment variable. GitHub branch or tag name.
  *
  * @example
- * ```typescript
- * import { getGithubRefName } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubRefName } from '@socketsecurity/lib/env/github'
  *
- * const refName = getGithubRefName()
- * // e.g. 'feature/my-branch' or 'v1.0.0'
- * ```
+ *   const refName = getGithubRefName()
+ *   // e.g. 'feature/my-branch' or 'v1.0.0'
+ *   ```
+ *
+ * @returns The branch or tag name, or `undefined` if not set
  */
 export declare function getGithubRefName(): string | undefined;
 /**
- * GITHUB_REF_TYPE environment variable.
- * GitHub ref type (branch or tag).
- *
- * @returns The ref type ('branch' or 'tag'), or `undefined` if not set
+ * GITHUB_REF_TYPE environment variable. GitHub ref type (branch or tag).
  *
  * @example
- * ```typescript
- * import { getGithubRefType } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubRefType } from '@socketsecurity/lib/env/github'
  *
- * const refType = getGithubRefType()
- * // e.g. 'branch' or 'tag'
- * ```
+ *   const refType = getGithubRefType()
+ *   // e.g. 'branch' or 'tag'
+ *   ```
+ *
+ * @returns The ref type ('branch' or 'tag'), or `undefined` if not set
  */
 export declare function getGithubRefType(): string | undefined;
 /**
- * GITHUB_REPOSITORY environment variable.
- * GitHub repository name in owner/repo format.
- *
- * @returns The repository name, or `undefined` if not set
+ * GITHUB_REPOSITORY environment variable. GitHub repository name in owner/repo
+ * format.
  *
  * @example
- * ```typescript
- * import { getGithubRepository } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubRepository } from '@socketsecurity/lib/env/github'
  *
- * const repo = getGithubRepository()
- * // e.g. 'SocketDev/socket-cli' or undefined
- * ```
+ *   const repo = getGithubRepository()
+ *   // e.g. 'SocketDev/socket-cli' or undefined
+ *   ```
+ *
+ * @returns The repository name, or `undefined` if not set
  */
 export declare function getGithubRepository(): string | undefined;
 /**
- * GITHUB_SERVER_URL environment variable.
- * GitHub server URL (e.g., https://github.com).
- *
- * @returns The GitHub server URL, or `undefined` if not set
+ * GITHUB_SERVER_URL environment variable. GitHub server URL (e.g.,
+ * https://github.com).
  *
  * @example
- * ```typescript
- * import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
  *
- * const serverUrl = getGithubServerUrl()
- * // e.g. 'https://github.com' or undefined
- * ```
+ *   const serverUrl = getGithubServerUrl()
+ *   // e.g. 'https://github.com' or undefined
+ *   ```
+ *
+ * @returns The GitHub server URL, or `undefined` if not set
  */
 export declare function getGithubServerUrl(): string | undefined;
 /**
- * GITHUB_TOKEN environment variable.
- * GitHub authentication token for API access.
- *
- * @returns The GitHub token, or `undefined` if not set
+ * GITHUB_TOKEN environment variable. GitHub authentication token for API
+ * access.
  *
  * @example
- * ```typescript
- * import { getGithubToken } from '@socketsecurity/lib/env/github'
+ *   ;```typescript
+ *   import { getGithubToken } from '@socketsecurity/lib/env/github'
  *
- * const token = getGithubToken()
- * // e.g. 'ghp_abc123...' or undefined
- * ```
+ *   const token = getGithubToken()
+ *   // e.g. 'ghp_abc123...' or undefined
+ *   ```
+ *
+ * @returns The GitHub token, or `undefined` if not set
  */
 export declare function getGithubToken(): string | undefined;

package/dist/env/home.d.ts

@@ -1,28 +1,29 @@
 /**
- * @fileoverview HOME environment variable getter with Windows fallback.
- * Returns the user's home directory. On Windows, HOME is typically unset —
- * fall back to USERPROFILE before giving up, matching the resolution order
- * used by npm, git, and Node's os.homedir().
+ * @file HOME environment variable getter with Windows fallback. Returns the
+ *   user's home directory. On Windows, HOME is typically unset — fall back to
+ *   USERPROFILE before giving up, matching the resolution order used by npm,
+ *   git, and Node's os.homedir().
  */
 /**
  * Returns the user's home directory path.
  *
  * Resolution order:
- *   1. `$HOME` (POSIX, and sometimes set on Windows by shells like Git Bash)
- *   2. `$USERPROFILE` (Windows default, e.g. `C:\Users\alice`)
+ *
+ * 1. `$HOME` (POSIX, and sometimes set on Windows by shells like Git Bash)
+ * 2. `$USERPROFILE` (Windows default, e.g. `C:\Users\alice`)
  *
  * Returns `undefined` only when neither is set, which on modern systems is
  * exceedingly rare outside of sandboxed or minimal-env test harnesses.
  *
- * @returns The user's home directory path, or `undefined` if not resolvable
- *
  * @example
- * ```typescript
- * import { getHome } from '@socketsecurity/lib/env/home'
+ *   ;```typescript
+ *   import { getHome } from '@socketsecurity/lib/env/home'
  *
- * const home = getHome()
- * // POSIX: '/Users/alice'
- * // Windows: 'C:\\Users\\alice'
- * ```
+ *   const home = getHome()
+ *   // POSIX: '/Users/alice'
+ *   // Windows: 'C:\\Users\\alice'
+ *   ```
+ *
+ * @returns The user's home directory path, or `undefined` if not resolvable
  */
 export declare function getHome(): string | undefined;