context_harness/

config.rs

//! Configuration parsing and validation.
//!
//! Context Harness is configured via a TOML file (default: `config/ctx.toml`).
//! The config defines database paths, chunking parameters, embedding provider
//! settings, retrieval tuning, server bind address, and connector configurations.
//!
//! # Example Configuration
//!
//! ```toml
//! [db]
//! path = ".ctx/data/ctx.sqlite"
//!
//! [chunking]
//! max_tokens = 700
//! overlap_tokens = 80
//!
//! [embedding]
//! provider = "openai"           # "disabled" | "openai"
//! model = "text-embedding-3-small"
//! dims = 1536
//!
//! [vector_index]
//! backend = "auto"
//! path = "auto"
//! metric = "cosine"
//! index = "hnsw"
//! fallback = "sqlite"
//!
//! [retrieval]
//! final_limit = 12
//! hybrid_alpha = 0.6            # 0.0 = keyword only, 1.0 = semantic only
//!
//! [server]
//! bind = "127.0.0.1:7331"
//!
//! [connectors.filesystem.docs]
//! root = "./docs"
//! include_globs = ["**/*.md", "**/*.txt"]
//!
//! [connectors.git.platform]
//! url = "https://github.com/acme/platform.git"
//! branch = "main"
//! ```
//!
//! # Connectors
//!
//! All connector types are **named** — you can configure multiple instances of each:
//! - **Filesystem** (`[connectors.filesystem.<name>]`) — scan a local directory
//! - **Git** (`[connectors.git.<name>]`) — clone/pull a Git repository
//! - **S3** (`[connectors.s3.<name>]`) — list and download from an S3 bucket
//! - **Script** (`[connectors.script.<name>]`) — custom Lua-scripted data sources
//!
//! # Validation
//!
//! [`load_config`] performs the following validations:
//! - `chunking.max_tokens > 0`
//! - `retrieval.final_limit >= 1`
//! - `retrieval.hybrid_alpha ∈ [0.0, 1.0]`
//! - When embedding provider is `openai` or `ollama`: `model` and `dims` must be set
//! - Embedding provider must be one of: `"disabled"`, `"openai"`, `"ollama"`, `"local"`

use anyhow::{Context, Result};
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::path::{Path, PathBuf};

use crate::ctx_dirs::{self, ConfigSourceKind};

/// Top-level configuration structure.
///
/// Deserialized from the TOML config file. All sections are required
/// except `connectors`, which defaults to an empty set.
#[derive(Debug, Deserialize, Clone)]
pub struct Config {
    /// Database connection settings.
    pub db: DbConfig,
    /// Text chunking parameters.
    pub chunking: ChunkingConfig,
    /// Search and retrieval tuning.
    pub retrieval: RetrievalConfig,
    /// Embedding provider settings (defaults to disabled).
    #[serde(default)]
    pub embedding: EmbeddingConfig,
    /// Optional vector-index acceleration settings (defaults to auto with SQLite fallback).
    #[serde(default)]
    #[allow(dead_code)]
    pub vector_index: VectorIndexConfig,
    /// HTTP server bind address.
    #[allow(dead_code)]
    pub server: ServerConfig,
    /// Connector configurations (all optional).
    #[serde(default)]
    pub connectors: ConnectorsConfig,
    /// Tool script configurations (all optional).
    #[serde(default)]
    pub tools: ToolsConfig,
    /// Reusable MCP profile configurations (all optional).
    ///
    /// The historical `[agents.*]` table remains accepted as an alias.
    #[serde(default, alias = "agents")]
    pub profiles: ProfilesConfig,
    /// Model aliases for standalone executable-agent resources.
    #[serde(default)]
    pub models: std::collections::BTreeMap<String, crate::agent_resource::ModelDefinition>,
    /// Named stdio MCP servers available to executable agents.
    #[serde(default)]
    pub mcp_servers: std::collections::BTreeMap<String, McpServerConfig>,
    /// Extension registry configurations (all optional).
    #[serde(default)]
    pub registries: HashMap<String, RegistryConfig>,
}

impl Config {
    /// Create a minimal config suitable for commands that don't need
    /// database or connector settings (e.g., `ctx connector test`).
    pub fn minimal() -> Self {
        Self {
            db: DbConfig {
                path: ctx_dirs::workspace_db_path(),
            },
            chunking: ChunkingConfig {
                max_tokens: 700,
                overlap_tokens: 0,
            },
            retrieval: RetrievalConfig {
                hybrid_alpha: default_hybrid_alpha(),
                candidate_k_keyword: default_candidate_k(),
                candidate_k_vector: default_candidate_k(),
                final_limit: default_final_limit(),
                group_by: default_group_by(),
                doc_agg: default_doc_agg(),
                max_chunks_per_doc: default_max_chunks_per_doc(),
            },
            embedding: EmbeddingConfig::default(),
            vector_index: VectorIndexConfig::default(),
            server: ServerConfig {
                bind: "127.0.0.1:7331".to_string(),
            },
            connectors: ConnectorsConfig::default(),
            tools: ToolsConfig::default(),
            profiles: ProfilesConfig::default(),
            models: std::collections::BTreeMap::new(),
            mcp_servers: std::collections::BTreeMap::new(),
            registries: HashMap::new(),
        }
    }
}

