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

moai_adk/templates/.claude/hooks/moai/pre_tool__tdd_enforcer.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""PreToolUse Hook: TDD Enforcement - Check test exists before code write.
+
+Enforces test-first development by checking for test files before allowing
+code writes for Python, TypeScript, and JavaScript.
+
+Exit Codes:
+- 0: Allow write (test exists or warning mode)
+- 2: Ask user confirmation (enforce mode, no test)
+"""
+
+import json
+import sys
+from pathlib import Path
+
+# Setup import path for shared modules
+HOOKS_DIR = Path(__file__).parent
+LIB_DIR = HOOKS_DIR / "lib"
+if str(LIB_DIR) not in sys.path:
+    sys.path.insert(0, str(LIB_DIR))
+
+try:
+    from language_detector import detect_language, get_test_file_path
+except ImportError:
+    # Fallback implementations
+    def detect_language(file_path: Path) -> str | None:
+        ext = file_path.suffix.lower()
+        lang_map = {
+            ".py": "Python",
+            ".ts": "TypeScript",
+            ".tsx": "TypeScript",
+            ".js": "JavaScript",
+            ".jsx": "JavaScript",
+        }
+        return lang_map.get(ext)
+
+    def get_test_file_path(source_file: Path) -> Path | None:
+        stem = source_file.stem
+        ext = source_file.suffix
+
+        if ext == ".py":
+            return Path("tests") / f"test_{stem}.py"
+        elif ext in (".ts", ".tsx", ".js", ".jsx"):
+            return source_file.parent / f"{stem}.test{ext}"
+        return None
+
+
+# File patterns to skip (no test needed)
+SKIP_PATTERNS = [
+    "/test/",
+    "_test.",
+    "_spec.",
+    ".test.",
+    ".spec.",
+    "config/",
+    "configs/",
+    "docs/",
+    "doc/",
+    ".md",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".lock",
+    ".min.",
+    "__tests__/",
+    "__mocks__/",
+]
+
+# Mode configuration
+MODES = ["warn", "enforce", "off"]
+
+
+def get_tdd_mode() -> str:
+    """Get TDD enforcement mode from quality.yaml."""
+    config_path = Path(".moai/config/sections/quality.yaml")
+    if config_path.exists():
+        try:
+            import yaml
+
+            with open(config_path) as f:
+                config = yaml.safe_load(f)
+                mode = config.get("constitution", {}).get("tdd_mode", "warn")
+                if mode in MODES:
+                    return mode
+        except Exception:
+            pass
+    return "warn"
+
+
+def should_skip_file(file_path: str) -> bool:
+    """Check if file should skip TDD enforcement.
+
+    Args:
+        file_path: Path to the file
+
+    Returns:
+        True if should skip, False otherwise
+    """
+    path_lower = file_path.lower()
+
+    for pattern in SKIP_PATTERNS:
+        if pattern.lower() in path_lower:
+            return True
+
+    return False
+
+
+def main():
+    """Main hook logic."""
+    # Read hook input
+    try:
+        input_data = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        # No input or invalid JSON - allow write
+        print(json.dumps({}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Only check Write operations
+    if tool_name != "Write":
+        print(json.dumps({}))
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        print(json.dumps({}))
+        sys.exit(0)
+
+    # Check if should skip
+    if should_skip_file(file_path):
+        print(json.dumps({}))
+        sys.exit(0)
+
+    # Detect language
+    language = detect_language(Path(file_path))
+    if not language:
+        # Unknown language - skip silently
+        print(json.dumps({}))
+        sys.exit(0)
+
+    # Only support Python, TypeScript, JavaScript
+    if language not in ("Python", "TypeScript", "JavaScript"):
+        print(json.dumps({}))
+        sys.exit(0)
+
+    # Get expected test file path
+    test_file = get_test_file_path(Path(file_path))
+    if not test_file:
+        print(json.dumps({}))
+        sys.exit(0)
+
+    # Check if test file exists
+    test_path = Path(test_file)
+    test_exists = test_path.exists()
+
+    # Get TDD mode
+    mode = get_tdd_mode()
+
+    if mode == "off":
+        print(json.dumps({}))
+        sys.exit(0)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",  # Default: allow write
+        }
+    }
+
+    if test_exists:
+        # Test file exists - allow write
+        output["hookSpecificOutput"]["additionalContext"] = f"TDD check passed for {language}: {test_file} exists"
+        print(json.dumps(output))
+        sys.exit(0)
+
+    # No test file - handle based on mode
+    if mode == "warn":
+        output["hookSpecificOutput"]["permissionDecision"] = "allow"
+        output["hookSpecificOutput"]["permissionDecisionReason"] = (
+            f"TDD Reminder ({language}): Test file not found.\n"
+            f"Expected: {test_file}\n"
+            f"Best practice: Write test first, then implement code.\n"
+            f"Continuing with code write..."
+        )
+        print(json.dumps(output))
+        sys.exit(0)
+
+    elif mode == "enforce":
+        output["hookSpecificOutput"]["permissionDecision"] = "ask"
+        output["hookSpecificOutput"]["permissionDecisionReason"] = (
+            f"TDD Enforcement ({language}): Test file required.\n\n"
+            f"Please create test file first:\n"
+            f"1. Create {test_file}\n"
+            f"2. Write test cases\n"
+            f"3. Then implement code\n\n"
+            f"Or configure tdd_mode: warn in quality.yaml to disable enforcement."
+        )
+        print(json.dumps(output))
+        sys.exit(2)  # Ask user for confirmation
+
+    print(json.dumps({}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

moai_adk/templates/.claude/hooks/moai/session_end__auto_cleanup.py

@@ -18,6 +18,8 @@ Features:
 - Generate session summary message
 """
 
