@utilarium/cardigantime 0.0.24-dev.0

package/dist/discovery/discoverer.d.ts

@@ -0,0 +1,62 @@
+import { ConfigDiscoveryOptions, DiscoveryResult, Logger } from '../types';
+/**
+ * Discovers configuration files in a directory using multiple naming patterns.
+ *
+ * Checks patterns in priority order and returns the first match.
+ * If `warnOnMultipleConfigs` is enabled (default), continues scanning after
+ * the first match to detect and warn about additional config files.
+ *
+ * @param directory - Directory to search for configuration files
+ * @param options - Discovery options including app name and patterns
+ * @param logger - Optional logger for debug/info/warn messages
+ * @returns Discovery result containing the found config and any warnings
+ *
+ * @example
+ * ```typescript
+ * const result = await discoverConfig('/path/to/project', {
+ *   appName: 'myapp',
+ *   extensions: ['yaml', 'json'],
+ * });
+ *
+ * if (result.config) {
+ *   console.log(`Found config: ${result.config.absolutePath}`);
+ * }
+ *
+ * if (result.multipleConfigWarning) {
+ *   console.warn(`Multiple configs found. Using ${result.multipleConfigWarning.used.path}`);
+ * }
+ * ```
+ */
+export declare function discoverConfig(directory: string, options: ConfigDiscoveryOptions, logger?: Logger): Promise<DiscoveryResult>;
+/**
+ * Discovers configuration files across multiple directories.
+ * Useful for hierarchical configuration where multiple directories may contain config files.
+ *
+ * @param directories - Directories to search, in order of precedence (first = highest)
+ * @param options - Discovery options
+ * @param logger - Optional logger
+ * @returns Array of discovery results, one per directory that had a config
+ *
+ * @example
+ * ```typescript
+ * const results = await discoverConfigsInHierarchy(
+ *   ['/project/subdir', '/project', '/home/user'],
+ *   { appName: 'myapp' }
+ * );
+ *
+ * // results[0] = config from /project/subdir (if exists)
+ * // results[1] = config from /project (if exists)
+ * // etc.
+ * ```
+ */
+export declare function discoverConfigsInHierarchy(directories: string[], options: ConfigDiscoveryOptions, logger?: Logger): Promise<DiscoveryResult[]>;
+/**
+ * Quickly checks if any config file exists in a directory.
+ * More efficient than `discoverConfig` when you only need to know if a config exists,
+ * not which one it is.
+ *
+ * @param directory - Directory to check
+ * @param options - Discovery options
+ * @returns True if any config file exists
+ */
+export declare function hasConfigFile(directory: string, options: ConfigDiscoveryOptions): Promise<boolean>;

package/dist/discovery/hierarchical-modes.d.ts