/// A stdio MCP process. Execution inherits the environment and uses the run's
/// workspace root as its working directory; launching requires process permission.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct McpServerConfig {
    pub command: String,
    #[serde(default)]
    pub args: Vec<String>,
    #[serde(default = "default_mcp_timeout_seconds")]
    pub timeout_seconds: u64,
}

fn default_mcp_timeout_seconds() -> u64 {
    30
}

impl McpServerConfig {
    /// Validate both the namespace and bounded process settings without spawning.
    pub fn validate(&self, name: &str) -> Result<()> {
        if name.is_empty()
            || name.len() > 64
            || !name
                .bytes()
                .all(|byte| byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-')
        {
            anyhow::bail!(
                "MCP server name must contain 1..64 ASCII letters, digits, underscores, or hyphens"
            );
        }
        if self.command.trim().is_empty()
            || self.command.len() > 4096
            || self.command.contains('\0')
        {
            anyhow::bail!("MCP server '{name}' command must contain 1..4096 bytes and no NUL");
        }
        if self.args.len() > 128
            || self.args.iter().any(|arg| arg.contains('\0'))
            || self.args.iter().map(String::len).sum::<usize>() > 64 * 1024
        {
            anyhow::bail!("MCP server '{name}' arguments must contain at most 128 entries and 65536 bytes, with no NUL");
        }
        if !(1..=60).contains(&self.timeout_seconds) {
            anyhow::bail!("MCP server '{name}' timeout_seconds must be in 1..=60");
        }
        Ok(())
    }
}

#[derive(Debug, Clone)]
pub struct ResolvedConfig {
    pub config: Config,
    pub path: Option<PathBuf>,
    #[allow(dead_code)]
    pub source: ConfigSourceKind,
}

/// Database configuration.
///
/// Specifies the path to the SQLite database file. The file and its
/// parent directories are created automatically on first use.
#[derive(Debug, Deserialize, Clone)]
pub struct DbConfig {
    /// Path to the SQLite database file (e.g. `".ctx/data/ctx.sqlite"`).
    pub path: PathBuf,
}

/// Text chunking parameters.
///
/// Controls how document bodies are split into chunks for indexing
/// and embedding. See [`crate::chunk`] for the chunking algorithm.
#[derive(Debug, Deserialize, Clone)]
pub struct ChunkingConfig {
    /// Maximum tokens per chunk. Chunks are split on paragraph boundaries
    /// to stay within this limit. Converted to characters via `max_tokens × 4`.
    pub max_tokens: usize,
    /// Number of overlapping tokens between adjacent chunks (reserved for future use).
    #[serde(default = "default_overlap")]
    #[allow(dead_code)]
    pub overlap_tokens: usize,
}

fn default_overlap() -> usize {
    0
}

/// Search and retrieval tuning parameters.
///
/// These settings control how keyword and semantic search results are
/// merged in hybrid mode, and the overall result limits.
///
/// # Hybrid Scoring
///
/// The `hybrid_alpha` weight determines the blend between keyword (BM25)
/// and semantic (cosine similarity) scores:
///
/// ```text
/// hybrid_score = (1 - α) × keyword_score + α × semantic_score
/// ```
///
/// - `α = 0.0` → pure keyword search
/// - `α = 1.0` → pure semantic search
/// - `α = 0.6` (default) → 60% semantic, 40% keyword
///
/// See `docs/HYBRID_SCORING.md` for the full specification.
#[derive(Debug, Deserialize, Clone)]
pub struct RetrievalConfig {
    /// Weight for semantic vs. keyword scores in hybrid mode.
    /// Range: `[0.0, 1.0]`. Default: `0.6`.
    #[serde(default = "default_hybrid_alpha")]
    pub hybrid_alpha: f64,
    /// Number of keyword candidates to fetch before merging. Default: `80`.
    #[serde(default = "default_candidate_k")]
    pub candidate_k_keyword: i64,
    /// Number of vector candidates to fetch before merging. Default: `80`.
    #[serde(default = "default_candidate_k")]
    pub candidate_k_vector: i64,
    /// Maximum number of results to return after merging and ranking. Default: `12`.
    #[serde(default = "default_final_limit")]
    pub final_limit: i64,
    /// Grouping strategy for results. Default: `"document"`.
    #[serde(default = "default_group_by")]
    #[allow(dead_code)]
    pub group_by: String,
    /// Aggregation method for document-level scores. Default: `"max"`.
    #[serde(default = "default_doc_agg")]
    #[allow(dead_code)]
    pub doc_agg: String,
    /// Maximum chunks per document in results. Default: `3`.
    #[serde(default = "default_max_chunks_per_doc")]
    #[allow(dead_code)]
    pub max_chunks_per_doc: usize,
}

fn default_hybrid_alpha() -> f64 {
    0.6
}
fn default_candidate_k() -> i64 {
    80
}
fn default_final_limit() -> i64 {
    12
}
fn default_group_by() -> String {
    "document".to_string()
}
fn default_doc_agg() -> String {
    "max".to_string()
}
fn default_max_chunks_per_doc() -> usize {
    3
}

/// Embedding provider configuration.
///
/// Controls which embedding provider is used and its parameters.
/// When `provider = "disabled"`, no embeddings are generated and
/// semantic/hybrid search modes will return errors.
///
/// # Providers
///
/// | Provider | Description |
/// |----------|-------------|
/// | `"disabled"` | No embeddings (default) |
/// | `"openai"` | OpenAI API (`text-embedding-3-small`, etc.) |
/// | `"ollama"` | Local Ollama instance (`nomic-embed-text`, etc.) |
/// | `"local"` | Built-in models via fastembed (primary) or tract (musl/Intel Mac) (`all-minilm-l6-v2`, etc.) |
///
/// When using `"openai"`, the `OPENAI_API_KEY` environment variable must be set.
/// When using `"ollama"`, an Ollama instance must be running (default: `http://localhost:11434`).
/// When using `"local"`, the model is downloaded on first use and cached in `~/.cache/huggingface/`.
#[derive(Debug, Deserialize, Clone)]
pub struct EmbeddingConfig {
    /// Provider name: `"disabled"`, `"openai"`, `"ollama"`, or `"local"`. Default: `"disabled"`.
    #[serde(default = "default_provider")]
    pub provider: String,
    /// Embedding model name (e.g. `"text-embedding-3-small"`, `"nomic-embed-text"`,
    /// `"all-minilm-l6-v2"`). Required for `openai` and `ollama`; optional for `local`
    /// (defaults to `"all-minilm-l6-v2"`).
    #[serde(default)]
    pub model: Option<String>,
    /// Embedding vector dimensionality (e.g. `1536` for `text-embedding-3-small`).
    /// Required for `openai` and `ollama`; auto-detected for `local`.
    #[serde(default)]
    pub dims: Option<usize>,
    /// Number of texts to embed per batch. Default: `64`.
    #[serde(default = "default_batch_size")]
    pub batch_size: usize,
    /// Maximum retry attempts for transient API errors. Default: `5`.
    #[serde(default = "default_max_retries")]
    pub max_retries: u32,
    /// HTTP timeout per request in seconds. Default: `30`.
    #[serde(default = "default_timeout_secs")]
    pub timeout_secs: u64,
    /// Base URL for Ollama API. Default: `"http://localhost:11434"`.
    #[serde(default)]
    pub url: Option<String>,
}

impl Default for EmbeddingConfig {
    fn default() -> Self {
        Self {
            provider: "disabled".to_string(),
            model: None,
            dims: None,
            batch_size: 64,
            max_retries: 5,
            timeout_secs: 30,
            url: None,
        }
    }
}

fn default_provider() -> String {
    "disabled".to_string()
}
fn default_batch_size() -> usize {
    64
}
fn default_max_retries() -> u32 {
    5
}
fn default_timeout_secs() -> u64 {
    30
}

/// Optional vector-index acceleration configuration.
///
/// The default is automatic: use the built-in vector accelerator when the
/// binary supports one and fall back to the exact SQLite vector scan otherwise.
#[derive(Debug, Deserialize, Clone)]
pub struct VectorIndexConfig {
    /// Backend name. Default: `"auto"`.
    #[serde(default = "default_vector_backend")]
    #[allow(dead_code)]
    pub backend: String,
    /// Filesystem path for external vector-index state. Default: `"auto"`.
    #[serde(default = "default_vector_path")]
    #[allow(dead_code)]
    pub path: PathBuf,
    /// Distance metric. Default: `"cosine"`.
    #[serde(default = "default_vector_metric")]
    #[allow(dead_code)]
    pub metric: String,
    /// Index kind. Default: `"hnsw"`.
    #[serde(default = "default_vector_index")]
    #[allow(dead_code)]
    pub index: String,
    /// Fallback strategy when acceleration is unavailable. Default: `"sqlite"`.
    #[serde(default = "default_vector_fallback")]
    #[allow(dead_code)]
    pub fallback: String,
}

impl Default for VectorIndexConfig {
    fn default() -> Self {
        Self {
            backend: default_vector_backend(),
            path: default_vector_path(),
            metric: default_vector_metric(),
            index: default_vector_index(),
            fallback: default_vector_fallback(),
        }
    }
}

fn default_vector_backend() -> String {
    "auto".to_string()
}

fn default_vector_path() -> PathBuf {
    PathBuf::from("auto")
}

fn default_vector_metric() -> String {
    "cosine".to_string()
}

fn default_vector_index() -> String {
    "hnsw".to_string()
}

fn default_vector_fallback() -> String {
    "sqlite".to_string()
}

/// HTTP server configuration.
#[derive(Debug, Deserialize, Clone)]
pub struct ServerConfig {
    /// Socket address to bind to (e.g. `"127.0.0.1:7331"`).
    pub bind: String,
}

/// Container for all connector configurations.
///
/// All connector types use named instances — you can configure multiple
/// of each type. For example:
///
/// ```toml
/// [connectors.git.platform]
/// url = "https://github.com/acme/platform.git"
///
/// [connectors.git.auth-service]
/// url = "https://github.com/acme/auth-service.git"
/// ```
///
/// Use `ctx sync git` to sync all git connectors, or `ctx sync git:platform`
/// for a specific one. `ctx sync all` syncs everything.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct ConnectorsConfig {
    /// Named filesystem connectors: walk local directories.
    #[serde(default)]
    pub filesystem: HashMap<String, FilesystemConnectorConfig>,
    /// Named Git connectors: clone and scan Git repositories.
    #[serde(default)]
    pub git: HashMap<String, GitConnectorConfig>,
    /// Named S3 connectors: list and download from S3 buckets.
    #[serde(default)]
    pub s3: HashMap<String, S3ConnectorConfig>,
    /// Named Lua script connectors.
    /// Each key is a connector name, each value contains the script path
    /// and arbitrary config keys passed to the Lua `connector.scan()` function.
    /// See `docs/LUA_CONNECTORS.md` for the full specification.
    #[serde(default)]
    pub script: HashMap<String, ScriptConnectorConfig>,
}

