mcp-souschef 3.2.0__py3-none-any.whl → 3.5.2__py3-none-any.whl

souschef/core/logging.py

@@ -0,0 +1,344 @@
+"""
+Structured logging configuration for SousChef.
+
+This module provides structured logging with JSON output support,
+contextual information, and integration with monitoring systems.
+"""
+
+import logging
+import sys
+from contextvars import ContextVar
+from typing import Any, Literal
+
+# Context variables for structured logging
+request_id_var: ContextVar[str | None] = ContextVar("request_id", default=None)
+operation_var: ContextVar[str | None] = ContextVar("operation", default=None)
+cookbook_var: ContextVar[str | None] = ContextVar("cookbook", default=None)
+
+
+class StructuredFormatter(logging.Formatter):
+    """
+    Formatter that outputs structured log records.
+
+    Supports both JSON and human-readable text formats.
+    """
+
+    def __init__(
+        self,
+        fmt: str | None = None,
+        datefmt: str | None = None,
+        style: Literal["%", "{", "$"] = "%",
+        json_format: bool = False,
+    ):
+        """
+        Initialise structured formatter.
+
+        Args:
+            fmt: Log format string (ignored if json_format=True).
+            datefmt: Date format string.
+            style: Format style ('%', '{', or '$').
+            json_format: Whether to output JSON format.
+
+        """
+        super().__init__(fmt, datefmt, style)
+        self.json_format = json_format
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format log record as structured output.
+
+        Args:
+            record: Log record to format.
+
+        Returns:
+            Formatted log string (JSON or text).
+
+        """
+        # Add context variables to record
+        record.request_id = request_id_var.get()
+        record.operation = operation_var.get()
+        record.cookbook = cookbook_var.get()
+
+        if self.json_format:
+            return self._format_json(record)
+        else:
+            return self._format_text(record)
+
+    def _format_json(self, record: logging.LogRecord) -> str:
+        """Format record as JSON."""
+        import json
+
+        log_data = {
+            "timestamp": self.formatTime(record, self.datefmt),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        # Add context if available
+        request_id = getattr(record, "request_id", None)
+        operation = getattr(record, "operation", None)
+        cookbook = getattr(record, "cookbook", None)
+
+        if request_id:
+            log_data["request_id"] = request_id
+        if operation:
+            log_data["operation"] = operation
+        if cookbook:
+            log_data["cookbook"] = cookbook
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        # Add extra fields
+        for key, value in record.__dict__.items():
+            if key not in {
+                "name",
+                "msg",
+                "args",
+                "created",
+                "msecs",
+                "levelname",
+                "levelno",
+                "pathname",
+                "filename",
+                "module",
+                "exc_info",
+                "exc_text",
+                "stack_info",
+                "lineno",
+                "funcName",
+                "processName",
+                "process",
+                "threadName",
+                "thread",
+                "request_id",
+                "operation",
+                "cookbook",
+                "message",
+                "asctime",
+                "relativeCreated",
+            } and not key.startswith("_"):
+                log_data[key] = value
+
+        return json.dumps(log_data, default=str)
+
+    def _format_text(self, record: logging.LogRecord) -> str:
+        """Format record as human-readable text."""
+        # Use parent formatter for base formatting
+        base_msg = super().format(record)
+
+        # Add context if available
+        context_parts = []
+        request_id = getattr(record, "request_id", None)
+        operation = getattr(record, "operation", None)
+        cookbook = getattr(record, "cookbook", None)
+
+        if request_id:
+            context_parts.append(f"request_id={request_id}")
+        if operation:
+            context_parts.append(f"operation={operation}")
+        if cookbook:
+            context_parts.append(f"cookbook={cookbook}")
+
+        if context_parts:
+            context_str = " [" + ", ".join(context_parts) + "]"
+            return base_msg + context_str
+
+        return base_msg
+
+
+def configure_logging(
+    level: str = "INFO",
+    json_format: bool = False,
+    log_file: str | None = None,
+) -> None:
+    """
+    Configure structured logging for SousChef.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        json_format: Whether to output JSON format.
+        log_file: Optional file path for log output.
+
+    """
+    # Convert string level to logging constant
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+    # Create formatter
+    if json_format:
+        formatter = StructuredFormatter(json_format=True)
+    else:
+        formatter = StructuredFormatter(
+            fmt="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(numeric_level)
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(numeric_level)
+    console_handler.setFormatter(formatter)
+    root_logger.addHandler(console_handler)
+
+    # File handler if specified
+    if log_file:
+        file_handler = logging.FileHandler(log_file)
+        file_handler.setLevel(numeric_level)
+        file_handler.setFormatter(formatter)
+        root_logger.addHandler(file_handler)
+
+    # Configure SousChef logger
+    souschef_logger = logging.getLogger("souschef")
+    souschef_logger.setLevel(numeric_level)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger instance for the given name.
+
+    Args:
+        name: Logger name (typically __name__).
+
+    Returns:
+        Configured logger instance.
+
+    """
+    return logging.getLogger(name)
+
+
+def set_context(
+    request_id: str | None = None,
+    operation: str | None = None,
+    cookbook: str | None = None,
+) -> None:
+    """
+    Set context variables for structured logging.
+
+    Args:
+        request_id: Unique request/operation ID.
+        operation: Current operation name.
+        cookbook: Cookbook being processed.
+
+    """
+    if request_id is not None:
+        request_id_var.set(request_id)
+    if operation is not None:
+        operation_var.set(operation)
+    if cookbook is not None:
+        cookbook_var.set(cookbook)
+
+
+def clear_context() -> None:
+    """Clear all context variables."""
+    request_id_var.set(None)
+    operation_var.set(None)
+    cookbook_var.set(None)
+
+
+class LogContext:
+    """
+    Context manager for temporary logging context.
+
+    Example:
+        with LogContext(operation="convert_recipe", cookbook="apache"):
+            logger.info("Converting recipe")
+
+    """
+
+    def __init__(
+        self,
+        request_id: str | None = None,
+        operation: str | None = None,
+        cookbook: str | None = None,
+    ):
+        """
+        Initialise log context.
+
+        Args:
+            request_id: Unique request/operation ID.
+            operation: Current operation name.
+            cookbook: Cookbook being processed.
+
+        """
+        self.request_id = request_id
+        self.operation = operation
+        self.cookbook = cookbook
+        self.previous_context: dict[str, Any] = {}
+
+    def __enter__(self) -> "LogContext":
+        """Enter context and save previous values."""
+        self.previous_context = {
+            "request_id": request_id_var.get(),
+            "operation": operation_var.get(),
+            "cookbook": cookbook_var.get(),
+        }
+        set_context(
+            request_id=self.request_id,
+            operation=self.operation,
+            cookbook=self.cookbook,
+        )
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context and restore previous values."""
+        request_id_var.set(self.previous_context["request_id"])
+        operation_var.set(self.previous_context["operation"])
+        cookbook_var.set(self.previous_context["cookbook"])
+
+
+def log_operation(operation_name: str):
+    """
+    Decorate functions to log operations with structured context.
+
+    Args:
+        operation_name: Name of the operation being logged.
+
+    Example:
+        @log_operation("convert_recipe")
+        def convert_recipe(recipe_path: str) -> str:
+            # Operation is logged with context
+            return playbook_content
+
+    """
+
+    def decorator(func):
+        import functools
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            logger = get_logger(func.__module__)
+
+            with LogContext(operation=operation_name):
+                logger.info(
+                    f"Starting {operation_name}",
+                    extra={"function": func.__name__},
+                )
+                try:
+                    result = func(*args, **kwargs)
+                    logger.info(
+                        f"Completed {operation_name}",
+                        extra={"function": func.__name__},
+                    )
+                    return result
+                except Exception as e:
+                    logger.error(
+                        f"Failed {operation_name}: {e}",
+                        extra={"function": func.__name__},
+                        exc_info=True,
+                    )
+                    raise
+
+        return wrapper
+
+    return decorator

souschef/core/metrics.py

@@ -33,49 +33,116 @@ class EffortMetrics:
     - Base unit: person-days (with decimal precision)
     - Derived: hours, weeks with consistent conversion factors
     - Ranges: For display purposes, converting days to week ranges
+    - WITH/WITHOUT SousChef: Shows effort reduction with AI assistance
 
     Ensures all components (migration planning, dependency mapping,
     validation reports) use the same underlying numbers.
     """
 
     estimated_days: float
