@utilarium/cardigantime 0.0.24-dev.0

package/dist/env/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Configuration for environment variable naming
+ */
+export interface EnvVarNamingConfig {
+    /** Application name used as prefix (e.g., 'riotplan') */
+    appName: string;
+    /** Custom env var name overrides */
+    envVarMap?: Record<string, string>;
+}
+/**
+ * Result of env var name generation
+ */
+export interface EnvVarName {
+    /** Full env var name (e.g., 'RIOTPLAN_PLAN_DIRECTORY') */
+    name: string;
+    /** Field path in config (e.g., 'planDirectory' or ['api', 'key']) */
+    fieldPath: string | string[];
+    /** Whether this is a custom override */
+    isCustom: boolean;
+}
+/**
+ * Result of reading an environment variable
+ */
+export interface EnvVarReadResult {
+    /** Full env var name that was read */
+    envVarName: string;
+    /** Value from process.env (undefined if not set) */
+    value: string | undefined;
+    /** Whether this used a custom mapping */
+    isCustom: boolean;
+    /** Field path in config */
+    fieldPath: string | string[];
+}
+/**
+ * Source information for env var config
+ */
+export interface EnvVarConfigSource {
+    type: 'env';
+    /** Map of field paths to env var read results */
+    values: Map<string, EnvVarReadResult>;
+    /** When the env vars were read */
+    readAt: Date;
+}

package/dist/error/ArgumentError.d.ts

@@ -0,0 +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 @@
+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;
+}
+/**
+ * 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"
+ * ```
+ */ 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;;;;;;;;;;;;;IAcO,MAAMA,aAAAA,SAAsBC,KAAAA,CAAAA;AAgB/B;;;;AAIC,QACD,IAAIC,QAAAA,GAAmB;QACnB,OAAO,IAAI,CAACC,YAAY;AAC5B,IAAA;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,IAAA;AAUJ;;;;"}

package/dist/error/ConfigParseError.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Error thrown when configuration file parsing fails.
+ * Provides detailed information about what went wrong during parsing.
+ */
+export declare class ConfigParseError extends Error {
+    /**
+     * The file path where the parse error occurred
+     */
+    readonly filePath: string;
+    /**
+     * The original error that caused the parse failure
+     */
+    readonly cause?: Error;
+    /**
+     * Creates a new ConfigParseError.
+     *
+     * @param message - Human-readable error message
+     * @param filePath - Path to the configuration file that failed to parse
+     * @param cause - Optional underlying error that caused the parse failure
+     */
+    constructor(message: string, filePath: string, cause?: Error);
+    /**
+     * Returns a detailed error message including file path and cause.
+     */
+    toString(): string;
+}

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 @@
+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;
+}
+/**
+ * Error thrown when configuration validation fails
+ */ 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;;IAGO,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,IAAA;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,IAAA;AAEA;;AAEC,QACD,OAAOI,MAAAA,CAAON,OAAe,EAAEO,OAAa,EAAsB;QAC9D,OAAO,IAAIV,kBAAAA,CAAmB,QAAA,EAAUG,OAAAA,EAASO,OAAAA,CAAAA;AACrD,IAAA;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,IAAA;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 @@
+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;
+}
+/**
+ * Error thrown when file system operations fail
+ */ 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;;IAGO,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,IAAA;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,IAAA;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,IAAA;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,IAAA;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,IAAA;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,IAAA;AA2CJ;;;;"}

package/dist/error/index.d.ts

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

package/dist/mcp/discovery.d.ts

@@ -0,0 +1,105 @@
+import { Cardigantime } from '../types';
+import { FileConfigSource } from './types';
+/**
+ * Options for file-based configuration discovery.
+ */
+export interface FileDiscoveryOptions {
+    /**
+     * CardiganTime instance to use for discovery.
+     * This provides access to the full configuration discovery functionality.
+     */
+    cardigantime: Cardigantime<any>;
+    /**
+     * Arguments to pass to CardiganTime's read function.
+     * These typically come from CLI parsing.
+     */
+    args?: Record<string, any>;
+}
+/**
+ * Discovers configuration starting from a target file's location.
+ *
+ * This implements the "detective work" pattern where the tool looks at
+ * the target file's location and walks up the directory tree to find
+ * configuration files.
+ *
+ * @param targetFile - Path to the target file being operated on
+ * @param options - Discovery options
+ * @returns Promise resolving to FileConfigSource or null if not found
+ *
+ * @example
+ * ```typescript
+ * const config = await discoverFromTargetFile(
+ *   '/app/src/api/handler.ts',
+ *   { cardigantime: myCardiganTimeInstance }
+ * );
+ *
+ * if (config) {
+ *   console.log('Found config at:', config.filePath);
+ * }
+ * ```
+ */
+export declare function discoverFromTargetFile(targetFile: string, options: FileDiscoveryOptions): Promise<FileConfigSource | null>;
+/**
+ * Discovers configuration starting from a working directory.
+ *
+ * This is the fallback when no target file is specified. It starts
+ * discovery from the working directory provided by the MCP invocation.
+ *
+ * @param workingDirectory - Working directory to start discovery from
+ * @param options - Discovery options
+ * @returns Promise resolving to FileConfigSource or null if not found
+ *
+ * @example
+ * ```typescript
+ * const config = await discoverFromWorkingDirectory(
+ *   '/app',
+ *   { cardigantime: myCardiganTimeInstance }
+ * );
+ * ```
+ */
+export declare function discoverFromWorkingDirectory(workingDirectory: string, options: FileDiscoveryOptions): Promise<FileConfigSource | null>;
+/**
+ * Creates a file discovery function for use with the MCP resolver.
+ *
+ * This is a convenience function that creates a `resolveFileConfig` function
+ * compatible with the MCP resolver. It automatically tries target file
+ * discovery first, then falls back to working directory discovery.
+ *
+ * @param options - Discovery options
+ * @returns File config resolver function
+ *
+ * @example
+ * ```typescript
+ * import { createFileDiscovery } from '@utilarium/cardigantime/mcp';
+ * import { createMCPIntegration } from '@utilarium/cardigantime/mcp';
+ *
+ * const fileDiscovery = createFileDiscovery({
+ *   cardigantime: myCardiganTimeInstance,
+ * });
+ *
+ * const integration = createMCPIntegration({
+ *   appName: 'myapp',
+ *   configSchema: mySchema,
+ *   resolveFileConfig: fileDiscovery,
+ * });
+ * ```
+ */
+export declare function createFileDiscovery(options: FileDiscoveryOptions): (workingDirectory: string, targetFile?: string) => Promise<FileConfigSource | null>;
+/**
+ * Logs the configuration discovery process.
+ *
+ * This is useful for debugging configuration issues. It shows which
+ * directories were checked and why a particular config was selected.
+ *
+ * @param message - Log message
+ * @param details - Additional details to log
+ *
+ * @example
+ * ```typescript
+ * logDiscovery('Checking for config', {
+ *   directory: '/app/src',
+ *   found: true,
+ * });
+ * ```
+ */
+export declare function logDiscovery(message: string, details?: Record<string, any>): void;

