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

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

@@ -0,0 +1,351 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-CLEAN | SPEC: Daily analysis handler with self-learning
+"""Daily Analysis Handler: Trigger daily session analysis and self-learning
+
+This handler implements daily session analysis with self-learning capabilities
+for continuous improvement and adaptation of Claude Code usage patterns.
+"""
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict
+
+
+@dataclass
+class AnalysisResult:
+    """Result of daily analysis operation"""
+    continue_execution: bool = True
+    analysis_completed: bool = False
+    days_since_last_analysis: int = 0
+    report_path: str = ""
+    message: str = ""
+
+
+def handle_daily_analysis(session_data: Dict[str, Any]) -> AnalysisResult:
+    """Handle daily session analysis
+
+    Args:
+        session_data: Session start data from Claude Code
+
+    Returns:
+        AnalysisResult: Analysis operation result
+    """
+    project_root = Path(session_data.get("projectPath", "."))
+    moai_dir = project_root / ".moai"
+
+    if not moai_dir.exists():
+        return AnalysisResult(
+            message="No .moai directory found - skipping daily analysis"
+        )
+
+    # Check last analysis date
+    last_analysis_file = moai_dir / "last_analysis_date.json"
+    cutoff_days = 1  # Run analysis every day
+
+    today = datetime.now()
+    last_analysis_date = None
+
+    if last_analysis_file.exists():
+        try:
+            last_data = json.loads(last_analysis_file.read_text(encoding="utf-8"))
+            last_analysis_str = last_data.get("last_analysis_date")
+            if last_analysis_str:
+                last_analysis_date = datetime.fromisoformat(last_analysis_str)
+        except (json.JSONDecodeError, ValueError, KeyError):
+            pass  # If file is corrupt, ignore and proceed
+
+    days_since_last = (today - last_analysis_date).days if last_analysis_date else 999
+
+    if days_since_last < cutoff_days:
+        return AnalysisResult(
+            analysis_completed=False,
+            days_since_last_analysis=days_since_last,
+            message=f"Analysis not due yet (last: {days_since_last} days ago)"
+        )
+
+    # Run analysis
+    return _run_daily_analysis(project_root, moai_dir, today)
+
+
+def _run_daily_analysis(project_root: Path, moai_dir: Path, analysis_date: datetime) -> AnalysisResult:
+    """Run the actual daily analysis
+
+    Args:
+        project_root: Project root directory
+        moai_dir: .moai directory
+        analysis_date: Current analysis date
+
+    Returns:
+        AnalysisResult: Analysis operation result
+    """
+    try:
+        # Import session analyzer from moai-adk package
+        from moai_adk.core.analysis import SessionAnalyzer
+
+        # Create analyzer for last 1 day
+        analyzer = SessionAnalyzer(days_back=1, verbose=False)
+
+        # Run analysis
+        analysis_results = analyzer.parse_sessions()
+
+        # Generate report
+        reports_dir = moai_dir / "reports"
+        reports_dir.mkdir(exist_ok=True)
+
+        report_filename = f"daily-{analysis_date.strftime('%Y-%m-%d')}.md"
+        report_path = reports_dir / report_filename
+
+        # Generate report content
+        report_content = _generate_daily_report(analysis_results, analysis_date)
+        report_path.write_text(report_content, encoding="utf-8")
+
+        # Update last analysis date
+        last_analysis_file = moai_dir / "last_analysis_date.json"
+        last_analysis_data = {
+            "last_analysis_date": analysis_date.isoformat(),
+            "report_file": report_filename,
+            "metrics": {
+                "total_sessions": analysis_results.get("total_sessions", 0),
+                "total_events": analysis_results.get("total_events", 0),
+                "success_rate": analysis_results.get("success_rate", 0.0)
+            }
+        }
+        last_analysis_file.write_text(json.dumps(last_analysis_data, indent=2), encoding="utf-8")
+
+        # Self-learning: Store patterns and insights
+        _store_learning_patterns(moai_dir, analysis_results, analysis_date)
+
+        return AnalysisResult(
+            continue_execution=True,
+            analysis_completed=True,
+            days_since_last_analysis=1,
+            report_path=str(report_path.relative_to(project_root)),
+            message=f"Daily analysis completed: {len(analysis_results.get('tool_usage', {}))} tools analyzed"
+        )
+
+    except Exception as e:
+        return AnalysisResult(
+            analysis_completed=False,
+            message=f"Analysis failed: {str(e)}"
+        )
+
+
+def _generate_daily_report(analysis_results: Dict[str, Any], analysis_date: datetime) -> str:
+    """Generate daily analysis report content
+
+    Args:
+        analysis_results: Results from session analysis
+        analysis_date: Analysis date
+
+    Returns:
+        str: Markdown report content
+    """
+    report_lines = [
+        "# Daily Session Analysis Report",
+        "",
+        f"**Analysis Date**: {analysis_date.strftime('%Y-%m-%d %H:%M:%S')}",
+        "**Analysis Period**: Last 24 hours",
+        "",
+        "## Summary Metrics",
+        "",
+        f"- **Total Sessions**: {analysis_results.get('total_sessions', 0)}",
+        f"- **Total Events**: {analysis_results.get('total_events', 0)}",
+        f"- **Success Rate**: {analysis_results.get('success_rate', 0):.1%}",
+        f"- **Failed Sessions**: {analysis_results.get('failed_sessions', 0)}",
+        "",
+        "## Tool Usage",
+        ""
+    ]
+
+    tool_usage = analysis_results.get("tool_usage", {})
+    if tool_usage:
+        for tool, count in sorted(tool_usage.items(), key=lambda x: x[1], reverse=True)[:10]:
+            report_lines.append(f"- **{tool}**: {count} uses")
+
+    report_lines.extend([
+        "",
+        "## Error Patterns",
+        ""
+    ])
+
+    error_patterns = analysis_results.get("error_patterns", {})
+    if error_patterns:
+        for error, count in sorted(error_patterns.items(), key=lambda x: x[1], reverse=True)[:5]:
+            report_lines.append(f"- **{error}**: {count} occurrences")
+    else:
+        report_lines.append("- No error patterns detected")
+
+    report_lines.extend([
+        "",
+        "## Daily Insights",
+        "",
+        "1. Monitor tool usage patterns for daily optimization opportunities",
+        "2. Address any recurring error patterns immediately",
+        "3. Review frequently used tools for performance optimization",
+        "4. Track daily productivity and workflow efficiency",
+        "",
+        "---",
+        "*Generated by MoAI-ADK Daily Analysis*"
+    ])
+
+    return "\n".join(report_lines)
+
+
+def to_dict(self) -> Dict[str, Any]:
+    """Convert AnalysisResult to dictionary for JSON serialization"""
+    return {
+        "continue": self.continue_execution,
+        "hookSpecificOutput": {
+            "analysis_completed": self.analysis_completed,
+            "days_since_last_analysis": self.days_since_last_analysis,
+            "report_path": self.report_path,
+            "message": self.message
+        }
+    }
+
+
+def _store_learning_patterns(moai_dir: Path, analysis_results: Dict[str, Any], analysis_date: datetime) -> None:
+    """Store daily analysis results for self-learning and pattern recognition
+
+    Args:
+        moai_dir: .moai directory
+        analysis_results: Results from session analysis
+        analysis_date: Analysis date
+    """
+    memory_dir = moai_dir / "memory"
+    patterns_file = memory_dir / "daily-patterns.json"
+
+    # Load existing patterns
+    if patterns_file.exists():
+        patterns_data = json.loads(patterns_file.read_text(encoding="utf-8"))
+    else:
+        patterns_data = {
+            "version": "1.0.0",
+            "created_at": analysis_date.isoformat(),
+            "last_updated": analysis_date.isoformat(),
+            "patterns": {
+                "tool_usage": {},
+                "error_patterns": {},
+                "success_patterns": {},
+                "workflow_optimizations": {}
+            },
+            "insights": {
+                "most_used_tools": [],
+                "common_errors": [],
+                "optimization_suggestions": []
+            },
+            "metadata": {
+                "total_days_analyzed": 0,
+                "patterns_identified": 0,
+                "insights_generated": 0
+            }
+        }
+
+    # Update tool usage patterns
+    tool_usage = analysis_results.get("tool_usage", {})
+    for tool, count in tool_usage.items():
+        if tool not in patterns_data["patterns"]["tool_usage"]:
+            patterns_data["patterns"]["tool_usage"][tool] = []
+        patterns_data["patterns"]["tool_usage"][tool].append({
+            "date": analysis_date.isoformat(),
+            "count": count,
+            "type": "usage"
+        })
+
+    # Update error patterns
+    error_patterns = analysis_results.get("error_patterns", {})
+    for error, count in error_patterns.items():
+        if error not in patterns_data["patterns"]["error_patterns"]:
+            patterns_data["patterns"]["error_patterns"][error] = []
+        patterns_data["patterns"]["error_patterns"][error].append({
+            "date": analysis_date.isoformat(),
+            "count": count,
+            "type": "error"
+        })
+
+    # Update success rate patterns
+    success_rate = analysis_results.get("success_rate", 0.0)
+    if "daily_success_rates" not in patterns_data["patterns"]:
+        patterns_data["patterns"]["daily_success_rates"] = []
+    patterns_data["patterns"]["daily_success_rates"].append({
+        "date": analysis_date.isoformat(),
+        "rate": success_rate
+    })
+
+    # Generate insights
+    insights = _generate_insights(patterns_data, analysis_results)
+    patterns_data["insights"].update(insights)
+
+    # Update metadata
+    patterns_data["last_updated"] = analysis_date.isoformat()
+    patterns_data["metadata"]["total_days_analyzed"] += 1
+    patterns_data["metadata"]["patterns_identified"] = len(tool_usage) + len(error_patterns)
+    patterns_data["metadata"]["insights_generated"] = len([v for v in insights.values() if v])
+
+    # Save updated patterns
+    patterns_file.write_text(json.dumps(patterns_data, indent=2), encoding="utf-8")
+
+
+def _generate_insights(patterns_data: Dict[str, Any], current_results: Dict[str, Any]) -> Dict[str, Any]:
+    """Generate insights from analysis patterns
+
+    Args:
+        patterns_data: Existing patterns data
+        current_results: Current day's analysis results
+
+    Returns:
+        Dict[str, Any]: Generated insights
+    """
+    insights = {}
+
+    # Most used tools insight
+    tool_usage = current_results.get("tool_usage", {})
+    if tool_usage:
+        most_used = max(tool_usage.items(), key=lambda x: x[1])
+        insights["most_used_tools"] = [{
+            "tool": most_used[0],
+            "count": most_used[1],
+            "date": datetime.now().isoformat()
+        }]
+
+    # Common errors insight
+    error_patterns = current_results.get("error_patterns", {})
+    if error_patterns:
+        most_common_error = max(error_patterns.items(), key=lambda x: x[1])
+        insights["common_errors"] = [{
+            "error": most_common_error[0],
+            "count": most_common_error[1],
+            "date": datetime.now().isoformat()
+        }]
+
+    # Optimization suggestions
+    suggestions = []
+
+    # Suggest optimization for frequently used tools
+    if tool_usage:
+        top_tools = sorted(tool_usage.items(), key=lambda x: x[1], reverse=True)[:3]
+        suggestions.append({
+            "type": "tool_optimization",
+            "description": f"Focus on optimizing {top_tools[0][0]} usage ({top_tools[0][1]} uses)",
+            "priority": "high"
+        })
+
+    # Suggest error resolution
+    if error_patterns:
+        for error, count in error_patterns.items():
+            if count >= 3:  # Errors occurring 3+ times
+                suggestions.append({
+                    "type": "error_resolution",
+                    "description": f"Address recurring error: {error} ({count} occurrences)",
+                    "priority": "critical"
+                })
+
+    insights["optimization_suggestions"] = suggestions
+
+    return insights
+
+
+# Add to_dict method to AnalysisResult
+AnalysisResult.to_dict = to_dict

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""Notification and control handlers
+
+Notification, Stop, SubagentStop event handling
+"""
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from core import HookPayload, HookResult
+
+
+def _get_command_state_file(cwd: str) -> Path:
+    """Get the path to command state tracking file"""
+    state_dir = Path(cwd) / ".moai" / "memory"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "command-execution-state.json"
+
+
+def _load_command_state(cwd: str) -> dict:
+    """Load current command execution state"""
+    try:
+        state_file = _get_command_state_file(cwd)
+        if state_file.exists():
+            with open(state_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+    except Exception:
+        pass
+    return {"last_command": None, "last_timestamp": None, "is_running": False}
+
+
+def _save_command_state(cwd: str, state: dict) -> None:
+    """Save command execution state"""
+    try:
+        state_file = _get_command_state_file(cwd)
+        with open(state_file, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2)
+    except Exception:
+        pass
+
+
+def _is_duplicate_command(current_cmd: str, last_cmd: str, last_timestamp: str) -> bool:
+    """Check if current command is a duplicate of the last one within 3 seconds"""
+    if not last_cmd or not last_timestamp or current_cmd != last_cmd:
+        return False
+
+    try:
+        last_time = datetime.fromisoformat(last_timestamp)
+        current_time = datetime.now()
+        time_diff = (current_time - last_time).total_seconds()
+        # Consider it a duplicate if same command within 3 seconds
+        return time_diff < 3
+    except Exception:
+        return False
+
+
+def handle_notification(payload: HookPayload) -> HookResult:
+    """Notification event handler
+
+    Detects and warns about duplicate command executions
+    (When the same /alfred: command is triggered multiple times within 3 seconds)
+    """
+    cwd = payload.get("cwd", ".")
+    notification = payload.get("notification", {})
+
+    # Extract command information from notification
+    current_cmd = None
+    if isinstance(notification, dict):
+        # Check if notification contains command information
+        text = notification.get("text", "") or str(notification)
+        if "/alfred:" in text:
+            # Extract /alfred: command
+            import re
+
+            match = re.search(r"/alfred:\S+", text)
+            if match:
+                current_cmd = match.group()
+
+    if not current_cmd:
+        return HookResult()
+
+    # Load current state
+    state = _load_command_state(cwd)
+    last_cmd = state.get("last_command")
+    last_timestamp = state.get("last_timestamp")
+
+    # Check for duplicate
+    if _is_duplicate_command(current_cmd, last_cmd, last_timestamp):
+        warning_msg = (
+            f"⚠️ Duplicate command detected: '{current_cmd}' "
+            f"is running multiple times within 3 seconds.\n"
+            f"This may indicate a system issue. Check logs in `.moai/logs/command-invocations.log`"
+        )
+
+        # Update state - mark as duplicate detected
+        state["duplicate_detected"] = True
+        state["duplicate_command"] = current_cmd
+        state["duplicate_timestamp"] = datetime.now().isoformat()
+        _save_command_state(cwd, state)
+
+        return HookResult(system_message=warning_msg, continue_execution=True)
+
+    # Update state with current command
+    state["last_command"] = current_cmd
+    state["last_timestamp"] = datetime.now().isoformat()
+    state["is_running"] = True
+    state["duplicate_detected"] = False
+    _save_command_state(cwd, state)
+
+    return HookResult()
+
+
+def handle_stop(payload: HookPayload) -> HookResult:
+    """Stop event handler
+
+    Marks command execution as complete
+    """
+    cwd = payload.get("cwd", ".")
+    state = _load_command_state(cwd)
+    state["is_running"] = False
+    state["last_timestamp"] = datetime.now().isoformat()
+    _save_command_state(cwd, state)
+
+    return HookResult()
+
+
+def handle_subagent_stop(payload: HookPayload) -> HookResult:
+    """SubagentStop event handler
+
+    Records when a sub-agent finishes execution
+    """
+    cwd = payload.get("cwd", ".")
+
+    # Extract subagent name if available
+    subagent_name = (
+        payload.get("subagent", {}).get("name")
+        if isinstance(payload.get("subagent"), dict)
+        else None
+    )
+
+    try:
+        state_file = _get_command_state_file(cwd).parent / "subagent-execution.log"
+        timestamp = datetime.now().isoformat()
+
+        with open(state_file, "a", encoding="utf-8") as f:
+            f.write(f"{timestamp} | Subagent Stop | {subagent_name}\n")
+    except Exception:
+        pass
+
+    return HookResult()
+
+
+__all__ = ["handle_notification", "handle_stop", "handle_subagent_stop"]

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

@@ -0,0 +1,174 @@
+#!/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, get_git_info, get_package_version_info
+
+
+def handle_session_start(payload: HookPayload) -> HookResult:
+    """SessionStart event handler with GRACEFUL DEGRADATION
+
+    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.
+    All optional operations are wrapped in try-except to ensure hook completes quickly even if
+    Git commands, file I/O, or other operations timeout or fail.
+
+    Args:
+        payload: Claude Code event payload (cwd key required)
+
+    Returns:
+        HookResult(system_message=project status summary message)
+
+    Message Format:
+        🚀 MoAI-ADK Session Started
+           [Version: {version}] - optional if version check fails
+           [Branch: {branch} ({commit hash})] - optional if git fails
+           [Changes: {Number of Changed Files}] - optional if git fails
+           [SPEC Progress: {Complete}/{Total} ({percent}%)] - optional if specs fail
+           [Checkpoints: {number} available] - optional if checkpoint list fails
+
+    Graceful Degradation Strategy:
+        - OPTIONAL: Version info (skip if timeout/failure)
+        - OPTIONAL: Git info (skip if timeout/failure)
+        - OPTIONAL: SPEC progress (skip if timeout/failure)
+        - OPTIONAL: Checkpoint list (skip if timeout/failure)
+        - Always display SOMETHING to user, never return empty message
+
+    Note:
+        - Claude Code processes SessionStart in several stages (clear → compact)
+        - Display message only at "compact" stage to prevent duplicate output
+        - "clear" step returns minimal result (empty hookSpecificOutput)
+        - CRITICAL: All optional operations must complete within 2-3 seconds total
+
+    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)
+        - UPDATE: Migrated to Claude Code standard Hook schema
+        - HOTFIX: Add graceful degradation for timeout scenarios (Issue #66)
+        - Phase 3: Add major version warning and release notes display (@TEST:MAJOR-UPDATE-001-07/08)
+
+    @TAG:CHECKPOINT-EVENT-001
+    @TAG:HOOKS-TIMEOUT-001
+    @CODE:MAJOR-UPDATE-WARN-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 minimal valid Hook result for clear phase
+        return HookResult(continue_execution=True)
+
+    cwd = payload.get("cwd", ".")
+
+    # OPTIONAL: Git info - skip if timeout/failure
+    git_info = {}
+    try:
+        git_info = get_git_info(cwd)
+    except Exception:
+        # Graceful degradation - continue without git info
+        pass
+
+    # OPTIONAL: SPEC progress - skip if timeout/failure
+    specs = {"completed": 0, "total": 0, "percentage": 0}
+    try:
+        specs = count_specs(cwd)
+    except Exception:
+        # Graceful degradation - continue without spec info
+        pass
+
+    # OPTIONAL: Checkpoint list - skip if timeout/failure
+    checkpoints = []
+    try:
+        checkpoints = list_checkpoints(cwd, max_count=10)
+    except Exception:
+        # Graceful degradation - continue without checkpoints
+        pass
+
+    # OPTIONAL: Package version info - skip if timeout/failure
+    version_info = {}
+    try:
+        version_info = get_package_version_info()
+    except Exception:
+        # Graceful degradation - continue without version info
+        pass
+
+    # Build message with available information
+    branch = git_info.get("branch", "N/A") if git_info else "N/A"
+    commit = git_info.get("commit", "N/A")[:7] if git_info else "N/A"
+    changes = git_info.get("changes", 0) if git_info else 0
+    spec_progress = f"{specs['completed']}/{specs['total']}" if specs["total"] > 0 else "0/0"
+
+    # system_message: displayed directly to the user
+    lines = [
+        "🚀 MoAI-ADK Session Started",
+        "",  # Blank line after title
+    ]
+
+    # Add version info first (at the top, right after title)
+    if version_info and version_info.get("current") != "unknown":
+        if version_info.get("update_available"):
+            # Check if this is a major version update
+            if version_info.get("is_major_update"):
+                # Major version warning
+                lines.append(
+                    f"   ⚠️  Major version update available: {version_info['current']} → {version_info['latest']}"
+                )
+                lines.append("   Breaking changes detected. Review release notes:")
+                if version_info.get("release_notes_url"):
+                    lines.append(f"   📝 {version_info['release_notes_url']}")
+            else:
+                # Regular update
+                lines.append(
+                    f"   🗿 MoAI-ADK Ver: {version_info['current']} → {version_info['latest']} available ✨"
+                )
+                if version_info.get("release_notes_url"):
+                    lines.append(f"   📝 Release Notes: {version_info['release_notes_url']}")
+
+            # Add upgrade recommendation
+            if version_info.get("upgrade_command"):
+                lines.append(f"   ⬆️  Upgrade: {version_info['upgrade_command']}")
+        else:
+            # No update available - show current version only
+            lines.append(f"   🗿 MoAI-ADK Ver: {version_info['current']}")
+
+
+    # Add Git info only if available (not degraded)
+    if git_info:
+        lines.append(f"   🌿 Branch: {branch} ({commit})")
+        lines.append(f"   📝 Changes: {changes}")
+
+        # Add last commit message if available
+        last_commit = git_info.get("last_commit", "")
+        if last_commit:
+            lines.append(f"   🔨 Last: {last_commit}")
+
+    # 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("")  # Blank line before restore command
+        lines.append("   ↩️  Restore: /alfred:0-project restore")
+
+    # Add SPEC progress only if available (not degraded) - at the bottom
+    if specs["total"] > 0:
+        lines.append(f"   📋 SPEC Progress: {spec_progress} ({specs['percentage']}%)")
+
+    system_message = "\n".join(lines)
+
+    return HookResult(system_message=system_message)
+
+
+def handle_session_end(payload: HookPayload) -> HookResult:
+    """SessionEnd event handler (default implementation)"""
+    return HookResult()
+
+
+__all__ = ["handle_session_start", "handle_session_end"]