@@ -0,0 +1,64 @@
+import { HierarchicalMode, HierarchicalOptions, ConfigDiscoveryOptions, DiscoveredConfig, Logger } from '../types';
+/**
+ * Result of hierarchical config discovery with mode awareness.
+ */
+export interface HierarchicalDiscoveryResult {
+    /** The mode that was used for discovery */
+    mode: HierarchicalMode;
+    /** Primary config (if found) */
+    primaryConfig: DiscoveredConfig | null;
+    /** All configs found during traversal (for 'enabled' mode) */
+    configs: DiscoveredConfig[];
+    /** Directories that were searched */
+    searchedDirectories: string[];
+    /** Whether hierarchical loading should occur */
+    shouldMerge: boolean;
+}
+/**
+ * Resolves hierarchical options with defaults.
+ *
+ * @param options - User-provided options
+ * @returns Resolved options with defaults applied
+ */
+export declare function resolveHierarchicalOptions(options?: Partial<HierarchicalOptions>): Required<HierarchicalOptions>;
+/**
+ * Discovers configuration files using the specified hierarchical mode.
+ *
+ * @param startPath - Starting directory for discovery
+ * @param discoveryOptions - Config discovery options (app name, patterns, etc.)
+ * @param hierarchicalOptions - Hierarchical mode options
+ * @param logger - Optional logger
+ * @returns Hierarchical discovery result
+ *
+ * @example
+ * ```typescript
+ * // Disabled mode - only check starting directory
+ * const result = await discoverWithMode('/project/src',
+ *   { appName: 'myapp' },
+ *   { mode: 'disabled' }
+ * );
+ *
+ * // Enabled mode - full hierarchical traversal
+ * const result = await discoverWithMode('/project/src',
+ *   { appName: 'myapp' },
+ *   { mode: 'enabled', maxDepth: 5 }
+ * );
+ * ```
+ */
+export declare function discoverWithMode(startPath: string, discoveryOptions: ConfigDiscoveryOptions, hierarchicalOptions?: Partial<HierarchicalOptions>, logger?: Logger): Promise<HierarchicalDiscoveryResult>;
+/**
+ * Checks if a config content specifies a hierarchical mode override.
+ * Configs can set `hierarchical.mode: disabled` to prevent parent merging.
+ *
+ * @param configContent - Parsed config content
+ * @returns The override mode if specified, undefined otherwise
+ */
+export declare function getHierarchicalModeOverride(configContent: unknown): HierarchicalMode | undefined;
+/**
+ * Gets hierarchical options from a config content.
+ * Extracts any hierarchical settings from the config.
+ *
+ * @param configContent - Parsed config content
+ * @returns Partial hierarchical options, or undefined if none
+ */
+export declare function getHierarchicalOptionsFromConfig(configContent: unknown): Partial<HierarchicalOptions> | undefined;

package/dist/discovery/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Configuration Discovery Module
+ *
+ * Provides functionality for discovering configuration files in various
+ * standard locations using customizable naming patterns.
+ *
+ * @module discovery
+ */
+export { STANDARD_PATTERNS, DEFAULT_EXTENSIONS, expandPattern, getDiscoveryPaths, } from './patterns';
+export { discoverConfig, discoverConfigsInHierarchy, hasConfigFile, } from './discoverer';
+export { isProjectRoot, findProjectRoot, shouldStopAt, walkUpToRoot, getDirectoriesToRoot, } from './root-detection';
+export type { RootDetectionResult } from './root-detection';
+export { discoverWithMode, resolveHierarchicalOptions, getHierarchicalModeOverride, getHierarchicalOptionsFromConfig, } from './hierarchical-modes';
+export type { HierarchicalDiscoveryResult } from './hierarchical-modes';
+export { DEFAULT_TRAVERSAL_BOUNDARY, expandEnvironmentVariables, normalizePath, getPathDepth, isPathWithin, isPathAtOrAbove, checkTraversalBoundary, resolveTraversalBoundary, createBoundaryChecker, filterAllowedPaths, } from './traversal-security';

package/dist/discovery/patterns.d.ts

