claude-mpm 3.4.27__py3-none-any.whl → 3.5.0__py3-none-any.whl

claude_mpm/services/parent_directory_manager/deduplication_manager.py

@@ -1,279 +0,0 @@
-#!/usr/bin/env python3
-"""
-Deduplication Manager - Handles INSTRUCTIONS.md/CLAUDE.md file deduplication in parent directory hierarchy
-================================================================================
-
-This module manages the deduplication of INSTRUCTIONS.md (and legacy CLAUDE.md) files 
-to prevent duplicate context loading in Claude Code.
-
-Business Logic:
-- Walk up the directory tree to find all INSTRUCTIONS.md and CLAUDE.md files
-- Identify framework deployment templates vs project files
-- Keep only the rootmost framework template
-- Preserve all project-specific INSTRUCTIONS.md/CLAUDE.md files
-"""
-
-import os
-from pathlib import Path
-from typing import List, Tuple, Optional, Dict, Any
-from datetime import datetime
-import logging
-
-
-class DeduplicationManager:
-    """Manages deduplication of INSTRUCTIONS.md/CLAUDE.md files in parent directories."""
-
-    def __init__(self, logger: Optional[logging.Logger] = None):
-        """
-        Initialize the Deduplication Manager.
-
-        Args:
-            logger: Logger instance to use
-        """
-        self.logger = logger or logging.getLogger(__name__)
-
-    async def deduplicate_claude_md_files(
-        self,
-        is_framework_template_func,
-        extract_version_func,
-        compare_versions_func,
-        create_backup_func
-    ) -> List[Tuple[Path, str]]:
-        """
-        Deduplicate INSTRUCTIONS.md/CLAUDE.md files in parent directory hierarchy.
-        
-        BUSINESS LOGIC:
-        1. Walk up the directory tree from current working directory to root
-        2. Find ALL INSTRUCTIONS.md and CLAUDE.md files in this parent hierarchy
-        3. Identify which files are framework deployment templates vs project files
-           - Framework templates have title "# Claude PM Framework Configuration - Deployment"
-           - Project files (like orchestration test projects) are preserved
-        4. Among framework templates, find the one with the newest version
-        5. Keep ONLY the rootmost (highest in hierarchy) framework template
-        6. Update the rootmost template to the newest version if needed
-        7. Backup and remove all other framework templates
-        8. Never touch project CLAUDE.md files
-        
-        RATIONALE:
-        - Claude Code loads ALL CLAUDE.md files it finds in the directory tree
-        - Multiple framework templates cause duplicated context
-        - Only one framework template should exist at the rootmost location
-        - Project-specific CLAUDE.md files serve different purposes and must be preserved
-        
-        Args:
-            is_framework_template_func: Function to check if content is framework template
-            extract_version_func: Function to extract version from content
-            compare_versions_func: Function to compare two version strings
-            create_backup_func: Function to create backup of a file
-        
-        Returns:
-            List of tuples (original_path, action_taken) for logging
-        """
-        deduplication_actions = []
-        
-        try:
-            self.logger.info("🔍 Starting INSTRUCTIONS.md/CLAUDE.md deduplication scan...")
-            
-            # STEP 1: Walk up the directory tree from current directory to root
-            current_path = Path.cwd()
-            claude_md_files = []
-            
-            # Collect ALL INSTRUCTIONS.md and CLAUDE.md files found while walking up parent directories
-            while current_path != current_path.parent:  # Stop at root
-                # Check for INSTRUCTIONS.md first
-                instructions_path = current_path / "INSTRUCTIONS.md"
-                if instructions_path.exists() and instructions_path.is_file():
-                    claude_md_files.append(instructions_path)
-                    self.logger.debug(f"Found INSTRUCTIONS.md at: {instructions_path}")
-                else:
-                    # Check for legacy CLAUDE.md
-                    claude_md_path = current_path / "CLAUDE.md"
-                    if claude_md_path.exists() and claude_md_path.is_file():
-                        claude_md_files.append(claude_md_path)
-                        self.logger.debug(f"Found CLAUDE.md at: {claude_md_path}")
-                current_path = current_path.parent
-            
-            # Check root directory as well
-            root_instructions = current_path / "INSTRUCTIONS.md"
-            if root_instructions.exists() and root_instructions.is_file():
-                claude_md_files.append(root_instructions)
-                self.logger.debug(f"Found INSTRUCTIONS.md at root: {root_instructions}")
-            else:
-                # Check for legacy CLAUDE.md at root
-                root_claude_md = current_path / "CLAUDE.md"
-                if root_claude_md.exists() and root_claude_md.is_file():
-                    claude_md_files.append(root_claude_md)
-                    self.logger.debug(f"Found CLAUDE.md at root: {root_claude_md}")
-            
-            # If we found 0 or 1 files, there's nothing to deduplicate
-            if len(claude_md_files) <= 1:
-                self.logger.info("✅ No duplicate INSTRUCTIONS.md/CLAUDE.md files found in parent hierarchy")
-                return deduplication_actions
-            
-            # STEP 2: Sort by path depth (rootmost first)
-            claude_md_files.sort(key=lambda p: len(p.parts))
-            
-            self.logger.info(f"📊 Found {len(claude_md_files)} INSTRUCTIONS.md/CLAUDE.md files in parent hierarchy")
-            
-            # STEP 3: First pass - analyze all files to categorize and find newest version
-            framework_templates = []
-            newest_version = None
-            newest_content = None
-            
-            for file_path in claude_md_files:
-                try:
-                    content = file_path.read_text()
-                    # Check if this is a framework deployment template
-                    is_framework_template = is_framework_template_func(content)
-                    
-                    if is_framework_template:
-                        # Extract version from CLAUDE_MD_VERSION metadata
-                        version = extract_version_func(content)
-                        framework_templates.append((file_path, content, version))
-                        
-                        # Track the newest version we've seen
-                        if version and (newest_version is None or compare_versions_func(version, newest_version) > 0):
-                            newest_version = version
-                            newest_content = content
-                            self.logger.info(f"📋 Found newer version {version} at: {file_path}")
-                except Exception as e:
-                    self.logger.error(f"Failed to analyze {file_path}: {e}")
-            
-            # STEP 4: Second pass - process files based on our analysis
-            for idx, file_path in enumerate(claude_md_files):
-                try:
-                    content = file_path.read_text()
-                    is_framework_template = is_framework_template_func(content)
-                    
-                    if idx == 0:
-                        # This is the ROOTMOST file
-                        if is_framework_template:
-                            current_version = extract_version_func(content)
-                            
-                            # Check if we found a newer version elsewhere that we should update to
-                            if newest_version and current_version and compare_versions_func(newest_version, current_version) > 0:
-                                # We found a newer version in a subdirectory - update the rootmost file
-                                
-                                # First backup the current rootmost file
-                                backup_path = await create_backup_func(file_path)
-                                if backup_path:
-                                    self.logger.info(f"📁 Backed up current rootmost file before update: {backup_path}")
-                                
-                                # Update with the newest content we found
-                                file_path.write_text(newest_content)
-                                self.logger.info(f"⬆️ Updated rootmost template from {current_version} to {newest_version}")
-                                deduplication_actions.append((file_path, f"updated from {current_version} to {newest_version}"))
-                            else:
-                                # Rootmost file already has the newest version (or versions are equal)
-                                self.logger.info(f"✅ Keeping primary framework template at: {file_path} (version {current_version})")
-                                deduplication_actions.append((file_path, "kept as primary"))
-                        else:
-                            # Rootmost file is NOT a framework template - this is unusual but we preserve it
-                            self.logger.info(f"⚠️ File at {file_path} is not a framework template - skipping")
-                            deduplication_actions.append((file_path, "skipped - not framework template"))
-                    else:
-                        # This is NOT the rootmost file
-                        if is_framework_template:
-                            # This is a REDUNDANT framework template that must be removed
-                            
-                            # Generate backup filename with timestamp
-                            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-                            backup_name = f"CLAUDE.md.backup_{timestamp}"
-                            backup_path = file_path.parent / backup_name
-                            
-                            # Handle duplicate timestamps (rare but possible)
-                            counter = 1
-                            while backup_path.exists():
-                                backup_name = f"CLAUDE.md.backup_{timestamp}_{counter:02d}"
-                                backup_path = file_path.parent / backup_name
-                                counter += 1
-                            
-                            # Rename the duplicate to backup
-                            file_path.rename(backup_path)
-                            self.logger.warning(f"📦 Backed up duplicate framework template: {file_path} → {backup_path}")
-                            deduplication_actions.append((file_path, f"backed up to {backup_path.name}"))
-                        else:
-                            # This is a PROJECT-SPECIFIC CLAUDE.md file - NEVER REMOVE THESE
-                            self.logger.info(f"🛡️ Preserving non-framework file at: {file_path}")
-                            deduplication_actions.append((file_path, "preserved - not framework template"))
-                            
-                except Exception as file_error:
-                    self.logger.error(f"Failed to process file {file_path}: {file_error}")
-                    deduplication_actions.append((file_path, f"error: {str(file_error)}"))
-            
-            # Log summary
-            backed_up_count = sum(1 for _, action in deduplication_actions if "backed up" in action)
-            if backed_up_count > 0:
-                self.logger.info(f"✅ Deduplication complete: {backed_up_count} duplicate framework templates backed up")
-            else:
-                self.logger.info("✅ Deduplication complete: No framework template duplicates needed backing up")
-                
-        except Exception as e:
-            self.logger.error(f"Failed during CLAUDE.md deduplication: {e}")
-            
-        return deduplication_actions
-
-    async def deduplicate_parent_claude_md(
-        self,
-        is_framework_template_func,
-        extract_version_func,
-        compare_versions_func,
-        create_backup_func
-    ) -> Dict[str, Any]:
-        """
-        Public method to manually trigger CLAUDE.md deduplication in parent hierarchy.
-        
-        Args:
-            is_framework_template_func: Function to check if content is framework template
-            extract_version_func: Function to extract version from content
-            compare_versions_func: Function to compare two version strings
-            create_backup_func: Function to create backup of a file
-        
-        Returns:
-            Dictionary with deduplication results
-        """
-        try:
-            self.logger.info("🔧 Manual CLAUDE.md deduplication requested")
-            
-            # Run deduplication
-            actions = await self.deduplicate_claude_md_files(
-                is_framework_template_func,
-                extract_version_func,
-                compare_versions_func,
-                create_backup_func
-            )
-            
-            # Build result summary
-            result = {
-                "success": True,
-                "timestamp": datetime.now().isoformat(),
-                "actions_taken": len(actions),
-                "details": []
-            }
-            
-            for file_path, action in actions:
-                result["details"].append({
-                    "file": str(file_path),
-                    "action": action
-                })
-            
-            # Count different action types
-            action_summary = {
-                "kept_primary": sum(1 for _, a in actions if "kept as primary" in a),
-                "backed_up": sum(1 for _, a in actions if "backed up" in a),
-                "preserved": sum(1 for _, a in actions if "preserved" in a),
-                "skipped": sum(1 for _, a in actions if "skipped" in a),
-                "errors": sum(1 for _, a in actions if "error:" in a)
-            }
-            
-            result["summary"] = action_summary
-            
-            return result
-            
-        except Exception as e:
-            self.logger.error(f"Failed to run manual deduplication: {e}")
-            return {
-                "success": False,
-                "error": str(e),
-                "timestamp": datetime.now().isoformat()
-            }