-    """Base unit: person-days (e.g., 2.5, 5.0, 10.0)"""
+    """Base unit: person-days WITHOUT SousChef assistance (manual migration)"""
+
+    @property
+    def estimated_days_with_souschef(self) -> float:
+        """
+        Effort WITH SousChef AI assistance.
+
+        Realistic reduction factors based on complexity:
+        - SousChef handles 60-70% of boilerplate conversion automatically
+        - Human still needed for validation, custom logic, testing
+        - Overall reduction: 40-50% of manual effort
+        """
+        return round(self.estimated_days * 0.5, 1)
+
+    @property
+    def time_saved(self) -> float:
+        """Time saved by using SousChef (in days)."""
+        return round(self.estimated_days - self.estimated_days_with_souschef, 1)
+
+    @property
+    def efficiency_gain_percent(self) -> int:
+        """Efficiency gain percentage from using SousChef."""
+        if self.estimated_days == 0:
+            return 0
+        return round((self.time_saved / self.estimated_days) * 100)
 
     @property
     def estimated_hours(self) -> float:
-        """Convert days to hours using standard 8-hour workday."""
+        """Convert days to hours using standard 8-hour workday (WITHOUT SousChef)."""
         return self.estimated_days * 8
 
+    @property
+    def estimated_hours_with_souschef(self) -> float:
+        """Convert days to hours using standard 8-hour workday (WITH SousChef)."""
+        return self.estimated_days_with_souschef * 8
+
     @property
     def estimated_weeks_low(self) -> int:
-        """Conservative estimate: assumes optimal parallelization."""
+        """Conservative estimate: assumes optimal parallelization (WITHOUT SousChef)."""
         return max(1, int(self.estimated_days / 7))
 
     @property
     def estimated_weeks_high(self) -> int:
-        """Realistic estimate: assumes sequential/limited parallelization."""
+        """Realistic estimate: sequential parallelization (WITHOUT SousChef)."""
         return max(1, int(self.estimated_days / 3.5))
 
+    @property
+    def estimated_weeks_low_with_souschef(self) -> int:
+        """Conservative estimate: assumes optimal parallelization (WITH SousChef)."""
+        return max(1, int(self.estimated_days_with_souschef / 7))
+
+    @property
+    def estimated_weeks_high_with_souschef(self) -> int:
+        """Realistic estimate: sequential parallelization (WITH SousChef)."""
+        return max(1, int(self.estimated_days_with_souschef / 3.5))
+
     @property
     def estimated_weeks_range(self) -> str:
-        """Human-readable week range (e.g., '2-4 weeks')."""
+        """Human-readable week range WITHOUT SousChef (e.g., '2-4 weeks')."""
         low = self.estimated_weeks_low
         high = self.estimated_weeks_high
         if low == high:
             return f"{low} week{'s' if low != 1 else ''}"
         return f"{low}-{high} weeks"
 
+    @property
+    def estimated_weeks_range_with_souschef(self) -> str:
+        """Human-readable week range WITH SousChef (e.g., '1-2 weeks')."""
+        low = self.estimated_weeks_low_with_souschef
+        high = self.estimated_weeks_high_with_souschef
+        if low == high:
+            return f"{low} week{'s' if low != 1 else ''}"
+        return f"{low}-{high} weeks"
+
     @property
     def estimated_days_formatted(self) -> str:
-        """Formatted days with appropriate precision."""
+        """Formatted days with appropriate precision (WITHOUT SousChef)."""
         if self.estimated_days == int(self.estimated_days):
             return f"{int(self.estimated_days)} days"
         return f"{self.estimated_days:.1f} days"
 
+    @property
+    def estimated_days_formatted_with_souschef(self) -> str:
+        """Formatted days with appropriate precision (WITH SousChef)."""
+        if self.estimated_days_with_souschef == int(self.estimated_days_with_souschef):
+            return f"{int(self.estimated_days_with_souschef)} days"
+        return f"{self.estimated_days_with_souschef:.1f} days"
+
     def __str__(self) -> str:
         """Return a string representation of effort metrics."""
         return f"{self.estimated_days_formatted} ({self.estimated_weeks_range})"
 
+    def get_comparison_summary(self) -> str:
+        """Format comparison of manual vs SousChef-assisted effort."""
+        return (
+            f"Without SousChef: {self.estimated_days_formatted} "
+            f"({self.estimated_weeks_range})\n"
+            f"With SousChef:    {self.estimated_days_formatted_with_souschef} "
+            f"({self.estimated_weeks_range_with_souschef})\n"
+            f"Time Saved:       {self.time_saved} days "
+            f"({self.efficiency_gain_percent}% faster)"
+        )
+
 
 class TeamRecommendation(NamedTuple):
     """Team composition and timeline recommendation."""

souschef/core/url_validation.py

