@utilarium/cardigantime 0.0.24-dev.0

package/dist/mcp/integration.d.ts

@@ -0,0 +1,184 @@
+import { ZodSchema } from 'zod';
+import { MCPInvocationContext, ResolvedConfig } from './types';
+/**
+ * Options for creating MCP integration helpers.
+ */
+export interface MCPIntegrationOptions {
+    /**
+     * Application name (used in CheckConfig documentation links).
+     */
+    appName: string;
+    /**
+     * Zod schema for configuration validation.
+     */
+    configSchema: ZodSchema;
+    /**
+     * Base URL for documentation links.
+     * @default "https://github.com/utilarium/cardigantime"
+     */
+    docsBaseUrl?: string;
+    /**
+     * Function to resolve file-based configuration.
+     * Called when MCP config is not provided.
+     */
+    resolveFileConfig?: (workingDirectory: string) => Promise<any>;
+}
+/**
+ * Creates a CheckConfig tool handler for your MCP server.
+ *
+ * This is a convenience function that returns a ready-to-use handler
+ * for the CheckConfig tool. Register this with your MCP server to
+ * automatically provide configuration inspection capabilities.
+ *
+ * @param options - Integration options
+ * @returns Object with tool descriptor and handler
+ *
+ * @example
+ * ```typescript
+ * import { createCheckConfigTool } from '@utilarium/cardigantime/mcp';
+ *
+ * const checkConfigTool = createCheckConfigTool({
+ *   appName: 'myapp',
+ *   configSchema: myConfigSchema,
+ *   resolveFileConfig: async (dir) => loadMyConfig(dir),
+ * });
+ *
+ * // Register with your MCP server
+ * server.registerTool(
+ *   checkConfigTool.descriptor,
+ *   checkConfigTool.handler
+ * );
+ * ```
+ */
+export declare function createCheckConfigTool(options: MCPIntegrationOptions): {
+    descriptor: import('./tools').CheckConfigToolDescriptor;
+    handler: (input: any, context: MCPInvocationContext) => Promise<import('./tools').CheckConfigResult>;
+};
+/**
+ * Creates a configuration resolver for MCP tool handlers.
+ *
+ * This function returns a resolver that you can call at the beginning
+ * of your tool handlers to get the resolved configuration. It handles
+ * both MCP-provided config and file-based fallback.
+ *
+ * @param options - Integration options
+ * @returns Configuration resolver function
+ *
+ * @example
+ * ```typescript
+ * import { createConfigResolver } from '@utilarium/cardigantime/mcp';
+ *
+ * const resolveMyConfig = createConfigResolver({
+ *   appName: 'myapp',
+ *   configSchema: myConfigSchema,
+ *   resolveFileConfig: async (dir) => loadMyConfig(dir),
+ * });
+ *
+ * // In your tool handler
+ * async function myToolHandler(input: any, context: MCPInvocationContext) {
+ *   const config = await resolveMyConfig(context);
+ *
+ *   // Use config.config for the resolved configuration
+ *   console.log('Port:', config.config.port);
+ *
+ *   // ... rest of tool logic
+ * }
+ * ```
+ */
+export declare function createConfigResolver<T = unknown>(options: MCPIntegrationOptions): (context: MCPInvocationContext) => Promise<ResolvedConfig<T>>;
+/**
+ * Wraps a tool handler to automatically inject resolved configuration.
+ *
+ * This higher-order function wraps your tool handler and automatically
+ * resolves configuration before calling your handler. The resolved config
+ * is added to the context object.
+ *
+ * @param handler - Your tool handler function
+ * @param options - Integration options
+ * @returns Wrapped handler with config injection
+ *
+ * @example
+ * ```typescript
+ * import { withConfig } from '@utilarium/cardigantime/mcp';
+ *
+ * // Your tool handler
+ * async function myTool(input: any, context: any) {
+ *   // Config is automatically available in context
+ *   console.log('Port:', context.resolvedConfig.config.port);
+ *
+ *   return { result: 'success' };
+ * }
+ *
+ * // Wrap with config injection
+ * const wrappedHandler = withConfig(myTool, {
+ *   appName: 'myapp',
+ *   configSchema: myConfigSchema,
+ *   resolveFileConfig: async (dir) => loadMyConfig(dir),
+ * });
+ *
+ * // Register wrapped handler with your MCP server
+ * server.registerTool('my_tool', wrappedHandler);
+ * ```
+ */
+export declare function withConfig<TInput = any, TOutput = any, TConfig = unknown>(handler: (input: TInput, context: MCPInvocationContext & {
+    resolvedConfig: ResolvedConfig<TConfig>;
+}) => Promise<TOutput>, options: MCPIntegrationOptions): (input: TInput, context: MCPInvocationContext) => Promise<TOutput>;
+/**
+ * Creates a complete set of MCP integration helpers.
+ *
+ * This is a convenience function that returns all the integration helpers
+ * you need in one call. Use this if you want a complete integration setup.
+ *
+ * @param options - Integration options
+ * @returns Object with all integration helpers
+ *
+ * @example
+ * ```typescript
+ * import { createMCPIntegration } from '@utilarium/cardigantime/mcp';
+ *
+ * const integration = createMCPIntegration({
+ *   appName: 'myapp',
+ *   configSchema: myConfigSchema,
+ *   resolveFileConfig: async (dir) => loadMyConfig(dir),
+ * });
+ *
+ * // Register CheckConfig tool
+ * server.registerTool(
+ *   integration.checkConfig.descriptor,
+ *   integration.checkConfig.handler
+ * );
+ *
+ * // Use config resolver in your tools
+ * async function myTool(input: any, context: MCPInvocationContext) {
+ *   const config = await integration.resolveConfig(context);
+ *   // ... use config
+ * }
+ *
+ * // Or wrap your handlers with config injection
+ * const wrappedHandler = integration.withConfig(myToolHandler);
+ * server.registerTool('my_tool', wrappedHandler);
+ * ```
+ */
+export declare function createMCPIntegration<TConfig = unknown>(options: MCPIntegrationOptions): {
+    /**
+     * CheckConfig tool ready for registration.
+     */
+    checkConfig: {
+        descriptor: import('./tools').CheckConfigToolDescriptor;
+        handler: (input: any, context: MCPInvocationContext) => Promise<import('./tools').CheckConfigResult>;
+    };
+    /**
+     * Configuration resolver function.
+     */
+    resolveConfig: (context: MCPInvocationContext) => Promise<ResolvedConfig<TConfig>>;
+    /**
+     * Higher-order function to wrap handlers with config injection.
+     */
+    withConfig: <TInput = any, TOutput = any>(handler: (input: TInput, context: MCPInvocationContext & {
+        resolvedConfig: ResolvedConfig<TConfig>;
+    }) => Promise<TOutput>) => (input: TInput, context: MCPInvocationContext) => Promise<TOutput>;
+    /**
+     * Integration options (for reference).
+     */
+    options: MCPIntegrationOptions;
+};

