claude-mpm 4.21.3__py3-none-any.whl → 5.0.2__py3-none-any.whl

claude_mpm/utils/gitignore.py

@@ -0,0 +1,241 @@
+"""GitIgnore management utilities.
+
+This module provides functionality to safely manage .gitignore entries,
+ensuring claude-mpm configuration directories are excluded from version control.
+
+Design Decisions:
+- In-memory set for duplicate detection (O(1) lookups)
+- Preserves existing file formatting and comments
+- Adds section headers for clarity
+- Handles edge cases (missing newlines, empty files, etc.)
+
+Trade-offs:
+- Simplicity: File append vs. full parse/rewrite (chosen append for safety)
+- Performance: Read entire file vs. streaming (file is small, simplicity wins)
+- Safety: Non-destructive append only, never modifies existing entries
+"""
+
+from pathlib import Path
+from typing import List, Set, Tuple
+
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
+
+
+class GitIgnoreManager:
+    """Manages .gitignore file updates safely and non-destructively.
+
+    Design Pattern: Builder pattern for fluent API
+    - Initialize with project directory
+    - Call ensure_entries() to add patterns
+    - Returns summary of changes made
+
+    Performance:
+    - Time Complexity: O(n) where n = existing .gitignore lines
+    - Space Complexity: O(n) for storing unique entries in set
+    - Expected Performance: <1ms for typical .gitignore files (<1000 lines)
+
+    Error Handling:
+    - FileNotFoundError: Creates new .gitignore if missing
+    - PermissionError: Propagated to caller for appropriate handling
+    - UnicodeDecodeError: Logged and treated as binary file (skip)
+    """
+
+    def __init__(self, project_dir: Path):
+        """Initialize with project directory.
+
+        Args:
+            project_dir: Path to project root (where .gitignore lives)
+        """
+        self.project_dir = Path(project_dir)
+        self.gitignore_path = self.project_dir / ".gitignore"
+
+    def ensure_entries(self, entries: List[str]) -> Tuple[List[str], List[str]]:
+        """Ensure specified entries exist in .gitignore.
+
+        Non-destructive operation that:
+        1. Reads existing entries (if file exists)
+        2. Identifies which entries are missing
+        3. Appends only missing entries with section header
+        4. Preserves all existing content and formatting
+
+        Args:
+            entries: List of gitignore patterns to add (e.g., [".claude-mpm/"])
+
+        Returns:
+            Tuple of (added_entries, existing_entries)
+            - added_entries: Patterns that were added to .gitignore
+            - existing_entries: Patterns that were already present
+
+        Example:
+            >>> manager = GitIgnoreManager(Path("."))
+            >>> added, existing = manager.ensure_entries([".claude-mpm/"])
+            >>> print(f"Added: {added}, Already present: {existing}")
+            Added: ['.claude-mpm/'], Already present: []
+        """
+        # Read existing entries
+        existing = self._read_existing_entries()
+
+        # Determine what needs to be added
+        to_add = [e for e in entries if e not in existing]
+        already_present = [e for e in entries if e in existing]
+
+        if to_add:
+            self._append_entries(to_add)
+            logger.info(f"Added {len(to_add)} entries to .gitignore: {to_add}")
+
+        if already_present:
+            logger.debug(f"Entries already in .gitignore: {already_present}")
+
+        return to_add, already_present
+
+    def _read_existing_entries(self) -> Set[str]:
+        """Read existing .gitignore entries.
+
+        Parses .gitignore file and extracts all non-comment, non-blank patterns.
+        Handles edge cases:
+        - File doesn't exist -> returns empty set
+        - File is binary -> logs warning, returns empty set
+        - File has no newline at end -> handled correctly
+
+        Returns:
+            Set of existing gitignore patterns (stripped, normalized)
+        """
+        if not self.gitignore_path.exists():
+            logger.debug(".gitignore does not exist, will create new file")
+            return set()
+
+        try:
+            with open(self.gitignore_path, encoding="utf-8") as f:
+                # Strip whitespace and comments, filter blanks
+                entries = {
+                    line.strip()
+                    for line in f
+                    if line.strip() and not line.strip().startswith("#")
+                }
+
+            logger.debug(f"Found {len(entries)} existing entries in .gitignore")
+            return entries
+
+        except UnicodeDecodeError:
+            logger.warning(
+                f".gitignore appears to be binary, cannot parse: {self.gitignore_path}"
+            )
+            return set()
+        except Exception as e:
+            logger.error(f"Error reading .gitignore: {e}")
+            raise
+
+    def _append_entries(self, entries: List[str]) -> None:
+        """Append entries to .gitignore with proper formatting.
+
+        Handles formatting edge cases:
+        - Ensures blank line before new section (if file exists and isn't empty)
+        - Adds section header comment for clarity
+        - Ensures each entry on its own line
+        - Handles missing trailing newline in existing file
+
+        Args:
+            entries: List of patterns to append
+
+        Raises:
+            PermissionError: If cannot write to .gitignore
+            OSError: If disk is full or other I/O error
+        """
+        mode = "a" if self.gitignore_path.exists() else "w"
+
+        try:
+            with open(self.gitignore_path, mode, encoding="utf-8") as f:
+                # Add blank line before entries if file exists and isn't empty
+                if mode == "a" and self.gitignore_path.stat().st_size > 0:
+                    # Check if last line has newline
+                    with open(self.gitignore_path, "rb") as check:
+                        check.seek(-1, 2)  # Seek to last byte
+                        last_byte = check.read(1)
+                        if last_byte != b"\n":
+                            f.write("\n")
+
+                    f.write("\n# Claude MPM configuration\n")
+                else:
+                    # New file or empty file - add header without extra blank line
+                    f.write("# Claude MPM configuration\n")
+
+                for entry in entries:
+                    f.write(f"{entry}\n")
+
+            logger.info(f"Updated .gitignore at {self.gitignore_path}")
+
+        except PermissionError:
+            logger.error(
+                f"Permission denied writing to .gitignore: {self.gitignore_path}"
+            )
+            raise
+        except OSError as e:
+            logger.error(f"I/O error writing to .gitignore: {e}")
+            raise
+
+
+def ensure_claude_mpm_gitignore(project_dir: str = ".") -> dict:
+    """Ensure claude-mpm directories are in .gitignore.
+
+    Convenience function that wraps GitIgnoreManager to add standard
+    claude-mpm configuration directories to .gitignore.
+
+    Standard Entries Added:
+    - .claude-mpm/: Main configuration directory
+    - .claude/agents/: Agent runtime files
+
+    Args:
+        project_dir: Project directory path (default: current directory)
+
+    Returns:
+        Dictionary with operation results:
+        - added: List of patterns that were added
+        - existing: List of patterns that were already present
+        - gitignore_path: Path to the .gitignore file
+
+    Example:
+        >>> result = ensure_claude_mpm_gitignore()
+        >>> if result["added"]:
+        ...     print(f"Added {len(result['added'])} entries to .gitignore")
+
+    Error Handling:
+        - PermissionError: Returns error dict with status="error"
+        - FileNotFoundError on parent dir: Returns error dict
+        - All other exceptions: Propagated to caller
+    """
+    try:
+        manager = GitIgnoreManager(Path(project_dir))
+
+        # Standard claude-mpm entries
+        entries_to_add = [
+            ".claude-mpm/",
+            ".claude/agents/",
+        ]
+
+        added, existing = manager.ensure_entries(entries_to_add)
+
+        return {
+            "status": "success",
+            "added": added,
+            "existing": existing,
+            "gitignore_path": str(manager.gitignore_path),
+        }
+
+    except PermissionError as e:
+        logger.error(f"Permission denied updating .gitignore: {e}")
+        return {
+            "status": "error",
+            "error": f"Permission denied: {e}",
+            "added": [],
+            "existing": [],
+        }
+    except FileNotFoundError as e:
+        logger.error(f"Project directory not found: {e}")
+        return {
+            "status": "error",
+            "error": f"Directory not found: {e}",
+            "added": [],
+            "existing": [],
+        }

