moai-adk 0.11.0__py3-none-any.whl → 0.12.0__py3-none-any.whl

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

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-CKPT | SPEC: Individual hook files for better UX
+"""PreToolUse Hook: Automatic Safety Checkpoint Creation
+
+Claude Code Event: PreToolUse
+Purpose: Detect risky operations and automatically create Git checkpoints before execution
+Execution: Triggered before Edit, Write, or MultiEdit tools are used
+Matcher: Edit|Write|MultiEdit
+
+Output: System message with checkpoint information (if created)
+
+Risky Operations Detected:
+- Bash: rm -rf, git merge, git reset --hard
+- Edit/Write: CLAUDE.md, config.json, critical files
+- MultiEdit: Operations affecting ≥10 files
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from utils.timeout import CrossPlatformTimeout, 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_pre_tool_use
+
+
+
+
+def main() -> None:
+    """Main entry point for PreToolUse hook
+
+    Analyzes tool usage and creates checkpoints for risky operations:
+    1. Detects dangerous patterns (rm -rf, git reset, etc.)
+    2. Creates Git checkpoint: checkpoint/before-{operation}-{timestamp}
+    3. Logs checkpoint to .moai/checkpoints.log
+    4. Returns guidance message to user
+
+    Exit Codes:
+        0: Success (checkpoint created or not needed)
+        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_pre_tool_use(data)
+
+        # Output result as JSON
+        print(json.dumps(result.to_dict()))
+        sys.exit(0)
+
+    except PlatformTimeoutError:
+        # Timeout - return minimal valid response (allow operation to continue)
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "systemMessage": "⚠️ Checkpoint creation timeout - operation proceeding without checkpoint",
+        }
+        print(json.dumps(timeout_response))
+        print("PreToolUse hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error - allow operation to continue
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"JSON parse error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"PreToolUse JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error - allow operation to continue
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {"error": f"PreToolUse error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"PreToolUse 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/session_end__cleanup.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-CLEAN | SPEC: Individual hook files for better UX
+"""SessionEnd Hook: Session Cleanup and Finalization
+
+Claude Code Event: SessionEnd
+Purpose: Clean up resources and finalize session when Claude Code exits
+Execution: Triggered when Claude Code session ends
+
+Output: Continue execution (currently a stub for future enhancements)
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from utils.timeout import CrossPlatformTimeout, 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_end
+
+
+
+
+def main() -> None:
+    """Main entry point for SessionEnd hook
+
+    Currently a stub for future functionality:
+    - Clear temporary caches
+    - Save session metrics
+    - Upload analytics (if enabled)
+    - Cleanup background processes
+
+    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_end(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": "⚠️ SessionEnd cleanup timeout - session ending anyway",
+        }
+        print(json.dumps(timeout_response))
+        print("SessionEnd 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"SessionEnd 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"SessionEnd error: {e}"},
+        }
+        print(json.dumps(error_response))
+        print(f"SessionEnd 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/session_start__show_project_info.py

@@ -0,0 +1,97 @@
+#!/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
+from utils.timeout import CrossPlatformTimeout, TimeoutError as PlatformTimeoutError
+ Path
+from typing import Any
+
+# 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
+
+
+    pass
+
+
+
+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

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