@utilarium/cardigantime 0.0.24-dev.0

package/dist/cardigantime.cjs

@@ -0,0 +1,2169 @@
+'use strict';
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const yaml = require('js-yaml');
+const path = require('node:path');
+const fs = require('node:fs');
+const glob = require('glob');
+const crypto = require('node:crypto');
+const zod = require('zod');
+
+function _interopNamespaceDefault(e) {
+    const n = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } });
+    if (e) {
+        for (const k in e) {
+            if (k !== 'default') {
+                const d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: () => e[k]
+                });
+            }
+        }
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
+const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+const crypto__namespace = /*#__PURE__*/_interopNamespaceDefault(crypto);
+
+function _define_property$2(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Error thrown when CLI arguments or function parameters are invalid.
+ * 
+ * This error provides specific context about which argument failed validation
+ * and why, making it easier for users to fix their command-line usage or
+ * for developers to debug parameter issues.
+ * 
+ * @example
+ * ```typescript
+ * throw new ArgumentError('config-directory', 'Path cannot be empty');
+ * // Error message: "Path cannot be empty"
+ * // error.argument: "config-directory"
+ * ```
+ */ class ArgumentError extends Error {
+    /**
+     * Gets the name of the argument that caused this error.
+     * 
+     * @returns The argument name
+     */ get argument() {
+        return this.argumentName;
+    }
+    /**
+     * Creates a new ArgumentError instance.
+     * 
+     * @param argumentName - The name of the invalid argument
+     * @param message - Description of why the argument is invalid
+     */ constructor(argumentName, message){
+        super(`${message}`), /** The name of the argument that caused the error */ _define_property$2(this, "argumentName", void 0);
+        this.name = 'ArgumentError';
+        this.argumentName = argumentName;
+    }
+}
+
+/**
+ * Validates a configuration directory path to ensure it's safe and valid.
+ * 
+ * Performs security and safety checks including:
+ * - Non-empty string validation
+ * - Null byte injection prevention
+ * - Path length validation
+ * - Type checking
+ * 
+ * @param configDirectory - The configuration directory path to validate
+ * @param _testThrowNonArgumentError - Internal testing parameter to simulate non-ArgumentError exceptions
+ * @returns The trimmed and validated configuration directory path
+ * @throws {ArgumentError} When the directory path is invalid
+ * 
+ * @example
+ * ```typescript
+ * const validDir = validateConfigDirectory('./config'); // Returns './config'
+ * const invalidDir = validateConfigDirectory(''); // Throws ArgumentError
+ * ```
+ */ function validateConfigDirectory$2(configDirectory, _testThrowNonArgumentError) {
+    if (!configDirectory) {
+        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty');
+    }
+    if (typeof configDirectory !== 'string') {
+        throw new ArgumentError('configDirectory', 'Configuration directory must be a string');
+    }
+    const trimmed = configDirectory.trim();
+    if (trimmed.length === 0) {
+        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty or whitespace only');
+    }
+    // Check for obviously invalid paths
+    if (trimmed.includes('\0')) {
+        throw new ArgumentError('configDirectory', 'Configuration directory contains invalid null character');
+    }
+    // Validate path length (reasonable limit)
+    if (trimmed.length > 1000) {
+        throw new ArgumentError('configDirectory', 'Configuration directory path is too long (max 1000 characters)');
+    }
+    return trimmed;
+}
+/**
+ * Configures a Commander.js command with Cardigantime's CLI options.
+ * 
+ * This function adds command-line options that allow users to override
+ * configuration settings at runtime, such as:
+ * - --config-directory: Override the default configuration directory
+ * 
+ * The function validates both the command object and the options to ensure
+ * they meet the requirements for proper integration.
+ * 
+ * @template T - The Zod schema shape type for configuration validation
+ * @param command - The Commander.js Command instance to configure
+ * @param options - Cardigantime options containing defaults and schema
+ * @param _testThrowNonArgumentError - Internal testing parameter
+ * @returns Promise resolving to the configured Command instance
+ * @throws {ArgumentError} When command or options are invalid
+ * 
+ * @example
+ * ```typescript
+ * import { Command } from 'commander';
+ * import { configure } from './configure';
+ * 
+ * const program = new Command();
+ * const configuredProgram = await configure(program, options);
+ * 
+ * // Now the program accepts: --config-directory <path>
+ * ```
+ */ const configure = async (command, options, _testThrowNonArgumentError)=>{
+    // Validate the command object
+    if (!command) {
+        throw new ArgumentError('command', 'Command instance is required');
+    }
+    if (typeof command.option !== 'function') {
+        throw new ArgumentError('command', 'Command must be a valid Commander.js Command instance');
+    }
+    // Validate options
+    if (!options) {
+        throw new ArgumentError('options', 'Options object is required');
+    }
+    if (!options.defaults) {
+        throw new ArgumentError('options.defaults', 'Options must include defaults configuration');
+    }
+    if (!options.defaults.configDirectory) {
+        throw new ArgumentError('options.defaults.configDirectory', 'Default config directory is required');
+    }
+    // Validate the default config directory
+    const validatedDefaultDir = validateConfigDirectory$2(options.defaults.configDirectory);
+    let retCommand = command;
+    // Add the config directory option with validation
+    retCommand = retCommand.option('-c, --config-directory <configDirectory>', 'Configuration directory path', (value)=>{
+        try {
+            return validateConfigDirectory$2(value, _testThrowNonArgumentError);
+        } catch (error) {
+            if (error instanceof ArgumentError) {
+                // Re-throw with more specific context for CLI usage
+                throw new ArgumentError('config-directory', `Invalid --config-directory: ${error.message}`);
+            }
+            throw error;
+        }
+    }, validatedDefaultDir);
+    // Add the init config option
+    retCommand = retCommand.option('--init-config', 'Generate initial configuration file and exit');
+    // Add the check config option
+    retCommand = retCommand.option('--check-config', 'Display resolved configuration with source tracking and exit');
+    // Add the config format option
+    retCommand = retCommand.option('--config-format <format>', 'Force a specific configuration file format (yaml, json, javascript, typescript)', (value)=>{
+        const validFormats = [
+            'yaml',
+            'json',
+            'javascript',
+            'typescript'
+        ];
+        const normalized = value.toLowerCase();
+        if (!validFormats.includes(normalized)) {
+            throw new ArgumentError('config-format', `Invalid --config-format: must be one of ${validFormats.join(', ')}`);
+        }
+        return normalized;
+    });
+    return retCommand;
+};
+
+/** Version string populated at build time with git and system information */ const VERSION = '0.0.24-dev.0 (working/2325c27  2026-01-30 13:16:50 -0800) darwin arm64 v24.8.0';
+/** The program name used in CLI help and error messages */ const PROGRAM_NAME = 'cardigantime';
+/** Default file encoding for reading configuration files */ const DEFAULT_ENCODING = 'utf8';
+/** Default configuration file name to look for in the config directory */ const DEFAULT_CONFIG_FILE = 'config.yaml';
+/**
+ * Default configuration options applied when creating a Cardigantime instance.
+ * These provide sensible defaults that work for most use cases.
+ */ const DEFAULT_OPTIONS = {
+    configFile: DEFAULT_CONFIG_FILE,
+    isRequired: false,
+    encoding: DEFAULT_ENCODING,
+    pathResolution: undefined
+};
+/**
+ * Default features enabled when creating a Cardigantime instance.
+ * Currently includes only the 'config' feature for configuration file support.
+ */ const DEFAULT_FEATURES = [
+    'config'
+];
+/**
+ * Default logger implementation using console methods.
+ * Provides basic logging functionality when no custom logger is specified.
+ * The verbose and silly methods are no-ops to avoid excessive output.
+ */ const DEFAULT_LOGGER = {
+    // eslint-disable-next-line no-console
+    debug: console.debug,
+    // eslint-disable-next-line no-console
+    info: console.info,
+    // eslint-disable-next-line no-console
+    warn: console.warn,
+    // eslint-disable-next-line no-console
+    error: console.error,
+    verbose: ()=>{},
+    silly: ()=>{}
+};
+
+function _define_property$1(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Error thrown when file system operations fail
+ */ class FileSystemError extends Error {
+    /**
+     * Creates an error for when a required directory doesn't exist
+     */ static directoryNotFound(path, isRequired = false) {
+        const message = isRequired ? 'Configuration directory does not exist and is required' : 'Configuration directory not found';
+        return new FileSystemError('not_found', message, path, 'directory_access');
+    }
+    /**
+     * Creates an error for when a directory exists but isn't readable
+     */ static directoryNotReadable(path) {
+        const message = 'Configuration directory exists but is not readable';
+        return new FileSystemError('not_readable', message, path, 'directory_read');
+    }
+    /**
+     * Creates an error for directory creation failures
+     */ static directoryCreationFailed(path, originalError) {
+        const message = 'Failed to create directory: ' + (originalError.message || 'Unknown error');
+        return new FileSystemError('creation_failed', message, path, 'directory_create', originalError);
+    }
+    /**
+     * Creates an error for file operation failures (glob, etc.)
+     */ static operationFailed(operation, path, originalError) {
+        const message = `Failed to ${operation}: ${originalError.message || 'Unknown error'}`;
+        return new FileSystemError('operation_failed', message, path, operation, originalError);
+    }
+    /**
+     * Creates an error for when a file is not found
+     */ static fileNotFound(path) {
+        const message = 'Configuration file not found';
+        return new FileSystemError('not_found', message, path, 'file_read');
+    }
+    constructor(errorType, message, path, operation, originalError){
+        super(message), _define_property$1(this, "errorType", void 0), _define_property$1(this, "path", void 0), _define_property$1(this, "operation", void 0), _define_property$1(this, "originalError", void 0);
+        this.name = 'FileSystemError';
+        this.errorType = errorType;
+        this.path = path;
+        this.operation = operation;
+        this.originalError = originalError;
+    }
+}
+
+const create$1 = (params)=>{
+    // eslint-disable-next-line no-console
+    const log = params.log || console.log;
+    const exists = async (path)=>{
+        try {
+            await fs__namespace.promises.stat(path);
+            return true;
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        } catch (error) {
+            return false;
+        }
+    };
+    const isDirectory = async (path)=>{
+        const stats = await fs__namespace.promises.stat(path);
+        if (!stats.isDirectory()) {
+            log(`${path} is not a directory`);
+            return false;
+        }
+        return true;
+    };
+    const isFile = async (path)=>{
+        const stats = await fs__namespace.promises.stat(path);
+        if (!stats.isFile()) {
+            log(`${path} is not a file`);
+            return false;
+        }
+        return true;
+    };
+    const isReadable = async (path)=>{
+        try {
+            await fs__namespace.promises.access(path, fs__namespace.constants.R_OK);
+        } catch (error) {
+            log(`${path} is not readable: %s %s`, error.message, error.stack);
+            return false;
+        }
+        return true;
+    };
+    const isWritable = async (path)=>{
+        try {
+            await fs__namespace.promises.access(path, fs__namespace.constants.W_OK);
+        } catch (error) {
+            log(`${path} is not writable: %s %s`, error.message, error.stack);
+            return false;
+        }
+        return true;
+    };
+    const isFileReadable = async (path)=>{
+        return await exists(path) && await isFile(path) && await isReadable(path);
+    };
+    const isDirectoryWritable = async (path)=>{
+        return await exists(path) && await isDirectory(path) && await isWritable(path);
+    };
+    const isDirectoryReadable = async (path)=>{
+        return await exists(path) && await isDirectory(path) && await isReadable(path);
+    };
+    const createDirectory = async (path)=>{
+        try {
+            await fs__namespace.promises.mkdir(path, {
+                recursive: true
+            });
+        } catch (mkdirError) {
+            throw FileSystemError.directoryCreationFailed(path, mkdirError);
+        }
+    };
+    const readFile = async (path, encoding)=>{
+        // Validate encoding parameter
+        const validEncodings = [
+            'utf8',
+            'utf-8',
+            'ascii',
+            'latin1',
+            'base64',
+            'hex',
+            'utf16le',
+            'ucs2',
+            'ucs-2'
+        ];
+        if (!validEncodings.includes(encoding.toLowerCase())) {
+            throw new Error('Invalid encoding specified');
+        }
+        // Check file size before reading to prevent DoS
+        try {
+            const stats = await fs__namespace.promises.stat(path);
+            const maxFileSize = 10 * 1024 * 1024; // 10MB limit
+            if (stats.size > maxFileSize) {
+                throw new Error('File too large to process');
+            }
+        } catch (error) {
+            if (error.code === 'ENOENT') {
+                throw FileSystemError.fileNotFound(path);
+            }
+            throw error;
+        }
+        return await fs__namespace.promises.readFile(path, {
+            encoding: encoding
+        });
+    };
+    const writeFile = async (path, data, encoding)=>{
+        await fs__namespace.promises.writeFile(path, data, {
+            encoding: encoding
+        });
+    };
+    const forEachFileIn = async (directory, callback, options = {
+        pattern: '*.*'
+    })=>{
+        try {
+            const files = await glob.glob(options.pattern, {
+                cwd: directory,
+                nodir: true
+            });
+            for (const file of files){
+                await callback(path__namespace.join(directory, file));
+            }
+        } catch (err) {
+            throw FileSystemError.operationFailed(`glob pattern ${options.pattern}`, directory, err);
+        }
+    };
+    const readStream = async (path)=>{
+        return fs__namespace.createReadStream(path);
+    };
+    const hashFile = async (path, length)=>{
+        const file = await readFile(path, 'utf8');
+        return crypto__namespace.createHash('sha256').update(file).digest('hex').slice(0, length);
+    };
+    const listFiles = async (directory)=>{
+        return await fs__namespace.promises.readdir(directory);
+    };
+    return {
+        exists,
+        isDirectory,
+        isFile,
+        isReadable,
+        isWritable,
+        isFileReadable,
+        isDirectoryWritable,
+        isDirectoryReadable,
+        createDirectory,
+        readFile,
+        readStream,
+        writeFile,
+        forEachFileIn,
+        hashFile,
+        listFiles
+    };
+};
+
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ */ function resolveConfigPaths$1(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue$1(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue$1(value, configDir, shouldResolveArrayElements);
+            setNestedValue$1(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue$1(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ */ function isUnsafeKey$1(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+function setNestedValue$1(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    // Prevent prototype pollution via special property names
+    if (isUnsafeKey$1(lastKey) || keys.some(isUnsafeKey$1)) {
+        return;
+    }
+    const target = keys.reduce((current, key)=>{
+        // Skip if this is an unsafe key (already checked above, but defensive)
+        if (isUnsafeKey$1(key)) {
+            return current;
+        }
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue$1(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath$1(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath$1(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath$1(pathStr, configDir) {
+    if (!pathStr || path__namespace.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path__namespace.resolve(configDir, pathStr);
+}
+/**
+ * Discovers configuration directories by traversing up the directory tree.
+ * 
+ * Starting from the specified directory (or current working directory),
+ * this function searches for directories with the given name, continuing
+ * up the directory tree until it reaches the filesystem root or the
+ * maximum number of levels.
+ * 
+ * @param options Configuration options for discovery
+ * @returns Promise resolving to array of discovered configuration directories
+ * 
+ * @example
+ * ```typescript
+ * const dirs = await discoverConfigDirectories({
+ *   configDirName: '.kodrdriv',
+ *   configFileName: 'config.yaml',
+ *   maxLevels: 5
+ * });
+ * // Returns: [
+ * //   { path: '/project/.kodrdriv', level: 0 },
+ * //   { path: '/project/parent/.kodrdriv', level: 1 }
+ * // ]
+ * ```
+ */ async function discoverConfigDirectories(options) {
+    const { configDirName, maxLevels = 10, startingDir = process.cwd(), logger } = options;
+    const storage = create$1({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const discoveredDirs = [];
+    let currentDir = path__namespace.resolve(startingDir);
+    let level = 0;
+    const visited = new Set(); // Prevent infinite loops with symlinks
+    logger === null || logger === void 0 ? void 0 : logger.debug(`Starting hierarchical discovery from: ${currentDir}`);
+    while(level < maxLevels){
+        // Prevent infinite loops with symlinks
+        const realPath = path__namespace.resolve(currentDir);
+        if (visited.has(realPath)) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Already visited ${realPath}, stopping discovery`);
+            break;
+        }
+        visited.add(realPath);
+        const configDirPath = path__namespace.join(currentDir, configDirName);
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Checking for config directory: ${configDirPath}`);
+        try {
+            const exists = await storage.exists(configDirPath);
+            const isReadable = exists && await storage.isDirectoryReadable(configDirPath);
+            if (exists && isReadable) {
+                discoveredDirs.push({
+                    path: configDirPath,
+                    level
+                });
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Found config directory at level ${level}: ${configDirPath}`);
+            } else if (exists && !isReadable) {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Config directory exists but is not readable: ${configDirPath}`);
+            }
+        } catch (error) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Error checking config directory ${configDirPath}: ${error.message}`);
+        }
+        // Move up one directory level
+        const parentDir = path__namespace.dirname(currentDir);
+        // Check if we've reached the root directory
+        if (parentDir === currentDir) {
+            logger === null || logger === void 0 ? void 0 : logger.debug('Reached filesystem root, stopping discovery');
+            break;
+        }
+        currentDir = parentDir;
+        level++;
+    }
+    logger === null || logger === void 0 ? void 0 : logger.verbose(`Discovery complete. Found ${discoveredDirs.length} config directories`);
+    return discoveredDirs;
+}
+/**
+ * Tries to find a config file with alternative extensions (.yaml or .yml).
+ * 
+ * @param storage Storage instance to use for file operations
+ * @param configDir The directory containing the config file
+ * @param configFileName The base config file name (may have .yaml or .yml extension)
+ * @param logger Optional logger for debugging
+ * @returns Promise resolving to the found config file path or null if not found
+ */ async function findConfigFileWithExtension$1(storage, configDir, configFileName, logger) {
+    const configFilePath = path__namespace.join(configDir, configFileName);
+    // First try the exact filename as specified
+    const exists = await storage.exists(configFilePath);
+    if (exists) {
+        const isReadable = await storage.isFileReadable(configFilePath);
+        if (isReadable) {
+            return configFilePath;
+        }
+    }
+    // If the exact filename doesn't exist or isn't readable, try alternative extensions
+    // Only do this if the filename has a .yaml or .yml extension
+    const ext = path__namespace.extname(configFileName);
+    if (ext === '.yaml' || ext === '.yml') {
+        const baseName = path__namespace.basename(configFileName, ext);
+        const alternativeExt = ext === '.yaml' ? '.yml' : '.yaml';
+        const alternativePath = path__namespace.join(configDir, baseName + alternativeExt);
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Config file not found at ${configFilePath}, trying alternative: ${alternativePath}`);
+        const altExists = await storage.exists(alternativePath);
+        if (altExists) {
+            const altIsReadable = await storage.isFileReadable(alternativePath);
+            if (altIsReadable) {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Found config file with alternative extension: ${alternativePath}`);
+                return alternativePath;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Loads and parses a configuration file from a directory.
+ * 
+ * @param configDir Path to the configuration directory
+ * @param configFileName Name of the configuration file
+ * @param encoding File encoding
+ * @param logger Optional logger
+ * @param pathFields Optional array of field names that contain paths to be resolved
+ * @param resolvePathArray Optional array of field names whose array elements should all be resolved as paths
+ * @returns Promise resolving to parsed configuration object or null if not found
+ */ async function loadConfigFromDirectory(configDir, configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray) {
+    const storage = create$1({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    try {
+        logger === null || logger === void 0 ? void 0 : logger.verbose(`Attempting to load config file: ${path__namespace.join(configDir, configFileName)}`);
+        // Try to find the config file with alternative extensions
+        const configFilePath = await findConfigFileWithExtension$1(storage, configDir, configFileName, logger);
+        if (!configFilePath) {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file does not exist: ${path__namespace.join(configDir, configFileName)}`);
+            return null;
+        }
+        const yamlContent = await storage.readFile(configFilePath, encoding);
+        const parsedYaml = yaml__namespace.load(yamlContent);
+        if (parsedYaml !== null && typeof parsedYaml === 'object') {
+            let config = parsedYaml;
+            // Apply path resolution if configured
+            if (pathFields && pathFields.length > 0) {
+                config = resolveConfigPaths$1(config, configDir, pathFields, resolvePathArray || []);
+            }
+            logger === null || logger === void 0 ? void 0 : logger.verbose(`Successfully loaded config from: ${configFilePath}`);
+            return config;
+        } else {
+            logger === null || logger === void 0 ? void 0 : logger.debug(`Config file contains invalid format: ${configFilePath}`);
+            return null;
+        }
+    } catch (error) {
+        logger === null || logger === void 0 ? void 0 : logger.debug(`Error loading config from ${path__namespace.join(configDir, configFileName)}: ${error.message}`);
+        return null;
+    }
+}
+/**
+ * Deep merges multiple configuration objects with proper precedence and configurable array overlap behavior.
+ * 
+ * Objects are merged from lowest precedence to highest precedence,
+ * meaning that properties in later objects override properties in earlier objects.
+ * Arrays can be merged using different strategies based on the fieldOverlaps configuration.
+ * 
+ * @param configs Array of configuration objects, ordered from lowest to highest precedence
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
+ * @returns Merged configuration object
+ * 
+ * @example
+ * ```typescript
+ * const merged = deepMergeConfigs([
+ *   { api: { timeout: 5000 }, features: ['auth'] },        // Lower precedence
+ *   { api: { retries: 3 }, features: ['analytics'] },      // Higher precedence
+ * ], {
+ *   'features': 'append'  // Results in features: ['auth', 'analytics']
+ * });
+ * ```
+ */ function deepMergeConfigs(configs, fieldOverlaps) {
+    if (configs.length === 0) {
+        return {};
+    }
+    if (configs.length === 1) {
+        return {
+            ...configs[0]
+        };
+    }
+    return configs.reduce((merged, current)=>{
+        return deepMergeTwo(merged, current, fieldOverlaps);
+    }, {});
+}
+/**
+ * Deep merges two objects with proper precedence and configurable array overlap behavior.
+ * 
+ * @param target Target object (lower precedence)
+ * @param source Source object (higher precedence)
+ * @param fieldOverlaps Configuration for how array fields should be merged (optional)
+ * @param currentPath Current field path for nested merging (used internally)
+ * @returns Merged object
+ */ function deepMergeTwo(target, source, fieldOverlaps, currentPath = '') {
+    // Handle null/undefined
+    if (source == null) return target;
+    if (target == null) return source;
+    // Handle non-objects (primitives, arrays, functions, etc.)
+    if (typeof source !== 'object' || typeof target !== 'object') {
+        return source; // Source takes precedence
+    }
+    // Handle arrays with configurable overlap behavior
+    if (Array.isArray(source)) {
+        if (Array.isArray(target) && fieldOverlaps) {
+            const overlapMode = getOverlapModeForPath(currentPath, fieldOverlaps);
+            return mergeArrays(target, source, overlapMode);
+        } else {
+            // Default behavior: replace entirely
+            return [
+                ...source
+            ];
+        }
+    }
+    if (Array.isArray(target)) {
+        return source; // Source object replaces target array
+    }
+    // Deep merge objects
+    const result = {
+        ...target
+    };
+    for(const key in source){
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const fieldPath = currentPath ? `${currentPath}.${key}` : key;
+            if (Object.prototype.hasOwnProperty.call(result, key) && typeof result[key] === 'object' && typeof source[key] === 'object' && !Array.isArray(source[key]) && !Array.isArray(result[key])) {
+                // Recursively merge nested objects
+                result[key] = deepMergeTwo(result[key], source[key], fieldOverlaps, fieldPath);
+            } else {
+                // Handle arrays and primitives with overlap consideration
+                if (Array.isArray(source[key]) && Array.isArray(result[key]) && fieldOverlaps) {
+                    const overlapMode = getOverlapModeForPath(fieldPath, fieldOverlaps);
+                    result[key] = mergeArrays(result[key], source[key], overlapMode);
+                } else {
+                    // Replace with source value (higher precedence)
+                    result[key] = source[key];
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Determines the overlap mode for a given field path.
+ * 
+ * @param fieldPath The current field path (dot notation)
+ * @param fieldOverlaps Configuration mapping field paths to overlap modes
+ * @returns The overlap mode to use for this field path
+ */ function getOverlapModeForPath(fieldPath, fieldOverlaps) {
+    // Check for exact match first
+    if (fieldPath in fieldOverlaps) {
+        return fieldOverlaps[fieldPath];
+    }
+    // Check for any parent path matches (for nested configurations)
+    const pathParts = fieldPath.split('.');
+    for(let i = pathParts.length - 1; i > 0; i--){
+        const parentPath = pathParts.slice(0, i).join('.');
+        if (parentPath in fieldOverlaps) {
+            return fieldOverlaps[parentPath];
+        }
+    }
+    // Default to override if no specific configuration found
+    return 'override';
+}
+/**
+ * Merges two arrays based on the specified overlap mode.
+ * 
+ * @param targetArray The lower precedence array
+ * @param sourceArray The higher precedence array
+ * @param mode The overlap mode to use
+ * @returns The merged array
+ */ function mergeArrays(targetArray, sourceArray, mode) {
+    switch(mode){
+        case 'append':
+            return [
+                ...targetArray,
+                ...sourceArray
+            ];
+        case 'prepend':
+            return [
+                ...sourceArray,
+                ...targetArray
+            ];
+        case 'override':
+        default:
+            return [
+                ...sourceArray
+            ];
+    }
+}
+/**
+ * Loads configurations from multiple directories and merges them with proper precedence.
+ * 
+ * This is the main function for hierarchical configuration loading. It:
+ * 1. Discovers configuration directories up the directory tree
+ * 2. Loads configuration files from each discovered directory
+ * 3. Merges them with proper precedence (closer directories win)
+ * 4. Returns the merged configuration with metadata
+ * 
+ * @param options Configuration options for hierarchical loading
+ * @returns Promise resolving to hierarchical configuration result
+ * 
+ * @example
+ * ```typescript
+ * const result = await loadHierarchicalConfig({
+ *   configDirName: '.kodrdriv',
+ *   configFileName: 'config.yaml',
+ *   startingDir: '/project/subdir',
+ *   maxLevels: 5,
+ *   fieldOverlaps: {
+ *     'features': 'append',
+ *     'excludePatterns': 'prepend'
+ *   }
+ * });
+ * 
+ * // result.config contains merged configuration with custom array merging
+ * // result.discoveredDirs shows where configs were found
+ * // result.errors contains any non-fatal errors
+ * ```
+ */ async function loadHierarchicalConfig(options) {
+    const { configFileName, encoding = 'utf8', logger, pathFields, resolvePathArray, fieldOverlaps } = options;
+    logger === null || logger === void 0 ? void 0 : logger.verbose('Starting hierarchical configuration loading');
+    // Discover all configuration directories
+    const discoveredDirs = await discoverConfigDirectories(options);
+    if (discoveredDirs.length === 0) {
+        logger === null || logger === void 0 ? void 0 : logger.verbose('No configuration directories found');
+        return {
+            config: {},
+            discoveredDirs: [],
+            resolvedConfigDirs: [],
+            errors: []
+        };
+    }
+    // Load configurations from each directory
+    const configs = [];
+    const resolvedConfigDirs = [];
+    const errors = [];
+    // Sort by level (highest level first = lowest precedence first)
+    const sortedDirs = [
+        ...discoveredDirs
+    ].sort((a, b)=>b.level - a.level);
+    for (const dir of sortedDirs){
+        try {
+            const config = await loadConfigFromDirectory(dir.path, configFileName, encoding, logger, pathFields, resolvePathArray);
+            if (config !== null) {
+                configs.push(config);
+                resolvedConfigDirs.push(dir);
+                logger === null || logger === void 0 ? void 0 : logger.debug(`Loaded config from level ${dir.level}: ${dir.path}`);
+            } else {
+                logger === null || logger === void 0 ? void 0 : logger.debug(`No valid config found at level ${dir.level}: ${dir.path}`);
+            }
+        } catch (error) {
+            const errorMsg = `Failed to load config from ${dir.path}: ${error.message}`;
+            errors.push(errorMsg);
+            logger === null || logger === void 0 ? void 0 : logger.debug(errorMsg);
+        }
+    }
+    // Merge all configurations with proper precedence and configurable array overlap
+    const mergedConfig = deepMergeConfigs(configs, fieldOverlaps);
+    logger === null || logger === void 0 ? void 0 : logger.verbose(`Hierarchical loading complete. Merged ${configs.length} configurations`);
+    return {
+        config: mergedConfig,
+        discoveredDirs,
+        resolvedConfigDirs,
+        errors
+    };
+}
+
+/**
+ * Removes undefined values from an object to create a clean configuration.
+ * This is used to merge configuration sources while avoiding undefined pollution.
+ * 
+ * @param obj - The object to clean
+ * @returns A new object with undefined values filtered out
+ */ function clean(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([_, v])=>v !== undefined));
+}
+/**
+ * Resolves relative paths in configuration values relative to the configuration file's directory.
+ * 
+ * @param config - The configuration object to process
+ * @param configDir - The directory containing the configuration file
+ * @param pathFields - Array of field names (using dot notation) that contain paths to be resolved
+ * @param resolvePathArray - Array of field names whose array elements should all be resolved as paths
+ * @returns The configuration object with resolved paths
+ */ function resolveConfigPaths(config, configDir, pathFields = [], resolvePathArray = []) {
+    if (!config || typeof config !== 'object' || pathFields.length === 0) {
+        return config;
+    }
+    const resolvedConfig = {
+        ...config
+    };
+    for (const fieldPath of pathFields){
+        const value = getNestedValue(resolvedConfig, fieldPath);
+        if (value !== undefined) {
+            const shouldResolveArrayElements = resolvePathArray.includes(fieldPath);
+            const resolvedValue = resolvePathValue(value, configDir, shouldResolveArrayElements);
+            setNestedValue(resolvedConfig, fieldPath, resolvedValue);
+        }
+    }
+    return resolvedConfig;
+}
+/**
+ * Gets a nested value from an object using dot notation.
+ */ function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key)=>current === null || current === void 0 ? void 0 : current[key], obj);
+}
+/**
+ * Checks if a key is unsafe for prototype pollution prevention.
+ */ function isUnsafeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}
+/**
+ * Sets a nested value in an object using dot notation.
+ * Prevents prototype pollution by rejecting dangerous property names.
+ */ function setNestedValue(obj, path, value) {
+    const keys = path.split('.');
+    const lastKey = keys.pop();
+    // Prevent prototype pollution via special property names
+    if (isUnsafeKey(lastKey) || keys.some(isUnsafeKey)) {
+        return;
+    }
+    const target = keys.reduce((current, key)=>{
+        // Skip if this is an unsafe key (already checked above, but defensive)
+        if (isUnsafeKey(key)) {
+            return current;
+        }
+        if (!(key in current)) {
+            current[key] = {};
+        }
+        return current[key];
+    }, obj);
+    target[lastKey] = value;
+}
+/**
+ * Resolves a path value (string or array of strings) relative to the config directory.
+ */ function resolvePathValue(value, configDir, resolveArrayElements) {
+    if (typeof value === 'string') {
+        return resolveSinglePath(value, configDir);
+    }
+    if (Array.isArray(value) && resolveArrayElements) {
+        return value.map((item)=>typeof item === 'string' ? resolveSinglePath(item, configDir) : item);
+    }
+    return value;
+}
+/**
+ * Resolves a single path string relative to the config directory if it's a relative path.
+ */ function resolveSinglePath(pathStr, configDir) {
+    if (!pathStr || path__namespace.isAbsolute(pathStr)) {
+        return pathStr;
+    }
+    return path__namespace.resolve(configDir, pathStr);
+}
+/**
+ * Validates and secures a user-provided path to prevent path traversal attacks.
+ * 
+ * Security checks include:
+ * - Path traversal prevention (blocks '..')
+ * - Absolute path detection
+ * - Path separator validation
+ * 
+ * @param userPath - The user-provided path component
+ * @param basePath - The base directory to join the path with
+ * @returns The safely joined and normalized path
+ * @throws {Error} When path traversal or absolute paths are detected
+ */ function validatePath(userPath, basePath) {
+    if (!userPath || !basePath) {
+        throw new Error('Invalid path parameters');
+    }
+    const normalized = path__namespace.normalize(userPath);
+    // Prevent path traversal attacks
+    if (normalized.includes('..') || path__namespace.isAbsolute(normalized)) {
+        throw new Error('Invalid path: path traversal detected');
+    }
+    // Ensure the path doesn't start with a path separator
+    if (normalized.startsWith('/') || normalized.startsWith('\\')) {
+        throw new Error('Invalid path: absolute path detected');
+    }
+    return path__namespace.join(basePath, normalized);
+}
+/**
+ * Validates a configuration directory path for security and basic formatting.
+ * 
+ * Performs validation to prevent:
+ * - Null byte injection attacks
+ * - Extremely long paths that could cause DoS
+ * - Empty or invalid directory specifications
+ * 
+ * @param configDir - The configuration directory path to validate
+ * @returns The normalized configuration directory path
+ * @throws {Error} When the directory path is invalid or potentially dangerous
+ */ function validateConfigDirectory$1(configDir) {
+    if (!configDir) {
+        throw new Error('Configuration directory is required');
+    }
+    // Check for null bytes which could be used for path injection
+    if (configDir.includes('\0')) {
+        throw new Error('Invalid path: null byte detected');
+    }
+    const normalized = path__namespace.normalize(configDir);
+    // Basic validation - could be expanded based on requirements
+    if (normalized.length > 1000) {
+        throw new Error('Configuration directory path too long');
+    }
+    return normalized;
+}
+/**
+ * Reads configuration from files and merges it with CLI arguments.
+ * 
+ * This function implements the core configuration loading logic:
+ * 1. Validates and resolves the configuration directory path
+ * 2. Attempts to read the YAML configuration file
+ * 3. Safely parses the YAML content with security protections
+ * 4. Merges file configuration with runtime arguments
+ * 5. Returns a typed configuration object
+ * 
+ * The function handles missing files gracefully and provides detailed
+ * logging for troubleshooting configuration issues.
+ * 
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments containing potential config overrides
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise resolving to the merged and typed configuration object
+ * @throws {Error} When configuration directory is invalid or required files cannot be read
+ * 
+ * @example
+ * ```typescript
+ * const config = await read(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config']
+ * });
+ * // config is fully typed based on your schema
+ * ```
+ */ const read = async (args, options)=>{
+    var _options_defaults, _options_defaults_pathResolution;
+    const logger = options.logger;
+    const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
+    if (!rawConfigDir) {
+        throw new Error('Configuration directory must be specified');
+    }
+    const resolvedConfigDir = validateConfigDirectory$1(rawConfigDir);
+    logger.verbose('Resolved config directory');
+    let rawFileConfig = {};
+    let discoveredConfigDirs = [];
+    let resolvedConfigDirs = [];
+    // Check if hierarchical configuration discovery is enabled
+    // Use optional chaining for safety although options.features is defaulted
+    if (options.features && options.features.includes('hierarchical')) {
+        logger.verbose('Hierarchical configuration discovery enabled');
+        try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
+            // Extract the config directory name from the path for hierarchical discovery
+            const configDirName = path__namespace.basename(resolvedConfigDir);
+            const startingDir = path__namespace.dirname(resolvedConfigDir);
+            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);
+            const hierarchicalResult = await loadHierarchicalConfig({
+                configDirName,
+                configFileName: options.defaults.configFile,
+                startingDir,
+                encoding: options.defaults.encoding,
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray,
+                fieldOverlaps: options.defaults.fieldOverlaps
+            });
+            rawFileConfig = hierarchicalResult.config;
+            discoveredConfigDirs = hierarchicalResult.discoveredDirs.map((dir)=>dir.path);
+            resolvedConfigDirs = hierarchicalResult.resolvedConfigDirs.map((dir)=>dir.path);
+            if (hierarchicalResult.discoveredDirs.length > 0) {
+                logger.verbose(`Hierarchical discovery found ${hierarchicalResult.discoveredDirs.length} configuration directories`);
+                hierarchicalResult.discoveredDirs.forEach((dir)=>{
+                    logger.debug(`  Level ${dir.level}: ${dir.path}`);
+                });
+            } else {
+                logger.verbose('No configuration directories found in hierarchy');
+            }
+            if (hierarchicalResult.resolvedConfigDirs.length > 0) {
+                logger.verbose(`Found ${hierarchicalResult.resolvedConfigDirs.length} directories with actual configuration files`);
+                hierarchicalResult.resolvedConfigDirs.forEach((dir)=>{
+                    logger.debug(`  Config dir level ${dir.level}: ${dir.path}`);
+                });
+            }
+            if (hierarchicalResult.errors.length > 0) {
+                hierarchicalResult.errors.forEach((error)=>logger.warn(`Hierarchical config warning: ${error}`));
+            }
+        } catch (error) {
+            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));
+            // Fall back to single directory mode
+            logger.verbose('Falling back to single directory configuration loading');
+            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+            // Include the directory in both arrays (discovered but check if it had config)
+            discoveredConfigDirs = [
+                resolvedConfigDir
+            ];
+            if (rawFileConfig && Object.keys(rawFileConfig).length > 0) {
+                resolvedConfigDirs = [
+                    resolvedConfigDir
+                ];
+            } else {
+                resolvedConfigDirs = [];
+            }
+        }
+    } else {
+        // Use traditional single directory configuration loading
+        logger.verbose('Using single directory configuration loading');
+        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+        // Include the directory in discovered, and in resolved only if it had config
+        discoveredConfigDirs = [
+            resolvedConfigDir
+        ];
+        if (rawFileConfig && Object.keys(rawFileConfig).length > 0) {
+            resolvedConfigDirs = [
+                resolvedConfigDir
+            ];
+        } else {
+            resolvedConfigDirs = [];
+        }
+    }
+    // Apply path resolution if configured
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
+    const config = clean({
+        ...processedConfig,
+        ...{
+            configDirectory: resolvedConfigDir,
+            discoveredConfigDirs,
+            resolvedConfigDirs
+        }
+    });
+    return config;
+};
+/**
+ * Tries to find a config file with alternative extensions (.yaml or .yml).
+ * 
+ * @param storage Storage instance to use for file operations
+ * @param configDir The directory containing the config file
+ * @param configFileName The base config file name (may have .yaml or .yml extension)
+ * @param logger Logger for debugging
+ * @returns Promise resolving to the found config file path or null if not found
+ */ async function findConfigFileWithExtension(storage, configDir, configFileName, logger) {
+    // Validate the config file name to prevent path traversal
+    const configFilePath = validatePath(configFileName, configDir);
+    // First try the exact filename as specified
+    const exists = await storage.exists(configFilePath);
+    if (exists) {
+        const isReadable = await storage.isFileReadable(configFilePath);
+        if (isReadable) {
+            return configFilePath;
+        }
+    }
+    // If the exact filename doesn't exist or isn't readable, try alternative extensions
+    // Only do this if the filename has a .yaml or .yml extension
+    const ext = path__namespace.extname(configFileName);
+    if (ext === '.yaml' || ext === '.yml') {
+        const baseName = path__namespace.basename(configFileName, ext);
+        const alternativeExt = ext === '.yaml' ? '.yml' : '.yaml';
+        const alternativeFileName = baseName + alternativeExt;
+        const alternativePath = validatePath(alternativeFileName, configDir);
+        logger.debug(`Config file not found at ${configFilePath}, trying alternative: ${alternativePath}`);
+        const altExists = await storage.exists(alternativePath);
+        if (altExists) {
+            const altIsReadable = await storage.isFileReadable(alternativePath);
+            if (altIsReadable) {
+                logger.debug(`Found config file with alternative extension: ${alternativePath}`);
+                return alternativePath;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Loads configuration from a single directory (traditional mode).
+ * 
+ * @param resolvedConfigDir - The resolved configuration directory path
+ * @param options - Cardigantime options
+ * @param logger - Logger instance
+ * @returns Promise resolving to the configuration object
+ */ async function loadSingleDirectoryConfig(resolvedConfigDir, options, logger) {
+    const storage = create$1({
+        log: logger.debug
+    });
+    logger.verbose('Attempting to load config file for cardigantime');
+    let rawFileConfig = {};
+    try {
+        // Try to find the config file with alternative extensions
+        const configFilePath = await findConfigFileWithExtension(storage, resolvedConfigDir, options.defaults.configFile, logger);
+        if (!configFilePath) {
+            logger.verbose('Configuration file not found. Using empty configuration.');
+            return rawFileConfig;
+        }
+        const yamlContent = await storage.readFile(configFilePath, options.defaults.encoding);
+        // SECURITY FIX: Use safer parsing options to prevent code execution vulnerabilities
+        const parsedYaml = yaml__namespace.load(yamlContent);
+        if (parsedYaml !== null && typeof parsedYaml === 'object') {
+            rawFileConfig = parsedYaml;
+            logger.verbose('Loaded configuration file successfully');
+        } else if (parsedYaml !== null) {
+            logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);
+        }
+    } catch (error) {
+        // Re-throw security-related errors (path validation failures)
+        if (error.message && /Invalid path|path traversal|absolute path/i.test(error.message)) {
+            throw error;
+        }
+        if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {
+            logger.verbose('Configuration file not found. Using empty configuration.');
+        } else {
+            // SECURITY FIX: Don't expose internal paths or detailed error information
+            logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));
+        }
+    }
+    return rawFileConfig;
+}
+/**
+ * Recursively tracks the source of configuration values from hierarchical loading.
+ * 
+ * @param config - The configuration object to track
+ * @param sourcePath - Path to the configuration file
+ * @param level - Hierarchical level
+ * @param prefix - Current object path prefix for nested values
+ * @param tracker - The tracker object to populate
+ */ function trackConfigSources(config, sourcePath, level, prefix = '', tracker = {}) {
+    if (!config || typeof config !== 'object' || Array.isArray(config)) {
+        // For primitives and arrays, track the entire value
+        tracker[prefix] = {
+            value: config,
+            sourcePath,
+            level,
+            sourceLabel: `Level ${level}: ${path__namespace.basename(path__namespace.dirname(sourcePath))}`
+        };
+        return tracker;
+    }
+    // For objects, recursively track each property
+    for (const [key, value] of Object.entries(config)){
+        const fieldPath = prefix ? `${prefix}.${key}` : key;
+        trackConfigSources(value, sourcePath, level, fieldPath, tracker);
+    }
+    return tracker;
+}
+/**
+ * Merges multiple configuration source trackers with proper precedence.
+ * Lower level numbers have higher precedence.
+ * 
+ * @param trackers - Array of trackers from different config sources
+ * @returns Merged tracker with proper precedence
+ */ function mergeConfigTrackers(trackers) {
+    const merged = {};
+    for (const tracker of trackers){
+        for (const [key, info] of Object.entries(tracker)){
+            // Only update if we don't have this key yet, or if this source has higher precedence (lower level)
+            if (!merged[key] || info.level < merged[key].level) {
+                merged[key] = info;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Formats a configuration value for display, handling different types appropriately.
+ * 
+ * @param value - The configuration value to format
+ * @returns Formatted string representation
+ */ function formatConfigValue(value) {
+    if (value === null) return 'null';
+    if (value === undefined) return 'undefined';
+    if (typeof value === 'string') return `"${value}"`;
+    if (typeof value === 'boolean') return value.toString();
+    if (typeof value === 'number') return value.toString();
+    if (Array.isArray(value)) {
+        if (value.length === 0) return '[]';
+        if (value.length <= 3) {
+            return `[${value.map(formatConfigValue).join(', ')}]`;
+        }
+        return `[${value.slice(0, 2).map(formatConfigValue).join(', ')}, ... (${value.length} items)]`;
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value);
+        if (keys.length === 0) return '{}';
+        if (keys.length <= 2) {
+            return `{${keys.slice(0, 2).join(', ')}}`;
+        }
+        return `{${keys.slice(0, 2).join(', ')}, ... (${keys.length} keys)}`;
+    }
+    return String(value);
+}
+/**
+ * Displays configuration with source tracking in a git blame-like format.
+ * 
+ * @param config - The resolved configuration object
+ * @param tracker - Configuration source tracker
+ * @param discoveredDirs - Array of discovered configuration directories
+ * @param logger - Logger instance for output
+ */ function displayConfigWithSources(config, tracker, discoveredDirs, logger) {
+    logger.info('\n' + '='.repeat(80));
+    logger.info('CONFIGURATION SOURCE ANALYSIS');
+    logger.info('='.repeat(80));
+    // Display discovered configuration hierarchy
+    logger.info('\nDISCOVERED CONFIGURATION HIERARCHY:');
+    if (discoveredDirs.length === 0) {
+        logger.info('  No configuration directories found in hierarchy');
+    } else {
+        discoveredDirs.sort((a, b)=>a.level - b.level) // Sort by precedence (lower level = higher precedence)
+        .forEach((dir)=>{
+            const precedence = dir.level === 0 ? '(highest precedence)' : dir.level === Math.max(...discoveredDirs.map((d)=>d.level)) ? '(lowest precedence)' : '';
+            logger.info(`  Level ${dir.level}: ${dir.path} ${precedence}`);
+        });
+    }
+    // Display resolved configuration with sources
+    logger.info('\nRESOLVED CONFIGURATION WITH SOURCES:');
+    logger.info('Format: [Source] key: value\n');
+    const sortedKeys = Object.keys(tracker).sort();
+    const maxKeyLength = Math.max(...sortedKeys.map((k)=>k.length), 20);
+    const maxSourceLength = Math.max(...Object.values(tracker).map((info)=>info.sourceLabel.length), 25);
+    for (const key of sortedKeys){
+        const info = tracker[key];
+        const paddedKey = key.padEnd(maxKeyLength);
+        const paddedSource = info.sourceLabel.padEnd(maxSourceLength);
+        const formattedValue = formatConfigValue(info.value);
+        logger.info(`[${paddedSource}] ${paddedKey}: ${formattedValue}`);
+    }
+    // Display summary
+    logger.info('\n' + '-'.repeat(80));
+    logger.info('SUMMARY:');
+    logger.info(`  Total configuration keys: ${Object.keys(tracker).length}`);
+    logger.info(`  Configuration sources: ${discoveredDirs.length}`);
+    // Count values by source
+    const sourceCount = {};
+    for (const info of Object.values(tracker)){
+        sourceCount[info.sourceLabel] = (sourceCount[info.sourceLabel] || 0) + 1;
+    }
+    logger.info('  Values by source:');
+    for (const [source, count] of Object.entries(sourceCount)){
+        logger.info(`    ${source}: ${count} value(s)`);
+    }
+    logger.info('='.repeat(80));
+}
+/**
+ * Checks and displays the resolved configuration with detailed source tracking.
+ * 
+ * This function provides a git blame-like view of configuration resolution,
+ * showing which file and hierarchical level contributed each configuration value.
+ * 
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise that resolves when the configuration check is complete
+ * 
+ * @example
+ * ```typescript
+ * await checkConfig(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config', 'hierarchical']
+ * });
+ * // Outputs detailed configuration source analysis
+ * ```
+ */ const checkConfig = async (args, options)=>{
+    var _options_defaults, _options_defaults_pathResolution;
+    const logger = options.logger;
+    logger.info('Starting configuration check...');
+    const rawConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
+    if (!rawConfigDir) {
+        throw new Error('Configuration directory must be specified');
+    }
+    const resolvedConfigDir = validateConfigDirectory$1(rawConfigDir);
+    logger.verbose(`Resolved config directory: ${resolvedConfigDir}`);
+    let rawFileConfig = {};
+    let discoveredDirs = [];
+    let resolvedConfigDirs = [];
+    let tracker = {};
+    // Check if hierarchical configuration discovery is enabled
+    // Use optional chaining for safety although options.features is defaulted
+    if (options.features && options.features.includes('hierarchical')) {
+        logger.verbose('Using hierarchical configuration discovery for source tracking');
+        try {
+            var _options_defaults_pathResolution1, _options_defaults_pathResolution2;
+            // Extract the config directory name from the path for hierarchical discovery
+            const configDirName = path__namespace.basename(resolvedConfigDir);
+            const startingDir = path__namespace.dirname(resolvedConfigDir);
+            logger.debug(`Using hierarchical discovery: configDirName=${configDirName}, startingDir=${startingDir}`);
+            const hierarchicalResult = await loadHierarchicalConfig({
+                configDirName,
+                configFileName: options.defaults.configFile,
+                startingDir,
+                encoding: options.defaults.encoding,
+                logger,
+                pathFields: (_options_defaults_pathResolution1 = options.defaults.pathResolution) === null || _options_defaults_pathResolution1 === void 0 ? void 0 : _options_defaults_pathResolution1.pathFields,
+                resolvePathArray: (_options_defaults_pathResolution2 = options.defaults.pathResolution) === null || _options_defaults_pathResolution2 === void 0 ? void 0 : _options_defaults_pathResolution2.resolvePathArray,
+                fieldOverlaps: options.defaults.fieldOverlaps
+            });
+            rawFileConfig = hierarchicalResult.config;
+            discoveredDirs = hierarchicalResult.discoveredDirs;
+            resolvedConfigDirs = hierarchicalResult.resolvedConfigDirs;
+            // Build detailed source tracking by re-loading each config individually
+            const trackers = [];
+            // Sort by level (highest level first = lowest precedence first) to match merge order
+            const sortedDirs = [
+                ...resolvedConfigDirs
+            ].sort((a, b)=>b.level - a.level);
+            for (const dir of sortedDirs){
+                const storage = create$1({
+                    log: logger.debug
+                });
+                const configFilePath = path__namespace.join(dir.path, options.defaults.configFile);
+                try {
+                    const exists = await storage.exists(configFilePath);
+                    if (!exists) continue;
+                    const isReadable = await storage.isFileReadable(configFilePath);
+                    if (!isReadable) continue;
+                    const yamlContent = await storage.readFile(configFilePath, options.defaults.encoding);
+                    const parsedYaml = yaml__namespace.load(yamlContent);
+                    if (parsedYaml !== null && typeof parsedYaml === 'object') {
+                        const levelTracker = trackConfigSources(parsedYaml, configFilePath, dir.level);
+                        trackers.push(levelTracker);
+                    }
+                } catch (error) {
+                    logger.debug(`Error loading config for source tracking from ${configFilePath}: ${error.message}`);
+                }
+            }
+            // Merge trackers with proper precedence
+            tracker = mergeConfigTrackers(trackers);
+            if (hierarchicalResult.errors.length > 0) {
+                logger.warn('Configuration loading warnings:');
+                hierarchicalResult.errors.forEach((error)=>logger.warn(`  ${error}`));
+            }
+        } catch (error) {
+            logger.error('Hierarchical configuration loading failed: ' + (error.message || 'Unknown error'));
+            logger.verbose('Falling back to single directory configuration loading');
+            // Fall back to single directory mode for source tracking
+            rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+            const configFilePath = path__namespace.join(resolvedConfigDir, options.defaults.configFile);
+            tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+            // Include the directory in discovered, and in resolved only if it had config
+            discoveredDirs = [
+                {
+                    path: resolvedConfigDir,
+                    level: 0
+                }
+            ];
+            if (rawFileConfig && Object.keys(rawFileConfig).length > 0) {
+                resolvedConfigDirs = [
+                    {
+                        path: resolvedConfigDir,
+                        level: 0
+                    }
+                ];
+            } else {
+                resolvedConfigDirs = [];
+            }
+        }
+    } else {
+        // Use traditional single directory configuration loading
+        logger.verbose('Using single directory configuration loading for source tracking');
+        rawFileConfig = await loadSingleDirectoryConfig(resolvedConfigDir, options, logger);
+        const configFilePath = path__namespace.join(resolvedConfigDir, options.defaults.configFile);
+        tracker = trackConfigSources(rawFileConfig, configFilePath, 0);
+        // Include the directory in discovered, and in resolved only if it had config
+        discoveredDirs = [
+            {
+                path: resolvedConfigDir,
+                level: 0
+            }
+        ];
+        if (rawFileConfig && Object.keys(rawFileConfig).length > 0) {
+            resolvedConfigDirs = [
+                {
+                    path: resolvedConfigDir,
+                    level: 0
+                }
+            ];
+        } else {
+            resolvedConfigDirs = [];
+        }
+    }
+    // Apply path resolution if configured (this doesn't change source tracking)
+    let processedConfig = rawFileConfig;
+    if ((_options_defaults_pathResolution = options.defaults.pathResolution) === null || _options_defaults_pathResolution === void 0 ? void 0 : _options_defaults_pathResolution.pathFields) {
+        processedConfig = resolveConfigPaths(rawFileConfig, resolvedConfigDir, options.defaults.pathResolution.pathFields, options.defaults.pathResolution.resolvePathArray || []);
+    }
+    // Build final configuration including built-in values
+    const finalConfig = clean({
+        ...processedConfig,
+        configDirectory: resolvedConfigDir,
+        discoveredConfigDirs: discoveredDirs.map((dir)=>dir.path),
+        resolvedConfigDirs: resolvedConfigDirs.map((dir)=>dir.path)
+    });
+    // Add built-in configuration to tracker
+    tracker['configDirectory'] = {
+        value: resolvedConfigDir,
+        sourcePath: 'built-in',
+        level: -1,
+        sourceLabel: 'Built-in (runtime)'
+    };
+    tracker['discoveredConfigDirs'] = {
+        value: discoveredDirs.map((dir)=>dir.path),
+        sourcePath: 'built-in',
+        level: -1,
+        sourceLabel: 'Built-in (runtime)'
+    };
+    tracker['resolvedConfigDirs'] = {
+        value: resolvedConfigDirs.map((dir)=>dir.path),
+        sourcePath: 'built-in',
+        level: -1,
+        sourceLabel: 'Built-in (runtime)'
+    };
+    // Display the configuration with source information
+    displayConfigWithSources(finalConfig, tracker, discoveredDirs, logger);
+};
+
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+/**
+ * Error thrown when configuration validation fails
+ */ class ConfigurationError extends Error {
+    /**
+     * Creates a validation error for when config doesn't match the schema
+     */ static validation(message, zodError, configPath) {
+        return new ConfigurationError('validation', message, zodError, configPath);
+    }
+    /**
+     * Creates an error for when extra/unknown keys are found
+     */ static extraKeys(extraKeys, allowedKeys, configPath) {
+        const message = `Unknown configuration keys found: ${extraKeys.join(', ')}. Allowed keys are: ${allowedKeys.join(', ')}`;
+        return new ConfigurationError('extra_keys', message, {
+            extraKeys,
+            allowedKeys
+        }, configPath);
+    }
+    /**
+     * Creates a schema error for when the configuration schema itself is invalid
+     */ static schema(message, details) {
+        return new ConfigurationError('schema', message, details);
+    }
+    constructor(errorType, message, details, configPath){
+        super(message), _define_property(this, "errorType", void 0), _define_property(this, "details", void 0), _define_property(this, "configPath", void 0);
+        this.name = 'ConfigurationError';
+        this.errorType = errorType;
+        this.details = details;
+        this.configPath = configPath;
+    }
+}
+
+/**
+ * Supported configuration file formats.
+ * 
+ * - 'yaml': YAML format (.yaml, .yml)
+ * - 'json': JSON format (.json)
+ * - 'javascript': JavaScript module (.js, .mjs, .cjs)
+ * - 'typescript': TypeScript module (.ts, .mts, .cts)
+ */ var ConfigFormat = /*#__PURE__*/ function(ConfigFormat) {
+    ConfigFormat["YAML"] = "yaml";
+    ConfigFormat["JSON"] = "json";
+    ConfigFormat["JavaScript"] = "javascript";
+    ConfigFormat["TypeScript"] = "typescript";
+    return ConfigFormat;
+}({});
+/**
+ * Base Zod schema for core Cardigantime configuration.
+ * Contains the minimum required configuration fields.
+ */ const ConfigSchema = zod.z.object({
+    /** The resolved configuration directory path */ configDirectory: zod.z.string(),
+    /** Array of all directory paths that were discovered during hierarchical search */ discoveredConfigDirs: zod.z.array(zod.z.string()),
+    /** Array of directory paths that actually contained valid configuration files */ resolvedConfigDirs: zod.z.array(zod.z.string())
+});
+/**
+ * Default root markers used when none are specified.
+ * These indicate common project root boundaries.
+ */ const DEFAULT_ROOT_MARKERS = [
+    {
+        type: 'file',
+        name: 'package.json'
+    },
+    {
+        type: 'directory',
+        name: '.git'
+    },
+    {
+        type: 'file',
+        name: 'pnpm-workspace.yaml'
+    },
+    {
+        type: 'file',
+        name: 'lerna.json'
+    },
+    {
+        type: 'file',
+        name: 'nx.json'
+    },
+    {
+        type: 'file',
+        name: 'rush.json'
+    }
+];
+
+/**
+ * Recursively extracts all keys from a Zod schema in dot notation.
+ *
+ * This function traverses a Zod schema structure and builds a flat list
+ * of all possible keys, using dot notation for nested objects. It handles
+ * optional/nullable types by unwrapping them and supports arrays by
+ * introspecting their element type.
+ *
+ * Special handling for:
+ * - ZodOptional/ZodNullable: Unwraps to get the underlying type
+ * - ZodAny/ZodRecord: Accepts any keys, returns the prefix or empty array
+ * - ZodArray: Introspects the element type
+ * - ZodObject: Recursively processes all shape properties
+ *
+ * @param schema - The Zod schema to introspect
+ * @param prefix - Internal parameter for building nested key paths
+ * @returns Array of strings representing all possible keys in dot notation
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   user: z.object({
+ *     name: z.string(),
+ *     settings: z.object({ theme: z.string() })
+ *   }),
+ *   debug: z.boolean()
+ * });
+ *
+ * const keys = listZodKeys(schema);
+ * // Returns: ['user.name', 'user.settings.theme', 'debug']
+ * ```
+ */ const listZodKeys = (schema, prefix = '')=>{
+    // Handle ZodOptional and ZodNullable - unwrap to get the underlying type
+    if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+        return listZodKeys(schema.unwrap(), prefix);
+    }
+    // Handle ZodAny and ZodRecord - these accept any keys, so don't introspect
+    if (schema instanceof zod.z.ZodAny || schema instanceof zod.z.ZodRecord) {
+        return prefix ? [
+            prefix
+        ] : [];
+    }
+    if (schema instanceof zod.z.ZodArray) {
+        return listZodKeys(schema.element, prefix);
+    }
+    if (schema instanceof zod.z.ZodObject) {
+        return Object.entries(schema.shape).flatMap(([key, subschema])=>{
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            const nested = listZodKeys(subschema, fullKey);
+            return nested.length ? nested : fullKey;
+        });
+    }
+    return [];
+};
+/**
+ * Type guard to check if a value is a plain object (not array, null, or other types).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a plain object
+ */ const isPlainObject = (value)=>{
+    // Check if it's an object, not null, and not an array.
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+};
+/**
+ * Generates a list of all keys within a JavaScript object, using dot notation for nested keys.
+ * Mimics the behavior of listZodKeys but operates on plain objects.
+ * For arrays, it inspects the first element that is a plain object to determine nested keys.
+ * If an array contains no plain objects, or is empty, the key for the array itself is listed.
+ *
+ * @param obj The object to introspect.
+ * @param prefix Internal use for recursion: the prefix for the current nesting level.
+ * @returns An array of strings representing all keys in dot notation.
+ */ const listObjectKeys = (obj, prefix = '')=>{
+    const keys = new Set(); // Use Set to automatically handle duplicates from array recursion
+    for(const key in obj){
+        // Ensure it's an own property, not from the prototype chain
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            const value = obj[key];
+            const fullKey = prefix ? `${prefix}.${key}` : key;
+            if (Array.isArray(value)) {
+                // Find the first element that is a plain object to determine structure
+                const firstObjectElement = value.find(isPlainObject);
+                if (firstObjectElement) {
+                    // Recurse into the structure of the first object element found
+                    const nestedKeys = listObjectKeys(firstObjectElement, fullKey);
+                    nestedKeys.forEach((k)=>keys.add(k));
+                } else {
+                    // Array is empty or contains no plain objects, list the array key itself
+                    keys.add(fullKey);
+                }
+            } else if (isPlainObject(value)) {
+                // Recurse into nested plain objects
+                const nestedKeys = listObjectKeys(value, fullKey);
+                nestedKeys.forEach((k)=>keys.add(k));
+            } else {
+                // It's a primitive, null, or other non-plain object/array type
+                keys.add(fullKey);
+            }
+        }
+    }
+    return Array.from(keys); // Convert Set back to Array
+};
+/**
+ * Validates that the configuration object contains only keys allowed by the schema.
+ *
+ * This function prevents configuration errors by detecting typos or extra keys
+ * that aren't defined in the Zod schema. It intelligently handles:
+ * - ZodRecord types that accept arbitrary keys
+ * - Nested objects and their key structures
+ * - Arrays and their element key structures
+ *
+ * The function throws a ConfigurationError if extra keys are found, providing
+ * helpful information about what keys are allowed vs. what was found.
+ *
+ * @param mergedSources - The merged configuration object to validate
+ * @param fullSchema - The complete Zod schema including base and user schemas
+ * @param logger - Logger for error reporting
+ * @throws {ConfigurationError} When extra keys are found that aren't in the schema
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string(), age: z.number() });
+ * const config = { name: 'John', age: 30, typo: 'invalid' };
+ *
+ * checkForExtraKeys(config, schema, console);
+ * // Throws: ConfigurationError with details about 'typo' being an extra key
+ * ```
+ */ const checkForExtraKeys = (mergedSources, fullSchema, logger)=>{
+    const allowedKeys = new Set(listZodKeys(fullSchema));
+    const actualKeys = listObjectKeys(mergedSources);
+    // Filter out keys that are under a record type (ZodRecord accepts any keys)
+    const recordPrefixes = new Set();
+    // Find all prefixes that are ZodRecord types
+    const findRecordPrefixes = (schema, prefix = '')=>{
+        if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+            findRecordPrefixes(schema.unwrap(), prefix);
+            return;
+        }
+        if (schema instanceof zod.z.ZodAny || schema instanceof zod.z.ZodRecord) {
+            if (prefix) recordPrefixes.add(prefix);
+            return;
+        }
+        if (schema instanceof zod.z.ZodObject) {
+            Object.entries(schema.shape).forEach(([key, subschema])=>{
+                const fullKey = prefix ? `${prefix}.${key}` : key;
+                findRecordPrefixes(subschema, fullKey);
+            });
+        }
+    };
+    findRecordPrefixes(fullSchema);
+    // Filter out keys that are under record prefixes
+    const extraKeys = actualKeys.filter((key)=>{
+        if (allowedKeys.has(key)) return false;
+        // Check if this key is under a record prefix
+        for (const recordPrefix of recordPrefixes){
+            if (key.startsWith(recordPrefix + '.')) {
+                return false; // This key is allowed under a record
+            }
+        }
+        return true; // This is an extra key
+    });
+    if (extraKeys.length > 0) {
+        const allowedKeysArray = Array.from(allowedKeys);
+        const error = ConfigurationError.extraKeys(extraKeys, allowedKeysArray);
+        logger.error(error.message);
+        throw error;
+    }
+};
+/**
+ * Validates that a configuration directory exists and is accessible.
+ *
+ * This function performs file system checks to ensure the configuration
+ * directory can be used. It handles the isRequired flag to determine
+ * whether a missing directory should cause an error or be silently ignored.
+ *
+ * @param configDirectory - Path to the configuration directory
+ * @param isRequired - Whether the directory must exist
+ * @param logger - Optional logger for debug information
+ * @throws {FileSystemError} When the directory is required but missing or unreadable
+ */ const validateConfigDirectory = async (configDirectory, isRequired, logger)=>{
+    const storage = create$1({
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
+    });
+    const exists = await storage.exists(configDirectory);
+    if (!exists) {
+        if (isRequired) {
+            throw FileSystemError.directoryNotFound(configDirectory, true);
+        }
+    } else if (exists) {
+        const isReadable = await storage.isDirectoryReadable(configDirectory);
+        if (!isReadable) {
+            throw FileSystemError.directoryNotReadable(configDirectory);
+        }
+    }
+};
+/**
+ * Validates a configuration object against the combined Zod schema.
+ *
+ * This is the main validation function that:
+ * 1. Validates the configuration directory (if config feature enabled)
+ * 2. Combines the base ConfigSchema with user-provided schema shape
+ * 3. Checks for extra keys not defined in the schema
+ * 4. Validates all values against their schema definitions
+ * 5. Provides detailed error reporting for validation failures
+ *
+ * The validation is comprehensive and catches common configuration errors
+ * including typos, missing required fields, wrong types, and invalid values.
+ *
+ * @template T - The Zod schema shape type for configuration validation
+ * @param config - The merged configuration object to validate
+ * @param options - Cardigantime options containing schema, defaults, and logger
+ * @throws {ConfigurationError} When configuration validation fails
+ * @throws {FileSystemError} When configuration directory validation fails
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   apiKey: z.string().min(1),
+ *   timeout: z.number().positive(),
+ * });
+ *
+ * await validate(config, {
+ *   configShape: schema.shape,
+ *   defaults: { configDirectory: './config', isRequired: true },
+ *   logger: console,
+ *   features: ['config']
+ * });
+ * // Throws detailed errors if validation fails
+ * ```
+ */ const validate = async (config, options)=>{
+    const logger = options.logger;
+    if (options.features.includes('config') && config.configDirectory) {
+        await validateConfigDirectory(config.configDirectory, options.defaults.isRequired, logger);
+    }
+    // Combine the base schema with the user-provided shape
+    const fullSchema = zod.z.object({
+        ...ConfigSchema.shape,
+        ...options.configShape
+    });
+    // Validate the merged sources against the full schema
+    const validationResult = fullSchema.safeParse(config);
+    // Check for extraneous keys
+    checkForExtraKeys(config, fullSchema, logger);
+    if (!validationResult.success) {
+        const formattedError = JSON.stringify(validationResult.error.format(), null, 2);
+        logger.error('Configuration validation failed. Check logs for details.');
+        logger.silly('Configuration validation failed: %s', formattedError);
+        throw ConfigurationError.validation('Configuration validation failed. Check logs for details.', validationResult.error);
+    }
+    return;
+};
+
+/**
+ * Extracts default values from a Zod schema recursively using Zod v4's parsing mechanisms.
+ *
+ * This function leverages Zod's own parsing behavior to extract defaults rather than
+ * accessing internal properties. It works by:
+ * 1. For ZodDefault types: parsing undefined to trigger the default
+ * 2. For ZodObject types: creating a minimal object and parsing to get all defaults
+ * 3. For wrapped types: unwrapping and recursing
+ *
+ * @param schema - The Zod schema to extract defaults from
+ * @returns An object containing all default values from the schema
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   name: z.string().default('app'),
+ *   port: z.number().default(3000),
+ *   debug: z.boolean().default(false),
+ *   database: z.object({
+ *     host: z.string().default('localhost'),
+ *     port: z.number().default(5432)
+ *   })
+ * });
+ *
+ * const defaults = extractSchemaDefaults(schema);
+ * // Returns: { name: 'app', port: 3000, debug: false, database: { host: 'localhost', port: 5432 } }
+ * ```
+ */ const extractSchemaDefaults = (schema)=>{
+    // Handle ZodDefault - parse undefined to get the default value
+    if (schema instanceof zod.z.ZodDefault) {
+        try {
+            return schema.parse(undefined);
+        } catch  {
+            // If parsing undefined fails, return undefined
+            return undefined;
+        }
+    }
+    // Handle ZodOptional and ZodNullable by unwrapping
+    if (schema instanceof zod.z.ZodOptional || schema instanceof zod.z.ZodNullable) {
+        return extractSchemaDefaults(schema.unwrap());
+    }
+    // Handle ZodObject - create an object with defaults by parsing an empty object
+    if (schema instanceof zod.z.ZodObject) {
+        const defaults = {};
+        const shape = schema.shape;
+        // First, try to extract defaults from individual fields
+        for (const [key, subschema] of Object.entries(shape)){
+            const defaultValue = extractSchemaDefaults(subschema);
+            if (defaultValue !== undefined) {
+                defaults[key] = defaultValue;
+            }
+        }
+        // Then parse an empty object to trigger any schema-level defaults
+        const result = schema.safeParse({});
+        if (result.success) {
+            // Merge the parsed result with our extracted defaults
+            return {
+                ...defaults,
+                ...result.data
+            };
+        }
+        return Object.keys(defaults).length > 0 ? defaults : undefined;
+    }
+    // Handle ZodArray - return empty array as a reasonable default
+    if (schema instanceof zod.z.ZodArray) {
+        const elementDefaults = extractSchemaDefaults(schema.element);
+        return elementDefaults !== undefined ? [
+            elementDefaults
+        ] : [];
+    }
+    // Handle ZodRecord - return empty object as default
+    if (schema instanceof zod.z.ZodRecord) {
+        return {};
+    }
+    // No default available for other schema types
+    return undefined;
+};
+/**
+ * Generates a complete configuration object with all default values populated.
+ *
+ * This function combines the base ConfigSchema with a user-provided schema shape
+ * and extracts all available default values to create a complete configuration
+ * example that can be serialized to YAML.
+ *
+ * @template T - The Zod schema shape type
+ * @param configShape - The user's configuration schema shape
+ * @param configDirectory - The configuration directory to include in the defaults
+ * @returns An object containing all default values suitable for YAML serialization
+ *
+ * @example
+ * ```typescript
+ * const shape = z.object({
+ *   apiKey: z.string().describe('Your API key'),
+ *   timeout: z.number().default(5000).describe('Request timeout in milliseconds'),
+ *   features: z.array(z.string()).default(['auth', 'logging'])
+ * }).shape;
+ *
+ * const config = generateDefaultConfig(shape, './config');
+ * // Returns: { timeout: 5000, features: ['auth', 'logging'] }
+ * // Note: apiKey is not included since it has no default
+ * ```
+ */ const generateDefaultConfig = (configShape, _configDirectory)=>{
+    // Create the full schema by combining base and user schema
+    const fullSchema = zod.z.object({
+        ...configShape
+    });
+    // Extract defaults from the full schema using only explicit defaults
+    const defaults = extractSchemaDefaults(fullSchema);
+    // Don't include configDirectory in the generated file since it's runtime-specific
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { configDirectory: _, ...configDefaults } = defaults || {};
+    return configDefaults || {};
+};
+
+/**
+ * Creates a new Cardigantime instance for configuration management.
+ * 
+ * Cardigantime handles the complete configuration lifecycle including:
+ * - Reading configuration from YAML files
+ * - Validating configuration against Zod schemas
+ * - Merging CLI arguments with file configuration and defaults
+ * - Providing type-safe configuration objects
+ * 
+ * @template T - The Zod schema shape type for your configuration
+ * @param pOptions - Configuration options for the Cardigantime instance
+ * @param pOptions.defaults - Default configuration settings
+ * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)
+ * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')
+ * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)
+ * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')
+ * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)
+ * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])
+ * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)
+ * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)
+ * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger
+ * 
+ * @example
+ * ```typescript
+ * import { create } from '@utilarium/cardigantime';
+ * import { z } from 'zod';
+ * 
+ * const MyConfigSchema = z.object({
+ *   apiKey: z.string().min(1),
+ *   timeout: z.number().default(5000),
+ *   debug: z.boolean().default(false),
+ *   contextDirectories: z.array(z.string()).optional(),
+ * });
+ * 
+ * const cardigantime = create({
+ *   defaults: {
+ *     configDirectory: './config',
+ *     configFile: 'myapp.yaml',
+ *     // Resolve relative paths in contextDirectories relative to config file location
+ *     pathResolution: {
+ *       pathFields: ['contextDirectories'],
+ *       resolvePathArray: ['contextDirectories']
+ *     },
+ *     // Configure how array fields are merged in hierarchical mode
+ *     fieldOverlaps: {
+ *       'features': 'append',              // Accumulate features from all levels
+ *       'excludePatterns': 'prepend'       // Higher precedence patterns come first
+ *     }
+ *   },
+ *   configShape: MyConfigSchema.shape,
+ *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery
+ * });
+ * 
+ * // If config file is at ../config/myapp.yaml and contains:
+ * // contextDirectories: ['./context', './data']
+ * // These paths will be resolved relative to ../config/ directory
+ * ```
+ */ const create = (pOptions)=>{
+    // Validate that configDirectory is a string
+    if (!pOptions.defaults.configDirectory || typeof pOptions.defaults.configDirectory !== 'string') {
+        throw new Error(`Configuration directory must be a string, received: ${typeof pOptions.defaults.configDirectory} (${JSON.stringify(pOptions.defaults.configDirectory)})`);
+    }
+    const defaults = {
+        ...DEFAULT_OPTIONS,
+        ...pOptions.defaults
+    };
+    const features = pOptions.features || DEFAULT_FEATURES;
+    const configShape = pOptions.configShape;
+    let logger = pOptions.logger || DEFAULT_LOGGER;
+    const options = {
+        defaults,
+        features,
+        configShape,
+        logger
+    };
+    const setLogger = (pLogger)=>{
+        logger = pLogger;
+        options.logger = pLogger;
+    };
+    const generateConfig = async (configDirectory)=>{
+        const targetDir = configDirectory || options.defaults.configDirectory;
+        const configFile = options.defaults.configFile;
+        const encoding = options.defaults.encoding;
+        // Validate that targetDir is a string
+        if (!targetDir || typeof targetDir !== 'string') {
+            throw new Error(`Configuration directory must be a string, received: ${typeof targetDir} (${JSON.stringify(targetDir)})`);
+        }
+        logger.verbose(`Generating configuration file in: ${targetDir}`);
+        // Create storage utility
+        const storage = create$1({
+            log: logger.debug
+        });
+        // Ensure the target directory exists
+        const dirExists = await storage.exists(targetDir);
+        if (!dirExists) {
+            logger.info(`Creating configuration directory: ${targetDir}`);
+            try {
+                await storage.createDirectory(targetDir);
+            } catch (error) {
+                throw FileSystemError.directoryCreationFailed(targetDir, error);
+            }
+        }
+        // Check if directory is writable
+        const isWritable = await storage.isDirectoryWritable(targetDir);
+        if (!isWritable) {
+            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');
+        }
+        // Build the full config file path
+        const configFilePath = path__namespace.join(targetDir, configFile);
+        // Generate default configuration
+        logger.debug(`Generating defaults for schema with keys: ${Object.keys(options.configShape).join(', ')}`);
+        const defaultConfig = generateDefaultConfig(options.configShape);
+        logger.debug(`Generated default config: ${JSON.stringify(defaultConfig, null, 2)}`);
+        // Convert to YAML with nice formatting
+        const yamlContent = yaml__namespace.dump(defaultConfig, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: true
+        });
+        // Add header comment to the YAML file
+        const header = `# Configuration file generated by Cardigantime
+# This file contains default values for your application configuration.
+# Modify the values below to customize your application's behavior.
+#
+# For more information about Cardigantime configuration:
+# https://utilarium.github.io/cardigantime/
+
+`;
+        const finalContent = header + yamlContent;
+        // Check if config file already exists
+        const configExists = await storage.exists(configFilePath);
+        if (configExists) {
+            logger.warn(`Configuration file already exists: ${configFilePath}`);
+            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');
+            logger.info('\n' + '='.repeat(60));
+            logger.info(finalContent.trim());
+            logger.info('='.repeat(60));
+            return;
+        }
+        // Write the configuration file
+        try {
+            await storage.writeFile(configFilePath, finalContent, encoding);
+            logger.info(`Configuration file generated successfully: ${configFilePath}`);
+        } catch (error) {
+            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);
+        }
+    };
+    return {
+        setLogger,
+        configure: (command)=>configure(command, options),
+        validate: (config)=>validate(config, options),
+        read: (args)=>read(args, options),
+        generateConfig,
+        checkConfig: (args)=>checkConfig(args, options)
+    };
+};
+/**
+ * Type-safe helper for defining configuration in TypeScript/JavaScript files.
+ * 
+ * This is a simple identity function that provides type checking and
+ * autocomplete for configuration objects when using TypeScript config files.
+ * 
+ * @template T - The configuration type
+ * @param config - The configuration object
+ * @returns The same configuration object (identity function)
+ * 
+ * @example
+ * ```typescript
+ * // config.ts
+ * import { defineConfig } from '@utilarium/cardigantime';
+ * 
+ * export default defineConfig({
+ *   apiKey: process.env.API_KEY || 'default-key',
+ *   timeout: 5000,
+ *   debug: process.env.NODE_ENV === 'development'
+ * });
+ * ```
+ */ function defineConfig(config) {
+    return config;
+}
+
+exports.ArgumentError = ArgumentError;
+exports.ConfigFormat = ConfigFormat;
+exports.ConfigSchema = ConfigSchema;
+exports.ConfigurationError = ConfigurationError;
+exports.DEFAULT_ROOT_MARKERS = DEFAULT_ROOT_MARKERS;
+exports.FileSystemError = FileSystemError;
+exports.PROGRAM_NAME = PROGRAM_NAME;
+exports.VERSION = VERSION;
+exports.create = create;
+exports.defineConfig = defineConfig;
+//# sourceMappingURL=cardigantime.cjs.map