@theunwalked/cardigantime 0.0.1 → 0.0.3

package/dist/error/FileSystemError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemError.js","sources":["../../src/error/FileSystemError.ts"],"sourcesContent":["/**\n * Error thrown when file system operations fail\n */\nexport class FileSystemError extends Error {\n    public readonly errorType: 'not_found' | 'not_readable' | 'not_writable' | 'creation_failed' | 'operation_failed';\n    public readonly path: string;\n    public readonly operation: string;\n    public readonly originalError?: Error;\n\n    constructor(\n        errorType: 'not_found' | 'not_readable' | 'not_writable' | 'creation_failed' | 'operation_failed',\n        message: string,\n        path: string,\n        operation: string,\n        originalError?: Error\n    ) {\n        super(message);\n        this.name = 'FileSystemError';\n        this.errorType = errorType;\n        this.path = path;\n        this.operation = operation;\n        this.originalError = originalError;\n    }\n\n    /**\n     * Creates an error for when a required directory doesn't exist\n     */\n    static directoryNotFound(path: string, isRequired: boolean = false): FileSystemError {\n        const message = isRequired\n            ? 'Configuration directory does not exist and is required'\n            : 'Configuration directory not found';\n        return new FileSystemError('not_found', message, path, 'directory_access');\n    }\n\n    /**\n     * Creates an error for when a directory exists but isn't readable\n     */\n    static directoryNotReadable(path: string): FileSystemError {\n        const message = 'Configuration directory exists but is not readable';\n        return new FileSystemError('not_readable', message, path, 'directory_read');\n    }\n\n    /**\n     * Creates an error for directory creation failures\n     */\n    static directoryCreationFailed(path: string, originalError: Error): FileSystemError {\n        const message = 'Failed to create directory: ' + (originalError.message || 'Unknown error');\n        return new FileSystemError('creation_failed', message, path, 'directory_create', originalError);\n    }\n\n    /**\n     * Creates an error for file operation failures (glob, etc.)\n     */\n    static operationFailed(operation: string, path: string, originalError: Error): FileSystemError {\n        const message = `Failed to ${operation}: ${originalError.message || 'Unknown error'}`;\n        return new FileSystemError('operation_failed', message, path, operation, originalError);\n    }\n\n    /**\n     * Creates an error for when a file is not found\n     */\n    static fileNotFound(path: string): FileSystemError {\n        const message = 'Configuration file not found';\n        return new FileSystemError('not_found', message, path, 'file_read');\n    }\n} "],"names":["FileSystemError","Error","directoryNotFound","path","isRequired","message","directoryNotReadable","directoryCreationFailed","originalError","operationFailed","operation","fileNotFound","errorType","name"],"mappings":"AAAA;;AAEC,IAAA,SAAA,gBAAA,CAAA,GAAA,EAAA,GAAA,EAAA,KAAA,EAAA;;;;;;;;;;;;;AACM,MAAMA,eAAAA,SAAwBC,KAAAA,CAAAA;AAqBjC;;AAEC,QACD,OAAOC,iBAAAA,CAAkBC,IAAY,EAAEC,UAAAA,GAAsB,KAAK,EAAmB;QACjF,MAAMC,OAAAA,GAAUD,aACV,wDAAA,GACA,mCAAA;AACN,QAAA,OAAO,IAAIJ,eAAAA,CAAgB,WAAA,EAAaK,OAAAA,EAASF,IAAAA,EAAM,kBAAA,CAAA;AAC3D;AAEA;;QAGA,OAAOG,oBAAAA,CAAqBH,IAAY,EAAmB;AACvD,QAAA,MAAME,OAAAA,GAAU,oDAAA;AAChB,QAAA,OAAO,IAAIL,eAAAA,CAAgB,cAAA,EAAgBK,OAAAA,EAASF,IAAAA,EAAM,gBAAA,CAAA;AAC9D;AAEA;;AAEC,QACD,OAAOI,uBAAAA,CAAwBJ,IAAY,EAAEK,aAAoB,EAAmB;AAChF,QAAA,MAAMH,UAAU,8BAAA,IAAkCG,aAAAA,CAAcH,OAAO,IAAI,eAAc,CAAA;AACzF,QAAA,OAAO,IAAIL,eAAAA,CAAgB,iBAAA,EAAmBK,OAAAA,EAASF,MAAM,kBAAA,EAAoBK,aAAAA,CAAAA;AACrF;AAEA;;AAEC,QACD,OAAOC,eAAAA,CAAgBC,SAAiB,EAAEP,IAAY,EAAEK,aAAoB,EAAmB;QAC3F,MAAMH,OAAAA,GAAU,CAAC,UAAU,EAAEK,SAAAA,CAAU,EAAE,EAAEF,aAAAA,CAAcH,OAAO,IAAI,eAAA,CAAA,CAAiB;AACrF,QAAA,OAAO,IAAIL,eAAAA,CAAgB,kBAAA,EAAoBK,OAAAA,EAASF,MAAMO,SAAAA,EAAWF,aAAAA,CAAAA;AAC7E;AAEA;;QAGA,OAAOG,YAAAA,CAAaR,IAAY,EAAmB;AAC/C,QAAA,MAAME,OAAAA,GAAU,8BAAA;AAChB,QAAA,OAAO,IAAIL,eAAAA,CAAgB,WAAA,EAAaK,OAAAA,EAASF,IAAAA,EAAM,WAAA,CAAA;AAC3D;IAvDA,WAAA,CACIS,SAAiG,EACjGP,OAAe,EACfF,IAAY,EACZO,SAAiB,EACjBF,aAAqB,CACvB;AACE,QAAA,KAAK,CAACH,OAAAA,CAAAA,EAZV,gBAAA,CAAA,IAAA,EAAgBO,WAAAA,EAAhB,SACA,gBAAA,CAAA,IAAA,EAAgBT,MAAAA,EAAhB,MAAA,CAAA,EACA,uBAAgBO,WAAAA,EAAhB,MAAA,CAAA,EACA,gBAAA,CAAA,IAAA,EAAgBF,iBAAhB,MAAA,CAAA;QAUI,IAAI,CAACK,IAAI,GAAG,iBAAA;QACZ,IAAI,CAACD,SAAS,GAAGA,SAAAA;QACjB,IAAI,CAACT,IAAI,GAAGA,IAAAA;QACZ,IAAI,CAACO,SAAS,GAAGA,SAAAA;QACjB,IAAI,CAACF,aAAa,GAAGA,aAAAA;AACzB;AA2CJ;;;;"}

package/dist/error/index.d.ts

@@ -0,0 +1,3 @@
+export { ArgumentError } from './ArgumentError';
+export { ConfigurationError } from './ConfigurationError';
+export { FileSystemError } from './FileSystemError';

package/dist/read.d.ts

@@ -1,3 +1,33 @@
 import { z, ZodObject } from 'zod';
 import { Args, ConfigSchema, Options } from './types';
+/**
+ * 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
+ * ```
+ */
 export declare const read: <T extends z.ZodRawShape>(args: Args, options: Options<T>) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;

package/dist/read.js

@@ -1,36 +1,129 @@
 import * as yaml from 'js-yaml';
-import path from 'path';
+import * as path from 'path';
 import { create } from './util/storage.js';
 
-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.normalize(userPath);
+    // Prevent path traversal attacks
+    if (normalized.includes('..') || path.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.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(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.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({
         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(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.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({

package/dist/read.js.map

@@ -1 +1 @@
-{"version":3,"file":"read.js","sources":["../src/read.ts"],"sourcesContent":["import * as yaml from 'js-yaml';\nimport path from 'path';\nimport { z, ZodObject } from 'zod';\nimport { Args, ConfigSchema, Options } from './types';\nimport * as Storage from './util/storage';\n\nfunction clean(obj: any) {\n    return Object.fromEntries(\n        Object.entries(obj).filter(([_, v]) => v !== undefined)\n    );\n}\n\nexport const read = async <T extends z.ZodRawShape>(args: Args, options: Options<T>): Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>> => {\n    const logger = options.logger;\n    const storage = Storage.create({ log: logger.debug });\n\n    const resolvedConfigDir = args.configDirectory || options.defaults?.configDirectory;\n    logger.debug(`Resolved config directory: ${resolvedConfigDir}`);\n\n    const configFile = path.join(resolvedConfigDir, options.defaults.configFile);\n    logger.debug(`Attempting to load config file for cardigantime: ${configFile}`);\n\n    let rawFileConfig: object = {};\n\n    try {\n        const yamlContent = await storage.readFile(configFile, options.defaults.encoding);\n        const parsedYaml = yaml.load(yamlContent);\n        if (parsedYaml !== null && typeof parsedYaml === 'object') {\n            rawFileConfig = parsedYaml;\n            logger.debug('Loaded Raw File Config for getValuesFromFile: \\n\\n%s\\n\\n', JSON.stringify(rawFileConfig, null, 2));\n        } else if (parsedYaml !== null) {\n            logger.warn(`Ignoring invalid configuration format in ${configFile} for cardigantime. Expected an object, got ${typeof parsedYaml}.`);\n        }\n    } catch (error: any) {\n        if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {\n            logger.debug(`Configuration file not found at ${configFile} for cardigantime. Returning empty object.`);\n        } else {\n            // Log error but don't throw, just return empty object as per the goal of just *getting* values\n            logger.error(`Failed to load or parse configuration from ${configFile} for getValuesFromFile: ${error.message}`);\n        }\n    }\n\n    const config: z.infer<ZodObject<T & typeof ConfigSchema.shape>> = clean({\n        ...rawFileConfig,\n        ...{\n            configDirectory: resolvedConfigDir,\n        }\n    }) as z.infer<ZodObject<T & typeof ConfigSchema.shape>>;\n\n    return config;\n}"],"names":["clean","obj","Object","fromEntries","entries","filter","_","v","undefined","read","args","options","logger","storage","Storage","log","debug","resolvedConfigDir","configDirectory","defaults","configFile","path","join","rawFileConfig","yamlContent","readFile","encoding","parsedYaml","yaml","load","JSON","stringify","warn","error","code","test","message","config"],"mappings":";;;;AAMA,SAASA,MAAMC,GAAQ,EAAA;AACnB,IAAA,OAAOC,MAAOC,CAAAA,WAAW,CACrBD,MAAAA,CAAOE,OAAO,CAACH,GAAAA,CAAAA,CAAKI,MAAM,CAAC,CAAC,CAACC,CAAGC,EAAAA,CAAAA,CAAE,GAAKA,CAAMC,KAAAA,SAAAA,CAAAA,CAAAA;AAErD;AAEO,MAAMC,IAAO,GAAA,OAAgCC,IAAYC,EAAAA,OAAAA,GAAAA;AAIVA,IAAAA,IAAAA,iBAAAA;IAHlD,MAAMC,MAAAA,GAASD,QAAQC,MAAM;IAC7B,MAAMC,OAAAA,GAAUC,MAAc,CAAC;AAAEC,QAAAA,GAAAA,EAAKH,OAAOI;AAAM,KAAA,CAAA;IAEnD,MAAMC,iBAAAA,GAAoBP,IAAKQ,CAAAA,eAAe,KAAIP,CAAAA,iBAAAA,GAAAA,QAAQQ,QAAQ,MAAA,IAAA,IAAhBR,iBAAAA,KAAAA,MAAAA,GAAAA,MAAAA,GAAAA,iBAAAA,CAAkBO,eAAe,CAAA;AACnFN,IAAAA,MAAAA,CAAOI,KAAK,CAAC,CAAC,2BAA2B,EAAEC,iBAAmB,CAAA,CAAA,CAAA;IAE9D,MAAMG,UAAAA,GAAaC,KAAKC,IAAI,CAACL,mBAAmBN,OAAQQ,CAAAA,QAAQ,CAACC,UAAU,CAAA;AAC3ER,IAAAA,MAAAA,CAAOI,KAAK,CAAC,CAAC,iDAAiD,EAAEI,UAAY,CAAA,CAAA,CAAA;AAE7E,IAAA,IAAIG,gBAAwB,EAAC;IAE7B,IAAI;QACA,MAAMC,WAAAA,GAAc,MAAMX,OAAQY,CAAAA,QAAQ,CAACL,UAAYT,EAAAA,OAAAA,CAAQQ,QAAQ,CAACO,QAAQ,CAAA;QAChF,MAAMC,UAAAA,GAAaC,IAAKC,CAAAA,IAAI,CAACL,WAAAA,CAAAA;AAC7B,QAAA,IAAIG,UAAe,KAAA,IAAA,IAAQ,OAAOA,UAAAA,KAAe,QAAU,EAAA;YACvDJ,aAAgBI,GAAAA,UAAAA;AAChBf,YAAAA,MAAAA,CAAOI,KAAK,CAAC,0DAAA,EAA4Dc,KAAKC,SAAS,CAACR,eAAe,IAAM,EAAA,CAAA,CAAA,CAAA;SAC1G,MAAA,IAAII,eAAe,IAAM,EAAA;YAC5Bf,MAAOoB,CAAAA,IAAI,CAAC,CAAC,yCAAyC,EAAEZ,UAAW,CAAA,2CAA2C,EAAE,OAAOO,UAAW,CAAA,CAAC,CAAC,CAAA;AACxI;AACJ,KAAA,CAAE,OAAOM,KAAY,EAAA;QACjB,IAAIA,KAAAA,CAAMC,IAAI,KAAK,QAAA,IAAY,0BAA0BC,IAAI,CAACF,KAAMG,CAAAA,OAAO,CAAG,EAAA;AAC1ExB,YAAAA,MAAAA,CAAOI,KAAK,CAAC,CAAC,gCAAgC,EAAEI,UAAAA,CAAW,0CAA0C,CAAC,CAAA;SACnG,MAAA;;YAEHR,MAAOqB,CAAAA,KAAK,CAAC,CAAC,2CAA2C,EAAEb,WAAW,wBAAwB,EAAEa,KAAMG,CAAAA,OAAO,CAAE,CAAA,CAAA;AACnH;AACJ;AAEA,IAAA,MAAMC,SAA4DrC,KAAM,CAAA;AACpE,QAAA,GAAGuB,aAAa;QAChB,GAAG;YACCL,eAAiBD,EAAAA;;AAEzB,KAAA,CAAA;IAEA,OAAOoB,MAAAA;AACX;;;;"}
+{"version":3,"file":"read.js","sources":["../src/read.ts"],"sourcesContent":["import * as yaml from 'js-yaml';\nimport * as path from 'path';\nimport { z, ZodObject } from 'zod';\nimport { Args, ConfigSchema, Options } from './types';\nimport * as Storage from './util/storage';\n\n/**\n * Removes undefined values from an object to create a clean configuration.\n * This is used to merge configuration sources while avoiding undefined pollution.\n * \n * @param obj - The object to clean\n * @returns A new object with undefined values filtered out\n */\nfunction clean(obj: any) {\n    return Object.fromEntries(\n        Object.entries(obj).filter(([_, v]) => v !== undefined)\n    );\n}\n\n/**\n * Validates and secures a user-provided path to prevent path traversal attacks.\n * \n * Security checks include:\n * - Path traversal prevention (blocks '..')\n * - Absolute path detection\n * - Path separator validation\n * \n * @param userPath - The user-provided path component\n * @param basePath - The base directory to join the path with\n * @returns The safely joined and normalized path\n * @throws {Error} When path traversal or absolute paths are detected\n */\nfunction validatePath(userPath: string, basePath: string): string {\n    if (!userPath || !basePath) {\n        throw new Error('Invalid path parameters');\n    }\n\n    const normalized = path.normalize(userPath);\n\n    // Prevent path traversal attacks\n    if (normalized.includes('..') || path.isAbsolute(normalized)) {\n        throw new Error('Invalid path: path traversal detected');\n    }\n\n    // Ensure the path doesn't start with a path separator\n    if (normalized.startsWith('/') || normalized.startsWith('\\\\')) {\n        throw new Error('Invalid path: absolute path detected');\n    }\n\n    return path.join(basePath, normalized);\n}\n\n/**\n * Validates a configuration directory path for security and basic formatting.\n * \n * Performs validation to prevent:\n * - Null byte injection attacks\n * - Extremely long paths that could cause DoS\n * - Empty or invalid directory specifications\n * \n * @param configDir - The configuration directory path to validate\n * @returns The normalized configuration directory path\n * @throws {Error} When the directory path is invalid or potentially dangerous\n */\nfunction validateConfigDirectory(configDir: string): string {\n    if (!configDir) {\n        throw new Error('Configuration directory is required');\n    }\n\n    // Check for null bytes which could be used for path injection\n    if (configDir.includes('\\0')) {\n        throw new Error('Invalid path: null byte detected');\n    }\n\n    const normalized = path.normalize(configDir);\n\n    // Basic validation - could be expanded based on requirements\n    if (normalized.length > 1000) {\n        throw new Error('Configuration directory path too long');\n    }\n\n    return normalized;\n}\n\n/**\n * Reads configuration from files and merges it with CLI arguments.\n * \n * This function implements the core configuration loading logic:\n * 1. Validates and resolves the configuration directory path\n * 2. Attempts to read the YAML configuration file\n * 3. Safely parses the YAML content with security protections\n * 4. Merges file configuration with runtime arguments\n * 5. Returns a typed configuration object\n * \n * The function handles missing files gracefully and provides detailed\n * logging for troubleshooting configuration issues.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param args - Parsed command-line arguments containing potential config overrides\n * @param options - Cardigantime options with defaults, schema, and logger\n * @returns Promise resolving to the merged and typed configuration object\n * @throws {Error} When configuration directory is invalid or required files cannot be read\n * \n * @example\n * ```typescript\n * const config = await read(cliArgs, {\n *   defaults: { configDirectory: './config', configFile: 'app.yaml' },\n *   configShape: MySchema.shape,\n *   logger: console,\n *   features: ['config']\n * });\n * // config is fully typed based on your schema\n * ```\n */\nexport const read = async <T extends z.ZodRawShape>(args: Args, options: Options<T>): Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>> => {\n    const logger = options.logger;\n    const storage = Storage.create({ log: logger.debug });\n\n    const rawConfigDir = args.configDirectory || options.defaults?.configDirectory;\n    if (!rawConfigDir) {\n        throw new Error('Configuration directory must be specified');\n    }\n\n    const resolvedConfigDir = validateConfigDirectory(rawConfigDir);\n    logger.debug('Resolved config directory');\n\n    const configFile = validatePath(options.defaults.configFile, resolvedConfigDir);\n    logger.debug('Attempting to load config file for cardigantime');\n\n    let rawFileConfig: object = {};\n\n    try {\n        const yamlContent = await storage.readFile(configFile, options.defaults.encoding);\n\n        // SECURITY FIX: Use safer parsing options to prevent code execution vulnerabilities\n        const parsedYaml = yaml.load(yamlContent);\n\n        if (parsedYaml !== null && typeof parsedYaml === 'object') {\n            rawFileConfig = parsedYaml;\n            logger.debug('Loaded configuration file successfully');\n        } else if (parsedYaml !== null) {\n            logger.warn('Ignoring invalid configuration format. Expected an object, got ' + typeof parsedYaml);\n        }\n    } catch (error: any) {\n        if (error.code === 'ENOENT' || /not found|no such file/i.test(error.message)) {\n            logger.debug('Configuration file not found. Using empty configuration.');\n        } else {\n            // SECURITY FIX: Don't expose internal paths or detailed error information\n            logger.error('Failed to load or parse configuration file: ' + (error.message || 'Unknown error'));\n        }\n    }\n\n    const config: z.infer<ZodObject<T & typeof ConfigSchema.shape>> = clean({\n        ...rawFileConfig,\n        ...{\n            configDirectory: resolvedConfigDir,\n        }\n    }) as z.infer<ZodObject<T & typeof ConfigSchema.shape>>;\n\n    return config;\n}"],"names":["clean","obj","Object","fromEntries","entries","filter","_","v","undefined","validatePath","userPath","basePath","Error","normalized","path","normalize","includes","isAbsolute","startsWith","join","validateConfigDirectory","configDir","length","read","args","options","logger","storage","Storage","log","debug","rawConfigDir","configDirectory","defaults","resolvedConfigDir","configFile","rawFileConfig","yamlContent","readFile","encoding","parsedYaml","yaml","load","warn","error","code","test","message","config"],"mappings":"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"}

package/dist/types.d.ts

@@ -1,40 +1,103 @@
 import { Command } from 'commander';
 import { ZodObject, z } from 'zod';
+/**
+ * Available features that can be enabled in Cardigantime.
+ * Currently supports:
+ * - 'config': Configuration file reading and validation
+ */
 export type Feature = 'config';
+/**
+ * Default configuration options for Cardigantime.
+ * These define the basic behavior of configuration loading.
+ */
 export interface DefaultOptions {
+    /** Directory path where configuration files are located */
     configDirectory: string;
+    /** Name of the configuration file (e.g., 'config.yaml', 'app.yml') */
     configFile: string;
+    /** Whether the configuration directory must exist. If true, throws error if directory doesn't exist */
     isRequired: boolean;
+    /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */
     encoding: string;
 }
+/**
+ * Complete options object passed to Cardigantime functions.
+ * Combines defaults, features, schema shape, and logger.
+ *
+ * @template T - The Zod schema shape type for configuration validation
+ */
 export interface Options<T extends z.ZodRawShape> {
+    /** Default configuration options */
     defaults: DefaultOptions;
+    /** Array of enabled features */
     features: Feature[];
+    /** Zod schema shape for validating user configuration */
     configShape: T;
+    /** Logger instance for debugging and error reporting */
     logger: Logger;
 }
+/**
+ * Logger interface for Cardigantime's internal logging.
+ * Compatible with popular logging libraries like Winston, Bunyan, etc.
+ */
 export interface Logger {
+    /** Debug-level logging for detailed troubleshooting information */
     debug: (message: string, ...args: any[]) => void;
+    /** Info-level logging for general information */
     info: (message: string, ...args: any[]) => void;
+    /** Warning-level logging for non-critical issues */
     warn: (message: string, ...args: any[]) => void;
+    /** Error-level logging for critical problems */
     error: (message: string, ...args: any[]) => void;
+    /** Verbose-level logging for extensive detail */
     verbose: (message: string, ...args: any[]) => void;
+    /** Silly-level logging for maximum detail */
     silly: (message: string, ...args: any[]) => void;
 }
+/**
+ * Main Cardigantime interface providing configuration management functionality.
+ *
+ * @template T - The Zod schema shape type for configuration validation
+ */
 export interface Cardigantime<T extends z.ZodRawShape> {
+    /**
+     * Adds Cardigantime's CLI options to a Commander.js command.
+     * This includes options like --config-directory for runtime config path overrides.
+     */
     configure: (command: Command) => Promise<Command>;
+    /** Sets a custom logger for debugging and error reporting */
     setLogger: (logger: Logger) => void;
+    /**
+     * Reads configuration from files and merges with CLI arguments.
+     * Returns a fully typed configuration object.
+     */
     read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;
+    /**
+     * Validates the merged configuration against the Zod schema.
+     * Throws ConfigurationError if validation fails.
+     */
     validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;
 }
+/**
+ * Parsed command-line arguments object, typically from Commander.js opts().
+ * Keys correspond to CLI option names with values from user input.
+ */
 export interface Args {
     [key: string]: any;
 }
+/**
+ * Base Zod schema for core Cardigantime configuration.
+ * Contains the minimum required configuration fields.
+ */
 export declare const ConfigSchema: ZodObject<{
+    /** The resolved configuration directory path */
     configDirectory: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     configDirectory: string;
 }, {
     configDirectory: string;
 }>;
+/**
+ * Base configuration type derived from the core schema.
+ */
 export type Config = z.infer<typeof ConfigSchema>;

package/dist/types.js

@@ -1,8 +1,10 @@
 import { z } from 'zod';
 
-// Base schema for core options
-const ConfigSchema = z.object({
-    configDirectory: z.string()
+/**
+ * Base Zod schema for core Cardigantime configuration.
+ * Contains the minimum required configuration fields.
+ */ const ConfigSchema = z.object({
+    /** The resolved configuration directory path */ configDirectory: z.string()
 });
 
 export { ConfigSchema };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { ZodObject } from \"zod\";\n\nimport { z } from \"zod\";\n\nexport type Feature = 'config';\n\nexport interface DefaultOptions {\n    configDirectory: string;\n    configFile: string;\n    isRequired: boolean;\n    encoding: string;\n}\n\n// Use ZodRawShape for easier merging later\nexport interface Options<T extends z.ZodRawShape> {\n    defaults: DefaultOptions,\n    features: Feature[],\n    configShape: T; // User-defined configuration shape\n    logger: Logger;\n}\n\nexport interface Logger {\n    debug: (message: string, ...args: any[]) => void;\n    info: (message: string, ...args: any[]) => void;\n    warn: (message: string, ...args: any[]) => void;\n    error: (message: string, ...args: any[]) => void;\n    verbose: (message: string, ...args: any[]) => void;\n    silly: (message: string, ...args: any[]) => void;\n}\n\n// Make interface generic\nexport interface Cardigantime<T extends z.ZodRawShape> {\n    configure: (command: Command) => Promise<Command>;\n    setLogger: (logger: Logger) => void;\n    read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;\n    validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;\n}\n\nexport interface Args {\n    [key: string]: any;\n}\n\n// Base schema for core options\nexport const ConfigSchema = z.object({\n    configDirectory: z.string(),\n});\n\nexport type Config = z.infer<typeof ConfigSchema>;\n"],"names":["ConfigSchema","z","object","configDirectory","string"],"mappings":";;AA2CA;AACaA,MAAAA,YAAAA,GAAeC,CAAEC,CAAAA,MAAM,CAAC;AACjCC,IAAAA,eAAAA,EAAiBF,EAAEG,MAAM;AAC7B,CAAG;;;;"}
+{"version":3,"file":"types.js","sources":["../src/types.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { ZodObject } from \"zod\";\n\nimport { z } from \"zod\";\n\n/**\n * Available features that can be enabled in Cardigantime.\n * Currently supports:\n * - 'config': Configuration file reading and validation\n */\nexport type Feature = 'config';\n\n/**\n * Default configuration options for Cardigantime.\n * These define the basic behavior of configuration loading.\n */\nexport interface DefaultOptions {\n    /** Directory path where configuration files are located */\n    configDirectory: string;\n    /** Name of the configuration file (e.g., 'config.yaml', 'app.yml') */\n    configFile: string;\n    /** Whether the configuration directory must exist. If true, throws error if directory doesn't exist */\n    isRequired: boolean;\n    /** File encoding for reading configuration files (e.g., 'utf8', 'ascii') */\n    encoding: string;\n}\n\n/**\n * Complete options object passed to Cardigantime functions.\n * Combines defaults, features, schema shape, and logger.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Options<T extends z.ZodRawShape> {\n    /** Default configuration options */\n    defaults: DefaultOptions,\n    /** Array of enabled features */\n    features: Feature[],\n    /** Zod schema shape for validating user configuration */\n    configShape: T;\n    /** Logger instance for debugging and error reporting */\n    logger: Logger;\n}\n\n/**\n * Logger interface for Cardigantime's internal logging.\n * Compatible with popular logging libraries like Winston, Bunyan, etc.\n */\nexport interface Logger {\n    /** Debug-level logging for detailed troubleshooting information */\n    debug: (message: string, ...args: any[]) => void;\n    /** Info-level logging for general information */\n    info: (message: string, ...args: any[]) => void;\n    /** Warning-level logging for non-critical issues */\n    warn: (message: string, ...args: any[]) => void;\n    /** Error-level logging for critical problems */\n    error: (message: string, ...args: any[]) => void;\n    /** Verbose-level logging for extensive detail */\n    verbose: (message: string, ...args: any[]) => void;\n    /** Silly-level logging for maximum detail */\n    silly: (message: string, ...args: any[]) => void;\n}\n\n/**\n * Main Cardigantime interface providing configuration management functionality.\n * \n * @template T - The Zod schema shape type for configuration validation\n */\nexport interface Cardigantime<T extends z.ZodRawShape> {\n    /** \n     * Adds Cardigantime's CLI options to a Commander.js command.\n     * This includes options like --config-directory for runtime config path overrides.\n     */\n    configure: (command: Command) => Promise<Command>;\n    /** Sets a custom logger for debugging and error reporting */\n    setLogger: (logger: Logger) => void;\n    /** \n     * Reads configuration from files and merges with CLI arguments.\n     * Returns a fully typed configuration object.\n     */\n    read: (args: Args) => Promise<z.infer<ZodObject<T & typeof ConfigSchema.shape>>>;\n    /** \n     * Validates the merged configuration against the Zod schema.\n     * Throws ConfigurationError if validation fails.\n     */\n    validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => Promise<void>;\n}\n\n/**\n * Parsed command-line arguments object, typically from Commander.js opts().\n * Keys correspond to CLI option names with values from user input.\n */\nexport interface Args {\n    [key: string]: any;\n}\n\n/**\n * Base Zod schema for core Cardigantime configuration.\n * Contains the minimum required configuration fields.\n */\nexport const ConfigSchema = z.object({\n    /** The resolved configuration directory path */\n    configDirectory: z.string(),\n});\n\n/**\n * Base configuration type derived from the core schema.\n */\nexport type Config = z.infer<typeof ConfigSchema>;\n"],"names":["ConfigSchema","z","object","configDirectory","string"],"mappings":";;AAgGA;;;AAGC,IACM,MAAMA,YAAAA,GAAeC,CAAAA,CAAEC,MAAM,CAAC;qDAEjCC,eAAAA,EAAiBF,CAAAA,CAAEG,MAAM;AAC7B,CAAA;;;;"}

package/dist/util/storage.js

@@ -1,7 +1,8 @@
 import * as fs from 'fs';
 import { glob } from 'glob';
-import path from 'path';
+import path__default from 'path';
 import crypto from 'crypto';
+import { FileSystemError } from '../error/FileSystemError.js';
 
 // eslint-disable-next-line no-restricted-imports
 const create = (params)=>{
@@ -65,10 +66,38 @@ const create = (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.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.promises.readFile(path, {
             encoding: encoding
         });
@@ -87,10 +116,10 @@ const create = (params)=>{
                 nodir: true
             });
             for (const file of files){
-                await callback(path.join(directory, file));
+                await callback(path__default.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)=>{

package/dist/util/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","sources":["../../src/util/storage.ts"],"sourcesContent":["// eslint-disable-next-line no-restricted-imports\nimport * as fs from 'fs';\nimport { glob } from 'glob';\nimport path from 'path';\nimport crypto from 'crypto';\n/**\n * This module exists to isolate filesystem operations from the rest of the codebase.\n * This makes testing easier by avoiding direct fs mocking in jest configuration.\n * \n * Additionally, abstracting storage operations allows for future flexibility - \n * this export utility may need to work with storage systems other than the local filesystem\n * (e.g. S3, Google Cloud Storage, etc).\n */\n\nexport interface Utility {\n    exists: (path: string) => Promise<boolean>;\n    isDirectory: (path: string) => Promise<boolean>;\n    isFile: (path: string) => Promise<boolean>;\n    isReadable: (path: string) => Promise<boolean>;\n    isWritable: (path: string) => Promise<boolean>;\n    isFileReadable: (path: string) => Promise<boolean>;\n    isDirectoryWritable: (path: string) => Promise<boolean>;\n    isDirectoryReadable: (path: string) => Promise<boolean>;\n    createDirectory: (path: string) => Promise<void>;\n    readFile: (path: string, encoding: string) => Promise<string>;\n    readStream: (path: string) => Promise<fs.ReadStream>;\n    writeFile: (path: string, data: string | Buffer, encoding: string) => Promise<void>;\n    forEachFileIn: (directory: string, callback: (path: string) => Promise<void>, options?: { pattern: string }) => Promise<void>;\n    hashFile: (path: string, length: number) => Promise<string>;\n    listFiles: (directory: string) => Promise<string[]>;\n}\n\nexport const create = (params: { log?: (message: string, ...args: any[]) => void }): Utility => {\n\n    // eslint-disable-next-line no-console\n    const log = params.log || console.log;\n\n    const exists = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.stat(path);\n            return true;\n            // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        } catch (error: any) {\n            return false;\n        }\n    }\n\n    const isDirectory = async (path: string): Promise<boolean> => {\n        const stats = await fs.promises.stat(path);\n        if (!stats.isDirectory()) {\n            log(`${path} is not a directory`);\n            return false;\n        }\n        return true;\n    }\n\n    const isFile = async (path: string): Promise<boolean> => {\n        const stats = await fs.promises.stat(path);\n        if (!stats.isFile()) {\n            log(`${path} is not a file`);\n            return false;\n        }\n        return true;\n    }\n\n    const isReadable = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.access(path, fs.constants.R_OK);\n        } catch (error: any) {\n            log(`${path} is not readable: %s %s`, error.message, error.stack);\n            return false;\n        }\n        return true;\n    }\n\n    const isWritable = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.access(path, fs.constants.W_OK);\n        } catch (error: any) {\n            log(`${path} is not writable: %s %s`, error.message, error.stack);\n            return false;\n        }\n        return true;\n    }\n\n    const isFileReadable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isFile(path) && await isReadable(path);\n    }\n\n    const isDirectoryWritable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isDirectory(path) && await isWritable(path);\n    }\n\n    const isDirectoryReadable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isDirectory(path) && await isReadable(path);\n    }\n\n    const createDirectory = async (path: string): Promise<void> => {\n        try {\n            await fs.promises.mkdir(path, { recursive: true });\n        } catch (mkdirError: any) {\n            throw new Error(`Failed to create output directory ${path}: ${mkdirError.message} ${mkdirError.stack}`);\n        }\n    }\n\n    const readFile = async (path: string, encoding: string): Promise<string> => {\n        return await fs.promises.readFile(path, { encoding: encoding as BufferEncoding });\n    }\n\n    const writeFile = async (path: string, data: string | Buffer, encoding: string): Promise<void> => {\n        await fs.promises.writeFile(path, data, { encoding: encoding as BufferEncoding });\n    }\n\n    const forEachFileIn = async (directory: string, callback: (file: string) => Promise<void>, options: { pattern: string | string[] } = { pattern: '*.*' }): Promise<void> => {\n        try {\n            const files = await glob(options.pattern, { cwd: directory, nodir: true });\n            for (const file of files) {\n                await callback(path.join(directory, file));\n            }\n        } catch (err: any) {\n            throw new Error(`Failed to glob pattern ${options.pattern} in ${directory}: ${err.message}`);\n        }\n    }\n\n    const readStream = async (path: string): Promise<fs.ReadStream> => {\n        return fs.createReadStream(path);\n    }\n\n    const hashFile = async (path: string, length: number): Promise<string> => {\n        const file = await readFile(path, 'utf8');\n        return crypto.createHash('sha256').update(file).digest('hex').slice(0, length);\n    }\n\n    const listFiles = async (directory: string): Promise<string[]> => {\n        return await fs.promises.readdir(directory);\n    }\n\n    return {\n        exists,\n        isDirectory,\n        isFile,\n        isReadable,\n        isWritable,\n        isFileReadable,\n        isDirectoryWritable,\n        isDirectoryReadable,\n        createDirectory,\n        readFile,\n        readStream,\n        writeFile,\n        forEachFileIn,\n        hashFile,\n        listFiles,\n    };\n}"],"names":["create","params","log","console","exists","path","fs","promises","stat","error","isDirectory","stats","isFile","isReadable","access","constants","R_OK","message","stack","isWritable","W_OK","isFileReadable","isDirectoryWritable","isDirectoryReadable","createDirectory","mkdir","recursive","mkdirError","Error","readFile","encoding","writeFile","data","forEachFileIn","directory","callback","options","pattern","files","glob","cwd","nodir","file","join","err","readStream","createReadStream","hashFile","length","crypto","createHash","update","digest","slice","listFiles","readdir"],"mappings":"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"}
+{"version":3,"file":"storage.js","sources":["../../src/util/storage.ts"],"sourcesContent":["// eslint-disable-next-line no-restricted-imports\nimport * as fs from 'fs';\nimport { glob } from 'glob';\nimport path from 'path';\nimport crypto from 'crypto';\nimport { FileSystemError } from '../error/FileSystemError';\n/**\n * This module exists to isolate filesystem operations from the rest of the codebase.\n * This makes testing easier by avoiding direct fs mocking in jest configuration.\n * \n * Additionally, abstracting storage operations allows for future flexibility - \n * this export utility may need to work with storage systems other than the local filesystem\n * (e.g. S3, Google Cloud Storage, etc).\n */\n\nexport interface Utility {\n    exists: (path: string) => Promise<boolean>;\n    isDirectory: (path: string) => Promise<boolean>;\n    isFile: (path: string) => Promise<boolean>;\n    isReadable: (path: string) => Promise<boolean>;\n    isWritable: (path: string) => Promise<boolean>;\n    isFileReadable: (path: string) => Promise<boolean>;\n    isDirectoryWritable: (path: string) => Promise<boolean>;\n    isDirectoryReadable: (path: string) => Promise<boolean>;\n    createDirectory: (path: string) => Promise<void>;\n    readFile: (path: string, encoding: string) => Promise<string>;\n    readStream: (path: string) => Promise<fs.ReadStream>;\n    writeFile: (path: string, data: string | Buffer, encoding: string) => Promise<void>;\n    forEachFileIn: (directory: string, callback: (path: string) => Promise<void>, options?: { pattern: string }) => Promise<void>;\n    hashFile: (path: string, length: number) => Promise<string>;\n    listFiles: (directory: string) => Promise<string[]>;\n}\n\nexport const create = (params: { log?: (message: string, ...args: any[]) => void }): Utility => {\n\n    // eslint-disable-next-line no-console\n    const log = params.log || console.log;\n\n    const exists = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.stat(path);\n            return true;\n            // eslint-disable-next-line @typescript-eslint/no-unused-vars\n        } catch (error: any) {\n            return false;\n        }\n    }\n\n    const isDirectory = async (path: string): Promise<boolean> => {\n        const stats = await fs.promises.stat(path);\n        if (!stats.isDirectory()) {\n            log(`${path} is not a directory`);\n            return false;\n        }\n        return true;\n    }\n\n    const isFile = async (path: string): Promise<boolean> => {\n        const stats = await fs.promises.stat(path);\n        if (!stats.isFile()) {\n            log(`${path} is not a file`);\n            return false;\n        }\n        return true;\n    }\n\n    const isReadable = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.access(path, fs.constants.R_OK);\n        } catch (error: any) {\n            log(`${path} is not readable: %s %s`, error.message, error.stack);\n            return false;\n        }\n        return true;\n    }\n\n    const isWritable = async (path: string): Promise<boolean> => {\n        try {\n            await fs.promises.access(path, fs.constants.W_OK);\n        } catch (error: any) {\n            log(`${path} is not writable: %s %s`, error.message, error.stack);\n            return false;\n        }\n        return true;\n    }\n\n    const isFileReadable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isFile(path) && await isReadable(path);\n    }\n\n    const isDirectoryWritable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isDirectory(path) && await isWritable(path);\n    }\n\n    const isDirectoryReadable = async (path: string): Promise<boolean> => {\n        return await exists(path) && await isDirectory(path) && await isReadable(path);\n    }\n\n    const createDirectory = async (path: string): Promise<void> => {\n        try {\n            await fs.promises.mkdir(path, { recursive: true });\n        } catch (mkdirError: any) {\n            throw FileSystemError.directoryCreationFailed(path, mkdirError);\n        }\n    }\n\n    const readFile = async (path: string, encoding: string): Promise<string> => {\n        // Validate encoding parameter\n        const validEncodings = ['utf8', 'utf-8', 'ascii', 'latin1', 'base64', 'hex', 'utf16le', 'ucs2', 'ucs-2'];\n        if (!validEncodings.includes(encoding.toLowerCase())) {\n            throw new Error('Invalid encoding specified');\n        }\n\n        // Check file size before reading to prevent DoS\n        try {\n            const stats = await fs.promises.stat(path);\n            const maxFileSize = 10 * 1024 * 1024; // 10MB limit\n            if (stats.size > maxFileSize) {\n                throw new Error('File too large to process');\n            }\n        } catch (error: any) {\n            if (error.code === 'ENOENT') {\n                throw FileSystemError.fileNotFound(path);\n            }\n            throw error;\n        }\n\n        return await fs.promises.readFile(path, { encoding: encoding as BufferEncoding });\n    }\n\n    const writeFile = async (path: string, data: string | Buffer, encoding: string): Promise<void> => {\n        await fs.promises.writeFile(path, data, { encoding: encoding as BufferEncoding });\n    }\n\n    const forEachFileIn = async (directory: string, callback: (file: string) => Promise<void>, options: { pattern: string | string[] } = { pattern: '*.*' }): Promise<void> => {\n        try {\n            const files = await glob(options.pattern, { cwd: directory, nodir: true });\n            for (const file of files) {\n                await callback(path.join(directory, file));\n            }\n        } catch (err: any) {\n            throw FileSystemError.operationFailed(`glob pattern ${options.pattern}`, directory, err);\n        }\n    }\n\n    const readStream = async (path: string): Promise<fs.ReadStream> => {\n        return fs.createReadStream(path);\n    }\n\n    const hashFile = async (path: string, length: number): Promise<string> => {\n        const file = await readFile(path, 'utf8');\n        return crypto.createHash('sha256').update(file).digest('hex').slice(0, length);\n    }\n\n    const listFiles = async (directory: string): Promise<string[]> => {\n        return await fs.promises.readdir(directory);\n    }\n\n    return {\n        exists,\n        isDirectory,\n        isFile,\n        isReadable,\n        isWritable,\n        isFileReadable,\n        isDirectoryWritable,\n        isDirectoryReadable,\n        createDirectory,\n        readFile,\n        readStream,\n        writeFile,\n        forEachFileIn,\n        hashFile,\n        listFiles,\n    };\n}"],"names":["create","params","log","console","exists","path","fs","promises","stat","error","isDirectory","stats","isFile","isReadable","access","constants","R_OK","message","stack","isWritable","W_OK","isFileReadable","isDirectoryWritable","isDirectoryReadable","createDirectory","mkdir","recursive","mkdirError","FileSystemError","directoryCreationFailed","readFile","encoding","validEncodings","includes","toLowerCase","Error","maxFileSize","size","code","fileNotFound","writeFile","data","forEachFileIn","directory","callback","options","pattern","files","glob","cwd","nodir","file","join","err","operationFailed","readStream","createReadStream","hashFile","length","crypto","createHash","update","digest","slice","listFiles","readdir"],"mappings":"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"}

package/dist/validate.d.ts

@@ -1,7 +1,41 @@
 import { z, ZodObject } from 'zod';
 import { ArgumentError } from './error/ArgumentError';
+import { ConfigurationError } from './error/ConfigurationError';
+import { FileSystemError } from './error/FileSystemError';
 import { ConfigSchema, Logger, Options } from './types';
-export { ArgumentError };
+export { ArgumentError, ConfigurationError, FileSystemError };
+/**
+ * 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']
+ * ```
+ */
 export declare const listZodKeys: (schema: z.ZodTypeAny, prefix?: string) => string[];
 /**
  * Generates a list of all keys within a JavaScript object, using dot notation for nested keys.
@@ -14,5 +48,66 @@ export declare const listZodKeys: (schema: z.ZodTypeAny, prefix?: string) => str
  * @returns An array of strings representing all keys in dot notation.
  */
 export declare const listObjectKeys: (obj: Record<string, unknown>, prefix?: string) => string[];
+/**
+ * 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
+ * ```
+ */
 export declare const checkForExtraKeys: (mergedSources: object, fullSchema: ZodObject<any>, logger: Logger | typeof console) => void;
+/**
+ * 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
+ * ```
+ */
 export declare const validate: <T extends z.ZodRawShape>(config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>, options: Options<T>) => Promise<void>;