refactor(config): migrate configuration to new structure

Author: HYP3R00T

docs/contributing/adding-service.md

@@ -53,7 +53,7 @@ If the service only supports a subset of regions, rely on `session.get_available
 
 ## 4. Update defaults and documentation
 
-- Append the service name to `aws.services` in `src/costcutter/conf/config.yaml`
+- Append the service name to `aws.services` defaults in `src/costcutter/config.py`
 - Refresh relevant documentation (for example `docs/guide/supported-services.md`)
 
 ## 5. Write tests

docs/guide/architecture.md

@@ -9,7 +9,7 @@ This section explains how the main pieces of CostCutter fit together and why the
 - Renders a Rich live table of events while orchestration runs and a summary when it finishes
 - Handles banner rendering, CSV export messaging, and keyboard interrupt handling
 
-**Configuration loader (`src/costcutter/conf/config.py`)**
+**Configuration loader (`src/costcutter/config.py`)**
 - Loads the default YAML file bundled with the package
 - Merges home directory overrides, an explicit file, environment variables, and CLI arguments
 - Exposes the merged result through a lightweight `Config` wrapper that supports attribute access
@@ -38,7 +38,7 @@ This section explains how the main pieces of CostCutter fit together and why the
 ## Data flow
 
 1. CLI parses arguments and clears the terminal
-2. `get_config` merges configuration sources into a single object
+2. `load_config` merges configuration sources into a single object
 3. Logging is initialised based on the merged configuration
 4. The orchestrator resolves regions and services, then creates an AWS session via `create_aws_session`
 5. Each `(region, service)` pair runs in the thread pool and calls the appropriate handler

docs/guide/config-reference.md

@@ -6,7 +6,7 @@ Complete guide to configuring CostCutter.
 
 CostCutter merges configuration from multiple sources in this order (later sources override earlier ones):
 
-1. **Default Config** - Built-in defaults (`src/costcutter/conf/config.yaml`)
+1. **Default Config** - Built-in defaults (defined in `src/costcutter/config.py`)
 2. **Home Config** - User's home directory (`~/.costcutter.{yaml,yml,toml,json}`)
 3. **Explicit File** - File specified via `--config` flag or `config_file` parameter
 4. **Environment Variables** - Shell environment variables with `COSTCUTTER_` prefix
@@ -18,7 +18,7 @@ CostCutter merges configuration from multiple sources in this order (later sourc
 
 ### Method 1: Default Configuration (Built-in)
 
-Located at `src/costcutter/conf/config.yaml`. Used automatically if no other config is provided.
+Defined in `src/costcutter/config.py`. Used automatically if no other config is provided.
 
 **Default Configuration:**
 
@@ -114,9 +114,9 @@ costcutter --config /path/to/myconfig.yaml
 
 ```python
 from pathlib import Path
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 
-config = get_config(config_file=Path("/path/to/myconfig.yaml"))
+config = load_config()
 ```
 
 **Supported formats:** `.yaml`, `.yml`, `.toml`, `.json`
@@ -177,12 +177,12 @@ export COSTCUTTER_AWS__SERVICES="[ec2, s3]"  # List
 
 ```python
 import os
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 
 os.environ["COSTCUTTER_DRY_RUN"] = "false"
 os.environ["COSTCUTTER_AWS__REGION"] = "[us-east-1]"
 
-config = get_config()
+config = load_config()
 ```
 
 **Priority:** Overrides defaults, home config, and explicit files. Only CLI arguments have higher priority.
@@ -207,7 +207,7 @@ costcutter --config myconfig.yaml --dry-run
 **Python API:**
 
 ```python
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 
 cli_overrides = {
     "dry_run": False,
@@ -216,7 +216,7 @@ cli_overrides = {
     }
 }
 
-config = get_config(cli_args=cli_overrides)
+config = load_config(overrides=cli_overrides)
 ```
 
 **Priority:** Highest priority. Overrides all other sources.
@@ -228,11 +228,11 @@ Import and configure programmatically:
 ### Basic Usage
 
 ```python
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 from costcutter.orchestrator import orchestrate_services
 
 # Load default config
-config = get_config()
+config = load_config()
 
 # Run cleanup
 orchestrate_services(dry_run=True)
@@ -241,53 +241,42 @@ orchestrate_services(dry_run=True)
 ### Custom Configuration
 
 ```python
-from pathlib import Path
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 
-# Method 1: Use config file
-config = get_config(config_file=Path("./myconfig.yaml"))
+# Method 1: Load with defaults (auto-discovers config files)
+config = load_config()
 
-# Method 2: Override via CLI args
-config = get_config(cli_args={
+# Method 2: Override via runtime parameters
+config = load_config(overrides={
     "dry_run": False,
     "aws": {
         "region": ["us-west-2"],
         "services": ["ec2", "s3"]
     }
 })
-
-# Method 3: Combine both
-config = get_config(
-    config_file=Path("./base.yaml"),
-    cli_args={"dry_run": False}
-)
 ```
 
 ### Reload Configuration
 
 ```python
-from costcutter.conf.config import reload_config
+from costcutter.config import load_config
 
 # Reload with new settings
-config = reload_config(cli_args={"dry_run": False})
+config = load_config(overrides={"dry_run": False})
 ```
 
 ### Access Configuration Values
 
 ```python
-config = get_config()
+config = load_config()
 
 # Dot notation
 print(config.dry_run)
 print(config.aws.region)
 print(config.logging.level)
 
-# Dictionary notation
-print(config["dry_run"])
-print(config["aws"]["region"])
-
 # Convert to dict
-config_dict = config.to_dict()
+config_dict = config.model_dump()
 print(config_dict["aws"]["services"])
 ```
 
