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

moai_adk/templates/.claude/hooks/moai/lib/language_validator.py

@@ -10,25 +10,110 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List
 
+try:
+    import yaml
+
+    YAML_AVAILABLE = True
+except ImportError:
+    YAML_AVAILABLE = False
 
-def load_config() -> Dict[str, Any]:
-    """Load configuration from .moai/config/config.json
+
+def _load_yaml_file(file_path: Path) -> Dict[str, Any]:
+    """Load a YAML file safely with fallback to empty dict.
+
+    Args:
+        file_path: Path to the YAML file
 
     Returns:
-        Configuration dictionary or empty dict if not found
+        Parsed YAML content or empty dict on failure
     """
-    config_path = Path(".moai/config/config.json")
+    if not file_path.exists():
+        return {}
+    if not YAML_AVAILABLE:
+        return {}
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            return yaml.safe_load(f) or {}
+    except Exception:
+        return {}
 
-    if not config_path.exists():
-        return {"error": "Configuration file not found"}
 
-    try:
-        with open(config_path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except json.JSONDecodeError as e:
-        return {"error": f"JSON decode error: {e}"}
-    except Exception as e:
-        return {"error": f"File read error: {e}"}
+def _merge_configs(base: Dict[str, Any], override: Dict[str, Any]) -> Dict[str, Any]:
+    """Recursively merge two configuration dictionaries.
+
+    Args:
+        base: Base configuration dictionary
+        override: Override configuration dictionary
+
+    Returns:
+        Merged configuration dictionary
+    """
+    result = base.copy()
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _merge_configs(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_config() -> Dict[str, Any]:
+    """Load configuration from section YAML files with fallbacks.
+
+    Priority:
+    1. Section files (.moai/config/sections/*.yaml)
+    2. Main config.yaml
+    3. Legacy config.json
+
+    Returns:
+        Configuration dictionary or dict with 'error' key if not found
+    """
+    config_dir = Path(".moai/config")
+    sections_dir = config_dir / "sections"
+
+    config: Dict[str, Any] = {}
+
+    # Try section-based configuration first (new approach)
+    if sections_dir.exists() and sections_dir.is_dir():
+        section_files = [
+            ("language.yaml", "language"),
+            ("user.yaml", "user"),
+            ("project.yaml", "project"),
+            ("system.yaml", "system"),
+            ("git-strategy.yaml", "git_strategy"),
+            ("quality.yaml", "quality"),
+        ]
+        for filename, _key in section_files:
+            section_path = sections_dir / filename
+            section_data = _load_yaml_file(section_path)
+            if section_data:
+                config = _merge_configs(config, section_data)
+        if config:
+            return config
+
+    # Fallback to main config.yaml
+    yaml_config_path = config_dir / "config.yaml"
+    if yaml_config_path.exists() and YAML_AVAILABLE:
+        try:
+            with open(yaml_config_path, "r", encoding="utf-8") as f:
+                config = yaml.safe_load(f) or {}
+                if config:
+                    return config
+        except Exception:
+            pass
+
+    # Legacy fallback to config.json
+    json_config_path = config_dir / "config.json"
+    if json_config_path.exists():
+        try:
+            with open(json_config_path, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            return {"error": f"JSON decode error: {e}"}
+        except Exception as e:
+            return {"error": f"File read error: {e}"}
+
+    return {"error": "Configuration file not found"}
 
 
 def validate_language_config(config: Dict[str, Any]) -> Dict[str, Any]:
@@ -137,7 +222,12 @@ def validate_output_style_compatibility() -> Dict[str, Any]:
             ]
 
             result["language_support_present"] = any(keyword in content for keyword in language_keywords)
-            result["config_reading_present"] = ".moai/config/config.json" in content
+            # Check for config reading (supports both YAML sections and legacy JSON)
+            result["config_reading_present"] = (
+                ".moai/config/sections" in content
+                or ".moai/config/config.yaml" in content
+                or ".moai/config/config.json" in content
+            )
 
             if not result["language_support_present"]:
                 recommendations.append("Add language support documentation to R2-D2 output style")

moai_adk/templates/.claude/hooks/moai/lib/models.py

@@ -5,8 +5,10 @@ Provides HookPayload and HookResult classes used by hook handlers
 to process events and return execution results to Claude Code.
 """
 
+from __future__ import annotations
+
 from dataclasses import asdict, dataclass
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 
 class HookPayload(dict):
@@ -27,7 +29,7 @@ class HookPayload(dict):
         working_dir = payload.get("cwd", ".")
     """
 
-    def __init__(self, data: Optional[Dict[str, Any]] = None):
+    def __init__(self, data: dict[str, Any] | None = None):
         """Initialize HookPayload with optional data dictionary."""
         super().__init__(data or {})
 
@@ -39,7 +41,7 @@ class HookPayload(dict):
         """Set value in payload."""
         super().__setitem__(key, value)
 
-    def update(self, other: Dict[str, Any]) -> None:  # type: ignore[override]
+    def update(self, other: dict[str, Any]) -> None:  # type: ignore[override]
         """Update payload with another dictionary."""
         super().update(other)
 
@@ -77,10 +79,10 @@ class HookResult:
         )
     """
 
-    system_message: Optional[str] = None
+    system_message: str | None = None
     continue_execution: bool = True
-    context_files: List[str] = None
-    hook_specific_output: Optional[Dict[str, Any]] = None
+    context_files: list[str] = None  # type: ignore[assignment]
+    hook_specific_output: dict[str, Any] | None = None
     block_execution: bool = False
 
     def __post_init__(self):
@@ -90,7 +92,7 @@ class HookResult:
         if self.hook_specific_output is None:
             self.hook_specific_output = {}
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """
         Convert HookResult to a dictionary for JSON serialization.
 

moai_adk/templates/.claude/hooks/moai/lib/path_utils.py

@@ -1,28 +1,219 @@
-"""Path utility functions for MoAI-ADK hooks"""
+"""Path utility functions for MoAI-ADK hooks
 
+Provides safe project root detection and .moai directory management.
+Prevents .moai directory creation outside of project root.
+
+Environment Variables:
+- MOAI_PROJECT_ROOT: Override project root detection (absolute path)
+- CLAUDE_PROJECT_DIR: Claude Code project directory (fallback)
+"""
+
+from __future__ import annotations
+
+import os
 from pathlib import Path
+from typing import Optional
+
+# Project root markers (files/dirs that indicate project root)
+PROJECT_ROOT_MARKERS = [
+    ".moai/config/config.yaml",  # Primary: MoAI config
+    ".moai/config/sections",  # Section-based config
+    "CLAUDE.md",  # Claude Code project marker
+    ".claude",  # Claude directory
+    ".git",  # Git repository root
+    "pyproject.toml",  # Python project
+    "package.json",  # Node.js project
+    "Cargo.toml",  # Rust project
+    "go.mod",  # Go project
+]
 
+# Cache for project root to avoid repeated filesystem traversals
+_project_root_cache: Optional[Path] = None
 
-def find_project_root() -> Path:
+
+def get_project_root_from_env() -> Optional[Path]:
+    """Get project root from environment variables.
+
+    Checks in order:
+    1. MOAI_PROJECT_ROOT - explicit override
+    2. CLAUDE_PROJECT_DIR - Claude Code's project directory
+
+    Returns:
+        Path if valid directory found, None otherwise
     """
-    Find project root by locating .moai directory.
+    # Check MOAI_PROJECT_ROOT first (explicit override)
+    moai_root = os.environ.get("MOAI_PROJECT_ROOT")
+    if moai_root:
+        root_path = Path(moai_root).resolve()
+        if root_path.is_dir():
+            return root_path
 
-    Starts from current file location and traverses upward
-    until .moai directory is found.
+    # Check CLAUDE_PROJECT_DIR (Claude Code sets this)
+    claude_dir = os.environ.get("CLAUDE_PROJECT_DIR")
+    if claude_dir:
+        root_path = Path(claude_dir).resolve()
+        if root_path.is_dir():
+            return root_path
+
+    return None
+
+
+def find_project_root(start_path: Optional[Path] = None) -> Path:
+    """Find project root by locating project markers.
+
+    Search order:
+    1. Environment variables (MOAI_PROJECT_ROOT, CLAUDE_PROJECT_DIR)
+    2. Traverse upward from start_path looking for project markers
+    3. Fallback to current working directory
+
+    Args:
+        start_path: Starting directory for search (defaults to current file location)
 
     Returns:
-        Path: Project root directory containing .moai/
+        Path: Project root directory
 
-    Fallback:
-        Returns Path.cwd() if .moai not found
+    Note:
+        Results are cached for performance. Use clear_project_root_cache()
+        to force re-detection.
     """
-    current = Path(__file__).resolve().parent
+    global _project_root_cache
+
+    # Return cached result if available
+    if _project_root_cache is not None:
+        return _project_root_cache
+
+    # Check environment variables first
+    env_root = get_project_root_from_env()
+    if env_root:
+        _project_root_cache = env_root
+        return env_root
 
-    # Traverse upward to find .moai directory
+    # Determine starting point
+    if start_path is None:
+        start_path = Path(__file__).resolve().parent
+    else:
+        start_path = Path(start_path).resolve()
+
+    # Traverse upward to find project markers
+    current = start_path
     while current != current.parent:
-        if (current / ".moai").is_dir():
-            return current
+        for marker in PROJECT_ROOT_MARKERS:
+            marker_path = current / marker
+            if marker_path.exists():
+                _project_root_cache = current
+                return current
         current = current.parent
 
     # Fallback to current working directory
-    return Path.cwd()
+    cwd = Path.cwd()
+    _project_root_cache = cwd
+    return cwd
+
+
+def clear_project_root_cache() -> None:
+    """Clear the cached project root.
+
+    Use when project root may have changed (e.g., after directory change).
+    """
+    global _project_root_cache
+    _project_root_cache = None
+
+
+def get_moai_dir() -> Path:
+    """Get the .moai directory path in project root.
+
+    Returns:
+        Path: Absolute path to .moai directory
+
+    Note:
+        Does NOT create the directory. Use ensure_moai_dir() for that.
+    """
+    return find_project_root() / ".moai"
+
+
+def ensure_moai_dir(subpath: str = "") -> Path:
+    """Ensure .moai subdirectory exists in project root.
+
+    Creates the directory structure if it doesn't exist.
+    ONLY creates within project root to prevent pollution.
+
+    Args:
+        subpath: Subdirectory path within .moai (e.g., "cache", "logs/sessions")
+
+    Returns:
+        Path: Absolute path to the directory
+
+    Raises:
+        ValueError: If attempting to create outside project root
+    """
+    project_root = find_project_root()
+    moai_dir = project_root / ".moai"
+
+    if subpath:
+        target_dir = moai_dir / subpath
+    else:
+        target_dir = moai_dir
+
+    # Safety check: ensure target is within project root
+    try:
+        target_dir.resolve().relative_to(project_root.resolve())
+    except ValueError:
+        raise ValueError(f"Cannot create .moai directory outside project root: {target_dir}")
+
+    # Create directory if it doesn't exist
+    target_dir.mkdir(parents=True, exist_ok=True)
+    return target_dir
+
+
+def is_within_project_root(path: Path) -> bool:
+    """Check if a path is within the project root.
+
+    Args:
+        path: Path to check
+
+    Returns:
+        True if path is within project root, False otherwise
+    """
+    project_root = find_project_root()
+    try:
+        Path(path).resolve().relative_to(project_root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def get_safe_moai_path(relative_path: str) -> Path:
+    """Get absolute path within .moai directory safely.
+
+    This is the recommended way to get paths within .moai.
+    Always returns absolute path based on project root.
+
+    Args:
+        relative_path: Path relative to .moai (e.g., "cache/version.json")
+
+    Returns:
+        Path: Absolute path within project root's .moai directory
+
+    Example:
+        >>> get_safe_moai_path("logs/sessions")
+        PosixPath('/path/to/project/.moai/logs/sessions')
+
+        >>> get_safe_moai_path("memory/last-session-state.json")
+        PosixPath('/path/to/project/.moai/memory/last-session-state.json')
+    """
+    return find_project_root() / ".moai" / relative_path
+
+
+def validate_cwd_is_project_root() -> bool:
+    """Validate that current working directory is the project root.
+
+    Returns:
+        True if CWD is project root, False otherwise
+
+    Use Case:
+        Hooks should check this before creating .moai directories
+        to prevent creating them in wrong locations.
+    """
+    cwd = Path.cwd().resolve()
+    project_root = find_project_root().resolve()
+    return cwd == project_root

moai_adk/templates/.claude/hooks/moai/lib/project.py

@@ -25,16 +25,27 @@ except ImportError:
         pass
 
 
+# Import find_project_root from path_utils (canonical implementation)
+# This consolidates project root detection to a single source of truth
+try:
+    from lib.path_utils import find_project_root as _canonical_find_project_root
+except ImportError:
+    # Fallback if path_utils not available
+    _canonical_find_project_root = None  # type: ignore
+
+
 # Cache directory for version check results
 CACHE_DIR_NAME = ".moai/cache"
 
 
 def find_project_root(start_path: str | Path = ".") -> Path:
-    """Find MoAI-ADK project root by searching upward for .moai/config/config.yaml
+    """Find MoAI-ADK project root by searching upward for project markers.
 
-    Traverses up the directory tree until it finds .moai/config/config.yaml or CLAUDE.md,
-    which indicates the project root. This ensures cache and other files are
-    always created in the correct location, regardless of where hooks execute.
+    This is a wrapper around path_utils.find_project_root() for backward compatibility.
+    The canonical implementation in path_utils provides:
+    - Environment variable support (MOAI_PROJECT_ROOT, CLAUDE_PROJECT_DIR)
+    - Caching for performance
+    - Multiple project marker detection
 
     Args:
         start_path: Starting directory (default: current directory)
@@ -48,17 +59,15 @@ def find_project_root(start_path: str | Path = ".") -> Path:
         >>> find_project_root(".claude/hooks/alfred")
         Path("/Users/user/my-project")  # Found root 3 levels up
 
-    Notes:
-        - Searches for .moai/config/config.yaml first (most reliable)
-        - Falls back to CLAUDE.md if config.yaml not found
-        - Max depth: 10 levels up (prevent infinite loop)
-        - Returns absolute path for consistency
-
-    TDD History:
-        - RED: 4 test scenarios (root, nested, not found, symlinks)
-        - GREEN: Minimal upward search with .moai/config/config.yaml detection
-        - REFACTOR: Add CLAUDE.md fallback, max depth limit, absolute path return
+    Note:
+        For new code, prefer using path_utils.find_project_root() directly.
     """
+    # Use canonical implementation if available
+    if _canonical_find_project_root is not None:
+        path = Path(start_path).resolve() if start_path != "." else None
+        return _canonical_find_project_root(path)
+
+    # Fallback implementation if path_utils not available
     current = Path(start_path).resolve()
     max_depth = 10  # Prevent infinite loop