@theunwalked/cardigantime 0.0.2 → 0.0.3

package/dist/cardigantime.cjs

@@ -27,25 +27,179 @@ function _interopNamespaceDefault(e) {
 }
 
 const yaml__namespace = /*#__PURE__*/_interopNamespaceDefault(yaml);
+const path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 const fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 
-const configure = async (command, options)=>{
+/**
+ * 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"
+ * ```
+ */ 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;
+}
+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;
-    retCommand = retCommand.option('-c, --config-directory <configDirectory>', 'Config Directory', options.defaults.configDirectory);
+    // 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);
     return retCommand;
 };
 
-const DEFAULT_ENCODING = 'utf8';
-const DEFAULT_CONFIG_FILE = 'config.yaml';
-const DEFAULT_OPTIONS = {
+/** 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
 };
-const DEFAULT_FEATURES = [
+/**
+ * Default features enabled when creating a Cardigantime instance.
+ * Currently includes only the 'config' feature for configuration file support.
+ */ const DEFAULT_FEATURES = [
     'config'
 ];
-const DEFAULT_LOGGER = {
+/**
+ * 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
@@ -58,6 +212,62 @@ const DEFAULT_LOGGER = {
     silly: ()=>{}
 };
 
+/**
+ * Error thrown when file system operations fail
+ */ 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;
+}
+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;
+    }
+}
+
 // eslint-disable-next-line no-restricted-imports
 const create$1 = (params)=>{
     // eslint-disable-next-line no-console
@@ -120,10 +330,38 @@ const create$1 = (params)=>{
                 recursive: true
             });
         } catch (mkdirError) {
-            throw new Error(`Failed to create output directory ${path}: ${mkdirError.message} ${mkdirError.stack}`);
+            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
         });
@@ -145,7 +383,7 @@ const create$1 = (params)=>{
                 await callback(path.join(directory, file));
             }
         } catch (err) {
-            throw new Error(`Failed to glob pattern ${options.pattern} in ${directory}: ${err.message}`);
+            throw FileSystemError.operationFailed(`glob pattern ${options.pattern}`, directory, err);
         }
     };
     const readStream = async (path)=>{
@@ -177,35 +415,128 @@ const create$1 = (params)=>{
     };
 };
 
