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

claude_mpm/cli/parsers/agent_source_parser.py

@@ -0,0 +1,171 @@
+"""Agent source command parser for agent repository management.
+
+WHY: This module provides CLI commands for managing agent source repositories
+(Git repositories containing agent markdown files). Parallel to skill source management
+but for the agent deployment system (multi-tier Git-based agents).
+
+DESIGN DECISION: Agent source management is separate from agent deployment to
+maintain clear separation of concerns:
+- agent-source commands: Manage repository configuration
+- agents commands: View and interact with agents themselves
+
+IMPLEMENTATION NOTE: This module is adapted from skill_source_parser.py, following
+the same proven patterns but for agent repositories instead of skills.
+"""
+
+import argparse
+
+from .base_parser import add_common_arguments
+
+
+def add_agent_source_subparser(subparsers) -> argparse.ArgumentParser:
+    """Add the agent-source subparser with all repository management commands.
+
+    WHY: Agent sources (Git repositories) need their own command group
+    for managing repository configuration, priorities, and synchronization.
+
+    Args:
+        subparsers: The subparsers object from the main parser
+
+    Returns:
+        The configured agent-source subparser
+    """
+    # Agent source command with subcommands
+    agent_source_parser = subparsers.add_parser(
+        "agent-source",
+        help="Manage agent source repositories",
+    )
+    add_common_arguments(agent_source_parser)
+
+    agent_source_subparsers = agent_source_parser.add_subparsers(
+        dest="agent_source_command",
+        help="Agent source repository commands",
+        metavar="SUBCOMMAND",
+    )
+
+    # Add repository
+    add_parser = agent_source_subparsers.add_parser(
+        "add",
+        help="Add a new agent source repository",
+    )
+    add_parser.add_argument(
+        "url",
+        help="Git repository URL (e.g., https://github.com/owner/repo)",
+    )
+    add_parser.add_argument(
+        "--subdirectory",
+        help="Subdirectory within repository containing agents (e.g., 'agents')",
+    )
+    add_parser.add_argument(
+        "--priority",
+        type=int,
+        default=100,
+        help="Priority for conflict resolution (lower = higher precedence, default: 100)",
+    )
+    add_parser.add_argument(
+        "--disabled",
+        action="store_true",
+        help="Add repository but keep it disabled",
+    )
+    add_parser.add_argument(
+        "--test",
+        action="store_true",
+        help="Test repository access without saving to configuration",
+    )
+    add_parser.add_argument(
+        "--no-test",
+        action="store_true",
+        dest="skip_test",
+        help="Skip immediate testing (not recommended)",
+    )
+
+    # Remove repository
+    remove_parser = agent_source_subparsers.add_parser(
+        "remove",
+        help="Remove an agent source repository",
+    )
+    remove_parser.add_argument(
+        "source_id",
+        help="Source identifier (e.g., 'owner/repo' or 'owner/repo/subdirectory')",
+    )
+    remove_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+
+    # List repositories
+    list_parser = agent_source_subparsers.add_parser(
+        "list",
+        help="List configured agent source repositories",
+    )
+    list_parser.add_argument(
+        "--by-priority",
+        action="store_true",
+        dest="by_priority",
+        help="Sort by priority (lowest first)",
+    )
+    list_parser.add_argument(
+        "--enabled-only",
+        action="store_true",
+        dest="enabled_only",
+        help="Show only enabled repositories",
+    )
+    list_parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+
+    # Update/sync repositories
+    update_parser = agent_source_subparsers.add_parser(
+        "update",
+        help="Update (sync) agent sources from Git",
+    )
+    update_parser.add_argument(
+        "source_id",
+        nargs="?",
+        help="Optional: Update only this repository (default: update all)",
+    )
+    update_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force update even if cache is fresh",
+    )
+
+    # Enable repository
+    enable_parser = agent_source_subparsers.add_parser(
+        "enable",
+        help="Enable a disabled repository",
+    )
+    enable_parser.add_argument(
+        "source_id",
+        help="Source identifier to enable",
+    )
+
+    # Disable repository
+    disable_parser = agent_source_subparsers.add_parser(
+        "disable",
+        help="Disable a repository",
+    )
+    disable_parser.add_argument(
+        "source_id",
+        help="Source identifier to disable",
+    )
+
+    # Show repository details
+    show_parser = agent_source_subparsers.add_parser(
+        "show",
+        help="Show details for an agent source",
+    )
+    show_parser.add_argument(
+        "source_id",
+        help="Source identifier to show",
+    )
+    show_parser.add_argument(
+        "--agents",
+        action="store_true",
+        help="Also list agents from this source",
+    )
+
+    return agent_source_parser

