ultraenv 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,2562 @@
+export { InferSchema, SchemaBuilder, SchemaDefinition, defineEnv, t, tryDefineEnv, validate } from './schema/index.cjs';
+export { healthCheckRoute, ultraenvMiddleware } from './middleware/express.cjs';
+export { createUltraenvPlugin, ultraenvPlugin } from './middleware/fastify.cjs';
+
+declare enum EnvFileType {
+    /** .env — Default, shared across all environments */
+    Env = ".env",
+    /** .env.local — Local overrides, gitignored by default */
+    EnvLocal = ".env.local",
+    /** .env.development — Development-specific */
+    EnvDevelopment = ".env.development",
+    /** .env.development.local — Local development overrides */
+    EnvDevelopmentLocal = ".env.development.local",
+    /** .env.test — Test-specific */
+    EnvTest = ".env.test",
+    /** .env.test.local — Local test overrides */
+    EnvTestLocal = ".env.test.local",
+    /** .env.production — Production-specific */
+    EnvProduction = ".env.production",
+    /** .env.production.local — Local production overrides */
+    EnvProductionLocal = ".env.production.local",
+    /** .env.staging — Staging-specific */
+    EnvStaging = ".env.staging",
+    /** .env.staging.local — Local staging overrides */
+    EnvStagingLocal = ".env.staging.local",
+    /** .env.ci — CI/CD-specific */
+    EnvCI = ".env.ci"
+}
+type MergeStrategy = 'first-wins' | 'last-wins' | 'error-on-conflict';
+type OutputFormat$1 = 'terminal' | 'json' | 'silent';
+interface UltraenvConfig {
+    /** Directory to search for .env files (default: '.') */
+    envDir: string;
+    /** Which .env file variants to load (default: [EnvFileType.Env]) */
+    files: readonly EnvFileType[];
+    /** Character encoding for reading files (default: 'utf-8') */
+    encoding: BufferEncoding;
+    /** Whether to expand $VAR references (default: true) */
+    expandVariables: boolean;
+    /** Whether to overwrite existing process.env values (default: false) */
+    overrideProcessEnv: boolean;
+    /** Merge strategy when multiple files define the same key */
+    mergeStrategy: MergeStrategy;
+    /** Whether to prefix error messages with "ultraenv" */
+    prefixErrors: boolean;
+    /** Whether to silence all output (equivalent to OutputFormat.silent) */
+    silent: boolean;
+    /** Custom schema for validation */
+    schema?: EnvSchema;
+    /** Vault configuration */
+    vault?: VaultConfig;
+    /** Watch configuration */
+    watch?: WatchOptions;
+    /** Scan options for secret detection */
+    scan?: ScanOptions;
+    /** Output format */
+    outputFormat: OutputFormat$1;
+    /** Whether to log debug information */
+    debug: boolean;
+    /** Custom reporter for events */
+    reporter?: Reporter;
+    /** Maximum allowed value length in bytes (default: 1MB) */
+    maxValueLength: number;
+    /** Maximum variable interpolation depth (default: 10) */
+    maxInterpolationDepth: number;
+}
+interface LoadOptions {
+    /** Override the env directory */
+    envDir?: string;
+    /** Override the list of files to load */
+    files?: readonly EnvFileType[];
+    /** Override the encoding */
+    encoding?: BufferEncoding;
+    /** Whether to expand variables */
+    expandVariables?: boolean;
+    /** Whether to override process.env */
+    overrideProcessEnv?: boolean;
+    /** Merge strategy */
+    mergeStrategy?: MergeStrategy;
+    /** Schema for validation */
+    schema?: EnvSchema;
+    /** Whether to silence output */
+    silent?: boolean;
+    /** Maximum interpolation depth */
+    maxInterpolationDepth?: number;
+    /** Maximum value length */
+    maxValueLength?: number;
+    /** Process env to merge with (defaults to process.env) */
+    processEnv?: Record<string, string | undefined>;
+}
+interface ParsedEnvVar {
+    /** The variable name (key) */
+    key: string;
+    /** The resolved/interpolated value */
+    value: string;
+    /** The raw value as-is from the file (before interpolation) */
+    raw: string;
+    /** Which file this variable came from */
+    source: string;
+    /** 1-based line number in the source file */
+    lineNumber: number;
+    /** Any inline comment after the value */
+    comment: string;
+}
+interface ParsedEnvFile {
+    /** Absolute path to the .env file */
+    path: string;
+    /** All parsed variables from this file */
+    vars: readonly ParsedEnvVar[];
+    /** Whether the file exists on disk */
+    exists: boolean;
+}
+interface LoadResult {
+    /** The final merged env key-value pairs */
+    env: Record<string, string>;
+    /** Metadata about the load operation */
+    metadata: LoadMetadata;
+    /** All parsed files with their contents */
+    parsed: readonly ParsedEnvFile[];
+    /** Validation results, if a schema was provided */
+    validation?: ValidationResult;
+}
+interface LoadMetadata {
+    /** Total number of variables loaded */
+    totalVars: number;
+    /** Number of files successfully parsed */
+    filesParsed: number;
+    /** Number of files that existed */
+    filesFound: number;
+    /** Wall-clock time for the load operation in ms */
+    loadTimeMs: number;
+    /** Timestamp when the load was performed */
+    timestamp: string;
+    /** Environment directory used */
+    envDir: string;
+    /** Whether any overrides occurred (existing keys overwritten) */
+    hadOverrides: boolean;
+}
+type SchemaDefinition = Record<string, StringSchema | NumberSchema | BooleanSchema | EnumSchema<string[]> | ArraySchema | JsonSchema | DateSchema | BigIntSchema>;
+/** Base schema shape shared by all types */
+interface BaseSchema<T> {
+    /** Human-readable description for documentation */
+    description?: string;
+    /** If true, the variable is optional (defaults to false) */
+    optional?: boolean;
+    /** Default value when the variable is not set */
+    default?: T;
+    /** Transform function applied after parsing */
+    transform?: (value: T) => T;
+    /** Custom validation function — return a string for error message, or void/undefined for pass */
+    validate?: (value: T) => string | undefined;
+    /** Deprecation message, if set this variable is deprecated */
+    deprecated?: string;
+}
+interface StringSchema extends BaseSchema<string> {
+    type: 'string';
+    /** Minimum string length */
+    minLength?: number;
+    /** Maximum string length */
+    maxLength?: number;
+    /** Regex pattern the value must match */
+    pattern?: RegExp;
+    /** Predefined format shortcut (e.g., 'email', 'url', 'uuid') */
+    format?: 'email' | 'url' | 'uuid' | 'hostname' | 'ip' | 'ipv4' | 'ipv6';
+    /** Allowed values (enum shorthand) */
+    enum?: readonly string[];
+    /** Trim whitespace before validation */
+    trim?: boolean;
+}
+interface NumberSchema extends BaseSchema<number> {
+    type: 'number';
+    /** Minimum allowed value */
+    min?: number;
+    /** Maximum allowed value */
+    max?: number;
+    /** Value must be an integer */
+    integer?: boolean;
+    /** Value must be positive (> 0) */
+    positive?: boolean;
+    /** Value must be negative (< 0) */
+    negative?: boolean;
+    /** Value must be non-negative (>= 0) */
+    nonNegative?: boolean;
+    /** Value cannot be NaN or Infinity */
+    finite?: boolean;
+    /** Custom parsing function */
+    parse?: (raw: string) => number;
+}
+interface BooleanSchema extends BaseSchema<boolean> {
+    type: 'boolean';
+    /** Custom truthy values (default: ['true', '1', 'yes']) */
+    truthy?: readonly string[];
+    /** Custom falsy values (default: ['false', '0', 'no']) */
+    falsy?: readonly string[];
+}
+interface EnumSchema<T extends readonly string[]> extends BaseSchema<T[number]> {
+    type: 'enum';
+    /** Allowed values */
+    values: T;
+    /** Whether matching is case-insensitive (default: false) */
+    caseInsensitive?: boolean;
+}
+interface ArraySchema extends BaseSchema<readonly string[]> {
+    type: 'array';
+    /** Separator to split the value on (default: ',') */
+    separator?: string;
+    /** Trim each item after splitting */
+    trimItems?: boolean;
+    /** Remove empty strings from the result */
+    filterEmpty?: boolean;
+    /** Minimum number of items */
+    minItems?: number;
+    /** Maximum number of items */
+    maxItems?: number;
+    /** Unique items only */
+    unique?: boolean;
+    /** Schema to validate each item against */
+    itemSchema?: BaseSchema<string>;
+}
+interface JsonSchema<T = unknown> extends BaseSchema<T> {
+    type: 'json';
+    /** Custom reviver for JSON.parse */
+    reviver?: (key: string, value: unknown) => unknown;
+}
+interface DateSchema extends BaseSchema<Date> {
+    type: 'date';
+    /** Custom date format string or parsing function */
+    format?: string;
+    /** Custom parse function */
+    parse?: (raw: string) => Date;
+    /** Minimum date */
+    min?: Date;
+    /** Maximum date */
+    max?: Date;
+}
+interface BigIntSchema extends BaseSchema<bigint> {
+    type: 'bigint';
+    /** Radix for parsing (default: 10) */
+    radix?: number;
+    /** Custom parse function */
+    parse?: (raw: string) => bigint;
+    /** Minimum value */
+    min?: bigint;
+    /** Maximum value */
+    max?: bigint;
+}
+interface EnvSchema {
+    /** Schema definitions keyed by variable name */
+    definitions: SchemaDefinition;
+    /** Whether to strip unknown variables (default: false) */
+    strict?: boolean;
+    /** Whether to allow extra variables not in the schema (inverse of strict) */
+    allowExtra?: boolean;
+}
+interface ValidationResult {
+    /** Whether all validations passed */
+    valid: boolean;
+    /** All validation errors */
+    errors: readonly ValidationError$1[];
+    /** All validation warnings (non-blocking) */
+    warnings: readonly ValidationWarning[];
+    /** Variables that passed validation */
+    validated: Record<string, unknown>;
+    /** Unknown variables not in schema (when strict mode) */
+    unknown: readonly string[];
+}
+interface ValidationError$1 {
+    /** The variable name */
+    field: string;
+    /** The actual value that failed validation */
+    value: string;
+    /** Human-readable error message */
+    message: string;
+    /** Actionable hint for fixing the error */
+    hint: string;
+    /** The schema that was violated */
+    schema: BaseSchema<unknown>;
+    /** The expected type or constraint */
+    expected: string;
+    /** Source file, if applicable */
+    source?: string;
+    /** Line number, if applicable */
+    lineNumber?: number;
+}
+interface ValidationWarning {
+    /** The variable name */
+    field: string;
+    /** The value that triggered the warning */
+    value: string;
+    /** Warning message */
+    message: string;
+    /** Warning code for programmatic handling */
+    code: string;
+}
+interface VaultConfig {
+    /** Path to the vault file (default: '.env.vault') */
+    vaultFile: string;
+    /** Path to the keys file (default: '.env.keys') */
+    keysFile: string;
+    /** Current environment name (e.g., 'development', 'production') */
+    environment: string;
+    /** Master encryption key (if not using keys file) */
+    masterKey?: string;
+    /** Whether to auto-generate a key if none exists */
+    autoGenerateKey: boolean;
+}
+interface VaultEnvironment {
+    /** Environment name */
+    name: string;
+    /** Number of encrypted variables */
+    varCount: number;
+    /** ISO timestamp of last modification */
+    lastModified: string;
+    /** Which keys are available for this environment */
+    keyIds: readonly string[];
+}
+interface EncryptionResult {
+    /** Initialization vector */
+    iv: Buffer;
+    /** Authentication tag (for AEAD modes like AES-GCM) */
+    authTag: Buffer;
+    /** Encrypted ciphertext */
+    ciphertext: Buffer;
+    /** Algorithm used (e.g., 'aes-256-gcm') */
+    algorithm: string;
+}
+interface ScanOptions {
+    /** Files/patterns to include */
+    include: readonly string[];
+    /** Files/patterns to exclude */
+    exclude: readonly string[];
+    /** Whether to scan git history (more thorough but slower) */
+    scanGitHistory: boolean;
+    /** Maximum file size to scan in bytes (default: 1MB) */
+    maxFileSize: number;
+    /** Custom secret patterns to match */
+    customPatterns?: readonly SecretPattern[];
+    /** Whether to include default patterns */
+    includeDefaults: boolean;
+    /** Whether to stop on first match */
+    failFast: boolean;
+}
+interface ScanResult {
+    /** Whether any secrets were detected */
+    found: boolean;
+    /** All detected secrets */
+    secrets: readonly DetectedSecret[];
+    /** Files that were scanned */
+    filesScanned: readonly string[];
+    /** Files that were skipped (binary, too large, etc.) */
+    filesSkipped: readonly string[];
+    /** Wall-clock time for the scan in ms */
+    scanTimeMs: number;
+    /** Timestamp of the scan */
+    timestamp: string;
+}
+interface DetectedSecret {
+    /** The type of secret detected */
+    type: string;
+    /** The full matched string (masked) */
+    value: string;
+    /** The file where it was detected */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Column number (1-based) */
+    column: number;
+    /** The pattern that matched */
+    pattern: SecretPattern;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** The variable name, if the secret is in a .env file */
+    varName?: string;
+}
+interface SecretPattern {
+    /** Human-readable name (e.g., 'AWS Access Key') */
+    name: string;
+    /** Unique identifier */
+    id: string;
+    /** Regex pattern to match */
+    pattern: RegExp;
+    /** Confidence score (0-1) for this pattern */
+    confidence: number;
+    /** Description of what this pattern detects */
+    description: string;
+    /** Recommended remediation */
+    remediation: string;
+    /** Severity level: critical, high, or medium */
+    severity: 'critical' | 'high' | 'medium';
+    /** Category for grouping (e.g., 'aws', 'github', 'database') */
+    category: string;
+}
+interface SyncResult {
+    /** Whether the sync was successful */
+    success: boolean;
+    /** Differences detected */
+    diffs: readonly SyncDiff$1[];
+    /** Number of variables added */
+    added: number;
+    /** Number of variables removed */
+    removed: number;
+    /** Number of variables changed */
+    changed: number;
+    /** Number of variables unchanged */
+    unchanged: number;
+    /** Source environment name */
+    source: string;
+    /** Target environment name */
+    target: string;
+}
+interface SyncDiff$1 {
+    /** The variable name */
+    key: string;
+    /** Type of difference */
+    type: 'added' | 'removed' | 'changed';
+    /** Value in the source (masked) */
+    sourceValue: string;
+    /** Value in the target (masked) */
+    targetValue: string;
+}
+interface TypegenOptions {
+    /** Output file path for generated .d.ts */
+    outFile: string;
+    /** Interface name (default: 'UltraenvEnv') */
+    interfaceName: string;
+    /** Whether to export as default */
+    exportAsDefault: boolean;
+    /** Whether to make it a const assertion */
+    constAssertion: boolean;
+    /** Custom header comment */
+    header?: string;
+    /** Whether to generate JSDoc comments from schema descriptions */
+    jsdoc: boolean;
+    /** Indentation (spaces) */
+    indent: number;
+}
+interface WatchOptions {
+    /** Files/patterns to watch */
+    files: readonly string[];
+    /** Whether to watch recursively */
+    recursive: boolean;
+    /** Debounce interval in ms (default: 100) */
+    debounceMs: number;
+    /** Whether to trigger on initial load */
+    initial: boolean;
+    /** Polling interval in ms (0 = use native fs.watch) */
+    pollIntervalMs: number;
+    /** Ignore patterns */
+    ignore: readonly string[];
+}
+interface Watcher {
+    /** Start watching */
+    start(): void;
+    /** Stop watching */
+    stop(): void;
+    /** Whether the watcher is currently active */
+    readonly active: boolean;
+    /** Register a callback for file changes */
+    on(event: 'change' | 'error' | 'ready', callback: WatcherCallback): Watcher;
+    /** Remove a callback */
+    off(event: 'change' | 'error' | 'ready', callback: WatcherCallback): Watcher;
+}
+type WatcherCallback = (event: WatcherEvent) => void;
+interface WatcherEvent {
+    /** Type of file system event */
+    type: 'add' | 'change' | 'unlink' | 'rename';
+    /** The file path that triggered the event */
+    path: string;
+    /** Timestamp of the event */
+    timestamp: number;
+}
+interface Preset {
+    /** Unique preset identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what this preset configures */
+    description: string;
+    /** Schema definitions for this preset */
+    schema: SchemaDefinition;
+    /** Recommended .env file variants */
+    files: readonly EnvFileType[];
+    /** Recommended vault settings */
+    vault?: Partial<VaultConfig>;
+    /** Tags for categorization */
+    tags: readonly string[];
+}
+interface Reporter {
+    /** Report a successfully loaded variable */
+    varLoaded(key: string, source: string): void;
+    /** Report a validation error */
+    varError(error: ValidationError$1): void;
+    /** Report a validation warning */
+    varWarning(warning: ValidationWarning): void;
+    /** Report a file being loaded */
+    fileLoaded(path: string, varCount: number): void;
+    /** Report a file that was not found */
+    fileNotFound(path: string): void;
+    /** Report the beginning of a load operation */
+    loadStart(config: UltraenvConfig): void;
+    /** Report the end of a load operation */
+    loadEnd(result: LoadResult): void;
+    /** Report a secret detection */
+    secretDetected(secret: DetectedSecret): void;
+    /** Report a sync operation */
+    syncResult(result: SyncResult): void;
+    /** Report a watch event */
+    watchEvent(event: WatcherEvent): void;
+    /** Report debug information */
+    debug(message: string, metadata?: Record<string, unknown>): void;
+}
+
+/**
+ * Load environment variables from .env files (synchronous).
+ *
+ * This function:
+ * 1. Resolves the file cascade based on environment
+ * 2. Reads and parses each .env file
+ * 3. Merges according to merge strategy
+ * 4. Expands variable references (if enabled)
+ * 5. Optionally sets process.env values
+ *
+ * @param options - Load configuration options
+ * @returns Merged env key-value pairs
+ */
+declare function load(options?: LoadOptions): Record<string, string>;
+/**
+ * Synchronous version of load (alias for clarity).
+ * Identical behavior — uses synchronous file I/O.
+ *
+ * @param options - Load configuration options
+ * @returns Merged env key-value pairs
+ */
+declare function loadSync(options?: LoadOptions): Record<string, string>;
+/**
+ * Full load with complete LoadResult (sync).
+ *
+ * @param options - Load configuration options
+ * @returns Complete LoadResult with env, metadata, and parsed files
+ */
+declare function loadWithResult(options?: LoadOptions): LoadResult;
+/**
+ * Full load with complete LoadResult (sync, explicit alias).
+ */
+declare function loadWithResultSync(options?: LoadOptions): LoadResult;
+
+/**
+ * Search for an ultraenv configuration file starting from `cwd`
+ * and walking up the directory tree.
+ *
+ * Searches for (in order):
+ * - .ultraenvrc.json
+ * - .ultraenvrc.yaml
+ * - .ultraenvrc.yml
+ * - ultraenv.config.js
+ * - ultraenv.config.cjs
+ * - "ultraenv" key in package.json
+ *
+ * @param cwd - Starting directory (default: process.cwd())
+ * @returns Absolute path to the config file, or null if none found
+ */
+declare function findConfig(cwd?: string): string | null;
+/**
+ * Load and validate ultraenv configuration from a file.
+ *
+ * @param configPath - Explicit path to a config file. If not provided,
+ *                     auto-discovers using findConfig().
+ * @returns The fully resolved and validated UltraenvConfig
+ * @throws ConfigError if the config file is invalid or cannot be read
+ */
+declare function loadConfig(configPath?: string): UltraenvConfig;
+
+interface CascadeOptions {
+    /** Directory to search for .env files (default: process.cwd()) */
+    envDir?: string;
+    /** Override the detected environment name */
+    environment?: string;
+    /** Specific file paths to load (takes priority over auto-detection) */
+    paths?: readonly string[];
+    /** Glob patterns for file matching */
+    patterns?: readonly string[];
+    /** Specific EnvFileType enum values to load */
+    files?: readonly EnvFileType[];
+    /** Merge strategy when multiple files define the same key */
+    mergeStrategy?: MergeStrategy;
+    /** Whether to include system env vars in the cascade (highest priority) */
+    includeSystemEnv?: boolean;
+    /** Custom system env snapshot (defaults to process.env) */
+    systemEnv?: Record<string, string | undefined>;
+}
+interface CascadeFileEntry {
+    /** Absolute path to the .env file */
+    absolutePath: string;
+    /** The file type (if recognized) */
+    fileType: EnvFileType | null;
+    /** Priority rank (higher = overrides lower) */
+    priority: number;
+    /** Whether the file exists on disk */
+    exists: boolean;
+}
+interface ResolvedCascadeResult {
+    /** Ordered list of file entries (lowest priority first) */
+    files: readonly CascadeFileEntry[];
+    /** The detected or specified environment name */
+    environment: string;
+    /** The merge strategy used */
+    mergeStrategy: MergeStrategy;
+    /** Whether system env vars are included */
+    includeSystemEnv: boolean;
+    /** The resolved env directory (absolute path) */
+    envDir: string;
+    /** Files that were found to exist */
+    existingFiles: readonly CascadeFileEntry[];
+    /** Source tracking: which file each key came from */
+    sources: Record<string, string>;
+}
+/**
+ * Resolve the file cascade based on the given options.
+ *
+ * This function determines which .env files to load and in what order.
+ * It supports:
+ * - Standard cascade: .env → .env.local → .env.{ENV} → .env.{ENV}.local
+ * - Custom file paths
+ * - Custom EnvFileType arrays
+ * - .env.local is skipped in test environment
+ *
+ * @param options - Cascade resolution options
+ * @returns ResolvedCascadeResult with ordered file list and metadata
+ * @throws ConfigError if options are invalid
+ */
+declare function resolveCascade(options?: CascadeOptions): ResolvedCascadeResult;
+/**
+ * Merge parsed env files according to the cascade result and merge strategy.
+ *
+ * @param parsedFiles - Array of successfully parsed env files (in priority order)
+ * @param cascade - The resolved cascade result
+ * @returns Merged key-value pairs with source tracking
+ * @throws ConfigError on conflict when using 'error-on-conflict' strategy
+ */
+declare function mergeCascade(parsedFiles: readonly ParsedEnvFile[], cascade: ResolvedCascadeResult): Record<string, string>;
+
+/**
+ * Create a new EnvFileWatcher instance.
+ *
+ * @param options - Optional watch and cascade configuration
+ * @returns A new Watcher instance
+ */
+declare function createWatcher(options?: {
+    watchOptions?: WatchOptions;
+    cascadeOptions?: CascadeOptions;
+}): Watcher;
+
+/**
+ * Encrypt an entire environment variable set using AES-256-GCM.
+ *
+ * The data is serialized to a deterministic string format (sorted keys,
+ * KEY=VALUE per line), then encrypted. The result includes the IV, auth tag,
+ * ciphertext, and algorithm identifier for later decryption.
+ *
+ * @param data - Object of environment variable key-value pairs.
+ * @param key - 32-byte encryption key.
+ * @returns EncryptionResult containing IV, auth tag, ciphertext, and algorithm.
+ * @throws EncryptionError if encryption fails.
+ *
+ * @example
+ * const result = encryptEnvironment(
+ *   { DATABASE_URL: 'postgres://localhost/mydb', API_KEY: 'sk-123' },
+ *   masterKey,
+ * );
+ */
+declare function encryptEnvironment(data: Record<string, string>, key: Buffer): EncryptionResult;
+/**
+ * Decrypt environment data that was encrypted with encryptEnvironment.
+ *
+ * @param encrypted - The EncryptionResult from a previous encryptEnvironment call.
+ * @param key - The 32-byte encryption key (must match the encryption key).
+ * @returns The original serialized environment data string.
+ * @throws EncryptionError if decryption fails, the key is wrong, or data was tampered with.
+ *
+ * @example
+ * const serialized = decryptEnvironment(encryptedResult, masterKey);
+ * // serialized = "API_KEY=sk-123\nDATABASE_URL=postgres://localhost/mydb"
+ */
+declare function decryptEnvironment(encrypted: EncryptionResult, key: Buffer): string;
+/**
+ * Encrypt a single value using AES-256-GCM and return it as a self-contained
+ * encoded string that includes the algorithm version, IV, auth tag, and ciphertext.
+ *
+ * Output format: `encrypted:v1:aes-256-gcm:{iv_base64}:{authTag_base64}:{ciphertext_base64}`
+ *
+ * This format is safe to store in .env files and .env.vault files.
+ * The IV and auth tag are generated fresh for each encryption.
+ *
+ * @param value - The plaintext string to encrypt.
+ * @param key - 32-byte encryption key.
+ * @returns The encrypted value in the standard ultraenv format.
+ * @throws EncryptionError if encryption fails.
+ *
+ * @example
+ * const encrypted = encryptValue('my-secret-password', masterKey);
+ * // encrypted = "encrypted:v1:aes-256-gcm:aBcDeF...:XyZ123...:QrStUv..."
+ */
+declare function encryptValue(value: string, key: Buffer): string;
+/**
+ * Decrypt a single value that was encrypted with encryptValue.
+ *
+ * Parses the self-contained encrypted format:
+ * `encrypted:v1:aes-256-gcm:{iv_base64}:{authTag_base64}:{ciphertext_base64}`
+ *
+ * @param encrypted - The encrypted string in ultraenv format.
+ * @param key - 32-byte encryption key (must match the encryption key).
+ * @returns The original plaintext string.
+ * @throws EncryptionError if the format is invalid, decryption fails, or the key is wrong.
+ *
+ * @example
+ * const plaintext = decryptValue(
+ *   'encrypted:v1:aes-256-gcm:aBcDeF...:XyZ123...:QrStUv...',
+ *   masterKey,
+ * );
+ * // plaintext = 'my-secret-password'
+ */
+declare function decryptValue(encrypted: string, key: Buffer): string;
+/**
+ * Check if a string is an ultraenv-encrypted value.
+ *
+ * @param value - The string to check.
+ * @returns true if the value matches the encrypted format prefix.
+ */
+declare function isEncryptedValue(value: string): boolean;
+
+/**
+ * Generate a cryptographically secure 32-byte master key for AES-256 encryption.
+ *
+ * Uses node:crypto.randomBytes for cryptographically secure pseudo-random
+ * number generation (CSPRNG).
+ *
+ * @returns A 32-byte Buffer containing the master key.
+ *
+ * @example
+ * const masterKey = generateMasterKey();
+ * // masterKey is a 32-byte Buffer — keep it secret!
+ */
+declare function generateMasterKey(): Buffer;
+/**
+ * Derive a per-environment encryption key from a master key using HKDF-SHA256.
+ *
+ * Each environment (development, staging, production, etc.) gets a unique key
+ * derived from the same master key. This means:
+ * - Compromising one environment's key does NOT compromise others.
+ * - Rotating an environment key only requires re-encrypting that environment.
+ * - The master key alone can derive all environment keys.
+ *
+ * Uses a fixed salt ("ultraenv") for deterministic derivation — the same
+ * master key + environment name always produces the same environment key.
+ *
+ * @param masterKey - The 32-byte master key.
+ * @param environment - The environment name (e.g., 'development', 'production').
+ * @returns A 32-byte derived key for the specified environment.
+ * @throws EncryptionError if the master key is invalid or derivation fails.
+ *
+ * @example
+ * const devKey = deriveEnvironmentKey(masterKey, 'development');
+ * const prodKey = deriveEnvironmentKey(masterKey, 'production');
+ * // devKey !== prodKey — each environment has a unique key
+ */
+declare function deriveEnvironmentKey(masterKey: Buffer, environment: string): Buffer;
+/**
+ * Format a raw key Buffer into a human-readable string with a version prefix.
+ *
+ * Output format: `ultraenv_key_v1_{base64}`
+ *
+ * This format allows:
+ * - Easy identification of ultraenv keys
+ * - Future algorithm migration (v2, v3, etc.)
+ * - Safe storage in .env.keys files
+ *
+ * @param key - The raw key Buffer.
+ * @returns The formatted key string.
+ * @throws EncryptionError if the key is too short to encode.
+ *
+ * @example
+ * const formatted = formatKey(masterKey);
+ * // formatted = "ultraenv_key_v1_aBcDeF123456..."
+ */
+declare function formatKey(key: Buffer): string;
+/**
+ * Parse a formatted key string back into a raw Buffer.
+ *
+ * Expects format: `ultraenv_key_v1_{base64}`
+ *
+ * @param formatted - The formatted key string.
+ * @returns The raw key Buffer.
+ * @throws EncryptionError if the format is invalid or base64 decoding fails.
+ *
+ * @example
+ * const key = parseKey('ultraenv_key_v1_aBcDeF123456...');
+ * // key is a 32-byte Buffer
+ */
+declare function parseKey(formatted: string): Buffer;
+/**
+ * Check if a string matches the ultraenv key format.
+ *
+ * Validates the prefix is correct and that the base64 portion is non-empty
+ * and decodable to at least 16 bytes.
+ *
+ * @param formatted - The string to check.
+ * @returns true if the string appears to be a valid ultraenv key.
+ *
+ * @example
+ * isValidKeyFormat('ultraenv_key_v1_aBcDeF123=') // true
+ * isValidKeyFormat('not-a-key')                   // false
+ * isValidKeyFormat('ultraenv_key_v1_')            // false
+ */
+declare function isValidKeyFormat(formatted: string): boolean;
+/**
+ * Mask a formatted key for safe display in logs or terminal output.
+ *
+ * Shows only the first 8 and last 4 characters, replacing everything
+ * in between with asterisks.
+ *
+ * @param formatted - The formatted key string.
+ * @returns The masked key string.
+ *
+ * @example
+ * maskKey('ultraenv_key_v1_aBcDeFgHiJkLmNoPqRsTuVwXyZ==')
+ * // → "ultraenv********XyZ=="
+ */
+declare function maskKey(formatted: string): string;
+/**
+ * Generate the content for a .env.keys file.
+ *
+ * The keys file stores environment-specific keys in a format that is safe
+ * to distribute through secure channels (NOT committed to git).
+ *
+ * Output format:
+ * ```
+ * # ultraenv encryption keys — DO NOT COMMIT
+ * # Generated: {ISO timestamp}
+ *
+ * ULTRAENV_KEY_DEVELOPMENT="ultraenv_key_v1_..."
+ * ULTRAENV_KEY_STAGING="ultraenv_key_v1_..."
+ * ULTRAENV_KEY_PRODUCTION="ultraenv_key_v1_..."
+ * ```
+ *
+ * @param environments - Array of environment names.
+ * @returns The complete .env.keys file content as a string.
+ *
+ * @example
+ * const masterKey = generateMasterKey();
+ * const keysFile = generateKeysFile(['development', 'staging', 'production'], masterKey);
+ */
+declare function generateKeysFile(environments: string[]): string;
+/**
+ * Parse a .env.keys file and extract environment-to-key mappings.
+ *
+ * Expects lines in the format: `ULTRAENV_KEY_{ENV}="ultraenv_key_v1_..."`
+ *
+ * @param content - The raw content of the .env.keys file.
+ * @returns A Map of environment name → formatted key string.
+ * @throws EncryptionError if the file format is invalid.
+ *
+ * @example
+ * const keys = parseKeysFile(fileContent);
+ * // keys.get('development') → 'ultraenv_key_v1_...'
+ */
+declare function parseKeysFile(content: string): Map<string, string>;
+/**
+ * Rotate encryption for data by decrypting with the old key and re-encrypting
+ * with the new key.
+ *
+ * This is used when you want to change the encryption key for an environment
+ * without losing the data. The process is:
+ * 1. Decrypt the data using the old key
+ * 2. Encrypt the same data using the new key
+ *
+ * @param oldKey - The current 32-byte encryption key.
+ * @param newData - The plaintext data (or previously encrypted data string).
+ * @param newKey - The new 32-byte encryption key.
+ * @returns The data encrypted with the new key (same format as encryptValue).
+ * @throws EncryptionError if either key is invalid or operations fail.
+ *
+ * @example
+ * const newEncrypted = rotateKey(oldEnvironmentKey, 'my-secret', newEnvironmentKey);
+ */
+declare function rotateKey(oldKey: Buffer, newData: string, newKey: Buffer): string;
+
+/**
+ * Internal vault entry that pairs the encrypted payload with environment metadata.
+ * Extends the public VaultEnvironment type with the encrypted data needed for
+ * serialization.
+ */
+interface VaultEntry extends VaultEnvironment {
+    /** The full encrypted payload string for this environment */
+    encrypted: string;
+}
+/**
+ * Parse the content of a .env.vault file into a Map of environment entries.
+ *
+ * Expected format:
+ * ```
+ * # ultraenv encrypted vault — safe to commit
+ * # Generated: {ISO timestamp}
+ * # Environments: development, staging, production
+ *
+ * ULTRAENV_VAULT_DEVELOPMENT="encrypted:v1:aes-256-gcm:..."
+ * ULTRAENV_VAULT_STAGING="encrypted:v1:aes-256-gcm:..."
+ * ```
+ *
+ * Comments (lines starting with #) and blank lines are ignored.
+ * Environment names are normalized to lowercase.
+ *
+ * @param content - The raw file content.
+ * @returns A Map of environment name (lowercase) → VaultEntry.
+ * @throws VaultError if the file format is invalid.
+ *
+ * @example
+ * const vault = parseVaultFile(fileContent);
+ * const devEntry = vault.get('development');
+ * // devEntry?.encrypted = "encrypted:v1:aes-256-gcm:..."
+ * // devEntry?.varCount = 5
+ */
+declare function parseVaultFile(content: string): Map<string, VaultEntry>;
+/**
+ * Serialize a Map of vault entries into the .env.vault file format.
+ *
+ * Output format:
+ * ```
+ * # ultraenv encrypted vault — safe to commit
+ * # Generated: {ISO timestamp}
+ * # Environments: development, staging, production
+ *
+ * ULTRAENV_VAULT_DEVELOPMENT="encrypted:v1:aes-256-gcm:..."
+ * ULTRAENV_VAULT_STAGING="encrypted:v1:aes-256-gcm:..."
+ * ```
+ *
+ * @param environments - A Map of environment name → VaultEntry.
+ * @returns The complete vault file content as a string.
+ *
+ * @example
+ * const content = serializeVaultFile(vaultMap);
+ */
+declare function serializeVaultFile(environments: Map<string, VaultEntry>): string;
+/**
+ * Read a .env.vault file from disk and parse it into a Map of entries.
+ *
+ * @param path - Absolute or relative path to the vault file.
+ * @returns A Map of environment name → VaultEntry.
+ * @throws VaultError if the file cannot be read or has an invalid format.
+ *
+ * @example
+ * const vault = await readVaultFile('.env.vault');
+ */
+declare function readVaultFile(path: string): Promise<Map<string, VaultEntry>>;
+/**
+ * Write vault entries to a .env.vault file on disk.
+ *
+ * Creates parent directories if needed. The file is overwritten atomically
+ * (written in full, not appended).
+ *
+ * @param path - Absolute or relative path to the vault file.
+ * @param environments - A Map of environment name → VaultEntry to write.
+ * @throws VaultError if the file cannot be written.
+ *
+ * @example
+ * await writeVaultFile('.env.vault', vaultMap);
+ */
+declare function writeVaultFile(path: string, environments: Map<string, VaultEntry>): Promise<void>;
+/**
+ * Get the vault entry for a specific environment from a parsed vault.
+ *
+ * @param vault - The parsed vault Map.
+ * @param env - The environment name (case-insensitive).
+ * @returns The VaultEntry if found, undefined otherwise.
+ *
+ * @example
+ * const entry = getEnvironmentData(vault, 'production');
+ * if (entry) {
+ *   console.log(`Found ${entry.varCount} encrypted variables`);
+ * }
+ */
+declare function getEnvironmentData(vault: Map<string, VaultEntry>, env: string): VaultEntry | undefined;
+/**
+ * Get a list of all environment names stored in the vault.
+ *
+ * @param vault - The parsed vault Map.
+ * @returns Array of environment names sorted alphabetically.
+ */
+declare function getVaultEnvironments(vault: Map<string, VaultEntry>): string[];
+
+/**
+ * Compute an HMAC-SHA256 integrity hash for data using the given key.
+ *
+ * The integrity hash authenticates that the data has not been modified
+ * since it was created. It is NOT a confidentiality mechanism — the data
+ * itself is not encrypted by this function.
+ *
+ * @param data - The string data to authenticate.
+ * @param key - The HMAC key (can be the encryption key or a separate integrity key).
+ * @returns The HMAC-SHA256 digest as a lowercase hex string (64 characters).
+ * @throws EncryptionError if the key or data is empty.
+ *
+ * @example
+ * const digest = computeIntegrity(serializedEnvData, encryptionKey);
+ * // digest = "a1b2c3d4e5f6...64 chars..."
+ */
+declare function computeIntegrity(data: string, key: Buffer): string;
+/**
+ * Verify the HMAC-SHA256 integrity of data using constant-time comparison.
+ *
+ * This function is resistant to timing attacks because it uses
+ * `crypto.timingSafeEqual` internally. Even if the data or expected digest
+ * differ, the function takes the same amount of time to complete.
+ *
+ * @param data - The string data to verify.
+ * @param key - The HMAC key (must match the key used to compute the digest).
+ * @param expected - The expected HMAC-SHA256 hex digest.
+ * @returns true if the computed digest matches the expected digest.
+ * @throws EncryptionError if the inputs are invalid.
+ *
+ * @example
+ * const isValid = verifyIntegrity(data, key, storedDigest);
+ * if (!isValid) {
+ *   throw new Error('Data has been tampered with!');
+ * }
+ */
+declare function verifyIntegrity(data: string, key: Buffer, expected: string): boolean;
+/**
+ * Compute a checksum over all environments in the vault.
+ *
+ * The checksum is computed by:
+ * 1. Sorting environment names alphabetically
+ * 2. Concatenating all encrypted payloads with their environment names
+ * 3. Computing HMAC-SHA256 over the combined data
+ *
+ * This provides a single integrity check for the entire vault file.
+ * If ANY environment's data changes, the vault checksum will change.
+ *
+ * @param environments - A Map of environment name → VaultEnvironment.
+ *   Each VaultEnvironment's `name` and `keyIds` are used to construct
+ *   the checksum input. The encrypted data is typically stored in a
+ *   VaultEntry (extends VaultEnvironment) — if the `encrypted` property
+ *   exists, it will be included.
+ * @param key - The HMAC key for computing the checksum.
+ * @returns The vault checksum as a lowercase hex string.
+ * @throws EncryptionError if the inputs are invalid.
+ *
+ * @example
+ * const checksum = computeVaultChecksum(vaultEntries, integrityKey);
+ */
+declare function computeVaultChecksum(environments: Map<string, VaultEnvironment>, key: Buffer): string;
+/**
+ * Verify the integrity of the entire vault against an expected checksum.
+ *
+ * @param environments - A Map of environment name → VaultEnvironment.
+ * @param key - The HMAC key used to compute the original checksum.
+ * @param expected - The expected vault checksum (64-char hex string).
+ * @returns true if the computed checksum matches the expected checksum.
+ * @throws EncryptionError if the inputs are invalid.
+ *
+ * @example
+ * const isValid = verifyVaultChecksum(vaultEntries, integrityKey, storedChecksum);
+ */
+declare function verifyVaultChecksum(environments: Map<string, VaultEnvironment>, key: Buffer, expected: string): boolean;
+
+/**
+ * A secure buffer wrapper that automatically zeroes its contents on garbage
+ * collection and provides safe access methods.
+ *
+ * Unlike a regular Buffer, SecureBuffer:
+ * - Zeros its contents when garbage collected (via FinalizationRegistry)
+ * - Does not expose the raw buffer to JSON.stringify or console.log
+ * - Provides explicit zero() and fill() methods for manual cleanup
+ *
+ * **Important**: While SecureBuffer reduces the risk of sensitive data
+ * remaining in memory, it cannot provide absolute guarantees. Node.js V8
+ * engine may create copies of the data during garbage collection or
+ * serialization. Use defense-in-depth practices.
+ *
+ * @example
+ * const buf = new SecureBuffer(32);
+ * buf.fill(0); // Fill with zeros
+ * // ... use buf ...
+ * buf.zero(); // Explicitly zero when done
+ * // buf will also be zeroed automatically when garbage collected
+ */
+declare class SecureBuffer {
+    private _buffer;
+    private _length;
+    private _zeroed;
+    /** Track all live SecureBuffers for FinalizationRegistry cleanup */
+    private static readonly registry;
+    /** Counter for generating unique token identifiers */
+    private static _instanceCount;
+    /**
+     * Create a new SecureBuffer.
+     *
+     * @param size - The size of the buffer in bytes.
+     * @throws RangeError if size is not a positive integer.
+     */
+    constructor(size: number);
+    /**
+     * Create a SecureBuffer from an existing Buffer.
+     * The source buffer is NOT modified — a copy is made.
+     *
+     * @param source - The source buffer to copy.
+     * @returns A new SecureBuffer containing a copy of the source data.
+     */
+    static from(source: Buffer | Uint8Array): SecureBuffer;
+    /**
+     * Create a SecureBuffer from a string.
+     *
+     * @param str - The string to encode.
+     * @param encoding - The character encoding (default: 'utf-8').
+     * @returns A new SecureBuffer containing the encoded string.
+     */
+    static fromString(str: string, encoding?: BufferEncoding): SecureBuffer;
+    /**
+     * The size of the buffer in bytes.
+     */
+    get length(): number;
+    /**
+     * Whether the buffer has been zeroed.
+     */
+    get isZeroed(): boolean;
+    /**
+     * Fill the buffer with the specified byte value.
+     *
+     * @param value - The byte value to fill with (0-255).
+     * @returns This SecureBuffer for chaining.
+     */
+    fill(value: number): SecureBuffer;
+    /**
+     * Fill the buffer with random bytes.
+     *
+     * @returns This SecureBuffer for chaining.
+     */
+    fillRandom(): SecureBuffer;
+    /**
+     * Zero out all bytes in the buffer.
+     *
+     * This should be called as soon as the sensitive data is no longer needed.
+     * The buffer will also be zeroed automatically on garbage collection, but
+     * explicit zeroing provides faster cleanup for time-sensitive operations.
+     *
+     * @returns This SecureBuffer for chaining.
+     */
+    zero(): SecureBuffer;
+    /**
+     * Get a read-only copy of the underlying buffer.
+     *
+     * **Warning**: This returns a COPY of the buffer contents.
+     * The caller is responsible for zeroing the returned buffer when done.
+     * Use toString() when possible to avoid managing raw buffers.
+     *
+     * @returns A copy of the buffer contents.
+     */
+    getBuffer(): Buffer;
+    /**
+     * Get a single byte at the specified index.
+     *
+     * @param index - The byte index.
+     * @returns The byte value (0-255).
+     */
+    getByte(index: number): number;
+    /**
+     * Convert the buffer contents to a string.
+     *
+     * @param encoding - The character encoding (default: 'utf-8').
+     * @returns The decoded string.
+     */
+    toString(encoding?: BufferEncoding): string;
+    /**
+     * Convert to hex string.
+     *
+     * @returns Lowercase hex string.
+     */
+    toHex(): string;
+    /**
+     * Convert to base64 string.
+     *
+     * @returns Base64-encoded string.
+     */
+    toBase64(): string;
+    /**
+     * JSON serialization — never exposes the buffer contents.
+     * Returns a placeholder string to prevent accidental logging of secrets.
+     *
+     * @returns A safe placeholder string.
+     */
+    toJSON(): string;
+    /**
+     * Manual cleanup — call when the SecureBuffer is no longer needed.
+     * Zeros the buffer and unregisters from the FinalizationRegistry.
+     *
+     * After calling dispose(), the buffer cannot be used.
+     */
+    dispose(): void;
+}
+/**
+ * A secure string that stores its backing data in a SecureBuffer.
+ * Provides string-like methods while ensuring the underlying data
+ * can be securely zeroed.
+ *
+ * @example
+ * const secret = createSecureString('my-api-key-12345');
+ * console.log(secret.value); // 'my-api-key-12345'
+ * secret.dispose(); // Zeros the backing buffer
+ * console.log(secret.value); // ''
+ */
+declare class SecureString {
+    private _buffer;
+    private _disposed;
+    /**
+     * Create a new SecureString.
+     *
+     * **Internal**: Use the `createSecureString()` factory function instead
+     * of calling this constructor directly.
+     *
+     * @param buffer - The SecureBuffer backing this string.
+     * @internal
+     */
+    constructor(buffer: SecureBuffer);
+    /**
+     * The string value.
+     * Returns empty string if the backing buffer has been zeroed/disposed.
+     */
+    get value(): string;
+    /**
+     * The length of the string in characters.
+     */
+    get length(): number;
+    /**
+     * Whether this SecureString has been disposed.
+     */
+    get disposed(): boolean;
+    /**
+     * Zero the backing buffer and mark as disposed.
+     * After calling dispose(), value will always return ''.
+     */
+    dispose(): void;
+    /**
+     * JSON serialization — never exposes the string contents.
+     */
+    toJSON(): string;
+}
+/**
+ * Create a SecureString from a plain string.
+ *
+ * The plain string's data is copied into a SecureBuffer. Note that the
+ * original string may still exist in V8's string table until GC runs.
+ *
+ * @param value - The string value to wrap securely.
+ * @returns A SecureString instance.
+ *
+ * @example
+ * const apiKey = createSecureString('sk-abc123def456');
+ * console.log(apiKey.value); // 'sk-abc123def456'
+ * apiKey.dispose();
+ */
+declare function createSecureString(value: string): SecureString;
+/**
+ * Create a SecureString from a Buffer.
+ *
+ * @param buffer - The buffer containing the string data.
+ * @param encoding - The character encoding (default: 'utf-8').
+ * @returns A SecureString instance.
+ */
+declare function createSecureStringFromBuffer(buffer: Buffer, encoding?: BufferEncoding): SecureString;
+/**
+ * Attempt to overwrite a string's memory with zeros.
+ *
+ * **Important limitation**: JavaScript strings are immutable in V8. This
+ * function works by creating a modified string that replaces characters,
+ * but V8 may retain copies of the original string in memory. This is a
+ * best-effort mitigation, not a guarantee.
+ *
+ * For truly secure handling, prefer SecureBuffer and SecureString which
+ * use mutable Buffer storage that CAN be reliably zeroed.
+ *
+ * @param str - The string to attempt to wipe.
+ *
+ * @example
+ * let password = 'my-secret-password';
+ * // ... use password ...
+ * wipeString(password);
+ * password = '';
+ */
+declare function wipeString(str: string): void;
+/**
+ * Constant-time comparison of two strings or Buffers.
+ *
+ * This function always takes the same amount of time regardless of where
+ * the first difference occurs, preventing timing attacks that could
+ * reveal information about the expected value.
+ *
+ * For strings: converts to UTF-8 Buffers and compares.
+ * For Buffers: compares directly.
+ * Different-length inputs are safely handled (returns false in constant time).
+ *
+ * @param a - First value (string or Buffer).
+ * @param b - Second value (string or Buffer).
+ * @returns true if the values are identical.
+ *
+ * @example
+ * // Safe for comparing passwords, tokens, API keys, etc.
+ * const isMatch = secureCompare(userInput, storedHash);
+ *
+ * // Also works with Buffers
+ * const isMatch = secureCompare(keyBuffer, expectedKeyBuffer);
+ */
+declare function secureCompare(a: string | Buffer, b: string | Buffer): boolean;
+
+/**
+ * Scan multiple files for secrets.
+ *
+ * Collects files from the given paths, respects include/exclude patterns,
+ * skips binary files and common non-source directories, checks .gitignore,
+ * and runs both pattern matching and entropy analysis on each file.
+ *
+ * @param paths - File or directory paths to scan.
+ * @param options - Scan configuration options.
+ * @returns A ScanResult with all detected secrets and metadata.
+ */
+declare function scanFiles(paths: readonly string[], options?: Partial<ScanOptions>): Promise<ScanResult>;
+
+/**
+ * Scan files staged for commit (in the git index) for secrets.
+ *
+ * Uses `git diff --cached` to get the staged content and scans it
+ * for any detected secrets.
+ *
+ * @param cwd - Working directory (default: process.cwd()).
+ * @returns Array of DetectedSecret objects found in staged files.
+ */
+declare function scanStagedFiles(cwd?: string): Promise<DetectedSecret[]>;
+/**
+ * Scan a git diff between two refs (or between a ref and working tree) for secrets.
+ *
+ * @param from - The base commit ref.
+ * @param to - The target commit ref. If omitted, compares to working tree.
+ * @param cwd - Working directory.
+ * @returns Array of DetectedSecret objects found in the diff.
+ */
+declare function scanDiff(from: string, to?: string, cwd?: string): Promise<DetectedSecret[]>;
+/**
+ * Git history scanning options.
+ */
+interface GitScanOptions {
+    /** Starting commit (default: HEAD~100) */
+    from?: string;
+    /** Ending commit (default: HEAD) */
+    to?: string;
+    /** Working directory (default: process.cwd()) */
+    cwd?: string;
+    /** Number of commits to scan (default: 100) */
+    depth?: number;
+    /** Whether to scan all history (overrides depth) */
+    allHistory?: boolean;
+}
+/**
+ * Scan git commit history for secrets.
+ *
+ * Uses `git log -p` to get patch content for each commit and scans
+ * for secrets. Reports each finding with the associated commit hash.
+ *
+ * @param options - Git scanning options.
+ * @returns A ScanResult with secrets found in git history.
+ */
+declare function scanGitHistory(options?: GitScanOptions): Promise<ScanResult>;
+
+/**
+ * Match all registered patterns against the given content.
+ *
+ * Iterates over every pattern in the registry and collects all detections.
+ *
+ * @param content - The text content to scan.
+ * @param filePath - Path to the file being scanned.
+ * @returns Array of DetectedSecret objects for all pattern matches.
+ */
+declare function matchPatterns(content: string, filePath: string): DetectedSecret[];
+/**
+ * Add a custom secret detection pattern to the registry.
+ *
+ * If a pattern with the same ID already exists, it will be replaced.
+ *
+ * @param pattern - The SecretPattern to add.
+ * @throws {Error} If the pattern has an invalid regex.
+ */
+declare function addCustomPattern(pattern: SecretPattern): void;
+/**
+ * Remove a custom (or built-in) pattern from the registry by ID.
+ *
+ * @param id - The unique pattern identifier to remove.
+ * @returns true if a pattern was removed, false if not found.
+ */
+declare function removeCustomPattern(id: string): boolean;
+/**
+ * Remove all custom patterns, restoring the registry to built-in patterns only.
+ */
+declare function resetPatterns(): void;
+
+/**
+ * Supported output formats.
+ */
+type OutputFormat = 'terminal' | 'json' | 'sarif';
+/**
+ * Format a scan result in the specified output format.
+ *
+ * @param result - The scan result to format.
+ * @param format - The output format ('terminal', 'json', or 'sarif').
+ * @returns A formatted string representation of the scan result.
+ */
+declare function formatScanResult(result: ScanResult, format: OutputFormat): string;
+
+/**
+ * Full scan options including git-specific options.
+ */
+interface FullScanOptions extends Partial<ScanOptions> {
+    /** Whether to scan staged files (for pre-commit hooks) */
+    scanStaged?: boolean;
+    /** Git ref to diff against (for diff scanning) */
+    diffFrom?: string;
+    /** Git ref to diff to (for diff scanning) */
+    diffTo?: string;
+    /** Number of git history commits to scan */
+    gitDepth?: number;
+    /** Scan all git history (overrides gitDepth) */
+    gitAllHistory?: boolean;
+    /** Output format for the report */
+    outputFormat?: 'terminal' | 'json' | 'sarif';
+    /** Working directory */
+    cwd?: string;
+    /** Paths to scan (files or directories) */
+    paths?: string[];
+}
+/**
+ * Perform a comprehensive secret scan.
+ *
+ * Combines:
+ * 1. File scanning (pattern matching + entropy analysis)
+ * 2. Git history scanning (if enabled)
+ * 3. Staged file scanning (if enabled)
+ * 4. Diff scanning (if refs provided)
+ *
+ * Results are deduplicated and sorted by severity.
+ *
+ * @param options - Scan configuration options.
+ * @returns A ScanResult with all detected secrets and metadata.
+ *
+ * @example
+ * // Scan current directory
+ * const result = await scan();
+ * console.log(formatScanResult(result, 'terminal'));
+ *
+ * // Scan with options
+ * const result = await scan({
+ *   include: ['src/', 'config/'],
+ *   exclude: ['src/*.test.ts'],
+ *   scanGitHistory: true,
+ * });
+ */
+declare function scan(options?: FullScanOptions): Promise<ScanResult>;
+
+interface EntropyOptions {
+    /** Minimum Shannon entropy threshold (default: 3.5) */
+    threshold?: number;
+    /** Minimum string length to consider (default: 20) */
+    minLength?: number;
+    /** Maximum string length to consider (default: 500) */
+    maxLength?: number;
+    /** Whether to include the high-entropy pattern in results (default: true) */
+    includeDefaultPattern?: boolean;
+}
+/**
+ * Scan a single line for high-entropy strings.
+ *
+ * Extracts candidate strings from the line, computes Shannon entropy,
+ * filters false positives, and returns detections above the threshold.
+ *
+ * @param line - The line of text to scan.
+ * @param lineNumber - The 1-based line number.
+ * @param filePath - The file path being scanned.
+ * @param options - Entropy detection options.
+ * @returns Array of DetectedSecret objects for high-entropy strings found.
+ */
+declare function scanLineForEntropy(line: string, lineNumber: number, filePath: string, options?: EntropyOptions): DetectedSecret[];
+/**
+ * Detect high-entropy strings in file content.
+ *
+ * Processes the content line by line, extracts candidate strings,
+ * computes Shannon entropy, and returns detections above the threshold.
+ *
+ * @param content - The full text content to scan.
+ * @param filePath - The file path being scanned.
+ * @param options - Entropy detection options.
+ * @returns Array of DetectedSecret objects for high-entropy strings found.
+ */
+declare function detectHighEntropyStrings(content: string, filePath: string, options?: EntropyOptions): DetectedSecret[];
+
+interface GenerateExampleOptions {
+    /** Include type hint comments (default: true) */
+    includeDescriptions?: boolean;
+    /** Include type annotation comments (default: true) */
+    includeTypes?: boolean;
+    /** Include default values in comments (default: true) */
+    includeDefaults?: boolean;
+    /** Path to a schema file (TypeScript module exporting schema) for metadata */
+    schemaPath?: string;
+}
+/**
+ * Generate a .env.example file from a .env file.
+ *
+ * Reads the .env file, strips secret values, preserves comments and variable
+ * ordering, and optionally adds type hints, descriptions, and default values
+ * from a schema definition.
+ *
+ * @param envPath - Path to the source .env file
+ * @param outputPath - Path where the .env.example will be written
+ * @param options - Generation options
+ * @throws FileSystemError if the .env file cannot be read
+ */
+declare function generateExampleFile(envPath: string, outputPath: string, options?: GenerateExampleOptions): Promise<void>;
+/**
+ * Generate the content of a .env.example file from parsed variables.
+ *
+ * @param vars - Parsed environment variables from a .env file
+ * @param schema - Optional schema definition for type/description metadata
+ * @param options - Generation options
+ * @returns The complete .env.example file content as a string
+ */
+declare function generateExampleContent(vars: readonly ParsedEnvVar[], schema?: SchemaDefinition, options?: {
+    includeDescriptions?: boolean;
+    includeTypes?: boolean;
+    includeDefaults?: boolean;
+}): string;
+/**
+ * Check if a .env.example file needs updating by comparing its content
+ * with what would be generated from the current .env file.
+ */
+declare function needsUpdate(envPath: string, examplePath: string, options?: GenerateExampleOptions): Promise<boolean>;
+
+/**
+ * Result of comparing .env against .env.example.
+ */
+interface SyncDiff {
+    /** Whether the two files are perfectly in sync */
+    inSync: boolean;
+    /** Variables present in .env.example but missing from .env */
+    missing: readonly string[];
+    /** Variables present in .env but not in .env.example */
+    extra: readonly string[];
+    /** Variables present in both but with different values (example has placeholder) */
+    different: readonly string[];
+    /** Variables present in both with the same value */
+    same: readonly string[];
+}
+/**
+ * Compare a .env file against a .env.example file.
+ *
+ * Analyzes both files and categorizes every variable into:
+ * - **missing**: present in .env.example but not in .env (needs to be added)
+ * - **extra**: present in .env but not in .env.example (possibly sensitive)
+ * - **different**: present in both but values differ (example may have placeholder)
+ * - **same**: present in both with matching values
+ *
+ * A file is considered "in sync" when there are no missing or extra variables.
+ * "Different" variables do NOT cause inSync to be false since the .env.example
+ * typically contains placeholder values rather than actual secrets.
+ *
+ * @param envPath - Path to the .env file
+ * @param examplePath - Path to the .env.example file
+ * @returns SyncDiff with categorized differences
+ * @throws FileSystemError if either file cannot be read
+ */
+declare function compareSync(envPath: string, examplePath: string): Promise<SyncDiff>;
+/**
+ * Compare two sets of environment variables.
+ *
+ * This is the core comparison logic, useful when you already have parsed
+ * variables and don't need file I/O.
+ *
+ * @param envVars - The actual environment variables (e.g., from .env)
+ * @param exampleVars - The example/template variables (e.g., from .env.example)
+ * @returns SyncDiff with categorized differences
+ */
+declare function compareValues(envVars: Record<string, string>, exampleVars: Record<string, string>): SyncDiff;
+
+interface CreateSyncWatcherOptions {
+    /** Path to the .env file to watch */
+    envPath: string;
+    /** Path to the .env.example file to update */
+    examplePath: string;
+    /** Schema definition for type hints (if available) */
+    schema?: SchemaDefinition;
+    /** Debounce interval in milliseconds (default: 300) */
+    debounceMs?: number;
+    /** Whether to include descriptions in the generated example */
+    includeDescriptions?: boolean;
+    /** Whether to include type annotations */
+    includeTypes?: boolean;
+    /** Whether to include default values */
+    includeDefaults?: boolean;
+    /** Callback invoked after a successful sync */
+    onSync?: (result: SyncWatcherResult) => void;
+}
+interface SyncWatcherResult {
+    /** Whether the sync was successful */
+    success: boolean;
+    /** The env file that triggered the sync */
+    envPath: string;
+    /** The example file that was updated */
+    examplePath: string;
+    /** Error message if sync failed */
+    error?: string;
+    /** Timestamp of the sync */
+    timestamp: string;
+}
+/**
+ * Create a new SyncWatcher that monitors a .env file and auto-updates .env.example.
+ *
+ * @param options - Configuration for the watcher
+ * @returns A Watcher instance
+ *
+ * @example
+ * ```ts
+ * import { createSyncWatcher } from 'ultraenv/sync';
+ *
+ * const watcher = createSyncWatcher({
+ *   envPath: '.env',
+ *   examplePath: '.env.example',
+ *   onSync: (result) => {
+ *     if (result.success) {
+ *       console.log('.env.example updated');
+ *     }
+ *   },
+ * });
+ *
+ * watcher.start();
+ * process.on('SIGINT', () => watcher.stop());
+ * ```
+ */
+declare function createSyncWatcher(options: CreateSyncWatcherOptions): Watcher;
+
+interface GenerateDeclarationOptions {
+    /** Interface name for the generated env type (default: 'UltraenvEnv') */
+    interfaceName?: string;
+    /** Custom header comment */
+    header?: string;
+    /** Whether to include JSDoc comments from schema descriptions */
+    jsdoc?: boolean;
+    /** Indentation in spaces (default: 4) */
+    indent?: number;
+}
+/**
+ * Generate TypeScript declaration content that augments NodeJS.ProcessEnv.
+ */
+declare function generateDeclaration(vars: Record<string, string>, schema?: SchemaDefinition, outputPath?: string, options?: GenerateDeclarationOptions): Promise<string>;
+
+interface GenerateModuleOptions {
+    /** Interface name (default: 'Env') */
+    interfaceName?: string;
+    /** Custom header comment */
+    header?: string;
+    /** Whether to include JSDoc comments from schema descriptions */
+    jsdoc?: boolean;
+    /** Indentation in spaces (default: 2) */
+    indent?: number;
+    /** Whether to export the interface as default */
+    exportAsDefault?: boolean;
+}
+/**
+ * Generate a TypeScript module with a typed Env interface.
+ */
+declare function generateModule(schema: SchemaDefinition, outputPath?: string, options?: GenerateModuleOptions): Promise<string>;
+
+interface GenerateJsonSchemaOptions {
+    /** Title for the JSON Schema (default: 'Environment Variables') */
+    title?: string;
+    /** Description for the JSON Schema */
+    description?: string;
+    /** Whether to include schema descriptions in the output */
+    includeDescriptions?: boolean;
+    /** Indentation in spaces (default: 2) */
+    indent?: number;
+}
+/**
+ * Generate a JSON Schema (draft-07) from a SchemaDefinition.
+ */
+declare function generateJsonSchema(schema: SchemaDefinition, outputPath?: string, options?: GenerateJsonSchemaOptions): Promise<string>;
+
+type TypegenFormat = 'declaration' | 'module' | 'json-schema' | 'all';
+interface CreateTypegenWatcherOptions {
+    /** Path to the schema file (watched for changes) */
+    schemaPath?: string;
+    /** Path to the .env file (watched for changes) */
+    envPath?: string;
+    /** Output path for the generated type file(s) */
+    outputPath: string;
+    /** The schema definition (used when schemaPath is not provided) */
+    schema?: SchemaDefinition;
+    /** Which formats to generate (default: 'declaration') */
+    format?: TypegenFormat;
+    /** Debounce interval in milliseconds (default: 300) */
+    debounceMs?: number;
+    /** Callback invoked after generation */
+    onGenerate?: (result: TypegenResult) => void;
+}
+interface TypegenResult {
+    /** Whether generation was successful */
+    success: boolean;
+    /** The format that was generated */
+    format: TypegenFormat;
+    /** Output path(s) written */
+    outputPaths: readonly string[];
+    /** Error message if generation failed */
+    error?: string;
+    /** Timestamp */
+    timestamp: string;
+}
+/**
+ * Create a new TypegenWatcher that monitors schema and env files,
+ * regenerating type declarations whenever changes are detected.
+ *
+ * @param options - Configuration for the watcher
+ * @returns A Watcher instance
+ *
+ * @example
+ * ```ts
+ * import { createTypegenWatcher } from 'ultraenv/typegen';
+ *
+ * const watcher = createTypegenWatcher({
+ *   envPath: '.env',
+ *   outputPath: 'src/env.d.ts',
+ *   schema: mySchema,
+ *   format: 'all',
+ *   onGenerate: (result) => {
+ *     if (result.success) {
+ *       console.log(`Generated: ${result.outputPaths.join(', ')}`);
+ *     }
+ *   },
+ * });
+ *
+ * watcher.start();
+ * process.on('SIGINT', () => watcher.stop());
+ * ```
+ */
+declare function createTypegenWatcher(options: CreateTypegenWatcherOptions): Watcher;
+
+interface EnvironmentInfo {
+    name: string;
+    fileName: string;
+    absolutePath: string;
+    exists: boolean;
+    variableCount: number;
+    fileSize: number;
+    lastModified: string;
+}
+type EnvironmentValidationMap = Map<string, {
+    valid: boolean;
+    errors: readonly {
+        field: string;
+        value: string;
+        message: string;
+        hint: string;
+    }[];
+    warnings: readonly {
+        field: string;
+        value: string;
+        message: string;
+        code: string;
+    }[];
+}>;
+declare function listEnvironments(cwd?: string): Promise<EnvironmentInfo[]>;
+declare function validateAllEnvironments(schema: SchemaDefinition, cwd?: string): Promise<EnvironmentValidationMap>;
+declare function switchEnvironment(envName: string, cwd?: string): Promise<void>;
+declare function getActiveEnvironment(cwd?: string): Promise<string>;
+declare function discoverEnvironments(cwd?: string): Promise<string[]>;
+
+/**
+ * Result of comparing two environments.
+ */
+interface EnvironmentComparison {
+    /** The first environment name */
+    env1Name: string;
+    /** The second environment name */
+    env2Name: string;
+    /** Variables only present in env1 */
+    onlyInEnv1: readonly EnvDifference[];
+    /** Variables only present in env2 */
+    onlyInEnv2: readonly EnvDifference[];
+    /** Variables present in both but with different values */
+    different: readonly EnvDifference[];
+    /** Variables present in both with the same value */
+    same: readonly string[];
+    /** Warnings about potentially dangerous differences */
+    warnings: readonly ComparisonWarning[];
+}
+/**
+ * A single variable difference between two environments.
+ */
+interface EnvDifference {
+    /** The variable name */
+    key: string;
+    /** Value in env1 (masked if secret) */
+    value1: string;
+    /** Value in env2 (masked if secret) */
+    value2: string;
+    /** Whether the value is a secret */
+    isSecret: boolean;
+}
+/**
+ * A warning about a potentially dangerous difference.
+ */
+interface ComparisonWarning {
+    /** The variable name */
+    key: string;
+    /** Warning message */
+    message: string;
+    /** Severity level */
+    severity: 'critical' | 'high' | 'medium' | 'low';
+    /** Value in env1 (masked) */
+    value1: string;
+    /** Value in env2 (masked) */
+    value2: string;
+}
+/**
+ * Compare two .env environment files and report differences.
+ *
+ * This compares the variables between two environments, masks secret values
+ * in the output, and generates warnings for potentially dangerous differences
+ * (e.g., different database URLs, disabled security features, debug mode enabled).
+ *
+ * @param env1 - Name of the first environment (e.g., 'development')
+ * @param env2 - Name of the second environment (e.g., 'production')
+ * @param cwd - The directory containing the .env files
+ * @param schema - Optional schema for identifying secrets and required fields
+ * @returns EnvironmentComparison with detailed difference information
+ * @throws FileSystemError if either environment file cannot be read
+ */
+declare function compareEnvironments(env1: string, env2: string, cwd?: string, _schema?: unknown): Promise<EnvironmentComparison>;
+/**
+ * Format an EnvironmentComparison into a human-readable summary string.
+ *
+ * @param comparison - The comparison result
+ * @returns Formatted string suitable for terminal output
+ */
+declare function formatComparison(comparison: EnvironmentComparison): string;
+
+interface CreateEnvironmentOptions {
+    copyFrom?: string;
+    fromTemplate?: string;
+    interactive?: boolean;
+    schema?: SchemaDefinition;
+    cwd?: string;
+    values?: Record<string, string>;
+}
+declare function createEnvironment(name: string, options?: CreateEnvironmentOptions): Promise<void>;
+declare function removeEnvironment(name: string, cwd?: string): Promise<void>;
+declare function duplicateEnvironment(sourceName: string, targetName: string, cwd?: string): Promise<void>;
+
+/**
+ * Register a preset by name.
+ *
+ * If a preset with the same name already exists, it will be replaced
+ * with a warning logged to stderr.
+ *
+ * @param name - Unique identifier for the preset (e.g., 'nextjs', 'vite')
+ * @param preset - The preset definition
+ *
+ * @example
+ * ```typescript
+ * import { registerPreset } from 'ultraenv/presets';
+ * registerPreset('my-framework', { id: 'my-framework', ... });
+ * ```
+ */
+declare function registerPreset(name: string, preset: Preset): void;
+/**
+ * Retrieve a preset by name.
+ *
+ * @param name - The preset identifier
+ * @returns The preset definition, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * import { getPreset } from 'ultraenv/presets';
+ * const nextjs = getPreset('nextjs');
+ * console.log(nextjs?.schema);
+ * ```
+ */
+declare function getPreset(name: string): Preset | undefined;
+/**
+ * List all registered preset names.
+ *
+ * @returns Array of preset identifier strings
+ *
+ * @example
+ * ```typescript
+ * import { listPresets } from 'ultraenv/presets';
+ * console.log(listPresets());
+ * // ['nextjs', 'vite', 'nuxt', 'remix', 'sveltekit', 'express', 'fastify', 'docker', 'aws-lambda']
+ * ```
+ */
+declare function listPresets(): string[];
+/**
+ * Check if a preset is registered.
+ *
+ * @param name - The preset identifier
+ * @returns Whether the preset exists in the registry
+ */
+declare function hasPreset(name: string): boolean;
+/**
+ * Remove a preset from the registry.
+ *
+ * @param name - The preset identifier to remove
+ * @returns Whether the preset was found and removed
+ */
+declare function unregisterPreset(name: string): boolean;
+/**
+ * Get all registered presets as a readonly record.
+ *
+ * @returns Readonly record of preset name → preset definition
+ */
+declare function getAllPresets(): Readonly<Record<string, Preset>>;
+
+/** Health check configuration options */
+interface HealthCheckOptions {
+    /**
+     * Custom env source to check.
+     * Defaults to process.env.
+     */
+    source?: Record<string, string | undefined>;
+    /**
+     * List of loaded .env files (for metadata).
+     */
+    loadedFiles?: readonly string[];
+    /**
+     * Total number of validated variables (from schema validation).
+     */
+    validCount?: number;
+    /**
+     * Additional metadata to include in the health response.
+     */
+    metadata?: Record<string, string | number | boolean>;
+}
+/** Health check response structure */
+interface HealthCheckResult {
+    /** Overall health status: 'ok' or 'error' */
+    status: 'ok' | 'error';
+    /** Total number of environment variables loaded */
+    loaded: number;
+    /** Number of variables that passed validation */
+    valid: number;
+    /** Current environment name */
+    environment: string;
+    /** List of .env files that were loaded */
+    files: readonly string[];
+    /** ISO 8601 timestamp of the check */
+    timestamp: string;
+    /** Any additional metadata */
+    metadata: Record<string, string | number | boolean>;
+}
+/**
+ * Perform an environment health check.
+ *
+ * Returns a structured object with health status information
+ * WITHOUT exposing any secret values. This is safe to expose
+ * via HTTP endpoints.
+ *
+ * @param options - Health check configuration
+ * @returns Health check result
+ *
+ * @example
+ * ```typescript
+ * import { healthCheck } from 'ultraenv';
+ * import { loadWithResult } from 'ultraenv';
+ *
+ * const result = loadWithResult();
+ * const health = healthCheck({
+ *   source: result.env,
+ *   loadedFiles: result.parsed.map(f => f.path),
+ *   validCount: result.validation?.errors.length === 0 ? Object.keys(result.env).length : 0,
+ * });
+ *
+ * // Use in Express:
+ * app.get('/health/env', (req, res) => res.json(healthCheck()));
+ *
+ * // Use in Fastify:
+ * fastify.get('/health/env', async () => healthCheck());
+ * ```
+ */
+declare function healthCheck(options?: HealthCheckOptions): HealthCheckResult;
+/**
+ * Returns a minimal liveness check response.
+ * Suitable for Kubernetes liveness probes.
+ *
+ * @returns Simple liveness response
+ *
+ * @example
+ * app.get('/health/live', (req, res) => res.json(liveCheck()));
+ * // → { status: 'ok', timestamp: '2024-01-15T10:30:00.000Z' }
+ */
+declare function liveCheck(): {
+    status: 'ok';
+    timestamp: string;
+};
+/**
+ * Returns a readiness check that verifies critical env vars are set.
+ *
+ * @param requiredVars - List of env var names that MUST be set
+ * @param source - Custom env source (defaults to process.env)
+ * @returns Readiness check result
+ *
+ * @example
+ * app.get('/health/ready', (req, res) => {
+ *   res.json(readinessCheck(['DATABASE_URL', 'JWT_SECRET']));
+ * });
+ * // → { status: 'ok', ready: true, missing: [], timestamp: '...' }
+ * // → { status: 'error', ready: false, missing: ['DATABASE_URL'], timestamp: '...' }
+ */
+declare function readinessCheck(requiredVars: readonly string[], source?: Record<string, string | undefined>): {
+    status: 'ok' | 'error';
+    ready: boolean;
+    missing: readonly string[];
+    timestamp: string;
+};
+
+/**
+ * Base error class for all ultraenv errors.
+ * Provides a structured `code` field, an optional `hint` for remediation,
+ * and a `cause` wrapper for chaining.
+ */
+declare class UltraenvError extends Error {
+    /** Machine-readable error code (e.g., 'PARSE_ERROR', 'ENCRYPTION_ERROR') */
+    readonly code: string;
+    /** Human-readable hint for how to fix this error */
+    readonly hint?: string;
+    /** The original cause of this error, if wrapping another error */
+    readonly cause?: Error;
+    constructor(message: string, options?: {
+        code?: string;
+        hint?: string;
+        cause?: Error;
+    });
+    /** Return a formatted string with code, message, and hint */
+    toString(): string;
+}
+/**
+ * Thrown when an environment variable fails schema validation.
+ */
+declare class ValidationError extends UltraenvError {
+    /** The variable name that failed validation */
+    readonly field: string;
+    /** The actual value that was provided */
+    readonly value: string;
+    /** The schema definition that was violated */
+    readonly schema: unknown;
+    /** Expected type or constraint description */
+    readonly expected: string;
+    constructor(field: string, value: string, message: string, options?: {
+        hint?: string;
+        schema?: unknown;
+        expected?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when an .env file cannot be parsed due to malformed syntax.
+ */
+declare class ParseError extends UltraenvError {
+    /** 1-based line number where the error occurred */
+    readonly line: number;
+    /** 1-based column number where the error occurred */
+    readonly column: number;
+    /** The raw content of the line that caused the error */
+    readonly raw: string;
+    /** Path to the file being parsed */
+    readonly filePath: string;
+    constructor(message: string, options?: {
+        line?: number;
+        column?: number;
+        raw?: string;
+        filePath?: string;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when variable interpolation (e.g., $VAR or ${VAR}) fails.
+ */
+declare class InterpolationError extends UltraenvError {
+    /** The variable reference that caused the error */
+    readonly variable: string;
+    /** Whether this was caused by a circular reference */
+    readonly circular: boolean;
+    constructor(message: string, options?: {
+        variable?: string;
+        circular?: boolean;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when encryption or decryption operations fail.
+ */
+declare class EncryptionError extends UltraenvError {
+    constructor(message: string, options?: {
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when vault operations fail (lock/unlock/encrypt/decrypt).
+ */
+declare class VaultError extends UltraenvError {
+    /** The environment name involved */
+    readonly environment: string;
+    /** The vault operation that failed */
+    readonly operation: string;
+    constructor(message: string, options?: {
+        environment?: string;
+        operation?: string;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when secret scanning encounters an issue.
+ */
+declare class ScanError extends UltraenvError {
+    /** The file being scanned */
+    readonly file: string;
+    /** The line number where the error occurred */
+    readonly line: number;
+    /** The secret pattern that triggered the error */
+    readonly pattern: string;
+    constructor(message: string, options?: {
+        file?: string;
+        line?: number;
+        pattern?: string;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when the ultraenv configuration is invalid.
+ */
+declare class ConfigError extends UltraenvError {
+    /** The configuration field that is invalid */
+    readonly field: string;
+    constructor(message: string, options?: {
+        field?: string;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Thrown when file system operations fail.
+ */
+declare class FileSystemError extends UltraenvError {
+    /** The file or directory path involved */
+    readonly path: string;
+    /** The operation that failed (e.g., 'read', 'write', 'mkdir') */
+    readonly operation: string;
+    /** The underlying system error code (e.g., 'ENOENT', 'EACCES') */
+    readonly code: string;
+    constructor(message: string, options?: {
+        path?: string;
+        operation?: string;
+        code?: string;
+        hint?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Check if an error is an ultraenv error (or subclass thereof).
+ */
+declare function isUltraenvError(error: unknown): error is UltraenvError;
+
+/** Unicode box drawing characters set */
+interface BoxChars {
+    /** Top-left corner */
+    topLeft: string;
+    /** Top-right corner */
+    topRight: string;
+    /** Bottom-left corner */
+    bottomLeft: string;
+    /** Bottom-right corner */
+    bottomRight: string;
+    /** Horizontal line */
+    horizontal: string;
+    /** Vertical line */
+    vertical: string;
+    /** Left tee (vertical meets horizontal) */
+    leftTee: string;
+    /** Right tee (vertical meets horizontal) */
+    rightTee: string;
+}
+
+/** Options for the terminal reporter */
+interface TerminalReporterOptions {
+    /** Whether to use colors (auto-detected if not specified) */
+    color?: boolean;
+    /** Box character style */
+    boxStyle?: BoxChars;
+    /** Maximum width of output lines (0 = no limit) */
+    maxWidth?: number;
+}
+/**
+ * Report a validation result with rich formatting.
+ *
+ * - Green box for passing validations
+ * - Red box for errors with field details table
+ * - Yellow warnings section
+ *
+ * @param result - The validation result to report
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportValidation$1(result: ValidationResult, options?: TerminalReporterOptions): string;
+/**
+ * Report an UltraenvError with structured formatting.
+ *
+ * @param error - The error to report
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportError$1(error: UltraenvError, options?: TerminalReporterOptions): string;
+/**
+ * Report a success message with a green checkmark.
+ *
+ * @param message - The success message
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportSuccess(message: string, options?: TerminalReporterOptions): string;
+/**
+ * Report a warning with yellow formatting.
+ *
+ * @param warning - The validation warning to report
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportWarning(warning: ValidationWarning, options?: TerminalReporterOptions): string;
+/**
+ * Report an informational message.
+ *
+ * @param message - The info message
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportInfo(message: string, options?: TerminalReporterOptions): string;
+/**
+ * Report a scan result with severity-colored table.
+ *
+ * @param result - The scan result to report
+ * @param options - Reporter options
+ * @returns Formatted terminal string
+ */
+declare function reportScanResult$2(result: ScanResult, options?: TerminalReporterOptions): string;
+
+/** Options for the JSON reporter */
+interface JsonReporterOptions {
+    /**
+     * Whether to pretty-print the JSON output.
+     * Default: true (2-space indent)
+     */
+    pretty?: boolean;
+    /**
+     * Number of spaces for indentation when pretty-printing.
+     * Default: 2
+     */
+    indent?: number;
+    /**
+     * Whether to include stack traces for errors.
+     * Default: false
+     */
+    includeStack?: boolean;
+}
+/**
+ * Report a validation result as a JSON string.
+ *
+ * @param result - The validation result to report
+ * @param options - Reporter options
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * import { reportValidation } from 'ultraenv/reporters/json';
+ * const json = reportValidation(result);
+ * // → '{"valid":true,"errorCount":0,"warningCount":0,"...}'
+ * ```
+ */
+declare function reportValidation(result: ValidationResult, options?: JsonReporterOptions): string;
+/**
+ * Report an UltraenvError as a JSON string.
+ *
+ * @param error - The error to report
+ * @param options - Reporter options
+ * @returns JSON string
+ */
+declare function reportError(error: UltraenvError, options?: JsonReporterOptions): string;
+/**
+ * Report a scan result as a JSON string.
+ *
+ * @param result - The scan result to report
+ * @param options - Reporter options
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * import { reportScanResult } from 'ultraenv/reporters/json';
+ * const json = reportScanResult(scanResult);
+ * ```
+ */
+declare function reportScanResult$1(result: ScanResult, options?: JsonReporterOptions): string;
+
+/** SARIF rule object */
+interface SarifRule {
+    id: string;
+    name: string;
+    shortDescription: {
+        text: string;
+    };
+    fullDescription: {
+        text: string;
+    };
+    helpUri?: string;
+    properties: {
+        'security-severity': string;
+        tags: string[];
+    };
+}
+/**
+ * Report a scan result as a SARIF JSON string.
+ *
+ * Generates a valid SARIF v2.1.0 document compatible with:
+ * - GitHub Code Scanning
+ * - GitHub CodeQL action
+ * - Azure DevOps
+ * - VS Code SARIF Viewer
+ *
+ * @param result - The scan result to report
+ * @param options - Reporter options
+ * @returns SARIF JSON string
+ *
+ * @example
+ * ```typescript
+ * import { reportScanResult } from 'ultraenv/reporters/sarif';
+ * import { writeFileSync } from 'fs';
+ *
+ * const sarif = reportScanResult(scanResult);
+ * writeFileSync('results.sarif', sarif);
+ * ```
+ */
+declare function reportScanResult(result: ScanResult, options?: {
+    /** Tool version to report (default: '1.0.0') */
+    toolVersion?: string;
+    /** Custom rules to add to the SARIF output */
+    additionalRules?: readonly SarifRule[];
+}): string;
+
+interface MaskOptions {
+    /** Number of characters visible at the start (default: 3) */
+    visibleStart?: number;
+    /** Number of characters visible at the end (default: 4) */
+    visibleEnd?: number;
+    /** Character used for masking (default: '*') */
+    maskChar?: string;
+    /** Minimum value length before masking is applied (default: 8) */
+    minLength?: number;
+}
+/**
+ * Mask a secret value for safe display.
+ *
+ * @example
+ * maskValue('sk-abc12345def67890') → 'sk-***********7890'
+ * maskValue('short') → 'short' (below minLength, not masked)
+ * maskValue('') → ''
+ */
+declare function maskValue(value: string, options?: MaskOptions): string;
+
+/**
+ * Calculate the Shannon entropy of a string in bits per character.
+ *
+ * Shannon entropy measures the uncertainty (randomness) in a message.
+ * Higher values indicate more randomness / less predictability.
+ *
+ * - Uniform lowercase English text: ~4.0–4.5 bits
+ * - Mixed case + digits + symbols: ~5.0–6.0 bits
+ * - Random hex strings: ~4.0 bits (per char)
+ * - High-entropy secrets (base64, API keys): typically > 3.5 bits
+ *
+ * @param str - The input string to analyze.
+ * @returns Entropy in bits per character (0.0 for empty strings).
+ *
+ * @example
+ * shannonEntropy('hello')     // ~2.85
+ * shannonEntropy('a1b2c3d4')  // ~3.0
+ * shannonEntropy('xJ9#kL2$mP') // ~4.12
+ * shannonEntropy('')          // 0
+ */
+declare function shannonEntropy(str: string): number;
+/**
+ * Check if a string has high entropy, suggesting it may be a secret or token.
+ *
+ * Uses Shannon entropy with configurable threshold.
+ * Default threshold of 3.5 is calibrated to catch common secret formats
+ * (API keys, tokens, passwords) while minimizing false positives on
+ * regular text.
+ *
+ * @param str - The string to check.
+ * @param threshold - Minimum entropy to consider "high" (default: 3.5).
+ * @returns true if the string's entropy exceeds the threshold.
+ *
+ * @example
+ * isHighEntropy('my-database-password')  // false (~3.1)
+ * isHighEntropy('sk_live_4eC39HqLyjWDarjtT1zdp7dc')  // true (~4.2)
+ * isHighEntropy('a]c!D@f#G$h%J^k&L*m')  // true (~4.0)
+ */
+declare function isHighEntropy(str: string, threshold?: number): boolean;
+
+/** Current ultraenv version */
+declare const VERSION = "1.0.0";
+
+/**
+ * Parse a .env file content string into a structured representation.
+ *
+ * Supported syntax:
+ * - KEY=value
+ * - KEY="value with escapes: \\n \\t \\xHH \\uXXXX"
+ * - KEY='literal value (no escaping)'
+ * - KEY=`backtick value`
+ * - KEY= or KEY="" (empty values)
+ * - KEY (no = sign → empty string)
+ * - # comments
+ * - export KEY=value
+ * - Inline comments: KEY=value # this is a comment
+ * - Multiline values in double quotes
+ * - Whitespace trimming around = and quotes
+ *
+ * @param content - The raw file content string
+ * @param filePath - Optional file path for error messages
+ * @returns ParsedEnvFile with all extracted variables
+ * @throws ParseError on malformed syntax
+ */
+declare function parseEnvFile(content: string, filePath?: string): ParsedEnvFile;
+
+interface ExpandOptions {
+    /** Maximum recursion depth for nested variable references (default: 10) */
+    maxDepth?: number;
+    /** Additional environment variables (e.g., system process.env) to resolve from */
+    systemEnv?: Record<string, string | undefined>;
+}
+/**
+ * Expand variable references in all values of the given env object.
+ *
+ * Supported expansions:
+ * - $VAR          → simple substitution
+ * - ${VAR}        → simple substitution (braced)
+ * - ${VAR:-def}   → default if unset or empty
+ * - ${VAR-def}    → default if unset
+ * - ${VAR:+alt}   → replacement if set and non-empty
+ * - ${VAR+alt}    → replacement if set
+ * - ${VAR:?err}   → error if unset or empty
+ * - ${VAR?err}    → error if unset
+ * - ${VAR^^}      → uppercase
+ * - ${VAR,,}      → lowercase
+ * - ${VAR:0:5}    → substring
+ * - ${#VAR}       → string length
+ * - \${VAR}       → escaped literal (no expansion)
+ *
+ * @param vars - The env variables to expand (key-value pairs)
+ * @param env - The full env map for resolving references (usually the same as vars)
+ * @param options - Expansion options
+ * @returns A new Record with all variable references expanded
+ * @throws InterpolationError on circular references or maximum depth exceeded
+ */
+declare function expandVariables(vars: Record<string, string>, env: Record<string, string>, options?: ExpandOptions): Record<string, string>;
+
+/**
+ * Read a file and return its contents as a string.
+ * @throws FileSystemError if the file cannot be read.
+ */
+declare function readFile(filePath: string, encoding?: BufferEncoding): Promise<string>;
+/**
+ * Synchronously read a file and return its contents as a string.
+ * Use sparingly — prefer the async version.
+ */
+declare function readFileSync(filePath: string, encoding?: BufferEncoding): string;
+/**
+ * Write content to a file, creating parent directories if needed.
+ * @throws FileSystemError if the write fails.
+ */
+declare function writeFile(filePath: string, content: string, encoding?: BufferEncoding): Promise<void>;
+/**
+ * Check if a path exists on the filesystem.
+ */
+declare function exists(filePath: string): Promise<boolean>;
+/**
+ * Check if the given path points to a regular file.
+ */
+declare function isFile(filePath: string): Promise<boolean>;
+/**
+ * Check if the given path points to a directory.
+ */
+declare function isDirectory(dirPath: string): Promise<boolean>;
+/**
+ * Ensure a directory exists, creating it recursively if necessary (mkdir -p).
+ */
+declare function ensureDir(dirPath: string): Promise<void>;
+/**
+ * Remove a file. Does nothing if the file does not exist.
+ */
+declare function removeFile(filePath: string): Promise<void>;
+/**
+ * Copy a file from src to dest, creating parent directories if needed.
+ */
+declare function copyFile(src: string, dest: string): Promise<void>;
+/**
+ * List files in a directory.
+ * @param dirPath - Directory to scan.
+ * @param recursive - Whether to recurse into subdirectories (default: false).
+ * @returns Array of file paths relative to dirPath.
+ */
+declare function listFiles(dirPath: string, recursive?: boolean): Promise<string[]>;
+/**
+ * Walk up the directory tree looking for a file with the given name.
+ * @param name - File name to search for (e.g., '.env').
+ * @param cwd - Starting directory (default: process.cwd()).
+ * @returns Absolute path to the found file, or null if not found.
+ */
+declare function findUp(name: string, cwd?: string): Promise<string | null>;
+
+/**
+ * ultraenv — The Ultimate Environment Variable Manager
+ *
+ * @example
+ * ```typescript
+ * // Simple loading (dotenv-compatible)
+ * import { load } from 'ultraenv';
+ * load();
+ *
+ * // Schema-based validation with full type inference
+ * import { defineEnv, t } from 'ultraenv';
+ * const env = defineEnv({
+ *   PORT: t.number().port().default(3000),
+ *   DATABASE_URL: t.string().url().required(),
+ *   NODE_ENV: t.enum(['development', 'staging', 'production'] as const).required(),
+ *   DEBUG: t.boolean().default(false),
+ * });
+ * // env.PORT → number (not string!)
+ * // env.NODE_ENV → 'development' | 'staging' | 'production'
+ * ```
+ *
+ * @module ultraenv
+ */
+
+declare const _default: {
+    version: string;
+};
+
+export { ConfigError, type DetectedSecret, EncryptionError, type EncryptionResult, FileSystemError, InterpolationError, type LoadMetadata, type LoadOptions, type LoadResult, ParseError, type ParsedEnvFile, type ParsedEnvVar, type Preset, ScanError, type ScanOptions, type ScanResult, type SecretPattern, SecureBuffer, SecureString, type SyncDiff$1 as SyncDiff, type SyncResult, type TypegenOptions, type UltraenvConfig, UltraenvError, ValidationError as UltraenvValidationError, VERSION, VaultError, type WatchOptions, type Watcher, type WatcherEvent, addCustomPattern, compareEnvironments, compareSync, compareValues, computeIntegrity, computeVaultChecksum, copyFile, createEnvironment, createSecureString, createSecureStringFromBuffer, createSyncWatcher, createTypegenWatcher, createWatcher, decryptEnvironment, decryptValue, _default as default, deriveEnvironmentKey, detectHighEntropyStrings, discoverEnvironments, duplicateEnvironment, encryptEnvironment, encryptValue, ensureDir, exists, expandVariables, findConfig, findUp, formatComparison, formatKey, formatScanResult, generateDeclaration, generateExampleContent, generateExampleFile, generateJsonSchema, generateKeysFile, generateMasterKey, generateModule, getActiveEnvironment, getAllPresets, getEnvironmentData, getPreset, getVaultEnvironments, hasPreset, healthCheck, isDirectory, isEncryptedValue, isFile, isHighEntropy, isUltraenvError, isValidKeyFormat, listEnvironments, listFiles, listPresets, liveCheck, load, loadConfig, loadSync, loadWithResult, loadWithResultSync, maskKey, maskValue as maskSecretValue, matchPatterns, mergeCascade, needsUpdate, parseEnvFile, parseKey, parseKeysFile, parseVaultFile, readFile, readFileSync, readVaultFile, readinessCheck, registerPreset, removeCustomPattern, removeEnvironment, removeFile, reportError$1 as reportError, reportError as reportErrorJson, reportInfo, reportScanResult$1 as reportScanResultJson, reportScanResult as reportScanResultSarif, reportScanResult$2 as reportScanResultTerminal, reportSuccess, reportValidation$1 as reportValidation, reportValidation as reportValidationJson, reportWarning, resetPatterns, resolveCascade, rotateKey, scan, scanDiff, scanFiles, scanGitHistory, scanLineForEntropy, scanStagedFiles, secureCompare, serializeVaultFile, shannonEntropy, switchEnvironment, unregisterPreset, validateAllEnvironments, verifyIntegrity, verifyVaultChecksum, wipeString, writeFile, writeVaultFile };