-function clean(obj) {
+/**
+ * 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));
 }
-const read = async (args, options)=>{
+/**
+ * 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;
     const logger = options.logger;
     const storage = create$1({
         log: logger.debug
     });
-    const resolvedConfigDir = args.configDirectory || ((_options_defaults = options.defaults) === null || _options_defaults === void 0 ? void 0 : _options_defaults.configDirectory);
-    logger.debug(`Resolved config directory: ${resolvedConfigDir}`);
-    const configFile = path.join(resolvedConfigDir, options.defaults.configFile);
-    logger.debug(`Attempting to load config file for cardigantime: ${configFile}`);
+    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.debug('Resolved config directory');
+    const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);
+    logger.debug('Attempting to load config file for cardigantime');
     let rawFileConfig = {};
     try {
         const yamlContent = await storage.readFile(configFile, 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.debug('Loaded Raw File Config for getValuesFromFile: \n\n%s\n\n', JSON.stringify(rawFileConfig, null, 2));
+            logger.debug('Loaded configuration file successfully');
         } else if (parsedYaml !== null) {
-            logger.warn(`Ignoring invalid configuration format in ${configFile} for cardigantime. Expected an object, got ${typeof parsedYaml}.`);
+            logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);
         }
     } catch (error) {
         if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {
-            logger.debug(`Configuration file not found at ${configFile} for cardigantime. Returning empty object.`);
+            logger.debug('Configuration file not found. Using empty configuration.');
         } else {
-            // Log error but don't throw, just return empty object as per the goal of just *getting* values
-            logger.error(`Failed to load or parse configuration from ${configFile} for getValuesFromFile: ${error.message}`);
+            // SECURITY FIX: Don't expose internal paths or detailed error information
+            logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));
         }
     }
     const config = clean({
@@ -217,18 +548,101 @@ const read = async (args, options)=>{
     return config;
 };
 
-// Base schema for core options
-const ConfigSchema = zod.z.object({
-    configDirectory: zod.z.string()
+/**
+ * Error thrown when configuration validation fails
+ */ 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;
+}
+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;
+    }
+}
+
+/**
+ * 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()
 });
 
-const listZodKeys = (schema, prefix = '')=>{
+/**
+ * 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 = '')=>{
     // Check if schema has unwrap method (which both ZodOptional and ZodNullable have)
     if (schema._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
         // Use type assertion to handle the unwrap method
         const unwrappable = schema;
         return listZodKeys(unwrappable.unwrap(), prefix);
     }
+    // Handle ZodAny and ZodRecord - these accept any keys, so don't introspect
+    if (schema._def && (schema._def.typeName === 'ZodAny' || schema._def.typeName === 'ZodRecord')) {
+        return prefix ? [
+            prefix
+        ] : [];
+    }
     if (schema._def && schema._def.typeName === 'ZodArray') {
         // Use type assertion to handle the element property
         const arraySchema = schema;
@@ -245,7 +659,12 @@ const listZodKeys = (schema, prefix = '')=>{
     }
     return [];
 };
-const isPlainObject = (value)=>{
+/**
+ * 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);
 };
@@ -288,59 +707,198 @@ const isPlainObject = (value)=>{
     }
     return Array.from(keys); // Convert Set back to Array
 };
-const checkForExtraKeys = (mergedSources, fullSchema, logger)=>{
+/**
+ * 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);
-    const extraKeys = actualKeys.filter((key)=>!allowedKeys.has(key));
+    // 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._def && (schema._def.typeName === 'ZodOptional' || schema._def.typeName === 'ZodNullable')) {
+            const unwrappable = schema;
+            findRecordPrefixes(unwrappable.unwrap(), prefix);
+            return;
+        }
+        if (schema._def && (schema._def.typeName === 'ZodAny' || schema._def.typeName === 'ZodRecord')) {
+            if (prefix) recordPrefixes.add(prefix);
+            return;
+        }
+        if (schema._def && schema._def.typeName === 'ZodObject') {
+            const objectSchema = schema;
+            Object.entries(objectSchema.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 allowedKeysString = Array.from(allowedKeys).join(', ');
-        const extraKeysString = extraKeys.join(', ');
-        const errorMessage = `Unknown configuration keys found: ${extraKeysString}. Allowed keys are: ${allowedKeysString}`;
-        logger.error(errorMessage);
-        throw new Error(`Configuration validation failed: Unknown keys found (${extraKeysString}). Check logs for details.`);
+        const allowedKeysArray = Array.from(allowedKeys);
+        const error = ConfigurationError.extraKeys(extraKeys, allowedKeysArray);
+        logger.error(error.message);
+        throw error;
     }
 };
-const validateConfigDirectory = async (configDirectory, isRequired)=>{
-    // eslint-disable-next-line no-console
+/**
+ * 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: console.log
+        log: (logger === null || logger === void 0 ? void 0 : logger.debug) || (()=>{})
     });
     const exists = await storage.exists(configDirectory);
     if (!exists) {
         if (isRequired) {
-            throw new Error(`Config directory does not exist and is required: ${configDirectory}`);
+            throw FileSystemError.directoryNotFound(configDirectory, true);
         }
     } else if (exists) {
         const isReadable = await storage.isDirectoryReadable(configDirectory);
         if (!isReadable) {
-            throw new Error(`Config directory exists but is not readable: ${configDirectory}`);
+            throw FileSystemError.directoryNotReadable(configDirectory);
         }
     }
 };
-const validate = async (config, options)=>{
+/**
+ * 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);
+        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
     });
-    logger.debug('Full Schema: \n\n%s\n\n', JSON.stringify(listZodKeys(fullSchema), null, 2));
     // Validate the merged sources against the full schema
     const validationResult = fullSchema.safeParse(config);
     // Check for extraneous keys
     checkForExtraKeys(config, fullSchema, logger);
     if (!validationResult.success) {
-        logger.error('Configuration validation failed: %s', JSON.stringify(validationResult.error.format(), null, 2));
-        throw new Error(`Configuration validation failed. Check logs for details.`);
+        const formattedError = JSON.stringify(validationResult.error.format(), null, 2);
+        logger.error('Configuration validation failed: %s', formattedError);
+        throw ConfigurationError.validation('Configuration validation failed. Check logs for details.', validationResult.error);
     }
     return;
 };
 
-// Make create function generic
-const create = (pOptions)=>{
+/**
+ * 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.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 '@theunwalked/cardigantime';
+ * import { z } from 'zod';
+ * 
+ * const MyConfigSchema = z.object({
+ *   apiKey: z.string().min(1),
+ *   timeout: z.number().default(5000),
+ *   debug: z.boolean().default(false),
+ * });
+ * 
+ * const cardigantime = create({
+ *   defaults: {
+ *     configDirectory: './config',
+ *     configFile: 'myapp.yaml',
+ *   },
+ *   configShape: MyConfigSchema.shape,
+ * });
+ * ```
+ */ const create = (pOptions)=>{
     const defaults = {
         ...DEFAULT_OPTIONS,
         ...pOptions.defaults
@@ -366,6 +924,9 @@ const create = (pOptions)=>{
     };
 };
 
+exports.ArgumentError = ArgumentError;
 exports.ConfigSchema = ConfigSchema;
+exports.ConfigurationError = ConfigurationError;
+exports.FileSystemError = FileSystemError;
 exports.create = create;
 //# sourceMappingURL=cardigantime.cjs.map