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

moai_adk/templates/.claude/hooks/moai/lib/README.md

@@ -0,0 +1,143 @@
+# MoAI-ADK Hooks Library
+
+Shared utilities for Claude Code hooks in MoAI-ADK.
+
+## Module Overview
+
+```
+lib/
+├── __init__.py           # Package exports
+├── common.py             # Shared utilities (format_duration, merge_configs)
+├── config_manager.py     # Configuration loading and management
+├── config_validator.py   # Configuration schema validation
+├── exceptions.py         # Exception hierarchy
+├── models.py             # Data structures (HookPayload, HookResult)
+├── path_utils.py         # Project root detection, safe paths
+├── project.py            # Project metadata (language, Git, SPEC)
+├── timeout.py            # Cross-platform timeout (Windows/Unix)
+├── unified_timeout_manager.py  # Advanced timeout with retry
+├── git_operations_manager.py   # Optimized Git operations
+├── checkpoint.py         # Risky operation detection
+├── language_validator.py # Language config validation
+└── tool_registry.py      # Formatter/linter tool registry
+```
+
+## Exit Codes
+
+| Code | Meaning | Usage |
+|------|---------|-------|
+| 0 | Success | Normal completion |
+| 1 | Warning/Error | Non-critical error, logged |
+| 2 | Critical Error | Blocks operation |
+| 3 | Configuration Error | Invalid config |
+
+## Exception Hierarchy
+
+```
+HooksBaseError (base)
+├── TimeoutError
+│   └── HookTimeoutError (with context)
+├── GitOperationError
+├── ConfigurationError
+├── ValidationError
+└── SecurityError
+```
+
+## Key Functions
+
+### Path Management (`path_utils.py`)
+
+```python
+from lib.path_utils import find_project_root, get_safe_moai_path
+
+# Find project root (with caching)
+root = find_project_root()
+
+# Get safe path within .moai/
+cache_path = get_safe_moai_path("cache/version.json")
+```
+
+### Configuration (`config_manager.py`)
+
+```python
+from lib.config_manager import ConfigManager, get_config
+
+# Load configuration
+config = ConfigManager().load_config()
+
+# Get specific value
+timeout = get_config("hooks.timeout_ms", default=5000)
+```
+
+### Timeout Handling (`timeout.py`, `unified_timeout_manager.py`)
+
+```python
+# Basic timeout
+from lib.timeout import CrossPlatformTimeout
+
+with CrossPlatformTimeout(5):
+    long_running_operation()
+
+# Advanced timeout with retry
+from lib.unified_timeout_manager import get_timeout_manager
+
+manager = get_timeout_manager()
+result = manager.execute_with_timeout("hook_name", func, config=config)
+```
+
+### Common Utilities (`common.py`)
+
+```python
+from lib.common import merge_configs, format_duration
+
+# Merge configs recursively
+merged = merge_configs(base_config, override_config)
+
+# Format duration
+formatted = format_duration(125.5)  # "2.1m"
+```
+
+## Configuration Files
+
+### Main Config
+Location: `.moai/config/config.yaml`
+
+### Section Files
+Location: `.moai/config/sections/`
+- `user.yaml` - User name
+- `language.yaml` - Language preferences
+- `project.yaml` - Project metadata
+- `git-strategy.yaml` - Git workflow
+- `quality.yaml` - TDD settings
+
+## Hook Data Flow
+
+```
+Claude Code Event
+    ↓
+stdin (JSON)
+    ↓
+Hook Process
+    ↓
+stdout (JSON response)
+    ↓
+Claude Code
+```
+
+### Response Format
+
+```json
+{
+  "continue": true,
+  "systemMessage": "...",
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow|deny|ask"
+  }
+}
+```
+
+## Version
+
+- Library Version: 1.0.0
+- Last Updated: 2025-01

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