@@ -0,0 +1,77 @@
+import { ConfigNamingPattern } from '../types';
+/**
+ * Standard configuration file naming patterns.
+ *
+ * These patterns cover the most common conventions used by modern JavaScript tools:
+ *
+ * 1. **Modern explicit pattern** (`{app}.config.{ext}`) - Used by Vite, Next.js, etc.
+ * 2. **Short explicit pattern** (`{app}.conf.{ext}`) - Unix-style configuration
+ * 3. **Hidden directory pattern** (`.{app}/config.{ext}`) - Current CardiganTime default
+ * 4. **RC file with extension** (`.{app}rc.{ext}`) - ESLint legacy, Babel
+ * 5. **RC file without extension** (`.{app}rc`) - Prettier, npm
+ *
+ * Patterns are ordered by priority (lower = checked first). This order prefers:
+ * - Visible files over hidden files (easier to discover)
+ * - Explicit naming over implicit (clearer intent)
+ * - Modern conventions over legacy conventions
+ *
+ * @example
+ * ```typescript
+ * import { STANDARD_PATTERNS, expandPattern } from './patterns';
+ *
+ * // List all patterns for 'protokoll' app with YAML extension
+ * const files = STANDARD_PATTERNS.map(p =>
+ *   expandPattern(p.pattern, 'protokoll', 'yaml')
+ * );
+ * // ['protokoll.config.yaml', 'protokoll.conf.yaml', '.protokoll/config.yaml', ...]
+ * ```
+ */
+export declare const STANDARD_PATTERNS: ConfigNamingPattern[];
+/**
+ * Expands a naming pattern into an actual file path segment.
+ *
+ * @param pattern - The pattern template with placeholders
+ * @param appName - The application name to substitute for `{app}`
+ * @param extension - The file extension to substitute for `{ext}` (optional)
+ * @returns The expanded file path segment
+ *
+ * @example
+ * ```typescript
+ * expandPattern('{app}.config.{ext}', 'myapp', 'yaml');
+ * // Returns: 'myapp.config.yaml'
+ *
+ * expandPattern('.{app}rc', 'myapp');
+ * // Returns: '.myapprc'
+ *
+ * expandPattern('.{app}/config.{ext}', 'protokoll', 'json');
+ * // Returns: '.protokoll/config.json'
+ * ```
+ */
+export declare function expandPattern(pattern: string, appName: string, extension?: string): string;
+/**
+ * Gets all file paths to check for a given app name and extensions.
+ * Expands all standard patterns with the provided extensions.
+ *
+ * @param appName - The application name
+ * @param extensions - Array of file extensions to search for
+ * @param options - Optional configuration
+ * @param options.includeHidden - Whether to include hidden file patterns (default: true)
+ * @param options.patterns - Custom patterns to use instead of STANDARD_PATTERNS
+ * @returns Array of file paths to check, ordered by priority
+ *
+ * @example
+ * ```typescript
+ * const paths = getDiscoveryPaths('myapp', ['yaml', 'json']);
+ * // Returns (in priority order):
+ * // ['myapp.config.yaml', 'myapp.config.json', 'myapp.conf.yaml', ...]
+ * ```
+ */
+export declare function getDiscoveryPaths(appName: string, extensions: string[], options?: {
+    includeHidden?: boolean;
+    patterns?: ConfigNamingPattern[];
+}): string[];
+/**
+ * Default file extensions supported for configuration discovery.
+ * Ordered by priority (TypeScript > JavaScript > JSON > YAML).
+ */
+export declare const DEFAULT_EXTENSIONS: string[];

package/dist/discovery/root-detection.d.ts

