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

claude_mpm/utils/progress.py

@@ -0,0 +1,387 @@
+"""ASCII Progress Bar Utility for Git Operations.
+
+WHY: Provides visual feedback during long-running operations like agent/skill downloads
+from Git sources. Enhances user experience with real-time progress indicators.
+
+DESIGN DECISION: Terminal-aware progress bar with graceful degradation
+
+Rationale: Use sys.stdout for line overwriting with \r to create animated progress bars.
+Detect TTY environments to avoid breaking non-interactive terminals (CI/CD, pipes).
+ASCII-based to ensure compatibility across all terminal types.
+
+Trade-offs:
+- Performance: Progress updates are throttled to avoid output flooding
+- Compatibility: Works in both TTY and non-TTY modes (graceful degradation)
+- Simplicity: Pure Python, no external dependencies (tqdm would be overkill)
+
+Extension Points: Can be extended to support multi-line progress (parallel downloads),
+nested progress bars, or integration with logging frameworks.
+
+Performance:
+- Time Complexity: O(1) for each update operation
+- Space Complexity: O(1) - no state accumulation
+- Expected Performance: <1ms per update, negligible overhead
+
+Example Usage:
+    >>> with ProgressBar(total=100, prefix="Downloading") as pb:
+    ...     for i in range(100):
+    ...         time.sleep(0.01)
+    ...         pb.update(i + 1)
+    ...         # Progress bar updates automatically
+    >>> # Automatically prints completion message and newline
+"""
+
+import os
+import sys
+import time
+from typing import Any, Optional
+
+
+class ProgressBar:
+    """ASCII progress bar for terminal output.
+
+    Features:
+    - Animated progress bar with percentage
+    - Current/total item counter
+    - Customizable prefix message
+    - TTY detection for safe degradation
+    - Automatic terminal width detection
+    - Context manager support for cleanup
+
+    Design Decision: Use █ (U+2588) for filled sections and ░ (U+2591) for empty
+
+    Rationale: These Unicode block characters provide clear visual progress while
+    maintaining compatibility with most modern terminals. Alternative ASCII chars
+    like '#' and '-' were rejected for being less visually appealing.
+
+    Compatibility: Gracefully degrades to simple logging in non-TTY environments
+    (CI/CD, redirected output, etc.)
+    """
+
+    def __init__(
+        self,
+        total: int,
+        prefix: str = "Progress",
+        bar_width: int = 20,
+        show_percentage: bool = True,
+        show_counter: bool = True,
+        enabled: Optional[bool] = None,
+    ):
+        """Initialize progress bar.
+
+        Args:
+            total: Total number of items to process
+            prefix: Message to display before progress bar (e.g., "Downloading")
+            bar_width: Width of the progress bar in characters (default: 20)
+            show_percentage: Show percentage complete (default: True)
+            show_counter: Show current/total counter (default: True)
+            enabled: Override TTY detection (None = auto-detect, True = always show, False = disable)
+
+        Example:
+            >>> pb = ProgressBar(100, prefix="Syncing agents", bar_width=30)
+            >>> pb.update(50, message="agent.md")
+            >>> # Displays: Syncing agents [███████████████░░░░░░░░░░░░░░░] 50% (50/100) agent.md
+        """
+        self.total = total
+        self.prefix = prefix
+        self.bar_width = bar_width
+        self.show_percentage = show_percentage
+        self.show_counter = show_counter
+        self.current = 0
+        self.start_time = time.time()
+        self.last_update_time = 0.0
+        self.update_throttle = (
+            0.1  # Minimum seconds between updates (throttle to 10 Hz)
+        )
+
+        # Auto-detect TTY unless explicitly overridden
+        if enabled is None:
+            self.enabled = self._is_tty()
+        else:
+            self.enabled = enabled
+
+        # Terminal width detection for preventing overflow
+        self.terminal_width = self._get_terminal_width()
+
+    def _is_tty(self) -> bool:
+        """Check if stdout is a TTY (interactive terminal).
+
+        Returns:
+            True if stdout is a TTY, False otherwise (e.g., piped, redirected)
+
+        Design Decision: Disable progress bars in non-TTY environments
+
+        Rationale: Progress bars use \r (carriage return) for line overwriting,
+        which appears as garbage in log files, CI/CD output, and piped commands.
+        Detecting TTY ensures clean output in all contexts.
+
+        Example:
+            $ python script.py              # TTY - progress bars enabled
+            $ python script.py > log.txt    # Non-TTY - simple logging
+            $ python script.py | grep foo   # Non-TTY - simple logging
+        """
+        try:
+            return sys.stdout.isatty()
+        except AttributeError:
+            # sys.stdout might not have isatty() in some environments
+            return False
+
+    def _get_terminal_width(self) -> int:
+        """Get terminal width for preventing line overflow.
+
+        Returns:
+            Terminal width in characters (default: 80 if detection fails)
+
+        Error Handling:
+        - OSError: Returns 80 (standard terminal width)
+        - AttributeError: Returns 80 (fallback)
+        - ValueError: Returns 80 (invalid terminal size)
+        """
+        try:
+            # Try to get terminal size from os module (Python 3.3+)
+            size = os.get_terminal_size()
+            return size.columns
+        except (OSError, AttributeError, ValueError):
+            # Fallback to standard terminal width
+            return 80
+
+    def update(self, current: int, message: str = "") -> None:
+        """Update progress bar to current position.
+
+        Args:
+            current: Current progress value (0 to total)
+            message: Optional message to display after progress bar (e.g., filename)
+
+        Performance: Updates are throttled to 10 Hz to avoid output flooding.
+        Non-TTY mode: Logs milestone updates (0%, 25%, 50%, 75%, 100%) instead of every update.
+
+        Example:
+            >>> pb = ProgressBar(10, prefix="Downloading")
+            >>> for i in range(10):
+            ...     pb.update(i + 1, message=f"file_{i}.md")
+            >>> # Progress bar updates in-place, then prints completion
+        """
+        self.current = min(current, self.total)  # Clamp to total
+
+        # Throttle updates to avoid flooding terminal
+        current_time = time.time()
+        if (
+            current_time - self.last_update_time < self.update_throttle
+            and current < self.total
+        ):
+            return  # Skip update, too soon since last one
+
+        self.last_update_time = current_time
+
+        if not self.enabled:
+            # Non-TTY mode: Log milestone updates only
+            self._log_milestone(message)
+            return
+
+        # TTY mode: Render and display progress bar
+        self._render_progress_bar(message)
+
+    def _log_milestone(self, message: str) -> None:
+        """Log progress at milestone percentages in non-TTY mode.
+
+        Milestones: 0%, 25%, 50%, 75%, 100%
+
+        Args:
+            message: Optional message to include in log
+
+        Design Decision: Log milestones instead of every update in non-TTY
+
+        Rationale: Avoids flooding logs with hundreds of progress lines while
+        still providing useful feedback. Rejected logging every update because
+        it creates noise in CI/CD logs and log files.
+
+        Respects show_percentage and show_counter settings for consistent output
+        across TTY and non-TTY modes.
+        """
+        percentage = int((self.current / self.total) * 100) if self.total > 0 else 0
+
+        # Log at milestones: 0%, 25%, 50%, 75%, 100%
+        milestones = [0, 25, 50, 75, 100]
+        if percentage in milestones or self.current == self.total:
+            # Build output respecting show_percentage and show_counter settings
+            if message and not (self.show_counter or self.show_percentage):
+                # Simple format: "Prefix: message"
+                output = f"{self.prefix}: {message}"
+            else:
+                # Complex format with counter/percentage
+                parts = [self.prefix]
+
+                if self.show_counter:
+                    parts.append(f"{self.current}/{self.total}")
+
+                if self.show_percentage:
+                    parts.append(f"({percentage}%)")
+
+                if message:
+                    parts.append(f"- {message}")
+
+                output = " ".join(parts)
+
+            print(output, flush=True)
+
+    def _render_progress_bar(self, message: str) -> None:
+        """Render and display progress bar in TTY mode.
+
+        Args:
+            message: Optional message to display after progress bar
+
+        Output Format:
+            [Prefix] [████████░░░░░░░░░░░░] XX% (current/total) message
+
+        Design Decision: Use \r to overwrite same line for animation effect
+
+        Rationale: Creates smooth animation by updating the same line instead
+        of printing new lines. Requires TTY for proper display (hence TTY check).
+
+        Terminal Width Handling:
+        - Calculates available space based on terminal width
+        - Truncates message if output would overflow
+        - Ensures progress bar always fits on one line
+        """
+        percentage = int((self.current / self.total) * 100) if self.total > 0 else 0
+        filled = (
+            int(self.bar_width * self.current / self.total) if self.total > 0 else 0
+        )
+        bar = "█" * filled + "░" * (self.bar_width - filled)
+
+        # Build output components
+        parts = [f"{self.prefix} [{bar}]"]
+
+        if self.show_percentage:
+            parts.append(f"{percentage}%")
+
+        if self.show_counter:
+            parts.append(f"({self.current}/{self.total})")
+
+        if message:
+            parts.append(message)
+
+        output = " ".join(parts)
+
+        # Truncate if exceeds terminal width (leave 2 chars margin)
+        max_width = self.terminal_width - 2
+        if len(output) > max_width:
+            # Truncate message part, preserve progress bar
+            truncate_at = max_width - 3  # Leave room for "..."
+            output = output[:truncate_at] + "..."
+
+        # Pad output to terminal width to clear previous longer text
+        # This prevents text artifacts when current message is shorter than previous
+        padded_output = output.ljust(max_width)
+
+        # Write to stdout with carriage return (overwrite current line)
+        sys.stdout.write(f"\r{padded_output}")
+        sys.stdout.flush()
+
+    def finish(self, message: str = "Complete") -> None:
+        """Complete progress bar and print final message.
+
+        Args:
+            message: Final message to display (default: "Complete")
+
+        Design Decision: Print newline after completion to prevent terminal corruption
+
+        Rationale: Without newline, next shell prompt or log message would
+        overwrite the final progress bar state. Explicit finish() ensures
+        clean terminal output.
+
+        Bug Fix: Avoid duplicate completion messages in non-TTY mode by not
+        calling update() again if already at 100%. The final milestone was
+        already logged during the last update() call.
+
+        Example:
+            >>> pb = ProgressBar(100)
+            >>> pb.update(100)
+            >>> pb.finish(message="Download complete")
+            >>> # Output: [████████████████████] 100% (100/100) Download complete
+        """
+        if self.enabled:
+            # TTY mode: Update to show final message, then add newline
+            self.update(self.total, message=message)
+            sys.stdout.write("\n")
+            sys.stdout.flush()
+        # Non-TTY mode: Only log if not already at 100%
+        # If already at 100%, _log_milestone() already printed during last update()
+        elif self.current < self.total:
+            self.update(self.total, message=message)
+
+    def __enter__(self) -> "ProgressBar":
+        """Context manager entry.
+
+        Returns:
+            Self for use in with statements
+
+        Example:
+            >>> with ProgressBar(100, prefix="Processing") as pb:
+            ...     for i in range(100):
+            ...         pb.update(i + 1)
+            >>> # Automatically calls finish() on exit
+        """
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[type],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[Any],
+    ) -> None:
+        """Context manager exit - ensures finish() is called.
+
+        Args:
+            exc_type: Exception type (if raised)
+            exc_val: Exception value (if raised)
+            exc_tb: Exception traceback (if raised)
+
+        Error Handling:
+        - Calls finish() even if exception occurred
+        - Displays "Failed" message if exception raised
+        - Re-raises exception after cleanup
+
+        Returns:
+            None (does not suppress exceptions)
+        """
+        if exc_type is not None:
+            # Exception occurred - finish with error message
+            self.finish(message="Failed")
+        else:
+            # Normal completion
+            self.finish()
+
+        # Don't suppress exceptions (returning None is equivalent to returning False)
+
+
+# Convenience function for simple use cases
+def create_progress_bar(
+    total: int,
+    prefix: str = "Progress",
+    enabled: Optional[bool] = None,
+) -> ProgressBar:
+    """Create a progress bar with sensible defaults.
+
+    Args:
+        total: Total number of items
+        prefix: Progress message
+        enabled: Override TTY detection (None = auto)
+
+    Returns:
+        Configured ProgressBar instance
+
+    Example:
+        >>> pb = create_progress_bar(100, "Downloading agents")
+        >>> for i in range(100):
+        ...     pb.update(i + 1, message=f"agent_{i}.md")
+        >>> pb.finish()
+    """
+    return ProgressBar(
+        total=total,
+        prefix=prefix,
+        bar_width=20,
+        show_percentage=True,
+        show_counter=True,
+        enabled=enabled,
+    )