package/dist/mcp/parser.d.ts

@@ -0,0 +1,141 @@
+import { ZodSchema } from 'zod';
+import { MCPConfigSource } from './types';
+/**
+ * Options for parsing MCP configuration.
+ */
+export interface ParseMCPConfigOptions {
+    /**
+     * Working directory for resolving relative paths.
+     * If not provided, paths are not resolved.
+     */
+    workingDirectory?: string;
+    /**
+     * Whether to expand environment variable references in string values.
+     * Environment variables are referenced as ${VAR_NAME} or $VAR_NAME.
+     *
+     * @default false
+     */
+    expandEnvVars?: boolean;
+    /**
+     * Fields that contain paths to be resolved relative to workingDirectory.
+     * Uses dot notation for nested fields (e.g., 'output.directory').
+     */
+    pathFields?: string[];
+}
+/**
+ * Parses and validates configuration received from MCP invocation.
+ *
+ * This function:
+ * - Validates the raw config against the provided Zod schema
+ * - Normalizes paths relative to the working directory
+ * - Optionally expands environment variable references
+ * - Returns a fully typed MCPConfigSource
+ *
+ * @template T - The Zod schema type
+ * @param rawConfig - The raw configuration object from MCP
+ * @param schema - Zod schema to validate against
+ * @param options - Optional parsing options
+ * @returns Promise resolving to a validated MCPConfigSource
+ * @throws {MCPConfigError} When validation fails or config is invalid
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   port: z.number(),
+ *   host: z.string(),
+ *   outputDir: z.string(),
+ * });
+ *
+ * const configSource = await parseMCPConfig(
+ *   { port: 3000, host: 'localhost', outputDir: './output' },
+ *   schema,
+ *   {
+ *     workingDirectory: '/app',
+ *     pathFields: ['outputDir'],
+ *   }
+ * );
+ *
+ * // configSource.config.outputDir is now '/app/output'
+ * ```
+ */
+export declare function parseMCPConfig<T extends ZodSchema>(rawConfig: unknown, schema: T, _options?: ParseMCPConfigOptions): Promise<MCPConfigSource>;
+/**
+ * Expands environment variable references in configuration values.
+ *
+ * Supports both ${VAR_NAME} and $VAR_NAME syntax.
+ * Only expands variables in string values.
+ *
+ * @param config - Configuration object to process
+ * @returns Configuration with environment variables expanded
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   host: '${HOST}',
+ *   port: 3000,
+ *   path: '$HOME/data',
+ * };
+ *
+ * const expanded = expandEnvironmentVariables(config);
+ * // { host: 'localhost', port: 3000, path: '/home/user/data' }
+ * ```
+ */
+export declare function expandEnvironmentVariables(config: any): any;
+/**
+ * Resolves relative paths in configuration to absolute paths.
+ *
+ * Paths are resolved relative to the provided working directory.
+ * Only processes fields specified in pathFields.
+ * Supports nested fields using dot notation.
+ *
+ * @param config - Configuration object to process
+ * @param workingDirectory - Base directory for resolving relative paths
+ * @param pathFields - Array of field paths to resolve (dot notation for nested)
+ * @returns Configuration with resolved paths
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   output: './dist',
+ *   nested: {
+ *     path: '../src',
+ *   },
+ * };
+ *
+ * const resolved = resolveConfigPaths(
+ *   config,
+ *   '/app',
+ *   ['output', 'nested.path']
+ * );
+ * // { output: '/app/dist', nested: { path: '/src' } }
+ * ```
+ */
+export declare function resolveConfigPaths(config: any, workingDirectory: string, pathFields: string[]): any;
+/**
+ * Merges MCP configuration with default values.
+ *
+ * This is useful when MCP provides partial configuration and you need
+ * to fill in missing fields with defaults.
+ *
+ * @template T - The configuration type
+ * @param mcpConfig - Configuration from MCP (may be partial)
+ * @param defaults - Default configuration values
+ * @returns Merged configuration with defaults applied
+ *
+ * @example
+ * ```typescript
+ * const defaults = {
+ *   port: 3000,
+ *   host: 'localhost',
+ *   timeout: 5000,
+ * };
+ *
+ * const mcpConfig = {
+ *   port: 8080,
+ * };
+ *
+ * const merged = mergeMCPConfigWithDefaults(mcpConfig, defaults);
+ * // { port: 8080, host: 'localhost', timeout: 5000 }
+ * ```
+ */
+export declare function mergeMCPConfigWithDefaults<T extends Record<string, any>>(mcpConfig: Partial<T>, defaults: T): T;

