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

claude_mpm/utils/migration.py

@@ -0,0 +1,372 @@
+"""Migration utilities for transitioning to new directory structure.
+
+WHY: Phase 3 of 1M-486 requires migrating from old single-tier deployment
+     (~/.claude/agents/, ~/.claude/skills/) to new two-phase architecture:
+     - Cache: ~/.claude-mpm/cache/remote-agents/, ~/.claude-mpm/cache/skills/
+     - Deployment: .claude-mpm/agents/, .claude-mpm/skills/
+
+DESIGN DECISIONS:
+- Optional migration: Users can continue using old paths (fallback support)
+- User confirmation: Prevents accidental data movement
+- Non-destructive: Creates copies, doesn't delete originals immediately
+- Deprecation warnings: Guides users toward new structure
+
+MIGRATION PATH:
+1. Detect old locations (if they exist)
+2. Prompt user for confirmation
+3. Copy to new cache location (not deployment, as that's project-specific)
+4. Show deprecation warning with cleanup instructions
+5. Provide fallback support for unmigrated systems
+"""
+
+import logging
+import shutil
+from pathlib import Path
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class MigrationUtility:
+    """Handles migration from old to new directory structure.
+
+    Trade-offs:
+    - Safety: Non-destructive copies vs. automatic moves
+    - User experience: Manual confirmation vs. automatic migration
+    - Compatibility: Fallback support adds complexity but ensures smooth transition
+    """
+
+    def __init__(self):
+        """Initialize migration utility with old and new paths."""
+        self.old_agent_dir = Path.home() / ".claude" / "agents"
+        self.old_skill_dir = Path.home() / ".claude" / "skills"
+
+        self.new_agent_cache = Path.home() / ".claude-mpm" / "cache" / "remote-agents"
+        self.new_skill_cache = Path.home() / ".claude-mpm" / "cache" / "skills"
+
+    def detect_old_locations(self) -> Dict[str, bool]:
+        """Detect if old directory locations exist and contain files.
+
+        Returns:
+            Dictionary with 'agents' and 'skills' keys indicating presence
+        """
+        results = {
+            "agents_exists": False,
+            "agents_count": 0,
+            "skills_exists": False,
+            "skills_count": 0,
+        }
+
+        # Check agents
+        if self.old_agent_dir.exists():
+            agent_files = list(self.old_agent_dir.glob("*.md")) + list(
+                self.old_agent_dir.glob("*.json")
+            )
+            results["agents_exists"] = len(agent_files) > 0
+            results["agents_count"] = len(agent_files)
+
+        # Check skills
+        if self.old_skill_dir.exists():
+            skill_dirs = [
+                d
+                for d in self.old_skill_dir.iterdir()
+                if d.is_dir() and (d / "SKILL.md").exists()
+            ]
+            results["skills_exists"] = len(skill_dirs) > 0
+            results["skills_count"] = len(skill_dirs)
+
+        return results
+
+    def migrate_agents(
+        self, dry_run: bool = False, auto_confirm: bool = False
+    ) -> Dict[str, any]:
+        """Migrate agents from ~/.claude/agents/ to ~/.claude-mpm/cache/remote-agents/.
+
+        Args:
+            dry_run: Preview migration without making changes
+            auto_confirm: Skip confirmation prompt (use with caution)
+
+        Returns:
+            Dictionary with migration results:
+            {
+                "migrated_count": 5,
+                "migrated_files": ["engineer.md", ...],
+                "skipped_count": 2,
+                "errors": []
+            }
+        """
+        if not self.old_agent_dir.exists():
+            return {
+                "migrated_count": 0,
+                "migrated_files": [],
+                "skipped_count": 0,
+                "errors": [],
+                "message": "No old agent directory found",
+            }
+
+        # Find agent files
+        agent_files = list(self.old_agent_dir.glob("*.md")) + list(
+            self.old_agent_dir.glob("*.json")
+        )
+
+        if not agent_files:
+            return {
+                "migrated_count": 0,
+                "migrated_files": [],
+                "skipped_count": 0,
+                "errors": [],
+                "message": "No agent files found in old directory",
+            }
+
+        # Dry run mode
+        if dry_run:
+            return {
+                "migrated_count": len(agent_files),
+                "migrated_files": [f.name for f in agent_files],
+                "skipped_count": 0,
+                "errors": [],
+                "dry_run": True,
+                "message": f"Would migrate {len(agent_files)} agent files",
+            }
+
+        # Confirmation prompt (unless auto_confirm)
+        if not auto_confirm:
+            logger.info(
+                f"Migration will copy {len(agent_files)} agents from:\n"
+                f"  {self.old_agent_dir}\n"
+                f"  → {self.new_agent_cache}"
+            )
+            # In CLI context, this would show interactive prompt
+            # For now, we assume confirmation through function parameter
+
+        # Create cache directory
+        try:
+            self.new_agent_cache.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            return {
+                "migrated_count": 0,
+                "migrated_files": [],
+                "skipped_count": 0,
+                "errors": [f"Permission denied creating cache directory: {e}"],
+            }
+
+        # Copy files
+        results = {
+            "migrated_count": 0,
+            "migrated_files": [],
+            "skipped_count": 0,
+            "errors": [],
+        }
+
+        for agent_file in agent_files:
+            target_file = self.new_agent_cache / agent_file.name
+
+            try:
+                # Skip if already exists and is identical
+                if target_file.exists():
+                    if self._files_identical(agent_file, target_file):
+                        results["skipped_count"] += 1
+                        logger.debug(f"Skipped (identical): {agent_file.name}")
+                        continue
+
+                # Copy to cache
+                shutil.copy2(agent_file, target_file)
+                results["migrated_count"] += 1
+                results["migrated_files"].append(agent_file.name)
+                logger.info(f"Migrated: {agent_file.name}")
+
+            except Exception as e:
+                error_msg = f"Failed to migrate {agent_file.name}: {e}"
+                results["errors"].append(error_msg)
+                logger.error(error_msg)
+
+        results["message"] = (
+            f"Migrated {results['migrated_count']} agents to cache. "
+            f"Old directory: {self.old_agent_dir}"
+        )
+
+        return results
+
+    def migrate_skills(
+        self, dry_run: bool = False, auto_confirm: bool = False
+    ) -> Dict[str, any]:
+        """Migrate skills from ~/.claude/skills/ to ~/.claude-mpm/cache/skills/.
+
+        Args:
+            dry_run: Preview migration without making changes
+            auto_confirm: Skip confirmation prompt
+
+        Returns:
+            Dictionary with migration results
+        """
+        if not self.old_skill_dir.exists():
+            return {
+                "migrated_count": 0,
+                "migrated_skills": [],
+                "skipped_count": 0,
+                "errors": [],
+                "message": "No old skill directory found",
+            }
+
+        # Find skill directories
+        skill_dirs = [
+            d
+            for d in self.old_skill_dir.iterdir()
+            if d.is_dir() and (d / "SKILL.md").exists()
+        ]
+
+        if not skill_dirs:
+            return {
+                "migrated_count": 0,
+                "migrated_skills": [],
+                "skipped_count": 0,
+                "errors": [],
+                "message": "No skill directories found",
+            }
+
+        # Dry run mode
+        if dry_run:
+            return {
+                "migrated_count": len(skill_dirs),
+                "migrated_skills": [d.name for d in skill_dirs],
+                "skipped_count": 0,
+                "errors": [],
+                "dry_run": True,
+                "message": f"Would migrate {len(skill_dirs)} skill directories",
+            }
+
+        # Create cache directory
+        try:
+            self.new_skill_cache.mkdir(parents=True, exist_ok=True)
+        except PermissionError as e:
+            return {
+                "migrated_count": 0,
+                "migrated_skills": [],
+                "skipped_count": 0,
+                "errors": [f"Permission denied creating cache directory: {e}"],
+            }
+
+        # Copy skill directories
+        results = {
+            "migrated_count": 0,
+            "migrated_skills": [],
+            "skipped_count": 0,
+            "errors": [],
+        }
+
+        for skill_dir in skill_dirs:
+            target_dir = self.new_skill_cache / skill_dir.name
+
+            try:
+                # Skip if already exists
+                if target_dir.exists():
+                    results["skipped_count"] += 1
+                    logger.debug(f"Skipped (exists): {skill_dir.name}")
+                    continue
+
+                # Copy entire skill directory
+                shutil.copytree(skill_dir, target_dir)
+                results["migrated_count"] += 1
+                results["migrated_skills"].append(skill_dir.name)
+                logger.info(f"Migrated: {skill_dir.name}")
+
+            except Exception as e:
+                error_msg = f"Failed to migrate {skill_dir.name}: {e}"
+                results["errors"].append(error_msg)
+                logger.error(error_msg)
+
+        results["message"] = (
+            f"Migrated {results['migrated_count']} skills to cache. "
+            f"Old directory: {self.old_skill_dir}"
+        )
+
+        return results
+
+    def migrate_all(
+        self, dry_run: bool = False, auto_confirm: bool = False
+    ) -> Dict[str, any]:
+        """Migrate both agents and skills.
+
+        Args:
+            dry_run: Preview migration without making changes
+            auto_confirm: Skip confirmation prompts
+
+        Returns:
+            Combined migration results for agents and skills
+        """
+        agent_results = self.migrate_agents(dry_run=dry_run, auto_confirm=auto_confirm)
+        skill_results = self.migrate_skills(dry_run=dry_run, auto_confirm=auto_confirm)
+
+        return {
+            "agents": agent_results,
+            "skills": skill_results,
+            "total_migrated": agent_results["migrated_count"]
+            + skill_results["migrated_count"],
+            "dry_run": dry_run,
+        }
+
+    def show_deprecation_warning(self) -> str:
+        """Generate deprecation warning message for old paths.
+
+        Returns:
+            Formatted warning message for display to user
+        """
+        detection = self.detect_old_locations()
+
+        if not detection["agents_exists"] and not detection["skills_exists"]:
+            return ""
+
+        warning = "\n⚠️  DEPRECATION WARNING ⚠️\n\n"
+        warning += "Old directory structure detected:\n\n"
+
+        if detection["agents_exists"]:
+            warning += f"  • {self.old_agent_dir}\n"
+            warning += f"    ({detection['agents_count']} agent files)\n"
+
+        if detection["skills_exists"]:
+            warning += f"  • {self.old_skill_dir}\n"
+            warning += f"    ({detection['skills_count']} skill directories)\n"
+
+        warning += "\nThe deployment architecture has changed:\n"
+        warning += "  OLD: ~/.claude/agents/ (single-tier, global)\n"
+        warning += "  NEW: ~/.claude-mpm/cache/remote-agents/ → .claude-mpm/agents/ (two-phase, per-project)\n\n"
+
+        warning += "To migrate:\n"
+        warning += "  claude-mpm migrate\n\n"
+
+        warning += "Or to continue using old paths (not recommended):\n"
+        warning += "  # Fallback support is enabled automatically\n\n"
+
+        return warning
+
+    def _files_identical(self, file1: Path, file2: Path) -> bool:
+        """Check if two files have identical content.
+
+        Args:
+            file1: First file path
+            file2: Second file path
+
+        Returns:
+            True if files are byte-for-byte identical
+        """
+        try:
+            return file1.read_bytes() == file2.read_bytes()
+        except Exception:
+            return False
+
+    def get_fallback_paths(self) -> Dict[str, Optional[Path]]:
+        """Get fallback paths for old directory structure.
+
+        Used when migration hasn't been performed and old paths still exist.
+
+        Returns:
+            Dictionary with fallback paths:
+            {
+                "agent_dir": Path to old agents (or None),
+                "skill_dir": Path to old skills (or None)
+            }
+        """
+        return {
+            "agent_dir": self.old_agent_dir if self.old_agent_dir.exists() else None,
+            "skill_dir": self.old_skill_dir if self.old_skill_dir.exists() else None,
+        }