@@ -0,0 +1,100 @@
+import { RootMarker, Logger } from '../types';
+/**
+ * Result of root detection operation.
+ */
+export interface RootDetectionResult {
+    /** Whether a root was found */
+    found: boolean;
+    /** Path to the detected root directory (if found) */
+    rootPath?: string;
+    /** The marker that triggered root detection (if found) */
+    matchedMarker?: RootMarker;
+}
+/**
+ * Checks if a directory is a project root based on the presence of root markers.
+ *
+ * @param directory - Directory to check
+ * @param markers - Root markers to look for (defaults to DEFAULT_ROOT_MARKERS)
+ * @param logger - Optional logger for debug output
+ * @returns True if the directory contains any of the root markers
+ *
+ * @example
+ * ```typescript
+ * const isRoot = await isProjectRoot('/path/to/dir');
+ * // Returns true if directory contains package.json, .git, etc.
+ * ```
+ */
+export declare function isProjectRoot(directory: string, markers?: RootMarker[], logger?: Logger): Promise<boolean>;
+/**
+ * Finds the project root by walking up from the starting directory.
+ *
+ * @param startPath - Starting directory for the search
+ * @param markers - Root markers to look for (defaults to DEFAULT_ROOT_MARKERS)
+ * @param maxDepth - Maximum number of directories to traverse (default: 20)
+ * @param logger - Optional logger for debug output
+ * @returns Detection result with the root path if found
+ *
+ * @example
+ * ```typescript
+ * const result = await findProjectRoot('/path/to/deep/nested/dir');
+ * if (result.found) {
+ *   console.log(`Project root: ${result.rootPath}`);
+ *   console.log(`Detected by: ${result.matchedMarker?.name}`);
+ * }
+ * ```
+ */
+export declare function findProjectRoot(startPath: string, markers?: RootMarker[], maxDepth?: number, logger?: Logger): Promise<RootDetectionResult>;
+/**
+ * Checks if a directory name is in the stop-at list.
+ *
+ * @param directory - Directory path to check
+ * @param stopAtNames - List of directory names to stop at
+ * @returns True if the directory should stop traversal
+ *
+ * @example
+ * ```typescript
+ * const shouldStop = shouldStopAt('/path/to/node_modules/pkg', ['node_modules', 'vendor']);
+ * // Returns false (parent 'node_modules' triggers stop, but current dir is 'pkg')
+ *
+ * const shouldStop2 = shouldStopAt('/path/to/node_modules', ['node_modules', 'vendor']);
+ * // Returns true (current directory is 'node_modules')
+ * ```
+ */
+export declare function shouldStopAt(directory: string, stopAtNames: string[]): boolean;
+/**
+ * Walks up the directory tree, checking each directory against root markers and stop conditions.
+ * Yields each directory until a stop condition is met.
+ *
+ * @param startPath - Starting directory
+ * @param options - Walk options
+ * @param logger - Optional logger
+ * @yields Directory paths from start to root/stop condition
+ *
+ * @example
+ * ```typescript
+ * for await (const dir of walkUpToRoot('/path/to/start', { maxDepth: 5 })) {
+ *   console.log(`Processing: ${dir}`);
+ * }
+ * ```
+ */
+export declare function walkUpToRoot(startPath: string, options?: {
+    maxDepth?: number;
+    rootMarkers?: RootMarker[];
+    stopAt?: string[];
+    stopAtRoot?: boolean;
+}, logger?: Logger): AsyncGenerator<string, void, undefined>;
+/**
+ * Gets all directories from start to root (or stop condition) as an array.
+ * Convenience wrapper around walkUpToRoot for when you need all directories at once.
+ *
+ * @param startPath - Starting directory
+ * @param options - Walk options
+ * @param logger - Optional logger
+ * @returns Array of directory paths
+ */
+export declare function getDirectoriesToRoot(startPath: string, options?: {
+    maxDepth?: number;
+    rootMarkers?: RootMarker[];
+    stopAt?: string[];
+    stopAtRoot?: boolean;
+}, logger?: Logger): Promise<string[]>;

package/dist/discovery/traversal-security.d.ts