/// Lua script connector configuration.
///
/// Points to a `.lua` file implementing the connector interface. All fields
/// except `path` and `timeout` are passed as a config table to the script's
/// `connector.scan(config)` function.
///
/// Values containing `${VAR_NAME}` are expanded from the process environment.
///
/// # Example
///
/// ```toml
/// [connectors.script.jira]
/// path = "connectors/jira.lua"
/// timeout = 600
/// url = "https://mycompany.atlassian.net"
/// api_token = "${JIRA_API_TOKEN}"
/// project_key = "ENG"
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct ScriptConnectorConfig {
    /// Path to the `.lua` connector script.
    pub path: PathBuf,
    /// Maximum execution time in seconds. Default: `300`.
    #[serde(default = "default_script_timeout")]
    pub timeout: u64,
    /// All other config keys — passed to the Lua `connector.scan()` function.
    #[serde(flatten)]
    pub extra: toml::Table,
}

fn default_script_timeout() -> u64 {
    300
}

/// Container for all tool script configurations.
///
/// Tool scripts are Lua files that define MCP tools profiles can discover
/// and call via the HTTP server. See `docs/LUA_TOOLS.md` for the full
/// specification.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct ToolsConfig {
    /// Named Lua tool scripts.
    /// Each key is the tool name, each value contains the script path
    /// and arbitrary config keys accessible via `context.config` in the script.
    #[serde(default)]
    pub script: HashMap<String, ScriptToolConfig>,
}