claude_mpm/cli/parsers/agents_parser.py

@@ -31,7 +31,22 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
     """
     # Agents command with subcommands
     agents_parser = subparsers.add_parser(
-        CLICommands.AGENTS.value, help="Manage agents and deployment"
+        CLICommands.AGENTS.value,
+        help="Manage agents and deployment",
+        description="""
+Manage Claude MPM agents.
+
+NOTE: For interactive agent management, use 'claude-mpm config' instead.
+      The 'agents manage' command has been deprecated in favor of the
+      unified configuration interface.
+
+Available commands:
+  discover    Discover available agents from configured sources
+  deploy      Deploy agents to your project
+  list        List available agents
+  manage      (Deprecated) Use 'claude-mpm config' instead
+""",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     add_common_arguments(agents_parser)
 
@@ -121,9 +136,17 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         "--backup", action="store_true", help="Create backup before deletion"
     )
 
-    # Manage local agents (interactive menu)
-    agents_subparsers.add_parser(
-        "manage", help="Interactive menu for managing local agents"
+    # Manage local agents (interactive menu) - DEPRECATED
+    manage_parser = agents_subparsers.add_parser(
+        "manage",
+        help="(Deprecated) Manage local agents - use 'claude-mpm config' instead",
+        description="Manage locally deployed agents. Note: This command has been deprecated. "
+        "Please use 'claude-mpm config' for the enhanced configuration interface.",
+    )
+    manage_parser.epilog = (
+        "\nDEPRECATION NOTICE:\n"
+        "This command has been deprecated in favor of 'claude-mpm config' which provides\n"
+        "a unified interface for managing agents, skills, templates, and behavior settings.\n"
     )
 
     # Configure agent deployment settings
@@ -193,6 +216,11 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         action="store_true",
         help="Show what would be deployed without actually deploying",
     )
+    deploy_agents_parser.add_argument(
+        "--preset",
+        type=str,
+        help="Deploy agents by preset name (minimal, python-dev, nextjs-fullstack, etc.)",
+    )
 
     # Validate agents
     validate_agents_parser = agents_subparsers.add_parser(
@@ -240,6 +268,28 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         help="Maximum retry attempts per package (default: 3)",
     )
 
+    # Cleanup: sync, install, and remove old underscore-named agents
+    cleanup_parser = agents_subparsers.add_parser(
+        "cleanup",
+        help="Sync agents, install with new naming, and remove old underscore-named duplicates",
+    )
+    cleanup_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without actually doing it",
+    )
+    cleanup_parser.add_argument(
+        "--target",
+        type=Path,
+        help="Target directory for agent deployment (default: project .claude-mpm/agents/)",
+    )
+    cleanup_parser.add_argument(
+        "--global",
+        dest="global_deployment",
+        action="store_true",
+        help="Deploy to global ~/.claude/agents/ instead of project directory",
+    )
+
     # Cleanup orphaned agents
     cleanup_orphaned_parser = agents_subparsers.add_parser(
         "cleanup-orphaned", help="Clean up orphaned agents that don't have templates"
@@ -266,6 +316,96 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
         help="Only show summary, not individual agents",
     )
 
+    # Migrate user-level agents to project-level (DEPRECATION support)
+    migrate_parser = agents_subparsers.add_parser(
+        "migrate-to-project",
+        help="Migrate user-level agents to project-level (user-level is DEPRECATED)",
+    )
+    migrate_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be migrated without actually doing it",
+    )
+    migrate_parser.add_argument(
+        "--force",
+        "-f",
+        action="store_true",
+        help="Overwrite existing project agents if conflicts",
+    )
+
+    # Deploy all agents from sources (single-tier deployment)
+    deploy_all_parser = agents_subparsers.add_parser(
+        "deploy-all",
+        help="Deploy all agents from configured sources (single-tier deployment)",
+    )
+    deploy_all_parser.add_argument(
+        "--force-sync",
+        action="store_true",
+        help="Force sync repositories before deploying (ignore cache)",
+    )
+    deploy_all_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # List available agents from sources
+    available_parser = agents_subparsers.add_parser(
+        "available",
+        help="List available agents from all configured sources",
+    )
+    available_parser.add_argument(
+        "--source",
+        help="Filter by source repository (e.g., 'owner/repo/subdirectory')",
+    )
+    available_parser.add_argument(
+        "--format",
+        choices=["table", "json", "simple"],
+        default="table",
+        help="Output format (default: table)",
+    )
+
+    # Discover agents with rich filtering (Phase 1: Discovery & Browsing)
+    discover_parser = agents_subparsers.add_parser(
+        "discover",
+        help="Discover available agents from configured sources with rich filtering",
+    )
+    discover_parser.add_argument(
+        "--source",
+        help="Filter by specific source ID (e.g., 'owner/repo')",
+    )
+    discover_parser.add_argument(
+        "--category",
+        help="Filter by category (e.g., 'engineer/backend', 'qa', 'ops/platform')",
+    )
+    discover_parser.add_argument(
+        "--language",
+        help="Filter by programming language (e.g., 'python', 'javascript', 'rust')",
+    )
+    discover_parser.add_argument(
+        "--framework",
+        help="Filter by framework (e.g., 'react', 'nextjs', 'django')",
+    )
+    discover_parser.add_argument(
+        "--platform",
+        help="Filter by platform (e.g., 'vercel', 'gcp', 'docker')",
+    )
+    discover_parser.add_argument(
+        "--specialization",
+        help="Filter by specialization (e.g., 'data', 'security', 'mobile')",
+    )
+    discover_parser.add_argument(
+        "--format",
+        choices=["table", "json", "simple"],
+        default="table",
+        help="Output format (default: table)",
+    )
+    discover_parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show descriptions and metadata for each agent",
+    )
+
     # Auto-configuration commands (TSK-0054 Phase 5)
     from .auto_configure_parser import (
         add_agents_detect_subparser,
@@ -275,4 +415,33 @@ def add_agents_subparser(subparsers) -> argparse.ArgumentParser:
     add_agents_detect_subparser(agents_subparsers)
     add_agents_recommend_subparser(agents_subparsers)
 
+    # Phase 3: Agent Selection Modes (single-tier deployment)
+    # Minimal configuration - deploy 6 core agents
+    deploy_minimal_parser = agents_subparsers.add_parser(
+        "deploy-minimal",
+        help="Deploy minimal configuration (6 core agents: engineer, documentation, qa, research, ops, ticketing)",
+    )
+    deploy_minimal_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
+    # Auto-configure - detect toolchain and deploy matching agents
+    deploy_auto_parser = agents_subparsers.add_parser(
+        "deploy-auto",
+        help="Auto-detect project toolchain and deploy matching agents",
+    )
+    deploy_auto_parser.add_argument(
+        "--path",
+        type=Path,
+        default=Path.cwd(),
+        help="Project path to scan for toolchain detection (default: current directory)",
+    )
+    deploy_auto_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be deployed without actually deploying",
+    )
+
     return agents_parser

claude_mpm/cli/parsers/base_parser.py

@@ -389,6 +389,27 @@ def create_parser(
     except ImportError:
         pass
 
+    try:
+        from .source_parser import add_source_subparser
+
+        add_source_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .skill_source_parser import add_skill_source_subparser
+
+        add_skill_source_subparser(subparsers)
+    except ImportError:
+        pass
+
+    try:
+        from .agent_source_parser import add_agent_source_subparser
+
+        add_agent_source_subparser(subparsers)
+    except ImportError:
+        pass
+
     try:
         from .auto_configure_parser import add_auto_configure_subparser
 
@@ -541,6 +562,34 @@ def create_parser(
         from ..commands.verify import add_parser as add_verify_parser
 
         add_verify_parser(subparsers)
+
+        # Add hook-errors command for managing hook error memory
+        hook_errors_parser = subparsers.add_parser(
+            "hook-errors",
+            help="Manage hook error memory and diagnostics",
+        )
+        hook_errors_parser.add_argument(
+            "hook_errors_command",
+            nargs="?",
+            choices=["list", "summary", "clear", "diagnose", "status"],
+            help="Hook errors subcommand",
+        )
+        hook_errors_parser.add_argument(
+            "--format",
+            choices=["table", "json"],
+            default="table",
+            help="Output format for list command",
+        )
+        hook_errors_parser.add_argument(
+            "--hook-type",
+            help="Filter by specific hook type",
+        )
+        hook_errors_parser.add_argument(
+            "-y",
+            "--yes",
+            action="store_true",
+            help="Skip confirmation prompts",
+        )
     except ImportError:
         # Commands module may not be available during testing or refactoring
         pass

claude_mpm/cli/parsers/config_parser.py

@@ -1,27 +1,26 @@
-from pathlib import Path
-
 """
 Config command parser for claude-mpm CLI.
 
