moai-adk 0.15.1__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/core/config/unified.py

@@ -0,0 +1,436 @@
+"""
+Unified Configuration Manager for MoAI-ADK
+
+Thread-safe singleton configuration manager that consolidates all config management
+patterns from across the codebase into a single, robust implementation.
+
+Features:
+- Thread-safe singleton with double-checked locking
+- Lazy loading with in-memory caching
+- Atomic writes with backup creation
+- Schema validation support
+- Smart defaults with auto-detection
+- Deep merge for nested configs
+- Configuration migration between versions
+- Domain-specific facades for different subsystems
+
+Design Philosophy:
+- Single source of truth for `.moai/config/config.yaml` (with JSON fallback)
+- Best patterns from StatuslineConfig, UnifiedConfigManager, ConfigurationManager
+- Backward compatible with existing ConfigManager interfaces
+- Performance optimized with caching and minimal I/O
+
+Usage:
+    >>> from moai_adk.core.config.unified import get_unified_config
+    >>> config = get_unified_config()
+    >>> timeout = config.get("hooks.timeout_ms", 2000)
+    >>> config.update({"hooks.timeout_ms": 3000})
+    >>> config.save()
+"""
+
+import json
+import logging
+import shutil
+import threading
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+try:
+    import yaml
+
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class UnifiedConfigManager:
+    """
+    Thread-safe singleton configuration manager for MoAI-ADK.
+
+    This class consolidates all configuration management patterns from:
+    - StatuslineConfig: Thread-safe singleton pattern
+    - UnifiedConfigManager (skills): Backup, migration, validation
+    - ConfigurationManager (project): Smart defaults, auto-detection
+    - ConfigManager (hooks): Convenience functions
+
+    Attributes:
+        _instance: Singleton instance
+        _config: Cached configuration dictionary
+        _lock: Thread lock for singleton pattern
+        _config_path: Path to configuration file
+        _last_modified: Last modification timestamp for cache invalidation
+    """
+
+    _instance: Optional["UnifiedConfigManager"] = None
+    _config: Dict[str, Any] = {}
+    _lock = threading.Lock()
+    _config_path: Optional[Path] = None
+    _last_modified: Optional[float] = None
+
+    def __new__(cls, config_path: Optional[Union[str, Path]] = None):
+        """
+        Create or return singleton instance with double-checked locking.
+
+        Args:
+            config_path: Optional path to config file (default: .moai/config/config.json)
+
+        Returns:
+            UnifiedConfigManager: Singleton instance
+        """
+        # Double-checked locking pattern for thread-safe singleton
+        if cls._instance is None:
+            with cls._lock:
+                # Double-check after acquiring lock
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+                    cls._instance._initialize(config_path)
+        return cls._instance
+
+    def _initialize(self, config_path: Optional[Union[str, Path]] = None) -> None:
+        """
+        Initialize configuration manager (called once by singleton).
+
+        Args:
+            config_path: Optional path to config file
+        """
+        # Set config path with auto-detection
+        if config_path:
+            self._config_path = Path(config_path)
+        else:
+            # Auto-detect YAML (preferred) or JSON (fallback)
+            base_path = Path.cwd() / ".moai" / "config"
+            yaml_path = base_path / "config.yaml"
+            json_path = base_path / "config.json"
+
+            if YAML_AVAILABLE and yaml_path.exists():
+                self._config_path = yaml_path
+            elif json_path.exists():
+                self._config_path = json_path
+            else:
+                # Default to YAML for new projects
+                self._config_path = yaml_path if YAML_AVAILABLE else json_path
+
+        # Load configuration
+        self._load_config()
+
+    def _load_config(self) -> None:
+        """
+        Load configuration from file with caching.
+
+        Implements cache invalidation based on file modification time.
+        Falls back to default configuration if file doesn't exist.
+        Supports both YAML (preferred) and JSON (legacy) formats.
+        """
+        try:
+            # Check if file exists
+            if not self._config_path.exists():
+                logger.warning(f"Config file not found: {self._config_path}")
+                self._config = self._get_default_config()
+                return
+
+            # Check cache validity
+            current_mtime = self._config_path.stat().st_mtime
+            if self._last_modified and current_mtime == self._last_modified:
+                # Cache is still valid
+                return
+
+            # Load from file (auto-detect format)
+            with open(self._config_path, "r", encoding="utf-8") as f:
+                if self._config_path.suffix == ".yaml" or self._config_path.suffix == ".yml":
+                    if not YAML_AVAILABLE:
+                        raise ImportError("PyYAML is required for YAML config files. Install with: pip install pyyaml")
+                    self._config = yaml.safe_load(f) or {}
+                else:
+                    self._config = json.load(f)
+
+            # Update cache timestamp
+            self._last_modified = current_mtime
+
+            logger.debug(f"Loaded config from {self._config_path}")
+
+        except (
+            json.JSONDecodeError,
+            yaml.YAMLError if YAML_AVAILABLE else Exception,
+            OSError,
+            UnicodeDecodeError,
+        ) as e:
+            logger.error(f"Failed to load config: {e}")
+            self._config = self._get_default_config()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value with dot-notation support.
+
+        Args:
+            key: Configuration key (supports dot notation, e.g., "hooks.timeout_ms")
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default
+
+        Examples:
+            >>> config.get("hooks.timeout_ms", 2000)
+            2000
+            >>> config.get("project.name")
+            "MoAI-ADK"
+        """
+        # Reload if file changed
+        self._reload_if_modified()
+
+        # Navigate nested dict with dot notation
+        keys = key.split(".")
+        value = self._config
+
+        for k in keys:
+            if isinstance(value, dict):
+                value = value.get(k)
+                if value is None:
+                    return default
+            else:
+                return default
+
+        return value if value is not None else default
+
+    def set(self, key: str, value: Any) -> None:
+        """
+        Set configuration value with dot-notation support.
+
+        Args:
+            key: Configuration key (supports dot notation)
+            value: Value to set
+
+        Examples:
+            >>> config.set("hooks.timeout_ms", 3000)
+            >>> config.set("project.name", "MyProject")
+        """
+        # Navigate to parent dict
+        keys = key.split(".")
+        target = self._config
+
+        for k in keys[:-1]:
+            if k not in target:
+                target[k] = {}
+            target = target[k]
+
+        # Set value
+        target[keys[-1]] = value
+
+    def update(self, updates: Dict[str, Any], deep_merge: bool = True) -> None:
+        """
+        Update configuration with dictionary.
+
+        Args:
+            updates: Dictionary of updates
+            deep_merge: If True, recursively merge nested dicts (default: True)
+
+        Examples:
+            >>> config.update({"hooks": {"timeout_ms": 3000}})
+            >>> config.update({"project.name": "MyProject"}, deep_merge=False)
+        """
+        if deep_merge:
+            self._config = self._deep_merge(self._config, updates)
+        else:
+            self._config.update(updates)
+
+    def save(self, backup: bool = True) -> bool:
+        """
+        Save configuration to file with atomic write.
+
+        Args:
+            backup: If True, create backup before saving (default: True)
+
+        Returns:
+            bool: True if save successful, False otherwise
+
+        Pattern: Temp file → Atomic rename (prevents corruption)
+        """
+        try:
+            # Create backup if requested
+            if backup and self._config_path.exists():
+                self._create_backup()
+
+            # Atomic write pattern: temp file → rename
+            temp_path = self._config_path.with_suffix(".tmp")
+
+            # Write to temp file (auto-detect format)
+            with open(temp_path, "w", encoding="utf-8") as f:
+                if self._config_path.suffix == ".yaml" or self._config_path.suffix == ".yml":
+                    if not YAML_AVAILABLE:
+                        raise ImportError("PyYAML is required for YAML config files. Install with: pip install pyyaml")
+                    yaml.safe_dump(
+                        self._config,
+                        f,
+                        default_flow_style=False,
+                        allow_unicode=True,
+                        sort_keys=False,
+                    )
+                else:
+                    json.dump(self._config, f, indent=2, ensure_ascii=False)
+
+            # Atomic rename
+            temp_path.replace(self._config_path)
+
+            # Update cache timestamp
+            self._last_modified = self._config_path.stat().st_mtime
+
+            logger.info(f"Saved config to {self._config_path}")
+            return True
+
+        except (OSError, PermissionError) as e:
+            logger.error(f"Failed to save config: {e}")
+            return False
+
+    def _create_backup(self) -> None:
+        """Create timestamped backup of config file."""
+        try:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            backup_dir = self._config_path.parent / "backups"
+            backup_dir.mkdir(parents=True, exist_ok=True)
+
+            backup_path = backup_dir / f"config_backup_{timestamp}.json"
+            shutil.copy2(self._config_path, backup_path)
+
+            logger.debug(f"Created backup: {backup_path}")
+
+        except (OSError, PermissionError) as e:
+            logger.warning(f"Failed to create backup: {e}")
+
+    def _reload_if_modified(self) -> None:
+        """Reload config if file has been modified."""
+        try:
+            if self._config_path.exists():
+                current_mtime = self._config_path.stat().st_mtime
+                if self._last_modified is None or current_mtime != self._last_modified:
+                    self._load_config()
+        except OSError:
+            pass
+
+    @staticmethod
+    def _deep_merge(base: Dict[str, Any], updates: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Recursively merge two dictionaries.
+
+        Args:
+            base: Base dictionary
+            updates: Updates to merge
+
+        Returns:
+            Merged dictionary
+        """
+        result = base.copy()
+
+        for key, value in updates.items():
+            if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+                result[key] = UnifiedConfigManager._deep_merge(result[key], value)
+            else:
+                result[key] = value
+
+        return result
+
+    @staticmethod
+    def _get_default_config() -> Dict[str, Any]:
+        """
+        Get default configuration when file doesn't exist.
+
+        Returns:
+            Default configuration dictionary
+        """
+        return {
+            "moai": {"version": "0.28.0", "update_check_frequency": "daily"},
+            "project": {"name": "MyProject", "initialized": False},
+            "hooks": {"timeout_ms": 2000, "graceful_degradation": True},
+            "session": {"suppress_setup_messages": False},
+            "language": {"conversation_language": "en", "agent_prompt_language": "en"},
+        }
+
+    def get_all(self) -> Dict[str, Any]:
+        """
+        Get entire configuration dictionary.
+
+        Returns:
+            Complete configuration dictionary
+        """
+        self._reload_if_modified()
+        return self._config.copy()
+
+    def reset_to_defaults(self) -> None:
+        """Reset configuration to defaults without saving."""
+        self._config = self._get_default_config()
+
+
+# Module-level singleton instance
+_unified_config_instance: Optional[UnifiedConfigManager] = None
+
+
+def get_unified_config(
+    config_path: Optional[Union[str, Path]] = None,
+) -> UnifiedConfigManager:
+    """
+    Get or create unified configuration manager instance.
+
+    Args:
+        config_path: Optional path to config file
+
+    Returns:
+        UnifiedConfigManager: Singleton instance
+
+    Examples:
+        >>> config = get_unified_config()
+        >>> timeout = config.get("hooks.timeout_ms", 2000)
+    """
+    global _unified_config_instance
+
+    if _unified_config_instance is None:
+        _unified_config_instance = UnifiedConfigManager(config_path)
+
+    return _unified_config_instance
+
+
+# Convenience functions for common operations
+@lru_cache(maxsize=1)
+def get_config_path() -> Path:
+    """Get path to configuration file."""
+    return Path.cwd() / ".moai" / "config" / "config.json"
+
+
+def get_config_value(key: str, default: Any = None) -> Any:
+    """
+    Get configuration value (convenience function).
+
+    Args:
+        key: Configuration key with dot notation
+        default: Default value if key not found
+
+    Returns:
+        Configuration value or default
+    """
+    return get_unified_config().get(key, default)
+
+
+def set_config_value(key: str, value: Any) -> None:
+    """
+    Set configuration value (convenience function).
+
+    Args:
+        key: Configuration key with dot notation
+        value: Value to set
+    """
+    config = get_unified_config()
+    config.set(key, value)
+
+
+def save_config(backup: bool = True) -> bool:
+    """
+    Save configuration (convenience function).
+
+    Args:
+        backup: Create backup before saving
+
+    Returns:
+        bool: True if successful
+    """
+    return get_unified_config().save(backup)