package/dist/mcp/resolver.d.ts

@@ -0,0 +1,165 @@
+import { ZodSchema } from 'zod';
+import { ResolvedConfig, MCPInvocationContext, FileConfigSource } from './types';
+import { ParseMCPConfigOptions } from './parser';
+import { Logger } from '../types';
+/**
+ * Options for resolving configuration from MCP, file, or environment variable sources.
+ */
+export interface ConfigResolverOptions {
+    /**
+     * Zod schema to validate configuration against.
+     */
+    schema: ZodSchema;
+    /**
+     * Options for parsing MCP configuration.
+     */
+    mcpOptions?: ParseMCPConfigOptions;
+    /**
+     * Logger for debugging and informational messages.
+     */
+    logger?: Logger;
+    /**
+     * Function to resolve configuration from files.
+     * This is called when MCP configuration is not provided.
+     *
+     * @param workingDirectory - Directory to start file discovery from
+     * @returns Promise resolving to a FileConfigSource
+     */
+    resolveFileConfig?: (workingDirectory: string) => Promise<FileConfigSource>;
+    /**
+     * Application name for environment variable prefix generation.
+     * Required if environment variable resolution is enabled.
+     *
+     * @example 'riotplan' generates env vars like RIOTPLAN_PLAN_DIRECTORY
+     */
+    appName?: string;
+    /**
+     * Custom environment variable name mappings.
+     * Maps config field names to custom env var names.
+     *
+     * @example { openaiApiKey: 'OPENAI_API_KEY' }
+     */
+    envVarMap?: Record<string, string>;
+    /**
+     * Disable environment variable resolution.
+     * When true, env vars are not checked even if appName is provided.
+     *
+     * @default false
+     */
+    disableEnvVars?: boolean;
+}
+/**
+ * Resolves configuration using the MCP priority model.
+ *
+ * **Priority Model:**
+ * 1. If MCP config is present → use it exclusively
+ * 2. If MCP config is absent → try file-based discovery
+ * 3. If no file config found → try environment variables
+ * 4. No merging between sources
+ *
+ * This priority model makes configuration predictable and debuggable.
+ * Each source is checked in order, and the first one found is used exclusively.
+ *
+ * @template T - The configuration type
+ * @param context - MCP invocation context
+ * @param options - Resolution options including schema and resolvers
+ * @returns Promise resolving to a ResolvedConfig with source tracking
+ * @throws {MCPContextError} When no configuration source is available
+ * @throws {MCPConfigError} When MCP config is invalid
+ *
+ * @example
+ * ```typescript
+ * const context: MCPInvocationContext = {
+ *   config: { port: 3000, host: 'localhost' },
+ *   workingDirectory: '/app',
+ * };
+ *
+ * const resolved = await resolveConfig(context, {
+ *   schema: myConfigSchema,
+ *   appName: 'myapp',
+ *   logger: console,
+ * });
+ *
+ * console.log(resolved.resolution); // "Configuration loaded from MCP invocation"
+ * ```
+ */
+export declare function resolveConfig<T = unknown>(context: MCPInvocationContext, options: ConfigResolverOptions): Promise<ResolvedConfig<T>>;
+/**
+ * Generates a human-readable explanation of how configuration was resolved.
+ *
+ * This is useful for:
+ * - Debugging configuration issues
+ * - The CheckConfig tool
+ * - User-facing error messages
+ *
+ * @param resolved - The resolved configuration
+ * @returns Human-readable explanation string
+ *
+ * @example
+ * ```typescript
+ * const explanation = explainResolution(resolved);
+ * // "Configuration loaded from MCP invocation"
+ * // "Configuration loaded from /app/config.yaml"
+ * // "Configuration merged from 3 files: /app/config.yaml, /app/src/config.yaml, /app/src/api/config.yaml"
+ * // "Configuration loaded from 5 environment variables"
+ * ```
+ */
+export declare function explainResolution(resolved: ResolvedConfig): string;
+/**
+ * Checks if a configuration was loaded from MCP.
+ *
+ * @param resolved - The resolved configuration
+ * @returns True if configuration came from MCP
+ *
+ * @example
+ * ```typescript
+ * if (isMCPConfig(resolved)) {
+ *   console.log('Using MCP-provided configuration');
+ * }
+ * ```
+ */
+export declare function isMCPConfig(resolved: ResolvedConfig): boolean;
+/**
+ * Checks if a configuration was loaded from files.
+ *
+ * @param resolved - The resolved configuration
+ * @returns True if configuration came from files
+ *
+ * @example
+ * ```typescript
+ * if (isFileConfig(resolved)) {
+ *   console.log(`Config file: ${resolved.source.filePath}`);
+ * }
+ * ```
+ */
+export declare function isFileConfig(resolved: ResolvedConfig): boolean;
+/**
+ * Checks if a configuration was loaded from environment variables.
+ *
+ * @param resolved - The resolved configuration
+ * @returns True if configuration came from environment variables
+ *
+ * @example
+ * ```typescript
+ * if (isEnvConfig(resolved)) {
+ *   console.log(`Config from ${resolved.source.variables.size} env vars`);
+ * }
+ * ```
+ */
+export declare function isEnvConfig(resolved: ResolvedConfig): boolean;
+/**
+ * Gets the list of all configuration files that contributed to the resolved config.
+ *
+ * For MCP configs, returns an empty array.
+ * For file configs, returns the main file and all parent files.
+ *
+ * @param resolved - The resolved configuration
+ * @returns Array of file paths
+ *
+ * @example
+ * ```typescript
+ * const files = getConfigFiles(resolved);
+ * console.log('Config loaded from:', files.join(', '));
+ * ```
+ */
+export declare function getConfigFiles(resolved: ResolvedConfig): string[];