@@ -0,0 +1,106 @@
+import { TraversalBoundary, TraversalCheckResult, TraversalSecurityOptions, Logger } from '../types';
+/**
+ * Default traversal boundaries.
+ * These provide safe defaults for most use cases.
+ */
+export declare const DEFAULT_TRAVERSAL_BOUNDARY: TraversalBoundary;
+/**
+ * Expands environment variable placeholders in a path.
+ * Supports $HOME, $USER, and $TMPDIR.
+ *
+ * @param pathStr - Path string with potential variable placeholders
+ * @returns Expanded path string
+ */
+export declare function expandEnvironmentVariables(pathStr: string): string;
+/**
+ * Normalizes a path for comparison.
+ * Resolves to absolute path and normalizes separators.
+ *
+ * @param pathStr - Path to normalize
+ * @returns Normalized absolute path
+ */
+export declare function normalizePath(pathStr: string): string;
+/**
+ * Calculates the depth of a path (number of segments from root).
+ *
+ * @param pathStr - Absolute path
+ * @returns Number of path segments
+ *
+ * @example
+ * ```typescript
+ * getPathDepth('/'); // 0
+ * getPathDepth('/home'); // 1
+ * getPathDepth('/home/user/project'); // 3
+ * ```
+ */
+export declare function getPathDepth(pathStr: string): number;
+/**
+ * Checks if a path is at or within a boundary path.
+ *
+ * @param checkPath - Path to check
+ * @param boundaryPath - Boundary path
+ * @returns True if checkPath is at or within boundaryPath
+ */
+export declare function isPathWithin(checkPath: string, boundaryPath: string): boolean;
+/**
+ * Checks if a path is at or above a boundary path.
+ * Used to check if traversal would go beyond soft boundaries.
+ *
+ * @param checkPath - Path to check
+ * @param boundaryPath - Boundary path
+ * @returns True if checkPath is at or above (parent of) boundaryPath
+ */
+export declare function isPathAtOrAbove(checkPath: string, boundaryPath: string): boolean;
+/**
+ * Checks if a path is allowed according to traversal boundaries.
+ *
+ * @param pathToCheck - Path to check
+ * @param boundary - Traversal boundaries to enforce
+ * @param startPath - Optional starting path for relative depth calculation
+ * @returns Check result with allowed status and reason
+ *
+ * @example
+ * ```typescript
+ * const result = checkTraversalBoundary('/etc/passwd', DEFAULT_TRAVERSAL_BOUNDARY);
+ * if (!result.allowed) {
+ *   console.error(`Access denied: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function checkTraversalBoundary(pathToCheck: string, boundary: TraversalBoundary, startPath?: string): TraversalCheckResult;
+/**
+ * Resolves traversal boundaries with defaults.
+ *
+ * @param options - User-provided options
+ * @returns Complete traversal boundary configuration
+ */
+export declare function resolveTraversalBoundary(options?: Partial<TraversalBoundary>): TraversalBoundary;
+/**
+ * Creates a boundary checker function with the specified options.
+ * Useful for repeated checks with the same configuration.
+ *
+ * @param options - Security options
+ * @param logger - Optional logger
+ * @returns Boundary checker function
+ *
+ * @example
+ * ```typescript
+ * const checker = createBoundaryChecker({ allowUnsafeTraversal: false });
+ *
+ * const result = checker('/path/to/check', '/start/path');
+ * if (!result.allowed) {
+ *   console.error(result.reason);
+ * }
+ * ```
+ */
+export declare function createBoundaryChecker(options?: TraversalSecurityOptions, logger?: Logger): (pathToCheck: string, startPath?: string) => TraversalCheckResult;
+/**
+ * Filters an array of paths to only include those within traversal boundaries.
+ *
+ * @param paths - Paths to filter
+ * @param options - Security options
+ * @param startPath - Starting path for relative depth calculation
+ * @param logger - Optional logger
+ * @returns Filtered array of allowed paths
+ */
+export declare function filterAllowedPaths(paths: string[], options?: TraversalSecurityOptions, startPath?: string, logger?: Logger): string[];

package/dist/env/errors.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * Error thrown when env var parsing fails
+ */
+export declare class EnvVarParseError extends Error {
+    readonly value: string;
+    readonly expectedType: string;
+    envVarName?: string | undefined;
+    constructor(message: string, value: string, expectedType: string, envVarName?: string | undefined);
+}
+/**
+ * Error thrown when env var validation fails
+ */
+export declare class EnvVarValidationError extends Error {
+    readonly envVarName: string;
+    readonly zodError: z.ZodError;
+    constructor(message: string, envVarName: string, zodError: z.ZodError);
+}

package/dist/env/index.d.ts

@@ -0,0 +1,7 @@
+export { toScreamingSnakeCase, generateEnvVarName, flattenFieldPath } from './naming';
+export { parseEnvVar, parseBoolean, parseNumber, parseArray } from './parser';
+export { readEnvVar, readEnvVarForField, readEnvVarsForSchema } from './reader';
+export { extractSchemaFields, getSchemaForField } from './schema-utils';
+export { resolveEnvVarConfig } from './resolver';
+export { EnvVarParseError, EnvVarValidationError } from './errors';
+export type { EnvVarNamingConfig, EnvVarName, EnvVarReadResult, EnvVarConfigSource } from './types';