moai_adk/core/context_manager.py

@@ -0,0 +1,273 @@
+"""
+Context Management Module for Commands Layer
+
+Provides utilities for:
+1. Path validation and absolute path conversion
+2. Atomic JSON file operations
+3. Phase result persistence and loading
+4. Template variable substitution
+"""
+
+import json
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+# Constants
+PROJECT_ROOT_SAFETY_MSG = "Path outside project root: {}"
+PARENT_DIR_MISSING_MSG = "Parent directory not found: {}"
+
+
+def _is_path_within_root(abs_path: str, project_root: str) -> bool:
+    """
+    Check if absolute path is within project root.
+
+    Resolves symlinks to prevent escape attacks.
+
+    Args:
+        abs_path: Absolute path to check
+        project_root: Project root directory
+
+    Returns:
+        True if path is within root, False otherwise
+    """
+    try:
+        real_abs_path = os.path.realpath(abs_path)
+        real_project_root = os.path.realpath(project_root)
+
+        return real_abs_path == real_project_root or real_abs_path.startswith(real_project_root + os.sep)
+    except OSError:
+        return False
+
+
+def validate_and_convert_path(relative_path: str, project_root: str) -> str:
+    """
+    Convert relative path to absolute path and validate it.
+
+    Ensures path stays within project root and parent directories exist
+    for file paths.
+
+    Args:
+        relative_path: Path to validate and convert (relative or absolute)
+        project_root: Project root directory for relative path resolution
+
+    Returns:
+        Validated absolute path
+
+    Raises:
+        ValueError: If path is outside project root
+        FileNotFoundError: If parent directory doesn't exist for file paths
+    """
+    # Convert to absolute path
+    abs_path = os.path.abspath(os.path.join(project_root, relative_path))
+    project_root_abs = os.path.abspath(project_root)
+
+    # Security check: ensure path stays within project root
+    if not _is_path_within_root(abs_path, project_root_abs):
+        raise ValueError(PROJECT_ROOT_SAFETY_MSG.format(abs_path))
+
+    # If it's a directory and exists, return it
+    if os.path.isdir(abs_path):
+        return abs_path
+
+    # For files, check if parent directory exists
+    parent_dir = os.path.dirname(abs_path)
+    if not os.path.exists(parent_dir):
+        raise FileNotFoundError(PARENT_DIR_MISSING_MSG.format(parent_dir))
+
+    return abs_path
+
+
+def _cleanup_temp_file(temp_fd: Optional[int], temp_path: Optional[str]) -> None:
+    """
+    Clean up temporary file handles and paths.
+
+    Silently ignores errors during cleanup.
+
+    Args:
+        temp_fd: File descriptor to close, or None
+        temp_path: Path to file to remove, or None
+    """
+    if temp_fd is not None:
+        try:
+            os.close(temp_fd)
+        except OSError:
+            pass
+
+    if temp_path and os.path.exists(temp_path):
+        try:
+            os.unlink(temp_path)
+        except OSError:
+            pass
+
+
+def save_phase_result(data: Dict[str, Any], target_path: str) -> None:
+    """
+    Atomically save phase result to JSON file.
+
+    Uses temporary file and atomic rename to ensure data integrity
+    even if write fails midway.
+
+    Args:
+        data: Dictionary to save
+        target_path: Full path where JSON should be saved
+
+    Raises:
+        IOError: If write or rename fails
+        OSError: If directory is not writable
+    """
+    target_dir = os.path.dirname(target_path)
+    os.makedirs(target_dir, exist_ok=True)
+
+    # Atomic write using temp file
+    temp_fd = None
+    temp_path = None
+
+    try:
+        # Create temp file in target directory for atomic rename
+        temp_fd, temp_path = tempfile.mkstemp(dir=target_dir, prefix=".tmp_phase_", suffix=".json")
+
+        # Write JSON to temp file
+        with os.fdopen(temp_fd, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+
+        temp_fd = None  # File handle is now closed
+
+        # Atomic rename
+        os.replace(temp_path, target_path)
+
+    except Exception as e:
+        _cleanup_temp_file(temp_fd, temp_path)
+        raise IOError(f"Failed to write {target_path}: {e}")
+
+
+def load_phase_result(source_path: str) -> Dict[str, Any]:
+    """
+    Load phase result from JSON file.
+
+    Args:
+        source_path: Full path to JSON file to load
+
+    Returns:
+        Dictionary containing phase result
+
+    Raises:
+        FileNotFoundError: If file doesn't exist
+        json.JSONDecodeError: If file is not valid JSON
+    """
+    if not os.path.exists(source_path):
+        raise FileNotFoundError(f"Phase result file not found: {source_path}")
+
+    with open(source_path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    return data
+
+
+def substitute_template_variables(text: str, context: Dict[str, str]) -> str:
+    """
+    Replace template variables in text with values from context.
+
+    Performs safe string substitution of {{VARIABLE}} placeholders.
+
+    Args:
+        text: Text containing {{VARIABLE}} placeholders
+        context: Dictionary mapping variable names to values
+
+    Returns:
+        Text with variables substituted
+    """
+    result = text
+
+    for key, value in context.items():
+        placeholder = f"{{{{{key}}}}}"
+        result = result.replace(placeholder, str(value))
+
+    return result
+
+
+# Regex pattern for detecting unsubstituted template variables
+# Matches {{VARIABLE}}, {{VAR_NAME}}, {{VAR1}}, etc.
+TEMPLATE_VAR_PATTERN = r"\{\{[A-Z_][A-Z0-9_]*\}\}"
+
+
+def validate_no_template_vars(text: str) -> None:
+    """
+    Validate that text contains no unsubstituted template variables.
+
+    Raises error if any {{VARIABLE}} patterns are found.
+
+    Args:
+        text: Text to validate
+
+    Raises:
+        ValueError: If unsubstituted variables are found
+    """
+    matches = re.findall(TEMPLATE_VAR_PATTERN, text)
+
+    if matches:
+        raise ValueError(f"Unsubstituted template variables found: {matches}")
+
+
+class ContextManager:
+    """
+    Manages context passing and state persistence for Commands layer.
+
+    Handles saving and loading phase results, managing state directory,
+    and providing convenient access to command state.
+    """
+
+    def __init__(self, project_root: str):
+        """
+        Initialize ContextManager.
+
+        Args:
+            project_root: Root directory of the project
+        """
+        self.project_root = project_root
+        self.state_dir = os.path.join(project_root, ".moai", "memory", "command-state")
+        os.makedirs(self.state_dir, exist_ok=True)
+
+    def save_phase_result(self, data: Dict[str, Any]) -> str:
+        """
+        Save phase result with timestamp.
+
+        Args:
+            data: Phase result data
+
+        Returns:
+            Path to saved file
+        """
+        # Generate filename with timestamp
+        timestamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+        phase_name = data.get("phase", "unknown")
+        filename = f"{phase_name}-{timestamp}.json"
+        target_path = os.path.join(self.state_dir, filename)
+
+        save_phase_result(data, target_path)
+        return target_path
+
+    def load_latest_phase(self) -> Optional[Dict[str, Any]]:
+        """
+        Load the most recent phase result.
+
+        Returns:
+            Phase result dictionary or None if no phase files exist
+        """
+        # List all phase files
+        phase_files = sorted([f for f in os.listdir(self.state_dir) if f.endswith(".json")])
+
+        if not phase_files:
+            return None
+
+        # Load the latest (last in sorted order)
+        latest_file = phase_files[-1]
+        latest_path = os.path.join(self.state_dir, latest_file)
+
+        return load_phase_result(latest_path)
+
+    def get_state_dir(self) -> str:
+        """Get the command state directory path."""
+        return self.state_dir

moai_adk/core/diagnostics/slash_commands.py

@@ -1,4 +1,3 @@
-# @CODE:CLAUDE-COMMANDS-001:DIAGNOSTIC | SPEC: SPEC-CLAUDE-COMMANDS-001.md | TEST: tests/unit/test_slash_commands.py
 """Slash command diagnostics
 
 Diagnose and validate Claude Code slash command loading issues.