@socketsecurity/lib 5.15.0 → 5.17.0

package/dist/env/ci.d.ts

@@ -1,2 +1,16 @@
+/**
+ * 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'
+ *
+ * if (getCI()) {
+ *   console.log('Running in CI')
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getCI(): boolean;

package/dist/env/debug.d.ts

@@ -1,2 +1,15 @@
+/**
+ * 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'
+ *
+ * const debug = getDebug()
+ * // e.g. 'socket:*' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getDebug(): string | undefined;

package/dist/env/github.d.ts

@@ -1,48 +1,128 @@
 /**
  * GITHUB_API_URL environment variable.
  * GitHub API URL (e.g., https://api.github.com).
+ *
+ * @returns The GitHub API URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const apiUrl = getGithubApiUrl()
+ * // e.g. 'https://api.github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
+ *
+ * const baseRef = getGithubBaseRef()
+ * // e.g. 'main' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefName } from '@socketsecurity/lib/env/github'
+ *
+ * const refName = getGithubRefName()
+ * // e.g. 'feature/my-branch' or 'v1.0.0'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefType } from '@socketsecurity/lib/env/github'
+ *
+ * const refType = getGithubRefType()
+ * // e.g. 'branch' or 'tag'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRepository } from '@socketsecurity/lib/env/github'
+ *
+ * const repo = getGithubRepository()
+ * // e.g. 'SocketDev/socket-cli' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const serverUrl = getGithubServerUrl()
+ * // e.g. 'https://github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 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
+ *
+ * @example
+ * ```typescript
+ * import { getGithubToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGithubToken()
+ * // e.g. 'ghp_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getGithubToken(): string | undefined;
 /**
  * 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
+ *
+ * @example
+ * ```typescript
+ * import { getGhToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGhToken()
+ * // e.g. 'gho_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getGhToken(): string | undefined;

package/dist/env/helpers.d.ts

@@ -1,9 +1,54 @@
 /**
  * @fileoverview Environment variable type conversion helpers.
  */