+from __future__ import annotations
+
 import json
 import logging
 import shutil
@@ -26,12 +28,29 @@ import sys
 import time
 from datetime import datetime, timedelta
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any
+
+# =============================================================================
+# Windows UTF-8 Encoding Fix (Issue #249)
+# Ensures emoji characters are properly displayed on Windows terminals
+# =============================================================================
+if sys.platform == "win32":
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, OSError):
+        # Python < 3.7 or reconfigure not available
+        pass
 
 # Add module path
 sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "src"))
 
-from lib.path_utils import find_project_root  # noqa: E402
+from lib.atomic_write import atomic_write_json  # noqa: E402
+from lib.path_utils import (  # noqa: E402
+    ensure_moai_dir,
+    find_project_root,
+    get_safe_moai_path,
+)
 
 # Import unified timeout manager and Git operations manager
 try:
@@ -120,40 +139,52 @@ logger = logging.getLogger(__name__)
 
 
 def load_hook_timeout() -> int:
-    """Load hook timeout from config.json (default: 5000ms)
+    """Load hook timeout from config.yaml (default: 5000ms)
+
+    Uses try/except instead of exists() check to prevent TOCTOU race conditions.
 
     Returns:
         Timeout in milliseconds
     """
     try:
-        config_file = Path(".moai/config/config.yaml")
-        if config_file.exists():
-            with open(config_file, "r", encoding="utf-8") as f:
-                config: Dict[str, Any] = json.load(f)
-                return config.get("hooks", {}).get("timeout_ms", 5000)
+        import yaml
+
+        config_file = get_safe_moai_path("config/config.yaml")
+        # Direct open without exists() check to prevent race condition
+        with open(config_file, "r", encoding="utf-8") as f:
+            config: dict[str, Any] = yaml.safe_load(f) or {}
+            return config.get("hooks", {}).get("timeout_ms", 5000)
+    except FileNotFoundError:
+        pass  # Config file doesn't exist, use default
     except Exception:
-        pass
+        pass  # Config file corrupted or invalid, use default
     return 5000
 
 
 def get_graceful_degradation() -> bool:
-    """Load graceful_degradation setting from config.json (default: true)
+    """Load graceful_degradation setting from config.yaml (default: true)
+
+    Uses try/except instead of exists() check to prevent TOCTOU race conditions.
 
     Returns:
         Whether graceful degradation is enabled
     """
     try:
-        config_file = Path(".moai/config/config.yaml")
-        if config_file.exists():
-            with open(config_file, "r", encoding="utf-8") as f:
-                config: Dict[str, Any] = json.load(f)
-                return config.get("hooks", {}).get("graceful_degradation", True)
+        import yaml
+
+        config_file = get_safe_moai_path("config/config.yaml")
+        # Direct open without exists() check to prevent race condition
+        with open(config_file, "r", encoding="utf-8") as f:
+            config: dict[str, Any] = yaml.safe_load(f) or {}
+            return config.get("hooks", {}).get("graceful_degradation", True)
+    except FileNotFoundError:
+        pass  # Config file doesn't exist, use default
     except Exception:
-        pass
+        pass  # Config file corrupted or invalid, use default
     return True
 
 
-def cleanup_old_files(config: Dict[str, Any]) -> Dict[str, int]:
+def cleanup_old_files(config: dict[str, Any]) -> dict[str, int]:
     """Clean up old files
 
     Args:
@@ -172,13 +203,13 @@ def cleanup_old_files(config: Dict[str, Any]) -> Dict[str, int]:
         cleanup_days = cleanup_config.get("cleanup_days", 7)
         cutoff_date = datetime.now() - timedelta(days=cleanup_days)
 
-        # Clean up temporary files
-        temp_dir = Path(".moai/temp")
+        # Clean up temporary files (use safe path to prevent creation in wrong directory)
+        temp_dir = get_safe_moai_path("temp")
         if temp_dir.exists():
             stats["temp_cleaned"] = cleanup_directory(temp_dir, cutoff_date, None, patterns=["*"])
 
-        # Clean up cache files
-        cache_dir = Path(".moai/cache")
+        # Clean up cache files (use safe path to prevent creation in wrong directory)
+        cache_dir = get_safe_moai_path("cache")
         if cache_dir.exists():
             stats["cache_cleaned"] = cleanup_directory(cache_dir, cutoff_date, None, patterns=["*"])
 
@@ -193,8 +224,8 @@ def cleanup_old_files(config: Dict[str, Any]) -> Dict[str, int]:
 def cleanup_directory(
     directory: Path,
     cutoff_date: datetime,
-    max_files: Optional[int],
-    patterns: List[str],
+    max_files: int | None,
+    patterns: list[str],
 ) -> int:
     """Clean up directory files
 
