moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

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

@@ -0,0 +1,268 @@
+"""
+Memory collector for MoAI-ADK statusline
+
+Collects memory usage information for display in the status bar.
+Uses psutil for cross-platform memory monitoring.
+"""
+
+import logging
+import os
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MemoryInfo:
+    """Memory usage information"""
+
+    # Process memory (current Python process)
+    process_rss_mb: float  # Resident Set Size
+    process_vms_mb: float  # Virtual Memory Size
+
+    # System memory
+    system_total_mb: float
+    system_available_mb: float
+    system_percent: float
+
+    # Formatted strings for display
+    display_process: str  # e.g., "128MB"
+    display_system: str  # e.g., "8.2GB/16GB"
+    display_percent: str  # e.g., "51%"
+
+    timestamp: datetime
+
+
+class MemoryCollector:
+    """
+    Memory collector for statusline display.
+
+    Features:
+    - Process memory monitoring (current Python process)
+    - System memory monitoring
+    - Caching with configurable TTL
+    - Graceful degradation on errors
+    - Multiple display format options
+    """
+
+    # Cache configuration
+    DEFAULT_CACHE_TTL_SECONDS = 10  # Memory doesn't change rapidly
+
+    def __init__(self, cache_ttl_seconds: Optional[int] = None):
+        """
+        Initialize memory collector.
+
+        Args:
+            cache_ttl_seconds: Cache TTL in seconds. If None, uses default.
+        """
+        self._cache_ttl = timedelta(seconds=cache_ttl_seconds or self.DEFAULT_CACHE_TTL_SECONDS)
+        self._cache: Optional[MemoryInfo] = None
+        self._cache_time: Optional[datetime] = None
+        self._logger = logging.getLogger(__name__)
+
+        # Check if psutil is available
+        self._psutil_available = self._check_psutil()
+
+    def _check_psutil(self) -> bool:
+        """Check if psutil is available."""
+        try:
+            import psutil  # noqa: F401
+
+            return True
+        except ImportError:
+            self._logger.warning("psutil not available, memory monitoring disabled")
+            return False
+
+    def get_memory_info(self, force_refresh: bool = False) -> Optional[MemoryInfo]:
+        """
+        Get memory usage information.
+
+        Args:
+            force_refresh: If True, bypass cache and force fresh collection
+
+        Returns:
+            MemoryInfo object or None if collection fails
+        """
+        if not self._psutil_available:
+            return None
+
+        # Check cache
+        if not force_refresh and self._is_cache_valid():
+            return self._cache
+
+        try:
+            memory_info = self._collect_memory_info()
+            self._update_cache(memory_info)
+            return memory_info
+        except Exception as e:
+            self._logger.error(f"Error collecting memory info: {e}")
+            return self._cache  # Return stale cache on error
+
+    def get_display_string(self, mode: str = "process", force_refresh: bool = False) -> str:
+        """
+        Get formatted memory string for statusline display.
+
+        Args:
+            mode: Display mode
+                - "process": Process memory (e.g., "128MB")
+                - "system": System memory usage (e.g., "8.2GB/16GB")
+                - "percent": System memory percentage (e.g., "51%")
+                - "compact": Process memory compact (e.g., "128M")
+            force_refresh: If True, bypass cache
+
+        Returns:
+            Formatted memory string, or "N/A" on error
+        """
+        memory_info = self.get_memory_info(force_refresh)
+
+        if memory_info is None:
+            return "N/A"
+
+        if mode == "process":
+            return memory_info.display_process
+        elif mode == "system":
+            return memory_info.display_system
+        elif mode == "percent":
+            return memory_info.display_percent
+        elif mode == "compact":
+            # Compact format without "MB" suffix
+            return self._format_compact(memory_info.process_rss_mb)
+        else:
+            return memory_info.display_process
+
+    def _collect_memory_info(self) -> MemoryInfo:
+        """
+        Collect memory information using psutil.
+
+        Returns:
+            MemoryInfo object with current memory usage
+        """
+        import psutil
+
+        # Get current process info
+        process = psutil.Process(os.getpid())
+        process_memory = process.memory_info()
+
+        # Convert to MB
+        process_rss_mb = process_memory.rss / (1024 * 1024)
+        process_vms_mb = process_memory.vms / (1024 * 1024)
+
+        # Get system memory info
+        system_memory = psutil.virtual_memory()
+        system_total_mb = system_memory.total / (1024 * 1024)
+        system_available_mb = system_memory.available / (1024 * 1024)
+        system_percent = system_memory.percent
+
+        # Format display strings
+        display_process = self._format_size(process_rss_mb)
+        display_system = (
+            f"{self._format_size(system_total_mb - system_available_mb)}/{self._format_size(system_total_mb)}"
+        )
+        display_percent = f"{system_percent:.0f}%"
+
+        return MemoryInfo(
+            process_rss_mb=process_rss_mb,
+            process_vms_mb=process_vms_mb,
+            system_total_mb=system_total_mb,
+            system_available_mb=system_available_mb,
+            system_percent=system_percent,
+            display_process=display_process,
+            display_system=display_system,
+            display_percent=display_percent,
+            timestamp=datetime.now(),
+        )
+
+    def _format_size(self, size_mb: float) -> str:
+        """
+        Format size in MB to human-readable string.
+
+        Args:
+            size_mb: Size in megabytes
+
+        Returns:
+            Formatted string (e.g., "128MB", "1.2GB")
+        """
+        if size_mb >= 1024:
+            return f"{size_mb / 1024:.1f}GB"
+        elif size_mb >= 100:
+            return f"{size_mb:.0f}MB"
+        elif size_mb >= 10:
+            return f"{size_mb:.1f}MB"
+        else:
+            return f"{size_mb:.2f}MB"
+
+    def _format_compact(self, size_mb: float) -> str:
+        """
+        Format size in compact format for tight spaces.
+
+        Args:
+            size_mb: Size in megabytes
+
+        Returns:
+            Compact formatted string (e.g., "128M", "1.2G")
+        """
+        if size_mb >= 1024:
+            return f"{size_mb / 1024:.1f}G"
+        else:
+            return f"{size_mb:.0f}M"
+
+    def _is_cache_valid(self) -> bool:
+        """Check if cache is still valid."""
+        if self._cache is None or self._cache_time is None:
+            return False
+
+        age = datetime.now() - self._cache_time
+        return age < self._cache_ttl
+
+    def _update_cache(self, memory_info: MemoryInfo) -> None:
+        """Update cache with new memory info."""
+        self._cache = memory_info
+        self._cache_time = datetime.now()
+
+    def clear_cache(self) -> None:
+        """Clear the memory cache."""
+        self._cache = None
+        self._cache_time = None
+
+    def get_cache_age_seconds(self) -> Optional[float]:
+        """
+        Get cache age in seconds.
+
+        Returns:
+            Cache age in seconds, or None if no cache
+        """
+        if self._cache_time is None:
+            return None
+        return (datetime.now() - self._cache_time).total_seconds()
+
+
+# Singleton instance for convenience
+_default_collector: Optional[MemoryCollector] = None
+
+
+def get_memory_collector() -> MemoryCollector:
+    """
+    Get the default memory collector instance.
+
+    Returns:
+        MemoryCollector singleton instance
+    """
+    global _default_collector
+    if _default_collector is None:
+        _default_collector = MemoryCollector()
+    return _default_collector
+
+
+def get_memory_display(mode: str = "process") -> str:
+    """
+    Convenience function to get memory display string.
+
+    Args:
+        mode: Display mode ("process", "system", "percent", "compact")
+
+    Returns:
+        Formatted memory string
+    """
+    return get_memory_collector().get_display_string(mode)

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