claude_mpm/services/parent_directory_manager/framework_protector.py

@@ -1,143 +0,0 @@
-"""Framework protection module for critical framework files.
-
-This module provides the FrameworkProtector class which ensures critical
-framework files like framework/INSTRUCTIONS.md (legacy: framework/CLAUDE.md) 
-are protected from accidental deletion and maintain proper permissions.
-"""
-
-import os
-from pathlib import Path
-from typing import Optional
-import logging
-
-
-class FrameworkProtector:
-    """Protects critical framework files from deletion and corruption."""
-    
-    def __init__(self, framework_path: Path, logger: Optional[logging.Logger] = None):
-        """Initialize the FrameworkProtector.
-        
-        Args:
-            framework_path: Path to the framework directory
-            logger: Optional logger instance for logging protection activities
-        """
-        self.framework_path = framework_path
-        self.logger = logger or logging.getLogger(__name__)
-        
-    def protect_framework_template(self, framework_template_path: Path) -> None:
-        """Ensure framework template is protected from deletion.
-        
-        This method verifies that the framework template exists, is the correct
-        file, and has proper read permissions. This is critical to prevent
-        accidental deletion of the master framework template.
-        
-        Args:
-            framework_template_path: Path to the framework template file
-        """
-        try:
-            # Verify the file exists
-            if not framework_template_path.exists():
-                self.logger.warning(
-                    f"Framework template not found at {framework_template_path}"
-                )
-                return
-                
-            # Verify this is actually the framework template
-            # Check that the filename is INSTRUCTIONS.md or CLAUDE.md (legacy) and path contains "framework"
-            if (framework_template_path.name not in ["INSTRUCTIONS.md", "CLAUDE.md"] or 
-                "framework" not in str(framework_template_path)):
-                self.logger.debug(
-                    f"Path {framework_template_path} does not appear to be "
-                    "the framework template"
-                )
-                return
-                
-            # Ensure file has proper permissions (readable)
-            try:
-                # Get current permissions
-                current_mode = framework_template_path.stat().st_mode
-                
-                # Ensure owner can read (add read permission if needed)
-                if not (current_mode & 0o400):
-                    new_mode = current_mode | 0o400  # Add owner read
-                    os.chmod(framework_template_path, new_mode)
-                    self.logger.info(
-                        f"Added read permission to framework template at "
-                        f"{framework_template_path}"
-                    )
-                    
-                # Log successful protection
-                self.logger.debug(
-                    f"Framework template protected at {framework_template_path}"
-                )
-                
-            except Exception as e:
-                self.logger.error(
-                    f"Failed to set permissions on framework template: {e}"
-                )
-                
-        except Exception as e:
-            self.logger.error(
-                f"Error protecting framework template at "
-                f"{framework_template_path}: {e}"
-            )
-            
-    def validate_framework_template_integrity(self, content: str) -> bool:
-        """Validate that framework template has proper structure and metadata.
-        
-        This method checks that the template contains essential metadata
-        and structure required for proper framework operation.
-        
-        Args:
-            content: The content of the framework template to validate
-            
-        Returns:
-            bool: True if template is valid, False otherwise
-        """
-        try:
-            # Check for essential metadata markers
-            required_markers = [
-                "CLAUDE_MD_VERSION:",
-                "FRAMEWORK_VERSION:",
-                "AI ASSISTANT ROLE DESIGNATION",
-                "AGENTS",
-                "TODO AND TASK TOOLS"
-            ]
-            
-            # Check each required marker exists in content
-            for marker in required_markers:
-                if marker not in content:
-                    self.logger.warning(
-                        f"Framework template missing required marker: {marker}"
-                    )
-                    return False
-                    
-            # Check for handlebars variables that should be present
-            required_variables = [
-                "{{DEPLOYMENT_ID}}",
-                "{{PLATFORM_NOTES}}"
-            ]
-            
-            for variable in required_variables:
-                if variable not in content:
-                    self.logger.warning(
-                        f"Framework template missing required variable: {variable}"
-                    )
-                    return False
-                    
-            # Validate minimum content length (templates should be substantial)
-            min_content_length = 1000  # Reasonable minimum for a valid template
-            if len(content) < min_content_length:
-                self.logger.warning(
-                    f"Framework template content too short: {len(content)} chars "
-                    f"(minimum: {min_content_length})"
-                )
-                return False
-                
-            # If all checks pass, template is valid
-            self.logger.debug("Framework template integrity validated successfully")
-            return True
-            
-        except Exception as e:
-            self.logger.error(f"Error validating framework template integrity: {e}")
-            return False