package/dist/mcp/tools/check-config-types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Type definitions for the CheckConfig MCP tool.
+ *
+ * CheckConfig is a built-in diagnostic tool available in all CardiganTime-based
+ * MCP servers. It helps AI assistants understand how a tool is configured.
+ *
+ * @module mcp/tools/check-config
+ */
+/**
+ * Input parameters for the CheckConfig tool.
+ */
+export interface CheckConfigInput {
+    /**
+     * Optional file path to check configuration for.
+     *
+     * When provided, the tool will determine the most relevant configuration
+     * for this specific file (useful in hierarchical mode).
+     *
+     * @example "/app/src/api/handler.ts"
+     */
+    targetFile?: string;
+    /**
+     * Whether to include detailed configuration breakdown.
+     *
+     * When true, includes:
+     * - All config sources that were checked
+     * - Merge order (if hierarchical)
+     * - Which values came from which source
+     *
+     * @default false
+     */
+    verbose?: boolean;
+    /**
+     * Whether to include the full resolved configuration.
+     *
+     * When false, only shows a summary without the actual config values.
+     * Useful when you only need to know where config comes from.
+     *
+     * @default true
+     */
+    includeConfig?: boolean;
+}
+/**
+ * Source type for configuration.
+ */
+export type ConfigSourceType = 'mcp' | 'file' | 'env' | 'defaults';
+/**
+ * Information about a configuration value's source.
+ */
+export interface ConfigValueSource {
+    /**
+     * The configuration field path (dot notation).
+     * @example "server.port"
+     */
+    field: string;
+    /**
+     * The value of the field (sanitized if sensitive).
+     */
+    value: unknown;
+    /**
+     * Where this value came from.
+     */
+    source: string;
+    /**
+     * Whether this value was sanitized for security.
+     */
+    sanitized: boolean;
+}
+/**
+ * Result of the CheckConfig tool.
+ */
+export interface CheckConfigResult {
+    /**
+     * Where the configuration came from.
+     */
+    source: ConfigSourceType;
+    /**
+     * If file-based, the path(s) to configuration files.
+     * Ordered from most specific (closest) to least specific (furthest).
+     */
+    configPaths?: string[];
+    /**
+     * Whether hierarchical configuration lookup was used.
+     */
+    hierarchical: boolean;
+    /**
+     * The resolved configuration (with sensitive values sanitized).
+     * Only included if includeConfig is true.
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Detailed breakdown of where each config value came from.
+     * Only included in verbose mode.
+     */
+    valueBreakdown?: ConfigValueSource[];
+    /**
+     * Human-readable summary of the configuration.
+     *
+     * @example "Configuration loaded from MCP invocation"
+     * @example "Configuration merged from 3 files: /app/config.yaml, /app/src/config.yaml, /app/src/api/config.yaml"
+     */
+    summary: string;
+    /**
+     * Links to relevant documentation.
+     */
+    documentation: {
+        /**
+         * Link to configuration guide.
+         */
+        configGuide: string;
+        /**
+         * Link to format reference (YAML, JSON, JS, TS).
+         */
+        formatReference: string;
+        /**
+         * Link to MCP integration guide.
+         */
+        mcpGuide: string;
+    };
+    /**
+     * Warnings or issues detected in the configuration.
+     */
+    warnings?: string[];
+}
+/**
+ * MCP tool descriptor for CheckConfig.
+ *
+ * This follows the MCP protocol specification for tool definitions.
+ */
+export interface CheckConfigToolDescriptor {
+    /**
+     * Tool name (always 'check_config').
+     */
+    name: 'check_config';
+    /**
+     * Human-readable description of what the tool does.
+     */
+    description: string;
+    /**
+     * JSON Schema for the tool's input parameters.
+     */
+    inputSchema: {
+        type: 'object';
+        properties: {
+            targetFile?: {
+                type: 'string';
+                description: string;
+            };
+            verbose?: {
+                type: 'boolean';
+                description: string;
+                default: boolean;
+            };
+            includeConfig?: {
+                type: 'boolean';
+                description: string;
+                default: boolean;
+            };
+        };
+        additionalProperties: boolean;
+    };
+}
+/**
+ * Standard CheckConfig tool descriptor.
+ *
+ * This can be used directly when registering the tool with an MCP server.
+ *
+ * @example
+ * ```typescript
+ * server.registerTool(CHECK_CONFIG_TOOL_DESCRIPTOR, async (input) => {
+ *   return await checkConfig(input);
+ * });
+ * ```
+ */
+export declare const CHECK_CONFIG_TOOL_DESCRIPTOR: CheckConfigToolDescriptor;
+/**
+ * Patterns for detecting sensitive configuration fields.
+ *
+ * These patterns are used to sanitize sensitive values in CheckConfig output.
+ */
+export declare const SENSITIVE_FIELD_PATTERNS: RegExp[];
+/**
+ * Checks if a field name indicates sensitive data.
+ *
+ * @param fieldName - The field name to check
+ * @returns True if the field appears to contain sensitive data
+ *
+ * @example
+ * ```typescript
+ * isSensitiveField('apiKey'); // true
+ * isSensitiveField('password'); // true
+ * isSensitiveField('port'); // false
+ * ```
+ */
+export declare function isSensitiveField(fieldName: string): boolean;
+/**
+ * Sanitizes a sensitive value for display.
+ *
+ * @param value - The value to sanitize
+ * @returns Sanitized value (e.g., "***")
+ *
+ * @example
+ * ```typescript
+ * sanitizeValue('my-secret-key'); // "***"
+ * sanitizeValue(12345); // "***"
+ * ```
+ */
+export declare function sanitizeValue(_value: unknown): string;