/// Lua tool script configuration.
///
/// Points to a `.lua` file implementing the tool interface. All fields
/// except `path` and `timeout` are passed as `context.config` to the
/// script's `tool.execute(params, context)` function.
///
/// Values containing `${VAR_NAME}` are expanded from the process environment.
///
/// # Example
///
/// ```toml
/// [tools.script.create_jira_ticket]
/// path = "tools/create-jira-ticket.lua"
/// timeout = 30
/// url = "https://mycompany.atlassian.net"
/// api_token = "${JIRA_API_TOKEN}"
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct ScriptToolConfig {
    /// Path to the `.lua` tool script.
    pub path: PathBuf,
    /// Maximum execution time in seconds. Default: `30`.
    #[serde(default = "default_tool_timeout")]
    pub timeout: u64,
    /// All other config keys — accessible via `context.config` in the script.
    #[serde(flatten)]
    pub extra: toml::Table,
}

fn default_tool_timeout() -> u64 {
    30
}

/// Container for all reusable profile configurations.
///
/// Profiles are named personas that combine a system prompt, scoped tools,
/// and optional dynamic context injection. They can be defined inline
/// in TOML or via Lua scripts.
///
/// # Example
///
/// ```toml
/// [profiles.inline.code-reviewer]
/// description = "Reviews code against project conventions"
/// tools = ["search", "get"]
/// system_prompt = "You are a senior code reviewer..."
///
/// [profiles.script.incident-responder]
/// path = "profiles/incident-responder.lua"
/// timeout = 30
/// ```
#[derive(Debug, Deserialize, Clone, Default)]
pub struct ProfilesConfig {
    /// Inline TOML profiles with static system prompts.
    /// Each key is the profile name, each value contains the prompt and tool list.
    #[serde(default)]
    pub inline: HashMap<String, InlineProfileConfig>,
    /// Lua script profiles with dynamic prompt resolution.
    /// Each key is the profile name, each value contains the script path
    /// and arbitrary config keys passed to `profile.resolve()`.
    #[serde(default)]
    pub script: HashMap<String, ScriptProfileConfig>,
}

