claude-mpm 4.13.2__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/cli/startup.py

@@ -0,0 +1,481 @@
+"""
+CLI Startup Functions
+=====================
+
+This module contains initialization functions that run on CLI startup,
+including project registry, MCP configuration, and update checks.
+
+Part of cli/__init__.py refactoring to reduce file size and improve modularity.
+"""
+
+import os
+import sys
+
+
+def setup_early_environment(argv):
+    """
+    Set up early environment variables and logging suppression.
+
+    WHY: Some commands need special environment handling before any logging
+    or service initialization occurs.
+
+    Args:
+        argv: Command line arguments
+
+    Returns:
+        Processed argv list
+    """
+    # Disable telemetry and set cleanup flags early
+    os.environ.setdefault("DISABLE_TELEMETRY", "1")
+    os.environ.setdefault("CLAUDE_MPM_SKIP_CLEANUP", "0")
+
+    # EARLY CHECK: Suppress logging for configure command
+    if argv is None:
+        argv = sys.argv[1:]
+    if "configure" in argv or (len(argv) > 0 and argv[0] == "configure"):
+        import logging
+
+        logging.getLogger("claude_mpm").setLevel(logging.WARNING)
+        os.environ["CLAUDE_MPM_SKIP_CLEANUP"] = "1"
+
+    return argv
+
+
+def should_skip_background_services(args, processed_argv):
+    """
+    Determine if background services should be skipped for this command.
+
+    WHY: Some commands (help, version, configure, doctor) don't need
+    background services and should start faster.
+
+    Args:
+        args: Parsed arguments
+        processed_argv: Processed command line arguments
+
+    Returns:
+        bool: True if background services should be skipped
+    """
+    skip_commands = ["--version", "-v", "--help", "-h"]
+    return any(cmd in (processed_argv or sys.argv[1:]) for cmd in skip_commands) or (
+        hasattr(args, "command")
+        and args.command in ["info", "doctor", "config", "mcp", "configure"]
+    )
+
+
+def setup_configure_command_environment(args):
+    """
+    Set up special environment for configure command.
+
+    WHY: Configure command needs clean state without background services
+    and with suppressed logging.
+
+    Args:
+        args: Parsed arguments
+    """
+    if hasattr(args, "command") and args.command == "configure":
+        os.environ["CLAUDE_MPM_SKIP_CLEANUP"] = "1"
+        import logging
+
+        logging.getLogger("claude_mpm").setLevel(logging.WARNING)
+
+
+def discover_and_link_runtime_skills():
+    """
+    Discover and link runtime skills from user/project directories.
+
+    WHY: Automatically discover and link skills added to .claude/skills/
+    without requiring manual configuration.
+
+    DESIGN DECISION: Failures are logged but don't block startup to ensure
+    claude-mpm remains functional even if skills discovery fails.
+    """
+    try:
+        from ..cli.interactive.skills_wizard import (
+            discover_and_link_runtime_skills as discover_skills,
+        )
+
+        discover_skills()
+    except Exception as e:
+        # Import logger here to avoid circular imports
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to discover runtime skills: {e}")
+        # Continue execution - skills discovery failure shouldn't block startup
+
+
+def run_background_services():
+    """
+    Initialize all background services on startup.
+
+    WHY: Centralizes all startup service initialization for cleaner main().
+    """
+    initialize_project_registry()
+    check_mcp_auto_configuration()
+    verify_mcp_gateway_startup()
+    check_for_updates_async()
+    discover_and_link_runtime_skills()
+
+
+def setup_mcp_server_logging(args):
+    """
+    Configure minimal logging for MCP server mode.
+
+    WHY: MCP server needs minimal stderr-only logging to avoid interfering
+    with stdout protocol communication.
+
+    Args:
+        args: Parsed arguments
+
+    Returns:
+        Configured logger
+    """
+    import logging
+
+    from ..cli.utils import setup_logging
+    from ..constants import CLICommands
+
+    if (
+        args.command == CLICommands.MCP.value
+        and getattr(args, "mcp_command", None) == "start"
+    ):
+        if not getattr(args, "test", False) and not getattr(
+            args, "instructions", False
+        ):
+            # Production MCP mode - minimal logging
+            logging.basicConfig(
+                level=logging.ERROR,
+                format="%(message)s",
+                stream=sys.stderr,
+                force=True,
+            )
+            return logging.getLogger("claude_mpm")
+        # Test or instructions mode - normal logging
+        return setup_logging(args)
+    # Normal logging for all other commands
+    return setup_logging(args)
+
+
+def initialize_project_registry():
+    """
+    Initialize or update the project registry for the current session.
+
+    WHY: The project registry tracks all claude-mpm projects and their metadata
+    across sessions. This function ensures the current project is properly
+    registered and updates session information.
+
+    DESIGN DECISION: Registry failures are logged but don't prevent startup
+    to ensure claude-mpm remains functional even if registry operations fail.
+    """
+    try:
+        from ..services.project.registry import ProjectRegistry
+
+        registry = ProjectRegistry()
+        registry.get_or_create_project_entry()
+    except Exception as e:
+        # Import logger here to avoid circular imports
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to initialize project registry: {e}")
+        # Continue execution - registry failure shouldn't block startup
+
+
+def check_mcp_auto_configuration():
+    """
+    Check and potentially auto-configure MCP for pipx installations.
+
+    WHY: Users installing via pipx should have MCP work out-of-the-box with
+    minimal friction. This function offers one-time auto-configuration with
+    user consent.
+
+    DESIGN DECISION: This is blocking but quick - it only runs once and has
+    a 10-second timeout. We want to catch users on first run for the best
+    experience.
+    """
+    try:
+        from ..services.mcp_gateway.auto_configure import check_and_configure_mcp
+
+        # This function handles all the logic:
+        # - Checks if already configured
+        # - Checks if pipx installation
+        # - Checks if already asked before
+        # - Prompts user if needed
+        # - Configures if user agrees
+        check_and_configure_mcp()
+
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"MCP auto-configuration check failed: {e}")
+
+    # Skip MCP service fixes for the doctor and configure commands
+    # The doctor command performs its own comprehensive MCP service check
+    # The configure command allows users to configure which services to enable
+    # Running both would cause duplicate checks and log messages (9 seconds apart)
+    if len(sys.argv) > 1 and sys.argv[1] in ("doctor", "configure"):
+        return
+
+    # Also ensure MCP services are properly configured in ~/.claude.json
+    # This fixes incorrect paths and adds missing services
+    try:
+        from ..core.logger import get_logger
+        from ..services.mcp_config_manager import MCPConfigManager
+
+        logger = get_logger("cli")
+        mcp_manager = MCPConfigManager()
+
+        # Fix any corrupted installations first
+        fix_success, fix_message = mcp_manager.fix_mcp_service_issues()
+        if fix_message and "Fixed:" in fix_message:
+            logger.info(f"MCP service fixes applied: {fix_message}")
+
+        # Ensure all services are configured correctly
+        config_success, config_message = mcp_manager.ensure_mcp_services_configured()
+        if config_message and "Added MCP services" in config_message:
+            logger.info(f"MCP services configured: {config_message}")
+
+    except Exception as e:
+        # Non-critical - log but don't fail
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"MCP services configuration update failed: {e}")
+
+
+def verify_mcp_gateway_startup():
+    """
+    Verify MCP Gateway configuration on startup and pre-warm MCP services.
+
+    WHY: The MCP gateway should be automatically configured and verified on startup
+    to provide a seamless experience with diagnostic tools, file summarizer, and
+    ticket service. Pre-warming MCP services eliminates the 11.9s delay on first use.
+
+    DESIGN DECISION: This is non-blocking - failures are logged but don't prevent
+    startup to ensure claude-mpm remains functional even if MCP gateway has issues.
+    """
+    # Quick verification of MCP services installation
+    try:
+        from ..core.logger import get_logger
+        from ..services.mcp_service_verifier import verify_mcp_services_on_startup
+
+        logger = get_logger("mcp_verify")
+        all_ok, message = verify_mcp_services_on_startup()
+        if not all_ok:
+            logger.warning(message)
+    except Exception:
+        # Non-critical - continue with startup
+        pass
+
+    try:
+        import asyncio
+        import time
+
+        from ..core.logger import get_logger
+        from ..services.mcp_gateway.core.startup_verification import (
+            is_mcp_gateway_configured,
+            verify_mcp_gateway_on_startup,
+        )
+
+        logger = get_logger("mcp_prewarm")
+
+        # Quick check first - if already configured, skip detailed verification
+        gateway_configured = is_mcp_gateway_configured()
+
+        # DISABLED: Pre-warming MCP servers can interfere with Claude Code's MCP management
+        # This was causing issues with MCP server initialization and stderr handling
+        # def run_pre_warming():
+        #     loop = None
+        #     try:
+        #         start_time = time.time()
+        #         loop = asyncio.new_event_loop()
+        #         asyncio.set_event_loop(loop)
+        #
+        #         # Pre-warm MCP servers (especially vector search)
+        #         logger.info("Pre-warming MCP servers to eliminate startup delay...")
+        #         loop.run_until_complete(pre_warm_mcp_servers())
+        #
+        #         pre_warm_time = time.time() - start_time
+        #         if pre_warm_time > 1.0:
+        #             logger.info(f"MCP servers pre-warmed in {pre_warm_time:.2f}s")
+
+        # Dummy function to maintain structure
+        def run_pre_warming():
+            loop = None
+            try:
+                time.time()
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+
+                # Also run gateway verification if needed
+                if not gateway_configured:
+                    loop.run_until_complete(verify_mcp_gateway_on_startup())
+
+            except Exception as e:
+                # Non-blocking - log but don't fail
+                logger.debug(f"MCP pre-warming error (non-critical): {e}")
+            finally:
+                # Properly clean up event loop to prevent kqueue warnings
+                if loop is not None:
+                    try:
+                        # Cancel all running tasks
+                        pending = asyncio.all_tasks(loop)
+                        for task in pending:
+                            task.cancel()
+                        # Wait for tasks to complete cancellation
+                        if pending:
+                            loop.run_until_complete(
+                                asyncio.gather(*pending, return_exceptions=True)
+                            )
+                    except Exception:
+                        pass  # Ignore cleanup errors
+                    finally:
+                        loop.close()
+                        # Clear the event loop reference to help with cleanup
+                        asyncio.set_event_loop(None)
+
+        # Run pre-warming in background thread
+        import threading
+
+        pre_warm_thread = threading.Thread(target=run_pre_warming, daemon=True)
+        pre_warm_thread.start()
+
+        return
+
+        # Run detailed verification in background if not configured
+        if not gateway_configured:
+            # Note: We don't await this to avoid blocking startup
+            def run_verification():
+                loop = None
+                try:
+                    loop = asyncio.new_event_loop()
+                    asyncio.set_event_loop(loop)
+                    results = loop.run_until_complete(verify_mcp_gateway_on_startup())
+
+                    # Log results but don't block
+                    from ..core.logger import get_logger
+
+                    logger = get_logger("cli")
+
+                    if results.get("gateway_configured"):
+                        logger.debug("MCP Gateway verification completed successfully")
+                    else:
+                        logger.debug("MCP Gateway verification completed with warnings")
+
+                except Exception as e:
+                    from ..core.logger import get_logger
+
+                    logger = get_logger("cli")
+                    logger.debug(f"MCP Gateway verification failed: {e}")
+                finally:
+                    # Properly clean up event loop to prevent kqueue warnings
+                    if loop is not None:
+                        try:
+                            # Cancel all running tasks
+                            pending = asyncio.all_tasks(loop)
+                            for task in pending:
+                                task.cancel()
+                            # Wait for tasks to complete cancellation
+                            if pending:
+                                loop.run_until_complete(
+                                    asyncio.gather(*pending, return_exceptions=True)
+                                )
+                        except Exception:
+                            pass  # Ignore cleanup errors
+                        finally:
+                            loop.close()
+                            # Clear the event loop reference to help with cleanup
+                            asyncio.set_event_loop(None)
+
+            # Run in background thread to avoid blocking startup
+            import threading
+
+            verification_thread = threading.Thread(target=run_verification, daemon=True)
+            verification_thread.start()
+
+    except Exception as e:
+        # Import logger here to avoid circular imports
+        from ..core.logger import get_logger
+
+        logger = get_logger("cli")
+        logger.debug(f"Failed to start MCP Gateway verification: {e}")
+        # Continue execution - MCP gateway issues shouldn't block startup
+
+
+def check_for_updates_async():
+    """
+    Check for updates in background thread (non-blocking).
+
+    WHY: Users should be notified of new versions and have an easy way to upgrade
+    without manually checking PyPI/npm. This runs asynchronously on startup to avoid
+    blocking the CLI.
+
+    DESIGN DECISION: This is non-blocking and non-critical - failures are logged
+    but don't prevent startup. Only runs for pip/pipx/npm installations, skips
+    editable/development installations.
+    """
+
+    def run_update_check():
+        """Inner function to run in background thread."""
+        loop = None
+        try:
+            import asyncio
+
+            from ..core.logger import get_logger
+            from ..services.self_upgrade_service import SelfUpgradeService
+
+            logger = get_logger("upgrade_check")
+
+            # Create new event loop for this thread
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+            # Create upgrade service and check for updates
+            upgrade_service = SelfUpgradeService()
+
+            # Skip for editable installs (development mode)
+            from ..services.self_upgrade_service import InstallationMethod
+
+            if upgrade_service.installation_method == InstallationMethod.EDITABLE:
+                logger.debug("Skipping version check for editable installation")
+                return
+
+            # Check and prompt for upgrade if available (non-blocking)
+            loop.run_until_complete(upgrade_service.check_and_prompt_on_startup())
+
+        except Exception as e:
+            # Non-critical - log but don't fail startup
+            try:
+                from ..core.logger import get_logger
+
+                logger = get_logger("upgrade_check")
+                logger.debug(f"Update check failed (non-critical): {e}")
+            except Exception:
+                pass  # Avoid any errors in error handling
+        finally:
+            # Properly clean up event loop
+            if loop is not None:
+                try:
+                    # Cancel all running tasks
+                    pending = asyncio.all_tasks(loop)
+                    for task in pending:
+                        task.cancel()
+                    # Wait for tasks to complete cancellation
+                    if pending:
+                        loop.run_until_complete(
+                            asyncio.gather(*pending, return_exceptions=True)
+                        )
+                except Exception:
+                    pass  # Ignore cleanup errors
+                finally:
+                    loop.close()
+                    # Clear the event loop reference to help with cleanup
+                    asyncio.set_event_loop(None)
+
+    # Run update check in background thread to avoid blocking startup
+    import threading
+
+    update_check_thread = threading.Thread(target=run_update_check, daemon=True)
+    update_check_thread.start()