claude_mpm/utils/robust_installer.py

@@ -9,6 +9,7 @@ DESIGN DECISION: We implement exponential backoff for retries and provide
 multiple installation strategies (pip, conda, source) to maximize success rate.
 """
 
+import os
 import re
 import subprocess
 import sys
@@ -80,6 +81,7 @@ class RobustPackageInstaller:
         self.use_cache = use_cache
         self.attempts: List[InstallAttempt] = []
         self.success_cache: Dict[str, bool] = {}
+        self.in_virtualenv = self._check_virtualenv()
         self.is_pep668_managed = self._check_pep668_managed()
         self.pep668_warning_shown = False
 
@@ -100,10 +102,9 @@ class RobustPackageInstaller:
             Tuple of (success, error_message)
         """
         # Check success cache first
-        if package_spec in self.success_cache:
-            if self.success_cache[package_spec]:
-                logger.debug(f"Package {package_spec} already successfully installed")
-                return True, None
+        if self.success_cache.get(package_spec):
+            logger.debug(f"Package {package_spec} already successfully installed")
+            return True, None
 
         # Default strategy order
         if strategies is None:
@@ -202,6 +203,33 @@ class RobustPackageInstaller:
         except Exception as e:
             return False, f"Unexpected error: {e!s}"
 
+    def _check_virtualenv(self) -> bool:
+        """
+        Check if running inside a virtual environment.
+
+        WHY: Virtual environments are already isolated and don't need
+        --user or --break-system-packages flags. In fact, using --user
+        in a virtualenv causes errors.
+
+        Returns:
+            True if in a virtualenv, False otherwise
+        """
+        # Multiple ways to detect virtualenv
+        return (
+            (
+                # venv creates sys.base_prefix
+                hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix
+            )
+            or (
+                # virtualenv creates sys.real_prefix
+                hasattr(sys, "real_prefix")
+            )
+            or (
+                # VIRTUAL_ENV environment variable
+                os.environ.get("VIRTUAL_ENV") is not None
+            )
+        )
+
     def _check_pep668_managed(self) -> bool:
         """
         Check if Python environment is PEP 668 externally managed.
@@ -212,6 +240,11 @@ class RobustPackageInstaller:
         Returns:
             True if PEP 668 managed, False otherwise
         """
