ccproxy-api 0.1.7__py3-none-any.whl → 0.2.0a4__py3-none-any.whl

ccproxy/config/settings.py

@@ -1,49 +1,51 @@
-"""Settings configuration for Claude Proxy API Server."""
-
-import contextlib
-import json
 import os
 import tomllib
 from pathlib import Path
 from typing import Any
 
-import structlog
-from pydantic import Field, field_validator, model_validator
+from pydantic import BaseModel, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from ccproxy.config.discovery import find_toml_config_file
-
-from .auth import AuthSettings
-from .claude import ClaudeSettings
-from .codex import CodexSettings
-from .cors import CORSSettings
-from .docker_settings import DockerSettings
-from .observability import ObservabilitySettings
-from .pricing import PricingSettings
-from .reverse_proxy import ReverseProxySettings
-from .scheduler import SchedulerSettings
-from .security import SecuritySettings
-from .server import ServerSettings
-
-
-__all__ = [
-    "Settings",
-    "ConfigurationError",
-    "ConfigurationManager",
-    "config_manager",
-    "get_settings",
+from ccproxy.core.logging import get_logger
+
+from .core import (
+    CORSSettings,
+    HTTPSettings,
+    LoggingSettings,
+    PluginDiscoverySettings,
+    ServerSettings,
+)
+from .runtime import BinarySettings
+from .security import AuthSettings, SecuritySettings
+from .utils import SchedulerSettings, find_toml_config_file, get_ccproxy_config_dir
+
+
+_CONFIG_MISSING_LOGGED = False
+
+# Default plugins enabled when no config file exists
+DEFAULT_ENABLED_PLUGINS = [
+    "codex",
+    "copilot",
+    "claude_api",
+    "claude_sdk",
+    "oauth_codex",
+    "oauth_claude",
 ]
 
 
+def _auth_default() -> AuthSettings:
+    return AuthSettings(credentials_ttl_seconds=3600.0)
+
+
+__all__ = ["Settings", "ConfigurationError"]
+
+
 class ConfigurationError(Exception):
     """Raised when configuration loading or validation fails."""
 
     pass
 
 
-# PoolSettings class removed - connection pooling functionality has been removed
-
-
 class Settings(BaseSettings):
     """
     Configuration settings for the Claude Proxy API Server.
@@ -64,12 +66,16 @@ class Settings(BaseSettings):
         env_nested_delimiter="__",
     )
 
-    # Core application settings
     server: ServerSettings = Field(
         default_factory=ServerSettings,
         description="Server configuration settings",
     )
 
+    logging: LoggingSettings = Field(
+        default_factory=LoggingSettings,
+        description="Centralized logging configuration",
+    )
+
     security: SecuritySettings = Field(
         default_factory=SecuritySettings,
         description="Security configuration settings",
@@ -80,230 +86,75 @@ class Settings(BaseSettings):
         description="CORS configuration settings",
     )
 
-    # Claude-specific settings
-    claude: ClaudeSettings = Field(
-        default_factory=ClaudeSettings,
-        description="Claude-specific configuration settings",
-    )
-
-    # Codex-specific settings
-    codex: CodexSettings = Field(
-        default_factory=CodexSettings,
-        description="OpenAI Codex-specific configuration settings",
-    )
-
-    # Proxy and authentication
-    reverse_proxy: ReverseProxySettings = Field(
-        default_factory=ReverseProxySettings,
-        description="Reverse proxy configuration settings",
+    http: HTTPSettings = Field(
+        default_factory=HTTPSettings,
+        description="HTTP client configuration settings",
+        json_schema_extra={"config_example_hidden": True},
     )
 
     auth: AuthSettings = Field(
-        default_factory=AuthSettings,
-        description="Authentication and credentials configuration",
-    )
-
-    # Container settings
-    docker: DockerSettings = Field(
-        default_factory=DockerSettings,
-        description="Docker configuration for running Claude commands in containers",
+        default_factory=_auth_default,
+        description="Authentication manager settings (e.g., credentials caching)",
     )
 
-    # Observability settings
-    observability: ObservabilitySettings = Field(
-        default_factory=ObservabilitySettings,
-        description="Observability configuration settings",
+    binary: BinarySettings = Field(
+        default_factory=BinarySettings,
+        description="Binary resolution and package manager fallback configuration",
+        json_schema_extra={"config_example_hidden": True},
     )
 
-    # Scheduler settings
     scheduler: SchedulerSettings = Field(
         default_factory=SchedulerSettings,
         description="Task scheduler configuration settings",
+        json_schema_extra={"config_example_hidden": True},
     )
 
-    # Pricing settings
-    pricing: PricingSettings = Field(
-        default_factory=PricingSettings,
-        description="Pricing and cost calculation configuration settings",
+    plugin_discovery: PluginDiscoverySettings = Field(
+        default_factory=PluginDiscoverySettings,
+        description="Filesystem plugin discovery search paths",
+        json_schema_extra={"config_example_hidden": True},
     )
 
-    @field_validator("server", mode="before")
-    @classmethod
-    def validate_server(cls, v: Any) -> Any:
-        """Validate and convert server settings."""
-        if v is None:
-            return ServerSettings()
-        if isinstance(v, ServerSettings):
-            return v
-        if isinstance(v, dict):
-            return ServerSettings(**v)
-        return v
-
-    @field_validator("security", mode="before")
-    @classmethod
-    def validate_security(cls, v: Any) -> Any:
-        """Validate and convert security settings."""
-        if v is None:
-            return SecuritySettings()
-        if isinstance(v, SecuritySettings):
-            return v
-        if isinstance(v, dict):
-            return SecuritySettings(**v)
-        return v
-
-    @field_validator("cors", mode="before")
-    @classmethod
-    def validate_cors(cls, v: Any) -> Any:
-        """Validate and convert CORS settings."""
-        if v is None:
-            return CORSSettings()
-        if isinstance(v, CORSSettings):
-            return v
-        if isinstance(v, dict):
-            return CORSSettings(**v)
-        return v
-
-    @field_validator("claude", mode="before")
-    @classmethod
-    def validate_claude(cls, v: Any) -> Any:
-        """Validate and convert Claude settings."""
-        if v is None:
-            return ClaudeSettings()
-        if isinstance(v, ClaudeSettings):
-            return v
-        if isinstance(v, dict):
-            return ClaudeSettings(**v)
-        return v
-
-    @field_validator("codex", mode="before")
-    @classmethod
-    def validate_codex(cls, v: Any) -> Any:
-        """Validate and convert Codex settings."""
-        if v is None:
-            return CodexSettings()
-        if isinstance(v, CodexSettings):
-            return v
-        if isinstance(v, dict):
-            return CodexSettings(**v)
-        return v
-
-    @field_validator("reverse_proxy", mode="before")
-    @classmethod
-    def validate_reverse_proxy(cls, v: Any) -> Any:
-        """Validate and convert reverse proxy settings."""
-        if v is None:
-            return ReverseProxySettings()
-        if isinstance(v, ReverseProxySettings):
-            return v
-        if isinstance(v, dict):
-            return ReverseProxySettings(**v)
-        return v
-
-    @field_validator("auth", mode="before")
-    @classmethod
-    def validate_auth(cls, v: Any) -> Any:
-        """Validate and convert auth settings."""
-        if v is None:
-            return AuthSettings()
-        if isinstance(v, AuthSettings):
-            return v
-        if isinstance(v, dict):
-            return AuthSettings(**v)
-        return v
-
-    @field_validator("docker", mode="before")
-    @classmethod
-    def validate_docker_settings(cls, v: Any) -> Any:
-        """Validate and convert Docker settings."""
-        if v is None:
-            return DockerSettings()
+    enable_plugins: bool = Field(
+        default=True,
+        description="Enable plugin system",
+        json_schema_extra={"config_example_hidden": True},
+    )
 
-        # If it's already a DockerSettings instance, return as-is
-        if isinstance(v, DockerSettings):
-            return v
+    plugins_disable_local_discovery: bool = Field(
+        default=False,
+        description=(
+            "If true, skip filesystem plugin discovery from the local 'plugins/' directory "
+            "and load plugins only from installed entry points."
+        ),
+        json_schema_extra={"config_example_hidden": True},
+    )
 
-        # If it's a dict, create DockerSettings from it
-        if isinstance(v, dict):
-            return DockerSettings(**v)
+    enabled_plugins: list[str] | None = Field(
+        default=None,
+        description="List of explicitly enabled plugins (None = all enabled). Takes precedence over disabled_plugins.",
+        json_schema_extra={"config_example_hidden": False},
+    )
 
-        # Try to convert to dict if possible
-        if hasattr(v, "model_dump"):
-            return DockerSettings(**v.model_dump())
-        elif hasattr(v, "__dict__"):
-            return DockerSettings(**v.__dict__)
+    disabled_plugins: list[str] | None = Field(
+        default=None,
+        description="List of explicitly disabled plugins.",
+        json_schema_extra={"config_example_hidden": True},
+    )
 
-        return v
+    # CLI context for plugin access (set dynamically)
+    cli_context: dict[str, Any] = Field(default_factory=dict, exclude=True)
 
-    @field_validator("observability", mode="before")
-    @classmethod
-    def validate_observability(cls, v: Any) -> Any:
-        """Validate and convert observability settings."""
-        if v is None:
-            return ObservabilitySettings()
-        if isinstance(v, ObservabilitySettings):
-            return v
-        if isinstance(v, dict):
-            return ObservabilitySettings(**v)
-        return v
-
-    @field_validator("scheduler", mode="before")
-    @classmethod
-    def validate_scheduler(cls, v: Any) -> Any:
-        """Validate and convert scheduler settings."""
-        if v is None:
-            return SchedulerSettings()
-        if isinstance(v, SchedulerSettings):
-            return v
-        if isinstance(v, dict):
-            return SchedulerSettings(**v)
-        return v
-
-    @field_validator("pricing", mode="before")
-    @classmethod
-    def validate_pricing(cls, v: Any) -> Any:
-        """Validate and convert pricing settings."""
-        if v is None:
-            return PricingSettings()
-        if isinstance(v, PricingSettings):
-            return v
-        if isinstance(v, dict):
-            return PricingSettings(**v)
-        return v
-
-    # validate_pool_settings method removed - connection pooling functionality has been removed
+    plugins: dict[str, dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Plugin-specific configurations keyed by plugin name",
+    )
 
     @property
     def server_url(self) -> str:
         """Get the complete server URL."""
         return f"http://{self.server.host}:{self.server.port}"
 
-    @property
-    def is_development(self) -> bool:
-        """Check if running in development mode."""
-        return self.server.reload or self.server.log_level == "DEBUG"
-
-    @model_validator(mode="after")
-    def setup_claude_cli_path(self) -> "Settings":
-        """Set up Claude CLI path in environment if provided or found."""
-        # If not explicitly set, try to find it
-        if not self.claude.cli_path:
-            found_path, found_in_path = self.claude.find_claude_cli()
-            if found_path:
-                self.claude.cli_path = found_path
-                # Only add to PATH if it wasn't found via which()
-                if not found_in_path:
-                    cli_dir = str(Path(self.claude.cli_path).parent)
-                    current_path = os.environ.get("PATH", "")
-                    if cli_dir not in current_path:
-                        os.environ["PATH"] = f"{cli_dir}:{current_path}"
-        elif self.claude.cli_path:
-            # If explicitly set, always add to PATH
-            cli_dir = str(Path(self.claude.cli_path).parent)
-            current_path = os.environ.get("PATH", "")
-            if cli_dir not in current_path:
-                os.environ["PATH"] = f"{cli_dir}:{current_path}"
-        return self
-
     def model_dump_safe(self) -> dict[str, Any]:
         """
         Dump model data with sensitive information masked.
@@ -311,21 +162,61 @@ class Settings(BaseSettings):
         Returns:
             dict: Configuration with sensitive data masked
         """
-        return self.model_dump()
+        return self.model_dump(mode="json")
 
     @classmethod
-    def load_toml_config(cls, toml_path: Path) -> dict[str, Any]:
-        """Load configuration from a TOML file.
+    def _validate_deprecated_keys(cls, config_data: dict[str, Any]) -> None:
+        """Fail fast if deprecated legacy config keys are present."""
+        deprecated_hits: list[tuple[str, str]] = []
+
+        scheduler_cfg = config_data.get("scheduler") or {}
+        if isinstance(scheduler_cfg, dict):
+            key_map = {
+                "pushgateway_enabled": "plugins.metrics.pushgateway_enabled",
+                "pushgateway_url": "plugins.metrics.pushgateway_url",
+                "pushgateway_job": "plugins.metrics.pushgateway_job",
+                "pushgateway_interval_seconds": "plugins.metrics.pushgateway_push_interval",
+            }
+            for old_key, new_key in key_map.items():
+                if old_key in scheduler_cfg:
+                    deprecated_hits.append((f"scheduler.{old_key}", new_key))
 
-        Args:
-            toml_path: Path to the TOML configuration file
+        if "observability" in config_data:
+            deprecated_hits.append(
+                ("observability.*", "plugins.* (metrics/analytics/dashboard)")
+            )
 
-        Returns:
-            dict: Configuration data from the TOML file
+        for env_key in os.environ:
+            upper = env_key.upper()
+            if upper.startswith("SCHEDULER__PUSHGATEWAY_"):
+                env_map = {
+                    "SCHEDULER__PUSHGATEWAY_ENABLED": "plugins.metrics.pushgateway_enabled",
+                    "SCHEDULER__PUSHGATEWAY_URL": "plugins.metrics.pushgateway_url",
+                    "SCHEDULER__PUSHGATEWAY_JOB": "plugins.metrics.pushgateway_job",
+                    "SCHEDULER__PUSHGATEWAY_INTERVAL_SECONDS": "plugins.metrics.pushgateway_push_interval",
+                }
+                target = env_map.get(upper, "plugins.metrics.*")
+                deprecated_hits.append((env_key, target))
+            if upper.startswith("OBSERVABILITY__"):
+                deprecated_hits.append(
+                    (env_key, "plugins.* (metrics/analytics/dashboard)")
+                )
 
-        Raises:
-            ValueError: If the TOML file is invalid or cannot be read
-        """
+        if deprecated_hits:
+            lines = [
+                "Removed configuration keys detected. The following are no longer supported:",
+            ]
+            for old, new in deprecated_hits:
+                lines.append(f"- {old} → {new}")
+            lines.append(
+                "Configure corresponding plugin settings under [plugins.*]. "
+                "See: ccproxy/plugins/metrics/README.md and the Plugin Config Quickstart."
+            )
+            raise ValueError("\n".join(lines))
+
+    @classmethod
+    def load_toml_config(cls, toml_path: Path) -> dict[str, Any]:
+        """Load configuration from a TOML file."""
         try:
             with toml_path.open("rb") as f:
                 return tomllib.load(f)
@@ -336,17 +227,7 @@ class Settings(BaseSettings):
 
     @classmethod
     def load_config_file(cls, config_path: Path) -> dict[str, Any]:
-        """Load configuration from a file based on its extension.
-
-        Args:
-            config_path: Path to the configuration file
-
-        Returns:
-            dict: Configuration data from the file
-
-        Raises:
-            ValueError: If the file format is unsupported or invalid
-        """
+        """Load configuration from a file based on its extension."""
         suffix = config_path.suffix.lower()
 
         if suffix in [".toml"]:
@@ -359,219 +240,279 @@ class Settings(BaseSettings):
 
     @classmethod
     def from_toml(cls, toml_path: Path | None = None, **kwargs: Any) -> "Settings":
-        """Create Settings instance from TOML configuration.
-
-        Args:
-            toml_path: Path to TOML configuration file. If None, auto-discovers file.
-            **kwargs: Additional keyword arguments to override config values
-
-        Returns:
-            Settings: Configured Settings instance
-        """
-        # Use the more generic from_config method
+        """Create Settings instance from TOML configuration."""
         return cls.from_config(config_path=toml_path, **kwargs)
 
+    # ------------------------------
+    # Internal helpers (merging/overrides)
+    # ------------------------------
+    @staticmethod
+    def _env_has_prefix(prefix: str) -> bool:
+        p = prefix.upper()
+        return any(k.upper().startswith(p) for k in os.environ)
+
+    @staticmethod
+    def _merge_model(
+        model: BaseModel, overrides: dict[str, Any], env_prefix: str
+    ) -> BaseModel:
+        """
+        Deep-merge a dict of overrides into a BaseModel while preserving env-var precedence.
+        env_prefix should end with '__' when called for nested fields.
+        """
+        update_payload: dict[str, Any] = {}
+
+        for field_name, override_value in overrides.items():
+            field_env_key = f"{env_prefix}{field_name.upper()}"
+            # If an env var exists for this field, do NOT override from file.
+            if os.getenv(field_env_key) is not None:
+                continue
+
+            current_value = getattr(model, field_name, None)
+
+            if isinstance(current_value, BaseModel) and isinstance(
+                override_value, dict
+            ):
+                nested_prefix = f"{field_env_key}__"
+                merged_nested = Settings._merge_model(
+                    current_value, override_value, nested_prefix
+                )
+                update_payload[field_name] = merged_nested
+            elif isinstance(current_value, dict) and isinstance(override_value, dict):
+                # Deep-merge dict but skip keys that have env overrides
+                merged_dict = current_value.copy()
+                for nk, nv in override_value.items():
+                    nested_env_key = f"{field_env_key}__{nk.upper()}"
+                    if os.getenv(nested_env_key) is None:
+                        if isinstance(merged_dict.get(nk), dict) and isinstance(
+                            nv, dict
+                        ):
+                            # deep merge nested dicts with respect to env
+                            merged_dict[nk] = Settings._merge_dict(
+                                merged_dict.get(nk, {}), nv, f"{nested_env_key}__"
+                            )
+                        else:
+                            merged_dict[nk] = nv
+                update_payload[field_name] = merged_dict
+            else:
+                update_payload[field_name] = override_value
+
+        if not update_payload:
+            return model
+        return model.model_copy(update=update_payload)
+
+    @staticmethod
+    def _merge_dict(
+        base: dict[str, Any], overrides: dict[str, Any], env_prefix: str
+    ) -> dict[str, Any]:
+        """
+        Deep-merge dicts while respecting env-var precedence using the given env_prefix (no trailing __ required).
+        """
+        out = dict(base)
+        for k, v in overrides.items():
+            key_env = f"{env_prefix}{k.upper()}"
+            if os.getenv(key_env) is not None:
+                continue
+            if isinstance(out.get(k), dict) and isinstance(v, dict):
+                out[k] = Settings._merge_dict(out[k], v, f"{key_env}__")
+            else:
+                out[k] = v
+        return out
+
+    @staticmethod
+    def _merge_plugins(
+        current_plugins: dict[str, Any], overrides: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Merge plugin configuration trees with env precedence at both plugin and nested key levels.
+        """
+        merged = dict(current_plugins)
+        for plugin_name, plugin_cfg in overrides.items():
+            env_prefix = f"PLUGINS__{plugin_name.upper()}__"
+
+            # If any env for this plugin exists, we keep current_plugins[plugin_name] as-is,
+            # but we still allow env-free nested keys to merge if we already have a dict.
+            if isinstance(plugin_cfg, dict):
+                if Settings._env_has_prefix(env_prefix):
+                    # Partial merge respecting env at nested levels if the plugin already exists as a dict.
+                    if isinstance(merged.get(plugin_name), dict):
+                        merged[plugin_name] = Settings._merge_dict(
+                            merged[plugin_name],
+                            plugin_cfg,
+                            env_prefix,
+                        )
+                    else:
+                        # Keep existing unless it's missing entirely.
+                        merged.setdefault(plugin_name, merged.get(plugin_name, {}))
+                else:
+                    existing = merged.get(plugin_name, {})
+                    if isinstance(existing, dict):
+                        merged[plugin_name] = Settings._merge_dict(
+                            existing, plugin_cfg, env_prefix
+                        )
+                    else:
+                        merged[plugin_name] = plugin_cfg
+            else:
+                # Non-dict plugin setting: only apply if no top-level env overrides present.
+                if not Settings._env_has_prefix(env_prefix):
+                    merged[plugin_name] = plugin_cfg
+        return merged
+
+    @staticmethod
+    def _apply_overrides(target: Any, overrides: dict[str, Any]) -> None:
+        """
+        Apply CLI/kwargs overrides after file and env processing.
+        Dicts are shallow-merged; nested BaseModels recurse.
+        """
+        for k, v in overrides.items():
+            if (
+                isinstance(v, dict)
+                and hasattr(target, k)
+                and isinstance(getattr(target, k), (BaseModel | dict))
+            ):
+                sub = getattr(target, k)
+                if isinstance(sub, BaseModel):
+                    # Apply directly field-by-field
+                    Settings._apply_overrides(sub, v)
+                elif isinstance(sub, dict):
+                    sub.update(v)
+            else:
+                setattr(target, k, v)
+
+    # ------------------------------
+    # Factory
+    # ------------------------------
     @classmethod
     def from_config(
-        cls, config_path: Path | str | None = None, **kwargs: Any
+        cls,
+        config_path: Path | str | None = None,
+        cli_context: dict[str, Any] | None = None,
+        **kwargs: Any,
     ) -> "Settings":
-        """Create Settings instance from configuration file.
+        """Create Settings instance from configuration file with env precedence and safe merging."""
+        logger = get_logger(__name__)
 
-        Args:
-            config_path: Path to configuration file. Can be:
-                - None: Auto-discover config file or use CONFIG_FILE env var
-                - Path or str: Use this specific config file
-            **kwargs: Additional keyword arguments to override config values
+        global _CONFIG_MISSING_LOGGED
 
-        Returns:
-            Settings: Configured Settings instance
-        """
-        # Check for CONFIG_FILE environment variable first
         if config_path is None:
             config_path_env = os.environ.get("CONFIG_FILE")
             if config_path_env:
                 config_path = Path(config_path_env)
 
-        # Convert string to Path if needed
         if isinstance(config_path, str):
             config_path = Path(config_path)
 
-        # Auto-discover config file if not provided
         if config_path is None:
             config_path = find_toml_config_file()
 
-        # Load config if found
-        config_data = {}
+        config_data: dict[str, Any] = {}
         if config_path and config_path.exists():
             config_data = cls.load_config_file(config_path)
-
-        # Merge config with kwargs (kwargs take precedence)
-        merged_config = {**config_data, **kwargs}
-
-        # Create Settings instance with merged config
-        return cls(**merged_config)
-
-
-class ConfigurationManager:
-    """Centralized configuration management for CLI and server."""
-
-    def __init__(self) -> None:
-        self._settings: Settings | None = None
-        self._config_path: Path | None = None
-        self._logging_configured = False
-
-    def load_settings(
-        self,
-        config_path: Path | None = None,
-        cli_overrides: dict[str, Any] | None = None,
-    ) -> Settings:
-        """Load settings with CLI overrides and caching."""
-        if self._settings is None or config_path != self._config_path:
-            try:
-                self._settings = Settings.from_config(
-                    config_path=config_path, **(cli_overrides or {})
-                )
-                self._config_path = config_path
-            except Exception as e:
-                raise ConfigurationError(f"Failed to load configuration: {e}") from e
-
-        return self._settings
-
-    def setup_logging(self, log_level: str | None = None) -> None:
-        """Configure logging once based on settings."""
-        if self._logging_configured:
-            return
-
-        # Import here to avoid circular import
-
-        effective_level = log_level or (
-            self._settings.server.log_level if self._settings else "INFO"
-        )
-
-        # Determine format based on log level - Rich for DEBUG, JSON for production
-        format_type = "rich" if effective_level.upper() == "DEBUG" else "json"
-
-        # setup_dual_logging(
-        #     level=effective_level,
-        #     format_type=format_type,
-        #     configure_uvicorn=True,
-        #     verbose_tracebacks=effective_level.upper() == "DEBUG",
-        # )
-        self._logging_configured = True
-
-    def get_cli_overrides_from_args(self, **cli_args: Any) -> dict[str, Any]:
-        """Extract non-None CLI arguments as configuration overrides."""
-        overrides = {}
-
-        # Server settings
-        server_settings = {}
-        for key in ["host", "port", "reload", "log_level", "log_file"]:
-            if cli_args.get(key) is not None:
-                server_settings[key] = cli_args[key]
-        if server_settings:
-            overrides["server"] = server_settings
-
-        # Security settings
-        if cli_args.get("auth_token") is not None:
-            overrides["security"] = {"auth_token": cli_args["auth_token"]}
-
-        # Claude settings
-        claude_settings = {}
-        if cli_args.get("claude_cli_path") is not None:
-            claude_settings["cli_path"] = cli_args["claude_cli_path"]
-
-        # Direct Claude settings (not nested in code_options)
-        for key in [
-            "sdk_message_mode",
-            "system_prompt_injection_mode",
-            "builtin_permissions",
-        ]:
-            if cli_args.get(key) is not None:
-                claude_settings[key] = cli_args[key]
-
-        # Handle pool configuration
-        if cli_args.get("sdk_pool") is not None:
-            claude_settings["sdk_pool"] = {"enabled": cli_args["sdk_pool"]}
-
-        if cli_args.get("sdk_pool_size") is not None:
-            if "sdk_pool" not in claude_settings:
-                claude_settings["sdk_pool"] = {}
-            claude_settings["sdk_pool"]["pool_size"] = cli_args["sdk_pool_size"]
-
-        if cli_args.get("sdk_session_pool") is not None:
-            claude_settings["sdk_session_pool"] = {
-                "enabled": cli_args["sdk_session_pool"]
-            }
-
-        # Claude Code options
-        claude_opts = {}
-        for key in [
-            "max_thinking_tokens",
-            "permission_mode",
-            "cwd",
-            "max_turns",
-            "append_system_prompt",
-            "permission_prompt_tool_name",
-            "continue_conversation",
-        ]:
-            if cli_args.get(key) is not None:
-                claude_opts[key] = cli_args[key]
-
-        # Handle comma-separated lists
-        for key in ["allowed_tools", "disallowed_tools"]:
-            if cli_args.get(key):
-                claude_opts[key] = [tool.strip() for tool in cli_args[key].split(",")]
-
-        if claude_opts:
-            claude_settings["code_options"] = claude_opts
-
-        if claude_settings:
-            overrides["claude"] = claude_settings
-
-        # CORS settings
-        if cli_args.get("cors_origins"):
-            overrides["cors"] = {
-                "origins": [
-                    origin.strip() for origin in cli_args["cors_origins"].split(",")
-                ]
+            logger.debug(
+                "config_file_loaded",
+                path=str(config_path),
+                category="config",
+            )
+        elif not _CONFIG_MISSING_LOGGED:
+            suggestion = f"ccproxy config init --output-dir {get_ccproxy_config_dir()}"
+            log_kwargs: dict[str, Any] = {
+                "category": "config",
+                "suggested_command": suggestion,
             }
+            if config_path is not None:
+                log_kwargs["path"] = str(config_path)
+            logger.warning("config_file_missing", **log_kwargs)
+            _CONFIG_MISSING_LOGGED = True
+
+        cls._validate_deprecated_keys(config_data)
+
+        # Start from env + .env via BaseSettings
+        settings = cls()
+
+        # Merge file-based configuration with env-var precedence
+        for key, value in config_data.items():
+            if not hasattr(settings, key):
+                continue
+
+            if key == "plugins" and isinstance(value, dict):
+                current_plugins = getattr(settings, key, {})
+                merged_plugins = cls._merge_plugins(current_plugins, value)
+                setattr(settings, key, merged_plugins)
+                continue
+
+            current_attr = getattr(settings, key)
+
+            if isinstance(value, dict) and isinstance(current_attr, BaseModel):
+                merged_model = cls._merge_model(current_attr, value, f"{key.upper()}__")
+                setattr(settings, key, merged_model)
+            else:
+                # Only set top-level simple types if there is no top-level env override
+                env_key = key.upper()
+                if os.getenv(env_key) is None:
+                    setattr(settings, key, value)
+
+        # Smart default: if no config file exists and enabled_plugins is still None,
+        # set a curated default list of core plugins
+        if not config_path or not config_path.exists():
+            if settings.enabled_plugins is None:
+                settings.enabled_plugins = DEFAULT_ENABLED_PLUGINS
+
+        # Apply direct kwargs overrides (highest precedence within process)
+        if kwargs:
+            cls._apply_overrides(settings, kwargs)
+
+        # Apply CLI context (explicit flags)
+        if cli_context:
+            # Store raw CLI context for plugin access
+            settings.cli_context = cli_context
+
+            # Apply common serve CLI overrides directly to settings
+            server_overrides: dict[str, Any] = {}
+            if cli_context.get("host") is not None:
+                server_overrides["host"] = cli_context["host"]
+            if cli_context.get("port") is not None:
+                server_overrides["port"] = cli_context["port"]
+            if cli_context.get("reload") is not None:
+                server_overrides["reload"] = cli_context["reload"]
+
+            logging_overrides: dict[str, Any] = {}
+            if cli_context.get("log_level") is not None:
+                logging_overrides["level"] = cli_context["log_level"]
+            if cli_context.get("log_file") is not None:
+                logging_overrides["file"] = cli_context["log_file"]
+
+            security_overrides: dict[str, Any] = {}
+            if cli_context.get("auth_token") is not None:
+                security_overrides["auth_token"] = cli_context["auth_token"]
+
+            if server_overrides:
+                cls._apply_overrides(settings, {"server": server_overrides})
+            if logging_overrides:
+                cls._apply_overrides(settings, {"logging": logging_overrides})
+            if security_overrides:
+                cls._apply_overrides(settings, {"security": security_overrides})
+
+            # Apply plugin enable/disable lists if provided
+            enabled_plugins = cli_context.get("enabled_plugins")
+            disabled_plugins = cli_context.get("disabled_plugins")
+            if enabled_plugins is not None:
+                settings.enabled_plugins = list(enabled_plugins)
+            if disabled_plugins is not None:
+                settings.disabled_plugins = list(disabled_plugins)
 
-        return overrides
-
-    def reset(self) -> None:
-        """Reset configuration state (useful for testing)."""
-        self._settings = None
-        self._config_path = None
-        self._logging_configured = False
-
-
-# Global configuration manager instance
-config_manager = ConfigurationManager()
-
-logger = structlog.get_logger(__name__)
+        return settings
 
+    def get_cli_context(self) -> dict[str, Any]:
+        """Get CLI context for plugin access."""
+        return self.cli_context
 
-def get_settings(config_path: Path | str | None = None) -> Settings:
-    """Get the global settings instance with configuration file support.
+    class LLMSettings(BaseModel):
+        """LLM-specific feature toggles and defaults."""
 
-    Args:
-        config_path: Optional path to configuration file. If None, uses CONFIG_FILE env var
-                    or auto-discovers config file.
+        openai_thinking_xml: bool = Field(
+            default=True, description="Serialize thinking as XML in OpenAI streams"
+        )
 
-    Returns:
-        Settings: Configured Settings instance
-    """
-    try:
-        # Check for CLI overrides from environment variable
-        cli_overrides = {}
-        cli_overrides_json = os.environ.get("CCPROXY_CONFIG_OVERRIDES")
-        if cli_overrides_json:
-            with contextlib.suppress(json.JSONDecodeError):
-                cli_overrides = json.loads(cli_overrides_json)
-
-        settings = Settings.from_config(config_path=config_path, **cli_overrides)
-        return settings
-    except Exception as e:
-        # If settings can't be loaded (e.g., missing API key),
-        # this will be handled by the caller
-        raise ValueError(f"Configuration error: {e}") from e
+    llm: LLMSettings = Field(
+        default_factory=LLMSettings,
+        description="Large Language Model (LLM) settings",
+    )