orcs_runtime/config/
mod.rs

1//! Configuration management with hierarchical layering.
2//!
3//! # Architecture
4//!
5//! Configuration is loaded from multiple sources with priority-based merging:
6//!
7//! ```text
8//! Priority (highest to lowest):
9//!
10//! ┌─────────────────────────────────────────┐
11//! │  1. Environment Variables (ORCS_*)      │  Runtime override
12//! ├─────────────────────────────────────────┤
13//! │  2. Project Config (.orcs/config.toml)  │  Project-specific
14//! ├─────────────────────────────────────────┤
15//! │  3. Global Config (~/.orcs/config.toml) │  User defaults
16//! ├─────────────────────────────────────────┤
17//! │  4. Default Values (compile-time)       │  Fallback
18//! └─────────────────────────────────────────┘
19//! ```
20//!
21//! # Directory Structure
22//!
23//! ```text
24//! ~/.orcs/                     # Global ORCS directory
25//! ├── config.toml              # Global configuration
26//! ├── sessions/                # Session data (separate from config)
27//! │   └── {uuid}.json
28//! └── cache/                   # Cache directory (future)
29//!
30//! <project>/.orcs/             # Project-local ORCS directory
31//! ├── config.toml              # Project configuration (overrides global)
32//! └── context.md               # Project context (future)
33//! ```
34//!
35//! # Config vs Session Separation
36//!
37//! | Aspect | Config | Session |
38//! |--------|--------|---------|
39//! | Format | TOML | JSON |
40//! | Scope | Global / Project | Per-conversation |
41//! | Mutability | Rarely changed | Frequently updated |
42//! | Contents | Settings, preferences | History, snapshots |
43//!
44//! # Usage
45//!
46//! ```ignore
47//! use orcs_runtime::config::{OrcsConfig, ConfigLoader};
48//!
49//! // Load configuration with automatic layering
50//! let config = ConfigLoader::new()
51//!     .with_project_root("/path/to/project")
52//!     .load()?;
53//!
54//! // Access settings
55//! if config.debug {
56//!     println!("Debug mode enabled");
57//! }
58//!
59//! // Environment variable override
60//! // ORCS_DEBUG=true overrides config.debug
61//! ```
62//!
63//! # Environment Variables
64//!
65//! | Variable | Config Field | Type |
66//! |----------|--------------|------|
67//! | `ORCS_DEBUG` | `debug` | bool |
68//! | `ORCS_MODEL` | `model.default` | String |
69//! | `ORCS_AUTO_APPROVE` | `hil.auto_approve` | bool |
70//! | `ORCS_SESSION_PATH` | `paths.session_dir` | PathBuf |
71//! | `ORCS_SCRIPTS_AUTO_LOAD` | `scripts.auto_load` | bool |
72//!
73//! # Example Configuration
74//!
75//! ```toml
76//! # ~/.orcs/config.toml
77//!
78//! # General settings
79//! debug = false
80//!
81//! [model]
82//! default = "llama3.2:latest"
83//! temperature = 0.7
84//!
85//! [hil]
86//! auto_approve = false
87//! timeout_ms = 30000
88//!
89//! [paths]
90//! session_dir = "~/.orcs/sessions"
91//!
92//! [ui]
93//! verbose = false
94//! color = true
95//!
96//! [scripts]
97//! dirs = ["~/.orcs/scripts", ".orcs/scripts"]
98//! auto_load = true
99//! ```
100
101mod error;
102mod loader;
103pub mod profile;
104mod resolver;
105mod types;
106
107pub use error::ConfigError;
108pub use loader::{save_global_config, ConfigLoader, EnvOverrides};
109pub use profile::{ProfileDef, ProfileEntry, ProfileStore};
110pub use resolver::{ConfigResolver, NoOpResolver};
111pub use types::{
112    ComponentsConfig, HilConfig, ModelConfig, OrcsConfig, PathsConfig, ScriptsConfig, UiConfig,
113};
114
115/// Default global config directory.
116pub fn default_config_dir() -> std::path::PathBuf {
117    dirs::home_dir()
118        .unwrap_or_else(|| std::path::PathBuf::from("."))
119        .join(".orcs")
120}
121
122/// Default global config file path.
123pub fn default_config_path() -> std::path::PathBuf {
124    default_config_dir().join("config.toml")
125}
126
127/// Project config directory name.
128pub const PROJECT_CONFIG_DIR: &str = ".orcs";
129
130/// Project config file name.
131pub const PROJECT_CONFIG_FILE: &str = "config.toml";
orcs_runtime/config/mod.rs

orcs_runtime/config/
mod.rs