@@ -1,85 +1,41 @@
+# type: ignore
 """
-Hook utilities library - Optimized and consolidated
+Statusline module for Claude Code status display
 
-This module provides centralized access to all hook-related utilities:
-- Configuration management (ConfigManager)
-- Core utilities (timeout, common utilities)
-- Data models (HookPayload, HookResult)
-- Project utilities (language detection, git info, SPEC counting)
-- Checkpoint utilities (risky operation detection, checkpoint creation)
-"""
-
-try:
-    # Import core components
-    # Import checkpoint utilities
-    from lib.checkpoint import (
-        create_checkpoint,
-        detect_risky_operation,
-        list_checkpoints,
-    )
-
-    # Import utilities
-    from lib.common import (
-        format_duration,
-        get_file_pattern_category,
-        get_summary_stats,
-        is_root_whitelisted,
-        suggest_moai_location,
-    )
-    from lib.config_manager import (
-        ConfigManager,
-        get_config,
-        get_config_manager,
-        get_exit_code,
-        get_graceful_degradation,
-        get_timeout_seconds,
-    )
-
-    # Import models
-    from lib.models import HookPayload, HookResult
+Provides real-time status information display in Claude Code terminal
 
-    # Import project utilities
-    from lib.project import (
-        count_specs,
-        find_project_root,
-        get_git_info,
-    )
-    from lib.timeout import CrossPlatformTimeout, TimeoutError, timeout_context
-
-    __all__ = [
-        # Core - Timeout
-        "CrossPlatformTimeout",
-        "TimeoutError",
-        "timeout_context",
-        # Core - Configuration
-        "ConfigManager",
-        "get_config_manager",
-        "get_config",
-        "get_timeout_seconds",
-        "get_graceful_degradation",
-        "get_exit_code",
-        # Common utilities
-        "format_duration",
-        "get_summary_stats",
-        "is_root_whitelisted",
-        "get_file_pattern_category",
-        "suggest_moai_location",
-        # Models
-        "HookPayload",
-        "HookResult",
-        # Checkpoint
-        "create_checkpoint",
-        "detect_risky_operation",
-        "list_checkpoints",
-        # Project
-        "find_project_root",
-        "get_git_info",
-        "count_specs",
-    ]
-
-except ImportError:
-    # Fallback if not all imports are available
-    __all__ = []
+Enhanced version includes:
+- Improved version reader with caching and error handling
+- Async support for better performance
+- Configurable version reading behavior
+- Comprehensive fallback strategies
+"""
 
-__version__ = "1.0.0"
-__author__ = "MoAI-ADK Team"
+__version__ = "0.1.0"
+
+from .alfred_detector import AlfredDetector, AlfredTask
+from .config import StatuslineConfig
+from .git_collector import GitCollector, GitInfo
+from .memory_collector import MemoryCollector, MemoryInfo
+from .metrics_tracker import MetricsTracker
+from .renderer import StatuslineData, StatuslineRenderer
+from .update_checker import UpdateChecker, UpdateInfo
+from .version_reader import VersionConfig, VersionReader, VersionReadError
+
+__all__ = [
+    "StatuslineRenderer",
+    "StatuslineData",
+    "StatuslineConfig",
+    "GitCollector",
+    "GitInfo",
+    "MemoryCollector",
+    "MemoryInfo",
+    "MetricsTracker",
+    "AlfredDetector",
+    "AlfredTask",
+    "VersionReader",
+    "VersionConfig",
+    "VersionReadError",
+    "UpdateChecker",
+    "UpdateInfo",
+]

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

@@ -0,0 +1,105 @@
+# type: ignore
+"""
+Alfred task detector for statusline
+
+"""
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class AlfredTask:
+    """Alfred task information"""
+
+    command: Optional[str]
+    spec_id: Optional[str]
+    stage: Optional[str]
+
+
+class AlfredDetector:
+    """Detects active Alfred tasks with 1-second caching"""
+
+    # Configuration
+    _CACHE_TTL_SECONDS = 1
+
+    def __init__(self):
+        """Initialize Alfred detector"""
+        self._cache: Optional[AlfredTask] = None
+        self._cache_time: Optional[datetime] = None
+        self._cache_ttl = timedelta(seconds=self._CACHE_TTL_SECONDS)
+        self._session_state_path = Path.home() / ".moai" / "memory" / "last-session-state.json"
+
+    def detect_active_task(self) -> AlfredTask:
+        """
+        Detect currently active Alfred task
+
+        Returns:
+            AlfredTask with command and spec_id
+        """
+        # Check cache
+        if self._is_cache_valid():
+            return self._cache
+
+        # Read and parse session state
+        task = self._read_session_state()
+        self._update_cache(task)
+        return task
+
+    def _read_session_state(self) -> AlfredTask:
+        """
+        Read Alfred task from session state file
+
+        Returns:
+            AlfredTask from file or defaults
+        """
+        try:
+            if not self._session_state_path.exists():
+                return self._create_default_task()
+
+            with open(self._session_state_path, "r") as f:
+                data = json.load(f)
+
+            active_task = data.get("active_task")
+            if active_task is None:
+                return self._create_default_task()
+
+            # Parse command and spec_id
+            command = active_task.get("command")
+            spec_id = active_task.get("spec_id")
+
+            return AlfredTask(
+                command=command,
+                spec_id=spec_id,
+                stage=active_task.get("stage"),
+            )
+
+        except Exception as e:
+            logger.debug(f"Error reading Alfred task: {e}")
+            return self._create_default_task()
+
+    def _is_cache_valid(self) -> bool:
+        """Check if task cache is still valid"""
+        if self._cache is None or self._cache_time is None:
+            return False
+        return datetime.now() - self._cache_time < self._cache_ttl
+
+    def _update_cache(self, task: AlfredTask) -> None:
+        """Update task cache"""
+        self._cache = task
+        self._cache_time = datetime.now()
+
+    @staticmethod
+    def _create_default_task() -> AlfredTask:
+        """Create default task (no active task)"""
+        return AlfredTask(
+            command=None,
+            spec_id=None,
+            stage=None,
+        )

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Atomic file operations for MoAI hooks.
+
+Provides safe file write operations with atomic semantics
+to prevent race conditions and data corruption.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+# Maximum file size for state/cache files (1MB)
+MAX_STATE_FILE_SIZE = 1024 * 1024  # 1MB
+
+
+def atomic_write_text(
+    file_path: Path | str,
+    content: str,
+    encoding: str = "utf-8",
+    make_dirs: bool = True,
+) -> bool:
+    """Atomically write text content to a file.
+
+    Uses write-to-temp-then-rename pattern to prevent race conditions
+    and partial writes from corrupting data.
+
+    Args:
+        file_path: Path to the file
+        content: Content to write
+        encoding: File encoding (default: utf-8)
+        make_dirs: Create parent directories if needed (default: True)
+
+    Returns:
+        True if write succeeded, False otherwise
+    """
+    path = Path(file_path)
+
+    if make_dirs:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Write to temporary file first
+        fd, temp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp_", suffix=path.suffix or ".tmp")
+        try:
+            # Write content to temp file
+            with os.fdopen(fd, "w", encoding=encoding) as f:
+                f.write(content)
+
+            # Atomic rename (overwrites target if exists)
+            os.replace(temp_path, path)
+            return True
+        except Exception:
+            # Clean up temp file on error
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            return False
+    except (OSError, ValueError):
+        return False
+
+
+def atomic_write_json(
+    file_path: Path | str,
+    data: Any,
+    indent: int = 2,
+    encoding: str = "utf-8",
+    ensure_ascii: bool = True,
+    make_dirs: bool = True,
+) -> bool:
+    """Atomically write JSON data to a file.
+
+    Uses write-to-temp-then-rename pattern to prevent race conditions
+    and partial writes from corrupting data.
+
+    Args:
+        file_path: Path to the file
+        data: Data to serialize as JSON
+        indent: JSON indentation (default: 2)
+        encoding: File encoding (default: utf-8)
+        ensure_ascii: Escape non-ASCII characters (default: True)
+        make_dirs: Create parent directories if needed (default: True)
+
+    Returns:
+        True if write succeeded, False otherwise
+    """
+    path = Path(file_path)
+
+    if make_dirs:
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        # Write to temporary file first
+        fd, temp_path = tempfile.mkstemp(dir=path.parent, prefix=".tmp_", suffix=".json")
+        try:
+            # Write JSON to temp file
+            with os.fdopen(fd, "w", encoding=encoding) as f:
+                json.dump(data, f, indent=indent, ensure_ascii=ensure_ascii)
+
+            # Atomic rename (overwrites target if exists)
+            os.replace(temp_path, path)
+            return True
+        except Exception:
+            # Clean up temp file on error
+            try:
+                os.unlink(temp_path)
+            except OSError:
+                pass
+            return False
+    except (OSError, ValueError, TypeError):
+        return False
+
+
+__all__ = [
+    "MAX_STATE_FILE_SIZE",
+    "atomic_write_text",
+    "atomic_write_json",
+]

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

@@ -70,9 +70,12 @@ def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str)
         critical_files = [
             "CLAUDE.md",
             "config.json",
+            "config.yaml",
             ".claude/skills/moai-core-dev-guide/reference.md",
             ".claude/skills/moai-core-spec-metadata-extended/reference.md",
-            ".moai/config/config.json",
+            ".moai/config/config.json",  # Legacy monolithic config
+            ".moai/config/config.yaml",  # Legacy monolithic config
+            ".moai/config/sections/",  # Section-based config (any file in sections/)
         ]
 
         if any(cf in file_path for cf in critical_files):

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

@@ -3,9 +3,39 @@
 Consolidated fallback implementations used across multiple hooks.
 """
 