+        # If in virtualenv, PEP 668 doesn't apply
+        if self.in_virtualenv:
+            logger.debug("Running in virtualenv, PEP 668 restrictions don't apply")
+            return False
+
         # Check for EXTERNALLY-MANAGED marker file
         stdlib_path = sysconfig.get_path("stdlib")
         marker_file = Path(stdlib_path) / "EXTERNALLY-MANAGED"
@@ -241,7 +274,7 @@ class RobustPackageInstaller:
                 "Your Python installation is marked as externally managed (PEP 668).\n"
                 "This typically means you're using a system Python managed by Homebrew, apt, etc.\n"
                 "\n"
-                "Installing packages with --break-system-packages --user flags...\n"
+                "Installing packages with --break-system-packages flag...\n"
                 "\n"
                 "RECOMMENDED: Use a virtual environment instead:\n"
                 "  python -m venv .venv\n"
@@ -256,8 +289,10 @@ class RobustPackageInstaller:
         """
         Build the installation command for a given strategy.
 
-        WHY: PEP 668 support added to handle externally managed Python
-        environments by adding appropriate flags when needed.
+        WHY: Proper environment detection ensures we use the right pip flags:
+        - Virtualenv: No special flags needed (already isolated)
+        - PEP 668 system: Use --break-system-packages only
+        - Normal system: Use --user for user-local install
 
         Args:
             package_spec: Package specification
@@ -268,14 +303,19 @@ class RobustPackageInstaller:
         """
         base_cmd = [sys.executable, "-m", "pip", "install"]
 