+/**
+ * Convert an environment variable string to a boolean.
+ *
+ * @param value - The environment variable value to convert
+ * @returns `true` if value is 'true', '1', or 'yes' (case-insensitive), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { envAsBoolean } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsBoolean('true')      // true
+ * envAsBoolean('1')         // true
+ * envAsBoolean('yes')       // true
+ * envAsBoolean(undefined)   // false
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function envAsBoolean(value: string | undefined): boolean;
+/**
+ * Convert an environment variable string to a number.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The parsed number, or `0` if the value is undefined or not a valid number
+ *
+ * @example
+ * ```typescript
+ * import { envAsNumber } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsNumber('3000')     // 3000
+ * envAsNumber(undefined)  // 0
+ * envAsNumber('abc')      // 0
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function envAsNumber(value: string | undefined): number;
+/**
+ * Convert an environment variable value to a string.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The string value, or an empty string if undefined
+ *
+ * @example
+ * ```typescript
+ * import { envAsString } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsString('hello')    // 'hello'
+ * envAsString(undefined)  // ''
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function envAsString(value: string | undefined): string;

package/dist/env/home.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the HOME environment variable.
+ *
+ * @returns The user's home directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getHome } from '@socketsecurity/lib/env/home'
+ *
+ * const home = getHome()
+ * // e.g. '/tmp/user' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getHome(): string | undefined;

package/dist/env/locale.d.ts

@@ -1,18 +1,48 @@
 /**
  * LANG environment variable.
  * System locale and language settings.
+ *
+ * @returns The system locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLang } from '@socketsecurity/lib/env/locale'
+ *
+ * const lang = getLang()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getLang(): string | undefined;
 /**
  * LC_ALL environment variable.
  * Override for all locale settings.
+ *
+ * @returns The locale override string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcAll } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcAll = getLcAll()
+ * // e.g. 'C' or 'en_US.UTF-8'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getLcAll(): string | undefined;
 /**
  * LC_MESSAGES environment variable.
  * Locale setting for message translations.
+ *
+ * @returns The messages locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcMessages } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcMessages = getLcMessages()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getLcMessages(): string | undefined;

package/dist/env/node-auth-token.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the NODE_AUTH_TOKEN environment variable.
+ *
+ * @returns The Node.js registry auth token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNodeAuthToken } from '@socketsecurity/lib/env/node-auth-token'
+ *
+ * const token = getNodeAuthToken()
+ * // e.g. 'npm_abc123...' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNodeAuthToken(): string | undefined;

package/dist/env/node-env.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the NODE_ENV environment variable.
+ *
+ * @returns The Node.js environment mode, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNodeEnv } from '@socketsecurity/lib/env/node-env'
+ *
+ * const env = getNodeEnv()
+ * // e.g. 'production', 'development', 'test', or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNodeEnv(): string | undefined;

package/dist/env/npm.d.ts

@@ -1,30 +1,80 @@
 /**
  * npm_config_registry environment variable.
  * NPM registry URL configured by package managers.
+ *
+ * @returns The configured NPM registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmConfigRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ * const registry = getNpmConfigRegistry()
+ * // e.g. 'https://registry.npmjs.org/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNpmConfigRegistry(): string | undefined;
 /**
  * npm_config_user_agent environment variable.
  * User agent string set by npm/pnpm/yarn package managers.
+ *
+ * @returns The package manager user agent string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmConfigUserAgent } from '@socketsecurity/lib/env/npm'
+ *
+ * const ua = getNpmConfigUserAgent()
+ * // e.g. 'pnpm/9.0.0 npm/? node/v20.0.0 darwin arm64'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNpmConfigUserAgent(): string | undefined;
 /**
  * npm_lifecycle_event environment variable.
  * The name of the npm lifecycle event that's currently running.
+ *
+ * @returns The current lifecycle event name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmLifecycleEvent } from '@socketsecurity/lib/env/npm'
+ *
+ * const event = getNpmLifecycleEvent()
+ * // e.g. 'install', 'postinstall', or 'test'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNpmLifecycleEvent(): string | undefined;
 /**
  * NPM_REGISTRY environment variable.
  * NPM registry URL override.
+ *
+ * @returns The NPM registry URL override, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ * const registry = getNpmRegistry()
+ * // e.g. 'https://registry.npmjs.org/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNpmRegistry(): string | undefined;
 /**
  * NPM_TOKEN environment variable.
  * Authentication token for NPM registry access.
+ *
+ * @returns The NPM auth token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmToken } from '@socketsecurity/lib/env/npm'
+ *
+ * const token = getNpmToken()
+ * // e.g. 'npm_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getNpmToken(): string | undefined;

package/dist/env/path.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the PATH environment variable.
+ *
+ * @returns The system executable search paths, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getPath } from '@socketsecurity/lib/env/path'
+ *
+ * const path = getPath()
+ * // e.g. '/usr/local/bin:/usr/bin:/bin' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getPath(): string | undefined;

package/dist/env/pre-commit.d.ts

@@ -1,2 +1,16 @@
+/**
+ * Returns whether the PRE_COMMIT environment variable is set to a truthy value.
+ *
+ * @returns `true` if running in a pre-commit hook, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getPreCommit } from '@socketsecurity/lib/env/pre-commit'
+ *
+ * if (getPreCommit()) {
+ *   console.log('Running in pre-commit hook')
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getPreCommit(): boolean;

package/dist/env/rewire.d.ts

@@ -1,5 +1,15 @@
 /**
  * Clear a specific environment variable override.
+ *
+ * @param key - The environment variable name to clear
+ *
+ * @example
+ * ```typescript
+ * import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
+ *
+ * setEnv('CI', '1')
+ * clearEnv('CI')
+ * ```
  */
 export declare function clearEnv(key: string): void;
 /**
@@ -11,10 +21,30 @@ export declare function clearEnv(key: string): void;
  * 3. process.env (including vi.stubEnv modifications)
  *
  * @internal Used by env getters to support test rewiring
+ *
+ * @example
+ * ```typescript
+ * import { getEnvValue } from '@socketsecurity/lib/env/rewire'
+ *
+ * const value = getEnvValue('NODE_ENV')
+ * // e.g. 'production' or undefined
+ * ```
  */
 export declare function getEnvValue(key: string): string | undefined;
 /**
  * Check if an environment variable has been overridden.
+ *
+ * @param key - The environment variable name to check
+ * @returns `true` if the variable has been overridden, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
+ *
+ * hasOverride('CI')  // false
+ * setEnv('CI', '1')
+ * hasOverride('CI')  // true
+ * ```
  */
 export declare function hasOverride(key: string): boolean;
 /**
@@ -26,6 +56,14 @@ export declare function hasOverride(key: string): boolean;
  * 3. process.env (including vi.stubEnv modifications)
  *
  * @internal Used by env getters to check for key presence (not value truthiness)
+ *
+ * @example
+ * ```typescript
+ * import { isInEnv } from '@socketsecurity/lib/env/rewire'
+ *
+ * isInEnv('PATH')     // true (usually set)
+ * isInEnv('MISSING')  // false
+ * ```
  */
 export declare function isInEnv(key: string): boolean;
 /**

package/dist/env/shell.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the SHELL environment variable.
+ *
+ * @returns The user's default shell path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getShell } from '@socketsecurity/lib/env/shell'
+ *
+ * const shell = getShell()
+ * // e.g. '/bin/zsh' or '/bin/bash'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getShell(): string | undefined;

package/dist/env/socket-cli-shadow.d.ts

@@ -2,6 +2,15 @@
  * Controls Socket CLI shadow mode risk acceptance.
  *
  * @returns Whether to accept all risks in shadow mode
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowAcceptRisks } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowAcceptRisks()) {
+ *   console.log('Shadow mode risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliShadowAcceptRisks(): boolean;
@@ -9,6 +18,14 @@ export declare function getSocketCliShadowAcceptRisks(): boolean;
  * API token for Socket CLI shadow mode.
  *
  * @returns Shadow mode API token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowApiToken } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * const token = getSocketCliShadowApiToken()
+ * // e.g. 'sk_shadow_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliShadowApiToken(): string | undefined;
@@ -16,6 +33,14 @@ export declare function getSocketCliShadowApiToken(): string | undefined;
  * Binary path for Socket CLI shadow mode.
  *
  * @returns Shadow mode binary path or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowBin } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * const bin = getSocketCliShadowBin()
+ * // e.g. '/usr/local/bin/socket-shadow' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliShadowBin(): string | undefined;
@@ -23,6 +48,15 @@ export declare function getSocketCliShadowBin(): string | undefined;
  * Controls Socket CLI shadow mode progress display.
  *
  * @returns Whether to show progress in shadow mode
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowProgress } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowProgress()) {
+ *   console.log('Shadow mode progress enabled')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliShadowProgress(): boolean;
@@ -30,6 +64,15 @@ export declare function getSocketCliShadowProgress(): boolean;
  * Controls Socket CLI shadow mode silent operation.
  *
  * @returns Whether shadow mode should operate silently
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowSilent } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowSilent()) {
+ *   console.log('Shadow mode is silent')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliShadowSilent(): boolean;