+from __future__ import annotations
+
 import re
 import statistics
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any
+
+
+def merge_configs(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge configuration dictionaries.
+
+    Deep merges two configuration dictionaries, with override values
+    taking precedence. Nested dictionaries are merged recursively.
+
+    Args:
+        base: Base configuration dictionary
+        override: Override configuration dictionary (values take precedence)
+
+    Returns:
+        Merged configuration dictionary
+
+    Examples:
+        >>> base = {"a": 1, "b": {"c": 2}}
+        >>> override = {"b": {"d": 3}}
+        >>> merge_configs(base, override)
+        {'a': 1, 'b': {'c': 2, 'd': 3}}
+    """
+    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 format_duration(seconds: float) -> str:
@@ -28,7 +58,7 @@ def format_duration(seconds: float) -> str:
     return f"{hours:.1f}h"
 
 
-def get_summary_stats(values: List[float]) -> Dict[str, float]:
+def get_summary_stats(values: list[float]) -> dict[str, float]:
     """Get summary statistics for a list of values.
 
     Calculates mean, min, max, and standard deviation.
@@ -50,7 +80,7 @@ def get_summary_stats(values: List[float]) -> Dict[str, float]:
     }
 
 
-def is_root_whitelisted(filename: str, config: Dict[str, Any]) -> bool:
+def is_root_whitelisted(filename: str, config: dict[str, Any]) -> bool:
     """Check if file is allowed in project root.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
@@ -73,7 +103,7 @@ def is_root_whitelisted(filename: str, config: Dict[str, Any]) -> bool:
     return False
 
 
-def get_file_pattern_category(filename: str, config: Dict[str, Any]) -> Optional[Tuple[str, str]]:
+def get_file_pattern_category(filename: str, config: dict[str, Any]) -> tuple[str, str] | None:
     """Match filename against patterns to determine category.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
@@ -98,7 +128,7 @@ def get_file_pattern_category(filename: str, config: Dict[str, Any]) -> Optional
     return None
 
 
-def suggest_moai_location(filename: str, config: Dict[str, Any]) -> str:
+def suggest_moai_location(filename: str, config: dict[str, Any]) -> str:
     """Suggest appropriate .moai/ location based on file pattern.
 
     Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py