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

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

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Pre-commit hook for TAG validation (T3: Pre-commit Validation Hook).
+
+Validates TAG format and SPEC existence before Git commit.
+Runs in warn mode by default (allows commit with warnings).
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+try:
+    from .lib import (
+        extract_tags_from_file,
+        get_config_manager,
+        spec_document_exists,
+        validate_tag,
+    )
+    from .lib.tag_validator import TAG
+except ImportError:
+    # Fallback for direct execution from hooks directory
+    try:
+        from lib import (
+            extract_tags_from_file,
+            get_config_manager,
+            spec_document_exists,
+            validate_tag,
+        )
+        from lib.tag_validator import TAG
+    except ImportError:
+        # Final fallback - try relative import from parent
+        import sys
+        from pathlib import Path
+
+        sys.path.insert(0, str(Path(__file__).parent.parent))
+        from hooks.moai.lib import (
+            extract_tags_from_file,
+            get_config_manager,
+            spec_document_exists,
+            validate_tag,
+        )
+        from hooks.moai.lib.tag_validator import TAG
+
+logger = logging.getLogger(__name__)
+
+
+def get_file_context(file_path: Path) -> dict:
+    """Get file context for flexible TAG validation.
+
+    Args:
+        file_path: Path to analyze
+
+    Returns:
+        Context dict with file type information
+    """
+    import re
+
+    file_str = str(file_path)
+
+    return {
+        "is_test_file": bool(re.search(r"test_\w+\.py|_\w+_test\.py|tests?/", file_str)),
+        "is_impl_file": not bool(re.search(r"test_\w+\.py|_\w+_test\.py|tests?/", file_str)),
+    }
+
+
+def load_tag_validation_config() -> dict:
+    """Load TAG validation configuration from quality.yaml.
+
+    Returns:
+        Configuration dict with enabled, mode, and other settings
+    """
+    try:
+        config_manager = get_config_manager()
+        quality_config = config_manager.config
+
+        # Get TAG validation settings
+        tag_config = quality_config.get("tag_validation", {})
+
+        # Apply defaults if not configured (T5.2)
+        defaults = {
+            "enabled": True,
+            "mode": "warn",  # warn | enforce | off
+        }
+
+        # Merge defaults with config
+        for key, value in defaults.items():
+            if key not in tag_config:
+                tag_config[key] = value
+
+        return tag_config
+
+    except Exception as e:
+        logger.warning(f"Error loading TAG validation config: {e}")
+        # Return safe defaults
+        return {"enabled": True, "mode": "warn"}
+
+
+def validate_tag_format(tag: TAG) -> tuple[bool, list[str]]:
+    """Validate TAG format.
+
+    Args:
+        tag: TAG to validate
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+    """
+    is_valid, errors = validate_tag(tag)
+    return is_valid, errors
+
+
+def check_spec_exists(spec_id: str) -> bool:
+    """Check if SPEC document exists.
+
+    Args:
+        spec_id: SPEC identifier to check
+
+    Returns:
+        True if SPEC exists, False otherwise
+    """
+    return spec_document_exists(spec_id)
+
+
+def validate_file_tags(file_path: Path, config: dict) -> tuple[int, list[str]]:
+    """Validate all TAGs in a file.
+
+    Args:
+        file_path: Path to Python file
+        config: TAG validation configuration
+
+    Returns:
+        Tuple of (exit_code, error_messages)
+    """
+    errors = []
+    file_context = get_file_context(file_path)
+
+    # Extract TAGs from file
+    tags = extract_tags_from_file(file_path)
+
+    if not tags:
+        return 0, []  # No TAGs, no errors
+
+    # Validate each TAG
+    for tag in tags:
+        # Validate TAG format
+        is_valid, format_errors = validate_tag_format(tag)
+
+        if not is_valid:
+            for error in format_errors:
+                errors.append(f"{file_path}:{tag.line}: {error}")
+
+        # Check SPEC existence with context-aware validation
+        if not check_spec_exists(tag.spec_id):
+            mode = config.get("mode", "warn")
+
+            # `related` verb: always allow, just show hint
+            if tag.verb == "related":
+                errors.append(
+                    f"{file_path}:{tag.line}: Hint: Consider creating SPEC for {tag.spec_id} "
+                    "(related TAG - no SPEC required)"
+                )
+                continue  # Allow commit
+
+            # TEST file with `verify` verb: allow with warning
+            if file_context["is_test_file"] and tag.verb == "verify":
+                errors.append(
+                    f"{file_path}:{tag.line}: Warning: TEST references missing SPEC: {tag.spec_id} "
+                    "(verify TAG in test file - commit allowed)"
+                )
+                continue  # Allow commit
+
+            # Implementation file with `impl` verb: strict validation
+            if file_context["is_impl_file"] and tag.verb == "impl":
+                if mode == "enforce":
+                    errors.append(
+                        f"{file_path}:{tag.line}: Error: Implementation references missing SPEC: {tag.spec_id} "
+                        "(commit blocked in enforce mode)"
+                    )
+                else:
+                    errors.append(
+                        f"{file_path}:{tag.line}: Warning: Implementation references missing SPEC: {tag.spec_id} "
+                        "(commit allowed in warn mode)"
+                    )
+                continue
+
+            # Default: warn but allow
+            errors.append(
+                f"{file_path}:{tag.line}: Warning: SPEC document not found: {tag.spec_id} (commit allowed in warn mode)"
+            )
+
+    # Determine exit code
+    if errors:
+        mode = config.get("mode", "warn")
+        if mode == "enforce":
+            # Check if any errors are blocking (not hints/warnings)
+            blocking_errors = [e for e in errors if "Error:" in e]
+            if blocking_errors:
+                return 1, errors  # Block commit
+        return 1, errors  # Warning code but commit allowed
+    else:
+        return 0, []  # Success
+
+
+def main() -> int:
+    """Main pre-commit hook entry point.
+
+    Returns:
+        Exit code (0 = success, 1 = warning/error)
+    """
+    # Load configuration
+    config = load_tag_validation_config()
+
+    # Check if TAG validation is enabled
+    if not config.get("enabled", True):
+        print("TAG validation disabled")
+        return 0
+
+    # Check if validation mode is 'off'
+    mode = config.get("mode", "warn")
+    if mode == "off":
+        print("TAG validation mode: off")
+        return 0
+
+    # Get staged files from git
+    import subprocess
+
+    try:
+        # Get list of staged Python files
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only", "--diff-filter=ACM"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+
+        if result.returncode != 0:
+            # Not in git repository or no staged files
+            return 0
+
+        staged_files = result.stdout.strip().splitlines()
+
+        # Filter for Python files only
+        python_files = [Path(f) for f in staged_files if f.endswith(".py") and Path(f).exists()]
+
+        if not python_files:
+            # No Python files staged
+            return 0
+
+    except Exception as e:
+        logger.warning(f"Error getting staged files: {e}")
+        return 0  # Don't block commit on git error
+
+    # Validate TAGs in all staged Python files
+    all_errors = []
+
+    for file_path in python_files:
+        _, file_errors = validate_file_tags(file_path, config)
+
+        if file_errors:
+            all_errors.extend(file_errors)
+
+    # Display errors
+    if all_errors:
+        print("\nTAG Validation Results:")
+        print("=" * 60)
+
+        for error in all_errors:
+            print(f"  {error}")
+
+        print("=" * 60)
+
+        if mode == "enforce":
+            print("\nCommit blocked due to TAG validation errors (enforce mode)")
+            print("Fix the errors and try again, or use --no-verify to bypass")
+        else:
+            print("\nCommit allowed with warnings (warn mode)")
+            print("Consider fixing the TAG validation errors")
+
+        return 1  # Warning code
+    else:
+        print("TAG validation: All TAGs valid")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,268 @@
+#!/usr/bin/env python3
+"""PreToolUse Hook: Security Guard
+
+Claude Code Event: PreToolUse
+Matcher: Write|Edit
+Purpose: Protect sensitive files and prevent dangerous modifications
+
+Security Features:
+- Block modifications to .env and secret files
+- Protect lock files (package-lock.json, yarn.lock)
+- Guard .git directory
+- Prevent accidental overwrites of critical configs
+
+Exit Codes:
+- 0: Success (with JSON output for permission decision)
+- 2: Error (blocking the operation)
+
+Permission Decisions:
+- "allow": Auto-approve safe operations
+- "deny": Block dangerous operations (reason shown to Claude)
+- "ask": Request user confirmation
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, List, Tuple
+
+# Patterns for files that should NEVER be modified
+DENY_PATTERNS = [
+    # Environment and secrets
+    r"\.env$",
+    r"\.env\.[^/]+$",  # .env.local, .env.production, etc.
+    r"\.envrc$",
+    r"secrets?\.(json|ya?ml|toml)$",
+    r"credentials?\.(json|ya?ml|toml)$",
+    r"\.secrets/.*",
+    r"secrets/.*",
+    # SSH and certificates
+    r"\.ssh/.*",
+    r"id_rsa.*",
+    r"id_ed25519.*",
+    r"\.pem$",
+    r"\.key$",
+    r"\.crt$",
+    # Git internals
+    r"\.git/.*",
+    # Cloud credentials
+    r"\.aws/.*",
+    r"\.gcloud/.*",
+    r"\.azure/.*",
+    r"\.kube/.*",
+    # Token files
+    r"\.token$",
+    r"\.tokens/.*",
+    r"auth\.json$",
+]
+
+# Patterns for files that require user confirmation
+ASK_PATTERNS = [
+    # Lock files
+    r"package-lock\.json$",
+    r"yarn\.lock$",
+    r"pnpm-lock\.ya?ml$",
+    r"Gemfile\.lock$",
+    r"Cargo\.lock$",
+    r"poetry\.lock$",
+    r"composer\.lock$",
+    r"Pipfile\.lock$",
+    r"uv\.lock$",
+    # Critical configs
+    r"tsconfig\.json$",
+    r"pyproject\.toml$",
+    r"Cargo\.toml$",
+    r"package\.json$",
+    r"docker-compose\.ya?ml$",
+    r"Dockerfile$",
+    r"\.dockerignore$",
+    # CI/CD configs
+    r"\.github/workflows/.*\.ya?ml$",
+    r"\.gitlab-ci\.ya?ml$",
+    r"\.circleci/.*",
+    r"Jenkinsfile$",
+    # Infrastructure
+    r"terraform/.*\.tf$",
+    r"\.terraform/.*",
+    r"kubernetes/.*\.ya?ml$",
+    r"k8s/.*\.ya?ml$",
+]
+
+# Content patterns that indicate sensitive data
+SENSITIVE_CONTENT_PATTERNS = [
+    r"-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----",
+    r"-----BEGIN\s+CERTIFICATE-----",
+    r"sk-[a-zA-Z0-9]{32,}",  # OpenAI API keys
+    r"ghp_[a-zA-Z0-9]{36}",  # GitHub tokens
+    r"gho_[a-zA-Z0-9]{36}",  # GitHub OAuth tokens
+    r"glpat-[a-zA-Z0-9\-]{20}",  # GitLab tokens
+    r"xox[baprs]-[a-zA-Z0-9\-]+",  # Slack tokens
+    r"AKIA[0-9A-Z]{16}",  # AWS access keys
+    r"ya29\.[a-zA-Z0-9_\-]+",  # Google OAuth tokens
+]
+
+
+def compile_patterns(patterns: list[str]) -> List[re.Pattern]:
+    """Compile regex patterns for efficient matching."""
+    return [re.compile(p, re.IGNORECASE) for p in patterns]
+
+
+DENY_COMPILED = compile_patterns(DENY_PATTERNS)
+ASK_COMPILED = compile_patterns(ASK_PATTERNS)
+SENSITIVE_COMPILED = compile_patterns(SENSITIVE_CONTENT_PATTERNS)
+
+
+def get_project_root() -> Path:
+    """Get the project root directory from environment or current working directory.
+
+    Returns:
+        Path to the project root directory.
+    """
+    import os
+
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+    return Path(project_dir).resolve()
+
+
+def check_file_path(file_path: str) -> Tuple[str, str]:
+    """Check if file path matches any security patterns.
+
+    Security measures:
+    - Resolves symlinks and '..' components to prevent path traversal
+    - Checks both original and resolved paths against patterns
+    - Validates path is within project boundaries
+
+    Args:
+        file_path: Path to check
+
+    Returns:
+        Tuple of (decision, reason)
+        decision: "allow", "deny", or "ask"
+    """
+    # Resolve path to prevent path traversal attacks
+    # This handles: symlinks, '..' components, and normalizes the path
+    try:
+        resolved_path = Path(file_path).resolve()
+        resolved_str = str(resolved_path)
+    except (OSError, ValueError):
+        # If path resolution fails, deny for safety
+        return "deny", "Invalid file path: cannot resolve"
+
+    # Normalize original path for pattern matching (keeps relative structure visible)
+    normalized_original = file_path.replace("\\", "/")
+    normalized_resolved = resolved_str.replace("\\", "/")
+
+    # Check project boundary (optional but recommended)
+    project_root = get_project_root()
+    try:
+        resolved_path.relative_to(project_root)
+    except ValueError:
+        # Path is outside project directory - potential path traversal attack
+        return "deny", "Path traversal detected: file is outside project directory"
+
+    # Check deny patterns against BOTH original and resolved paths
+    # This catches attempts like ".env/../other.txt" (matches .env in original)
+    # AND "/absolute/path/to/.env" (matches in resolved)
+    for pattern in DENY_COMPILED:
+        if pattern.search(normalized_original) or pattern.search(normalized_resolved):
+            return "deny", "Protected file: access denied for security reasons"
+
+    # Check ask patterns against both paths
+    for pattern in ASK_COMPILED:
+        if pattern.search(normalized_original) or pattern.search(normalized_resolved):
+            return "ask", f"Critical config file: {Path(file_path).name}"
+
+    return "allow", ""
+
+
+def check_content_for_secrets(content: str) -> Tuple[bool, str]:
+    """Check if content contains sensitive data patterns.
+
+    Args:
+        content: Content to check
+
+    Returns:
+        Tuple of (has_secrets, description)
+    """
+    for pattern in SENSITIVE_COMPILED:
+        match = pattern.search(content)
+        if match:
+            # Don't reveal the actual secret or pattern
+            return True, "Detected sensitive data (credentials, API keys, or certificates)"
+
+    return False, ""
+
+
+def main() -> None:
+    """Main entry point for PreToolUse security guard hook.
+
+    Reads JSON input from stdin, checks for security concerns,
+    and outputs permission decision.
+    """
+    try:
+        # Read JSON input from stdin
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        # Invalid JSON input - allow by default
+        sys.exit(0)
+
+    # Extract tool information
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Only process Write and Edit tools
+    if tool_name not in ("Write", "Edit"):
+        sys.exit(0)
+
+    # Get file path from tool input
+    file_path = tool_input.get("file_path", "")
+    if not file_path:
+        sys.exit(0)
+
+    # Check file path against patterns
+    decision, reason = check_file_path(file_path)
+
+    # For Write operations, also check content for secrets
+    if tool_name == "Write" and decision == "allow":
+        content = tool_input.get("content", "")
+        if content:
+            has_secrets, secret_reason = check_content_for_secrets(content)
+            if has_secrets:
+                decision = "deny"
+                reason = f"Content contains secrets: {secret_reason}"
+
+    # Build output based on decision
+    output: dict[str, Any] = {}
+
+    if decision == "deny":
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": reason,
+            }
+        }
+        print(json.dumps(output))
+        sys.exit(0)
+
+    elif decision == "ask":
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "ask",
+                "permissionDecisionReason": reason,
+            }
+        }
+        print(json.dumps(output))
+        sys.exit(0)
+
+    else:
+        # Allow - no output needed (or suppress)
+        output = {"suppressOutput": True}
+        print(json.dumps(output))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()