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

moai_adk/templates/.claude/hooks/alfred/shared/core/tags.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+# @CODE:HOOK-TAG-001 | SPEC: TBD | TEST: tests/hooks/test_tag_validation.py
+"""TAG validation helpers for MoAI-ADK hooks
+
+Fast checks used by PreToolUse/PostToolUse to nudge users when
+new or modified files are missing required @TAG annotations.
+
+Configurable rules with sensible defaults:
+- Load patterns from .moai/tag-rules.json if present.
+- Otherwise, apply default glob patterns (folder names are not hard-coded only).
+
+Defaults (order matters; first match wins):
+1) SPEC
+   - .moai/specs/**
+   - **/SPEC-*/spec.md
+2) TEST
+   - **/*_test.py, **/test_*.py, **/*.test.* (ts,tsx,js,jsx,go,rs)
+   - **/*.spec.* (ts,tsx,js,jsx)
+   - tests/**
+3) DOC
+   - docs/**/*.md, **/README.md, **/*.api.md
+4) CODE
+   - Source extensions: .py,.ts,.tsx,.js,.jsx,.go,.rs,.java,.kt,.rb,.php,.c,.cpp,.cs,.swift,.scala
+   - Excluding TEST patterns
+
+Notes:
+- Best-effort: skip binary/large files and non-target paths
+- Do not block execution; return a list of issues for messaging
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+DEFAULT_CODE_EXTS = (
+    ".py",
+    ".ts",
+    ".tsx",
+    ".js",
+    ".jsx",
+    ".go",
+    ".rs",
+    ".java",
+    ".kt",
+    ".rb",
+    ".php",
+    ".c",
+    ".cpp",
+    ".cs",
+    ".swift",
+    ".scala",
+)
+
+
+@dataclass
+class TagIssue:
+    path: str
+    expected: str  # one of @SPEC, @TEST, @CODE, @DOC
+    reason: str
+
+
+@dataclass
+class Rule:
+    include: List[str]
+    expect: str  # '@SPEC:' | '@TEST:' | '@CODE:' | '@DOC:'
+    exclude: List[str]
+
+
+def _load_rules(cwd: str) -> List[Rule]:
+    """Load tag rules from .moai/tag-rules.json or return defaults.
+
+    Schema example:
+    {
+      "rules": [
+        {"include": ["**/*_test.py", "**/*.test.ts"], "expect": "@TEST:", "exclude": []},
+        {"include": ["docs/**/*.md", "**/README.md"], "expect": "@DOC:", "exclude": []}
+      ]
+    }
+    """
+    cfg = Path(cwd) / ".moai" / "tag-rules.json"
+    if cfg.exists():
+        try:
+            data = json.loads(cfg.read_text(encoding="utf-8"))
+            items = data.get("rules", [])
+            rules: List[Rule] = []
+            for it in items:
+                include = list(it.get("include", []))
+                expect = str(it.get("expect", ""))
+                exclude = list(it.get("exclude", []))
+                if include and expect in ("@SPEC:", "@TEST:", "@CODE:", "@DOC:"):
+                    rules.append(Rule(include=include, expect=expect, exclude=exclude))
+            if rules:
+                return rules
+        except Exception:
+            pass
+
+    # Defaults (ordered)
+    return [
+        Rule(include=[".moai/specs/**", "**/SPEC-*/spec.md"], expect="@SPEC:", exclude=[]),
+        Rule(
+            include=[
+                "**/*_test.py",
+                "**/test_*.py",
+                "**/*.test.ts",
+                "**/*.test.tsx",
+                "**/*.test.js",
+                "**/*.test.jsx",
+                "**/*.test.go",
+                "**/*.test.rs",
+                "**/*.spec.ts",
+                "**/*.spec.tsx",
+                "tests/**",
+            ],
+            expect="@TEST:",
+            exclude=[".claude/**"],
+        ),
+        Rule(
+            include=["docs/**/*.md", "**/README.md", "**/*.api.md"],
+            expect="@DOC:",
+            exclude=[".claude/**"],
+        ),
+        Rule(
+            include=["**/*"],
+            expect="@CODE:",
+            exclude=[
+                "tests/**",
+                "docs/**",
+                ".moai/**",
+                ".claude/**",
+                "**/*.md",
+                "**/*.json",
+                "**/*.yml",
+                "**/*.yaml",
+                "**/*.toml",
+                "**/*.lock",
+                "**/*.svg",
+                "**/*.png",
+                "**/*.jpg",
+                "**/*.jpeg",
+                "**/*.gif",
+            ],
+        ),
+    ]
+
+
+def _match_any(path: str, patterns: List[str]) -> bool:
+    return any(fnmatch.fnmatch(path, pat) for pat in patterns)
+
+
+def _needs_tag_str(path_str: str, rules: List[Rule]) -> Optional[str]:
+    p = path_str
+    for rule in rules:
+        if _match_any(p, rule.include) and not _match_any(p, rule.exclude):
+            if rule.expect == "@CODE:":
+                # CODE: limit to source-like extensions to reduce noise
+                if not any(p.endswith(ext) for ext in DEFAULT_CODE_EXTS):
+                    continue
+            return rule.expect
+    return None
+
+
+def _has_tag(content: str, expected: str) -> bool:
+    return expected in content
+
+
+def _iter_recent_changes(cwd: str) -> Iterable[Path]:
+    root = Path(cwd)
+    try:
+        # Staged files
+        r1 = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=1,
+        )
+        # Modified (unstaged) tracked files
+        r2 = subprocess.run(
+            ["git", "ls-files", "-m"], cwd=cwd, capture_output=True, text=True, timeout=1
+        )
+        # Untracked (other) files respecting .gitignore
+        r3 = subprocess.run(
+            ["git", "ls-files", "-o", "--exclude-standard"],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=1,
+        )
+        names = set()
+        if r1.returncode == 0:
+            names.update([line.strip() for line in r1.stdout.splitlines() if line.strip()])
+        if r2.returncode == 0:
+            names.update([line.strip() for line in r2.stdout.splitlines() if line.strip()])
+        if r3.returncode == 0:
+            names.update([line.strip() for line in r3.stdout.splitlines() if line.strip()])
+        for n in names:
+            p = (root / n).resolve()
+            if p.is_file():
+                yield p
+    except Exception:
+        return []
+
+
+def scan_recent_changes_for_missing_tags(cwd: str) -> list[TagIssue]:
+    issues: list[TagIssue] = []
+    rules = _load_rules(cwd)
+    root = Path(cwd).resolve()
+    for path in _iter_recent_changes(cwd):
+        try:
+            content = path.read_text(encoding="utf-8", errors="ignore")
+        except Exception:
+            continue
+        # compute relative path once and use for matching/excluding
+        try:
+            rel = path.resolve().relative_to(root)
+            rel_s = rel.as_posix()
+        except Exception:
+            rel_s = path.name
+
+        expected = _needs_tag_str(rel_s, rules)
+        if not expected:
+            continue
+        if not _has_tag(content, expected):
+            issues.append(TagIssue(path=rel_s, expected=expected, reason="missing tag"))
+    return issues

moai_adk/templates/.claude/hooks/alfred/shared/core/version_cache.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+# @CODE:VERSION-CACHE-001
+"""Version information cache with TTL support
+
+TTL-based caching system for version check results to minimize network calls
+during SessionStart hook execution.
+
+SPEC: SPEC-UPDATE-ENHANCE-001 - SessionStart 버전 체크 시스템 강화
+Phase 1: Cache System Implementation
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+class VersionCache:
+    """TTL-based version information cache
+
+    Caches version check results with configurable Time-To-Live (TTL)
+    to avoid excessive network calls to PyPI during SessionStart events.
+
+    Attributes:
+        cache_dir: Directory to store cache file
+        ttl_hours: Time-to-live in hours (default 24)
+        cache_file: Path to the cache JSON file
+
+    Examples:
+        >>> cache = VersionCache(Path(".moai/cache"), ttl_hours=24)
+        >>> cache.save({"current_version": "0.8.1", "latest_version": "0.9.0"})
+        True
+        >>> cache.is_valid()
+        True
+        >>> data = cache.load()
+        >>> data["current_version"]
+        '0.8.1'
+    """
+
+    def __init__(self, cache_dir: Path, ttl_hours: int = 4):
+        """Initialize cache with TTL in hours
+
+        Args:
+            cache_dir: Directory where cache file will be stored
+            ttl_hours: Time-to-live in hours (default 4)
+        """
+        self.cache_dir = Path(cache_dir)
+        self.ttl_hours = ttl_hours
+        self.cache_file = self.cache_dir / "version-check.json"
+
+    def _calculate_age_hours(self, last_check_iso: str) -> float:
+        """Calculate age in hours from ISO timestamp (internal helper)
+
+        Normalizes timezone-aware and naive datetimes for consistent comparison.
+
+        Args:
+            last_check_iso: ISO format timestamp string
+
+        Returns:
+            Age in hours
+
+        Raises:
+            ValueError: If timestamp parsing fails
+        """
+        last_check = datetime.fromisoformat(last_check_iso)
+
+        # Normalize to naive datetime (remove timezone for comparison)
+        if last_check.tzinfo is not None:
+            last_check = last_check.replace(tzinfo=None)
+
+        now = datetime.now()
+        return (now - last_check).total_seconds() / 3600
+
+    def is_valid(self) -> bool:
+        """Check if cache exists and is not expired
+
+        Returns:
+            True if cache file exists and is within TTL, False otherwise
+
+        Examples:
+            >>> cache = VersionCache(Path(".moai/cache"))
+            >>> cache.is_valid()
+            False  # No cache file exists yet
+        """
+        if not self.cache_file.exists():
+            return False
+
+        try:
+            with open(self.cache_file, "r") as f:
+                data = json.load(f)
+
+            age_hours = self._calculate_age_hours(data["last_check"])
+            return age_hours < self.ttl_hours
+
+        except (json.JSONDecodeError, KeyError, ValueError, OSError):
+            # Corrupted or invalid cache file
+            return False
+
+    def load(self) -> dict[str, Any] | None:
+        """Load cached version info if valid
+
+        Returns:
+            Cached version info dictionary if valid, None otherwise
+
+        Examples:
+            >>> cache = VersionCache(Path(".moai/cache"))
+            >>> data = cache.load()
+            >>> data is None
+            True  # No valid cache exists
+        """
+        if not self.is_valid():
+            return None
+
+        try:
+            with open(self.cache_file, "r") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, OSError):
+            # Graceful degradation on read errors
+            return None
+
+    def save(self, version_info: dict[str, Any]) -> bool:
+        """Save version info to cache file
+
+        Creates cache directory if it doesn't exist.
+        Updates last_check timestamp to current time if not provided.
+
+        Args:
+            version_info: Version information dictionary to cache
+
+        Returns:
+            True on successful save, False on error
+
+        Examples:
+            >>> cache = VersionCache(Path(".moai/cache"))
+            >>> cache.save({"current_version": "0.8.1"})
+            True
+        """
+        try:
+            # Create cache directory if it doesn't exist
+            self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+            # Update last_check timestamp only if not provided (for testing)
+            if "last_check" not in version_info:
+                version_info["last_check"] = datetime.now(timezone.utc).isoformat()
+
+            # Write to cache file
+            with open(self.cache_file, "w") as f:
+                json.dump(version_info, f, indent=2)
+
+            return True
+
+        except (OSError, TypeError):
+            # Graceful degradation on write errors
+            return False
+
+    def clear(self) -> bool:
+        """Clear/remove cache file
+
+        Returns:
+            True if cache file was removed or didn't exist, False on error
+
+        Examples:
+            >>> cache = VersionCache(Path(".moai/cache"))
+            >>> cache.clear()
+            True
+        """
+        try:
+            if self.cache_file.exists():
+                self.cache_file.unlink()
+            return True
+        except OSError:
+            return False
+
+    def get_age_hours(self) -> float:
+        """Get age of cache in hours
+
+        Returns:
+            Age in hours, or 0.0 if cache doesn't exist or is invalid
+
+        Examples:
+            >>> cache = VersionCache(Path(".moai/cache"))
+            >>> cache.get_age_hours()
+            0.0  # No cache exists
+        """
+        if not self.cache_file.exists():
+            return 0.0
+
+        try:
+            with open(self.cache_file, "r") as f:
+                data = json.load(f)
+
+            return self._calculate_age_hours(data["last_check"])
+
+        except (json.JSONDecodeError, KeyError, ValueError, OSError):
+            return 0.0
+
+
+__all__ = ["VersionCache"]

moai_adk/templates/.claude/hooks/alfred/shared/handlers/__init__.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Event handlers for Alfred Hooks
+
+Claude Code Event Handlers
+"""
+
+from .notification import handle_notification, handle_stop, handle_subagent_stop
+from .session import handle_session_end, handle_session_start
+from .tool import handle_post_tool_use, handle_pre_tool_use
+from .user import handle_user_prompt_submit
+
+__all__ = [
+    "handle_session_start",
+    "handle_session_end",
+    "handle_user_prompt_submit",
+    "handle_pre_tool_use",
+    "handle_post_tool_use",
+    "handle_notification",
+    "handle_stop",
+    "handle_subagent_stop",
+]