@@ -0,0 +1,230 @@
+"""URL validation utilities for user-provided endpoints."""
+
+import ipaddress
+import os
+from collections.abc import Iterable
+from urllib.parse import urlparse, urlunparse
+
+DEFAULT_ALLOWLIST_ENV = "SOUSCHEF_ALLOWED_HOSTNAMES"
+
+
+def _split_allowlist(env_value: str) -> set[str]:
+    """
+    Split an allowlist environment variable into hostnames.
+
+    Args:
+        env_value: Raw environment value containing hostnames.
+
+    Returns:
+        A set of normalised hostnames.
+
+    """
+    return {entry.strip().lower() for entry in env_value.split(",") if entry.strip()}
+
+
+def _matches_allowlist(hostname: str, allowlist: Iterable[str]) -> bool:
+    """
+    Check whether a hostname matches the allowlist.
+
+    Args:
+        hostname: Hostname to validate.
+        allowlist: Iterable of allowlist entries.
+
+    Returns:
+        True if the hostname matches the allowlist.
+
+    """
+    for entry in allowlist:
+        entry = entry.lower().strip()
+        if not entry:
+            continue
+        if entry.startswith("*."):
+            suffix = entry[1:]
+            if hostname.endswith(suffix) and hostname != suffix.lstrip("."):
+                return True
+        elif hostname == entry:
+            return True
+    return False
+
+
+def _is_private_hostname(hostname: str) -> bool:
+    """
+    Determine whether a hostname resolves to a private or local address.
+
+    This check only validates IP literals and well-known local hostnames.
+
+    Args:
+        hostname: Hostname to inspect.
+
+    Returns:
+        True if the hostname is private or local.
+
+    """
+    local_suffixes = (".localhost", ".local", ".localdomain", ".internal")
+    if hostname in {"localhost"} or hostname.endswith(local_suffixes):
+        return True
+
+    try:
+        ip_address = ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+
+    return bool(
+        ip_address.is_private
+        or ip_address.is_loopback
+        or ip_address.is_link_local
+        or ip_address.is_reserved
+        or ip_address.is_multicast
+        or ip_address.is_unspecified
+    )
+
+
+def _is_ip_literal(hostname: str) -> bool:
+    """
+    Check whether the hostname is an IP literal.
+
+    Args:
+        hostname: Hostname to inspect.
+
+    Returns:
+        True if the hostname is an IP literal.
+
+    """
+    try:
+        ipaddress.ip_address(hostname)
+    except ValueError:
+        return False
+    return True
+
+
+def _normalise_url_value(base_url: str, default_url: str | None) -> str:
+    """
+    Normalise the input URL value.
+
+    Args:
+        base_url: URL provided by the user.
+        default_url: Default URL to use when base_url is empty.
+
+    Returns:
+        Normalised URL string.
+
+    """
+    url_value = str(base_url).strip()
+    if not url_value:
+        if default_url is None:
+            raise ValueError("Base URL is required.")
+        url_value = default_url
+
+    if "://" not in url_value:
+        url_value = f"https://{url_value}"
+
+    return url_value
+
+
+def _validate_scheme(parsed_url) -> None:
+    """
+    Validate URL scheme.
+
+    Args:
+        parsed_url: Parsed URL object.
+
+    """
+    if parsed_url.scheme.lower() != "https":
+        raise ValueError("Base URL must use HTTPS.")
+
+
+def _validate_hostname(
+    hostname: str,
+    allowlist: set[str],
+    allowed_hosts: set[str] | None,
+) -> None:
+    """
+    Validate hostname using allowlist and public host rules.
+
+    Args:
+        hostname: Hostname to validate.
+        allowlist: Allowlisted hostnames.
+        allowed_hosts: Provider-specific allowed hostnames.
+
+    """
+    hostname = hostname.lower()
+    is_ip_literal = _is_ip_literal(hostname)
+
+    if allowed_hosts and hostname not in allowed_hosts:
+        raise ValueError("Base URL host is not permitted.")
+
+    allowlist_match = _matches_allowlist(hostname, allowlist) if allowlist else False
+    if allowlist and not allowlist_match:
+        raise ValueError("Base URL host is not in the allowlist.")
+
+    if not allowlist_match and _is_private_hostname(hostname):
+        raise ValueError("Base URL host must be a public hostname.")
+
+    if not allowlist_match and "." not in hostname and not is_ip_literal:
+        raise ValueError("Base URL host must be a fully qualified domain name.")
+
+
+def _normalise_parsed_url(parsed_url, strip_path: bool) -> str:
+    """
+    Normalise a parsed URL into a string.
+
+    Args:
+        parsed_url: Parsed URL object.
+        strip_path: Whether to strip paths, queries, and fragments.
+
+    Returns:
+        Normalised URL string.
+
+    """
+    cleaned = parsed_url._replace(params="", query="", fragment="")
+    if strip_path:
+        cleaned = cleaned._replace(path="")
+
+    return str(urlunparse(cleaned)).rstrip("/")
+
+
+def validate_user_provided_url(
+    base_url: str,
+    *,
+    default_url: str | None = None,
+    allowlist_env_var: str = DEFAULT_ALLOWLIST_ENV,
+    allowed_hosts: set[str] | None = None,
+    strip_path: bool = False,
+) -> str:
+    """
+    Validate a user-provided URL for outbound requests.
+
+    Args:
+        base_url: URL provided by the user.
+        default_url: Default URL to use when base_url is empty.
+        allowlist_env_var: Environment variable containing allowed hostnames.
+        allowed_hosts: Explicit host allowlist for provider-specific endpoints.
+        strip_path: Whether to strip paths, queries, and fragments.
+
+    Returns:
+        Validated and normalised URL string.
+
+    Raises:
+        ValueError: If the URL is invalid or fails security validation.
+
+    """
+    url_value = _normalise_url_value(base_url, default_url)
+    parsed = urlparse(url_value)
+
+    _validate_scheme(parsed)
+
+    if not parsed.hostname:
+        raise ValueError("Base URL must include a hostname.")
+
+    if parsed.username or parsed.password:
+        raise ValueError("Base URL must not include user credentials.")
+
+    allowlist_value = os.environ.get(allowlist_env_var, "")
+    allowlist = _split_allowlist(allowlist_value)
+    normalised_allowed_hosts = (
+        {host.lower() for host in allowed_hosts} if allowed_hosts else None
+    )
+
+    _validate_hostname(parsed.hostname, allowlist, normalised_allowed_hosts)
+
+    return _normalise_parsed_url(parsed, strip_path)