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

moai_adk/templates/.claude/hooks/alfred/README.md

@@ -1,230 +0,0 @@
-# Alfred Hooks System
-
-**Event-Driven Context Management for MoAI-ADK**
-
-Alfred Hooks integrates with Claude Code's event system to automatically manage project context, create checkpoints before risky operations, and provide just-in-time (JIT) document loading.
-
----
-
-## 📐 Architecture
-
-### Modular Design (9 Files, ≤284 LOC each)
-
-```
-.claude/hooks/alfred/
-├── alfred_hooks.py          # Main entry point (CLI router)
-├── core/                    # Core business logic
-│   ├── __init__.py         # Type definitions (HookPayload, HookResult)
-│   ├── project.py          # Language detection, Git info, SPEC counting
-│   ├── context.py          # JIT retrieval, workflow context
-│   ├── checkpoint.py       # Event-driven checkpoint creation
-│   └── tags.py             # TAG search, verification, caching
-└── handlers/                # Event handlers
-    ├── __init__.py         # Handler exports
-    ├── session.py          # SessionStart, SessionEnd
-    ├── user.py             # UserPromptSubmit
-    ├── tool.py             # PreToolUse, PostToolUse
-    └── notification.py     # Notification, Stop, SubagentStop
-```
-
-### Design Principles
-
-- **Single Responsibility**: Each module has one clear responsibility
-- **Separation of Concerns**: core (business logic) vs handlers (event processing)
-- **CODE-FIRST**: Scan code directly without intermediate cache (mtime Based invalidation)
-- **Context Engineering**: Minimize initial context burden with JIT Retrieval
-
----
-
-## 🎯 Core Modules
-
-### `core/project.py` (284 LOC)
-
-**Project metadata and language detection**
-
-```python
-# Public API
-detect_language(cwd: str) -> str
-get_project_language(cwd: str) -> str
-get_git_info(cwd: str) -> dict[str, Any]
-count_specs(cwd: str) -> dict[str, int]
-```
-
-**Features**:
-- Automatic detection of 20 languages ​​(Python, TypeScript, Java, Go, Rust, etc.)
-- `.moai/config.json` First, fallback to auto-detection
-- Check Git information (branch, commit, changes)
-- SPEC progress calculation (total, completed, percentage)
-
-### `core/context.py` (110 LOC)
-
-**JIT Context Retrieval and Workflow Management**
-
-```python
-# Public API
-get_jit_context(prompt: str, cwd: str) -> list[str]
-save_phase_context(phase: str, data: Any, ttl: int = 600)
-load_phase_context(phase: str, ttl: int = 600) -> Any | None
-clear_workflow_context()
-```
-
-**Features**:
-- Automatically recommend documents based on prompt analysis
-  - `/alfred:1-plan` → `spec-metadata.md`
-  - `/alfred:2-run` → `development-guide.md`
-- Context caching for each workflow step (TTL 10 minutes)
-- Compliance with Anthropic Context Engineering principles
-
-### `core/checkpoint.py` (244 LOC)
-
-**Event-Driven Checkpoint Automation**
-
-```python
-# Public API
-detect_risky_operation(tool: str, args: dict, cwd: str) -> tuple[bool, str]
-create_checkpoint(cwd: str, operation: str) -> str
-log_checkpoint(cwd: str, branch: str, description: str)
-list_checkpoints(cwd: str, max_count: int = 10) -> list[dict]
-```
-
-**Features**:
-- Automatic detection of dangerous tasks:
-  - Bash: `rm -rf`, `git merge`, `git reset --hard`
-  - Edit/Write: `CLAUDE.md`, `config.json`
-  - MultiEdit: ≥10 files
-- Automatic creation of Git checkpoint: `checkpoint/before-{operation}-{timestamp}`
-- Checkpoint history management and recovery guide
-
-### `core/tags.py` (244 LOC)
-
-**CODE-FIRST TAG SYSTEM**
-
-```python
-# Public API
-search_tags(pattern: str, scope: list[str], cache_ttl: int = 60) -> list[dict]
-verify_tag_chain(tag_id: str) -> dict[str, Any]
-find_all_tags_by_type(tag_type: str) -> dict[str, list[str]]
-suggest_tag_reuse(keyword: str) -> list[str]
-get_library_version(library: str, cache_ttl: int = 86400) -> str | None
-set_library_version(library: str, version: str)
-```
-
-**Features**:
-- ripgrep-based TAG search (parsing JSON output)
-- mtime-based cache invalidation (CODE-FIRST guaranteed)
-- TAG chain verification (@SPEC → @TEST → @CODE completeness check)
-- Library version caching (TTL 24 hours)
-
----
-
-## 🎬 Event Handlers
-
-### `handlers/session.py`
-
-**SessionStart, SessionEnd handlers**
-
-- **SessionStart**: Display project information
- - Language, Git status, SPEC progress, recent checkpoint
- - Display directly to user with `systemMessage` field
-- **SessionEnd**: Cleanup task (stub)
-
-### `handlers/user.py`
-
-**UserPromptSubmit Handler**
-
-- Return list of JIT Context recommended documents
-- Analyze user prompt patterns and load related documents
-
-### `handlers/tool.py`
-
-**PreToolUse, PostToolUse handlers**
-
-- **PreToolUse**: Automatic checkpoint creation when dangerous operation is detected
-- **PostToolUse**: Post-processing operation (stub)
-
-### `handlers/notification.py`
-
-**Notification, Stop, SubagentStop handlers**
-
-- Basic implementation (stub, can be expanded in the future)
-
----
-
-## 🧪 Testing
-
-### Test Suite
-
-```bash
-# Run all tests
-uv run pytest tests/unit/test_alfred_hooks_*.py -v --no-cov
-
-# Run specific module tests
-uv run pytest tests/unit/test_alfred_hooks_core_tags.py -v
-uv run pytest tests/unit/test_alfred_hooks_core_context.py -v
-uv run pytest tests/unit/test_alfred_hooks_core_project.py -v
-```
-
-### Test Coverage (18 tests)
-
-- ✅ **tags.py**: 7 tests (cache, TAG verification, version management)
-- ✅ **context.py**: 5 tests (JIT, workflow context)
-- ✅ **project.py**: 6 tests (language detection, Git, SPEC count)
-
-### Test Structure
-
-```python
-# Dynamic module loading for isolated testing
-def _load_{module}_module(module_name: str):
-    repo_root = Path(__file__).resolve().parents[2]
-    hooks_dir = repo_root / ".claude" / "hooks" / "alfred"
-    sys.path.insert(0, str(hooks_dir))
-    
-    module_path = hooks_dir / "core" / "{module}.py"
-    spec = importlib.util.spec_from_file_location(module_name, module_path)
-    # ...
-```
-
----
-
-## 🔄 Migration from moai_hooks.py
-
-### Before (Monolithic)
-
-- **1 file**: 1233 LOC
-- **Issues**: 
-- All functions concentrated in one file
- - Difficult to test, complex to maintain
- - Unclear separation of responsibilities
-
-### After (Modular)
-
-- **9 files**: ≤284 LOC each
-- **Benefits**:
-- Clear separation of responsibilities (SRP)
- - Independent module testing possible
- - Easy to expand, easy to maintain
- - Compliance with Context Engineering principles
-
-### Breaking Changes
-
-**None** - External APIs remain the same.
-
----
-
-## 📚 References
-
-### Internal Documents
-
-- **CLAUDE.md**: MoAI-ADK User Guide
-- **.moai/memory/development-guide.md**: SPEC-First TDD Workflow
-- **.moai/memory/spec-metadata.md**: SPEC metadata standard
-
-### External Resources
-
-- [Claude Code Hooks Documentation](https://docs.claude.com/en/docs/claude-code)
-- [Anthropic Context Engineering](https://docs.anthropic.com/claude/docs/context-engineering)
-
----
-
-**Last Updated**: 2025-10-16  
-**Author**: @Alfred (MoAI-ADK SuperAgent)

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

@@ -1,156 +0,0 @@
-#!/usr/bin/env python3
-# @CODE:HOOKS-REFACTOR-001 | SPEC: SPEC-HOOKS-REFACTOR-001.md
-"""Alfred Hooks - Main entry point for MoAI-ADK Claude Code Hooks
-
-A main entry point that routes Claude Code events to the appropriate handlers.
-
-🏗️ Architecture:
-┌─────────────────────────────────────────────────────────────┐
-│ alfred_hooks.py (Router)                                    │
-├─────────────────────────────────────────────────────────────┤
-│ - CLI argument parsing                                      │
-│ - JSON I/O (stdin/stdout)                                   │
-│ - Event routing to handlers                                 │
-└─────────────────────────────────────────────────────────────┘
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│ handlers/ (Event Handlers)                                  │
-├─────────────────────────────────────────────────────────────┤
-│ - session.py: SessionStart, SessionEnd                      │
-│ - user.py: UserPromptSubmit                                 │
-│ - tool.py: PreToolUse, PostToolUse                          │
-│ - notification.py: Notification, Stop, SubagentStop         │
-└─────────────────────────────────────────────────────────────┘
-                         ▼
-┌─────────────────────────────────────────────────────────────┐
-│ core/ (Business Logic)                                      │
-├─────────────────────────────────────────────────────────────┤
-│ - project.py: Language detection, Git info, SPEC progress   │
-│ - context.py: JIT Retrieval, workflow context               │
-│ - checkpoint.py: Event-Driven Checkpoint system             │
-│ - tags.py: TAG search/verification, library version cache   │
-└─────────────────────────────────────────────────────────────┘
-
-🛠️ Usage:
-    python alfred_hooks.py <event_name> < payload.json
-
-📣 Supported Events:
-    - SessionStart: Start Session (display project status)
-    - UserPromptSubmit: Prompt submission (JIT document loading)
-    - PreToolUse: Before using the tool (automatically creates checkpoint)
-    - SessionEnd, PostToolUse, Notification, Stop, SubagentStop
-
-🚦 Exit Codes:
-    - 0: Success
-    - 1: Error (no arguments, JSON parsing failure, exception thrown)
-
-🧪 TDD History:
-    - RED: Module separation design, event routing test
-    - GREEN: 1233 LOC → 9 items Module separation implementation (SRP compliance)
-    - REFACTOR: Import optimization, enhanced error handling
-
-Setup sys.path for package imports
-"""
-
-import json
-import sys
-from pathlib import Path
-
-from core import HookResult
-from handlers import (
-    handle_notification,
-    handle_post_tool_use,
-    handle_pre_tool_use,
-    handle_session_end,
-    handle_session_start,
-    handle_stop,
-    handle_subagent_stop,
-    handle_user_prompt_submit,
-)
-
-# Add the hooks directory to sys.path to enable package imports
-HOOKS_DIR = Path(__file__).parent
-if str(HOOKS_DIR) not in sys.path:
-    sys.path.insert(0, str(HOOKS_DIR))
-
-
-def main() -> None:
-    """Main entry point - Claude Code Hook script
-
-    Receives the event name as a CLI argument and reads the JSON payload through stdin.
-    Calls the handler appropriate for the event and outputs the results to stdout as JSON.
-
-    🛠️ Usage:
-        python alfred_hooks.py <event_name> < payload.json
-
-    📣 Supported Events:
-        - SessionStart: Start Session (display project status)
-        - UserPromptSubmit: Prompt submission (JIT document loading)
-        - SessionEnd, PreToolUse, PostToolUse, Notification, Stop, SubagentStop
-
-    🚦 Exit Codes:
-        - 0: Success
-        - 1: Error (no arguments, JSON parsing failure, exception thrown)
-
-    📝 Examples:
-        $ echo '{"cwd": "."}' | python alfred_hooks.py SessionStart
-        {"message": "🚀 MoAI-ADK Session Started\\n...", ...}
-
-    🗒️ Notes:
-        - Claude Code is automatically called (no need for direct user execution)
-        - JSON I/O processing through stdin/stdout
-        - Print error message to stderr
-        - UserPromptSubmit uses a special output schema (hookEventName + additionalContext)
-
-    🧪 TDD History:
-        - RED: Event routing, JSON I/O, error handling testing
-        - GREEN: Handler map-based routing implementation
-        - REFACTOR: Error message clarification, exit code standardization, UserPromptSubmit schema separation
-    """
-    # Check for event argument
-    if len(sys.argv) < 2:
-        print("Usage: alfred_hooks.py <event>", file=sys.stderr)
-        sys.exit(1)
-
-    event_name = sys.argv[1]
-
-    try:
-        # Read JSON from stdin
-        input_data = sys.stdin.read()
-        data = json.loads(input_data)
-
-        cwd = data.get("cwd", ".")
-
-        # Route to appropriate handler
-        handlers = {
-            "SessionStart": handle_session_start,
-            "UserPromptSubmit": handle_user_prompt_submit,
-            "SessionEnd": handle_session_end,
-            "PreToolUse": handle_pre_tool_use,
-            "PostToolUse": handle_post_tool_use,
-            "Notification": handle_notification,
-            "Stop": handle_stop,
-            "SubagentStop": handle_subagent_stop,
-        }
-
-        handler = handlers.get(event_name)
-        result = handler({"cwd": cwd, **data}) if handler else HookResult()
-
-        # UserPromptSubmit uses a special output schema
-        if event_name == "UserPromptSubmit":
-            print(json.dumps(result.to_user_prompt_submit_dict()))
-        else:
-            print(json.dumps(result.to_dict()))
-
-        sys.exit(0)
-
-    except json.JSONDecodeError as e:
-        print(f"JSON parse error: {e}", file=sys.stderr)
-        sys.exit(1)
-    except Exception as e:
-        print(f"Unexpected error: {e}", file=sys.stderr)
-        sys.exit(1)
-
-
-if __name__ == "__main__":
-    main()

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

@@ -1,85 +0,0 @@
-#!/usr/bin/env python3
-"""Core module for Alfred Hooks
-
-Common type definitions and utility functions
-"""
-
-from dataclasses import asdict, dataclass, field
-from typing import Any, 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"""
-
-    message: str | None = None
-    systemMessage: str | None = None  # Message displayed directly to the user  # noqa: N815
-    blocked: bool = False
-    contextFiles: list[str] = field(default_factory=list)  # noqa: N815
-    suggestions: list[str] = field(default_factory=list)
-    exitCode: int = 0  # noqa: N815
-
-    def to_dict(self) -> dict[str, Any]:
-        """Dictionary conversion for general Hook"""
-        return asdict(self)
-
-    def to_user_prompt_submit_dict(self) -> dict[str, Any]:
-        """UserPromptSubmit Hook-specific output format
-
-        Claude Code requires a special schema for UserPromptSubmit:
-        {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": "string (required)"
-        }
-
-        Returns:
-            Claude Code UserPromptSubmit Hook Dictionary matching schema
-
-        Examples:
-            >>> result = HookResult(contextFiles=["tests/"])
-            >>> result.to_user_prompt_submit_dict()
-            {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}
-        """
-        # Convert contextFiles to additionalContext string
-        if self.contextFiles:
-            context_str = "\n".join([f"📎 Context: {f}" for f in self.contextFiles])
-        else:
-            context_str = ""
-
-        # Add message if there is one
-        if self.message:
-            if context_str:
-                context_str = f"{self.message}\n\n{context_str}"
-            else:
-                context_str = self.message
-
-        # If the string is empty, use default
-        if not context_str:
-            context_str = ""
-
-        return {
-            "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/handlers/notification.py

@@ -1,25 +0,0 @@
-#!/usr/bin/env python3
-"""Notification and control handlers
-
-Notification, Stop, SubagentStop event handling
-"""
-
-from core import HookPayload, HookResult
-
-
-def handle_notification(payload: HookPayload) -> HookResult:
-    """Notification event handler (default implementation)"""
-    return HookResult()
-
-
-def handle_stop(payload: HookPayload) -> HookResult:
-    """Stop event handler (default implementation)"""
-    return HookResult()
-
-
-def handle_subagent_stop(payload: HookPayload) -> HookResult:
-    """SubagentStop event handler (default implementation)"""
-    return HookResult()
-
-
-__all__ = ["handle_notification", "handle_stop", "handle_subagent_stop"]

moai_adk/templates/.claude/hooks/alfred/handlers/session.py

@@ -1,92 +0,0 @@
-#!/usr/bin/env python3
-"""Session event handlers
-
-SessionStart, SessionEnd event handling
-"""
-
-from core import HookPayload, HookResult
-from core.checkpoint import list_checkpoints
-from core.project import count_specs, detect_language, get_git_info
-
-
-def handle_session_start(payload: HookPayload) -> HookResult:
-    """SessionStart event handler (with Checkpoint list)
-
-    When Claude Code Session starts, it displays a summary of project status.
-    You can check the language, Git status, SPEC progress, and checkpoint list at a glance.
-
-    Args:
-        payload: Claude Code event payload (cwd key required)
-
-    Returns:
-        HookResult(message=project status summary message, systemMessage=for user display)
-
-    Message Format:
-        🚀 MoAI-ADK Session Started
-           Language: {language}
-           Branch: {branch} ({commit hash})
-           Changes: {Number of Changed Files}
-           SPEC Progress: {Complete}/{Total} ({percent}%)
-           Checkpoints: {number} available (showing the latest 3 items)
-
-    Note:
-        - Claude Code processes SessionStart in several stages (clear → compact)
-        - Display message only at “compact” stage to prevent duplicate output
-        - "clear" step returns empty result (invisible to user)
-
-    TDD History:
-        - RED: Session startup message format test
-        - GREEN: Generate status message by combining helper functions
-        - REFACTOR: Improved message format, improved readability, added checkpoint list
-        - FIX: Prevent duplicate output of clear step (only compact step is displayed)
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    # Claude Code SessionStart runs in several stages (clear, compact, etc.)
-    # Ignore the "clear" stage and output messages only at the "compact" stage
-    event_phase = payload.get("phase", "")
-    if event_phase == "clear":
-        return HookResult() # returns an empty result (prevents duplicate output)
-
-    cwd = payload.get("cwd", ".")
-    language = detect_language(cwd)
-    git_info = get_git_info(cwd)
-    specs = count_specs(cwd)
-    checkpoints = list_checkpoints(cwd, max_count=10)
-
-    branch = git_info.get("branch", "N/A")
-    commit = git_info.get("commit", "N/A")[:7]
-    changes = git_info.get("changes", 0)
-    spec_progress = f"{specs['completed']}/{specs['total']}"
-
-    # systemMessage: displayed directly to the user
-    lines = [
-        "🚀 MoAI-ADK Session Started",
-        f"   Language: {language}",
-        f"   Branch: {branch} ({commit})",
-        f"   Changes: {changes}",
-        f"   SPEC Progress: {spec_progress} ({specs['percentage']}%)",
-    ]
-
-    # Add Checkpoint list (show only the latest 3 items)
-    if checkpoints:
-        lines.append(f"   Checkpoints: {len(checkpoints)} available")
-        for cp in reversed(checkpoints[-3:]):  # Latest 3 items
-            branch_short = cp["branch"].replace("before-", "")
-            lines.append(f"      - {branch_short}")
-        lines.append("   Restore: /alfred:0-project restore")
-
-    system_message = "\n".join(lines)
-
-    return HookResult(
-        message=system_message, # for Claude context
-        systemMessage=system_message, # For user display
-    )
-
-
-def handle_session_end(payload: HookPayload) -> HookResult:
-    """SessionEnd event handler (default implementation)"""
-    return HookResult()
-
-
-__all__ = ["handle_session_start", "handle_session_end"]

moai_adk/templates/.claude/hooks/alfred/handlers/tool.py

@@ -1,70 +0,0 @@
-#!/usr/bin/env python3
-"""Tool usage handlers
-
-PreToolUse, PostToolUse event handling
-"""
-
-from core import HookPayload, HookResult
-from core.checkpoint import create_checkpoint, detect_risky_operation
-
-
-def handle_pre_tool_use(payload: HookPayload) -> HookResult:
-    """PreToolUse event handler (Event-Driven Checkpoint integration)
-
-    Automatically creates checkpoints before dangerous operations.
-    Called before using the Claude Code tool, it notifies the user when danger is detected.
-
-    Args:
-        payload: Claude Code event payload
-                 (includes tool, arguments, cwd keys)
-
-    Returns:
-        HookResult(
-            message=checkpoint creation notification (when danger is detected);
-            blocked=False (always continue operation)
-        )
-
-    Checkpoint Triggers:
-        - Bash: rm -rf, git merge, git reset --hard
-        - Edit/Write: CLAUDE.md, config.json
-        - MultiEdit: ≥10 files
-
-    Examples:
-        Bash tool (rm -rf) detection:
-        → "🛡️ Checkpoint created: before-delete-20251015-143000"
-
-    Notes:
-        - Return blocked=False even after detection of danger (continue operation)
-        - Work continues even when checkpoint fails (ignores)
-        - Transparent background operation
-
-    @TAG:CHECKPOINT-EVENT-001
-    """
-    tool_name = payload.get("tool", "")
-    tool_args = payload.get("arguments", {})
-    cwd = payload.get("cwd", ".")
-
-    # Dangerous operation detection
-    is_risky, operation_type = detect_risky_operation(tool_name, tool_args, cwd)
-
-    # Create checkpoint when danger is detected
-    if is_risky:
-        checkpoint_branch = create_checkpoint(cwd, operation_type)
-
-        if checkpoint_branch != "checkpoint-failed":
-            message = (
-                f"🛡️ Checkpoint created: {checkpoint_branch}\n"
-                f"   Operation: {operation_type}"
-            )
-
-            return HookResult(message=message, blocked=False)
-
-    return HookResult(blocked=False)
-
-
-def handle_post_tool_use(payload: HookPayload) -> HookResult:
-    """PostToolUse event handler (default implementation)"""
-    return HookResult()
-
-
-__all__ = ["handle_pre_tool_use", "handle_post_tool_use"]