@utilarium/cardigantime 0.0.24-dev.0

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

@@ -0,0 +1,85 @@
+import { ZodSchema } from 'zod';
+import { MCPInvocationContext } from '../types';
+import { CheckConfigInput, CheckConfigResult } from './check-config-types';
+/**
+ * Options for the CheckConfig tool.
+ */
+export interface CheckConfigOptions {
+    /**
+     * Application name for documentation links.
+     */
+    appName: string;
+    /**
+     * Zod schema for configuration validation.
+     */
+    schema: ZodSchema;
+    /**
+     * Base URL for documentation.
+     * @default "https://github.com/utilarium/cardigantime"
+     */
+    docsBaseUrl?: string;
+    /**
+     * Function to resolve file-based configuration.
+     * Required when MCP config is not provided.
+     */
+    resolveFileConfig?: (workingDirectory: string) => Promise<any>;
+}
+/**
+ * Implements the CheckConfig tool for MCP servers.
+ *
+ * This tool helps AI assistants understand how a tool is configured by:
+ * - Showing where configuration came from (MCP, file, or defaults)
+ * - Displaying the resolved configuration (with sensitive values sanitized)
+ * - Providing links to relevant documentation
+ * - Optionally showing detailed breakdown of config sources
+ *
+ * @param input - Tool input parameters
+ * @param context - MCP invocation context
+ * @param options - Tool configuration options
+ * @returns Promise resolving to CheckConfigResult
+ *
+ * @example
+ * ```typescript
+ * const result = await checkConfig(
+ *   { verbose: true },
+ *   { config: { port: 3000 } },
+ *   { appName: 'myapp', schema: mySchema }
+ * );
+ *
+ * console.log(result.summary);
+ * // "Configuration loaded from MCP invocation"
+ * ```
+ */
+export declare function checkConfig(input: CheckConfigInput, context: MCPInvocationContext, options: CheckConfigOptions): Promise<CheckConfigResult>;
+/**
+ * Sanitizes a configuration object by masking sensitive values.
+ *
+ * Recursively walks through the configuration and replaces sensitive
+ * values with "***" to prevent accidental exposure.
+ *
+ * @param config - Configuration object to sanitize
+ * @param path - Current path in the object (for nested fields)
+ * @returns Sanitized configuration object
+ */
+export declare function sanitizeConfig(config: Record<string, unknown>, path?: string): Record<string, unknown>;
+/**
+ * Creates a CheckConfig tool handler for MCP servers.
+ *
+ * This is a convenience function that returns a handler function
+ * ready to be registered with an MCP server.
+ *
+ * @param options - Tool configuration options
+ * @returns Tool handler function
+ *
+ * @example
+ * ```typescript
+ * const handler = createCheckConfigHandler({
+ *   appName: 'myapp',
+ *   schema: myConfigSchema,
+ *   resolveFileConfig: async (dir) => loadConfig(dir),
+ * });
+ *
+ * server.registerTool('check_config', handler);
+ * ```
+ */
+export declare function createCheckConfigHandler(options: CheckConfigOptions): (input: CheckConfigInput, context: MCPInvocationContext) => Promise<CheckConfigResult>;

package/dist/mcp/tools/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * MCP tools module.
+ *
+ * This module exports built-in MCP tools that are automatically available
+ * in all CardiganTime-based MCP servers.
+ *
+ * @module mcp/tools
+ */
+export type { CheckConfigInput, CheckConfigResult, CheckConfigToolDescriptor, ConfigSourceType, ConfigValueSource, } from './check-config-types';
+export { CHECK_CONFIG_TOOL_DESCRIPTOR, SENSITIVE_FIELD_PATTERNS, isSensitiveField, sanitizeValue, } from './check-config-types';
+export { checkConfig, sanitizeConfig, createCheckConfigHandler, } from './check-config';
+export type { CheckConfigOptions, } from './check-config';

package/dist/mcp/types.d.ts