claude_mpm/cli/utils.py

@@ -6,9 +6,10 @@ Centralizing these functions reduces code duplication and provides a single plac
 for common CLI operations.
 """
 
+import difflib
 import sys
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
 
 from ..core.logger import get_logger
 
@@ -207,3 +208,53 @@ def ensure_directories() -> None:
         # Continue even if initialization fails
         # The individual commands will handle missing directories as needed
         pass
+
+
+def suggest_similar_commands(
+    invalid_command: str,
+    valid_commands: List[str],
+    cutoff: float = 0.6,
+    max_suggestions: int = 3,
+) -> Optional[str]:
+    """
+    Suggest similar commands for an invalid command using fuzzy matching.
+
+    WHY: Helps users quickly identify typos and discover correct command names
+    by suggesting the most similar valid commands. Uses stdlib difflib for
+    zero-dependency fuzzy matching.
+
+    DESIGN DECISION: Using difflib.get_close_matches provides good results for
+    typos and partial matches while being simple and lightweight (no external deps).
+
+    Args:
+        invalid_command: The invalid command the user typed
+        valid_commands: List of valid commands to match against
+        cutoff: Similarity threshold (0.0-1.0), default 0.6
+        max_suggestions: Maximum number of suggestions to return, default 3
+
+    Returns:
+        Formatted suggestion string or None if no good matches found
+
+    Examples:
+        >>> suggest_similar_commands("tickts", ["tickets", "run", "agents"])
+        "Did you mean 'tickets'?"
+
+        >>> suggest_similar_commands("mem", ["memory", "monitor", "mcp"])
+        "Did you mean one of these?\n  memory\n  monitor\n  mcp"
+
+        >>> suggest_similar_commands("xyz", ["tickets", "run"])
+        None  # No good matches
+    """
+    # Use difflib to find close matches
+    matches = difflib.get_close_matches(
+        invalid_command, valid_commands, n=max_suggestions, cutoff=cutoff
+    )
+
+    if not matches:
+        return None
+
+    # Format suggestion message
+    if len(matches) == 1:
+        return f"Did you mean '{matches[0]}'?"
+    suggestions = "\n  ".join(matches)
+    return f"Did you mean one of these?\n  {suggestions}"

claude_mpm/commands/mpm-help.md

@@ -90,6 +90,9 @@ Available Commands:
 /mpm-monitor [start|stop|restart|status|port]
   Manage Socket.IO monitoring server and dashboard
 
+/mpm-version
+  Display comprehensive version information including project version, all agents with versions, and all skills with versions
+
 Use '/mpm-help <command>' for detailed help on a specific command.
 ```
 

claude_mpm/commands/mpm-version.md

@@ -0,0 +1,113 @@
+# Display Claude MPM Version Information
+
+Show comprehensive version information for Claude MPM project, agents, and skills.
+
+## Usage
+
+```
+/mpm-version
+```
+
+## Description
+
+Display version information including:
+- Project version and build number
+- All deployed agents with their versions (grouped by tier: system/user/project)
+- All available skills with their versions (grouped by source: bundled/user/project)
+- Summary statistics
+
+## Implementation
+
+When you run `/mpm-version`, the PM will:
+
+1. **Collect Version Information**
+   - Use VersionService to gather all version data
+   - Project version from pyproject.toml
+   - Build number from BUILD_NUMBER file
+   - Agent versions from AgentRegistry
+   - Skills versions from SkillRegistry
+
+2. **Format Output**
+   - Hierarchical display: Project → Agents → Skills
+   - Grouped by tier/source for clarity
+   - Sorted alphabetically within groups
+   - Summary statistics at the end
+
+3. **Display Results**
+   - Well-formatted tree structure
+   - Easy to scan and read
+   - Includes totals and counts
+
+## Example Output
+
+```
+Claude MPM Version Information
+==============================
+
+Project Version: 4.16.3
+Build: 481
+
+Agents (35 total)
+-----------------
+
+System Agents (30):
+  ├─ agent-manager (1.0.0)
+  ├─ engineer (3.9.1)
+  ├─ research-agent (4.5.1)
+  ├─ documentation (2.1.0)
+  ├─ qa (2.0.3)
+  └─ ... (25 more)
+
+User Agents (3):
+  ├─ custom-agent (1.0.0)
+  ├─ testing-agent (0.5.0)
+  └─ prototype-agent (0.1.0)
+
+Project Agents (2):
+  ├─ project-specific (2.0.0)
+  └─ domain-expert (1.1.0)
+
+Skills (20 total)
+-----------------
+
+Bundled Skills (20):
+  ├─ test-driven-development (0.1.0)
+  ├─ systematic-debugging (0.1.0)
+  ├─ async-testing (0.1.0)
+  ├─ performance-profiling (0.1.0)
+  ├─ security-scanning (0.1.0)
+  └─ ... (15 more)
+
+User Skills (0):
+  (none)
+
+Project Skills (0):
+  (none)
+
+Summary
+-------
+• Project: v4.16.3 (build 481)
+• Agents: 35 total (30 system, 3 user, 2 project)
+• Skills: 20 total (20 bundled, 0 user, 0 project)
+```
+
+## PM Implementation Instructions
+
+To execute this command, PM should:
+
+1. Import and use VersionService:
+   ```python
+   from claude_mpm.services.version_service import VersionService
+
+   service = VersionService()
+   summary = service.get_version_summary()
+   ```
+
+2. Format output following the example structure above
+3. Handle missing data gracefully (show "unknown" for missing versions)
+4. Include all tiers/sources even if counts are zero
+
+## Related Commands
+
+- `/mpm-help` - Show all available MPM commands
+- `/mpm-status` - Show system status information

claude_mpm/commands/mpm.md

@@ -8,6 +8,7 @@ Available MPM commands:
 - /mpm-help - Show command help
 - /mpm-status - Show MPM status
 - /mpm-config - Manage configuration
+- /mpm-version - Display version information for project, agents, and skills
 
 Claude MPM extends Claude Code with:
 - Multi-agent orchestration

claude_mpm/config/agent_config.py

@@ -242,7 +242,7 @@ class AgentConfig:
                 Path.cwd() / get_path_manager().CONFIG_DIR / "agent_config.yaml"
             )
             if project_config.exists():
-                logger.info(f"Loading project agent config from {project_config}")
+                logger.debug(f"Loading project agent config from {project_config}")
                 file_config = cls.from_file(project_config)
                 # Merge with environment config (env takes precedence)
                 config = cls._merge_configs(config, file_config)
@@ -252,7 +252,7 @@ class AgentConfig:
             if user_config_dir:
                 user_config = user_config_dir / "agent_config.yaml"
                 if user_config.exists():
-                    logger.info(f"Loading user agent config from {user_config}")
+                    logger.debug(f"Loading user agent config from {user_config}")
                     file_config = cls.from_file(user_config)
                     config = cls._merge_configs(config, file_config)