moai-adk 0.15.0__py3-none-any.whl → 0.25.4__py3-none-any.whl

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

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

@@ -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/checkpoint.py

@@ -1,271 +0,0 @@
-#!/usr/bin/env python3
-"""Event-Driven Checkpoint system
-
-Detect risky tasks and create automatic checkpoints
-@TAG:CHECKPOINT-EVENT-001
-"""
-
-import json
-import re
-import subprocess
-from datetime import datetime
-from pathlib import Path
-from typing import Any
-
-# Script execution pattern for each language supported by MoAI-ADK
-# Python, TypeScript, Java, Go, Rust, Dart, Swift, Kotlin + Shell
-SCRIPT_EXECUTION_PATTERN = re.compile(
-    r"\b("
-    # Python ecosystem
-    r"python3?|pytest|pip|uv|"
-    # JavaScript/TypeScript ecosystem
-    r"node|npm|npx|yarn|bun|tsx|ts-node|vitest|jest|"
-    # Java ecosystem
-    r"java|javac|mvn|gradle|"
-    # Go
-    r"go|"
-    # Rust
-    r"cargo|"
-    # Dart/Flutter
-    r"dart|flutter|"
-    # Swift
-    r"swift|xcodebuild|"
-    # Kotlin
-    r"kotlinc?|"
-    # Shell scripts and build tools
-    r"bash|sh|zsh|fish|make"
-    r")\b"
-)
-
-
-def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str) -> tuple[bool, str]:
-    """Risk task detection (for Event-Driven Checkpoint)
-
-    Claude Code tool automatically detects dangerous tasks before use.
-    When a risk is detected, a checkpoint is automatically created to enable rollback.
-
-    Args:
-        tool_name: Name of the Claude Code tool (Bash, Edit, Write, MultiEdit)
-        tool_args: Tool argument dictionary
-        cwd: Project root directory path
-
-    Returns:
-        (is_risky, operation_type) tuple
-        - is_risky: Whether the operation is dangerous (bool)
-        - operation_type: operation type (str: delete, merge, script, critical-file, refactor)
-
-    Risky Operations:
-        - Bash tool: rm -rf, git merge, git reset --hard, git rebase, script execution
-        - Edit/Write tool: CLAUDE.md, config.json, .claude/skills/*.md
-        - MultiEdit tool: Edit ≥10 items File simultaneously
-        - Script execution: Python, Node, Java, Go, Rust, Dart, Swift, Kotlin, Shell scripts
-
-    Examples:
-        >>> detect_risky_operation("Bash", {"command": "rm -rf src/"}, ".")
-        (True, 'delete')
-        >>> detect_risky_operation("Edit", {"file_path": "CLAUDE.md"}, ".")
-        (True, 'critical-file')
-        >>> detect_risky_operation("Read", {"file_path": "test.py"}, ".")
-        (False, '')
-
-    Notes:
-        - Minimize false positives: ignore safe operations
-        - Performance: lightweight string matching (< 1ms)
-        - Extensibility: Easily added to the patterns dictionary
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    # Bash tool: Detect dangerous commands
-    if tool_name == "Bash":
-        command = tool_args.get("command", "")
-
-        # Mass Delete
-        if any(pattern in command for pattern in ["rm -rf", "git rm"]):
-            return (True, "delete")
-
-        # Git merge/reset/rebase
-        if any(pattern in command for pattern in ["git merge", "git reset --hard", "git rebase"]):
-            return (True, "merge")
-
-        # Execute external script (potentially destructive)
-        if any(command.startswith(prefix) for prefix in ["python ", "node ", "bash ", "sh "]):
-            return (True, "script")
-
-    # Edit/Write tool: Detect important files
-    if tool_name in ("Edit", "Write"):
-        file_path = tool_args.get("file_path", "")
-
-        critical_files = [
-            "CLAUDE.md",
-            "config.json",
-            ".claude/skills/moai-alfred-dev-guide/reference.md",
-            ".claude/skills/moai-alfred-spec-metadata-extended/reference.md",
-            ".moai/config.json",
-        ]
-
-        if any(cf in file_path for cf in critical_files):
-            return (True, "critical-file")
-
-    # MultiEdit tool: Detect large edits
-    if tool_name == "MultiEdit":
-        edits = tool_args.get("edits", [])
-        if len(edits) >= 10:
-            return (True, "refactor")
-
-    return (False, "")
-
-
-def create_checkpoint(cwd: str, operation_type: str) -> str:
-    """Create checkpoint (Git local branch)
-
-    Automatically creates checkpoints before dangerous operations.
-    Prevent remote repository contamination by creating a Git local branch.
-
-    Args:
-        cwd: Project root directory path
-        operation_type: operation type (delete, merge, script, etc.)
-
-    Returns:
-        checkpoint_branch: Created branch name
-        Returns "checkpoint-failed" on failure
-
-    Branch Naming:
-        before-{operation}-{YYYYMMDD-HHMMSS}
-        Example: before-delete-20251015-143000
-
-    Examples:
-        >>> create_checkpoint(".", "delete")
-        'before-delete-20251015-143000'
-
-    Notes:
-        - Create only local branch (no remote push)
-        - Fallback in case of Git error (ignore and continue)
-        - Do not check dirty working directory (allow uncommitted changes)
-        - Automatically record checkpoint logs (.moai/checkpoints.log)
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
-    branch_name = f"before-{operation_type}-{timestamp}"
-
-    try:
-        # Create a new local branch from the current branch (without checking out)
-        subprocess.run(
-            ["git", "branch", branch_name],
-            cwd=cwd,
-            check=True,
-            capture_output=True,
-            text=True,
-            timeout=2,
-        )
-
-        # Checkpoint log records
-        log_checkpoint(cwd, branch_name, operation_type)
-
-        return branch_name
-
-    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
-        # Fallback (ignore) in case of Git error
-        return "checkpoint-failed"
-
-
-def log_checkpoint(cwd: str, branch_name: str, operation_type: str) -> None:
-    """Checkpoint log records (.moai/checkpoints.log)
-
-    Checkpoint creation history is recorded in JSON Lines format.
-    SessionStart reads this log to display a list of checkpoints.
-
-    Args:
-        cwd: Project root directory path
-        branch_name: Created checkpoint branch name
-        operation_type: operation type
-
-    Log Format (JSON Lines):
-        {"timestamp": "2025-10-15T14:30:00", "branch": "before-delete-...", "operation": "delete"}
-
-    Examples:
-        >>> log_checkpoint(".", "before-delete-20251015-143000", "delete")
-        # Add 1 line to .moai/checkpoints.log
-
-    Notes:
-        - If the file does not exist, it is automatically created.
-        - Record in append mode (preserve existing logs)
-        - Ignored in case of failure (not critical)
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    log_file = Path(cwd) / ".moai" / "checkpoints.log"
-
-    try:
-        log_file.parent.mkdir(parents=True, exist_ok=True)
-
-        log_entry = {
-            "timestamp": datetime.now().isoformat(),
-            "branch": branch_name,
-            "operation": operation_type,
-        }
-
-        with log_file.open("a") as f:
-            f.write(json.dumps(log_entry) + "\n")
-
-    except (OSError, PermissionError):
-        # Ignore log failures (not critical)
-        pass
-
-
-def list_checkpoints(cwd: str, max_count: int = 10) -> list[dict[str, str]]:
-    """Checkpoint list (parsing .moai/checkpoints.log)
-
-    Returns a list of recently created checkpoints.
-    Used in the SessionStart, /alfred:0-project restore command.
-
-    Args:
-        cwd: Project root directory path
-        max_count: Maximum number to return (default 10 items)
-
-    Returns:
-        Checkpoint list (most recent)
-        [{"timestamp": "...", "branch": "...", "operation": "..."}, ...]
-
-    Examples:
-        >>> list_checkpoints(".")
-        [
-            {"timestamp": "2025-10-15T14:30:00", "branch": "before-delete-...", "operation": "delete"},
-            {"timestamp": "2025-10-15T14:25:00", "branch": "before-merge-...", "operation": "merge"},
-        ]
-
-    Notes:
-        - If there is no log file, an empty list is returned.
-        - Ignore lines where JSON parsing fails
-        - Return only the latest max_count
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    log_file = Path(cwd) / ".moai" / "checkpoints.log"
-
-    if not log_file.exists():
-        return []
-
-    checkpoints = []
-
-    try:
-        with log_file.open("r") as f:
-            for line in f:
-                try:
-                    checkpoints.append(json.loads(line.strip()))
-                except json.JSONDecodeError:
-                    # Ignore lines where parsing failed
-                    pass
-    except (OSError, PermissionError):
-        return []
-
-    # Return only the most recent max_count items (in order of latest)
-    return checkpoints[-max_count:]
-
-
-__all__ = [
-    "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"]