moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/pre_tool__realtime_tag_monitor.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+# @CODE:HOOK-REALTIME-001 | SPEC: TAG-REALTIME-HOOK-001 | TEST: tests/hooks/test_realtime_tag_monitor.py
+"""실시간 TAG 모니터링 Hook
+
+지속적인 TAG 상태 모니터링과 실시간 위반 탐지.
+PreToolUse 단계에서 프로젝트 전체 TAG 상태를 빠르게 검사.
+
+기능:
+- 실시간 TAG 상태 모니터링
+- 빠른 위반 탐지 (5초 내)
+- 프로젝트 전체 TAG 무결성 검사
+- 사용자에게 즉각적인 피드백
+
+사용법:
+    python3 pre_tool__realtime_tag_monitor.py <tool_name> <tool_args_json>
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+
+# 모듈 경로 추가
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "src"))
+
+from moai_adk.core.tags.validator import CentralValidationResult, CentralValidator, ValidationConfig
+
+from ..utils.hook_config import get_graceful_degradation, load_hook_timeout
+
+
+def load_config() -> Dict[str, Any]:
+    """설정 파일 로드
+
+    Returns:
+        설정 딕셔너리
+    """
+    try:
+        config_file = Path(".moai/config.json")
+        if config_file.exists():
+            with open(config_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+    except Exception:
+        pass
+
+    return {}
+
+
+def create_validator() -> CentralValidator:
+    """중앙 검증기 생성
+
+    Returns:
+        CentralValidator 인스턴스
+    """
+    config_data = load_config()
+    tag_policy_config = config_data.get("tags", {}).get("policy", {})
+
+    # ValidationConfig 생성
+    validation_config = ValidationConfig(
+        strict_mode=tag_policy_config.get("enforcement_mode", "strict") == "strict",
+        check_duplicates=True,
+        check_orphans=True,
+        check_chain_integrity=tag_policy_config.get("realtime_validation", {}).get("enforce_chains", True)
+    )
+
+    return CentralValidator(config=validation_config)
+
+
+def should_monitor(tool_name: str, tool_args: Dict[str, Any]) -> bool:
+    """모니터링 대상 툴인지 확인
+
+    Args:
+        tool_name: 툴 이름
+        tool_args: 툴 인자
+
+    Returns:
+        모니터링 대상이면 True
+    """
+    # 파일 조작 툴만 모니터링
+    monitoring_tools = {"Edit", "Write", "MultiEdit"}
+    return tool_name in monitoring_tools
+
+
+def get_project_files_to_scan() -> List[str]:
+    """스캔할 프로젝트 파일 목록 가져오기
+
+    Returns:
+        파일 경로 목록
+    """
+    files = []
+    important_patterns = [
+        "src/**/*.py",
+        "tests/**/*.py",
+        "**/*.md",
+        ".claude/**/*",
+        ".moai/**/*"
+    ]
+
+    # 빠른 스캔을 위해 파일 수 제한
+    max_files = 50
+
+    for pattern in important_patterns:
+        if len(files) >= max_files:
+            break
+
+        try:
+            for path in Path(".").glob(pattern):
+                if len(files) >= max_files:
+                    break
+                if path.is_file():
+                    files.append(str(path))
+        except Exception:
+            continue
+
+    return files[:max_files]
+
+
+def create_quick_scan_result(validation_result: CentralValidationResult,
+                           scan_time_ms: float) -> Dict[str, Any]:
+    """빠른 스캔 결과 생성
+
+    Args:
+        validation_result: 검증 결과
+        scan_time_ms: 스캔 시간
+
+    Returns:
+        스캔 결과 딕셔너리
+    """
+    result = {
+        "quick_scan_completed": True,
+        "scan_time_ms": scan_time_ms,
+        "files_scanned": validation_result.statistics.total_files_scanned,
+        "tags_found": validation_result.statistics.total_tags_found,
+        "total_issues": validation_result.statistics.total_issues,
+        "is_valid": validation_result.is_valid
+    }
+
+    # 심각한 문제만 요약
+    if validation_result.errors:
+        result["critical_issues"] = len(validation_result.errors)
+        result["error_summary"] = [
+            {
+                "type": error.type,
+                "tag": error.tag,
+                "message": error.message
+            }
+            for error in validation_result.errors[:5]  # 최대 5개만 표시
+        ]
+
+    if validation_result.warnings:
+        result["warnings"] = len(validation_result.warnings)
+
+    # 커버리지 정보
+    result["coverage_percentage"] = validation_result.statistics.coverage_percentage
+
+    # 상태 메시지
+    if validation_result.is_valid:
+        result["status_message"] = "✅ 프로젝트 TAG 상태 양호"
+    elif validation_result.errors:
+        result["status_message"] = f"🚨 {len(validation_result.errors)}개 치명적 문제 발견"
+    else:
+        result["status_message"] = f"⚠️ {len(validation_result.warnings)}개 경고 발견"
+
+    return result
+
+
+def create_health_check_result(issues_count: int,
+                             coverage_percentage: float,
+                             scan_time_ms: float) -> Dict[str, Any]:
+    """프로젝트 건강 상태 결과 생성
+
+    Args:
+        issues_count: 문제 수
+        coverage_percentage: 커버리지
+        scan_time_ms: 스캔 시간
+
+    Returns:
+        건강 상태 결과
+    """
+    # 건강 상태 계산
+    health_score = 100
+
+    # 문제 점수 차감
+    health_score -= min(issues_count * 5, 50)  # 최대 50점 차감
+
+    # 커버리지 점수
+    if coverage_percentage < 50:
+        health_score -= 20
+    elif coverage_percentage < 75:
+        health_score -= 10
+
+    health_score = max(0, health_score)
+
+    # 건강 등급
+    if health_score >= 90:
+        health_grade = "A"
+        health_message = "매우 좋음"
+    elif health_score >= 80:
+        health_grade = "B"
+        health_message = "좋음"
+    elif health_score >= 70:
+        health_grade = "C"
+        health_message = "보통"
+    elif health_score >= 60:
+        health_grade = "D"
+        health_message = "주의 필요"
+    else:
+        health_grade = "F"
+        health_message = "개선 필요"
+
+    return {
+        "health_score": health_score,
+        "health_grade": health_grade,
+        "health_message": health_message,
+        "issues_count": issues_count,
+        "coverage_percentage": coverage_percentage,
+        "scan_time_ms": scan_time_ms
+    }
+
+
+def main() -> None:
+    """메인 함수"""
+    try:
+        # 설정에서 타임아웃 값 로드 (밀리초 → 초)
+        timeout_seconds = load_hook_timeout() / 1000
+        graceful_degradation = get_graceful_degradation()
+
+        # 인자 파싱
+        if len(sys.argv) < 3:
+            print(json.dumps({
+                "quick_scan_completed": False,
+                "error": "Invalid arguments. Usage: python3 pre_tool__realtime_tag_monitor.py <tool_name> <tool_args_json>"
+            }))
+            sys.exit(0)
+
+        tool_name = sys.argv[1]
+        try:
+            tool_args = json.loads(sys.argv[2])
+        except json.JSONDecodeError:
+            print(json.dumps({
+                "quick_scan_completed": False,
+                "error": "Invalid tool_args JSON"
+            }))
+            sys.exit(0)
+
+        # 모니터링 대상 확인
+        if not should_monitor(tool_name, tool_args):
+            print(json.dumps({
+                "quick_scan_completed": True,
+                "message": "모니터링 대상 아님"
+            }))
+            sys.exit(0)
+
+        # 시작 시간 기록
+        start_time = time.time()
+
+        # 스캔할 파일 목록 가져오기
+        files_to_scan = get_project_files_to_scan()
+        if not files_to_scan:
+            print(json.dumps({
+                "quick_scan_completed": True,
+                "message": "스캔할 파일 없음"
+            }))
+            sys.exit(0)
+
+        # 검증기 생성
+        validator = create_validator()
+
+        # 빠른 검증 실행 (설정된 타임아웃 사용)
+        try:
+            # 타임아웃 체크
+            if time.time() - start_time > timeout_seconds:
+                raise TimeoutError("Real-time monitoring timeout")
+
+            validation_result = validator.validate_files(files_to_scan)
+        except Exception as e:
+            # 검증 실패시 타임아웃 처리
+            scan_time = (time.time() - start_time) * 1000
+            error_response = {
+                "quick_scan_completed": False,
+                "error": f"검증 타임아웃: {str(e)}",
+                "scan_time_ms": scan_time,
+                "message": "실시간 검증 타임아웃 - 정상 작동으로 간주"
+            }
+
+            if graceful_degradation:
+                error_response["graceful_degradation"] = True
+                error_response["message"] = "Real-time monitoring timeout but continuing due to graceful degradation"
+
+            print(json.dumps(error_response, ensure_ascii=False))
+            sys.exit(0)
+
+        scan_time_ms = (time.time() - start_time) * 1000
+
+        # 결과 생성
+        scan_result = create_quick_scan_result(validation_result, scan_time_ms)
+
+        # 건강 상태 검사
+        health_result = create_health_check_result(
+            validation_result.statistics.total_issues,
+            validation_result.statistics.coverage_percentage,
+            scan_time_ms
+        )
+
+        # 최종 응답
+        response = {
+            **scan_result,
+            "health_check": health_result,
+            "monitoring_type": "realtime_quick_scan"
+        }
+
+        # 타임아웃 경고
+        timeout_warning_ms = timeout_seconds * 1000 * 0.8  # 80% of timeout
+        if scan_time_ms > timeout_warning_ms:
+            response["performance_warning"] = f"스캔 시간이 설정된 타임아웃의 80%를 초과했습니다 ({scan_time_ms:.0f}ms / {timeout_warning_ms:.0f}ms)"
+
+        print(json.dumps(response, ensure_ascii=False, indent=2))
+
+    except Exception as e:
+        # 예외 발생시 기본 응답
+        error_response = {
+            "quick_scan_completed": False,
+            "error": f"Hook execution error: {str(e)}",
+            "message": "실시간 모니터링 오류 - 정상 작동으로 간주"
+        }
+
+        if graceful_degradation:
+            error_response["graceful_degradation"] = True
+            error_response["message"] = "Real-time monitoring failed but continuing due to graceful degradation"
+
+        print(json.dumps(error_response, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

moai_adk/templates/.claude/hooks/alfred/pre_tool__tag_policy_validator.py

@@ -0,0 +1,325 @@
+#!/usr/bin/env python3
+# @CODE:HOOK-PRE-TAG-001 | SPEC: TAG-PRE-HOOK-001 | TEST: tests/hooks/test_pre_tool_tag_validator.py
+"""PreToolUse Hook: TAG 정책 위반 실시간 차단
+
+Edit/Write/MultiEdit 실행 전 TAG 정책 위반을 탐지하고 차단.
+SPEC-first 원칙을 강제하여 코드 품질 보증.
+
+기능:
+- 파일 생성 전 TAG 정책 검증
+- SPEC 없이 CODE 생성 시 차단
+- 실시간 위반 보고 및 수정 가이드
+- 작업 차단 또는 경고 제공
+
+사용법:
+    python3 pre_tool__tag_policy_validator.py <tool_name> <tool_args_json>
+"""
+
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any, Dict, List
+
+# 모듈 경로 추가
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent / "src"))
+
+from moai_adk.core.tags.policy_validator import (
+    PolicyValidationConfig,
+    PolicyViolation,
+    PolicyViolationLevel,
+    TagPolicyValidator,
+)
+
+from ..utils.hook_config import get_graceful_degradation, load_hook_timeout
+
+
+def load_config() -> Dict[str, Any]:
+    """설정 파일 로드
+
+    Returns:
+        설정 딕셔너리
+    """
+    try:
+        config_file = Path(".moai/config.json")
+        if config_file.exists():
+            with open(config_file, 'r', encoding='utf-8') as f:
+                return json.load(f)
+    except Exception:
+        pass
+
+    return {}
+
+
+def create_policy_validator() -> TagPolicyValidator:
+    """TAG 정책 검증기 생성
+
+    Returns:
+        TagPolicyValidator 인스턴스
+    """
+    config_data = load_config()
+    tag_policy_config = config_data.get("tags", {}).get("policy", {})
+
+    # PolicyValidationConfig 생성
+    policy_config = PolicyValidationConfig(
+        strict_mode=tag_policy_config.get("enforcement_mode", "strict") == "strict",
+        require_spec_before_code=tag_policy_config.get("require_spec_before_code", True),
+        require_test_for_code=tag_policy_config.get("require_test_for_code", True),
+        allow_duplicate_tags=not tag_policy_config.get("enforce_chains", True),
+        validation_timeout=tag_policy_config.get("realtime_validation", {}).get("validation_timeout", 5),
+        auto_fix_enabled=tag_policy_config.get("auto_correction", {}).get("enabled", False)
+    )
+
+    return TagPolicyValidator(config=policy_config)
+
+
+def should_validate_tool(tool_name: str, tool_args: Dict[str, Any]) -> bool:
+    """검증 대상 툴인지 확인
+
+    Args:
+        tool_name: 툴 이름
+        tool_args: 툴 인자
+
+    Returns:
+        검증 대상이면 True
+    """
+    # 파일 조작 툴만 검증
+    validation_tools = {"Edit", "Write", "MultiEdit"}
+    if tool_name not in validation_tools:
+        return False
+
+    # CLAUDE.md 파일은 TAG 검증에서 제외
+    if tool_name in {"Edit", "Write"}:
+        file_path = tool_args.get("file_path", "")
+        if file_path.endswith("CLAUDE.md"):
+            return False
+
+    # MultiEdit의 경우 CLAUDE.md 포함 여부 확인
+    if tool_name == "MultiEdit":
+        edits = tool_args.get("edits", [])
+        for edit in edits:
+            file_path = edit.get("file_path", "")
+            if file_path.endswith("CLAUDE.md"):
+                return False
+
+    return True
+
+
+def extract_file_paths(tool_name: str, tool_args: Dict[str, Any]) -> List[str]:
+    """툴 인자에서 파일 경로 추출
+
+    Args:
+        tool_name: 툴 이름
+        tool_args: 툴 인자
+
+    Returns:
+        파일 경로 목록
+    """
+    file_paths = []
+
+    if tool_name in {"Edit", "Write"}:
+        file_path = tool_args.get("file_path", "")
+        if file_path:
+            file_paths.append(file_path)
+
+    elif tool_name == "MultiEdit":
+        # MultiEdit의 경우 여러 파일 경로 추출
+        edits = tool_args.get("edits", [])
+        for edit in edits:
+            file_path = edit.get("file_path", "")
+            if file_path:
+                file_paths.append(file_path)
+
+    return file_paths
+
+
+def get_file_content(tool_name: str, tool_args: Dict[str, Any], file_path: str) -> str:
+    """파일 내용 가져오기
+
+    Args:
+        tool_name: 툴 이름
+        tool_args: 툴 인자
+        file_path: 파일 경로
+
+    Returns:
+        파일 내용
+    """
+    # Write: 새 내용
+    if tool_name == "Write":
+        return tool_args.get("content", "")
+
+    # Edit/MultiEdit: 기존 내용에 수정 적용
+    try:
+        path = Path(file_path)
+        if path.exists():
+            return path.read_text(encoding="utf-8", errors="ignore")
+    except Exception:
+        pass
+
+    return ""
+
+
+def create_block_response(violations: List[PolicyViolation]) -> Dict[str, Any]:
+    """작업 차단 응답 생성
+
+    Args:
+        violations: 정책 위반 목록
+
+    Returns:
+        차단 응답 딕셔너리
+    """
+    critical_violations = [v for v in violations if v.level == PolicyViolationLevel.CRITICAL]
+    blocking_violations = [v for v in violations if v.should_block_operation()]
+
+    response = {
+        "block_execution": True,
+        "reason": "TAG 정책 위반",
+        "violations": [v.to_dict() for v in blocking_violations],
+        "message": "❌ TAG 정책 위반으로 작업이 차단되었습니다.",
+        "guidance": []
+    }
+
+    if critical_violations:
+        response["message"] = "🚨 치명적인 TAG 정책 위반입니다. 작업을 진행할 수 없습니다."
+        response["critical_violations"] = [v.to_dict() for v in critical_violations]
+
+    # 수정 가이드 추가
+    for violation in blocking_violations:
+        if violation.guidance:
+            response["guidance"].append(f"• {violation.guidance}")
+
+    return response
+
+
+def create_warning_response(violations: List[PolicyViolation]) -> Dict[str, Any]:
+    """경고 응답 생성
+
+    Args:
+        violations: 정책 위반 목록
+
+    Returns:
+        경고 응답 딕셔너리
+    """
+    response = {
+        "block_execution": False,
+        "reason": "TAG 정책 경고",
+        "violations": [v.to_dict() for v in violations],
+        "message": "⚠️ TAG 정책 경고가 있지만 작업을 진행할 수 있습니다.",
+        "guidance": []
+    }
+
+    # 수정 가이드 추가
+    for violation in violations:
+        if violation.guidance:
+            response["guidance"].append(f"• {violation.guidance}")
+
+    return response
+
+
+def create_success_response() -> Dict[str, Any]:
+    """성공 응답 생성
+
+    Returns:
+        성공 응답 딕셔너리
+    """
+    return {
+        "block_execution": False,
+        "reason": "TAG 정책 준수",
+        "violations": [],
+        "message": "✅ TAG 정책 검증 통과",
+        "guidance": []
+    }
+
+
+def main() -> None:
+    """메인 함수"""
+    try:
+        # 설정에서 타임아웃 값 로드 (밀리초 → 초)
+        timeout_seconds = load_hook_timeout() / 1000
+        graceful_degradation = get_graceful_degradation()
+
+        # 인자 파싱
+        if len(sys.argv) < 3:
+            print(json.dumps({
+                "block_execution": False,
+                "error": "Invalid arguments. Usage: python3 pre_tool__tag_policy_validator.py <tool_name> <tool_args_json>"
+            }))
+            sys.exit(0)
+
+        tool_name = sys.argv[1]
+        try:
+            tool_args = json.loads(sys.argv[2])
+        except json.JSONDecodeError:
+            print(json.dumps({
+                "block_execution": False,
+                "error": "Invalid tool_args JSON"
+            }))
+            sys.exit(0)
+
+        # 시작 시간 기록 (타임아웃 체크용)
+        start_time = time.time()
+
+        # 툴 검증 여부 확인
+        if not should_validate_tool(tool_name, tool_args):
+            print(json.dumps(create_success_response()))
+            sys.exit(0)
+
+        # 파일 경로 추출
+        file_paths = extract_file_paths(tool_name, tool_args)
+        if not file_paths:
+            print(json.dumps(create_success_response()))
+            sys.exit(0)
+
+        # 정책 검증기 생성
+        validator = create_policy_validator()
+
+        # 모든 파일에 대해 검증
+        all_violations = []
+        for file_path in file_paths:
+            # 타임아웃 체크
+            if time.time() - start_time > timeout_seconds:
+                break
+
+            # 파일 내용 가져오기
+            content = get_file_content(tool_name, tool_args, file_path)
+
+            # 정책 검증
+            violations = validator.validate_before_creation(file_path, content)
+            all_violations.extend(violations)
+
+        # 위반 수준별 분류
+        blocking_violations = [v for v in all_violations if v.should_block_operation()]
+        warning_violations = [v for v in all_violations if not v.should_block_operation()]
+
+        # 응답 생성
+        if blocking_violations:
+            response = create_block_response(blocking_violations)
+        elif warning_violations:
+            response = create_warning_response(warning_violations)
+        else:
+            response = create_success_response()
+
+        # 검증 보고서 추가
+        if all_violations:
+            validation_report = validator.create_validation_report(all_violations)
+            response["validation_report"] = validation_report
+
+        print(json.dumps(response, ensure_ascii=False, indent=2))
+
+    except Exception as e:
+        # 예외 발생 시 차단하지 않고 로그만 남김
+        error_response = {
+            "block_execution": False,
+            "error": f"Hook execution error: {str(e)}",
+            "message": "Hook 실행 중 오류가 발생했지만 작업을 진행합니다."
+        }
+
+        if graceful_degradation:
+            error_response["graceful_degradation"] = True
+            error_response["message"] = "Hook failed but continuing due to graceful degradation"
+
+        print(json.dumps(error_response, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()