claude-mpm 0.3.0__py3-none-any.whl

claude_mpm/services/framework_claude_md_generator/content_assembler.py

@@ -0,0 +1,151 @@
+"""
+Content assembly for framework CLAUDE.md templates.
+
+Assembles sections and applies template variable substitution.
+"""
+
+import hashlib
+from datetime import datetime
+from typing import Dict, List, Optional, Any
+from collections import OrderedDict
+
+
+class ContentAssembler:
+    """Assembles framework CLAUDE.md content from sections."""
+    
+    def __init__(self):
+        """Initialize content assembler."""
+        self.template_variables = {}
+    
+    def generate_content_hash(self) -> str:
+        """
+        Generate a content hash for integrity verification.
+        
+        Returns:
+            str: 16-character hash of content
+        """
+        timestamp = datetime.utcnow().isoformat()
+        hash_obj = hashlib.sha256(timestamp.encode())
+        return hash_obj.hexdigest()[:16]
+    
+    def assemble_content(self, 
+                        sections: OrderedDict,
+                        template_variables: Optional[Dict[str, str]] = None) -> str:
+        """
+        Assemble complete content from sections.
+        
+        Args:
+            sections: OrderedDict of section_name -> (generator_func, section_data)
+            template_variables: Variables to substitute in the template
+            
+        Returns:
+            str: Complete assembled content
+        """
+        # Store template variables
+        if template_variables:
+            self.template_variables = template_variables
+        
+        # Generate all sections
+        content_parts = []
+        for section_name, (generator_func, section_data) in sections.items():
+            section_content = generator_func(section_data)
+            content_parts.append(section_content)
+        
+        # Join all sections
+        full_content = '\n'.join(content_parts)
+        
+        # Apply template variable substitution
+        full_content = self.apply_template_variables(full_content)
+        
+        return full_content
+    
+    def apply_template_variables(self, content: str) -> str:
+        """
+        Apply template variable substitution to content.
+        
+        Args:
+            content: Content with template variables
+            
+        Returns:
+            str: Content with variables substituted
+        """
+        for var_name, var_value in self.template_variables.items():
+            placeholder = f"{{{{{var_name}}}}}"
+            content = content.replace(placeholder, var_value)
+        
+        return content
+    
+    def merge_sections(self, 
+                      base_sections: OrderedDict,
+                      custom_sections: Dict[str, tuple]) -> OrderedDict:
+        """
+        Merge custom sections with base sections.
+        
+        Args:
+            base_sections: Base section definitions
+            custom_sections: Custom sections to merge
+            
+        Returns:
+            OrderedDict: Merged sections
+        """
+        merged = OrderedDict(base_sections)
+        
+        for section_name, section_def in custom_sections.items():
+            merged[section_name] = section_def
+        
+        return merged
+    
+    def insert_section_after(self,
+                           sections: OrderedDict,
+                           new_section_name: str,
+                           new_section_def: tuple,
+                           after_section: str) -> OrderedDict:
+        """
+        Insert a new section after a specified section.
+        
+        Args:
+            sections: Current sections
+            new_section_name: Name of new section
+            new_section_def: Definition tuple for new section
+            after_section: Section to insert after
+            
+        Returns:
+            OrderedDict: Updated sections
+        """
+        if after_section not in sections:
+            # If target section doesn't exist, just append
+            sections[new_section_name] = new_section_def
+            return sections
+        
+        new_sections = OrderedDict()
+        for key, value in sections.items():
+            new_sections[key] = value
+            if key == after_section:
+                new_sections[new_section_name] = new_section_def
+        
+        return new_sections
+    
+    def create_metadata_dict(self, 
+                           version: str,
+                           framework_version: str,
+                           content_hash: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Create metadata dictionary for header generation.
+        
+        Args:
+            version: CLAUDE_MD_VERSION string
+            framework_version: Framework version
+            content_hash: Optional content hash
+            
+        Returns:
+            Dict: Metadata for header
+        """
+        timestamp = datetime.utcnow().isoformat()
+        
+        return {
+            'version': version,
+            'framework_version': framework_version,
+            'deployment_date': timestamp,
+            'last_updated': timestamp,
+            'content_hash': content_hash or self.generate_content_hash()
+        }

claude_mpm/services/framework_claude_md_generator/content_validator.py

@@ -0,0 +1,126 @@
+"""
+Content validation for framework CLAUDE.md templates.
+
+Validates generated content structure and completeness.
+"""
+
+import re
+from typing import Tuple, List, Set
+
+
+class ContentValidator:
+    """Validates framework CLAUDE.md content for completeness and correctness."""
+    
+    # Required sections that must be present
+    REQUIRED_SECTIONS = [
+        (r'CLAUDE_MD_VERSION:', 'Version metadata'),
+        (r'## 🤖 AI ASSISTANT ROLE DESIGNATION', 'Role designation section'),
+        (r'## A\) AGENTS', 'Agents section'),
+        (r'## B\) TODO AND TASK TOOLS', 'Todo/Task tools section'),
+        (r'## C\) CLAUDE-PM INIT', 'Claude-PM init section'),
+        (r'## 🚨 CORE ORCHESTRATION PRINCIPLES', 'Orchestration principles'),
+        (r'## 🔥🚨 CRITICAL: SUBPROCESS VALIDATION PROTOCOL', 'Subprocess validation'),
+        (r'## 🚨 CRITICAL DELEGATION CONSTRAINTS', 'Delegation constraints'),
+        (r'## 🚨 TROUBLESHOOTING', 'Troubleshooting section'),
+        (r'## Core Responsibilities', 'Core responsibilities'),
+    ]
+    
+    # Template variables that are allowed to remain unsubstituted for runtime
+    ALLOWED_RUNTIME_VARS = {
+        '{{DEPLOYMENT_ID}}',
+        '{{PLATFORM}}',
+        '{{PYTHON_CMD}}',
+        '{{PLATFORM_NOTES}}'
+    }
+    
+    def validate_content(self, content: str) -> Tuple[bool, List[str]]:
+        """
+        Validate that generated content has all required sections.
+        
+        Args:
+            content: Content to validate
+            
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        issues = []
+        
+        # Check for required sections
+        for pattern, section_name in self.REQUIRED_SECTIONS:
+            if not re.search(pattern, content):
+                issues.append(f"Missing required section: {section_name}")
+        
+        # Check for unsubstituted template variables
+        unsubstituted = re.findall(r'\{\{[^}]+\}\}', content)
+        unexpected_vars = [var for var in unsubstituted if var not in self.ALLOWED_RUNTIME_VARS]
+        if unexpected_vars:
+            issues.append(f"Unsubstituted template variables: {', '.join(set(unexpected_vars))}")
+        
+        # Validate version format - now accepts simple serial numbers
+        version_match = re.search(r'CLAUDE_MD_VERSION:\s*(\d+)(?:-(\d+))?', content)
+        if not version_match:
+            issues.append("Invalid or missing CLAUDE_MD_VERSION format")
+        
+        # Check for proper structure
+        if not content.strip():
+            issues.append("Content is empty")
+        
+        # Validate agent section completeness
+        if '## A) AGENTS' in content:
+            required_agents = [
+                'Documentation Agent',
+                'Ticketing Agent',
+                'Version Control Agent',
+                'QA Agent',
+                'Research Agent',
+                'Ops Agent',
+                'Security Agent',
+                'Engineer Agent',
+                'Data Engineer Agent'
+            ]
+            for agent in required_agents:
+                if agent not in content:
+                    issues.append(f"Missing core agent: {agent}")
+        
+        return len(issues) == 0, issues
+    
+    def validate_section_order(self, sections: List[str]) -> Tuple[bool, List[str]]:
+        """
+        Validate that sections are in the correct order.
+        
+        Args:
+            sections: List of section names in order
+            
+        Returns:
+            Tuple of (is_valid, list_of_issues)
+        """
+        expected_order = [
+            'header',
+            'role_designation',
+            'agents',
+            'todo_task_tools',
+            'claude_pm_init',
+            'orchestration_principles',
+            'subprocess_validation',
+            'delegation_constraints',
+            'environment_config',
+            'troubleshooting',
+            'core_responsibilities',
+            'footer'
+        ]
+        
+        issues = []
+        
+        # Check that all expected sections are present
+        missing = set(expected_order) - set(sections)
+        if missing:
+            issues.append(f"Missing sections: {', '.join(missing)}")
+        
+        # Check order (only for sections that exist in both lists)
+        common_sections = [s for s in sections if s in expected_order]
+        expected_common = [s for s in expected_order if s in sections]
+        
+        if common_sections != expected_common:
+            issues.append("Sections are not in the expected order")
+        
+        return len(issues) == 0, issues

claude_mpm/services/framework_claude_md_generator/deployment_manager.py

@@ -0,0 +1,137 @@
+"""
+Deployment management for framework CLAUDE.md templates.
+
+Handles deployment operations to parent directories.
+"""
+
+from pathlib import Path
+from typing import Tuple, Optional
+from datetime import datetime
+from .version_manager import VersionManager
+from .content_validator import ContentValidator
+
+# Import framework detection utilities
+from ...utils.framework_detection import is_framework_source_directory
+
+
+class DeploymentManager:
+    """Manages deployment of framework CLAUDE.md to parent directories."""
+    
+    def __init__(self, version_manager: VersionManager, validator: ContentValidator):
+        """
+        Initialize deployment manager.
+        
+        Args:
+            version_manager: Version management instance
+            validator: Content validator instance
+        """
+        self.version_manager = version_manager
+        self.validator = validator
+    
+    def deploy_to_parent(self, 
+                        content: str,
+                        parent_path: Path, 
+                        force: bool = False) -> Tuple[bool, str]:
+        """
+        Deploy generated content to a parent directory.
+        
+        Args:
+            content: Content to deploy
+            parent_path: Path to parent directory
+            force: Force deployment even if versions match
+            
+        Returns:
+            Tuple of (success, message)
+        """
+        # Check if we're in the framework source directory
+        is_framework, markers = is_framework_source_directory(parent_path)
+        if is_framework:
+            return True, f"Skipping deployment - detected framework source directory (markers: {', '.join(markers)})"
+        
+        # Use INSTRUCTIONS.md as primary, with CLAUDE.md as fallback
+        target_file = parent_path / "INSTRUCTIONS.md"
+        # TODO: Make this configurable via parameter
+        
+        # Validate content before deployment
+        is_valid, issues = self.validator.validate_content(content)
+        if not is_valid:
+            return False, f"Validation failed: {'; '.join(issues)}"
+        
+        # Check if file exists and compare versions
+        if target_file.exists() and not force:
+            with open(target_file, 'r') as f:
+                existing_content = f.read()
+                existing_fw_ver, _ = self.version_manager.parse_current_version(existing_content)
+                
+            if existing_fw_ver == self.version_manager.framework_version:
+                return True, f"Version {existing_fw_ver} already deployed"
+        
+        # Deploy
+        try:
+            # Ensure parent directory exists
+            parent_path.mkdir(parents=True, exist_ok=True)
+            
+            # Write content
+            with open(target_file, 'w') as f:
+                f.write(content)
+            
+            # Get version info for success message
+            fw_ver, serial = self.version_manager.parse_current_version(content)
+            version_str = f"{fw_ver}-{serial:03d}"
+            
+            return True, f"Successfully deployed version {version_str}"
+        except Exception as e:
+            return False, f"Deployment failed: {str(e)}"
+    
+    def check_deployment_needed(self, parent_path: Path) -> Tuple[bool, str]:
+        """
+        Check if deployment is needed for a parent directory.
+        
+        Args:
+            parent_path: Path to parent directory
+            
+        Returns:
+            Tuple of (needed, reason)
+        """
+        target_file = parent_path / "CLAUDE.md"
+        
+        if not target_file.exists():
+            return True, "CLAUDE.md does not exist"
+        
+        try:
+            with open(target_file, 'r') as f:
+                existing_content = f.read()
+                existing_fw_ver, _ = self.version_manager.parse_current_version(existing_content)
+            
+            if existing_fw_ver != self.version_manager.framework_version:
+                return True, f"Version mismatch: {existing_fw_ver} vs {self.version_manager.framework_version}"
+            
+            return False, "Already up to date"
+        except Exception as e:
+            return True, f"Error checking existing file: {str(e)}"
+    
+    def backup_existing(self, parent_path: Path) -> Optional[Path]:
+        """
+        Create a backup of existing CLAUDE.md before deployment.
+        
+        Args:
+            parent_path: Path to parent directory
+            
+        Returns:
+            Path to backup file if created, None otherwise
+        """
+        target_file = parent_path / "CLAUDE.md"
+        
+        if not target_file.exists():
+            return None
+        
+        # Create backup filename with timestamp
+        timestamp = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+        backup_file = parent_path / f"CLAUDE.md.backup.{timestamp}"
+        
+        try:
+            import shutil
+            shutil.copy2(target_file, backup_file)
+            return backup_file
+        except Exception:
+            return None

claude_mpm/services/framework_claude_md_generator/section_generators/__init__.py

@@ -0,0 +1,106 @@
+"""
+Section generators for framework CLAUDE.md template.
+
+This module provides base classes and registry for section generators.
+"""
+
+from typing import Dict, Any, Optional
+from abc import ABC, abstractmethod
+from datetime import datetime
+
+
+class BaseSectionGenerator(ABC):
+    """Base class for all section generators."""
+    
+    def __init__(self, framework_version: str):
+        """
+        Initialize section generator.
+        
+        Args:
+            framework_version: Current framework version
+        """
+        self.framework_version = framework_version
+    
+    @abstractmethod
+    def generate(self, data: Dict[str, Any]) -> str:
+        """
+        Generate section content.
+        
+        Args:
+            data: Section-specific data
+            
+        Returns:
+            str: Generated section content
+        """
+        pass
+    
+    def get_timestamp(self) -> str:
+        """Get current UTC timestamp."""
+        return datetime.utcnow().isoformat()
+
+
+class SectionGeneratorRegistry:
+    """Registry for section generators."""
+    
+    def __init__(self):
+        """Initialize registry."""
+        self._generators = {}
+    
+    def register(self, name: str, generator_class: type):
+        """
+        Register a section generator.
+        
+        Args:
+            name: Section name
+            generator_class: Generator class
+        """
+        self._generators[name] = generator_class
+    
+    def get(self, name: str) -> Optional[type]:
+        """
+        Get a section generator class.
+        
+        Args:
+            name: Section name
+            
+        Returns:
+            Generator class or None
+        """
+        return self._generators.get(name)
+    
+    def list_sections(self) -> list:
+        """Get list of registered section names."""
+        return list(self._generators.keys())
+
+
+# Global registry instance
+section_registry = SectionGeneratorRegistry()
+
+
+# Import and register all section generators
+from .header import HeaderGenerator
+from .role_designation import RoleDesignationGenerator
+from .agents import AgentsGenerator
+from .todo_task_tools import TodoTaskToolsGenerator
+from .claude_pm_init import ClaudePmInitGenerator
+from .orchestration_principles import OrchestrationPrinciplesGenerator
+from .subprocess_validation import SubprocessValidationGenerator
+from .delegation_constraints import DelegationConstraintsGenerator
+from .environment_config import EnvironmentConfigGenerator
+from .troubleshooting import TroubleshootingGenerator
+from .core_responsibilities import CoreResponsibilitiesGenerator
+from .footer import FooterGenerator
+
+# Register all generators
+section_registry.register('header', HeaderGenerator)
+section_registry.register('role_designation', RoleDesignationGenerator)
+section_registry.register('agents', AgentsGenerator)
+section_registry.register('todo_task_tools', TodoTaskToolsGenerator)
+section_registry.register('claude_pm_init', ClaudePmInitGenerator)
+section_registry.register('orchestration_principles', OrchestrationPrinciplesGenerator)
+section_registry.register('subprocess_validation', SubprocessValidationGenerator)
+section_registry.register('delegation_constraints', DelegationConstraintsGenerator)
+section_registry.register('environment_config', EnvironmentConfigGenerator)
+section_registry.register('troubleshooting', TroubleshootingGenerator)
+section_registry.register('core_responsibilities', CoreResponsibilitiesGenerator)
+section_registry.register('footer', FooterGenerator)