claude-mpm 4.1.26__py3-none-any.whl → 4.24.0__py3-none-any.whl

claude_mpm/utils/database_connector.py

@@ -0,0 +1,298 @@
+"""
+Database Connector with Fallback Support
+=========================================
+
+WHY: Database connectivity packages often have compilation requirements that
+can fail on certain systems. This module provides intelligent fallback to
+pure Python alternatives when native packages are unavailable.
+
+DESIGN DECISION: We prioritize pure Python implementations over native ones
+for better cross-platform compatibility, even if they might be slightly slower.
+"""
+
+from typing import Any, ClassVar, Dict, Optional, Tuple
+
+from ..core.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class DatabaseConnector:
+    """
+    Manages database connections with automatic fallback to alternative drivers.
+
+    WHY: Provides a unified interface for database connections that automatically
+    handles missing or failed driver installations by falling back to alternatives.
+    """
+
+    # Database drivers in order of preference (first is preferred)
+    MYSQL_DRIVERS: ClassVar[list] = [
+        ("pymysql", "pymysql"),  # Pure Python, no compilation required
+        ("mysqlclient", "MySQLdb"),  # Faster but requires MySQL dev headers
+        ("mysql-connector-python", "mysql.connector"),  # Oracle's pure Python driver
+    ]
+
+    POSTGRESQL_DRIVERS: ClassVar[list] = [
+        ("psycopg2-binary", "psycopg2"),  # Binary wheel, no compilation
+        ("psycopg2", "psycopg2"),  # Requires PostgreSQL dev headers
+        ("pg8000", "pg8000"),  # Pure Python alternative
+    ]
+
+    ORACLE_DRIVERS: ClassVar[list] = [
+        ("cx_Oracle", "cx_Oracle"),  # Requires Oracle client libraries
+        ("oracledb", "oracledb"),  # Pure Python Oracle driver (newer)
+    ]
+
+    def __init__(self):
+        """Initialize the database connector."""
+        self.available_drivers: Dict[str, Tuple[str, Any]] = {}
+        self._scan_available_drivers()
+
+    def _scan_available_drivers(self) -> None:
+        """
+        Scan for available database drivers and cache them.
+
+        WHY: Pre-scanning allows us to know what's available without
+        repeatedly trying imports, improving performance.
+        """
+        # Check MySQL drivers
+        for package_name, import_name in self.MYSQL_DRIVERS:
+            driver = self._try_import(import_name)
+            if driver and "mysql" not in self.available_drivers:
+                self.available_drivers["mysql"] = (package_name, driver)
+                logger.info(f"MySQL driver available: {package_name}")
+
+        # Check PostgreSQL drivers
+        for package_name, import_name in self.POSTGRESQL_DRIVERS:
+            driver = self._try_import(import_name)
+            if driver and "postgresql" not in self.available_drivers:
+                self.available_drivers["postgresql"] = (package_name, driver)
+                logger.info(f"PostgreSQL driver available: {package_name}")
+
+        # Check Oracle drivers
+        for package_name, import_name in self.ORACLE_DRIVERS:
+            driver = self._try_import(import_name)
+            if driver and "oracle" not in self.available_drivers:
+                self.available_drivers["oracle"] = (package_name, driver)
+                logger.info(f"Oracle driver available: {package_name}")
+
+    def _try_import(self, module_name: str) -> Optional[Any]:
+        """
+        Try to import a module and return it if successful.
+
+        Args:
+            module_name: Name of the module to import
+
+        Returns:
+            The imported module or None if import fails
+        """
+        try:
+            import importlib
+
+            return importlib.import_module(module_name)
+        except ImportError:
+            return None
+
+    def get_mysql_connection_string(
+        self, host: str, database: str, user: str, password: str, port: int = 3306
+    ) -> Optional[str]:
+        """
+        Get a SQLAlchemy connection string for MySQL with automatic driver selection.
+
+        WHY: SQLAlchemy needs different connection string formats depending on the driver.
+        This method automatically selects the best available driver.
+
+        Args:
+            host: Database host
+            database: Database name
+            user: Username
+            password: Password
+            port: Port number (default 3306)
+
+        Returns:
+            SQLAlchemy connection string or None if no driver available
+        """
+        if "mysql" not in self.available_drivers:
+            logger.error(
+                "No MySQL driver available. Install one of: pymysql, mysqlclient, or mysql-connector-python"
+            )
+            return None
+
+        package_name, _ = self.available_drivers["mysql"]
+
+        # Format connection string based on driver
+        if package_name == "pymysql":
+            return f"mysql+pymysql://{user}:{password}@{host}:{port}/{database}"
+        if package_name == "mysqlclient":
+            return f"mysql+mysqldb://{user}:{password}@{host}:{port}/{database}"
+        if package_name == "mysql-connector-python":
+            return f"mysql+mysqlconnector://{user}:{password}@{host}:{port}/{database}"
+
+        return None
+
+    def get_postgresql_connection_string(
+        self, host: str, database: str, user: str, password: str, port: int = 5432
+    ) -> Optional[str]:
+        """
+        Get a SQLAlchemy connection string for PostgreSQL with automatic driver selection.
+
+        Args:
+            host: Database host
+            database: Database name
+            user: Username
+            password: Password
+            port: Port number (default 5432)
+
+        Returns:
+            SQLAlchemy connection string or None if no driver available
+        """
+        if "postgresql" not in self.available_drivers:
+            logger.error(
+                "No PostgreSQL driver available. Install one of: psycopg2-binary, psycopg2, or pg8000"
+            )
+            return None
+
+        package_name, _ = self.available_drivers["postgresql"]
+
+        # Format connection string based on driver
+        if package_name in ["psycopg2-binary", "psycopg2"]:
+            return f"postgresql+psycopg2://{user}:{password}@{host}:{port}/{database}"
+        if package_name == "pg8000":
+            return f"postgresql+pg8000://{user}:{password}@{host}:{port}/{database}"
+
+        return None
+
+    def get_oracle_connection_string(
+        self, host: str, database: str, user: str, password: str, port: int = 1521
+    ) -> Optional[str]:
+        """
+        Get a SQLAlchemy connection string for Oracle with automatic driver selection.
+
+        Args:
+            host: Database host
+            database: Database name/SID
+            user: Username
+            password: Password
+            port: Port number (default 1521)
+
+        Returns:
+            SQLAlchemy connection string or None if no driver available
+        """
+        if "oracle" not in self.available_drivers:
+            logger.error(
+                "No Oracle driver available. Install one of: cx_Oracle or oracledb"
+            )
+            return None
+
+        package_name, _ = self.available_drivers["oracle"]
+
+        # Format connection string based on driver
+        if package_name == "cx_Oracle":
+            return f"oracle+cx_oracle://{user}:{password}@{host}:{port}/{database}"
+        if package_name == "oracledb":
+            return f"oracle+oracledb://{user}:{password}@{host}:{port}/{database}"
+
+        return None
+
+    def get_available_drivers(self) -> Dict[str, str]:
+        """
+        Get a summary of available database drivers.
+
+        Returns:
+            Dictionary mapping database type to driver package name
+        """
+        return {
+            db_type: driver_info[0]
+            for db_type, driver_info in self.available_drivers.items()
+        }
+
+    def suggest_missing_drivers(self) -> Dict[str, str]:
+        """
+        Suggest drivers to install for databases without drivers.
+
+        Returns:
+            Dictionary mapping database type to recommended package
+        """
+        suggestions = {}
+
+        if "mysql" not in self.available_drivers:
+            suggestions["mysql"] = "pymysql"  # Pure Python, always works
+
+        if "postgresql" not in self.available_drivers:
+            suggestions["postgresql"] = "psycopg2-binary"  # No compilation needed
+
+        if "oracle" not in self.available_drivers:
+            suggestions["oracle"] = "oracledb"  # Pure Python, newer
+
+        return suggestions
+
+    @staticmethod
+    def get_installation_help() -> str:
+        """
+        Get helpful installation instructions for database drivers.
+
+        Returns:
+            Formatted help text
+        """
+        return """
+Database Driver Installation Help
+=================================
+
+For MySQL:
+  Recommended: pip install pymysql (pure Python, no compilation)
+  Alternative: pip install mysql-connector-python (Oracle's pure Python)
+  Fastest (requires MySQL dev headers):
+    macOS: brew install mysql && pip install mysqlclient
+    Ubuntu: sudo apt-get install libmysqlclient-dev && pip install mysqlclient
+
+For PostgreSQL:
+  Recommended: pip install psycopg2-binary (pre-compiled, no headers needed)
+  Alternative: pip install pg8000 (pure Python, slightly slower)
+  Fastest (requires PostgreSQL dev headers):
+    macOS: brew install postgresql && pip install psycopg2
+    Ubuntu: sudo apt-get install libpq-dev && pip install psycopg2
+
+For Oracle:
+  Recommended: pip install oracledb (pure Python, no Oracle client needed)
+  Alternative (requires Oracle Instant Client):
+    1. Download Oracle Instant Client from oracle.com
+    2. Set environment variables (LD_LIBRARY_PATH, etc.)
+    3. pip install cx_Oracle
+
+Note: Pure Python drivers are slightly slower but much easier to install
+and maintain. They're recommended unless you have specific performance needs.
+"""
+
+
+def test_database_connectivity() -> None:
+    """
+    Test database connectivity and report available drivers.
+
+    WHY: Helps users understand what database drivers are available and
+    what they might need to install.
+    """
+    connector = DatabaseConnector()
+
+    print("Database Driver Status")
+    print("=" * 50)
+
+    available = connector.get_available_drivers()
+    if available:
+        print("\nAvailable Drivers:")
+        for db_type, driver in available.items():
+            print(f"  {db_type:12} -> {driver}")
+    else:
+        print("\nNo database drivers found!")
+
+    suggestions = connector.suggest_missing_drivers()
+    if suggestions:
+        print("\nRecommended installations for missing drivers:")
+        for db_type, package in suggestions.items():
+            print(f"  {db_type:12} -> pip install {package}")
+
+    print("\n" + connector.get_installation_help())
+
+
+if __name__ == "__main__":
+    # Run connectivity test when module is executed directly
+    test_database_connectivity()