-        # Add PEP 668 bypass flags if needed
-        if self.is_pep668_managed:
+        # Determine appropriate flags based on environment
+        if self.in_virtualenv:
+            # In virtualenv - no special flags needed
+            logger.debug("Installing in virtualenv (no special flags)")
+        elif self.is_pep668_managed:
+            # System Python with PEP 668 - use --break-system-packages only
             self._show_pep668_warning()
-            # Add flags to bypass PEP 668 restrictions
-            base_cmd.extend(["--break-system-packages", "--user"])
-            logger.debug(
-                "Added --break-system-packages --user flags for PEP 668 environment"
-            )
+            base_cmd.append("--break-system-packages")
+            logger.debug("Added --break-system-packages flag for PEP 668 environment")
+        else:
+            # Normal system Python - use --user for user-local install
+            base_cmd.append("--user")
+            logger.debug("Added --user flag for user-local installation")
 
         # Add cache control
         if not self.use_cache:
@@ -340,6 +380,12 @@ class RobustPackageInstaller:
             "tree-sitter-java",
             "tree-sitter-cpp",
             "tree-sitter-c",
+            # Database packages that require compilation
+            "mysqlclient",  # Requires MySQL development headers
+            "psycopg2",  # Requires PostgreSQL development headers
+            "cx_oracle",  # Requires Oracle client libraries
+            "pycairo",  # Requires Cairo development headers
+            "lxml",  # Requires libxml2 development headers
         }
 
         return package_name.lower() in special_packages
