mcp-coder-utils 0.1.2__tar.gz → 0.1.3__tar.gz

{mcp_coder_utils-0.1.2 → mcp_coder_utils-0.1.3}/.claude/settings.local.json

@@ -4,15 +4,6 @@
       "mcp__tools-py__run_pylint_check",
       "mcp__tools-py__run_pytest_check",
       "mcp__tools-py__run_mypy_check",
-      "mcp__tools-py__run_lint_imports_check",
-      "mcp__tools-py__run_vulture_check",
-      "mcp__tools-py__run_format_code",
-      "mcp__tools-py__list_symbols",
-      "mcp__tools-py__find_references",
-      "mcp__tools-py__move_symbol",
-      "mcp__tools-py__rename_symbol",
-      "mcp__tools-py__move_module",
-      "mcp__tools-py__get_library_source",
       "mcp__workspace__get_reference_projects",
       "mcp__workspace__list_reference_directory",
       "mcp__workspace__read_reference_file",
@@ -23,20 +14,15 @@
       "mcp__workspace__delete_this_file",
       "mcp__workspace__move_file",
       "mcp__workspace__edit_file",
-      "Bash(git status:*)",
       "Bash(git diff:*)",
-      "Bash(git log:*)",
-      "Bash(git fetch:*)",
-      "Bash(git ls-tree:*)",
       "Bash(gh run view:*)",
       "Bash(gh issue view:*)",
-      "Bash(mcp-coder check file-size:*)",
-      "Bash(mcp-coder check branch-status:*)",
-      "Bash(mcp-coder gh-tool:*)",
-      "Bash(mcp-coder git-tool:*)",
-      "Bash(find:*)",
-      "Bash(ruff rule:*)",
-      "Bash(ruff check:*)",
+      "Bash(./tools/tach_check.sh:*)",
+      "Bash(tach check:*)",
+      "Bash(start docs/architecture/dependency_graph.html)",
+      "Bash(./tools/pycycle_check.sh:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(./tools/ruff_check.sh:*)",
       "Skill(commit_push)",
       "Skill(discuss)",
       "Skill(implementation_approve)",
@@ -54,9 +40,30 @@
       "Skill(plan_review_supervisor)",
       "Skill(plan_update)",
       "Skill(rebase)",
+      "Bash(find:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git fetch:*)",
+      "Bash(mcp-coder check file-size:*)",
+      "Bash(mcp-coder check branch-status:*)",
       "Skill(check_branch_status)",
       "Skill(implement_direct)",
+      "Skill(issue_requirements)",
       "WebFetch(domain:*)",
+      "Bash(mcp-coder gh-tool:*)",
+      "Bash(git ls-tree:*)",
+      "Bash(mcp-coder git-tool:*)",
+      "Bash(ruff rule:*)",
+      "Bash(ruff check:*)",
+      "mcp__tools-py__list_symbols",
+      "mcp__tools-py__find_references",
+      "mcp__tools-py__move_symbol",
+      "mcp__tools-py__rename_symbol",
+      "mcp__tools-py__move_module",
+      "mcp__tools-py__run_format_code",
+      "mcp__tools-py__run_lint_imports_check",
+      "mcp__tools-py__run_vulture_check",
+      "mcp__tools-py__get_library_source",
       "mcp__workspace__search_files"
     ]
   },

