@utilarium/cardigantime 0.0.24-dev.0

package/dist/cardigantime.js

@@ -0,0 +1,198 @@
+import { configure } from './configure.js';
+import { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants.js';
+export { PROGRAM_NAME, VERSION } from './constants.js';
+import { checkConfig, read } from './read.js';
+import { validate } from './validate.js';
+import * as yaml from 'js-yaml';
+import * as path from 'node:path';
+import { generateDefaultConfig } from './util/schema-defaults.js';
+import { create as create$1 } from './util/storage.js';
+import { FileSystemError } from './error/FileSystemError.js';
+export { ConfigFormat, ConfigSchema, DEFAULT_ROOT_MARKERS } from './types.js';
+export { ArgumentError } from './error/ArgumentError.js';
+export { ConfigurationError } from './error/ConfigurationError.js';
+
+/**
+ * Creates a new Cardigantime instance for configuration management.
+ * 
+ * Cardigantime handles the complete configuration lifecycle including:
+ * - Reading configuration from YAML files
+ * - Validating configuration against Zod schemas
+ * - Merging CLI arguments with file configuration and defaults
+ * - Providing type-safe configuration objects
+ * 
+ * @template T - The Zod schema shape type for your configuration
+ * @param pOptions - Configuration options for the Cardigantime instance
+ * @param pOptions.defaults - Default configuration settings
+ * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)
+ * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')
+ * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)
+ * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')
+ * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)
+ * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])
+ * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)
+ * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)
+ * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger
+ * 
+ * @example
+ * ```typescript
+ * import { create } from '@utilarium/cardigantime';
+ * import { z } from 'zod';
+ * 
+ * const MyConfigSchema = z.object({
+ *   apiKey: z.string().min(1),
+ *   timeout: z.number().default(5000),
+ *   debug: z.boolean().default(false),
+ *   contextDirectories: z.array(z.string()).optional(),
+ * });
+ * 
+ * const cardigantime = create({
+ *   defaults: {
+ *     configDirectory: './config',
+ *     configFile: 'myapp.yaml',
+ *     // Resolve relative paths in contextDirectories relative to config file location
+ *     pathResolution: {
+ *       pathFields: ['contextDirectories'],
+ *       resolvePathArray: ['contextDirectories']
+ *     },
+ *     // Configure how array fields are merged in hierarchical mode
+ *     fieldOverlaps: {
+ *       'features': 'append',              // Accumulate features from all levels
+ *       'excludePatterns': 'prepend'       // Higher precedence patterns come first
+ *     }
+ *   },
+ *   configShape: MyConfigSchema.shape,
+ *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery
+ * });
+ * 
+ * // If config file is at ../config/myapp.yaml and contains:
+ * // contextDirectories: ['./context', './data']
+ * // These paths will be resolved relative to ../config/ directory
+ * ```
+ */ const create = (pOptions)=>{
+    // Validate that configDirectory is a string
+    if (!pOptions.defaults.configDirectory || typeof pOptions.defaults.configDirectory !== 'string') {
+        throw new Error(`Configuration directory must be a string, received: ${typeof pOptions.defaults.configDirectory} (${JSON.stringify(pOptions.defaults.configDirectory)})`);
+    }
+    const defaults = {
+        ...DEFAULT_OPTIONS,
+        ...pOptions.defaults
+    };
+    const features = pOptions.features || DEFAULT_FEATURES;
+    const configShape = pOptions.configShape;
+    let logger = pOptions.logger || DEFAULT_LOGGER;
+    const options = {
+        defaults,
+        features,
+        configShape,
+        logger
+    };
+    const setLogger = (pLogger)=>{
+        logger = pLogger;
+        options.logger = pLogger;
+    };
+    const generateConfig = async (configDirectory)=>{
+        const targetDir = configDirectory || options.defaults.configDirectory;
+        const configFile = options.defaults.configFile;
+        const encoding = options.defaults.encoding;
+        // Validate that targetDir is a string
+        if (!targetDir || typeof targetDir !== 'string') {
+            throw new Error(`Configuration directory must be a string, received: ${typeof targetDir} (${JSON.stringify(targetDir)})`);
+        }
+        logger.verbose(`Generating configuration file in: ${targetDir}`);
+        // Create storage utility
+        const storage = create$1({
+            log: logger.debug
+        });
+        // Ensure the target directory exists
+        const dirExists = await storage.exists(targetDir);
+        if (!dirExists) {
+            logger.info(`Creating configuration directory: ${targetDir}`);
+            try {
+                await storage.createDirectory(targetDir);
+            } catch (error) {
+                throw FileSystemError.directoryCreationFailed(targetDir, error);
+            }
+        }
+        // Check if directory is writable
+        const isWritable = await storage.isDirectoryWritable(targetDir);
+        if (!isWritable) {
+            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');
+        }
+        // Build the full config file path
+        const configFilePath = path.join(targetDir, configFile);
+        // Generate default configuration
+        logger.debug(`Generating defaults for schema with keys: ${Object.keys(options.configShape).join(', ')}`);
+        const defaultConfig = generateDefaultConfig(options.configShape);
+        logger.debug(`Generated default config: ${JSON.stringify(defaultConfig, null, 2)}`);
+        // Convert to YAML with nice formatting
+        const yamlContent = yaml.dump(defaultConfig, {
+            indent: 2,
+            lineWidth: 120,
+            noRefs: true,
+            sortKeys: true
+        });
+        // Add header comment to the YAML file
+        const header = `# Configuration file generated by Cardigantime
+# This file contains default values for your application configuration.
+# Modify the values below to customize your application's behavior.
+#
+# For more information about Cardigantime configuration:
+# https://utilarium.github.io/cardigantime/
+
+`;
+        const finalContent = header + yamlContent;
+        // Check if config file already exists
+        const configExists = await storage.exists(configFilePath);
+        if (configExists) {
+            logger.warn(`Configuration file already exists: ${configFilePath}`);
+            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');
+            logger.info('\n' + '='.repeat(60));
+            logger.info(finalContent.trim());
+            logger.info('='.repeat(60));
+            return;
+        }
+        // Write the configuration file
+        try {
+            await storage.writeFile(configFilePath, finalContent, encoding);
+            logger.info(`Configuration file generated successfully: ${configFilePath}`);
+        } catch (error) {
+            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);
+        }
+    };
+    return {
+        setLogger,
+        configure: (command)=>configure(command, options),
+        validate: (config)=>validate(config, options),
+        read: (args)=>read(args, options),
+        generateConfig,
+        checkConfig: (args)=>checkConfig(args, options)
+    };
+};
+/**
+ * Type-safe helper for defining configuration in TypeScript/JavaScript files.
+ * 
+ * This is a simple identity function that provides type checking and
+ * autocomplete for configuration objects when using TypeScript config files.
+ * 
+ * @template T - The configuration type
+ * @param config - The configuration object
+ * @returns The same configuration object (identity function)
+ * 
+ * @example
+ * ```typescript
+ * // config.ts
+ * import { defineConfig } from '@utilarium/cardigantime';
+ * 
+ * export default defineConfig({
+ *   apiKey: process.env.API_KEY || 'default-key',
+ *   timeout: 5000,
+ *   debug: process.env.NODE_ENV === 'development'
+ * });
+ * ```
+ */ function defineConfig(config) {
+    return config;
+}
+
+export { FileSystemError, create, defineConfig };
+//# sourceMappingURL=cardigantime.js.map

