claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

claude_mpm/core/framework/loaders/file_loader.py

@@ -0,0 +1,176 @@
+"""File loading utilities for the framework."""
+
+import logging
+import re
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class FileLoader:
+    """Handles file I/O operations for the framework."""
+
+    def __init__(self):
+        """Initialize the file loader."""
+        self.logger = get_logger("file_loader")
+        self.framework_version: Optional[str] = None
+        self.framework_last_modified: Optional[str] = None
+
+    def try_load_file(self, file_path: Path, file_type: str) -> Optional[str]:
+        """
+        Try to load a file with error handling.
+
+        Args:
+            file_path: Path to the file to load
+            file_type: Description of file type for logging
+
+        Returns:
+            File content if successful, None otherwise
+        """
+        try:
+            content = file_path.read_text()
+            if self.logger.isEnabledFor(logging.INFO):
+                self.logger.info(f"Loaded {file_type} from: {file_path}")
+
+            # Extract metadata if present
+            self._extract_metadata(content, file_path)
+            return content
+        except Exception as e:
+            if self.logger.isEnabledFor(logging.ERROR):
+                self.logger.error(f"Failed to load {file_type}: {e}")
+            return None
+
+    def _extract_metadata(self, content: str, file_path: Path) -> None:
+        """Extract metadata from file content.
+
+        Args:
+            content: File content to extract metadata from
+            file_path: Path to the file (for context)
+        """
+        # Extract version
+        version_match = re.search(r"<!-- FRAMEWORK_VERSION: (\d+) -->", content)
+        if version_match:
+            version = version_match.group(1)  # Keep as string to preserve leading zeros
+            self.logger.info(f"Framework version: {version}")
+            # Store framework version if this is the main INSTRUCTIONS.md
+            if "INSTRUCTIONS.md" in str(file_path):
+                self.framework_version = version
+
+        # Extract modification timestamp
+        timestamp_match = re.search(r"<!-- LAST_MODIFIED: ([^>]+) -->", content)
+        if timestamp_match:
+            timestamp = timestamp_match.group(1).strip()
+            self.logger.info(f"Last modified: {timestamp}")
+            # Store timestamp if this is the main INSTRUCTIONS.md
+            if "INSTRUCTIONS.md" in str(file_path):
+                self.framework_last_modified = timestamp
+
+    def _load_tier_file(
+        self,
+        filename: str,
+        current_dir: Path,
+        framework_path: Optional[Path] = None,
+        include_system: bool = False,
+    ) -> tuple[Optional[str], Optional[str]]:
+        """Load file with tier precedence: project → user → system.
+
+        Args:
+            filename: Name of file to load (e.g., "INSTRUCTIONS.md")
+            current_dir: Current working directory for project-level
+            framework_path: Path to framework installation for system-level
+            include_system: Whether to check system-level path
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        # Check project-level (highest priority)
+        project_path = current_dir / ".claude-mpm" / filename
+        if project_path.exists():
+            loaded_content = self.try_load_file(
+                project_path, f"project-specific {filename}"
+            )
+            if loaded_content:
+                self.logger.info(f"Using project-specific {filename} from .claude-mpm/")
+                return loaded_content, "project"
+
+        # Check user-level (medium priority)
+        user_path = Path.home() / ".claude-mpm" / filename
+        if user_path.exists():
+            loaded_content = self.try_load_file(user_path, f"user-specific {filename}")
+            if loaded_content:
+                self.logger.info(f"Using user-specific {filename} from ~/.claude-mpm/")
+                return loaded_content, "user"
+
+        # Check system-level (lowest priority)
+        if include_system and framework_path and framework_path != Path("__PACKAGED__"):
+            system_path = framework_path / "src" / "claude_mpm" / "agents" / filename
+            if system_path.exists():
+                loaded_content = self.try_load_file(system_path, f"system {filename}")
+                if loaded_content:
+                    self.logger.info(f"Using system {filename}")
+                    return loaded_content, "system"
+
+        return None, None
+
+    def load_instructions_file(
+        self, current_dir: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load custom INSTRUCTIONS.md from .claude-mpm directories.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/INSTRUCTIONS.md
+        2. User-specific: ~/.claude-mpm/INSTRUCTIONS.md
+
+        Args:
+            current_dir: Current working directory
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', or None
+        """
+        return self._load_tier_file("INSTRUCTIONS.md", current_dir)
+
+    def load_workflow_file(
+        self, current_dir: Path, framework_path: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load WORKFLOW.md from various locations.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/WORKFLOW.md
+        2. User-specific: ~/.claude-mpm/WORKFLOW.md
+        3. System default: framework/agents/WORKFLOW.md
+
+        Args:
+            current_dir: Current working directory
+            framework_path: Path to framework installation
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        return self._load_tier_file(
+            "WORKFLOW.md", current_dir, framework_path, include_system=True
+        )
+
+    def load_memory_file(
+        self, current_dir: Path, framework_path: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load MEMORY.md from various locations.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/MEMORY.md
+        2. User-specific: ~/.claude-mpm/MEMORY.md
+        3. System default: framework/agents/MEMORY.md
+
+        Args:
+            current_dir: Current working directory
+            framework_path: Path to framework installation
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        return self._load_tier_file(
+            "MEMORY.md", current_dir, framework_path, include_system=True
+        )

claude_mpm/core/framework/loaders/instruction_loader.py

@@ -0,0 +1,181 @@
+"""Loader for framework instructions and configuration files."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+from .file_loader import FileLoader
+from .packaged_loader import PackagedLoader
+
+
+class InstructionLoader:
+    """Handles loading of INSTRUCTIONS, WORKFLOW, and MEMORY files."""
+
+    def __init__(self, framework_path: Optional[Path] = None):
+        """Initialize the instruction loader.
+
+        Args:
+            framework_path: Path to framework installation
+        """
+        self.logger = get_logger("instruction_loader")
+        self.framework_path = framework_path
+        self.file_loader = FileLoader()
+        self.packaged_loader = PackagedLoader()
+        self.current_dir = Path.cwd()
+
+    def load_all_instructions(self, content: Dict[str, Any]) -> None:
+        """Load all instruction files into the content dictionary.
+
+        Args:
+            content: Dictionary to update with loaded instructions
+        """
+        # Load custom INSTRUCTIONS.md
+        self.load_custom_instructions(content)
+
+        # Load framework instructions
+        self.load_framework_instructions(content)
+
+        # Load WORKFLOW.md
+        self.load_workflow_instructions(content)
+
+        # Load MEMORY.md
+        self.load_memory_instructions(content)
+
+    def load_custom_instructions(self, content: Dict[str, Any]) -> None:
+        """Load custom INSTRUCTIONS.md from .claude-mpm directories.
+
+        Args:
+            content: Dictionary to update with loaded instructions
+        """
+        instructions, level = self.file_loader.load_instructions_file(self.current_dir)
+        if instructions:
+            content["custom_instructions"] = instructions
+            content["custom_instructions_level"] = level
+
+    def load_framework_instructions(self, content: Dict[str, Any]) -> None:
+        """Load framework INSTRUCTIONS.md or PM_INSTRUCTIONS.md.
+
+        Args:
+            content: Dictionary to update with framework instructions
+        """
+        if not self.framework_path:
+            return
+
+        # Check if this is a packaged installation
+        if self.framework_path == Path("__PACKAGED__"):
+            # Use packaged loader
+            self.packaged_loader.load_framework_content(content)
+        else:
+            # Load from filesystem for development mode
+            self._load_filesystem_framework_instructions(content)
+
+        # Update framework metadata
+        if self.file_loader.framework_version:
+            content["instructions_version"] = self.file_loader.framework_version
+            content["version"] = self.file_loader.framework_version
+        if self.file_loader.framework_last_modified:
+            content["instructions_last_modified"] = (
+                self.file_loader.framework_last_modified
+            )
+
+        # Transfer metadata from packaged loader if available
+        if self.packaged_loader.framework_version:
+            content["instructions_version"] = self.packaged_loader.framework_version
+            content["version"] = self.packaged_loader.framework_version
+        if self.packaged_loader.framework_last_modified:
+            content["instructions_last_modified"] = (
+                self.packaged_loader.framework_last_modified
+            )
+
+    def _load_filesystem_framework_instructions(self, content: Dict[str, Any]) -> None:
+        """Load framework instructions from filesystem.
+
+        Priority order:
+        1. Deployed compiled file: .claude-mpm/PM_INSTRUCTIONS_DEPLOYED.md (HIGHEST PRIORITY)
+        2. Source file (development): src/claude_mpm/agents/PM_INSTRUCTIONS.md
+        3. Legacy file (backward compat): src/claude_mpm/agents/INSTRUCTIONS.md
+
+        Args:
+            content: Dictionary to update with framework instructions
+        """
+        # PRIORITY 1: Check for compiled/deployed version in .claude-mpm/
+        # This is the merged PM_INSTRUCTIONS.md + WORKFLOW.md + MEMORY.md
+        deployed_path = self.current_dir / ".claude-mpm" / "PM_INSTRUCTIONS_DEPLOYED.md"
+        if deployed_path.exists():
+            loaded_content = self.file_loader.try_load_file(
+                deployed_path, "deployed PM_INSTRUCTIONS_DEPLOYED.md"
+            )
+            if loaded_content:
+                content["framework_instructions"] = loaded_content
+                content["loaded"] = True
+                self.logger.info("Loaded PM_INSTRUCTIONS_DEPLOYED.md from .claude-mpm/")
+                return  # Stop here - deployed version takes precedence
+
+        # PRIORITY 2: Development mode - load from source PM_INSTRUCTIONS.md
+        pm_instructions_path = (
+            self.framework_path / "src" / "claude_mpm" / "agents" / "PM_INSTRUCTIONS.md"
+        )
+        framework_instructions_path = (
+            self.framework_path / "src" / "claude_mpm" / "agents" / "INSTRUCTIONS.md"
+        )
+
+        # Try loading new consolidated file
+        if pm_instructions_path.exists():
+            loaded_content = self.file_loader.try_load_file(
+                pm_instructions_path, "source PM_INSTRUCTIONS.md (development mode)"
+            )
+            if loaded_content:
+                content["framework_instructions"] = loaded_content
+                content["loaded"] = True
+                self.logger.warning(
+                    "Using source PM_INSTRUCTIONS.md - deployed version not found"
+                )
+        # PRIORITY 3: Fall back to legacy file for backward compatibility
+        elif framework_instructions_path.exists():
+            loaded_content = self.file_loader.try_load_file(
+                framework_instructions_path, "framework INSTRUCTIONS.md (legacy)"
+            )
+            if loaded_content:
+                content["framework_instructions"] = loaded_content
+                content["loaded"] = True
+                self.logger.warning(
+                    "Using legacy INSTRUCTIONS.md - consider migrating to PM_INSTRUCTIONS.md"
+                )
+
+        # Load BASE_PM.md for core framework requirements
+        base_pm_path = (
+            self.framework_path / "src" / "claude_mpm" / "agents" / "BASE_PM.md"
+        )
+        if base_pm_path.exists():
+            base_pm_content = self.file_loader.try_load_file(
+                base_pm_path, "BASE_PM framework requirements"
+            )
+            if base_pm_content:
+                content["base_pm_instructions"] = base_pm_content
+
+    def load_workflow_instructions(self, content: Dict[str, Any]) -> None:
+        """Load WORKFLOW.md from appropriate location.
+
+        Args:
+            content: Dictionary to update with workflow instructions
+        """
+        workflow, level = self.file_loader.load_workflow_file(
+            self.current_dir, self.framework_path
+        )
+        if workflow:
+            content["workflow_instructions"] = workflow
+            content["workflow_instructions_level"] = level
+
+    def load_memory_instructions(self, content: Dict[str, Any]) -> None:
+        """Load MEMORY.md from appropriate location.
+
+        Args:
+            content: Dictionary to update with memory instructions
+        """
+        memory, level = self.file_loader.load_memory_file(
+            self.current_dir, self.framework_path
+        )
+        if memory:
+            content["memory_instructions"] = memory
+            content["memory_instructions_level"] = level

claude_mpm/core/framework/loaders/packaged_loader.py

@@ -0,0 +1,232 @@
+"""Loader for packaged installations using importlib.resources."""
+
+import re
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+# Import resource handling for packaged installations
+try:
+    # Python 3.9+
+    from importlib.resources import files
+except ImportError:
+    # Python 3.8 fallback
+    try:
+        from importlib_resources import files
+    except ImportError:
+        # Final fallback for development environments
+        files = None
+
+
+class PackagedLoader:
+    """Handles loading resources from packaged installations."""
+
+    def __init__(self):
+        """Initialize the packaged loader."""
+        self.logger = get_logger("packaged_loader")
+        self.framework_version: Optional[str] = None
+        self.framework_last_modified: Optional[str] = None
+
+    def load_packaged_file(self, filename: str) -> Optional[str]:
+        """Load a file from the packaged installation."""
+        if not files:
+            self.logger.warning("importlib.resources not available")
+            return None
+
+        try:
+            # Use importlib.resources to load file from package
+            agents_package = files("claude_mpm.agents")
+            file_path = agents_package / filename
+
+            if file_path.is_file():
+                content = file_path.read_text()
+                self.logger.info(f"Loaded {filename} from package")
+                return content
+            self.logger.warning(f"File {filename} not found in package")
+            return None
+        except Exception as e:
+            self.logger.error(f"Failed to load {filename} from package: {e}")
+            return None
+
+    def load_packaged_file_fallback(self, filename: str, resources) -> Optional[str]:
+        """Load a file from the packaged installation using importlib.resources fallback."""
+        try:
+            # Try different resource loading methods
+            try:
+                # Method 1: resources.read_text (Python 3.9+)
+                content = resources.read_text("claude_mpm.agents", filename)
+                self.logger.info(f"Loaded {filename} from package using read_text")
+                return content
+            except AttributeError:
+                # Method 2: resources.files (Python 3.9+)
+                agents_files = resources.files("claude_mpm.agents")
+                file_path = agents_files / filename
+                if file_path.is_file():
+                    content = file_path.read_text()
+                    self.logger.info(f"Loaded {filename} from package using files")
+                    return content
+                self.logger.warning(f"File {filename} not found in package")
+                return None
+        except Exception as e:
+            self.logger.error(
+                f"Failed to load {filename} from package with fallback: {e}"
+            )
+            return None
+
+    def extract_metadata_from_content(self, content: str, filename: str) -> None:
+        """Extract metadata from content string.
+
+        Args:
+            content: Content to extract metadata from
+            filename: Filename for context
+        """
+        # Extract version
+        version_match = re.search(r"<!-- FRAMEWORK_VERSION: (\d+) -->", content)
+        if version_match and "INSTRUCTIONS.md" in filename:
+            self.framework_version = version_match.group(1)
+            self.logger.info(f"Framework version: {self.framework_version}")
+
+        # Extract timestamp
+        timestamp_match = re.search(r"<!-- LAST_MODIFIED: ([^>]+) -->", content)
+        if timestamp_match and "INSTRUCTIONS.md" in filename:
+            self.framework_last_modified = timestamp_match.group(1).strip()
+            self.logger.info(f"Last modified: {self.framework_last_modified}")
+
+    def load_framework_content(self, content: Dict[str, Any]) -> None:
+        """Load framework content from packaged installation.
+
+        Args:
+            content: Dictionary to update with loaded content
+        """
+        if not files:
+            self.logger.warning(
+                "importlib.resources not available, cannot load packaged framework"
+            )
+            self.logger.debug(f"files variable is: {files}")
+            # Try alternative import methods
+            try:
+                from importlib import resources
+
+                self.logger.info("Using importlib.resources as fallback")
+                self.load_framework_content_fallback(content, resources)
+                return
+            except ImportError:
+                self.logger.error(
+                    "No importlib.resources available, using minimal framework"
+                )
+                return
+
+        try:
+            # Try new consolidated PM_INSTRUCTIONS.md first
+            pm_instructions_content = self.load_packaged_file("PM_INSTRUCTIONS.md")
+            if pm_instructions_content:
+                content["framework_instructions"] = pm_instructions_content
+                content["loaded"] = True
+                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md from package")
+                # Extract and store version/timestamp metadata
+                self.extract_metadata_from_content(
+                    pm_instructions_content, "PM_INSTRUCTIONS.md"
+                )
+            else:
+                # Fall back to legacy INSTRUCTIONS.md
+                instructions_content = self.load_packaged_file("INSTRUCTIONS.md")
+                if instructions_content:
+                    content["framework_instructions"] = instructions_content
+                    content["loaded"] = True
+                    self.logger.warning("Using legacy INSTRUCTIONS.md from package")
+                    # Extract and store version/timestamp metadata
+                    self.extract_metadata_from_content(
+                        instructions_content, "INSTRUCTIONS.md"
+                    )
+
+            if self.framework_version:
+                content["instructions_version"] = self.framework_version
+                content["version"] = self.framework_version
+            if self.framework_last_modified:
+                content["instructions_last_modified"] = self.framework_last_modified
+
+            # Load BASE_PM.md
+            base_pm_content = self.load_packaged_file("BASE_PM.md")
+            if base_pm_content:
+                content["base_pm_instructions"] = base_pm_content
+
+            # Load WORKFLOW.md
+            workflow_content = self.load_packaged_file("WORKFLOW.md")
+            if workflow_content:
+                content["workflow_instructions"] = workflow_content
+                content["workflow_instructions_level"] = "system"
+
+            # Load MEMORY.md
+            memory_content = self.load_packaged_file("MEMORY.md")
+            if memory_content:
+                content["memory_instructions"] = memory_content
+                content["memory_instructions_level"] = "system"
+
+        except Exception as e:
+            self.logger.error(f"Failed to load packaged framework content: {e}")
+
+    def load_framework_content_fallback(
+        self, content: Dict[str, Any], resources
+    ) -> None:
+        """Load framework content using importlib.resources fallback.
+
+        Args:
+            content: Dictionary to update with loaded content
+            resources: The importlib.resources module
+        """
+        try:
+            # Try new consolidated PM_INSTRUCTIONS.md first
+            pm_instructions_content = self.load_packaged_file_fallback(
+                "PM_INSTRUCTIONS.md", resources
+            )
+            if pm_instructions_content:
+                content["framework_instructions"] = pm_instructions_content
+                content["loaded"] = True
+                self.logger.info("Loaded consolidated PM_INSTRUCTIONS.md via fallback")
+                # Extract and store version/timestamp metadata
+                self.extract_metadata_from_content(
+                    pm_instructions_content, "PM_INSTRUCTIONS.md"
+                )
+            else:
+                # Fall back to legacy INSTRUCTIONS.md
+                instructions_content = self.load_packaged_file_fallback(
+                    "INSTRUCTIONS.md", resources
+                )
+                if instructions_content:
+                    content["framework_instructions"] = instructions_content
+                    content["loaded"] = True
+                    self.logger.warning("Using legacy INSTRUCTIONS.md via fallback")
+                    # Extract and store version/timestamp metadata
+                    self.extract_metadata_from_content(
+                        instructions_content, "INSTRUCTIONS.md"
+                    )
+
+            if self.framework_version:
+                content["instructions_version"] = self.framework_version
+                content["version"] = self.framework_version
+            if self.framework_last_modified:
+                content["instructions_last_modified"] = self.framework_last_modified
+
+            # Load BASE_PM.md
+            base_pm_content = self.load_packaged_file_fallback("BASE_PM.md", resources)
+            if base_pm_content:
+                content["base_pm_instructions"] = base_pm_content
+
+            # Load WORKFLOW.md
+            workflow_content = self.load_packaged_file_fallback(
+                "WORKFLOW.md", resources
+            )
+            if workflow_content:
+                content["workflow_instructions"] = workflow_content
+                content["workflow_instructions_level"] = "system"
+
+            # Load MEMORY.md
+            memory_content = self.load_packaged_file_fallback("MEMORY.md", resources)
+            if memory_content:
+                content["memory_instructions"] = memory_content
+                content["memory_instructions_level"] = "system"
+
+        except Exception as e:
+            self.logger.error(
+                f"Failed to load packaged framework content with fallback: {e}"
+            )

claude_mpm/core/framework/processors/__init__.py

@@ -0,0 +1,11 @@
+"""Framework processors for handling metadata, templates, and memory content."""
+
+from .memory_processor import MemoryProcessor
+from .metadata_processor import MetadataProcessor
+from .template_processor import TemplateProcessor
+
+__all__ = [
+    "MemoryProcessor",
+    "MetadataProcessor",
+    "TemplateProcessor",
+]