claude_mpm/services/parent_directory_manager/operations.py

@@ -1,186 +0,0 @@
-#!/usr/bin/env python3
-"""
-Parent Directory Operations - Handles directory context detection and registration
-================================================================================
-
-This module manages parent directory context detection, auto-registration,
-and template variable generation.
-"""
-
-import os
-from pathlib import Path
-from typing import List, Dict, Any, Optional
-from datetime import datetime
-from enum import Enum
-import logging
-
-
-class ParentDirectoryContext(Enum):
-    """Context types for parent directory management."""
-    DEPLOYMENT_ROOT = "deployment_root"
-    PROJECT_COLLECTION = "project_collection"
-    WORKSPACE_ROOT = "workspace_root"
-    USER_HOME = "user_home"
-    CUSTOM = "custom"
-
-
-class ParentDirectoryOperations:
-    """Manages parent directory detection and operations."""
-
-    def __init__(self, logger: Optional[logging.Logger] = None):
-        """
-        Initialize the Parent Directory Operations.
-
-        Args:
-            logger: Logger instance to use
-        """
-        self.logger = logger or logging.getLogger(__name__)
-
-    async def detect_parent_directory_context(
-        self, target_directory: Path
-    ) -> ParentDirectoryContext:
-        """
-        Detect the context of a parent directory.
-
-        Args:
-            target_directory: Directory to analyze
-
-        Returns:
-            ParentDirectoryContext enum value
-        """
-        try:
-            # Check if it's the user home directory
-            if target_directory == Path.home():
-                return ParentDirectoryContext.USER_HOME
-
-            # Check if it contains a deployment (has claude-multiagent-pm subdirectory)
-            if (target_directory / "claude-multiagent-pm").exists():
-                return ParentDirectoryContext.DEPLOYMENT_ROOT
-
-            # Check if it contains multiple projects
-            subdirs = [d for d in target_directory.iterdir() if d.is_dir()]
-            project_indicators = [".git", "package.json", "pyproject.toml", "Cargo.toml"]
-
-            project_count = 0
-            for subdir in subdirs:
-                if any((subdir / indicator).exists() for indicator in project_indicators):
-                    project_count += 1
-
-            if project_count > 1:
-                return ParentDirectoryContext.PROJECT_COLLECTION
-
-            # Check if it's a workspace root
-            workspace_indicators = [".vscode", ".idea", "workspace.json"]
-            if any((target_directory / indicator).exists() for indicator in workspace_indicators):
-                return ParentDirectoryContext.WORKSPACE_ROOT
-
-            # Default to custom
-            return ParentDirectoryContext.CUSTOM
-
-        except Exception as e:
-            self.logger.error(
-                f"Failed to detect parent directory context for {target_directory}: {e}"
-            )
-            return ParentDirectoryContext.CUSTOM
-
-    async def auto_register_parent_directories(
-        self,
-        search_paths: List[Path],
-        template_id: str,
-        register_func,
-        get_default_variables_func
-    ) -> List[Path]:
-        """
-        Automatically register parent directories that should be managed.
-
-        Args:
-            search_paths: Paths to search for parent directories
-            template_id: Template to use for auto-registration
-            register_func: Function to register directory
-            get_default_variables_func: Function to get default template variables
-
-        Returns:
-            List of registered directories
-        """
-        try:
-            registered_directories = []
-
-            for search_path in search_paths:
-                if not search_path.exists() or not search_path.is_dir():
-                    continue
-
-                # Check if this directory should be managed
-                context = await self.detect_parent_directory_context(search_path)
-
-                # Skip user home directory unless explicitly configured
-                if context == ParentDirectoryContext.USER_HOME:
-                    continue
-
-                # Auto-register if it looks like a deployment root or project collection
-                if context in [
-                    ParentDirectoryContext.DEPLOYMENT_ROOT,
-                    ParentDirectoryContext.PROJECT_COLLECTION,
-                ]:
-                    success = await register_func(
-                        search_path,
-                        context,
-                        template_id,
-                        get_default_variables_func(search_path, context),
-                    )
-
-                    if success:
-                        registered_directories.append(search_path)
-                        self.logger.info(f"Auto-registered parent directory: {search_path}")
-
-            return registered_directories
-
-        except Exception as e:
-            self.logger.error(f"Failed to auto-register parent directories: {e}")
-            return []
-
-    def get_default_template_variables(
-        self,
-        target_directory: Path,
-        context: ParentDirectoryContext,
-        deployment_context: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
-        """Get default template variables for a directory."""
-        variables = {
-            "DIRECTORY_PATH": str(target_directory),
-            "DIRECTORY_NAME": target_directory.name,
-            "CONTEXT": context.value,
-            "TIMESTAMP": datetime.now().isoformat(),
-            "PLATFORM": os.name,
-        }
-
-        # Add deployment-specific variables if available
-        if deployment_context:
-            variables.update(
-                {
-                    "DEPLOYMENT_TYPE": deployment_context.get("strategy", "unknown"),
-                    "DEPLOYMENT_PLATFORM": deployment_context.get("config", {}).get(
-                        "platform", "unknown"
-                    ),
-                }
-            )
-
-        return variables
-
-    def get_platform_notes(self) -> str:
-        """
-        Get platform-specific notes for the framework template.
-        
-        Returns:
-            Platform-specific notes string
-        """
-        import platform
-        system = platform.system().lower()
-        
-        if system == 'windows':
-            return "Windows users may need to use 'python' instead of 'python3' depending on installation."
-        elif system == 'darwin':
-            return "macOS users should ensure python3 is installed via Homebrew or official Python installer."
-        elif system == 'linux':
-            return "Linux users may need to install python3 via their package manager if not present."
-        else:
-            return f"Platform-specific configuration may be required for {system}."