package/dist/cardigantime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardigantime.js","sources":["../src/cardigantime.ts"],"sourcesContent":["import { Command } from 'commander';\nimport { Args, DefaultOptions, Feature, Cardigantime, Logger, Options } from 'types';\nimport { z, ZodObject } from 'zod';\nimport { configure } from './configure';\nimport { DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS } from './constants';\nimport { read, checkConfig } from './read';\nimport { ConfigSchema } from 'types';\nimport { validate } from './validate';\nimport * as yaml from 'js-yaml';\nimport * as path from 'node:path';\nimport { generateDefaultConfig } from './util/schema-defaults';\nimport * as Storage from './util/storage';\nimport { FileSystemError } from './error/FileSystemError';\n\nexport * from './types';\nexport { ArgumentError, ConfigurationError, FileSystemError } from './validate';\nexport { VERSION, PROGRAM_NAME } from './constants';\n\n/**\n * Creates a new Cardigantime instance for configuration management.\n * \n * Cardigantime handles the complete configuration lifecycle including:\n * - Reading configuration from YAML files\n * - Validating configuration against Zod schemas\n * - Merging CLI arguments with file configuration and defaults\n * - Providing type-safe configuration objects\n * \n * @template T - The Zod schema shape type for your configuration\n * @param pOptions - Configuration options for the Cardigantime instance\n * @param pOptions.defaults - Default configuration settings\n * @param pOptions.defaults.configDirectory - Directory to search for configuration files (required)\n * @param pOptions.defaults.configFile - Name of the configuration file (optional, defaults to 'config.yaml')\n * @param pOptions.defaults.isRequired - Whether the config directory must exist (optional, defaults to false)\n * @param pOptions.defaults.encoding - File encoding for reading config files (optional, defaults to 'utf8')\n * @param pOptions.defaults.pathResolution - Configuration for resolving relative paths in config values relative to the config file's directory (optional)\n * @param pOptions.features - Array of features to enable (optional, defaults to ['config'])\n * @param pOptions.configShape - Zod schema shape defining your configuration structure (required)\n * @param pOptions.logger - Custom logger implementation (optional, defaults to console logger)\n * @returns A Cardigantime instance with methods for configure, read, validate, and setLogger\n * \n * @example\n * ```typescript\n * import { create } from '@utilarium/cardigantime';\n * import { z } from 'zod';\n * \n * const MyConfigSchema = z.object({\n *   apiKey: z.string().min(1),\n *   timeout: z.number().default(5000),\n *   debug: z.boolean().default(false),\n *   contextDirectories: z.array(z.string()).optional(),\n * });\n * \n * const cardigantime = create({\n *   defaults: {\n *     configDirectory: './config',\n *     configFile: 'myapp.yaml',\n *     // Resolve relative paths in contextDirectories relative to config file location\n *     pathResolution: {\n *       pathFields: ['contextDirectories'],\n *       resolvePathArray: ['contextDirectories']\n *     },\n *     // Configure how array fields are merged in hierarchical mode\n *     fieldOverlaps: {\n *       'features': 'append',              // Accumulate features from all levels\n *       'excludePatterns': 'prepend'       // Higher precedence patterns come first\n *     }\n *   },\n *   configShape: MyConfigSchema.shape,\n *   features: ['config', 'hierarchical'],   // Enable hierarchical discovery\n * });\n * \n * // If config file is at ../config/myapp.yaml and contains:\n * // contextDirectories: ['./context', './data']\n * // These paths will be resolved relative to ../config/ directory\n * ```\n */\nexport const create = <T extends z.ZodRawShape>(pOptions: {\n    defaults: Pick<DefaultOptions, 'configDirectory'> & Partial<Omit<DefaultOptions, 'configDirectory'>>,\n    features?: Feature[],\n    configShape: T, // Make configShape mandatory\n    logger?: Logger,\n}): Cardigantime<T> => {\n\n    // Validate that configDirectory is a string\n    if (!pOptions.defaults.configDirectory || typeof pOptions.defaults.configDirectory !== 'string') {\n        throw new Error(`Configuration directory must be a string, received: ${typeof pOptions.defaults.configDirectory} (${JSON.stringify(pOptions.defaults.configDirectory)})`);\n    }\n\n    const defaults: DefaultOptions = { ...DEFAULT_OPTIONS, ...pOptions.defaults } as DefaultOptions;\n    const features = pOptions.features || DEFAULT_FEATURES;\n    const configShape = pOptions.configShape;\n    let logger = pOptions.logger || DEFAULT_LOGGER;\n\n    const options: Options<T> = {\n        defaults,\n        features,\n        configShape, // Store the shape\n        logger,\n    }\n\n    const setLogger = (pLogger: Logger) => {\n        logger = pLogger;\n        options.logger = pLogger;\n    }\n\n    const generateConfig = async (configDirectory?: string): Promise<void> => {\n        const targetDir = configDirectory || options.defaults.configDirectory;\n        const configFile = options.defaults.configFile;\n        const encoding = options.defaults.encoding;\n\n        // Validate that targetDir is a string\n        if (!targetDir || typeof targetDir !== 'string') {\n            throw new Error(`Configuration directory must be a string, received: ${typeof targetDir} (${JSON.stringify(targetDir)})`);\n        }\n\n        logger.verbose(`Generating configuration file in: ${targetDir}`);\n\n        // Create storage utility\n        const storage = Storage.create({ log: logger.debug });\n\n        // Ensure the target directory exists\n        const dirExists = await storage.exists(targetDir);\n        if (!dirExists) {\n            logger.info(`Creating configuration directory: ${targetDir}`);\n            try {\n                await storage.createDirectory(targetDir);\n            } catch (error: any) {\n                throw FileSystemError.directoryCreationFailed(targetDir, error);\n            }\n        }\n\n        // Check if directory is writable\n        const isWritable = await storage.isDirectoryWritable(targetDir);\n        if (!isWritable) {\n            throw new FileSystemError('not_writable', 'Configuration directory is not writable', targetDir, 'directory_write');\n        }\n\n        // Build the full config file path\n        const configFilePath = path.join(targetDir, configFile);\n\n        // Generate default configuration\n        logger.debug(`Generating defaults for schema with keys: ${Object.keys(options.configShape).join(', ')}`);\n        const defaultConfig = generateDefaultConfig(options.configShape, targetDir);\n        logger.debug(`Generated default config: ${JSON.stringify(defaultConfig, null, 2)}`);\n\n        // Convert to YAML with nice formatting\n        const yamlContent = yaml.dump(defaultConfig, {\n            indent: 2,\n            lineWidth: 120,\n            noRefs: true,\n            sortKeys: true\n        });\n\n        // Add header comment to the YAML file\n        const header = `# Configuration file generated by Cardigantime\n# This file contains default values for your application configuration.\n# Modify the values below to customize your application's behavior.\n#\n# For more information about Cardigantime configuration:\n# https://utilarium.github.io/cardigantime/\n\n`;\n\n        const finalContent = header + yamlContent;\n\n        // Check if config file already exists\n        const configExists = await storage.exists(configFilePath);\n        if (configExists) {\n            logger.warn(`Configuration file already exists: ${configFilePath}`);\n            logger.warn('This file was not overwritten, but here is what the default configuration looks like if you want to copy it:');\n            logger.info('\\n' + '='.repeat(60));\n            logger.info(finalContent.trim());\n            logger.info('='.repeat(60));\n            return;\n        }\n\n        // Write the configuration file\n        try {\n            await storage.writeFile(configFilePath, finalContent, encoding);\n            logger.info(`Configuration file generated successfully: ${configFilePath}`);\n        } catch (error: any) {\n            throw FileSystemError.operationFailed('write configuration file', configFilePath, error);\n        }\n    };\n\n    return {\n        setLogger,\n        configure: (command: Command) => configure(command, options),\n        validate: (config: z.infer<ZodObject<T & typeof ConfigSchema.shape>>) => validate(config, options),\n        read: (args: Args) => read(args, options),\n        generateConfig,\n        checkConfig: (args: Args) => checkConfig(args, options),\n    }\n}\n\n/**\n * Type-safe helper for defining configuration in TypeScript/JavaScript files.\n * \n * This is a simple identity function that provides type checking and\n * autocomplete for configuration objects when using TypeScript config files.\n * \n * @template T - The configuration type\n * @param config - The configuration object\n * @returns The same configuration object (identity function)\n * \n * @example\n * ```typescript\n * // config.ts\n * import { defineConfig } from '@utilarium/cardigantime';\n * \n * export default defineConfig({\n *   apiKey: process.env.API_KEY || 'default-key',\n *   timeout: 5000,\n *   debug: process.env.NODE_ENV === 'development'\n * });\n * ```\n */\nexport function defineConfig<T>(config: T): T {\n    return config;\n}\n\n"],"names":["create","pOptions","defaults","configDirectory","Error","JSON","stringify","DEFAULT_OPTIONS","features","DEFAULT_FEATURES","configShape","logger","DEFAULT_LOGGER","options","setLogger","pLogger","generateConfig","targetDir","configFile","encoding","verbose","storage","Storage","log","debug","dirExists","exists","info","createDirectory","error","FileSystemError","directoryCreationFailed","isWritable","isDirectoryWritable","configFilePath","path","join","Object","keys","defaultConfig","generateDefaultConfig","yamlContent","yaml","dump","indent","lineWidth","noRefs","sortKeys","header","finalContent","configExists","warn","repeat","trim","writeFile","operationFailed","configure","command","validate","config","read","args","checkConfig","defineConfig"],"mappings":"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"}

package/dist/config/executable-security.d.ts

@@ -0,0 +1,32 @@
+import { ConfigFormat, Logger } from '../types';
+/**
+ * Security error thrown when executable config is detected but not allowed.
+ */
+export declare class ExecutableConfigSecurityError extends Error {
+    readonly format: ConfigFormat;
+    readonly filePath: string;
+    constructor(format: ConfigFormat, filePath: string);
+}
+/**
+ * Checks if a configuration format is executable (JavaScript or TypeScript).
+ *
+ * @param format - The configuration format to check
+ * @returns True if the format is executable
+ */
+export declare function isExecutableFormat(format: ConfigFormat): boolean;
+/**
+ * Validates that executable configuration is allowed before loading.
+ *
+ * @param format - The configuration format being loaded
+ * @param filePath - Path to the configuration file
+ * @param allowExecutableConfig - Whether executable configs are allowed
+ * @param logger - Optional logger for warnings
+ * @throws {ExecutableConfigSecurityError} When executable config is not allowed
+ */
+export declare function validateExecutableConfig(format: ConfigFormat, filePath: string, allowExecutableConfig?: boolean, logger?: Logger): void;
+/**
+ * Gets a user-friendly description of the security model for executable configs.
+ *
+ * @returns Security model description
+ */
+export declare function getExecutableConfigSecurityModel(): string;

package/dist/config/format-detector.d.ts

@@ -0,0 +1,59 @@
+import { ConfigFormat, Logger } from '../types';
+/**
+ * Options for format detection.
+ */
+export interface FormatDetectorOptions {
+    /** Base configuration file name without extension (e.g., 'config') */
+    configFileName: string;
+    /** Directory to search for configuration files */
+    configDirectory: string;
+    /** Optional format override to force a specific format */
+    formatOverride?: ConfigFormat;
+    /** Logger for debugging */
+    logger?: Logger;
+    /** Storage interface for file system operations */
+    storage: {
+        exists(filePath: string): Promise<boolean>;
+        isFileReadable(filePath: string): Promise<boolean>;
+    };
+}
+/**
+ * Result of format detection.
+ */
+export interface DetectedFormat {
+    /** The detected or overridden format */
+    format: ConfigFormat;
+    /** Full path to the configuration file */
+    filePath: string;
+    /** Whether this was an override or auto-detected */
+    wasOverridden: boolean;
+}
+/**
+ * Detects the configuration file format to use.
+ *
+ * Searches for configuration files in priority order:
+ * 1. TypeScript (.ts, .mts, .cts)
+ * 2. JavaScript (.js, .mjs, .cjs)
+ * 3. JSON (.json)
+ * 4. YAML (.yaml, .yml)
+ *
+ * If a format override is provided, only that format is checked.
+ *
+ * @param options - Format detection options
+ * @returns Promise resolving to detected format info, or null if no config found
+ */
+export declare function detectConfigFormat(options: FormatDetectorOptions): Promise<DetectedFormat | null>;
+/**
+ * Gets the priority value for a format (higher = more priority).
+ *
+ * @param format - The configuration format
+ * @returns Priority value (0-based index)
+ */
+export declare function getFormatPriority(format: ConfigFormat): number;
+/**
+ * Gets all file extensions for a given format.
+ *
+ * @param format - The configuration format
+ * @returns Array of file extensions (e.g., ['.yaml', '.yml'])
+ */
+export declare function getFormatExtensions(format: ConfigFormat): string[];

package/dist/configure.d.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander';
+import { z } from 'zod';
+import { ArgumentError } from './error/ArgumentError';
+import { Options } from './types';
+export { ArgumentError };
+/**
+ * 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
+ * ```
+ */
+export declare function validateConfigDirectory(configDirectory: string, _testThrowNonArgumentError?: boolean): string;
+/**
+ * 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>
+ * ```
+ */
+export declare const configure: <T extends z.ZodRawShape>(command: Command, options: Options<T>, _testThrowNonArgumentError?: boolean) => Promise<Command>;

package/dist/configure.js

@@ -0,0 +1,125 @@
+import { ArgumentError } from './error/ArgumentError.js';
+
+/**
+ * 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(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(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(value, _testThrowNonArgumentError);
+        } catch (error) {
+            if (error instanceof ArgumentError) {
+                // Re-throw with more specific context for CLI usage
+                throw new ArgumentError('config-directory', `Invalid --config-directory: ${error.message}`);
+            }
+            throw error;
+        }
+    }, validatedDefaultDir);
+    // Add the init config option
+    retCommand = retCommand.option('--init-config', 'Generate initial configuration file and exit');
+    // Add the check config option
+    retCommand = retCommand.option('--check-config', 'Display resolved configuration with source tracking and exit');
+    // Add the config format option
+    retCommand = retCommand.option('--config-format <format>', 'Force a specific configuration file format (yaml, json, javascript, typescript)', (value)=>{
+        const validFormats = [
+            'yaml',
+            'json',
+            'javascript',
+            'typescript'
+        ];
+        const normalized = value.toLowerCase();
+        if (!validFormats.includes(normalized)) {
+            throw new ArgumentError('config-format', `Invalid --config-format: must be one of ${validFormats.join(', ')}`);
+        }
+        return normalized;
+    });
+    return retCommand;
+};
+
+export { ArgumentError, configure, validateConfigDirectory };
+//# sourceMappingURL=configure.js.map

package/dist/configure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configure.js","sources":["../src/configure.ts"],"sourcesContent":["import { Command } from \"commander\";\nimport { z } from \"zod\";\nimport { ArgumentError } from \"./error/ArgumentError\";\nimport { Options } from \"./types\";\nexport { ArgumentError };\n\n/**\n * Validates a configuration directory path to ensure it's safe and valid.\n * \n * Performs security and safety checks including:\n * - Non-empty string validation\n * - Null byte injection prevention\n * - Path length validation\n * - Type checking\n * \n * @param configDirectory - The configuration directory path to validate\n * @param _testThrowNonArgumentError - Internal testing parameter to simulate non-ArgumentError exceptions\n * @returns The trimmed and validated configuration directory path\n * @throws {ArgumentError} When the directory path is invalid\n * \n * @example\n * ```typescript\n * const validDir = validateConfigDirectory('./config'); // Returns './config'\n * const invalidDir = validateConfigDirectory(''); // Throws ArgumentError\n * ```\n */\nexport function validateConfigDirectory(configDirectory: string, _testThrowNonArgumentError?: boolean): string {\n    if (_testThrowNonArgumentError) {\n        throw new Error('Test non-ArgumentError for coverage');\n    }\n\n    if (!configDirectory) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty');\n    }\n\n    if (typeof configDirectory !== 'string') {\n        throw new ArgumentError('configDirectory', 'Configuration directory must be a string');\n    }\n\n    const trimmed = configDirectory.trim();\n    if (trimmed.length === 0) {\n        throw new ArgumentError('configDirectory', 'Configuration directory cannot be empty or whitespace only');\n    }\n\n    // Check for obviously invalid paths\n    if (trimmed.includes('\\0')) {\n        throw new ArgumentError('configDirectory', 'Configuration directory contains invalid null character');\n    }\n\n    // Validate path length (reasonable limit)\n    if (trimmed.length > 1000) {\n        throw new ArgumentError('configDirectory', 'Configuration directory path is too long (max 1000 characters)');\n    }\n\n    return trimmed;\n}\n\n/**\n * Configures a Commander.js command with Cardigantime's CLI options.\n * \n * This function adds command-line options that allow users to override\n * configuration settings at runtime, such as:\n * - --config-directory: Override the default configuration directory\n * \n * The function validates both the command object and the options to ensure\n * they meet the requirements for proper integration.\n * \n * @template T - The Zod schema shape type for configuration validation\n * @param command - The Commander.js Command instance to configure\n * @param options - Cardigantime options containing defaults and schema\n * @param _testThrowNonArgumentError - Internal testing parameter\n * @returns Promise resolving to the configured Command instance\n * @throws {ArgumentError} When command or options are invalid\n * \n * @example\n * ```typescript\n * import { Command } from 'commander';\n * import { configure } from './configure';\n * \n * const program = new Command();\n * const configuredProgram = await configure(program, options);\n * \n * // Now the program accepts: --config-directory <path>\n * ```\n */\nexport const configure = async <T extends z.ZodRawShape>(\n    command: Command,\n    options: Options<T>,\n    _testThrowNonArgumentError?: boolean\n): Promise<Command> => {\n    // Validate the command object\n    if (!command) {\n        throw new ArgumentError('command', 'Command instance is required');\n    }\n\n    if (typeof command.option !== 'function') {\n        throw new ArgumentError('command', 'Command must be a valid Commander.js Command instance');\n    }\n\n    // Validate options\n    if (!options) {\n        throw new ArgumentError('options', 'Options object is required');\n    }\n\n    if (!options.defaults) {\n        throw new ArgumentError('options.defaults', 'Options must include defaults configuration');\n    }\n\n    if (!options.defaults.configDirectory) {\n        throw new ArgumentError('options.defaults.configDirectory', 'Default config directory is required');\n    }\n\n    // Validate the default config directory\n    const validatedDefaultDir = validateConfigDirectory(options.defaults.configDirectory, _testThrowNonArgumentError);\n\n    let retCommand = command;\n\n    // Add the config directory option with validation\n    retCommand = retCommand.option(\n        '-c, --config-directory <configDirectory>',\n        'Configuration directory path',\n        (value: string) => {\n            try {\n                return validateConfigDirectory(value, _testThrowNonArgumentError);\n            } catch (error) {\n                if (error instanceof ArgumentError) {\n                    // Re-throw with more specific context for CLI usage\n                    throw new ArgumentError('config-directory', `Invalid --config-directory: ${error.message}`);\n                }\n                throw error;\n            }\n        },\n        validatedDefaultDir\n    );\n\n    // Add the init config option\n    retCommand = retCommand.option(\n        '--init-config',\n        'Generate initial configuration file and exit'\n    );\n\n    // Add the check config option\n    retCommand = retCommand.option(\n        '--check-config',\n        'Display resolved configuration with source tracking and exit'\n    );\n\n    // Add the config format option\n    retCommand = retCommand.option(\n        '--config-format <format>',\n        'Force a specific configuration file format (yaml, json, javascript, typescript)',\n        (value: string) => {\n            const validFormats = ['yaml', 'json', 'javascript', 'typescript'];\n            const normalized = value.toLowerCase();\n            if (!validFormats.includes(normalized)) {\n                throw new ArgumentError(\n                    'config-format',\n                    `Invalid --config-format: must be one of ${validFormats.join(', ')}`\n                );\n            }\n            return normalized;\n        }\n    );\n\n    return retCommand;\n}\n\n\n\n\n"],"names":["validateConfigDirectory","configDirectory","_testThrowNonArgumentError","ArgumentError","trimmed","trim","length","includes","configure","command","options","option","defaults","validatedDefaultDir","retCommand","value","error","message","validFormats","normalized","toLowerCase","join"],"mappings":";;AAMA;;;;;;;;;;;;;;;;;;;AAmBC,IACM,SAASA,uBAAAA,CAAwBC,eAAuB,EAAEC,0BAAoC,EAAA;AAKjG,IAAA,IAAI,CAACD,eAAAA,EAAiB;QAClB,MAAM,IAAIE,cAAc,iBAAA,EAAmB,yCAAA,CAAA;AAC/C,IAAA;IAEA,IAAI,OAAOF,oBAAoB,QAAA,EAAU;QACrC,MAAM,IAAIE,cAAc,iBAAA,EAAmB,0CAAA,CAAA;AAC/C,IAAA;IAEA,MAAMC,OAAAA,GAAUH,gBAAgBI,IAAI,EAAA;IACpC,IAAID,OAAAA,CAAQE,MAAM,KAAK,CAAA,EAAG;QACtB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,4DAAA,CAAA;AAC/C,IAAA;;IAGA,IAAIC,OAAAA,CAAQG,QAAQ,CAAC,IAAA,CAAA,EAAO;QACxB,MAAM,IAAIJ,cAAc,iBAAA,EAAmB,yDAAA,CAAA;AAC/C,IAAA;;IAGA,IAAIC,OAAAA,CAAQE,MAAM,GAAG,IAAA,EAAM;QACvB,MAAM,IAAIH,cAAc,iBAAA,EAAmB,gEAAA,CAAA;AAC/C,IAAA;IAEA,OAAOC,OAAAA;AACX;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BC,IACM,MAAMI,SAAAA,GAAY,OACrBC,SACAC,OAAAA,EACAR,0BAAAA,GAAAA;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIN,cAAc,SAAA,EAAW,8BAAA,CAAA;AACvC,IAAA;AAEA,IAAA,IAAI,OAAOM,OAAAA,CAAQE,MAAM,KAAK,UAAA,EAAY;QACtC,MAAM,IAAIR,cAAc,SAAA,EAAW,uDAAA,CAAA;AACvC,IAAA;;AAGA,IAAA,IAAI,CAACO,OAAAA,EAAS;QACV,MAAM,IAAIP,cAAc,SAAA,EAAW,4BAAA,CAAA;AACvC,IAAA;IAEA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,EAAE;QACnB,MAAM,IAAIT,cAAc,kBAAA,EAAoB,6CAAA,CAAA;AAChD,IAAA;AAEA,IAAA,IAAI,CAACO,OAAAA,CAAQE,QAAQ,CAACX,eAAe,EAAE;QACnC,MAAM,IAAIE,cAAc,kCAAA,EAAoC,sCAAA,CAAA;AAChE,IAAA;;AAGA,IAAA,MAAMU,sBAAsBb,uBAAAA,CAAwBU,OAAAA,CAAQE,QAAQ,CAACX,eAAiBC,CAAAA;AAEtF,IAAA,IAAIY,UAAAA,GAAaL,OAAAA;;AAGjBK,IAAAA,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,0CAAA,EACA,gCACA,CAACI,KAAAA,GAAAA;QACG,IAAI;AACA,YAAA,OAAOf,wBAAwBe,KAAAA,EAAOb,0BAAAA,CAAAA;AAC1C,QAAA,CAAA,CAAE,OAAOc,KAAAA,EAAO;AACZ,YAAA,IAAIA,iBAAiBb,aAAAA,EAAe;;gBAEhC,MAAM,IAAIA,cAAc,kBAAA,EAAoB,CAAC,4BAA4B,EAAEa,KAAAA,CAAMC,OAAO,CAAA,CAAE,CAAA;AAC9F,YAAA;YACA,MAAMD,KAAAA;AACV,QAAA;IACJ,CAAA,EACAH,mBAAAA,CAAAA;;IAIJC,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,eAAA,EACA,8CAAA,CAAA;;IAIJG,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,gBAAA,EACA,8DAAA,CAAA;;AAIJG,IAAAA,UAAAA,GAAaA,UAAAA,CAAWH,MAAM,CAC1B,0BAAA,EACA,mFACA,CAACI,KAAAA,GAAAA;AACG,QAAA,MAAMG,YAAAA,GAAe;AAAC,YAAA,MAAA;AAAQ,YAAA,MAAA;AAAQ,YAAA,YAAA;AAAc,YAAA;AAAa,SAAA;QACjE,MAAMC,UAAAA,GAAaJ,MAAMK,WAAW,EAAA;AACpC,QAAA,IAAI,CAACF,YAAAA,CAAaX,QAAQ,CAACY,UAAAA,CAAAA,EAAa;YACpC,MAAM,IAAIhB,cACN,eAAA,EACA,CAAC,wCAAwC,EAAEe,YAAAA,CAAaG,IAAI,CAAC,IAAA,CAAA,CAAA,CAAO,CAAA;AAE5E,QAAA;QACA,OAAOF,UAAAA;AACX,IAAA,CAAA,CAAA;IAGJ,OAAOL,UAAAA;AACX;;;;"}

package/dist/constants.d.ts

@@ -0,0 +1,25 @@
+import { DefaultOptions, Feature, Logger } from './types';
+/** Version string populated at build time with git and system information */
+export declare const VERSION = "__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__";
+/** The program name used in CLI help and error messages */
+export declare const PROGRAM_NAME = "cardigantime";
+/** Default file encoding for reading configuration files */
+export declare const DEFAULT_ENCODING = "utf8";
+/** Default configuration file name to look for in the config directory */
+export declare 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.
+ */
+export declare const DEFAULT_OPTIONS: Partial<DefaultOptions>;
+/**
+ * Default features enabled when creating a Cardigantime instance.
+ * Currently includes only the 'config' feature for configuration file support.
+ */
+export declare const DEFAULT_FEATURES: Feature[];
+/**
+ * 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.
+ */
+export declare const DEFAULT_LOGGER: Logger;

package/dist/constants.js

@@ -0,0 +1,38 @@
+/** Version string populated at build time with git and system information */ const VERSION = '0.0.24-dev.0 (working/2325c27  2026-01-30 13:16:50 -0800) darwin arm64 v24.8.0';
+/** The program name used in CLI help and error messages */ const PROGRAM_NAME = 'cardigantime';
+/** Default file encoding for reading configuration files */ const DEFAULT_ENCODING = 'utf8';
+/** Default configuration file name to look for in the config directory */ const DEFAULT_CONFIG_FILE = 'config.yaml';
+/**
+ * Default configuration options applied when creating a Cardigantime instance.
+ * These provide sensible defaults that work for most use cases.
+ */ const DEFAULT_OPTIONS = {
+    configFile: DEFAULT_CONFIG_FILE,
+    isRequired: false,
+    encoding: DEFAULT_ENCODING,
+    pathResolution: undefined
+};
+/**
+ * Default features enabled when creating a Cardigantime instance.
+ * Currently includes only the 'config' feature for configuration file support.
+ */ const DEFAULT_FEATURES = [
+    'config'
+];
+/**
+ * Default logger implementation using console methods.
+ * Provides basic logging functionality when no custom logger is specified.
+ * The verbose and silly methods are no-ops to avoid excessive output.
+ */ const DEFAULT_LOGGER = {
+    // eslint-disable-next-line no-console
+    debug: console.debug,
+    // eslint-disable-next-line no-console
+    info: console.info,
+    // eslint-disable-next-line no-console
+    warn: console.warn,
+    // eslint-disable-next-line no-console
+    error: console.error,
+    verbose: ()=>{},
+    silly: ()=>{}
+};
+
+export { DEFAULT_CONFIG_FILE, DEFAULT_ENCODING, DEFAULT_FEATURES, DEFAULT_LOGGER, DEFAULT_OPTIONS, PROGRAM_NAME, VERSION };
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["import { DefaultOptions, Feature, Logger } from \"./types\";\n\n/** Version string populated at build time with git and system information */\nexport const VERSION = '__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__';\n\n/** The program name used in CLI help and error messages */\nexport const PROGRAM_NAME = 'cardigantime';\n\n/** Default file encoding for reading configuration files */\nexport const DEFAULT_ENCODING = 'utf8';\n\n/** Default configuration file name to look for in the config directory */\nexport const DEFAULT_CONFIG_FILE = 'config.yaml';\n\n/**\n * Default configuration options applied when creating a Cardigantime instance.\n * These provide sensible defaults that work for most use cases.\n */\nexport const DEFAULT_OPTIONS: Partial<DefaultOptions> = {\n    configFile: DEFAULT_CONFIG_FILE,\n    isRequired: false,\n    encoding: DEFAULT_ENCODING,\n    pathResolution: undefined, // No path resolution by default\n}\n\n/**\n * Default features enabled when creating a Cardigantime instance.\n * Currently includes only the 'config' feature for configuration file support.\n */\nexport const DEFAULT_FEATURES: Feature[] = ['config'];\n\n/**\n * Default logger implementation using console methods.\n * Provides basic logging functionality when no custom logger is specified.\n * The verbose and silly methods are no-ops to avoid excessive output.\n */\nexport const DEFAULT_LOGGER: Logger = {\n    // eslint-disable-next-line no-console\n    debug: console.debug,\n    // eslint-disable-next-line no-console\n    info: console.info,\n    // eslint-disable-next-line no-console\n    warn: console.warn,\n    // eslint-disable-next-line no-console\n    error: console.error,\n\n    verbose: () => { },\n\n    silly: () => { },\n}\n"],"names":["VERSION","PROGRAM_NAME","DEFAULT_ENCODING","DEFAULT_CONFIG_FILE","DEFAULT_OPTIONS","configFile","isRequired","encoding","pathResolution","undefined","DEFAULT_FEATURES","DEFAULT_LOGGER","debug","console","info","warn","error","verbose","silly"],"mappings":"AAEA,8EACO,MAAMA,OAAAA,GAAU;AAEvB,4DACO,MAAMC,YAAAA,GAAe;AAE5B,6DACO,MAAMC,gBAAAA,GAAmB;AAEhC,2EACO,MAAMC,mBAAAA,GAAsB;AAEnC;;;UAIaC,eAAAA,GAA2C;IACpDC,UAAAA,EAAYF,mBAAAA;IACZG,UAAAA,EAAY,KAAA;IACZC,QAAAA,EAAUL,gBAAAA;IACVM,cAAAA,EAAgBC;AACpB;AAEA;;;UAIaC,gBAAAA,GAA8B;AAAC,IAAA;;AAE5C;;;;UAKaC,cAAAA,GAAyB;;AAElCC,IAAAA,KAAAA,EAAOC,QAAQD,KAAK;;AAEpBE,IAAAA,IAAAA,EAAMD,QAAQC,IAAI;;AAElBC,IAAAA,IAAAA,EAAMF,QAAQE,IAAI;;AAElBC,IAAAA,KAAAA,EAAOH,QAAQG,KAAK;AAEpBC,IAAAA,OAAAA,EAAS,IAAA,CAAQ,CAAA;AAEjBC,IAAAA,KAAAA,EAAO,IAAA,CAAQ;AACnB;;;;"}