claude_mpm/utils/dependency_cache.py

@@ -66,7 +66,7 @@ class DependencyCache:
             return self._cache_data
 
         try:
-            with open(self.cache_file) as f:
+            with self.cache_file.open() as f:
                 self._cache_data = json.load(f)
                 return self._cache_data
         except Exception as e:
@@ -85,7 +85,7 @@ class DependencyCache:
             # Ensure directory exists
             self.cache_dir.mkdir(parents=True, exist_ok=True)
 
-            with open(self.cache_file, "w") as f:
+            with self.cache_file.open("w") as f:
                 json.dump(cache_data, f, indent=2)
 
             self._cache_data = cache_data

claude_mpm/utils/dependency_strategies.py

@@ -10,7 +10,7 @@ based on the execution context and user preferences.
 import json
 import os
 import sys
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from enum import Enum
 from typing import Any, Dict, Optional, Tuple
 
@@ -106,7 +106,7 @@ class DependencyStrategy:
     def _is_docker(self) -> bool:
         """Check if running inside Docker container."""
         return (
-            os.path.exists("/.dockerenv")
+            Path("/.dockerenv").exists()
             or os.environ.get("KUBERNETES_SERVICE_HOST") is not None
         )
 
@@ -128,7 +128,7 @@ class DependencyStrategy:
             # Try to load YAML config
             import yaml
 