/// Inline TOML profile configuration.
///
/// Defines a profile with a static system prompt and fixed tool list.
///
/// # Example
///
/// ```toml
/// [profiles.inline.architect]
/// description = "Answers architecture questions"
/// tools = ["search", "get", "sources"]
/// system_prompt = """
/// You are a software architect. Search for ADRs and design
/// docs to ground your recommendations.
/// """
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct InlineProfileConfig {
    /// One-line description for profile discovery.
    pub description: String,
    /// List of tool names this profile suggests.
    pub tools: Vec<String>,
    /// The system prompt text.
    pub system_prompt: String,
}

/// Lua script profile configuration.
///
/// Points to a `.lua` file implementing the profile interface. All fields
/// except `path` and `timeout` are passed as config to the script's
/// `profile.resolve(args, config, context)` function.
///
/// Values containing `${VAR_NAME}` are expanded from the process environment.
///
/// # Example
///
/// ```toml
/// [profiles.script.incident-responder]
/// path = "profiles/incident-responder.lua"
/// timeout = 30
/// search_limit = 5
/// priority_sources = ["runbooks"]
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct ScriptProfileConfig {
    /// Path to the `.lua` profile script.
    pub path: PathBuf,
    /// Maximum execution time in seconds. Default: `30`.
    #[serde(default = "default_profile_timeout")]
    pub timeout: u64,
    /// All other config keys — passed to the Lua `profile.resolve()` function.
    #[serde(flatten)]
    pub extra: toml::Table,
}

fn default_profile_timeout() -> u64 {
    30
}

#[deprecated(note = "use ProfilesConfig")]
#[allow(dead_code)]
pub type AgentsConfig = ProfilesConfig;
#[deprecated(note = "use InlineProfileConfig")]
#[allow(dead_code)]
pub type InlineAgentConfig = InlineProfileConfig;
#[deprecated(note = "use ScriptProfileConfig")]
#[allow(dead_code)]
pub type ScriptAgentConfig = ScriptProfileConfig;

/// Extension registry configuration.
///
/// Points to a local directory (optionally backed by a Git repository)
/// containing Lua connector, tool, and profile scripts described by a
/// `registry.toml` manifest.
///
/// # Example
///
/// ```toml
/// [registries.community]
/// url = "https://github.com/parallax-labs/ctx-registry.git"
/// branch = "main"
/// path = "~/.local/share/ctx/registries/community"
/// readonly = true
/// auto_update = true
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct RegistryConfig {
    /// Git repository URL to clone from. `None` means local-only (no git).
    pub url: Option<String>,
    /// Git branch or tag to track. Default: `"main"`.
    pub branch: Option<String>,
    /// Local filesystem path where the registry is (or will be) stored.
    pub path: PathBuf,
    /// If `true`, extensions on this path cannot be edited in place;
    /// overrides are copied to a writable registry.
    #[serde(default)]
    pub readonly: bool,
    /// If `true`, `ctx registry update` (and optionally `ctx sync`) will
    /// `git pull` this registry automatically.
    #[serde(default)]
    #[allow(dead_code)]
    pub auto_update: bool,
}

/// Filesystem connector configuration.
///
/// Scans a local directory tree, applying glob include/exclude filters.
/// See [`crate::connector_fs`] for the scanning implementation.
///
/// # Example
///
/// ```toml
/// [connectors.filesystem.docs]
/// root = "./docs"
/// include_globs = ["**/*.md", "**/*.txt"]
/// exclude_globs = ["**/drafts/**"]
/// follow_symlinks = false
/// max_extract_bytes = 50_000_000
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct FilesystemConnectorConfig {
    /// Root directory to scan.
    pub root: PathBuf,
    /// Glob patterns for files to include. Default: `["**/*.md", "**/*.txt"]`.
    #[serde(default = "default_include_globs")]
    pub include_globs: Vec<String>,
    /// Glob patterns for files to exclude. Default: `[]`.
    #[serde(default)]
    pub exclude_globs: Vec<String>,
    /// Whether to follow symbolic links. Default: `false`.
    #[serde(default)]
    pub follow_symlinks: bool,
    /// Files larger than this (bytes) are not extracted; they are skipped and counted in extraction skipped. Default: 50_000_000.
    #[serde(default = "default_max_extract_bytes")]
    pub max_extract_bytes: u64,
}