claude_mpm/utils/log_cleanup.py

@@ -496,15 +496,15 @@ class LogCleanupUtility:
         }
 
         # Cleanup operations
-        sessions_removed, sessions_space = self.cleanup_old_sessions(
+        _sessions_removed, _sessions_space = self.cleanup_old_sessions(
             session_max_age_days, dry_run
         )
 
-        archives_removed, archives_space = self.cleanup_archived_logs(
+        _archives_removed, _archives_space = self.cleanup_archived_logs(
             archive_max_age_days, dry_run
         )
 
-        logs_removed, logs_space = self.cleanup_old_logs(log_max_age_days, dry_run)
+        _logs_removed, _logs_space = self.cleanup_old_logs(log_max_age_days, dry_run)
 
         # Optional compression
         if compress_age_days is not None:

claude_mpm/utils/progress.py

@@ -0,0 +1,383 @@
+"""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] + "..."
+
+        # Write to stdout with carriage return (overwrite current line)
+        sys.stdout.write(f"\r{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

@@ -218,8 +218,7 @@ class RobustPackageInstaller:
         return (
             (
                 # venv creates sys.base_prefix
-                hasattr(sys, "base_prefix")
-                and sys.base_prefix != sys.prefix
+                hasattr(sys, "base_prefix") and sys.base_prefix != sys.prefix
             )
             or (
                 # virtualenv creates sys.real_prefix
@@ -227,8 +226,7 @@ class RobustPackageInstaller:
             )
             or (
                 # VIRTUAL_ENV environment variable
-                os.environ.get("VIRTUAL_ENV")
-                is not None
+                os.environ.get("VIRTUAL_ENV") is not None
             )
         )
 
@@ -768,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())