package/dist/mcp/errors.d.ts

@@ -0,0 +1,75 @@
+import { ZodError } from 'zod';
+/**
+ * Error thrown when MCP configuration is invalid or cannot be parsed.
+ *
+ * This error is thrown when:
+ * - The MCP configuration doesn't match the expected schema
+ * - Required fields are missing
+ * - Field values are invalid
+ *
+ * The error includes the original Zod validation error for detailed diagnostics.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await parseMCPConfig(rawConfig, schema);
+ * } catch (error) {
+ *   if (error instanceof MCPConfigError) {
+ *     console.error('MCP config validation failed:', error.message);
+ *     if (error.validationError) {
+ *       console.error('Details:', error.validationError.format());
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class MCPConfigError extends Error {
+    readonly validationError?: ZodError | undefined;
+    /**
+     * The name of the error class.
+     * Always set to 'MCPConfigError'.
+     */
+    readonly name = "MCPConfigError";
+    /**
+     * Creates a new MCPConfigError.
+     *
+     * @param message - Human-readable error message
+     * @param validationError - Optional Zod validation error with detailed field-level errors
+     */
+    constructor(message: string, validationError?: ZodError | undefined);
+    /**
+     * Returns a formatted error message including validation details.
+     *
+     * @returns Formatted error message with validation issues
+     */
+    getDetailedMessage(): string;
+}
+/**
+ * Error thrown when MCP invocation context is missing required information.
+ *
+ * This error is thrown when:
+ * - Neither MCP config nor working directory is provided
+ * - Required context fields are missing for the operation
+ *
+ * @example
+ * ```typescript
+ * if (!context.config && !context.workingDirectory) {
+ *   throw new MCPContextError(
+ *     'MCP invocation must provide either config or workingDirectory'
+ *   );
+ * }
+ * ```
+ */
+export declare class MCPContextError extends Error {
+    /**
+     * The name of the error class.
+     * Always set to 'MCPContextError'.
+     */
+    readonly name = "MCPContextError";
+    /**
+     * Creates a new MCPContextError.
+     *
+     * @param message - Human-readable error message
+     */
+    constructor(message: string);
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * MCP (Model Context Protocol) integration module.
+ *
+ * This module provides types and utilities for integrating CardiganTime
+ * with MCP servers, enabling AI assistants to provide configuration
+ * to tools at invocation time.
+ *
+ * @module mcp
+ */
+export type { MCPConfigSource, FileConfigSource, EnvVarConfigSource, ConfigSource, ResolvedConfig, MCPInvocationContext, } from './types';
+export { MCPConfigError, MCPContextError, } from './errors';
+export { parseMCPConfig, expandEnvironmentVariables, resolveConfigPaths, mergeMCPConfigWithDefaults, } from './parser';
+export type { ParseMCPConfigOptions, } from './parser';
+export { resolveConfig, explainResolution, isMCPConfig, isFileConfig, isEnvConfig, getConfigFiles, } from './resolver';
+export type { ConfigResolverOptions, } from './resolver';
+export type { CheckConfigInput, CheckConfigResult, CheckConfigToolDescriptor, ConfigSourceType, ConfigValueSource, } from './tools';
+export { CHECK_CONFIG_TOOL_DESCRIPTOR, SENSITIVE_FIELD_PATTERNS, isSensitiveField, sanitizeValue, checkConfig, sanitizeConfig, createCheckConfigHandler, } from './tools';
+export type { CheckConfigOptions, } from './tools';
+export { createCheckConfigTool, createConfigResolver, withConfig, createMCPIntegration, } from './integration';
+export type { MCPIntegrationOptions, } from './integration';
+export { discoverFromTargetFile, discoverFromWorkingDirectory, createFileDiscovery, logDiscovery, } from './discovery';
+export type { FileDiscoveryOptions, } from './discovery';