package/dist/env/naming.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Convert camelCase to SCREAMING_SNAKE_CASE
+ *
+ * Examples:
+ *   planDirectory -> PLAN_DIRECTORY
+ *   apiKey -> API_KEY
+ *   maxRetryCount -> MAX_RETRY_COUNT
+ *   openaiAPIKey -> OPENAI_API_KEY
+ *   api.key -> API_KEY (dots converted to underscores)
+ *
+ * @param camelCase - The camelCase string to convert
+ * @returns The SCREAMING_SNAKE_CASE version
+ */
+export declare function toScreamingSnakeCase(camelCase: string): string;
+/**
+ * Flatten nested field path to single-underscore format
+ *
+ * Examples:
+ *   ['api', 'key'] -> 'api.key'
+ *   ['config', 'server', 'port'] -> 'config.server.port'
+ *
+ * @param path - Array of field path segments
+ * @returns Dot-notation string
+ */
+export declare function flattenFieldPath(path: string[]): string;
+/**
+ * Generate full env var name with prefix
+ *
+ * Examples:
+ *   ('riotplan', 'planDirectory') -> 'RIOTPLAN_PLAN_DIRECTORY'
+ *   ('protokoll', ['api', 'key']) -> 'PROTOKOLL_API_KEY'
+ *   ('MyApp', 'setting') -> 'MYAPP_SETTING'
+ *
+ * @param appName - Application name to use as prefix
+ * @param fieldPath - Field path as string or array
+ * @returns Full environment variable name
+ */
+export declare function generateEnvVarName(appName: string, fieldPath: string | string[]): string;

package/dist/env/parser.d.ts

@@ -0,0 +1,61 @@
+import { ZodTypeAny } from 'zod';
+/**
+ * Parse environment variable value based on Zod schema type
+ *
+ * This function inspects the Zod schema type and delegates to the appropriate
+ * parser function. It supports boolean, number, array, and string types.
+ *
+ * @param value - Raw string value from process.env
+ * @param zodType - Zod schema type to parse into
+ * @returns Parsed value of appropriate type
+ * @throws EnvVarParseError if parsing fails
+ */
+export declare function parseEnvVar(value: string | undefined, zodType: ZodTypeAny): unknown;
+/**
+ * Parse boolean from various string formats
+ *
+ * Uses the 'yn' library (https://github.com/sindresorhus/yn) which is
+ * well-maintained with 7.1M weekly downloads. Supports case-insensitive:
+ * - true/false
+ * - yes/no
+ * - y/n
+ * - 1/0
+ * - on/off
+ *
+ * Empty string is treated as false.
+ *
+ * @param value - String value to parse
+ * @returns Boolean value
+ * @throws EnvVarParseError if value cannot be parsed as boolean
+ */
+export declare function parseBoolean(value: string): boolean;
+/**
+ * Parse number from string
+ *
+ * Supports:
+ * - Integers: 42, -10, 0
+ * - Floats: 3.14, -2.7, 0.5
+ * - Scientific notation: 1e6, 1.5e3, 2e-3
+ * - Hexadecimal: 0xFF, 0x10
+ *
+ * @param value - String value to parse
+ * @returns Number value
+ * @throws EnvVarParseError if value cannot be parsed as number
+ */
+export declare function parseNumber(value: string): number;
+/**
+ * Parse array from space-separated string
+ *
+ * Example: "tag1 tag2 tag3" -> ['tag1', 'tag2', 'tag3']
+ *
+ * Each item is parsed according to the element type of the array schema.
+ * Multiple spaces are treated as a single separator.
+ * Leading and trailing whitespace is trimmed.
+ *
+ * Note: Items with spaces are not supported in this version.
+ *
+ * @param value - Space-separated string value
+ * @param elementType - Zod schema type for array elements
+ * @returns Array of parsed values
+ */
+export declare function parseArray(value: string, elementType: ZodTypeAny): unknown[];

package/dist/env/reader.d.ts