-            with open(self.config_path) as f:
+            with self.config_path.open() as f:
                 config = yaml.safe_load(f)
                 mode_str = config.get("dependency_mode")
                 if mode_str:
@@ -155,12 +155,14 @@ class DependencyStrategy:
             return True
 
         try:
-            with open(self.cache_path) as f:
+            with self.cache_path.open() as f:
                 cache = json.load(f)
                 last_check = datetime.fromisoformat(cache.get("timestamp", ""))
 
                 # Check if cache is still valid
-                if datetime.now() - last_check < timedelta(seconds=cache_ttl):
+                if datetime.now(timezone.utc) - last_check < timedelta(
+                    seconds=cache_ttl
+                ):
                     logger.debug(f"Using cached dependency check from {last_check}")
                     return False
 
@@ -179,9 +181,12 @@ class DependencyStrategy:
         try:
             self.cache_path.parent.mkdir(parents=True, exist_ok=True)
 
-            cache_data = {"timestamp": datetime.now().isoformat(), "results": results}
+            cache_data = {
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "results": results,
+            }
 
-            with open(self.cache_path, "w") as f:
+            with self.cache_path.open("w") as f:
                 json.dump(cache_data, f, indent=2)
 
             logger.debug(f"Cached dependency results to {self.cache_path}")