/// Git connector configuration.
///
/// Clones (or pulls) a Git repository and scans files within a configurable
/// subdirectory. Extracts per-file metadata from `git log`.
/// See [`crate::connector_git`] for the full implementation.
///
/// # Example
///
/// ```toml
/// [connectors.git.platform]
/// url = "https://github.com/acme/platform.git"
/// branch = "main"
/// root = "docs/"
/// include_globs = ["**/*.md"]
/// shallow = true
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct GitConnectorConfig {
    /// Git repository URL (`https://`, `git@`, or local path).
    pub url: String,
    /// Branch to clone/pull. Default: `"main"`.
    #[serde(default = "default_git_branch")]
    pub branch: String,
    /// Subdirectory within the repo to scan. Default: `"."` (entire repo).
    #[serde(default = "default_git_root")]
    pub root: String,
    /// Glob patterns for files to include. Default: `["**/*.md", "**/*.txt"]`.
    #[serde(default = "default_include_globs")]
    pub include_globs: Vec<String>,
    /// Glob patterns for files to exclude. Default: `[]`.
    #[serde(default)]
    pub exclude_globs: Vec<String>,
    /// Use shallow clone (`--depth 1`) to save disk space. Default: `true`.
    #[serde(default = "default_true")]
    pub shallow: bool,
    /// Directory to cache cloned repos. Default: `.ctx/cache/git/<url-hash>/`
    /// when using the workspace DB, otherwise `<db-dir>/.git-cache/<url-hash>/`.
    #[serde(default)]
    pub cache_dir: Option<PathBuf>,
}

/// Amazon S3 connector configuration.
///
/// Lists and downloads objects from an S3 bucket using the REST API with
/// AWS Signature V4. Supports custom endpoints for S3-compatible services.
/// See [`crate::connector_s3`] for the full implementation.
///
/// # Environment Variables
///
/// - `AWS_ACCESS_KEY_ID` — required
/// - `AWS_SECRET_ACCESS_KEY` — required
/// - `AWS_SESSION_TOKEN` — optional (for temporary credentials)
///
/// # Example
///
/// ```toml
/// [connectors.s3.runbooks]
/// bucket = "acme-docs"
/// prefix = "engineering/runbooks/"
/// region = "us-east-1"
/// include_globs = ["**/*.md"]
/// # endpoint_url = "http://localhost:9000"   # for MinIO
/// ```
#[derive(Debug, Deserialize, Clone)]
pub struct S3ConnectorConfig {
    /// S3 bucket name.
    pub bucket: String,
    /// Key prefix to filter objects. Default: `""` (entire bucket).
    #[serde(default)]
    pub prefix: String,
    /// AWS region. Default: `"us-east-1"`.
    #[serde(default = "default_s3_region")]
    pub region: String,
    /// Glob patterns for object keys to include. Default: `["**/*.md", "**/*.txt"]`.
    #[serde(default = "default_include_globs")]
    pub include_globs: Vec<String>,
    /// Glob patterns for object keys to exclude. Default: `[]`.
    #[serde(default)]
    pub exclude_globs: Vec<String>,
    /// Custom endpoint URL for S3-compatible services (MinIO, LocalStack).
    #[serde(default)]
    pub endpoint_url: Option<String>,
}

fn default_git_branch() -> String {
    "main".to_string()
}

fn default_git_root() -> String {
    ".".to_string()
}

fn default_true() -> bool {
    true
}

fn default_s3_region() -> String {
    "us-east-1".to_string()
}

fn default_include_globs() -> Vec<String> {
    vec!["**/*.md".to_string(), "**/*.txt".to_string()]
}

fn default_max_extract_bytes() -> u64 {
    50_000_000
}

impl EmbeddingConfig {
    /// Returns `true` if an embedding provider is configured (not `"disabled"`).
    pub fn is_enabled(&self) -> bool {
        self.provider != "disabled"
    }
}

