claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

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

@@ -0,0 +1,313 @@
+"""
+Environment context detection for smart dependency checking.
+
+This module determines the execution environment and whether interactive
+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
+
+logger = get_logger(__name__)
+
+
+class EnvironmentContext:
+    """
+    Detects and analyzes the execution environment.
+
+    WHY: We need to know if we're in an environment where prompting makes sense.
+    Interactive prompting should only happen in TTY environments where a human
+    is present. CI/CD, Docker, and non-interactive contexts should skip prompts.
+
+    DESIGN DECISION: Use multiple indicators to detect environment type:
+    - TTY presence is the primary indicator for interactivity
+    - Environment variables help identify CI/CD and containerized environments
+    - Command-line flags can override automatic detection
+    """
+
+    # Known CI environment variables
+    CI_ENV_VARS = [
+        "CI",
+        "CONTINUOUS_INTEGRATION",
+        "GITHUB_ACTIONS",
+        "GITLAB_CI",
+        "JENKINS",
+        "TRAVIS",
+        "CIRCLECI",
+        "BUILDKITE",
+        "DRONE",
+        "TEAMCITY_VERSION",
+        "TF_BUILD",
+        "CODEBUILD_BUILD_ID",
+        "BITBUCKET_BUILD_NUMBER",
+    ]
+
+    # Docker/container indicators
+    CONTAINER_INDICATORS = [
+        "/.dockerenv",  # Docker creates this file
+        "/run/.containerenv",  # Podman creates this file
+    ]
+
+    @classmethod
+    def detect_execution_context(cls) -> Dict[str, bool]:
+        """
+        Detect the current execution context.
+
+        Returns:
+            Dictionary with context indicators:
+            - is_tty: True if running in a terminal with TTY
+            - is_ci: True if running in CI/CD environment
+            - is_docker: True if running inside Docker container
+            - is_interactive: True if interactive prompting is possible
+            - is_automated: True if running in automated context (CI or scheduled)
+        """
+        context = {
+            "is_tty": cls._detect_tty(),
+            "is_ci": cls._detect_ci(),
+            "is_docker": cls._detect_docker(),
+            "is_interactive": False,
+            "is_automated": False,
+            "is_jupyter": cls._detect_jupyter(),
+            "is_ssh": cls._detect_ssh(),
+        }
+
+        # Determine if we're in an automated context
+        context["is_automated"] = context["is_ci"] or cls._detect_automated()
+
+        # Interactive if TTY is available and not in automated context
+        context["is_interactive"] = (
+            context["is_tty"]
+            and not context["is_automated"]
+            and not context["is_docker"]  # Docker usually non-interactive
+        )
+
+        logger.debug(f"Environment context detected: {context}")
+        return context
+
+    @classmethod
+    def _detect_tty(cls) -> bool:
+        """
+        Detect if we have a TTY (terminal) available.
+
+        WHY: TTY presence is the most reliable indicator that a human
+        is present and can respond to prompts.
+        """
+        try:
+            # Check if stdin is a terminal
+            has_stdin_tty = (
+                sys.stdin.isatty() if hasattr(sys.stdin, "isatty") else False
+            )
+
+            # Check if stdout is a terminal (for output)
+            has_stdout_tty = (
+                sys.stdout.isatty() if hasattr(sys.stdout, "isatty") else False
+            )
+
+            # Both should be TTY for interactive use
+            return has_stdin_tty and has_stdout_tty
+        except Exception as e:
+            logger.debug(f"TTY detection failed: {e}")
+            return False
+
+    @classmethod
+    def _detect_ci(cls) -> bool:
+        """
+        Detect if running in a CI/CD environment.
+
+        WHY: CI environments should never prompt for user input.
+        They need to run fully automated without human intervention.
+        """
+        # Check for common CI environment variables
+        for var in cls.CI_ENV_VARS:
+            if os.environ.get(var):
+                logger.debug(f"CI environment detected via {var}={os.environ.get(var)}")
+                return True
+
+        # Additional heuristics for CI detection
+        return bool(os.environ.get("BUILD_ID") or os.environ.get("BUILD_NUMBER"))
+
+    @classmethod
+    def _detect_docker(cls) -> bool:
+        """
+        Detect if running inside a Docker container.
+
+        WHY: Docker containers typically run non-interactively,
+        and prompting for input often doesn't make sense.
+        """
+        # Check for Docker-specific files
+        for indicator_file in cls.CONTAINER_INDICATORS:
+            if Path(indicator_file).exists():
+                logger.debug(f"Container detected via {indicator_file}")
+                return True
+
+        # Check for container-related environment variables
+        if os.environ.get("KUBERNETES_SERVICE_HOST"):
+            return True
+
+        # Check cgroup for docker/containerd references
+        try:
+            with Path("/proc/1/cgroup").open() as f:
+                cgroup_content = f.read()
+                if "docker" in cgroup_content or "containerd" in cgroup_content:
+                    return True
+        except (FileNotFoundError, PermissionError):
+            pass
+
+        return False
+
+    @classmethod
+    def _detect_automated(cls) -> bool:
+        """
+        Detect if running in an automated context (cron, systemd, etc).
+
+        WHY: Automated scripts should not prompt for input even if
+        they technically have TTY access.
+        """
+        # Check for cron execution
+        if os.environ.get("CRON") or not os.environ.get("TERM"):
+            return True
+
+        # Check for systemd service
+        if os.environ.get("INVOCATION_ID"):  # systemd sets this
+            return True
+
+        return False
+
+    @classmethod
+    def _detect_jupyter(cls) -> bool:
+        """
+        Detect if running in Jupyter notebook/lab.
+
+        WHY: Jupyter has its own interaction model and standard
+        terminal prompts don't work well.
+        """
+        try:
+            # Check for IPython/Jupyter
+            get_ipython = globals().get("get_ipython")
+            if get_ipython is not None:
+                return True
+        except Exception:
+            pass
+
+        # Check for Jupyter-specific environment variables
+        return "JPY_PARENT_PID" in os.environ
+
+    @classmethod
+    def _detect_ssh(cls) -> bool:
+        """
+        Detect if running over SSH.
+
+        WHY: SSH sessions might have TTY but prompting behavior
+        should be more conservative.
+        """
+        return "SSH_CLIENT" in os.environ or "SSH_TTY" in os.environ
+
+    @classmethod
+    def should_prompt_for_dependencies(
+        cls, force_prompt: bool = False, force_skip: bool = False
+    ) -> Tuple[bool, str]:
+        """
+        Determine if we should prompt for dependency installation.
+
+        Args:
+            force_prompt: Force prompting regardless of environment
+            force_skip: Force skipping prompts regardless of environment
+
+        Returns:
+            Tuple of (should_prompt, reason_message)
+
+        WHY: This is the main decision point for the smart dependency system.
+        We want to prompt only when it makes sense and is safe to do so.
+        """
+        # Handle forced flags
+        if force_skip:
+            return False, "Prompting disabled by --no-prompt flag"
+        if force_prompt:
+            return True, "Prompting forced by --prompt flag"
+
+        # Get environment context
+        context = cls.detect_execution_context()
+
+        # Decision logic with clear reasoning
+        if not context["is_tty"]:
+            return False, "No TTY available for interactive prompts"
+
+        if context["is_ci"]:
+            return False, "Running in CI environment - prompts disabled"
+
+        if context["is_docker"]:
+            return False, "Running in Docker container - prompts disabled"
+
+        if context["is_automated"]:
+            return False, "Running in automated context - prompts disabled"
+
+        if context["is_jupyter"]:
+            return False, "Running in Jupyter - standard prompts not supported"
+
+        if context["is_interactive"]:
+            return True, "Interactive TTY environment detected"
+
+        # Default to not prompting if uncertain
+        return False, "Environment type uncertain - prompts disabled for safety"
+
+    @classmethod
+    def get_environment_summary(cls) -> str:
+        """
+        Get a human-readable summary of the environment.
+
+        Returns:
+            String describing the detected environment.
+        """
+        context = cls.detect_execution_context()
+
+        env_types = []
+        if context["is_ci"]:
+            env_types.append("CI/CD")
+        if context["is_docker"]:
+            env_types.append("Docker")
+        if context["is_jupyter"]:
+            env_types.append("Jupyter")
+        if context["is_ssh"]:
+            env_types.append("SSH")
+        if context["is_automated"]:
+            env_types.append("Automated")
+
+        if not env_types:
+            if context["is_interactive"]:
+                env_types.append("Interactive Terminal")
+            else:
+                env_types.append("Non-interactive")
+
+        return f"Environment: {', '.join(env_types)} (TTY: {context['is_tty']})"
+
+
+def detect_execution_context() -> Dict[str, bool]:
+    """
+    Convenience function to detect execution context.
+
+    Returns:
+        Dictionary with context indicators.
+    """
+    return EnvironmentContext.detect_execution_context()
+
+
+def should_prompt_for_dependencies(
+    force_prompt: bool = False, force_skip: bool = False
+) -> Tuple[bool, str]:
+    """
+    Convenience function to determine if prompting is appropriate.
+
+    Args:
+        force_prompt: Force prompting regardless of environment
+        force_skip: Force skipping prompts regardless of environment
+
+    Returns:
+        Tuple of (should_prompt, reason_message)
+    """
+    return EnvironmentContext.should_prompt_for_dependencies(
+        force_prompt=force_prompt, force_skip=force_skip
+    )