{mcp_coder_utils-0.1.2 → mcp_coder_utils-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-coder-utils
-Version: 0.1.2
+Version: 0.1.3
 Summary: Shared low-level Python helpers (subprocess, logging, fs) for the mcp-coder family of repos
 Author-email: Marcus Jellinghaus <Marcus@Jellinghaus.ch>
 Project-URL: Homepage, https://github.com/MarcusJellinghaus/mcp-coder-utils

{mcp_coder_utils-0.1.2 → mcp_coder_utils-0.1.3}/docs/architecture/architecture.md

@@ -41,6 +41,7 @@ consumed by `mcp-coder`, `mcp-tools-py`, `mcp-workspace`, and `mcp-config`.
 src/mcp_coder_utils/
     __init__.py
     py.typed
+    log_utils.py
     subprocess_runner.py
     subprocess_streaming.py
 ```

mcp_coder_utils-0.1.3/src/mcp_coder_utils/log_utils.py

@@ -0,0 +1,476 @@
+"""Shared logging configuration and utilities."""
+
+import json
+import logging
+import os
+import time
+from functools import wraps
+from pathlib import Path
+from typing import Any, Callable, Optional, TypeVar, cast, overload
+
+import structlog
+from pythonjsonlogger.json import JsonFormatter
+
+from mcp_coder_utils.redaction import RedactableDict, redact_for_logging
+
+__all__ = ["OUTPUT", "log_function_call", "setup_logging"]
+
+# Custom OUTPUT log level (between INFO=20 and WARNING=30)
+# OUTPUT is the default CLI threshold. At this threshold, CleanFormatter
+# produces bare messages; at INFO/DEBUG, ExtraFieldsFormatter produces
+# verbose timestamped output. Use logger.log(OUTPUT, ...) for user-facing
+# CLI messages that should be clean at default verbosity.
+OUTPUT = 25
+logging.addLevelName(OUTPUT, "OUTPUT")
+
+# Type variable for function return types
+T = TypeVar("T")
+
+# Standard LogRecord fields to exclude when extracting extra fields
+# These are built-in attributes of logging.LogRecord that should not be treated as "extra" data
+STANDARD_LOG_FIELDS: frozenset[str] = frozenset(
+    {
+        "name",
+        "msg",
+        "args",
+        "asctime",  # Added by Formatter.format()
+        "created",
+        "filename",
+        "funcName",
+        "levelname",
+        "levelno",
+        "lineno",
+        "module",
+        "msecs",
+        "pathname",
+        "process",
+        "processName",
+        "relativeCreated",
+        "stack_info",
+        "exc_info",
+        "exc_text",
+        "thread",
+        "threadName",
+        "taskName",
+        "message",
+    }
+)
+
+
+class CleanFormatter(logging.Formatter):
+    """Formatter for clean CLI output.
+
+    Used when log threshold is OUTPUT. Produces:
+    - OUTPUT-level records: bare message (no prefix)
+    - WARNING/ERROR/CRITICAL: "LEVEL: message"
+
+    Extra fields (passed via extra={}) are appended as JSON,
+    independently of ExtraFieldsFormatter.
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format the log record for clean CLI output.
+
+        Args:
+            record: The log record to format.
+
+        Returns:
+            The formatted log message.
+        """
+        message = record.getMessage()
+
+        if record.levelno > OUTPUT:
+            message = f"{record.levelname}: {message}"
+
+        # Extract extra fields (attributes not in standard LogRecord fields)
+        extra_fields = {
+            key: value
+            for key, value in record.__dict__.items()
+            if key not in STANDARD_LOG_FIELDS
+        }
+
+        if extra_fields:
+            suffix = json.dumps(extra_fields, default=str)
+            return f"{message} {suffix}"
+
+        return message
+
+
+class ExtraFieldsFormatter(logging.Formatter):
+    """Formatter that appends extra fields to log messages.
+
+    This formatter extends the standard logging.Formatter to include any
+    extra fields passed via the `extra` parameter in logging calls.
+    Extra fields are appended to the log message as a JSON object.
+
+    Example:
+        >>> formatter = ExtraFieldsFormatter(
+        ...     "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        ... )
+        >>> handler.setFormatter(formatter)
+        >>> logger.info("User logged in", extra={"user_id": 123, "ip": "192.168.1.1"})
+        # Output: 2024-01-15 10:30:00 - myapp - INFO - User logged in {"user_id": 123, "ip": "192.168.1.1"}
+    """
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format the log record, appending any extra fields as JSON.
+
+        Args:
+            record: The log record to format.
+
+        Returns:
+            The formatted log message with extra fields appended as JSON.
+        """
+        # Get the base formatted message
+        base_message = super().format(record)
+
+        # Extract extra fields (attributes not in standard LogRecord fields)
+        extra_fields = {
+            key: value
+            for key, value in record.__dict__.items()
+            if key not in STANDARD_LOG_FIELDS
+        }
+
+        # If there are extra fields, append them as JSON
+        if extra_fields:
+            # Use default=str to handle non-serializable values
+            suffix = json.dumps(extra_fields, default=str)
+            return f"{base_message} {suffix}"
+
+        return base_message
+
+
+# Create standard logger
+stdlogger = logging.getLogger(__name__)
+
+
+def _is_testing_environment() -> bool:
+    """Check if we're currently running in a testing environment (pytest).
+
+    Returns:
+        True if pytest is detected in the current process.
+    """
+    import sys
+
+    # Check if pytest is running
+    return (
+        "pytest" in sys.modules
+        or "_pytest" in sys.modules
+        or hasattr(sys, "_called_from_test")
+        or "PYTEST_CURRENT_TEST" in os.environ
+    )
+
+
+def setup_logging(log_level: str, log_file: Optional[str] = None) -> None:
+    """Configure logging - if log_file specified, logs only to file; otherwise to console.
+
+    Configures structlog globally. Call once at startup;
+    repeated calls override the structlog configuration.
+
+    Raises:
+        ValueError: If log_level is not a valid logging level.
+    """
+    # Set log level
+    numeric_level = getattr(logging, log_level.upper(), None)
+    if not isinstance(numeric_level, int):
+        numeric_level = logging.getLevelName(log_level.upper())
+        if not isinstance(numeric_level, int):
+            raise ValueError(f"Invalid log level: {log_level}")
+
+    # Don't clear handlers if we're in a testing environment (pytest)
+    # This prevents conflicts with pytest's logging capture
+    if not _is_testing_environment():
+        # Clear existing handlers
+        root_logger = logging.getLogger()
+        for handler in root_logger.handlers[:]:
+            root_logger.removeHandler(handler)
+    else:
+        root_logger = logging.getLogger()
+
+    root_logger.setLevel(numeric_level)
+
+    # Set up logging based on whether log_file is specified
+    if log_file:
+        # FILE LOGGING ONLY - no console output
+        # Create directory if needed
+        os.makedirs(os.path.dirname(os.path.abspath(log_file)), exist_ok=True)
+
+        # In testing environment, only add handler if it doesn't already exist
+        if _is_testing_environment():
+            # Check if file handler for this file already exists
+            file_handler_exists = any(
+                isinstance(h, logging.FileHandler)
+                and h.baseFilename == os.path.abspath(log_file)
+                for h in root_logger.handlers
+            )
+            if file_handler_exists:
+                return  # Handler already exists, don't add another
+
+        # Configure JSON file handler
+        json_handler = logging.FileHandler(log_file)
+        json_handler.setLevel(numeric_level)
+
+        # This formatter ensures timestamp and level are included as separate fields in JSON
+        json_formatter = JsonFormatter(
+            fmt="%(asctime)s %(levelname)s %(name)s %(message)s %(module)s %(funcName)s %(lineno)d"
+        )
+        json_handler.setFormatter(json_formatter)
+        root_logger.addHandler(json_handler)
+
+        # Configure structlog processors for file logging
+        # Only configure if not in testing environment to avoid conflicts
+        if not _is_testing_environment():
+            structlog.configure(
+                processors=[
+                    structlog.stdlib.filter_by_level,
+                    structlog.stdlib.add_logger_name,
+                    structlog.stdlib.add_log_level,
+                    structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
+                    structlog.processors.StackInfoRenderer(),
+                    structlog.processors.format_exc_info,
+                    structlog.processors.UnicodeDecoder(),
+                    structlog.processors.JSONRenderer(),
+                ],
+                context_class=dict,
+                logger_factory=structlog.stdlib.LoggerFactory(),
+                wrapper_class=structlog.stdlib.BoundLogger,
+                cache_logger_on_first_use=True,
+            )
+
+        # Log initialization message to file only
+        stdlogger.info("Logging initialized: file=%s, level=%s", log_file, log_level)
+    else:
+        # CONSOLE LOGGING ONLY (fallback when no file specified)
+        # In testing environment, only add handler if no console handler exists
+        if _is_testing_environment():
+            console_handler_exists = any(
+                isinstance(h, logging.StreamHandler)
+                and not isinstance(h, logging.FileHandler)
+                for h in root_logger.handlers
+            )
+            if console_handler_exists:
+                return  # Console handler already exists, don't add another
+
+        console_handler = logging.StreamHandler()
+        console_handler.setLevel(numeric_level)
+        if numeric_level >= OUTPUT:
+            console_formatter: logging.Formatter = CleanFormatter()
+        else:
+            console_formatter = ExtraFieldsFormatter(
+                "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+            )
+        console_handler.setFormatter(console_formatter)
+        root_logger.addHandler(console_handler)
+
+        # Configure structlog processors for console logging
+        # Only configure if not in testing environment to avoid conflicts
+        if not _is_testing_environment():
+            structlog.configure(
+                processors=[
+                    structlog.stdlib.filter_by_level,  # This will respect the logging level
+                    structlog.stdlib.add_logger_name,
+                    structlog.stdlib.add_log_level,
+                    structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S"),
+                    structlog.processors.StackInfoRenderer(),
+                    structlog.processors.format_exc_info,
+                    structlog.processors.UnicodeDecoder(),
+                    structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+                ],
+                context_class=dict,
+                logger_factory=structlog.stdlib.LoggerFactory(),
+                wrapper_class=structlog.stdlib.BoundLogger,
+                cache_logger_on_first_use=True,
+            )
+
+        stdlogger.debug("Logging initialized: console=%s", log_level)
+
+
+# Overload signatures for proper typing
+@overload
+def log_function_call(func: Callable[..., T]) -> Callable[..., T]: ...
+
+
+@overload
+def log_function_call(
+    func: None = None,
+    *,
+    sensitive_fields: list[str] | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]: ...
+
+
+def log_function_call(
+    func: Callable[..., T] | None = None,
+    *,
+    sensitive_fields: list[str] | None = None,
+) -> Callable[..., T] | Callable[[Callable[..., T]], Callable[..., T]]:
+    """Decorator to log function calls with parameters, timing, and results.
+
+    Can be used as @log_function_call or @log_function_call(sensitive_fields=[...]).
+
+    Args:
+        func: The function to decorate (when used without parentheses).
+        sensitive_fields: Optional list of field names whose values should be
+            redacted in logs. Applies to both parameters and return values.
+
+    Returns:
+        Decorated function or decorator depending on usage.
+    """
+    sensitive_set = set(sensitive_fields) if sensitive_fields else set()
+
+    def decorator(fn: Callable[..., T]) -> Callable[..., T]:
+        @wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            func_name = fn.__name__
+            module_name = fn.__module__
+            line_no = fn.__code__.co_firstlineno
+
+            # Get logger for the decorated function's module (not log_utils)
+            func_logger = logging.getLogger(module_name)
+
+            # Prepare parameters for logging
+            log_params: dict[str, Any] = {}
+
+            # Handle method calls (skip self/cls)
+            if args and fn.__code__.co_varnames[0] in ("self", "cls"):
+                log_params.update(
+                    dict(zip(fn.__code__.co_varnames[1 : len(args)], args[1:]))
+                )
+            else:
+                log_params.update(dict(zip(fn.__code__.co_varnames[: len(args)], args)))
+
+            # Add keyword arguments
+            log_params.update(kwargs)
+
+            # Convert Path objects to strings and handle other non-serializable types
+            serializable_params: dict[str, Any] = {}
+            for k, v in log_params.items():
+                if isinstance(v, Path):
+                    serializable_params[k] = str(v)
+                else:
+                    try:
+                        # Test if it's JSON serializable
+                        json.dumps(v)
+                        serializable_params[k] = v
+                    except (TypeError, OverflowError):
+                        # If not serializable, convert to string
+                        serializable_params[k] = str(v)
+
+            # Apply redaction for sensitive fields
+            # Cast needed because serializable_params is dict[str, Any] but
+            # redact_for_logging accepts RedactableDict
+            params_for_log = (
+                redact_for_logging(
+                    cast(RedactableDict, serializable_params),
+                    sensitive_set,
+                )
+                if sensitive_set
+                else serializable_params
+            )
+
+            # Check if structured logging is enabled
+            has_structured = any(
+                isinstance(h, logging.FileHandler) for h in logging.getLogger().handlers
+            )
+
+            # Log function call
+            if has_structured:
+                structlogger = structlog.get_logger(module_name)
+                structlogger.debug(
+                    "Calling function",
+                    function=func_name,
+                    parameters=params_for_log,
+                    module=module_name,
+                    lineno=line_no,
+                )
+
+            func_logger.debug(
+                "%s(%s)", func_name, json.dumps(params_for_log, default=str)
+            )
+
+            # Execute function and measure time
+            start_time = time.time()
+            try:
+                result = fn(*args, **kwargs)
+                elapsed_ms = round((time.time() - start_time) * 1000, 2)
+
+                # Prepare result for logging
+                result_for_log: Any
+                serializable_result: Any
+                if isinstance(result, (list, dict)) and len(str(result)) > 1000:
+                    result_for_log = (
+                        f"<Large result of type {type(result).__name__}, "
+                        f"length: {len(str(result))}>"
+                    )
+                    serializable_result = result_for_log
+                else:
+                    result_for_log = result
+                    # Make result JSON serializable for structured logging
+                    try:
+                        json.dumps(result)  # Test if result is JSON serializable
+                        serializable_result = result
+                    except (TypeError, OverflowError):
+                        serializable_result = (
+                            str(result) if result is not None else None
+                        )
+
+                # Apply redaction to result if it's a dict
+                if sensitive_set and isinstance(serializable_result, dict):
+                    serializable_result = redact_for_logging(
+                        serializable_result, sensitive_set
+                    )
+                if sensitive_set and isinstance(result_for_log, dict):
+                    result_for_log = redact_for_logging(result_for_log, sensitive_set)
+
+                # Log completion
+                if has_structured:
+                    structlogger.debug(
+                        "Function completed",
+                        function=func_name,
+                        execution_time_ms=elapsed_ms,
+                        status="success",
+                        result=serializable_result,
+                        module=module_name,
+                        lineno=line_no,
+                    )
+
+                func_logger.debug(
+                    "%s -> %s (%sms)", func_name, result_for_log, elapsed_ms
+                )
+                return result
+
+            except (
+                Exception
+            ) as e:  # pylint: disable=broad-exception-caught  # TODO: narrow exception type
+                # Log exceptions
+                elapsed_ms = round((time.time() - start_time) * 1000, 2)
+
+                if has_structured:
+                    structlogger.error(
+                        "Function failed",
+                        function=func_name,
+                        execution_time_ms=elapsed_ms,
+                        error_type=type(e).__name__,
+                        error_message=str(e),
+                        module=module_name,
+                        lineno=line_no,
+                        exc_info=True,
+                    )
+
+                func_logger.error(
+                    "%s FAILED: %s: %s (%sms)",
+                    func_name,
+                    type(e).__name__,
+                    str(e),
+                    elapsed_ms,
+                    exc_info=True,
+                )
+                raise
+
+        return cast(Callable[..., T], wrapper)
+
+    # Handle both @log_function_call and @log_function_call(sensitive_fields=[...])
+    if func is not None:
+        # Called without parentheses: @log_function_call
+        return decorator(func)
+    # Called with parentheses: @log_function_call(sensitive_fields=[...])
+    return decorator

mcp_coder_utils-0.1.3/src/mcp_coder_utils/redaction.py

@@ -0,0 +1,94 @@
+"""Redaction utilities for sanitising sensitive data before logging."""
+
+from collections.abc import Mapping
+from typing import Any
+
+__all__ = [
+    "redact_for_logging",
+    "redact_env_vars",
+    "SENSITIVE_KEY_PATTERNS",
+    "REDACTED_VALUE",
+    "RedactableDict",
+]
+
+# Type alias for dictionaries that can have string or tuple keys
+# Used by redact_for_logging to handle get_config_values() return format
+RedactableDict = dict[str | tuple[str, ...], Any]
+
+# Redaction placeholder for sensitive values
+REDACTED_VALUE = "***"
+
+# Substring patterns for identifying sensitive env var keys (case-insensitive)
+SENSITIVE_KEY_PATTERNS: frozenset[str] = frozenset(
+    {
+        "token",
+        "secret",
+        "password",
+        "credential",
+        "api_key",
+        "access_key",
+    }
+)
+
+
+def redact_for_logging(
+    data: RedactableDict,
+    sensitive_fields: set[str],
+) -> RedactableDict:
+    """Create a copy of data with sensitive fields redacted for logging.
+
+    Args:
+        data: Dictionary containing data to be logged.
+        sensitive_fields: Set of field names whose values should be redacted.
+            For tuple keys, the last element of the tuple is checked against
+            sensitive_fields (e.g., ("github", "token") matches "token").
+
+    Returns:
+        A shallow copy of data with sensitive field values replaced by "***".
+        Nested dictionaries are processed recursively.
+    """
+    result = data.copy()
+    for key in result:
+        # Check if key matches sensitive fields
+        # For tuple keys, check the last element
+        key_to_check: str | None = None
+        if isinstance(key, str):
+            key_to_check = key
+        elif isinstance(key, tuple) and len(key) > 0:
+            last_element = key[-1]
+            if isinstance(last_element, str):
+                key_to_check = last_element
+
+        if key_to_check is not None and key_to_check in sensitive_fields:
+            result[key] = REDACTED_VALUE
+        elif isinstance(result[key], dict):
+            result[key] = redact_for_logging(result[key], sensitive_fields)
+    return result
+
+
+def redact_env_vars(
+    env: Mapping[str, str],
+    extra_patterns: frozenset[str] | None = None,
+) -> dict[str, str]:
+    """Redact env var values whose keys contain sensitive substrings (case-insensitive).
+
+    Args:
+        env: Mapping of environment variable names to values.
+        extra_patterns: Additional substring patterns to merge with defaults.
+
+    Returns:
+        A new dict with sensitive values replaced by the redaction placeholder.
+    """
+    patterns = (
+        SENSITIVE_KEY_PATTERNS | extra_patterns
+        if extra_patterns
+        else SENSITIVE_KEY_PATTERNS
+    )
+    result: dict[str, str] = {}
+    for key, value in env.items():
+        key_lower = key.lower()
+        if any(pattern in key_lower for pattern in patterns):
+            result[key] = REDACTED_VALUE
+        else:
+            result[key] = value
+    return result

{mcp_coder_utils-0.1.2 → mcp_coder_utils-0.1.3}/src/mcp_coder_utils.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-coder-utils
-Version: 0.1.2
+Version: 0.1.3
 Summary: Shared low-level Python helpers (subprocess, logging, fs) for the mcp-coder family of repos
 Author-email: Marcus Jellinghaus <Marcus@Jellinghaus.ch>
 Project-URL: Homepage, https://github.com/MarcusJellinghaus/mcp-coder-utils

{mcp_coder_utils-0.1.2 → mcp_coder_utils-0.1.3}/src/mcp_coder_utils.egg-info/SOURCES.txt

@@ -46,7 +46,9 @@ vulture_whitelist.py
 .github/workflows/publish.yml
 docs/architecture/architecture.md
 src/mcp_coder_utils/__init__.py
+src/mcp_coder_utils/log_utils.py
 src/mcp_coder_utils/py.typed
+src/mcp_coder_utils/redaction.py
 src/mcp_coder_utils/subprocess_runner.py
 src/mcp_coder_utils/subprocess_streaming.py
 src/mcp_coder_utils.egg-info/PKG-INFO
@@ -55,6 +57,8 @@ src/mcp_coder_utils.egg-info/dependency_links.txt
 src/mcp_coder_utils.egg-info/requires.txt
 src/mcp_coder_utils.egg-info/top_level.txt
 tests/__init__.py
+tests/test_log_utils.py
+tests/test_redaction.py
 tests/test_subprocess_runner.py
 tests/test_subprocess_runner_real.py
 tests/test_subprocess_streaming.py