/// Load and validate a configuration file from disk.
///
/// # Arguments
///
/// * `path` — Path to a TOML configuration file.
///
/// # Errors
///
/// Returns an error if:
/// - The file cannot be read or parsed
/// - `chunking.max_tokens` is zero
/// - `retrieval.final_limit` is less than 1
/// - `retrieval.hybrid_alpha` is outside `[0.0, 1.0]`
/// - Embedding provider is enabled but `model` or `dims` is missing/zero
/// - Unknown embedding provider name
#[allow(dead_code)]
pub fn load_config(path: &Path) -> Result<Config> {
    load_config_file(path)
}

pub fn load_config_for_cli(explicit_path: Option<PathBuf>) -> Result<ResolvedConfig> {
    let paths = ctx_dirs::config_paths(explicit_path);
    let source = paths.resolve();

    match source.kind {
        ConfigSourceKind::Explicit | ConfigSourceKind::Env | ConfigSourceKind::Global => {
            let path = source
                .path
                .clone()
                .expect("path-backed config source must include path");
            let config = load_config_file(&path)?;
            Ok(ResolvedConfig {
                config,
                path: Some(path),
                source: source.kind,
            })
        }
        ConfigSourceKind::Workspace | ConfigSourceKind::LegacyWorkspace => {
            let workspace_path = source
                .path
                .clone()
                .expect("path-backed config source must include path");
            let workspace_value = load_config_value(&workspace_path)?;
            let merged_value = if paths.global.exists() {
                let mut global_value = load_config_value(&paths.global)?;
                merge_toml(&mut global_value, workspace_value);
                global_value
            } else {
                workspace_value
            };
            let config = config_from_value(merged_value)?;
            Ok(ResolvedConfig {
                config,
                path: Some(workspace_path),
                source: source.kind,
            })
        }
        ConfigSourceKind::BuiltIn => Ok(ResolvedConfig {
            config: Config::minimal(),
            path: None,
            source: ConfigSourceKind::BuiltIn,
        }),
    }
}

/// Resolve a workspace's effective config from its root directory (SPEC-0014 R4).
///
/// Resolves `<root>/.ctx/config.toml` (or the legacy `<root>/config/ctx.toml`)
/// and merges global config defaults underneath it — mirroring the `Workspace`
/// branch of [`load_config_for_cli`] but anchored at an explicit `root` instead
/// of the process working directory. Relative store paths in the resolved
/// config are re-rooted under `root` so each workspace addresses its own store.
pub fn load_config_for_root(root: &Path) -> Result<ResolvedConfig> {
    let workspace_path = root.join(".ctx").join("config.toml");
    let legacy_path = root.join("config").join("ctx.toml");

    let (chosen, kind) = if workspace_path.exists() {
        (Some(workspace_path), ConfigSourceKind::Workspace)
    } else if legacy_path.exists() {
        (Some(legacy_path), ConfigSourceKind::LegacyWorkspace)
    } else {
        (None, ConfigSourceKind::BuiltIn)
    };

    let global = ctx_dirs::config_dir().join("config.toml");

    let mut config = match &chosen {
        Some(path) => {
            let workspace_value = load_config_value(path)?;
            let merged = if global.exists() {
                let mut global_value = load_config_value(&global)?;
                merge_toml(&mut global_value, workspace_value);
                global_value
            } else {
                workspace_value
            };
            config_from_value(merged)?
        }
        None if global.exists() => load_config_file(&global)?,
        None => Config::minimal(),
    };

    reroot_workspace_paths(&mut config, root);
    Ok(ResolvedConfig {
        config,
        path: chosen,
        source: kind,
    })
}

/// Load a pinned config file as the sole source, with no global merge (SPEC-0014 R5).
///
/// Preserves explicit-config behavior (`config = …` in the workspace registry),
/// but still re-roots relative store paths under `root` so the workspace
/// addresses its own store in multi-workspace mode.
pub fn load_config_pinned(config_path: &Path, root: &Path) -> Result<ResolvedConfig> {
    let mut config = load_config_file(config_path)?;
    reroot_workspace_paths(&mut config, root);
    Ok(ResolvedConfig {
        config,
        path: Some(config_path.to_path_buf()),
        source: ConfigSourceKind::Explicit,
    })
}

/// Re-root relative store paths under an explicit workspace root so each
/// workspace addresses its own SQLite store and vector sidecar regardless of
/// the server's working directory (SPEC-0014 R55–R58).
fn reroot_workspace_paths(config: &mut Config, root: &Path) {
    if config.db.path.is_relative() {
        config.db.path = root.join(&config.db.path);
    }
    // The vector sidecar path is derived from db.path when set to "auto" (see
    // vector_index::resolve_vector_index_path), so only an explicit relative
    // override needs re-rooting here.
    if config.vector_index.path.as_os_str() != "auto" && config.vector_index.path.is_relative() {
        config.vector_index.path = root.join(&config.vector_index.path);
    }
    // Filesystem connector roots feed `sources` health checks; re-root relative ones.
    for fs in config.connectors.filesystem.values_mut() {
        if fs.root.is_relative() {
            fs.root = root.join(&fs.root);
        }
    }
}