@@ -0,0 +1,210 @@
+import { ConfigFormat } from '../types';
+/**
+ * Configuration source from an MCP (Model Context Protocol) server invocation.
+ *
+ * MCP servers receive configuration as JSON in the server invocation context.
+ * This type tracks the raw configuration received from the MCP environment
+ * and when it was received.
+ *
+ * @example
+ * ```typescript
+ * const mcpSource: MCPConfigSource = {
+ *   type: 'mcp',
+ *   rawConfig: { features: ['validation'], maxRetries: 3 },
+ *   receivedAt: new Date(),
+ * };
+ * ```
+ */
+export interface MCPConfigSource {
+    /** Source type discriminator */
+    type: 'mcp';
+    /**
+     * The raw JSON configuration received from the MCP invocation.
+     * This is the unparsed, unvalidated configuration object.
+     */
+    rawConfig: unknown;
+    /**
+     * Timestamp when the configuration was received from the MCP server.
+     * Used for debugging and cache invalidation.
+     */
+    receivedAt: Date;
+}
+/**
+ * Configuration source from a file on the filesystem.
+ *
+ * File-based configuration is the traditional way of providing config,
+ * supporting multiple formats (YAML, JSON, JavaScript, TypeScript).
+ * This type tracks the file path, format, and optional parent configs
+ * in hierarchical mode.
+ *
+ * @example
+ * ```typescript
+ * const fileSource: FileConfigSource = {
+ *   type: 'file',
+ *   filePath: '/project/app.config.yaml',
+ *   format: ConfigFormat.YAML,
+ *   parents: [parentConfigSource],
+ * };
+ * ```
+ */
+export interface FileConfigSource {
+    /** Source type discriminator */
+    type: 'file';
+    /**
+     * Absolute path to the configuration file.
+     */
+    filePath: string;
+    /**
+     * The format of the configuration file.
+     */
+    format: ConfigFormat;
+    /**
+     * Parent configuration sources in hierarchical mode.
+     * These are configs from parent directories that were merged.
+     * Ordered from most specific (closest) to least specific (furthest).
+     */
+    parents?: FileConfigSource[];
+}
+/**
+ * Configuration source from environment variables.
+ *
+ * Environment variables provide a system-wide way to configure applications.
+ * This type tracks which environment variables were read and their values.
+ *
+ * @example
+ * ```typescript
+ * const envSource: EnvVarConfigSource = {
+ *   type: 'env',
+ *   variables: new Map([
+ *     ['MYAPP_PORT', { value: '3000', isCustom: false }],
+ *     ['OPENAI_API_KEY', { value: 'sk-...', isCustom: true }],
+ *   ]),
+ *   readAt: new Date(),
+ * };
+ * ```
+ */
+export interface EnvVarConfigSource {
+    /** Source type discriminator */
+    type: 'env';
+    /**
+     * Map of environment variable names to their values.
+     * Keys are the actual env var names (e.g., 'MYAPP_PORT').
+     * Values indicate whether custom mapping was used.
+     */
+    variables: Map<string, {
+        value: string;
+        isCustom: boolean;
+    }>;
+    /**
+     * Timestamp when the environment variables were read.
+     * Used for debugging and cache invalidation.
+     */
+    readAt: Date;
+}
+/**
+ * Union type representing all possible configuration sources.
+ *
+ * Configuration can come from:
+ * - MCP server invocation (for AI assistant tools)
+ * - File on the filesystem (traditional config files)
+ * - Environment variables (system-wide configuration)
+ *
+ * Use the `type` discriminator to determine which source type you have.
+ *
+ * @example
+ * ```typescript
+ * function handleConfig(source: ConfigSource) {
+ *   if (source.type === 'mcp') {
+ *     console.log('Config from MCP:', source.rawConfig);
+ *   } else if (source.type === 'file') {
+ *     console.log('Config from file:', source.filePath);
+ *   } else {
+ *     console.log('Config from env vars:', source.variables.size);
+ *   }
+ * }
+ * ```
+ */
+export type ConfigSource = MCPConfigSource | FileConfigSource | EnvVarConfigSource;
+/**
+ * A fully resolved configuration with source tracking.
+ *
+ * This type represents the final configuration after all parsing,
+ * validation, and merging has been completed. It includes metadata
+ * about where the configuration came from and how it was resolved.
+ *
+ * @template T - The type of the parsed configuration object
+ *
+ * @example
+ * ```typescript
+ * const resolved: ResolvedConfig<AppConfig> = {
+ *   source: { type: 'file', filePath: '/app/config.yaml', format: ConfigFormat.YAML },
+ *   config: { port: 3000, host: 'localhost' },
+ *   hierarchical: true,
+ *   resolution: 'Merged 3 configs from /app, /app/src, /app/src/api',
+ * };
+ * ```
+ */
+export interface ResolvedConfig<T = unknown> {
+    /**
+     * The source of the configuration (MCP or file).
+     */
+    source: ConfigSource;
+    /**
+     * The parsed and validated configuration object.
+     */
+    config: T;
+    /**
+     * Whether hierarchical configuration lookup was used.
+     * True if multiple configs were merged from parent directories.
+     */
+    hierarchical: boolean;
+    /**
+     * Human-readable explanation of how the configuration was resolved.
+     * Useful for debugging and the checkConfig tool.
+     *
+     * @example "Config from MCP invocation"
+     * @example "Merged 2 configs: /project/config.yaml, /project/src/config.yaml"
+     * @example "Single config from /app/.myapprc.json"
+     */
+    resolution: string;
+}
+/**
+ * Context information provided by MCP server invocations.
+ *
+ * When an MCP tool is invoked by an AI assistant (like Claude in Cursor),
+ * the invocation includes contextual information about the environment.
+ * This type captures that context.
+ *
+ * @example
+ * ```typescript
+ * // MCP tool invocation from Cursor
+ * const context: MCPInvocationContext = {
+ *   workingDirectory: '/Users/dev/project',
+ *   targetFile: '/Users/dev/project/src/index.ts',
+ *   config: {
+ *     features: ['validation'],
+ *     maxRetries: 3,
+ *   },
+ * };
+ * ```
+ */
+export interface MCPInvocationContext {
+    /**
+     * Working directory for file operations.
+     * This is typically the current working directory in the AI assistant's context.
+     * Used as the starting point for hierarchical config discovery.
+     */
+    workingDirectory?: string;
+    /**
+     * The specific file being operated on.
+     * For tools like Protokoll that operate on files, this is the target file path.
+     * Used to determine the most relevant configuration.
+     */
+    targetFile?: string;
+    /**
+     * MCP-provided configuration object.
+     * This is the raw configuration passed by the AI assistant environment.
+     * Must be parsed and validated before use.
+     */
+    config?: unknown;
+}