@@ -525,22 +514,18 @@ costcutter
 
 ```python
 # cleanup.py
-from pathlib import Path
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 from costcutter.orchestrator import orchestrate_services
 from costcutter.logger import setup_logging
 
-# Load configuration
-config = get_config(
-    config_file=Path("./config.yaml"),
-    cli_args={
-        "dry_run": False,
-        "aws": {
-            "region": ["us-east-1"],
-            "services": ["ec2"]
-        }
+# Load configuration with overrides
+config = load_config(overrides={
+    "dry_run": False,
+    "aws": {
+        "region": ["us-east-1"],
+        "services": ["ec2"]
     }
-)
+})
 
 # Setup logging
 setup_logging(config)
@@ -644,10 +629,10 @@ costcutter --config myconfig.txt
 **Debug configuration:**
 
 ```python
-from costcutter.conf.config import get_config
+from costcutter.config import load_config
 
-config = get_config()
-print(config.to_dict())  # See final merged config
+config = load_config()
+print(config.model_dump())  # See final merged config
 ```
 
 ### Environment variables not working
@@ -662,7 +647,7 @@ print(config.to_dict())  # See final merged config
 
 ```bash
 export COSTCUTTER_DRY_RUN=false
-python -c "import os; from costcutter.conf.config import get_config; print(get_config().dry_run)"
+python -c "import os; from costcutter.config import load_config; print(load_config().dry_run)"
 # Should print: False
 ```
 

docs/guide/how-it-works.md

@@ -5,7 +5,7 @@ This page breaks down a single CostCutter run from CLI invocation to final summa
 ## High level timeline
 
 1. **CLI start** - Typer parses flags, clears the console, and prints the ASCII banner
-2. **Configuration merge** - `get_config` loads defaults, home overrides, optional files, environment variables, and CLI overrides
+2. **Configuration merge** - `load_config` loads defaults, home overrides, optional files, environment variables, and CLI overrides
 3. **Logging** - `setup_logging` configures file handlers and suppresses noisy libraries
 4. **Session creation** - `create_aws_session` builds a boto3 session using explicit keys, a credential file, or the default resolver
 5. **Worklist build** - the orchestrator pairs each configured region with each requested service and filters out unsupported region/service combinations
@@ -37,7 +37,7 @@ This page breaks down a single CostCutter run from CLI invocation to final summa
 
 Configuration sources apply in this order:
 
-1. Bundled defaults (`src/costcutter/conf/config.yaml`)
+1. Built-in defaults (defined in `src/costcutter/config.py`)
 2. Home overrides (`~/.costcutter.yaml`, `.yml`, `.toml`, `.json`)
 3. Explicit file from `--config`
 4. Environment variables prefixed with `COSTCUTTER_`

docs/usage-cli.md

@@ -18,7 +18,7 @@ All modes expose the same options.
 | `--no-dry-run` | Disable dry run for the current invocation. |
 | `--config PATH` | Load an explicit YAML, YML, TOML, or JSON file. |
 
-Dry run is enabled by default through `src/costcutter/conf/config.yaml`. Use `--no-dry-run` only when you intend to delete resources.
+Dry run is enabled by default. Use `--no-dry-run` only when you intend to delete resources.
 
 ## Typical Workflows
 

src/costcutter/__init__.py

@@ -1,4 +1,4 @@
-from costcutter.conf.config import load_config
+from costcutter.config import load_config
 from costcutter.logger import setup_logging
 from costcutter.main import run
 

src/costcutter/cli.py

@@ -11,7 +11,7 @@
 from rich.live import Live
 from rich.table import Table
 
-from costcutter.conf.config import load_config
+from costcutter.config import load_config
 from costcutter.logger import setup_logging
 from costcutter.orchestrator import orchestrate_services
 from costcutter.reporter import get_reporter

src/costcutter/conf/__init__.py

@@ -1,42 +1,26 @@
 import logging
 import os
-from typing import Any
 
 import boto3
 from boto3.session import Session
-from pydantic import BaseModel
 
-from costcutter.conf.config import Config
+from costcutter.config import Config
 
 logger = logging.getLogger(__name__)
 
 
-def _get_aws_value(aws_config: BaseModel | dict[str, Any] | object, key: str, default: str | None = None) -> str | None:
-    """Extract value from aws config (BaseModel, dict, or object)."""
-    if isinstance(aws_config, BaseModel):
-        return getattr(aws_config, key, default)
-    if isinstance(aws_config, dict):
-        return aws_config.get(key, default)
-    return getattr(aws_config, key, default)
-
-
 def create_aws_session(config: Config) -> Session:
     """Create a boto3 Session based on aws-related settings in Config.
 
     Falls back through explicit keys, credential file, then default discovery.
     """
-    try:
-        aws_config = config.aws
-    except AttributeError:
-        aws_config = {}
-
-    # Handle dict-based aws_config
-    aws_access_key_id = _get_aws_value(aws_config, "aws_access_key_id")
-    aws_secret_access_key = _get_aws_value(aws_config, "aws_secret_access_key")
-    aws_session_token = _get_aws_value(aws_config, "aws_session_token")
-    credential_file_path_raw = _get_aws_value(aws_config, "credential_file_path", "")
-    credential_file_path = os.path.expanduser(credential_file_path_raw or "")
-    profile_name = _get_aws_value(aws_config, "profile", "default")
+    aws_config = config.aws
+
+    aws_access_key_id = aws_config.aws_access_key_id
+    aws_secret_access_key = aws_config.aws_secret_access_key
+    aws_session_token = aws_config.aws_session_token
+    credential_file_path = os.path.expanduser(aws_config.credential_file_path or "")
+    profile_name = aws_config.profile
 
     if aws_access_key_id and aws_secret_access_key:
         logger.info("Using credentials from config (access key + secret)")