@@ -363,6 +409,35 @@ class RobustPackageInstaller:
                 InstallStrategy.PIP_NO_DEPS,
             ]
 
+        # Database packages that require compilation
+        compilation_packages = {
+            "mysqlclient": ["pymysql"],  # Pure Python alternative
+            "psycopg2": ["psycopg2-binary"],  # Binary wheel alternative
+            "cx_oracle": [],  # No good alternative
+            "pycairo": [],  # No good alternative
+            "lxml": [],  # Usually works with binary wheels
+        }
+
+        package_lower = package_name.lower()
+        if package_lower in compilation_packages:
+            # Try normal install first, but with limited retries
+            strategies = [InstallStrategy.PIP]
+
+            # If there are alternatives, log suggestion
+            alternatives = compilation_packages[package_lower]
+            if alternatives:
+                logger.info(
+                    f"Package {package_name} requires compilation. "
+                    f"Consider using alternative: {', '.join(alternatives)}"
+                )
+            else:
+                logger.warning(
+                    f"Package {package_name} requires compilation and may fail on systems "
+                    f"without development headers installed."
+                )
+
+            return strategies
+
         return [InstallStrategy.PIP, InstallStrategy.PIP_UPGRADE]
 
     def _verify_installation(self, package_spec: str) -> bool:
@@ -459,6 +534,27 @@ class RobustPackageInstaller:
         if not stderr:
             return "Unknown error"
 
+        # Check for specific compilation errors
+        stderr_lower = stderr.lower()
+
+        if "mysql_config" in stderr_lower or "mysql.h" in stderr_lower:
+            return (
+                "mysqlclient compilation failed (missing MySQL development headers). "
+                "Use 'pip install pymysql' for a pure Python alternative that doesn't require compilation."
+            )
+
+        if "pg_config" in stderr_lower or "libpq-fe.h" in stderr_lower:
+            return (
+                "psycopg2 compilation failed (missing PostgreSQL development headers). "
+                "Use 'pip install psycopg2-binary' for a pre-compiled version."
+            )
+
+        if "oracle" in stderr_lower and "client" in stderr_lower:
+            return (
+                "cx_Oracle compilation failed (missing Oracle client libraries). "
+                "Use 'pip install oracledb' for a pure Python alternative."
+            )
+
         # Look for ERROR: lines
         error_lines = []
         for line in stderr.splitlines():
@@ -557,11 +653,16 @@ class RobustPackageInstaller:
         try:
             cmd = [sys.executable, "-m", "pip", "install"]
 
-            # Add PEP 668 bypass flags if needed
-            if self.is_pep668_managed:
+            # Add appropriate flags based on environment
+            if self.in_virtualenv:
+                logger.debug("Batch install in virtualenv (no special flags)")
+            elif self.is_pep668_managed:
                 self._show_pep668_warning()
-                cmd.extend(["--break-system-packages", "--user"])
-                logger.debug("Added PEP 668 flags for batch installation")
+                cmd.append("--break-system-packages")
+                logger.debug("Added --break-system-packages for batch installation")
+            else:
+                cmd.append("--user")
+                logger.debug("Added --user flag for batch installation")
 
             cmd.extend(packages)
 
@@ -599,12 +700,18 @@ class RobustPackageInstaller:
         lines.append("INSTALLATION REPORT")
         lines.append("=" * 60)
 
-        # Add PEP 668 status
-        if self.is_pep668_managed:
-            lines.append("")
+        # Add environment status
+        lines.append("")
+        if self.in_virtualenv:
+            lines.append("✓ Environment: Virtual Environment (isolated)")
+            lines.append("  No special pip flags needed")
+        elif self.is_pep668_managed:
             lines.append("⚠️  PEP 668 Managed Environment: YES")
-            lines.append("   Installations used --break-system-packages --user flags")
+            lines.append("   Installations used --break-system-packages flag")
             lines.append("   Consider using a virtual environment for better isolation")
+        else:
+            lines.append("Environment: System Python")
+            lines.append("   Installations used --user flag for user-local install")
 
         # Summary
         total_attempts = len(self.attempts)
@@ -617,7 +724,7 @@ class RobustPackageInstaller:
         lines.append("")
 
         # Details by package
-        packages = {}
+        packages: Dict[str, List[InstallAttempt]] = {}
         for attempt in self.attempts:
             if attempt.package not in packages:
                 packages[attempt.package] = []
@@ -659,7 +766,7 @@ def install_with_retry(
         logging.getLogger().setLevel(logging.DEBUG)
 
     installer = RobustPackageInstaller(max_retries=max_retries)
-    successful, failed, errors = installer.install_packages(packages)
+    _successful, failed, errors = installer.install_packages(packages)
 
     if verbose:
         print(installer.get_report())

claude_mpm/utils/session_logging.py

@@ -6,13 +6,13 @@ Session Logging Utilities
 Convenience functions for session-based response logging.
 """
 
-import logging
 import os
 from typing import Any, Dict, Optional
 
+from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.services.claude_session_logger import get_session_logger
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 def is_session_logging_enabled() -> bool: