claude-mpm 3.9.9__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/config/experimental_features.py

@@ -0,0 +1,217 @@
+from pathlib import Path
+
+"""Experimental features configuration for Claude MPM.
+
+WHY: This module manages experimental and beta features, providing a centralized
+way to control feature flags and display appropriate warnings to users.
+
+DESIGN DECISION: Use a simple configuration class with static defaults that can
+be overridden through environment variables or config files. This allows for
+gradual rollout of experimental features while maintaining stability in production.
+"""
+
+import json
+import os
+from typing import Any, Dict, Optional
+
+
+class ExperimentalFeatures:
+    """Manages experimental feature flags and warnings.
+
+    WHY: Experimental features need special handling to ensure users understand
+    they are using beta functionality that may change or have issues.
+
+    DESIGN DECISION: Use environment variables for quick override during development,
+    but also support configuration files for persistent settings.
+    """
+
+    # Default feature flags
+    DEFAULTS = {
+        "enable_mcp_gateway": False,  # MCP Gateway is experimental
+        "enable_advanced_aggregation": False,  # Advanced aggregation features
+        "show_experimental_warnings": True,  # Show warnings for experimental features
+        "require_experimental_acceptance": True,  # Require explicit acceptance
+    }
+
+    # Warning messages for experimental features
+    WARNINGS = {
+        "mcp_gateway": (
+            "⚠️  EXPERIMENTAL FEATURE: MCP Gateway is in early access.\n"
+            "   Tool integration may be unstable. Not recommended for production use."
+        ),
+        "advanced_aggregation": (
+            "⚠️  EXPERIMENTAL FEATURE: Advanced aggregation is under development.\n"
+            "   Results may vary. Please verify outputs manually."
+        ),
+    }
+
+    def __init__(self, config_file: Optional[Path] = None):
+        """Initialize experimental features configuration.
+
+        Args:
+            config_file: Optional path to configuration file
+        """
+        self._features = self.DEFAULTS.copy()
+        self._config_file = config_file
+        self._load_configuration()
+        self._apply_environment_overrides()
+
+    def _load_configuration(self):
+        """Load configuration from file if it exists.
+
+        WHY: Allow persistent configuration of experimental features without
+        requiring environment variables to be set every time.
+        """
+        if self._config_file and self._config_file.exists():
+            try:
+                with open(self._config_file, "r") as f:
+                    config = json.load(f)
+                    experimental = config.get("experimental_features", {})
+                    self._features.update(experimental)
+            except Exception:
+                # Silently ignore configuration errors for experimental features
+                pass
+
+    def _apply_environment_overrides(self):
+        """Apply environment variable overrides.
+
+        WHY: Environment variables provide a quick way to enable/disable features
+        during development and testing without modifying configuration files.
+
+        Format: CLAUDE_MPM_EXPERIMENTAL_<FEATURE_NAME>=true/false
+        """
+        for key in self._features:
+            env_key = f"CLAUDE_MPM_EXPERIMENTAL_{key.upper()}"
+            if env_key in os.environ:
+                value = os.environ[env_key].lower()
+                self._features[key] = value in ("true", "1", "yes", "on")
+
+    def is_enabled(self, feature: str) -> bool:
+        """Check if a feature is enabled.
+
+        Args:
+            feature: Feature name (without 'enable_' prefix)
+
+        Returns:
+            True if the feature is enabled
+        """
+        key = f"enable_{feature}" if not feature.startswith("enable_") else feature
+        return self._features.get(key, False)
+
+    def get_warning(self, feature: str) -> Optional[str]:
+        """Get warning message for a feature.
+
+        Args:
+            feature: Feature name
+
+        Returns:
+            Warning message or None if no warning exists
+        """
+        return self.WARNINGS.get(feature)
+
+    def should_show_warning(self, feature: str) -> bool:
+        """Check if warning should be shown for a feature.
+
+        Args:
+            feature: Feature name
+
+        Returns:
+            True if warning should be displayed
+        """
+        if not self._features.get("show_experimental_warnings", True):
+            return False
+
+        # Check if user has already accepted this feature
+        accepted_file = Path.home() / ".claude-mpm" / ".experimental_accepted"
+        if accepted_file.exists():
+            try:
+                with open(accepted_file, "r") as f:
+                    accepted = json.load(f)
+                    if feature in accepted.get("features", []):
+                        return False
+            except Exception:
+                pass
+
+        return True
+
+    def mark_accepted(self, feature: str):
+        """Mark a feature as accepted by the user.
+
+        WHY: Once a user accepts the experimental status, we don't need to
+        warn them every time they use the feature.
+
+        Args:
+            feature: Feature name to mark as accepted
+        """
+        accepted_file = Path.home() / ".claude-mpm" / ".experimental_accepted"
+        accepted_file.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            if accepted_file.exists():
+                with open(accepted_file, "r") as f:
+                    data = json.load(f)
+            else:
+                data = {"features": [], "timestamp": {}}
+
+            if feature not in data["features"]:
+                data["features"].append(feature)
+                data["timestamp"][feature] = os.environ.get(
+                    "CLAUDE_MPM_TIMESTAMP", str(Path.cwd())
+                )
+
+            with open(accepted_file, "w") as f:
+                json.dump(data, f, indent=2)
+        except Exception:
+            # Silently ignore errors in acceptance tracking
+            pass
+
+    def requires_acceptance(self) -> bool:
+        """Check if experimental features require explicit acceptance.
+
+        Returns:
+            True if acceptance is required
+        """
+        return self._features.get("require_experimental_acceptance", True)
+
+    def get_all_features(self) -> Dict[str, bool]:
+        """Get all feature flags and their current values.
+
+        Returns:
+            Dictionary of feature flags and their values
+        """
+        return self._features.copy()
+
+
+# Global instance for easy access
+_experimental_features = None
+
+
+def get_experimental_features(
+    config_file: Optional[Path] = None,
+) -> ExperimentalFeatures:
+    """Get the global experimental features instance.
+
+    WHY: Provide a singleton-like access pattern to experimental features
+    configuration to ensure consistency across the application.
+
+    Args:
+        config_file: Optional configuration file path
+
+    Returns:
+        ExperimentalFeatures instance
+    """
+    global _experimental_features
+    if _experimental_features is None:
+        # Check for config file in standard locations
+        if config_file is None:
+            for path in [
+                Path.cwd() / ".claude-mpm" / "experimental.json",
+                Path.home() / ".claude-mpm" / "experimental.json",
+            ]:
+                if path.exists():
+                    config_file = path
+                    break
+
+        _experimental_features = ExperimentalFeatures(config_file)
+
+    return _experimental_features

claude_mpm/config/paths.py

@@ -1,317 +1,203 @@
 """
 Centralized path management for claude-mpm.
 
+This module provides the primary interface for path management operations.
+All functionality has been consolidated into the unified path management system.
+
 This module provides a consistent, reliable way to access project paths
 without fragile parent.parent.parent patterns.
 """
 
-import os
+import logging
 import sys
 from pathlib import Path
 from typing import Optional, Union
-from functools import cached_property
-import logging
+
+# Import from the unified path management system
+from ..core.unified_paths import get_path_manager
 
 logger = logging.getLogger(__name__)
 
 
 class ClaudeMPMPaths:
     """
-    Centralized path management for the claude-mpm project.
-    
-    This class provides a singleton instance with properties for all common paths
-    in the project, eliminating the need for fragile Path(__file__).parent.parent patterns.
-    
+    Primary interface for the unified path management system.
+
+    This class provides access to all path operations through the UnifiedPathManager.
+
     Usage:
         from claude_mpm.config.paths import paths
-        
+
         # Access common paths
         project_root = paths.project_root
         agents_dir = paths.agents_dir
         config_file = paths.config_dir / "some_config.yaml"
     """
-    
-    _instance: Optional['ClaudeMPMPaths'] = None
-    _project_root: Optional[Path] = None
-    _is_installed: bool = False
-    
-    def __new__(cls) -> 'ClaudeMPMPaths':
+
+    _instance: Optional["ClaudeMPMPaths"] = None
+    _path_manager = None
+
+    def __new__(cls) -> "ClaudeMPMPaths":
         """Singleton pattern to ensure single instance."""
         if cls._instance is None:
             cls._instance = super().__new__(cls)
         return cls._instance
-    
+
     def __init__(self):
-        """Initialize paths if not already done."""
-        if self._project_root is None:
-            self._is_installed = False
-            self._detect_project_root()
-    
-    def _detect_project_root(self) -> None:
-        """
-        Detect the project root directory.
-        
-        Strategy:
-        1. Look for definitive project markers (pyproject.toml, setup.py)
-        2. Look for combination of markers to ensure we're at the right level
-        3. Walk up from current file location
-        4. Handle both development and installed environments
-        """
-        # Start from this file's location
-        current = Path(__file__).resolve()
-        
-        # Check if we're in an installed environment (site-packages)
-        # In pip/pipx installs, the package is directly in site-packages
-        if 'site-packages' in str(current) or 'dist-packages' in str(current):
-            # We're in an installed environment
-            # The claude_mpm package directory itself is the "root" for resources
-            import claude_mpm
-            self._project_root = Path(claude_mpm.__file__).parent
-            self._is_installed = True
-            logger.debug(f"Installed environment detected, using package dir: {self._project_root}")
-            return
-        
-        # We're in a development environment, look for project markers
-        for parent in current.parents:
-            # Check for definitive project root indicators
-            # Prioritize pyproject.toml and setup.py as they're only at root
-            if (parent / 'pyproject.toml').exists() or (parent / 'setup.py').exists():
-                self._project_root = parent
-                self._is_installed = False
-                logger.debug(f"Project root detected at: {parent} (found pyproject.toml or setup.py)")
-                return
-            
-            # Secondary check: .git directory + VERSION file together
-            # This combination is more likely to be the real project root
-            if (parent / '.git').exists() and (parent / 'VERSION').exists():
-                self._project_root = parent
-                self._is_installed = False
-                logger.debug(f"Project root detected at: {parent} (found .git and VERSION)")
-                return
-        
-        # Fallback: walk up to find claude-mpm directory name
-        for parent in current.parents:
-            if parent.name == 'claude-mpm':
-                self._project_root = parent
-                self._is_installed = False
-                logger.debug(f"Project root detected at: {parent} (by directory name)")
-                return
-        
-        # Last resort fallback: 3 levels up from this file
-        # paths.py is in src/claude_mpm/config/
-        self._project_root = current.parent.parent.parent
-        self._is_installed = False
-        logger.warning(f"Project root fallback to: {self._project_root}")
-    
+        """Initialize paths using the unified path manager."""
+        if self._path_manager is None:
+            self._path_manager = get_path_manager()
+
+    # ========================================================================
+    # Compatibility Properties - Delegate to UnifiedPathManager
+    # ========================================================================
+
     @property
     def project_root(self) -> Path:
         """Get the project root directory."""
-        if self._project_root is None:
-            self._detect_project_root()
-        return self._project_root
-    
+        return self._path_manager.project_root
+
+    @property
+    def framework_root(self) -> Path:
+        """Get the framework root directory."""
+        return self._path_manager.framework_root
+
     @property
     def src_dir(self) -> Path:
         """Get the src directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # In installed environment, there's no src directory
-            # Return the package directory itself
-            return self.project_root.parent
-        return self.project_root / "src"
-    
+        return self._path_manager.framework_root / "src"
+
     @property
     def claude_mpm_dir(self) -> Path:
         """Get the main claude_mpm package directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # In installed environment, project_root IS the claude_mpm directory
-            return self.project_root
-        return self.src_dir / "claude_mpm"
-    
+        return self._path_manager.package_root
+
     @property
     def agents_dir(self) -> Path:
         """Get the agents directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # In installed environment, agents is directly under the package
-            return self.project_root / "agents"
-        return self.claude_mpm_dir / "agents"
-    
+        return self._path_manager.get_agents_dir("framework")
+
     @property
     def services_dir(self) -> Path:
         """Get the services directory."""
-        return self.claude_mpm_dir / "services"
-    
+        return self._path_manager.package_root / "services"
+
     @property
     def hooks_dir(self) -> Path:
         """Get the hooks directory."""
-        return self.claude_mpm_dir / "hooks"
-    
+        return self._path_manager.package_root / "hooks"
+
     @property
     def config_dir(self) -> Path:
         """Get the config directory."""
-        return self.claude_mpm_dir / "config"
-    
+        return self._path_manager.package_root / "config"
+
     @property
     def cli_dir(self) -> Path:
         """Get the CLI directory."""
-        return self.claude_mpm_dir / "cli"
-    
+        return self._path_manager.package_root / "cli"
+
     @property
     def core_dir(self) -> Path:
         """Get the core directory."""
-        return self.claude_mpm_dir / "core"
-    
+        return self._path_manager.package_root / "core"
+
     @property
     def schemas_dir(self) -> Path:
         """Get the schemas directory."""
-        return self.claude_mpm_dir / "schemas"
-    
+        return self._path_manager.package_root / "schemas"
+
     @property
     def scripts_dir(self) -> Path:
         """Get the scripts directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # In installed environment, scripts might be in a different location or not exist
-            # Return a path that won't cause issues but indicates it's not available
-            return Path.home() / '.claude-mpm' / 'scripts'
-        return self.project_root / "scripts"
-    
+        return self._path_manager.get_scripts_dir()
+
     @property
     def tests_dir(self) -> Path:
         """Get the tests directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # Tests aren't distributed with installed packages
-            return Path.home() / '.claude-mpm' / 'tests'
-        return self.project_root / "tests"
-    
+        return self._path_manager.project_root / "tests"
+
     @property
     def docs_dir(self) -> Path:
         """Get the documentation directory."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # Docs might be installed separately or not at all