pub fn ensure_workspace_config_for_init(explicit_path: Option<&Path>) -> Result<Option<PathBuf>> {
    let paths = ctx_dirs::config_paths(explicit_path.map(Path::to_path_buf));
    if paths.has_explicit_source() || paths.has_workspace_source() {
        return Ok(paths.resolve().path);
    }

    let ctx_dir = ctx_dirs::workspace_dir();
    std::fs::create_dir_all(ctx_dirs::workspace_data_dir())?;
    std::fs::create_dir_all(ctx_dirs::workspace_cache_dir())?;
    std::fs::write(ctx_dir.join(".gitignore"), "data/\ncache/\n")?;

    let config_path = ctx_dirs::workspace_config_path();
    if !config_path.exists() {
        std::fs::write(&config_path, default_workspace_config_toml())?;
    }
    Ok(Some(config_path))
}

fn load_config_file(path: &Path) -> Result<Config> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {}", path.display()))?;

    let config: Config = toml::from_str(&content).with_context(|| "Failed to parse config file")?;
    validate_config(config)
}

fn load_config_value(path: &Path) -> Result<toml::Value> {
    let content = std::fs::read_to_string(path)
        .with_context(|| format!("Failed to read config file: {}", path.display()))?;
    toml::from_str(&content).with_context(|| "Failed to parse config file")
}

fn config_from_value(value: toml::Value) -> Result<Config> {
    let config: Config = value
        .try_into()
        .with_context(|| "Failed to parse config file")?;
    validate_config(config)
}

fn validate_config(config: Config) -> Result<Config> {
    for (name, server) in &config.mcp_servers {
        server.validate(name)?;
    }

    // Validate chunking
    if config.chunking.max_tokens == 0 {
        anyhow::bail!("chunking.max_tokens must be > 0");
    }

    // Validate retrieval
    if config.retrieval.final_limit < 1 {
        anyhow::bail!("retrieval.final_limit must be >= 1");
    }

    if !(0.0..=1.0).contains(&config.retrieval.hybrid_alpha) {
        anyhow::bail!("retrieval.hybrid_alpha must be in [0.0, 1.0]");
    }

    // Validate embedding
    match config.embedding.provider.as_str() {
        "disabled" => {}
        "openai" | "ollama" => {
            if config.embedding.dims.is_none() || config.embedding.dims == Some(0) {
                anyhow::bail!(
                    "embedding.dims must be > 0 when provider is '{}'",
                    config.embedding.provider
                );
            }
            if config.embedding.model.is_none() {
                anyhow::bail!(
                    "embedding.model must be specified when provider is '{}'",
                    config.embedding.provider
                );
            }
        }
        "local" => {
            // model and dims are optional for local — defaults applied at runtime
        }
        other => anyhow::bail!(
            "Unknown embedding provider: '{}'. Must be disabled, openai, ollama, or local.",
            other
        ),
    }

    match config.vector_index.backend.as_str() {
        "auto" | "zvec" | "sqlite" | "disabled" => {}
        other => anyhow::bail!(
            "Unknown vector_index.backend: '{}'. Must be auto, zvec, sqlite, or disabled.",
            other
        ),
    }

    match config.vector_index.metric.as_str() {
        "cosine" => {}
        other => anyhow::bail!("Unknown vector_index.metric: '{}'. Must be cosine.", other),
    }

    match config.vector_index.index.as_str() {
        "hnsw" | "flat" => {}
        other => anyhow::bail!(
            "Unknown vector_index.index: '{}'. Must be hnsw or flat.",
            other
        ),
    }

    match config.vector_index.fallback.as_str() {
        "sqlite" | "disabled" => {}
        other => anyhow::bail!(
            "Unknown vector_index.fallback: '{}'. Must be sqlite or disabled.",
            other
        ),
    }

    Ok(config)
}

fn merge_toml(base: &mut toml::Value, overlay: toml::Value) {
    match (base, overlay) {
        (toml::Value::Table(base_table), toml::Value::Table(overlay_table)) => {
            for (key, overlay_value) in overlay_table {
                match base_table.get_mut(&key) {
                    Some(base_value) => merge_toml(base_value, overlay_value),
                    None => {
                        base_table.insert(key, overlay_value);
                    }
                }
            }
        }
        (base_value, overlay_value) => {
            *base_value = overlay_value;
        }
    }
}

pub fn default_workspace_config_toml() -> &'static str {
    r#"[db]
path = ".ctx/data/ctx.sqlite"

[chunking]
max_tokens = 700
overlap_tokens = 0

[retrieval]
final_limit = 12

[server]
bind = "127.0.0.1:7331"
"#
}