@@ -0,0 +1,78 @@
+# type: ignore
+"""
+Session metrics tracker for statusline
+
+"""
+
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class MetricsTracker:
+    """Tracks session duration with 10-second caching"""
+
+    # Configuration
+    _CACHE_TTL_SECONDS = 10
+
+    def __init__(self):
+        """Initialize metrics tracker"""
+        self._session_start: datetime = datetime.now()
+        self._duration_cache: Optional[str] = None
+        self._cache_time: Optional[datetime] = None
+        self._cache_ttl = timedelta(seconds=self._CACHE_TTL_SECONDS)
+
+    def get_duration(self) -> str:
+        """
+        Get formatted session duration
+
+        Returns:
+            Formatted duration string (e.g., "5m", "1h 30m")
+        """
+        # Check cache validity
+        if self._is_cache_valid():
+            return self._duration_cache
+
+        # Calculate and format duration
+        duration = self._calculate_and_format_duration()
+        self._update_cache(duration)
+        return duration
+
+    def _calculate_and_format_duration(self) -> str:
+        """
+        Calculate session duration and format it
+
+        Returns:
+            Formatted duration string
+        """
+        elapsed = datetime.now() - self._session_start
+        total_seconds = int(elapsed.total_seconds())
+
+        # Format based on duration range
+        if total_seconds < 60:
+            return f"{total_seconds}s"
+        elif total_seconds < 3600:
+            minutes = total_seconds // 60
+            seconds = total_seconds % 60
+            if seconds > 0:
+                return f"{minutes}m {seconds}s"
+            return f"{minutes}m"
+        else:
+            hours = total_seconds // 3600
+            minutes = (total_seconds % 3600) // 60
+            if minutes > 0:
+                return f"{hours}h {minutes}m"
+            return f"{hours}h"
+
+    def _is_cache_valid(self) -> bool:
+        """Check if duration cache is still valid"""
+        if self._duration_cache is None or self._cache_time is None:
+            return False
+        return datetime.now() - self._cache_time < self._cache_ttl
+
+    def _update_cache(self, duration: str) -> None:
+        """Update duration cache"""
+        self._duration_cache = duration
+        self._cache_time = datetime.now()

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: Path | None = 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: Path | None = 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