package/dist/parsers/index.d.ts

@@ -0,0 +1,25 @@
+import { ConfigFormat, ConfigParser } from '../types';
+/**
+ * Gets a parser for a given file extension.
+ *
+ * @param extension - File extension (e.g., '.json', '.yaml')
+ * @returns The parser for this extension, or undefined if not found
+ */
+export declare function getParserForExtension(extension: string): ConfigParser | undefined;
+/**
+ * Gets a parser for a given format.
+ *
+ * @param format - Configuration format
+ * @returns The parser for this format, or undefined if not found
+ */
+export declare function getParserForFormat(format: ConfigFormat): ConfigParser | undefined;
+/**
+ * Gets all registered parsers.
+ *
+ * @returns Array of all registered parsers
+ */
+export declare function getAllParsers(): ConfigParser[];
+export { jsonParser } from './json-parser';
+export { yamlParser } from './yaml-parser';
+export { javascriptParser } from './javascript-parser';
+export { typescriptParser } from './typescript-parser';

package/dist/parsers/javascript-parser.d.ts

@@ -0,0 +1,12 @@
+import { ConfigParser } from '../types';
+/**
+ * JavaScript configuration parser.
+ * Loads and executes JavaScript configuration files using dynamic import.
+ *
+ * Supports:
+ * - ESM default exports: `export default { ... }`
+ * - CommonJS exports: `module.exports = { ... }`
+ * - Async function exports: `export default async () => ({ ... })`
+ * - Named exports as fallback
+ */
+export declare const javascriptParser: ConfigParser;

package/dist/parsers/json-parser.d.ts

@@ -0,0 +1,6 @@
+import { ConfigParser } from '../types';
+/**
+ * JSON configuration parser.
+ * Parses configuration from .json files using native JSON.parse.
+ */
+export declare const jsonParser: ConfigParser;

package/dist/parsers/typescript-parser.d.ts

@@ -0,0 +1,15 @@
+import { ConfigParser } from '../types';
+/**
+ * TypeScript configuration parser.
+ * Loads and executes TypeScript configuration files using dynamic import.
+ *
+ * IMPORTANT: TypeScript files must be transpiled before they can be imported.
+ * This parser relies on a TypeScript runtime being available (tsx, ts-node, etc.)
+ * or the files being pre-compiled to JavaScript.
+ *
+ * Supports:
+ * - ESM default exports: `export default { ... }`
+ * - Async function exports: `export default async () => ({ ... })`
+ * - Type-safe configs with defineConfig helper
+ */
+export declare const typescriptParser: ConfigParser;

package/dist/parsers/yaml-parser.d.ts

@@ -0,0 +1,6 @@
+import { ConfigParser } from '../types';
+/**
+ * YAML configuration parser.
+ * Parses configuration from .yaml and .yml files using js-yaml.
+ */
+export declare const yamlParser: ConfigParser;

package/dist/read.d.ts

@@ -0,0 +1,56 @@
+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>>>;
+/**
+ * Checks and displays the resolved configuration with detailed source tracking.
+ *
+ * This function provides a git blame-like view of configuration resolution,
+ * showing which file and hierarchical level contributed each configuration value.
+ *
+ * @template T - The Zod schema shape type for configuration validation
+ * @param args - Parsed command-line arguments
+ * @param options - Cardigantime options with defaults, schema, and logger
+ * @returns Promise that resolves when the configuration check is complete
+ *
+ * @example
+ * ```typescript
+ * await checkConfig(cliArgs, {
+ *   defaults: { configDirectory: './config', configFile: 'app.yaml' },
+ *   configShape: MySchema.shape,
+ *   logger: console,
+ *   features: ['config', 'hierarchical']
+ * });
+ * // Outputs detailed configuration source analysis
+ * ```
+ */
+export declare const checkConfig: <T extends z.ZodRawShape>(args: Args, options: Options<T>) => Promise<void>;