@theunwalked/cardigantime 0.0.2 → 0.0.3

package/dist/constants.js

@@ -1,14 +1,24 @@
-const DEFAULT_ENCODING = 'utf8';
-const DEFAULT_CONFIG_FILE = 'config.yaml';
-const DEFAULT_OPTIONS = {
+/** Default file encoding for reading configuration files */ const DEFAULT_ENCODING = 'utf8';
+/** Default configuration file name to look for in the config directory */ const DEFAULT_CONFIG_FILE = 'config.yaml';
+/**
+ * Default configuration options applied when creating a Cardigantime instance.
+ * These provide sensible defaults that work for most use cases.
+ */ const DEFAULT_OPTIONS = {
     configFile: DEFAULT_CONFIG_FILE,
     isRequired: false,
     encoding: DEFAULT_ENCODING
 };
-const DEFAULT_FEATURES = [
+/**
+ * Default features enabled when creating a Cardigantime instance.
+ * Currently includes only the 'config' feature for configuration file support.
+ */ const DEFAULT_FEATURES = [
     'config'
 ];
-const DEFAULT_LOGGER = {
+/**
+ * Default logger implementation using console methods.
+ * Provides basic logging functionality when no custom logger is specified.
+ * The verbose and silly methods are no-ops to avoid excessive output.
+ */ const DEFAULT_LOGGER = {
     // eslint-disable-next-line no-console
     debug: console.debug,
     // eslint-disable-next-line no-console

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":["../src/constants.ts"],"sourcesContent":["import { DefaultOptions, Feature, Logger } from \"./types\";\n\nexport const VERSION = '__VERSION__ (__GIT_BRANCH__/__GIT_COMMIT__ __GIT_TAGS__ __GIT_COMMIT_DATE__) __SYSTEM_INFO__';\nexport const PROGRAM_NAME = 'cardigantime';\nexport const DEFAULT_ENCODING = 'utf8';\nexport const DEFAULT_CONFIG_FILE = 'config.yaml';\n\nexport const DEFAULT_OPTIONS: Partial<DefaultOptions> = {\n    configFile: DEFAULT_CONFIG_FILE,\n    isRequired: false,\n    encoding: DEFAULT_ENCODING,\n}\n\nexport const DEFAULT_FEATURES: Feature[] = ['config'];\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":["DEFAULT_ENCODING","DEFAULT_CONFIG_FILE","DEFAULT_OPTIONS","configFile","isRequired","encoding","DEFAULT_FEATURES","DEFAULT_LOGGER","debug","console","info","warn","error","verbose","silly"],"mappings":"AAIO,MAAMA,mBAAmB;AACzB,MAAMC,sBAAsB;MAEtBC,eAA2C,GAAA;IACpDC,UAAYF,EAAAA,mBAAAA;IACZG,UAAY,EAAA,KAAA;IACZC,QAAUL,EAAAA;AACd;MAEaM,gBAA8B,GAAA;AAAC,IAAA;;MAE/BC,cAAyB,GAAA;;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,IAAQ,EAAA;AAEjBC,IAAAA,KAAAA,EAAO,IAAQ;AACnB;;;;"}
+{"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}\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":["DEFAULT_ENCODING","DEFAULT_CONFIG_FILE","DEFAULT_OPTIONS","configFile","isRequired","encoding","DEFAULT_FEATURES","DEFAULT_LOGGER","debug","console","info","warn","error","verbose","silly"],"mappings":"AAQA,6DACO,MAAMA,gBAAAA,GAAmB;AAEhC,2EACO,MAAMC,mBAAAA,GAAsB;AAEnC;;;UAIaC,eAAAA,GAA2C;IACpDC,UAAAA,EAAYF,mBAAAA;IACZG,UAAAA,EAAY,KAAA;IACZC,QAAAA,EAAUL;AACd;AAEA;;;UAIaM,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,EAAQ;AAEjBC,IAAAA,KAAAA,EAAO,IAAA;AACX;;;;"}

package/dist/error/ArgumentError.d.ts

@@ -1,5 +1,31 @@
+/**
+ * Error thrown when CLI arguments or function parameters are invalid.
+ *
+ * This error provides specific context about which argument failed validation
+ * and why, making it easier for users to fix their command-line usage or
+ * for developers to debug parameter issues.
+ *
+ * @example
+ * ```typescript
+ * throw new ArgumentError('config-directory', 'Path cannot be empty');
+ * // Error message: "Path cannot be empty"
+ * // error.argument: "config-directory"
+ * ```
+ */
 export declare class ArgumentError extends Error {
+    /** The name of the argument that caused the error */
     private argumentName;
+    /**
+     * Creates a new ArgumentError instance.
+     *
+     * @param argumentName - The name of the invalid argument
+     * @param message - Description of why the argument is invalid
+     */
     constructor(argumentName: string, message: string);
+    /**
+     * Gets the name of the argument that caused this error.
+     *
+     * @returns The argument name
+     */
     get argument(): string;
 }

package/dist/error/ArgumentError.js

@@ -0,0 +1,48 @@
+/**
+ * Error thrown when CLI arguments or function parameters are invalid.
+ * 
+ * This error provides specific context about which argument failed validation
+ * and why, making it easier for users to fix their command-line usage or
+ * for developers to debug parameter issues.
+ * 
+ * @example
+ * ```typescript
+ * throw new ArgumentError('config-directory', 'Path cannot be empty');
+ * // Error message: "Path cannot be empty"
+ * // error.argument: "config-directory"
+ * ```
+ */ function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class ArgumentError extends Error {
+    /**
+     * Gets the name of the argument that caused this error.
+     * 
+     * @returns The argument name
+     */ get argument() {
+        return this.argumentName;
+    }
+    /**
+     * Creates a new ArgumentError instance.
+     * 
+     * @param argumentName - The name of the invalid argument
+     * @param message - Description of why the argument is invalid
+     */ constructor(argumentName, message){
+        super(`${message}`), /** The name of the argument that caused the error */ _define_property(this, "argumentName", void 0);
+        this.name = 'ArgumentError';
+        this.argumentName = argumentName;
+    }
+}
+
+export { ArgumentError };
+//# sourceMappingURL=ArgumentError.js.map

package/dist/error/ArgumentError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgumentError.js","sources":["../../src/error/ArgumentError.ts"],"sourcesContent":["/**\n * Error thrown when CLI arguments or function parameters are invalid.\n * \n * This error provides specific context about which argument failed validation\n * and why, making it easier for users to fix their command-line usage or\n * for developers to debug parameter issues.\n * \n * @example\n * ```typescript\n * throw new ArgumentError('config-directory', 'Path cannot be empty');\n * // Error message: \"Path cannot be empty\"\n * // error.argument: \"config-directory\"\n * ```\n */\nexport class ArgumentError extends Error {\n    /** The name of the argument that caused the error */\n    private argumentName: string;\n\n    /**\n     * Creates a new ArgumentError instance.\n     * \n     * @param argumentName - The name of the invalid argument\n     * @param message - Description of why the argument is invalid\n     */\n    constructor(argumentName: string, message: string) {\n        super(`${message}`);\n        this.name = 'ArgumentError';\n        this.argumentName = argumentName;\n    }\n\n    /**\n     * Gets the name of the argument that caused this error.\n     * \n     * @returns The argument name\n     */\n    get argument(): string {\n        return this.argumentName;\n    }\n}"],"names":["ArgumentError","Error","argument","argumentName","message","name"],"mappings":"AAAA;;;;;;;;;;;;;AAaC,IAAA,SAAA,gBAAA,CAAA,GAAA,EAAA,GAAA,EAAA,KAAA,EAAA;;;;;;;;;;;;;AACM,MAAMA,aAAAA,SAAsBC,KAAAA,CAAAA;AAgB/B;;;;AAIC,QACD,IAAIC,QAAAA,GAAmB;QACnB,OAAO,IAAI,CAACC,YAAY;AAC5B;AAnBA;;;;;AAKC,QACD,WAAA,CAAYA,YAAoB,EAAEC,OAAe,CAAE;QAC/C,KAAK,CAAC,GAAGA,OAAAA,CAAAA,CAAS,CAAA,wDATtB,gBAAA,CAAA,IAAA,EAAQD,gBAAR,MAAA,CAAA;QAUI,IAAI,CAACE,IAAI,GAAG,eAAA;QACZ,IAAI,CAACF,YAAY,GAAGA,YAAAA;AACxB;AAUJ;;;;"}

package/dist/error/ConfigurationError.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Error thrown when configuration validation fails
+ */
+export declare class ConfigurationError extends Error {
+    readonly errorType: 'validation' | 'schema' | 'extra_keys';
+    readonly details?: any;
+    readonly configPath?: string;
+    constructor(errorType: 'validation' | 'schema' | 'extra_keys', message: string, details?: any, configPath?: string);
+    /**
+     * Creates a validation error for when config doesn't match the schema
+     */
+    static validation(message: string, zodError?: any, configPath?: string): ConfigurationError;
+    /**
+     * Creates an error for when extra/unknown keys are found
+     */
+    static extraKeys(extraKeys: string[], allowedKeys: string[], configPath?: string): ConfigurationError;
+    /**
+     * Creates a schema error for when the configuration schema itself is invalid
+     */
+    static schema(message: string, details?: any): ConfigurationError;
+}

package/dist/error/ConfigurationError.js

@@ -0,0 +1,46 @@
+/**
+ * Error thrown when configuration validation fails
+ */ function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class ConfigurationError extends Error {
+    /**
+     * Creates a validation error for when config doesn't match the schema
+     */ static validation(message, zodError, configPath) {
+        return new ConfigurationError('validation', message, zodError, configPath);
+    }
+    /**
+     * Creates an error for when extra/unknown keys are found
+     */ static extraKeys(extraKeys, allowedKeys, configPath) {
+        const message = `Unknown configuration keys found: ${extraKeys.join(', ')}. Allowed keys are: ${allowedKeys.join(', ')}`;
+        return new ConfigurationError('extra_keys', message, {
+            extraKeys,
+            allowedKeys
+        }, configPath);
+    }
+    /**
+     * Creates a schema error for when the configuration schema itself is invalid
+     */ static schema(message, details) {
+        return new ConfigurationError('schema', message, details);
+    }
+    constructor(errorType, message, details, configPath){
+        super(message), _define_property(this, "errorType", void 0), _define_property(this, "details", void 0), _define_property(this, "configPath", void 0);
+        this.name = 'ConfigurationError';
+        this.errorType = errorType;
+        this.details = details;
+        this.configPath = configPath;
+    }
+}
+
+export { ConfigurationError };
+//# sourceMappingURL=ConfigurationError.js.map

package/dist/error/ConfigurationError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigurationError.js","sources":["../../src/error/ConfigurationError.ts"],"sourcesContent":["/**\n * Error thrown when configuration validation fails\n */\nexport class ConfigurationError extends Error {\n    public readonly errorType: 'validation' | 'schema' | 'extra_keys';\n    public readonly details?: any;\n    public readonly configPath?: string;\n\n    constructor(\n        errorType: 'validation' | 'schema' | 'extra_keys',\n        message: string,\n        details?: any,\n        configPath?: string\n    ) {\n        super(message);\n        this.name = 'ConfigurationError';\n        this.errorType = errorType;\n        this.details = details;\n        this.configPath = configPath;\n    }\n\n    /**\n     * Creates a validation error for when config doesn't match the schema\n     */\n    static validation(message: string, zodError?: any, configPath?: string): ConfigurationError {\n        return new ConfigurationError('validation', message, zodError, configPath);\n    }\n\n    /**\n     * Creates an error for when extra/unknown keys are found\n     */\n    static extraKeys(extraKeys: string[], allowedKeys: string[], configPath?: string): ConfigurationError {\n        const message = `Unknown configuration keys found: ${extraKeys.join(', ')}. Allowed keys are: ${allowedKeys.join(', ')}`;\n        return new ConfigurationError('extra_keys', message, { extraKeys, allowedKeys }, configPath);\n    }\n\n    /**\n     * Creates a schema error for when the configuration schema itself is invalid\n     */\n    static schema(message: string, details?: any): ConfigurationError {\n        return new ConfigurationError('schema', message, details);\n    }\n} "],"names":["ConfigurationError","Error","validation","message","zodError","configPath","extraKeys","allowedKeys","join","schema","details","errorType","name"],"mappings":"AAAA;;AAEC,IAAA,SAAA,gBAAA,CAAA,GAAA,EAAA,GAAA,EAAA,KAAA,EAAA;;;;;;;;;;;;;AACM,MAAMA,kBAAAA,SAA2BC,KAAAA,CAAAA;AAkBpC;;AAEC,QACD,OAAOC,UAAAA,CAAWC,OAAe,EAAEC,QAAc,EAAEC,UAAmB,EAAsB;AACxF,QAAA,OAAO,IAAIL,kBAAAA,CAAmB,YAAA,EAAcG,OAAAA,EAASC,QAAAA,EAAUC,UAAAA,CAAAA;AACnE;AAEA;;AAEC,QACD,OAAOC,SAAAA,CAAUA,SAAmB,EAAEC,WAAqB,EAAEF,UAAmB,EAAsB;AAClG,QAAA,MAAMF,OAAAA,GAAU,CAAC,kCAAkC,EAAEG,SAAAA,CAAUE,IAAI,CAAC,IAAA,CAAA,CAAM,oBAAoB,EAAED,WAAAA,CAAYC,IAAI,CAAC,IAAA,CAAA,CAAA,CAAO;QACxH,OAAO,IAAIR,kBAAAA,CAAmB,YAAA,EAAcG,OAAAA,EAAS;AAAEG,YAAAA,SAAAA;AAAWC,YAAAA;SAAY,EAAGF,UAAAA,CAAAA;AACrF;AAEA;;AAEC,QACD,OAAOI,MAAAA,CAAON,OAAe,EAAEO,OAAa,EAAsB;QAC9D,OAAO,IAAIV,kBAAAA,CAAmB,QAAA,EAAUG,OAAAA,EAASO,OAAAA,CAAAA;AACrD;AAjCA,IAAA,WAAA,CACIC,SAAiD,EACjDR,OAAe,EACfO,OAAa,EACbL,UAAmB,CACrB;AACE,QAAA,KAAK,CAACF,OAAAA,CAAAA,EAVV,gBAAA,CAAA,IAAA,EAAgBQ,WAAAA,EAAhB,MAAA,CAAA,EACA,gBAAA,CAAA,IAAA,EAAgBD,SAAAA,EAAhB,MAAA,CAAA,EACA,gBAAA,CAAA,IAAA,EAAgBL,YAAAA,EAAhB,MAAA,CAAA;QASI,IAAI,CAACO,IAAI,GAAG,oBAAA;QACZ,IAAI,CAACD,SAAS,GAAGA,SAAAA;QACjB,IAAI,CAACD,OAAO,GAAGA,OAAAA;QACf,IAAI,CAACL,UAAU,GAAGA,UAAAA;AACtB;AAuBJ;;;;"}

package/dist/error/FileSystemError.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Error thrown when file system operations fail
+ */
+export declare class FileSystemError extends Error {
+    readonly errorType: 'not_found' | 'not_readable' | 'not_writable' | 'creation_failed' | 'operation_failed';
+    readonly path: string;
+    readonly operation: string;
+    readonly originalError?: Error;
+    constructor(errorType: 'not_found' | 'not_readable' | 'not_writable' | 'creation_failed' | 'operation_failed', message: string, path: string, operation: string, originalError?: Error);
+    /**
+     * Creates an error for when a required directory doesn't exist
+     */
+    static directoryNotFound(path: string, isRequired?: boolean): FileSystemError;
+    /**
+     * Creates an error for when a directory exists but isn't readable
+     */
+    static directoryNotReadable(path: string): FileSystemError;
+    /**
+     * Creates an error for directory creation failures
+     */
+    static directoryCreationFailed(path: string, originalError: Error): FileSystemError;
+    /**
+     * Creates an error for file operation failures (glob, etc.)
+     */
+    static operationFailed(operation: string, path: string, originalError: Error): FileSystemError;
+    /**
+     * Creates an error for when a file is not found
+     */
+    static fileNotFound(path: string): FileSystemError;
+}

package/dist/error/FileSystemError.js

@@ -0,0 +1,58 @@
+/**
+ * Error thrown when file system operations fail
+ */ function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+class FileSystemError extends Error {
+    /**
+     * Creates an error for when a required directory doesn't exist
+     */ static directoryNotFound(path, isRequired = false) {
+        const message = isRequired ? 'Configuration directory does not exist and is required' : 'Configuration directory not found';
+        return new FileSystemError('not_found', message, path, 'directory_access');
+    }
+    /**
+     * Creates an error for when a directory exists but isn't readable
+     */ static directoryNotReadable(path) {
+        const message = 'Configuration directory exists but is not readable';
+        return new FileSystemError('not_readable', message, path, 'directory_read');
+    }
+    /**
+     * Creates an error for directory creation failures
+     */ static directoryCreationFailed(path, originalError) {
+        const message = 'Failed to create directory: ' + (originalError.message || 'Unknown error');
+        return new FileSystemError('creation_failed', message, path, 'directory_create', originalError);
+    }
+    /**
+     * Creates an error for file operation failures (glob, etc.)
+     */ static operationFailed(operation, path, originalError) {
+        const message = `Failed to ${operation}: ${originalError.message || 'Unknown error'}`;
+        return new FileSystemError('operation_failed', message, path, operation, originalError);
+    }
+    /**
+     * Creates an error for when a file is not found
+     */ static fileNotFound(path) {
+        const message = 'Configuration file not found';
+        return new FileSystemError('not_found', message, path, 'file_read');
+    }
+    constructor(errorType, message, path, operation, originalError){
+        super(message), _define_property(this, "errorType", void 0), _define_property(this, "path", void 0), _define_property(this, "operation", void 0), _define_property(this, "originalError", void 0);
+        this.name = 'FileSystemError';
+        this.errorType = errorType;
+        this.path = path;
+        this.operation = operation;
+        this.originalError = originalError;
+    }
+}
+
+export { FileSystemError };
+//# sourceMappingURL=FileSystemError.js.map

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>;