-            return Path.home() / '.claude-mpm' / 'docs'
-        return self.project_root / "docs"
-    
+        return self._path_manager.project_root / "docs"
+
     @property
     def logs_dir(self) -> Path:
         """Get the logs directory (creates if doesn't exist)."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # Use user's home directory for logs in installed environment
-            logs = Path.home() / '.claude-mpm' / 'logs'
-        else:
-            logs = self.project_root / "logs"
-        logs.mkdir(parents=True, exist_ok=True)
-        return logs
-    
+        logs_dir = self._path_manager.get_logs_dir("project")
+        self._path_manager.ensure_directory(logs_dir)
+        return logs_dir
+
     @property
     def temp_dir(self) -> Path:
         """Get the temporary files directory (creates if doesn't exist)."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # Use user's home directory for temp files in installed environment
-            temp = Path.home() / '.claude-mpm' / '.tmp'
-        else:
-            temp = self.project_root / ".tmp"
-        temp.mkdir(parents=True, exist_ok=True)
-        return temp
-    
+        temp_dir = self._path_manager.project_root / ".tmp"
+        self._path_manager.ensure_directory(temp_dir)
+        return temp_dir
+
     @property
     def claude_mpm_dir_hidden(self) -> Path:
         """Get the hidden .claude-mpm directory (creates if doesn't exist)."""
-        if hasattr(self, '_is_installed') and self._is_installed:
-            # Use current working directory in installed environment
-            hidden = Path.cwd() / ".claude-mpm"
-        else:
-            hidden = self.project_root / ".claude-mpm"
-        hidden.mkdir(exist_ok=True)
-        return hidden
-    
-    @cached_property
+        hidden_dir = self._path_manager.get_config_dir("project")
+        self._path_manager.ensure_directory(hidden_dir)
+        return hidden_dir
+
+    @property
     def version_file(self) -> Path:
         """Get the VERSION file path."""
-        return self.project_root / "VERSION"
-    
-    @cached_property
+        return self._path_manager.project_root / "VERSION"
+
+    @property
     def pyproject_file(self) -> Path:
         """Get the pyproject.toml file path."""
-        return self.project_root / "pyproject.toml"
-    
-    @cached_property
+        return self._path_manager.project_root / "pyproject.toml"
+
+    @property
     def package_json_file(self) -> Path:
         """Get the package.json file path."""
-        return self.project_root / "package.json"
-    
-    @cached_property
+        return self._path_manager.project_root / "package.json"
+
+    @property
     def claude_md_file(self) -> Path:
         """Get the CLAUDE.md file path."""
-        return self.project_root / "CLAUDE.md"
-    
+        return self._path_manager.project_root / "CLAUDE.md"
+
     def get_version(self) -> str:
-        """
-        Get the project version from various sources.
-        
-        Returns:
-            Version string or 'unknown' if not found.
-        """
-        # Try VERSION file first
-        if self.version_file.exists():
-            return self.version_file.read_text().strip()
-        
-        # Try package metadata
-        try:
-            from importlib.metadata import version
-            return version('claude-mpm')
-        except Exception:
-            pass
-        
-        return 'unknown'
-    
+        """Get the project version from various sources."""
+        return self._path_manager.get_version()
+
     def ensure_in_path(self) -> None:
         """Ensure src directory is in Python path."""
-        src_str = str(self.src_dir)
-        if src_str not in sys.path:
-            sys.path.insert(0, src_str)
-    
+        self._path_manager.ensure_src_in_path()
+
     def relative_to_project(self, path: Union[str, Path]) -> Path:
-        """
-        Get a path relative to the project root.
-        
-        Args:
-            path: Path to make relative
-            
-        Returns:
-            Path relative to project root
-        """
+        """Get a path relative to the project root."""
         abs_path = Path(path).resolve()
         try:
             return abs_path.relative_to(self.project_root)
         except ValueError:
             return abs_path
-    
+
     def resolve_config_path(self, config_name: str) -> Path:
-        """
-        Resolve a configuration file path.
-        
-        Args:
-            config_name: Name of the config file
-            
-        Returns:
-            Full path to the config file
-        """
+        """Resolve a configuration file path."""
         # Check in config directory first
         config_path = self.config_dir / config_name
         if config_path.exists():
             return config_path
-        
+
         # Check in project root
         root_path = self.project_root / config_name
         if root_path.exists():
             return root_path
-        
+
         # Return config dir path as default
         return config_path
-    
+
     def __str__(self) -> str:
         """String representation."""
         return f"ClaudeMPMPaths(root={self.project_root})"
-    
+
     def __repr__(self) -> str:
         """Developer representation."""
         return (
@@ -369,4 +255,4 @@ def ensure_src_in_path() -> None:
 
 
 # Auto-ensure src is in path when module is imported
-ensure_src_in_path()
+ensure_src_in_path()