@@ -200,7 +205,7 @@ class DependencyStrategy:
             return None
 
         try:
-            with open(self.cache_path) as f:
+            with self.cache_path.open() as f:
                 cache = json.load(f)
                 return cache.get("results")
         except Exception:
@@ -280,7 +285,7 @@ class DependencyStrategy:
             if self.config_path.exists():
                 import yaml
 
-                with open(self.config_path) as f:
+                with self.config_path.open() as f:
                     config = yaml.safe_load(f) or {}
 
             # Update dependency mode
@@ -289,7 +294,7 @@ class DependencyStrategy:
             # Save config
             import yaml
 
-            with open(self.config_path, "w") as f:
+            with self.config_path.open("w") as f:
                 yaml.dump(config, f, default_flow_style=False)
 
             print(f"✓ Saved preference: {mode.value}")

claude_mpm/utils/display_helper.py

@@ -0,0 +1,260 @@
+"""
+Display Helper for Rich Console Output.
+
+WHY: Centralizes display formatting logic to reduce code duplication
+across CLI commands. Provides reusable components for tables, panels,
+reports, and structured output.
+"""
+
+from typing import Any, Dict, List, Tuple
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+
+class DisplayHelper:
+    """Centralized display formatting for Rich console output."""
+
+    def __init__(self, console: Console):
+        """Initialize display helper with console instance."""
+        self.console = console
+
+    def display_separator(self, char: str = "=", width: int = 60) -> None:
+        """Display a separator line."""
+        self.console.print(char * width)
+
+    def display_header(self, title: str, width: int = 60) -> None:
+        """Display a formatted header with separators."""
+        self.display_separator(width=width)
+        self.console.print(f"[bold]{title}[/bold]")
+        self.display_separator(width=width)
+        self.console.print()
+
+    def display_section_title(self, title: str, emoji: str = "") -> None:
+        """Display a section title with optional emoji."""
+        if emoji:
+            self.console.print(f"[bold cyan]{emoji} {title}[/bold cyan]")
+        else:
+            self.console.print(f"[bold cyan]{title}[/bold cyan]")
+
+    def display_key_value_table(
+        self,
+        title: str,
+        data: Dict[str, Any],
+        key_style: str = "cyan",
+        value_style: str = "white",
+    ) -> None:
+        """Display a two-column key-value table."""
+        table = Table(title=title, show_header=True)
+        table.add_column("Property", style=key_style)
+        table.add_column("Value", style=value_style)
+
+        for key, value in data.items():
+            # Handle various value types
+            if isinstance(value, bool):
+                display_value = "✓" if value else "✗"
+            elif isinstance(value, int) and key.lower().find("size") >= 0:
+                display_value = f"{value:,} characters"
+            else:
+                display_value = str(value)
+            table.add_row(key, display_value)
+
+        self.console.print(table)
+
+    def display_list_section(
+        self, title: str, items: List[str], max_items: int = 10, color: str = "white"
+    ) -> None:
+        """Display a titled list of items."""
+        self.console.print(f"\n[bold cyan]{title}[/bold cyan]")
+        for item in items[:max_items]:
+            self.console.print(f"  [{color}]{item}[/{color}]")
+
+    def display_warning_list(self, title: str, items: List[str]) -> None:
+        """Display a list of warning items."""
+        self.console.print(f"\n[yellow]{title}[/yellow]")
+        for item in items:
+            self.console.print(f"  • {item}")
+
+    def display_info_list(self, title: str, items: List[str]) -> None:
+        """Display a list of info items."""
+        self.console.print(f"\n[blue]{title}[/blue]")
+        for item in items[:5]:
+            self.console.print(f"  • {item}")
+
+    def display_metric_row(
+        self, label: str, value: Any, indent: int = 2, warning: bool = False
+    ) -> None:
+        """Display a single metric row with label and value."""
+        indent_str = " " * indent
+        if warning:
+            self.console.print(f"{indent_str}[yellow]{label}: {value}[/yellow]")
+        else:
+            self.console.print(f"{indent_str}{label}: {value}")
+
+    def display_metrics_section(
+        self, title: str, metrics: Dict[str, Any], emoji: str = ""
+    ) -> None:
+        """Display a section with multiple metrics."""
+        self.display_section_title(title, emoji)
+        for label, value in metrics.items():
+            self.display_metric_row(label, value)
+
+    def display_report_section(
+        self,
+        title: str,
+        data: Dict[str, Any],
+        emoji: str = "",
+        show_warnings: bool = True,
+    ) -> None:
+        """Display a generic report section with data and optional warnings."""
+        self.display_section_title(title, emoji)
+
+        for key, value in data.items():
+            if isinstance(value, dict):
+                # Handle nested dictionaries
+                self.console.print(f"  {key}:")
+                for sub_key, sub_value in value.items():
+                    self.console.print(f"    {sub_key}: {sub_value}")
+            elif isinstance(value, list):
+                # Handle lists
+                self.console.print(f"  {key}:")
+                for item in value[:5]:  # Limit to first 5 items
+                    if isinstance(item, dict):
+                        # Handle dict items in list
+                        desc = item.get("description") or str(item)
+                        prefix = "⚠️  " if show_warnings else "•"
+                        self.console.print(f"    {prefix} {desc}")
+                    else:
+                        self.console.print(f"    • {item}")
+            else:
+                # Simple key-value
+                self.console.print(f"  {key}: {value}")
+
+    def display_recommendations(self, recommendations: List[str]) -> None:
+        """Display a recommendations section."""
+        if recommendations:
+            self.display_section_title("💡 Recommendations")
+            for rec in recommendations[:5]:
+                self.console.print(f"  → {rec}")
+
+    def display_documentation_status(
+        self, analysis: Dict, title: str = "Current CLAUDE.md Status"
+    ) -> None:
+        """Display documentation status table."""
+        data = {
+            "Size": analysis.get("size", 0),
+            "Lines": analysis.get("lines", 0),
+            "Sections": len(analysis.get("sections", [])),
+            "Has Priority Index": analysis.get("has_priority_index", False),
+            "Has Priority Markers": analysis.get("has_priority_markers", False),
+        }
+
+        if analysis.get("last_modified"):
+            data["Last Modified"] = analysis["last_modified"]
+
+        self.display_key_value_table(title, data)
+
+        # Display warnings if present
+        if analysis.get("outdated_patterns"):
+            self.display_warning_list(
+                "⚠️  Outdated patterns detected:", analysis["outdated_patterns"]
+            )
+
+        # Display custom sections if present
+        if analysis.get("custom_sections"):
+            self.display_info_list(
+                "[INFO]️  Custom sections found:", analysis["custom_sections"]
+            )
+
+    def display_activity_summary(
+        self, summary: Dict, period: str = "Last 30 days"
+    ) -> None:
+        """Display activity summary metrics."""
+        metrics = {
+            "Total commits": summary.get("total_commits", 0),
+            "Active contributors": summary.get("total_authors", 0),
+            "Files modified": summary.get("files_changed", 0),
+            "Current branch": summary.get("current_branch", "unknown"),
+        }
+
+        self.display_metrics_section(
+            f"📊 Activity Overview ({period.lower()})", metrics
+        )
+
+        if summary.get("has_uncommitted"):
+            self.display_metric_row(
+                "⚠️  Uncommitted changes",
+                f"{summary.get('uncommitted_count', 0)} files",
+                warning=True,
+            )
+
+    def display_commit_list(
+        self, commits: List[Dict], title: str = "📝 Recent Commits (last 10)"
+    ) -> None:
+        """Display a list of commits."""
+        if commits:
+            self.display_section_title(title)
+            for commit in commits[:10]:
+                msg = commit.get("message", "")[:60]
+                hash_val = commit.get("hash", "")
+                author = commit.get("author", "")
+                self.console.print(f"  [{hash_val}] {msg} - {author}")
+
+    def display_file_change_list(
+        self, files: List[Tuple[str, int]], title: str = "🔥 Most Changed Files"
+    ) -> None:
+        """Display a list of changed files with change counts."""
+        if files:
+            self.display_section_title(title)
+            for file_path, changes in files[:10]:
+                self.console.print(f"  {file_path}: {changes} changes")
+
+    def display_branch_list(
+        self,
+        branches: List[str],
+        current_branch: str,
+        title: str = "🌿 Active Branches",
+    ) -> None:
+        """Display a list of branches with current branch marked."""
+        if branches:
+            self.display_section_title(title)
+            for branch in branches:
+                marker = "→" if branch == current_branch else " "
+                self.console.print(f"  {marker} {branch}")
+
+    def display_success_panel(
+        self,
+        title: str,
+        content: str,
+        border_style: str = "green",
+    ) -> None:
+        """Display a success panel with content."""
+        self.console.print(Panel(content, title=title, border_style=border_style))
+
+    def display_info_panel(
+        self,
+        title: str,
+        content: str,
+        border_style: str = "cyan",
+    ) -> None:
+        """Display an info panel with content."""
+        self.console.print(Panel(content, title=title, border_style=border_style))
+
+    def display_files_list(
+        self, title: str, files: List[str], prefix: str = "•"
+    ) -> None:
+        """Display a list of files."""
+        if files:
+            self.console.print(f"[bold]{title}[/bold]")
+            for file in files:
+                self.console.print(f"  {prefix} {file}")
+            self.console.print()
+
+    def display_next_steps(self, steps: List[str]) -> None:
+        """Display next steps list."""
+        if steps:
+            self.console.print("[bold]Next Steps:[/bold]")
+            for step in steps:
+                self.console.print(f"  → {step}")
+            self.console.print()

claude_mpm/utils/environment_context.py

@@ -7,6 +7,7 @@ prompting is appropriate for dependency installation.
 
 import os
 import sys
+from pathlib import Path
 from typing import Dict, Tuple
 
 from ..core.logger import get_logger
@@ -139,7 +140,7 @@ class EnvironmentContext:
         """
         # Check for Docker-specific files
         for indicator_file in cls.CONTAINER_INDICATORS:
-            if os.path.exists(indicator_file):
+            if Path(indicator_file).exists():
                 logger.debug(f"Container detected via {indicator_file}")
                 return True
 
@@ -149,7 +150,7 @@ class EnvironmentContext:
 
         # Check cgroup for docker/containerd references
         try:
-            with open("/proc/1/cgroup") as f:
+            with Path("/proc/1/cgroup").open() as f:
                 cgroup_content = f.read()
                 if "docker" in cgroup_content or "containerd" in cgroup_content:
                     return True
@@ -189,7 +190,7 @@ class EnvironmentContext:
             get_ipython = globals().get("get_ipython")
             if get_ipython is not None:
                 return True
-        except:
+        except Exception:
             pass
 
         # Check for Jupyter-specific environment variables