-WHY: This module contains all arguments specific to configuration management,
-extracted from the monolithic parser.py for better organization.
+WHY: This module provides the config command which is synonymous with configure.
+Both launch the interactive configuration TUI.
 
-DESIGN DECISION: Configuration commands handle validation and management
-of claude-mpm settings and warrant their own module.
+DESIGN DECISION: 'config' and 'configure' are aliases - both commands provide
+identical functionality through the interactive configuration interface.
 """
 
 import argparse
 
-from ...constants import CLICommands, ConfigCommands
+from ...constants import CLICommands
 from .base_parser import add_common_arguments
 
 
 def add_config_subparser(subparsers) -> argparse.ArgumentParser:
     """
-    Add the config subparser with all configuration management commands.
+    Add the config subparser (alias for configure).
 
-    WHY: Configuration management has multiple subcommands for validation,
-    viewing, and editing that need their own argument structures.
+    WHY: 'config' and 'configure' are synonymous commands that both launch
+    the interactive configuration interface. This provides a consistent
+    parser setup matching the configure command.
 
     Args:
         subparsers: The subparsers object from the main parser
@@ -29,57 +28,111 @@ def add_config_subparser(subparsers) -> argparse.ArgumentParser:
     Returns:
         The configured config subparser
     """
-    # Config command with subcommands
+    # Config command - alias for configure (interactive configuration)
     config_parser = subparsers.add_parser(
-        CLICommands.CONFIG.value, help="Validate and manage configuration"
+        CLICommands.CONFIG.value,
+        help="Interactive configuration interface for managing agents and behaviors (alias for 'configure')",
+        description="Launch an interactive Rich-based menu for configuring claude-mpm agents, templates, and behavior files",
     )
+
+    # Add common arguments
     add_common_arguments(config_parser)
 
-    config_subparsers = config_parser.add_subparsers(
-        dest="config_command", help="Config commands", metavar="SUBCOMMAND"
+    # Configuration scope options
+    scope_group = config_parser.add_argument_group("configuration scope")
+    scope_group.add_argument(
+        "--scope",
+        choices=["project", "user"],
+        default="project",
+        help="Configuration scope to manage (default: project)",
     )
 
-    # Validate config
-    validate_config_parser = config_subparsers.add_parser(
-        ConfigCommands.VALIDATE.value, help="Validate configuration files"
+    # Direct navigation options (skip main menu)
+    nav_group = config_parser.add_argument_group("direct navigation")
+    nav_group.add_argument(
+        "--agents", action="store_true", help="Jump directly to agent management"
     )
-    validate_config_parser.add_argument(
-        "--config-file",
-        type=Path,
-        help="Specific config file to validate (default: all)",
+    nav_group.add_argument(
+        "--templates", action="store_true", help="Jump directly to template editing"
+    )
+    nav_group.add_argument(
+        "--behaviors",
+        action="store_true",
+        help="Jump directly to behavior file management",
     )
-    validate_config_parser.add_argument(
-        "--strict", action="store_true", help="Use strict validation rules"
+    nav_group.add_argument(
+        "--startup",
+        action="store_true",
+        help="Configure startup services and agents",
     )
-    validate_config_parser.add_argument(
-        "--fix",
+    nav_group.add_argument(
+        "--version-info",
         action="store_true",
-        help="Attempt to fix validation errors automatically",
+        help="Display version information and exit",
+    )
+
+    # Non-interactive options
+    noninteractive_group = config_parser.add_argument_group("non-interactive options")
+    noninteractive_group.add_argument(
+        "--list-agents", action="store_true", help="List all available agents and exit"
+    )
+    noninteractive_group.add_argument(
+        "--enable-agent",
+        type=str,
+        metavar="AGENT_NAME",
+        help="Enable a specific agent and exit",
+    )
+    noninteractive_group.add_argument(
+        "--disable-agent",
+        type=str,
+        metavar="AGENT_NAME",
+        help="Disable a specific agent and exit",
+    )
+    noninteractive_group.add_argument(
+        "--export-config",
+        type=str,
+        metavar="FILE",
+        help="Export current configuration to a file",
+    )
+    noninteractive_group.add_argument(
+        "--import-config",
+        type=str,
+        metavar="FILE",
+        help="Import configuration from a file",
     )
 
-    # View config
-    view_config_parser = config_subparsers.add_parser(
-        ConfigCommands.VIEW.value, help="View current configuration"
+    # Hook management options
+    hooks_group = config_parser.add_argument_group("hook management")
+    hooks_group.add_argument(
+        "--install-hooks",
+        action="store_true",
+        help="Install Claude MPM hooks for Claude Code integration",
     )
-    view_config_parser.add_argument(
-        "--section", help="Specific configuration section to view"
+    hooks_group.add_argument(
+        "--verify-hooks",
+        action="store_true",
+        help="Verify that Claude MPM hooks are properly installed",
     )
-    view_config_parser.add_argument(
-        "--format",
-        choices=["yaml", "json", "table"],
-        default="yaml",
-        help="Output format (default: yaml)",
+    hooks_group.add_argument(
+        "--uninstall-hooks",
+        action="store_true",
+        help="Uninstall Claude MPM hooks",
     )
-    view_config_parser.add_argument(
-        "--show-defaults", action="store_true", help="Include default values in output"
+    hooks_group.add_argument(
+        "--force",
+        action="store_true",
+        help="Force reinstallation of hooks even if they already exist",
     )
 
-    # Status config
-    status_config_parser = config_subparsers.add_parser(
-        ConfigCommands.STATUS.value, help="Show configuration status"
+    # Display options
+    display_group = config_parser.add_argument_group("display options")
+    display_group.add_argument(
+        "--no-colors",
+        action="store_true",
+        help="Disable colored output in the interface",
     )
-    status_config_parser.add_argument(
-        "--verbose", action="store_true", help="Show detailed status information"
+    display_group.add_argument(
+        "--compact", action="store_true", help="Use compact display mode"
     )
 
     return config_parser