@@ -0,0 +1,45 @@
+import { EnvVarNamingConfig, EnvVarReadResult } from './types';
+/**
+ * Read environment variable value
+ *
+ * This is a simple wrapper around process.env access for testability
+ * and consistency. It does not throw errors for missing variables.
+ *
+ * @param envVarName - Full env var name (e.g., 'RIOTPLAN_PLAN_DIRECTORY')
+ * @returns Value from process.env or undefined if not set
+ */
+export declare function readEnvVar(envVarName: string): string | undefined;
+/**
+ * Read environment variable for a config field
+ *
+ * Checks custom mapping first (from envVarMap), then falls back to
+ * auto-generated name. This allows users to override the default
+ * naming convention for specific fields.
+ *
+ * Example:
+ *   readEnvVarForField('openaiApiKey', {
+ *     appName: 'riotplan',
+ *     envVarMap: { openaiApiKey: 'OPENAI_API_KEY' }
+ *   })
+ *   // Reads from OPENAI_API_KEY instead of RIOTPLAN_OPENAI_API_KEY
+ *
+ * @param fieldPath - Field path in config (e.g., 'planDirectory' or ['api', 'key'])
+ * @param config - Naming configuration with appName and envVarMap
+ * @returns Object with env var name and value
+ */
+export declare function readEnvVarForField(fieldPath: string | string[], config: EnvVarNamingConfig): EnvVarReadResult;
+/**
+ * Read all environment variables for a schema
+ *
+ * Returns a map of field paths to env var values. Only includes
+ * fields that have corresponding environment variables set.
+ * Missing env vars are not included in the result.
+ *
+ * This is useful for batch reading all env vars for a config schema
+ * at once, which can then be merged with other config sources.
+ *
+ * @param fieldPaths - All field paths from schema
+ * @param config - Naming configuration
+ * @returns Map of field paths to read results (only includes set vars)
+ */
+export declare function readEnvVarsForSchema(fieldPaths: string[], config: EnvVarNamingConfig): Map<string, EnvVarReadResult>;

package/dist/env/resolver.d.ts

@@ -0,0 +1,25 @@
+import { ZodObject, ZodRawShape, z } from 'zod';
+import { EnvVarNamingConfig, EnvVarConfigSource } from './types';
+/**
+ * Resolve configuration from environment variables
+ *
+ * This is the main entry point for the env module. It orchestrates:
+ * 1. Extracting field paths from the schema
+ * 2. Reading environment variables
+ * 3. Parsing values according to schema types
+ * 4. Validating the final config with Zod
+ *
+ * Returns null if no environment variables are found, allowing
+ * the caller to fall back to other config sources.
+ *
+ * Throws EnvVarParseError if a value cannot be parsed.
+ * Throws EnvVarValidationError if the parsed config fails Zod validation.
+ *
+ * @param schema - Zod schema defining config structure
+ * @param config - Naming configuration (appName, envVarMap)
+ * @returns Parsed config object and source information, or null if no env vars found
+ */
+export declare function resolveEnvVarConfig<T extends ZodRawShape>(schema: ZodObject<T>, config: EnvVarNamingConfig): Promise<{
+    config: z.infer<ZodObject<T>>;
+    source: EnvVarConfigSource;
+} | null>;

package/dist/env/schema-utils.d.ts

@@ -0,0 +1,33 @@
+import { ZodObject, ZodTypeAny } from 'zod';
+/**
+ * Extract all field paths from a Zod schema
+ *
+ * Handles nested objects by flattening to dot notation.
+ * This allows us to generate environment variable names for all
+ * fields in a schema, including nested ones.
+ *
+ * Example:
+ *   schema = z.object({ api: z.object({ key: z.string() }) })
+ *   extractSchemaFields(schema) => ['api', 'api.key']
+ *
+ * @param schema - Zod object schema
+ * @returns Array of field paths in dot notation
+ */
+export declare function extractSchemaFields(schema: ZodObject<any>): string[];
+/**
+ * Get Zod schema for a specific field path
+ *
+ * Navigates through nested objects using dot notation to find
+ * the schema for a specific field. This is used to determine
+ * the correct parser for each field.
+ *
+ * Example:
+ *   schema = z.object({ api: z.object({ key: z.string() }) })
+ *   getSchemaForField(schema, 'api.key') => z.string()
+ *
+ * @param schema - Zod object schema
+ * @param fieldPath - Field path in dot notation
+ * @returns Zod schema for the field
+ * @throws Error if field path is invalid
+ */
+export declare function getSchemaForField(schema: ZodObject<any>, fieldPath: string): ZodTypeAny;