claude_mpm/utils/progress.py

@@ -270,8 +270,12 @@ class ProgressBar:
             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{output}")
+        sys.stdout.write(f"\r{padded_output}")
         sys.stdout.flush()
 
     def finish(self, message: str = "Complete") -> None:

{claude_mpm-5.0.2.dist-info → claude_mpm-5.1.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-mpm
-Version: 5.0.2
+Version: 5.1.9
 Summary: Claude Multi-Agent Project Manager - Orchestrate Claude with agent delegation and ticket tracking
 Author-email: Bob Matsuoka <bob@matsuoka.com>
 Maintainer: Claude MPM Team
@@ -13,12 +13,10 @@ Keywords: claude,orchestration,multi-agent,ticket-management
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ai-trackdown-pytools>=1.4.0
@@ -48,7 +46,6 @@ Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: pyee>=13.0.0
-Requires-Dist: importlib-resources>=5.0; python_version < "3.9"
 Requires-Dist: pathspec>=0.11.0
 Requires-Dist: kuzu-memory>=1.1.5
 Provides-Extra: mcp
@@ -66,6 +63,12 @@ Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
 Requires-Dist: types-requests>=2.25.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Provides-Extra: eval
+Requires-Dist: deepeval>=1.0.0; extra == "eval"
+Requires-Dist: pytest>=7.4.0; extra == "eval"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "eval"
+Requires-Dist: pytest-timeout>=2.1.0; extra == "eval"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.2.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
@@ -121,7 +124,6 @@ Requires-Dist: prometheus-client>=0.19.0; extra == "agents"
 Requires-Dist: psycopg2-binary>=2.9.0; extra == "agents"
 Requires-Dist: pyarrow>=14.0.0; extra == "agents"
 Requires-Dist: pydantic>=2.6.0; extra == "agents"
-Requires-Dist: pydoc-markdown>=4.8.0; extra == "agents"
 Requires-Dist: pydriller>=2.5.0; extra == "agents"
 Requires-Dist: pygments>=2.17.0; extra == "agents"
 Requires-Dist: pyjwt>=2.8.0; extra == "agents"
@@ -302,7 +304,7 @@ See [docs/features/hierarchical-base-agents.md](docs/features/hierarchical-base-
 
 **Before installing Claude MPM**, ensure you have:
 
-1. **Python 3.8+** (3.11+ recommended)
+1. **Python 3.11+** (required for kuzu-memory dependency)
 2. **Claude Code CLI v1.0.92+** (required!)
 
 ```bash
@@ -439,6 +441,65 @@ claude-mpm verify
 
 **That's it!** See [docs/user/getting-started.md](docs/user/getting-started.md) for immediate usage.
 
+## Cache Management
+
+Claude MPM maintains a local cache of agent templates at `~/.claude-mpm/cache/remote-agents/`.
+
+### Cache Structure
+
+```
+~/.claude-mpm/cache/remote-agents/
+└── bobmatnyc/
+    └── claude-mpm-agents/
+        ├── .git/              # Git repository
+        ├── agents/            # 45+ agent templates
+        └── docs/
+```
+
+### Git Workflow (Optional)
+
+If your cache is a git repository, you can manage agents with git operations:
+
+```bash
+# Check cache status
+claude-mpm agents cache-status
+
+# Pull latest agents
+claude-mpm agents cache-pull
+
+# Commit local changes
+claude-mpm agents cache-commit --message "feat: update agents"
+
+# Push changes
+claude-mpm agents cache-push
+
+# Full sync workflow
+claude-mpm agents cache-sync
+```
+
+**Or use Makefile targets:**
+
+```bash
+make agents-cache-status   # Show git status
+make agents-cache-pull     # Pull latest
+make agents-cache-sync     # Full sync (pull + commit + push)
+make deploy-agents         # Deploy with auto-pull
+```
+
+### HTTP Sync Fallback
+
+If cache is not a git repository, Claude MPM automatically falls back to HTTP sync with GitHub API.
+
+### Migration from Legacy Cache
+
+If you have an old `cache/agents/` directory, run the migration script:
+
+```bash
+python scripts/migrate_cache_to_remote_agents.py
+```
+
+**See also:** [docs/CACHE_MANAGEMENT.md](docs/CACHE_MANAGEMENT.md) for comprehensive cache management guide.
+
 ## Quick Usage
 
 ```bash