@theunwalked/cardigantime 0.0.1 → 0.0.3

package/dist/cardigantime.cjs

@@ -2,21 +2,910 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const configure = require('./configure.cjs');
-const constants = require('./constants.cjs');
-const read = require('./read.cjs');
-const validate = require('./validate.cjs');
-const types = require('./types.cjs');
-
-// Make create function generic
-const create = (pOptions)=>{
+const yaml = require('js-yaml');
+const path = require('path');
+const fs = require('fs');
+const glob = require('glob');
+const crypto = require('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);
+
+/**
+ * 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;
+    // 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;
+};
+
+/** 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
+};
+/**
+ * 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: ()=>{}
+};
+
+/**
+ * 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
+    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.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.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
+    };
+};
+
+/**
+ * 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));
+}
+/**
+ * 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 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 configuration file successfully');
+        } else if (parsedYaml !== null) {
+            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. 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'));
+        }
+    }
+    const config = clean({
+        ...rawFileConfig,
+        ...{
+            configDirectory: resolvedConfigDir
+        }
+    });
+    return config;
+};
+
+/**
+ * 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()
+});
+
+/**
+ * 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;
+        return listZodKeys(arraySchema.element, prefix);
+    }
+    if (schema._def && schema._def.typeName === 'ZodObject') {
+        // Use type assertion to handle the shape property
+        const objectSchema = schema;
+        return Object.entries(objectSchema.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._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 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: %s', formattedError);
+        throw ConfigurationError.validation('Configuration validation failed. Check logs for details.', validationResult.error);
+    }
+    return;
+};
+
+/**
+ * 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 = {
-        ...constants.DEFAULT_OPTIONS,
+        ...DEFAULT_OPTIONS,
         ...pOptions.defaults
     };
-    const features = pOptions.features || constants.DEFAULT_FEATURES;
+    const features = pOptions.features || DEFAULT_FEATURES;
     const configShape = pOptions.configShape;
-    let logger = pOptions.logger || constants.DEFAULT_LOGGER;
+    let logger = pOptions.logger || DEFAULT_LOGGER;
     const options = {
         defaults,
         features,
@@ -29,12 +918,15 @@ const create = (pOptions)=>{
     };
     return {
         setLogger,
-        configure: (command)=>configure.configure(command, options),
-        validate: (config)=>validate.validate(config, options),
-        read: (args)=>read.read(args, options)
+        configure: (command)=>configure(command, options),
+        validate: (config)=>validate(config, options),
+        read: (args)=>read(args, options)
     };
 };
 
-exports.ConfigSchema = types.ConfigSchema;
+exports.ArgumentError = ArgumentError;
+exports.ConfigSchema = ConfigSchema;
+exports.ConfigurationError = ConfigurationError;
+exports.FileSystemError = FileSystemError;
 exports.create = create;
 //# sourceMappingURL=cardigantime.cjs.map