moai-adk 0.15.1__py3-none-any.whl → 0.32.8__py3-none-any.whl

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

@@ -1,94 +0,0 @@
-#!/usr/bin/env python3
-# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
-"""SessionStart Hook: Show Project Information
-
-Claude Code Event: SessionStart
-Purpose: Display project status, language, Git info, and SPEC progress when session starts
-Execution: Triggered automatically when Claude Code session begins
-
-Output: System message with formatted project summary
-"""
-
-import json
-import sys
-from pathlib import Path
-from typing import Any
-
-from utils.timeout import CrossPlatformTimeout
-from utils.timeout import TimeoutError as PlatformTimeoutError
-
-# Setup import path for shared modules
-HOOKS_DIR = Path(__file__).parent
-SHARED_DIR = HOOKS_DIR / "shared"
-if str(SHARED_DIR) not in sys.path:
-    sys.path.insert(0, str(SHARED_DIR))
-
-from handlers import handle_session_start
-
-
-def main() -> None:
-    """Main entry point for SessionStart hook
-
-    Displays project information including:
-    - Programming language
-    - Git branch and status
-    - SPEC progress (completed/total)
-    - Recent checkpoints
-
-    Exit Codes:
-        0: Success
-        1: Error (timeout, JSON parse failure, handler exception)
-    """
-    # Set 5-second timeout
-    timeout = CrossPlatformTimeout(5)
-    timeout.start()
-
-    try:
-        # Read JSON payload from stdin
-        input_data = sys.stdin.read()
-        data = json.loads(input_data) if input_data.strip() else {}
-
-        # Call handler
-        result = handle_session_start(data)
-
-        # Output result as JSON
-        print(json.dumps(result.to_dict()))
-        sys.exit(0)
-
-    except PlatformTimeoutError:
-        # Timeout - return minimal valid response
-        timeout_response: dict[str, Any] = {
-            "continue": True,
-            "systemMessage": "⚠️ Session start timeout - continuing without project info",
-        }
-        print(json.dumps(timeout_response))
-        print("SessionStart hook timeout after 5 seconds", file=sys.stderr)
-        sys.exit(1)
-
-    except json.JSONDecodeError as e:
-        # JSON parse error
-        error_response: dict[str, Any] = {
-            "continue": True,
-            "hookSpecificOutput": {"error": f"JSON parse error: {e}"},
-        }
-        print(json.dumps(error_response))
-        print(f"SessionStart JSON parse error: {e}", file=sys.stderr)
-        sys.exit(1)
-
-    except Exception as e:
-        # Unexpected error
-        error_response: dict[str, Any] = {
-            "continue": True,
-            "hookSpecificOutput": {"error": f"SessionStart error: {e}"},
-        }
-        print(json.dumps(error_response))
-        print(f"SessionStart unexpected error: {e}", file=sys.stderr)
-        sys.exit(1)
-
-    finally:
-        # Always cancel alarm
-        timeout.cancel()
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,170 +0,0 @@
-#!/usr/bin/env python3
-"""Core module for Alfred Hooks
-
-Common type definitions and utility functions
-"""
-
-from dataclasses import dataclass, field
-from typing import Any, Literal, NotRequired, TypedDict
-
-
-class HookPayload(TypedDict):
-    """Claude Code Hook event payload type definition
-
-    Data structure that Claude Code passes to the Hook script.
-    Use NotRequired because fields may vary depending on the event.
-    """
-
-    cwd: str
-    userPrompt: NotRequired[str]  # Includes only UserPromptSubmit events
-    tool: NotRequired[str]  # PreToolUse/PostToolUse events
-    arguments: NotRequired[dict[str, Any]]  # Tool arguments
-
-
-@dataclass
-class HookResult:
-    """Hook execution result following Claude Code standard schema.
-
-    Attributes conform to Claude Code Hook output specification:
-    https://docs.claude.com/en/docs/claude-code/hooks
-
-    Standard Fields (Claude Code schema - included in JSON output):
-        continue_execution: Allow execution to continue (default True)
-        suppress_output: Suppress hook output display (default False)
-        decision: "approve" or "block" operation (optional)
-        reason: Explanation for decision (optional)
-        permission_decision: "allow", "deny", or "ask" (optional)
-        system_message: Message displayed to user (top-level field)
-
-    Internal Fields (MoAI-ADK only - NOT in JSON output):
-        context_files: List of context files to load (internal use only)
-        suggestions: Suggestions for user (internal use only)
-        exit_code: Exit code for diagnostics (internal use only)
-
-    Note:
-        - systemMessage appears at TOP LEVEL in JSON output
-        - hookSpecificOutput is ONLY used for UserPromptSubmit events
-        - Internal fields are used for Python logic but not serialized to JSON
-    """
-
-    # Claude Code standard fields
-    continue_execution: bool = True
-    suppress_output: bool = False
-    decision: Literal["approve", "block"] | None = None
-    reason: str | None = None
-    permission_decision: Literal["allow", "deny", "ask"] | None = None
-
-    # MoAI-ADK custom fields (wrapped in hookSpecificOutput)
-    system_message: str | None = None
-    context_files: list[str] = field(default_factory=list)
-    suggestions: list[str] = field(default_factory=list)
-    exit_code: int = 0
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to Claude Code standard Hook output schema.
-
-        Returns:
-            Dictionary conforming to Claude Code Hook specification with:
-            - Top-level fields: continue, suppressOutput, decision, reason,
-              permissionDecision, systemMessage
-            - MoAI-ADK internal fields (context_files, suggestions, exit_code)
-              are NOT included in JSON output (used for internal logic only)
-
-        Examples:
-            >>> result = HookResult(continue_execution=True)
-            >>> result.to_dict()
-            {'continue': True}
-
-            >>> result = HookResult(decision="block", reason="Dangerous")
-            >>> result.to_dict()
-            {'decision': 'block', 'reason': 'Dangerous'}
-
-            >>> result = HookResult(system_message="Test")
-            >>> result.to_dict()
-            {'continue': True, 'systemMessage': 'Test'}
-
-        Note:
-            - systemMessage is a TOP-LEVEL field (not nested in hookSpecificOutput)
-            - hookSpecificOutput is ONLY used for UserPromptSubmit events
-            - context_files, suggestions, exit_code are internal-only fields
-        """
-        output: dict[str, Any] = {}
-
-        # Add decision or continue flag
-        if self.decision:
-            output["decision"] = self.decision
-        else:
-            output["continue"] = self.continue_execution
-
-        # Add reason if provided (works with both decision and permissionDecision)
-        if self.reason:
-            output["reason"] = self.reason
-
-        # Add suppressOutput if True
-        if self.suppress_output:
-            output["suppressOutput"] = True
-
-        # Add permissionDecision if set
-        if self.permission_decision:
-            output["permissionDecision"] = self.permission_decision
-
-        # Add systemMessage at TOP LEVEL (required by Claude Code schema)
-        if self.system_message:
-            output["systemMessage"] = self.system_message
-
-        # Note: context_files, suggestions, exit_code are internal-only fields
-        # and are NOT included in the JSON output per Claude Code schema
-
-        return output
-
-    def to_user_prompt_submit_dict(self) -> dict[str, Any]:
-        """UserPromptSubmit Hook-specific output format.
-
-        Claude Code requires a special schema for UserPromptSubmit events.
-        The result is wrapped in the standard Hook schema with hookSpecificOutput.
-
-        Returns:
-            Claude Code UserPromptSubmit Hook Dictionary matching schema:
-            {
-                "continue": true,
-                "hookSpecificOutput": {
-                    "hookEventName": "UserPromptSubmit",
-                    "additionalContext": "string"
-                }
-            }
-
-        Examples:
-            >>> result = HookResult(context_files=["tests/"])
-            >>> result.to_user_prompt_submit_dict()
-            {'continue': True, 'hookSpecificOutput': \
-{'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}}
-        """
-        # Convert context_files to additionalContext string
-        if self.context_files:
-            context_str = "\n".join([f"📎 Context: {f}" for f in self.context_files])
-        else:
-            context_str = ""
-
-        # Add system_message if there is one
-        if self.system_message:
-            if context_str:
-                context_str = f"{self.system_message}\n\n{context_str}"
-            else:
-                context_str = self.system_message
-
-        return {
-            "continue": self.continue_execution,
-            "hookSpecificOutput": {
-                "hookEventName": "UserPromptSubmit",
-                "additionalContext": context_str,
-            },
-        }
-
-
-__all__ = ["HookPayload", "HookResult"]
-
-# Note: core module exports:
-# - HookPayload, HookResult (type definitions)
-# - project.py: detect_language, get_git_info, count_specs, get_project_language
-# - context.py: get_jit_context
-# - checkpoint.py: detect_risky_operation, create_checkpoint, log_checkpoint, list_checkpoints

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

@@ -1,67 +0,0 @@
-#!/usr/bin/env python3
-"""Context Engineering utilities
-
-JIT (Just-in-Time) Retrieval
-"""
-
-from pathlib import Path
-
-
-def get_jit_context(prompt: str, cwd: str) -> list[str]:
-    """JIT Context Retrieval based on prompt.
-
-    Analyze user prompts and automatically recommend relevant documents.
-    Alfred commands and keyword-based pattern matching load only the documents you need.
-
-    Args:
-        prompt: Prompt for user input (case is irrelevant)
-        cwd: Project root directory path
-
-    Returns:
-        List of recommended document paths (relative paths).
-        If there is no matching pattern or file, an empty list []
-
-    Patterns:
-        - "/alfred:1-plan" → .claude/skills/moai-alfred-spec-metadata-extended/reference.md
-        - "/alfred:2-run" → .claude/skills/moai-alfred-dev-guide/reference.md
-        - "test" → tests/ (if directory exists)
-
-    Examples:
-        >>> get_jit_context("/alfred:1-plan", "/project")
-        ['.claude/skills/moai-alfred-spec-metadata-extended/reference.md']
-        >>> get_jit_context("implement test", "/project")
-        ['tests/']
-        >>> get_jit_context("unknown", "/project")
-        []
-
-    Notes:
-        - Context Engineering: Compliance with JIT Retrieval principles
-        - Minimize initial context burden by loading only necessary documents
-        - Return after checking whether file exists
-
-    TDD History:
-        - RED: 18 items scenario testing (command matching, keywords, empty results)
-        - GREEN: Pattern matching dictionary-based implementation
-        - REFACTOR: Expandable pattern structure, file existence validation added
-    """
-    context_files = []
-    cwd_path = Path(cwd)
-
-    # Pattern matching
-    patterns = {
-        "/alfred:1-plan": [".claude/skills/moai-alfred-spec-metadata-extended/reference.md"],
-        "/alfred:2-run": [".claude/skills/moai-alfred-dev-guide/reference.md"],
-        "test": ["tests/"],
-    }
-
-    for pattern, files in patterns.items():
-        if pattern in prompt.lower():
-            for file in files:
-                file_path = cwd_path / file
-                if file_path.exists():
-                    context_files.append(file)
-
-    return context_files
-
-
-__all__ = ["get_jit_context"]

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

@@ -1,230 +0,0 @@
-#!/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