@@ -246,7 +277,7 @@ def cleanup_directory(
     return cleaned_count
 
 
-def save_session_metrics(payload: Dict[str, Any]) -> bool:
+def save_session_metrics(payload: dict[str, Any]) -> bool:
     """Save session metrics (P0-1)
 
     Args:
@@ -256,9 +287,8 @@ def save_session_metrics(payload: Dict[str, Any]) -> bool:
         Success status
     """
     try:
-        # Create logs directory
-        logs_dir = Path(".moai/logs/sessions")
-        logs_dir.mkdir(parents=True, exist_ok=True)
+        # Create logs directory (use ensure_moai_dir for safe creation in project root)
+        logs_dir = ensure_moai_dir("logs/sessions")
 
         # Collect session information
         session_metrics = {
@@ -270,10 +300,9 @@ def save_session_metrics(payload: Dict[str, Any]) -> bool:
             "specs_worked_on": extract_specs_from_memory(),
         }
 
-        # Save session metrics
+        # Save session metrics using atomic write (H3)
         session_file = logs_dir / f"session-{session_metrics['session_id']}.json"
-        with open(session_file, "w", encoding="utf-8") as f:
-            json.dump(session_metrics, f, indent=2, ensure_ascii=False)
+        atomic_write_json(session_file, session_metrics, indent=2, ensure_ascii=False)
 
         logger.info(f"Session metrics saved: {session_file}")
         return True
@@ -283,7 +312,7 @@ def save_session_metrics(payload: Dict[str, Any]) -> bool:
         return False
 
 
-def save_work_state(payload: Dict[str, Any]) -> bool:
+def save_work_state(payload: dict[str, Any]) -> bool:
     """Save work state snapshot (P0-2)
 
     Args:
@@ -293,9 +322,8 @@ def save_work_state(payload: Dict[str, Any]) -> bool:
         Success status
     """
     try:
-        # Create memory directory
-        memory_dir = Path(".moai/memory")
-        memory_dir.mkdir(parents=True, exist_ok=True)
+        # Create memory directory (use ensure_moai_dir for safe creation in project root)
+        ensure_moai_dir("memory")
 
         # Collect work state
         work_state = {
@@ -306,10 +334,9 @@ def save_work_state(payload: Dict[str, Any]) -> bool:
             "specs_in_progress": extract_specs_from_memory(),
         }
 
-        # Save state
-        state_file = memory_dir / "last-session-state.json"
-        with open(state_file, "w", encoding="utf-8") as f:
-            json.dump(work_state, f, indent=2, ensure_ascii=False)
+        # Save work state using atomic write (H3)
+        state_file = get_safe_moai_path("memory/last-session-state.json")
+        atomic_write_json(state_file, work_state, indent=2, ensure_ascii=False)
 
         logger.info(f"Work state saved: {state_file}")
         return True
@@ -319,7 +346,7 @@ def save_work_state(payload: Dict[str, Any]) -> bool:
         return False
 
 
-def check_uncommitted_changes() -> Optional[str]:
+def check_uncommitted_changes() -> str | None:
     """Warn uncommitted changes (P0-3) using optimized Git operations
 
     Returns:
@@ -367,7 +394,7 @@ def check_uncommitted_changes() -> Optional[str]:
     return None
 
 
-def get_current_branch() -> Optional[str]:
+def get_current_branch() -> str | None:
     """Get current Git branch name using optimized Git operations
 
     Returns:
@@ -487,21 +514,28 @@ def count_recent_commits() -> int:
     return 0
 
 
-def extract_specs_from_memory() -> List[str]:
-    """Extract SPEC information from memory"""
-    specs = []
-
-    try:
-        # Query recent SPECs from command_execution_state.json
-        state_file = Path(".moai/memory/command-execution-state.json")
-        if state_file.exists():
-            with open(state_file, "r", encoding="utf-8") as f:
-                state_data = json.load(f)
+def extract_specs_from_memory() -> list[str]:
+    """Extract SPEC information from memory
 
-            # Extract recent SPEC IDs
-            if "last_specs" in state_data:
-                specs = state_data["last_specs"][:3]  # Latest 3
+    Uses try/except instead of exists() check to prevent TOCTOU race conditions.
+    """
+    specs: list[str] = []
 
+    try:
+        # Query recent SPECs from command_execution_state.json (use safe path)
+        state_file = get_safe_moai_path("memory/command-execution-state.json")
+        # Direct open without exists() check to prevent race condition
+        with open(state_file, "r", encoding="utf-8") as f:
+            state_data = json.load(f)
+
+        # Extract recent SPEC IDs
+        if "last_specs" in state_data:
+            specs = state_data["last_specs"][:3]  # Latest 3
+
+    except FileNotFoundError:
+        pass  # State file doesn't exist yet, return empty list
+    except (json.JSONDecodeError, KeyError, TypeError) as e:
+        logger.warning(f"Failed to parse specs from memory: {e}")
     except Exception as e:
         logger.warning(f"Failed to extract specs from memory: {e}")
 
@@ -512,7 +546,7 @@ def extract_specs_from_memory() -> List[str]:
 # are now imported from lib.common (consolidated from duplicate implementations)
 
 
-def scan_root_violations(config: Dict[str, Any]) -> List[Dict[str, str]]:
+def scan_root_violations(config: dict[str, Any]) -> list[dict[str, str]]:
     """Scan project root for document management violations
 
     Args:
@@ -524,10 +558,8 @@ def scan_root_violations(config: Dict[str, Any]) -> List[Dict[str, str]]:
     violations = []
 
     try:
-        # Get project root
-        project_root = Path(".moai/config/config.yaml").parent.parent
-        if not project_root.exists():
-            project_root = find_project_root()
+        # Get project root (always use find_project_root for consistent behavior)
+        project_root = find_project_root()
 
         # Scan root directory
         for item in project_root.iterdir():
@@ -563,7 +595,7 @@ def scan_root_violations(config: Dict[str, Any]) -> List[Dict[str, str]]:
     return violations
 
 
-def generate_migration_report(violations: List[Dict[str, str]]) -> str:
+def generate_migration_report(violations: list[dict[str, str]]) -> str:
     """Generate migration suggestions report
 
     Args:
@@ -592,7 +624,7 @@ def generate_migration_report(violations: List[Dict[str, str]]) -> str:
 
 
 def generate_session_summary(
-    cleanup_stats: Dict[str, int], work_state: Dict[str, Any], violations_count: int = 0
+    cleanup_stats: dict[str, int], work_state: dict[str, Any], violations_count: int = 0
 ) -> str:
     """Generate session summary (P1-3)
 
@@ -632,7 +664,7 @@ def generate_session_summary(
     return "\n".join(summary_lines)
 
 
-def execute_session_end_workflow() -> tuple[Dict[str, Any], str]:
+def execute_session_end_workflow() -> tuple[dict[str, Any], str]:
     """Execute the session end workflow with proper error handling"""
     start_time = time.time()
 

moai_adk/templates/.claude/hooks/moai/session_end__rank_submit.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""MoAI Rank Session Hook
+
+This hook submits Claude Code session token usage to the MoAI Rank service.
+It is triggered automatically when a session ends.
+
+The hook reads session data from stdin and submits it to the rank service
+if the user has registered with MoAI Rank.
+
+Requirements:
+- User must be registered: Run `moai-adk rank register` to connect GitHub account
+- API key stored securely in ~/.moai/rank/credentials.json
+
+Privacy:
+- Only token counts are submitted (input, output, cache tokens)
+- Project paths are anonymized using one-way hashing
+- No code or conversation content is transmitted
+
+Opt-out: Configure ~/.moai/rank/config.yaml to exclude specific projects:
+    rank:
+      enabled: true
+      exclude_projects:
+        - "/path/to/private-project"
+        - "*/confidential/*"
+"""
+
+import json
+import sys
+
+
+def main():
+    """Main hook entry point."""
+    try:
+        # Read session data from stdin
+        input_data = sys.stdin.read()
+        if not input_data:
+            return
+
+        session_data = json.loads(input_data)
+
+        # Lazy import to avoid startup delay
+        try:
+            from moai_adk.rank.hook import is_project_excluded, submit_session_hook
+        except ImportError:
+            # moai-adk not installed or rank module not available
+            return
+
+        # Check if this project is excluded
+        project_path = session_data.get("projectPath") or session_data.get("cwd")
+        if is_project_excluded(project_path):
+            return  # Silently skip excluded projects
+
+        result = submit_session_hook(session_data)
+
+        if result["success"]:
+            print("Session submitted to MoAI Rank", file=sys.stderr)
+        elif result["message"] and result["message"] != "Not registered with MoAI Rank":
+            print(f"MoAI Rank: {result['message']}", file=sys.stderr)
+
+    except json.JSONDecodeError:
+        # Invalid JSON input, silently skip
+        pass
+    except Exception as e:
+        # Log errors but don't fail the hook
+        print(f"MoAI Rank hook error: {e}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()