Configuration System

Relevant source files

The following files were used as context for generating this wiki page:

• src/config/mod.rs
• src/config/schema.rs
• tests/config_contract.rs
• specs/003-implement-core-infrastructure/spec.md
• specs/006-intelligent-prompt-generation/spec.md
• specs/003-implement-core-infrastructure/tasks.md

The caro configuration system is a core infrastructure module responsible for managing all user preferences and operational parameters. It provides a flexible and layered approach to settings management, allowing users to configure the tool via a persistent TOML file while enabling overrides through command-line arguments. The system is designed to be robust, with built-in validation, sensible defaults, and clear error handling.

The primary goals of the configuration system are to persist user preferences for settings like safety level, default shell, and model choice, and to ensure that the application can be configured for different environments and use cases, including cross-platform command generation. It uses a human-readable TOML file format and respects platform-specific directory conventions, such as the XDG Base Directory specification.

Sources: specs/003-implement-core-infrastructure/spec.md:21-31, 84-91, specs/006-intelligent-prompt-generation/spec.md:310-316

Architecture and Data Flow

The configuration system is built around the ConfigManager, which orchestrates the loading, merging, and validation of settings. It follows a clear hierarchical loading strategy to ensure that the most specific settings take precedence.

Sources: specs/003-implement-core-infrastructure/spec.md:88-91, tests/config_contract.rs

Configuration Loading Hierarchy

Settings are loaded and merged in a specific order, with later sources overriding earlier ones. This provides a flexible system where global defaults can be overridden by user-specific files, which can in turn be overridden by session-specific CLI arguments.

The diagram below illustrates the configuration loading and merging flow.

Data Models and Schema

The configuration is structured into several nested data models to organize settings logically. The root of the configuration is the CmdaiConfig struct, which contains specialized configuration structs for different parts of the application.

Sources: specs/006-intelligent-prompt-generation/spec.md:310-316

Core Configuration Structs

The diagram below shows the main configuration data structures and their relationships.

The main configuration structs are:

Struct	Purpose	Source File
CmdaiConfig	The root configuration object holding all other config structs.	specs/006-intelligent-prompt-generation/spec.md:318-325
PlatformConfig	Manages platform-specific settings like OS, shell, and architecture. Supports cross-platform generation via target_os.	specs/006-intelligent-prompt-generation/spec.md:327-334
GenerationConfig	Controls the behavior of the AI command generation, including confidence thresholds and retry logic.	specs/006-intelligent-prompt-generation/spec.md:342-348
PromptConfig	Defines which prompt templates to use and where they are located.	specs/006-intelligent-prompt-generation/spec.md:350-354
CacheConfig	Manages settings for the model and man page caches, including location, TTL, and refresh policies.	specs/006-intelligent-prompt-generation/spec.md:356-361
UserConfiguration	A subset of settings that are directly user-configurable, managed via a builder pattern.	specs/003-implement-core-infrastructure/tasks.md:102-105

Example config.toml

The following is an example of the config.toml file that users can create to persist their settings.

# ~/.config/caro/config.toml

version = "1.0.0"

[platform]
os = "macos"
unix_flavor = "bsd"
shell = "zsh"
arch = "aarch64"
# target_os = "linux"  # Uncomment for cross-platform generation

[generation]
confidence_threshold = 0.6
enable_multi_turn = true
enable_clarification = true
max_retries = 3
timeout_seconds = 30

[prompts]
base_template = "base-bsd.toml"
fallback_templates = ["detailed-bsd.toml", "interactive-bsd.toml"]
template_dir = "~/.config/cmdai/prompts"

[cache]
cache_dir = "~/.cache/cmdai"
man_page_ttl_days = 30
auto_refresh = true

This example shows the structure of the user-facing configuration file, which maps directly to the data models.

Sources: specs/006-intelligent-prompt-generation/spec.md:520-547

Key Components

ConfigManager

The ConfigManager is the primary entry point for interacting with the configuration system. It is responsible for the entire lifecycle of configuration data.

Responsibilities:

• Loading: Reads the TOML configuration file from the appropriate XDG directory.
• Saving: Persists UserConfiguration changes back to the file.
• Merging: Combines settings from the config file, environment variables, and CLI arguments.
• Validation: Uses ConfigSchema to validate the loaded configuration.
• Path Management: Provides the path to the configuration file.

Sources: src/config/mod.rs, tests/config_contract.rs, specs/003-implement-core-infrastructure/tasks.md:152-156

ConfigSchema

The ConfigSchema component is responsible for validating the structure and values of a loaded configuration. This ensures that the configuration is valid before it is used by the application, preventing runtime errors due to misconfiguration.

Responsibilities:

• Schema Definition: Defines known sections and keys that are valid in the config.toml file.
• Validation: Checks a loaded configuration against the known schema.
• Migration: Identifies and handles deprecated keys, facilitating smooth upgrades for users.

Sources: src/config/schema.rs, specs/003-implement-core-infrastructure/tasks.md:154-155

Builder Pattern

The UserConfiguration struct utilizes a builder pattern (UserConfigurationBuilder) to allow for programmatic and fluent construction of configuration objects. This is particularly useful in tests and when merging settings from multiple sources.

Sources: specs/003-implement-core-infrastructure/tasks.md:104

Error Handling

The configuration module defines a custom ConfigError enum to handle various failure scenarios gracefully. This provides specific, typed errors that can be handled appropriately by the calling code.

The main error types include:

• Failure to read or write the config file.
• TOML parsing errors.
• Validation errors against the schema.
• I/O errors related to file operations.

Sources: src/config/mod.rs, tests/config_contract.rs

Summary

The caro configuration system is a foundational module that provides a robust, flexible, and user-friendly mechanism for managing application settings. Through its layered loading hierarchy, structured data models, and built-in validation, it ensures that caro can be easily adapted to different user needs and environments while maintaining stability and providing clear feedback on misconfigurations. Its design is central to features like cross-platform command generation and customizable AI behavior.

Sources: specs/003-implement-core-infrastructure/spec.md, specs/006-intelligent-prompt-generation/spec.md