@hustle-together/api-dev-tools 3.6.5 → 3.10.0

package/hooks/session-logger.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""
+Hook: Stop
+Purpose: Save session to .claude/api-sessions/ for later review
+
+This hook runs when a Claude Code session ends (Stop event).
+It saves the session data for the completed workflow including:
+  - State snapshot at completion
+  - Files created during the workflow
+  - Summary of phases completed
+  - Research sources used
+  - Interview decisions made
+
+Added in v3.6.7 for session logging support.
+
+Returns:
+  - JSON with session save info
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+import shutil
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+SESSIONS_DIR = Path(__file__).parent.parent / "api-sessions"
+RESEARCH_DIR = Path(__file__).parent.parent / "research"
+
+
+def get_active_endpoint(state):
+    """Get active endpoint - supports both old and new state formats."""
+    # New format (v3.6.7+): endpoints object with active_endpoint pointer
+    if "endpoints" in state and "active_endpoint" in state:
+        active = state.get("active_endpoint")
+        if active and active in state["endpoints"]:
+            return active, state["endpoints"][active]
+        return None, None
+
+    # Old format: single endpoint field
+    endpoint = state.get("endpoint")
+    if endpoint:
+        return endpoint, state
+
+    return None, None
+
+
+def get_completed_phases(endpoint_data):
+    """Get list of completed phases."""
+    completed = []
+    phases = endpoint_data.get("phases", {})
+
+    phase_order = [
+        "disambiguation", "scope", "research_initial", "interview",
+        "research_deep", "schema_creation", "environment_check",
+        "tdd_red", "tdd_green", "verify", "tdd_refactor", "documentation", "completion"
+    ]
+
+    for phase_name in phase_order:
+        phase = phases.get(phase_name, {})
+        if phase.get("status") == "complete":
+            completed.append(phase_name)
+
+    return completed
+
+
+def get_files_created(endpoint_data):
+    """Get list of files created during this workflow."""
+    files = []
+
+    # From completion phase
+    completion = endpoint_data.get("phases", {}).get("completion", {})
+    files.extend(completion.get("files_created", []))
+
+    # From schema phase
+    schema = endpoint_data.get("phases", {}).get("schema_creation", {})
+    if schema.get("schema_file"):
+        files.append(schema.get("schema_file"))
+
+    # From TDD phases
+    tdd_red = endpoint_data.get("phases", {}).get("tdd_red", {})
+    if tdd_red.get("test_file"):
+        files.append(tdd_red.get("test_file"))
+
+    tdd_green = endpoint_data.get("phases", {}).get("tdd_green", {})
+    if tdd_green.get("implementation_file"):
+        files.append(tdd_green.get("implementation_file"))
+
+    return list(set(files))  # Deduplicate
+
+
+def generate_summary(endpoint, endpoint_data, state):
+    """Generate a markdown summary of the session."""
+    completed = get_completed_phases(endpoint_data)
+    files = get_files_created(endpoint_data)
+    decisions = endpoint_data.get("phases", {}).get("interview", {}).get("decisions", {})
+
+    lines = [
+        f"# Session Summary: {endpoint}",
+        "",
+        f"*Generated: {datetime.now().isoformat()}*",
+        "",
+        "## Overview",
+        "",
+        f"- **Endpoint:** {endpoint}",
+        f"- **Library:** {endpoint_data.get('library', 'N/A')}",
+        f"- **Started:** {endpoint_data.get('started_at', 'N/A')}",
+        f"- **Completed Phases:** {len(completed)}/13",
+        f"- **Status:** {endpoint_data.get('status', 'unknown')}",
+        "",
+        "## Phases Completed",
+        ""
+    ]
+
+    for i, phase in enumerate(completed, 1):
+        lines.append(f"{i}. {phase.replace('_', ' ').title()}")
+
+    lines.extend([
+        "",
+        "## Files Created",
+        ""
+    ])
+
+    for f in files:
+        lines.append(f"- `{f}`")
+
+    if decisions:
+        lines.extend([
+            "",
+            "## Interview Decisions",
+            ""
+        ])
+        for key, value in decisions.items():
+            response = value.get("response", value.get("value", "N/A"))
+            lines.append(f"- **{key}:** {response}")
+
+    lines.extend([
+        "",
+        "## Research Sources",
+        ""
+    ])
+
+    # Check for research cache
+    research_path = RESEARCH_DIR / endpoint / "sources.json"
+    if research_path.exists():
+        try:
+            sources = json.loads(research_path.read_text())
+            for src in sources.get("sources", [])[:10]:  # Limit to 10
+                url = src.get("url", src.get("query", ""))
+                if url:
+                    lines.append(f"- {url}")
+        except (json.JSONDecodeError, IOError):
+            lines.append("- (sources.json not readable)")
+    else:
+        lines.append("- (no sources.json found)")
+
+    lines.extend([
+        "",
+        "---",
+        "",
+        f"*Session saved to: .claude/api-sessions/{endpoint}_{{timestamp}}/*"
+    ])
+
+    return "\n".join(lines)
+
+
+def save_session(endpoint, endpoint_data, state):
+    """Save session to .claude/api-sessions/."""
+    # Create timestamp
+    timestamp = datetime.now().strftime("%Y-%m-%d_%H-%M-%S")
+    session_dir = SESSIONS_DIR / f"{endpoint}_{timestamp}"
+    session_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1. Save state snapshot
+    state_snapshot = {
+        "saved_at": datetime.now().isoformat(),
+        "endpoint": endpoint,
+        "endpoint_data": endpoint_data,
+        "turn_count": state.get("turn_count", 0),
+        "research_queries": state.get("research_queries", [])
+    }
+    (session_dir / "state-snapshot.json").write_text(json.dumps(state_snapshot, indent=2))
+
+    # 2. Save files list
+    files = get_files_created(endpoint_data)
+    (session_dir / "files-created.txt").write_text("\n".join(files))
+
+    # 3. Generate and save summary
+    summary = generate_summary(endpoint, endpoint_data, state)
+    (session_dir / "summary.md").write_text(summary)
+
+    # 4. Copy research cache if exists
+    research_src = RESEARCH_DIR / endpoint
+    if research_src.exists():
+        research_dst = session_dir / "research-cache"
+        research_dst.mkdir(exist_ok=True)
+        for f in research_src.iterdir():
+            if f.is_file():
+                shutil.copy2(f, research_dst / f.name)
+
+    # 5. Update sessions index
+    update_sessions_index(endpoint, timestamp, endpoint_data)
+
+    return session_dir
+
+
+def update_sessions_index(endpoint, timestamp, endpoint_data):
+    """Update the sessions index file."""
+    index_file = SESSIONS_DIR / "index.json"
+
+    if index_file.exists():
+        try:
+            index = json.loads(index_file.read_text())
+        except json.JSONDecodeError:
+            index = {"version": "3.6.7", "sessions": []}
+    else:
+        index = {"version": "3.6.7", "sessions": []}
+
+    # Add this session
+    completed = get_completed_phases(endpoint_data)
+    index["sessions"].append({
+        "endpoint": endpoint,
+        "timestamp": timestamp,
+        "folder": f"{endpoint}_{timestamp}",
+        "status": endpoint_data.get("status", "unknown"),
+        "phases_completed": len(completed),
+        "created_at": datetime.now().isoformat()
+    })
+
+    index_file.write_text(json.dumps(index, indent=2))
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get active endpoint
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Only save if there's meaningful progress
+    completed = get_completed_phases(endpoint_data)
+    if len(completed) < 2:
+        # Not enough progress to save
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "sessionSaved": False,
+                "reason": "Not enough progress to save (need at least 2 completed phases)"
+            }
+        }))
+        sys.exit(0)
+
+    # Save the session
+    try:
+        session_dir = save_session(endpoint, endpoint_data, state)
+
+        output = {
+            "hookSpecificOutput": {
+                "sessionSaved": True,
+                "endpoint": endpoint,
+                "sessionDir": str(session_dir),
+                "phasesCompleted": len(completed)
+            }
+        }
+
+        print(json.dumps(output))
+        sys.exit(0)
+
+    except Exception as e:
+        output = {
+            "hookSpecificOutput": {
+                "sessionSaved": False,
+                "error": str(e)
+            }
+        }
+        print(json.dumps(output))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session-startup.py

@@ -13,6 +13,11 @@ helping to re-ground Claude on:
 
 Returns:
   - JSON with additionalContext to inject into Claude's context
+
+Updated in v3.6.7:
+  - Support multi-API state structure (endpoints object)
+  - Read research index from .claude/research/index.json file
+  - Calculate freshness from timestamps
 """
 import json
 import sys
@@ -25,6 +30,75 @@ STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
 
 
+def get_workflow_type(state):
+    """Detect the workflow type from state."""
+    workflow = state.get("workflow", "")
+    if workflow:
+        return workflow
+
+    # Infer from state structure
+    if state.get("combine_config"):
+        return "combine-api"
+    if state.get("ui_config"):
+        mode = state.get("ui_config", {}).get("mode", "")
+        return f"ui-create-{mode}" if mode else "ui-create-component"
+
+    return "api-create"
+
+
+def get_active_endpoint(state):
+    """Get active endpoint - supports both old and new state formats."""
+    # New format (v3.6.7+): endpoints object with active_endpoint pointer
+    if "endpoints" in state and "active_endpoint" in state:
+        active = state.get("active_endpoint")
+        if active and active in state["endpoints"]:
+            return active, state["endpoints"][active]
+        return None, None
+
+    # Support for elements (UI workflow)
+    if "elements" in state and "active_element" in state:
+        active = state.get("active_element")
+        if active and active in state["elements"]:
+            return active, state["elements"][active]
+        return None, None
+
+    # Old format: single endpoint field
+    endpoint = state.get("endpoint")
+    if endpoint:
+        # Return endpoint name and the entire state as endpoint data
+        return endpoint, state
+
+    # Try active_element without elements dict
+    active = state.get("active_element")
+    if active:
+        return active, state
+
+    return None, None
+
+
+def load_research_index():
+    """Load research index from .claude/research/index.json file."""
+    if not RESEARCH_INDEX.exists():
+        return {}
+    try:
+        index = json.loads(RESEARCH_INDEX.read_text())
+        return index.get("apis", {})
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def calculate_days_old(timestamp_str):
+    """Calculate how many days old a timestamp is."""
+    if not timestamp_str:
+        return 0
+    try:
+        last_updated = datetime.fromisoformat(timestamp_str.replace('Z', '+00:00'))
+        now = datetime.now(last_updated.tzinfo) if last_updated.tzinfo else datetime.now()
+        return (now - last_updated).days
+    except (ValueError, TypeError):
+        return 0
+
+
 def main():
     # Read hook input from stdin
     try:
@@ -46,21 +120,74 @@ def main():
         print(json.dumps({"continue": True}))
         sys.exit(0)
 
-    # Check if there's an active workflow
-    endpoint = state.get("endpoint")
-    if not endpoint:
+    # Get active endpoint (supports both old and new formats)
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
         # No active endpoint - just continue
         print(json.dumps({"continue": True}))
         sys.exit(0)
 
+    # Detect workflow type
+    workflow_type = get_workflow_type(state)
+
     # Build context summary
     context_parts = []
-    context_parts.append("## API Development Session Context")
+
+    # Header based on workflow type
+    if workflow_type == "combine-api":
+        context_parts.append("## Combined API Development Session Context")
+    elif workflow_type.startswith("ui-create"):
+        mode = "Page" if "page" in workflow_type else "Component"
+        context_parts.append(f"## UI {mode} Development Session Context")
+    else:
+        context_parts.append("## API Development Session Context")
+
     context_parts.append("")
-    context_parts.append(f"**Active Endpoint:** {endpoint}")
+    context_parts.append(f"**Workflow:** {workflow_type}")
+    context_parts.append(f"**Active Element:** {endpoint}")
+
+    # Add combine-specific context
+    if workflow_type == "combine-api":
+        combine_config = state.get("combine_config", {})
+        source_elements = combine_config.get("source_elements", [])
+        flow_type = combine_config.get("flow_type", "sequential")
+        error_strategy = combine_config.get("error_strategy", "fail-fast")
+
+        if source_elements:
+            source_names = []
+            for elem in source_elements:
+                if isinstance(elem, dict):
+                    source_names.append(elem.get("name", "unknown"))
+                else:
+                    source_names.append(str(elem))
+
+            context_parts.append("")
+            context_parts.append("**Combining APIs:**")
+            for name in source_names:
+                context_parts.append(f"  - {name}")
+            context_parts.append(f"  Flow: {flow_type}")
+            context_parts.append(f"  Error Strategy: {error_strategy}")
+
+    # Add UI-specific context
+    elif workflow_type.startswith("ui-create"):
+        ui_config = state.get("ui_config", {})
+        if not ui_config and endpoint_data:
+            ui_config = endpoint_data.get("ui_config", {})
+
+        if ui_config:
+            context_parts.append("")
+            context_parts.append("**UI Configuration:**")
+            if ui_config.get("use_brand_guide"):
+                context_parts.append("  - Brand guide: Applied")
+            if ui_config.get("component_type"):
+                context_parts.append(f"  - Type: {ui_config['component_type']}")
+            if ui_config.get("accessibility_level"):
+                context_parts.append(f"  - A11y: {ui_config['accessibility_level']}")
+            if ui_config.get("data_sources"):
+                context_parts.append(f"  - Data sources: {len(ui_config['data_sources'])}")
 
-    # Get phase status
-    phases = state.get("phases", {})
+    # Get phase status (from endpoint_data for multi-API, or state for legacy)
+    phases = endpoint_data.get("phases", {})
     completed = []
     in_progress = []
     not_started = []
@@ -103,17 +230,26 @@ def main():
             if response:
                 context_parts.append(f"  - {key}: {str(response)[:100]}")
 
-    # Research cache info
-    research_index = state.get("research_index", {})
+    # Research cache info - READ FROM index.json FILE (v3.6.7 fix)
+    research_index = load_research_index()
     if endpoint in research_index:
         entry = research_index[endpoint]
-        days_old = entry.get("days_old", 0)
+        last_updated = entry.get("last_updated", "")
+        days_old = calculate_days_old(last_updated)
         context_parts.append("")
         context_parts.append("**Research Cache:**")
         context_parts.append(f"  - Location: .claude/research/{endpoint}/CURRENT.md")
-        context_parts.append(f"  - Last Updated: {entry.get('last_updated', 'Unknown')}")
+        context_parts.append(f"  - Last Updated: {last_updated or 'Unknown'}")
         if days_old > 7:
-            context_parts.append(f"  - WARNING: Research is {days_old} days old. Consider re-researching.")
+            context_parts.append(f"  - ⚠️ WARNING: Research is {days_old} days old. Consider re-researching.")
+    else:
+        # Check if research directory exists even without index entry
+        research_dir = Path(__file__).parent.parent / "research" / endpoint
+        if research_dir.exists():
+            context_parts.append("")
+            context_parts.append("**Research Cache:**")
+            context_parts.append(f"  - Location: .claude/research/{endpoint}/")
+            context_parts.append(f"  - ⚠️ Not indexed - run /api-research to update")
 
     # Turn count for re-grounding awareness
     turn_count = state.get("turn_count", 0)
@@ -128,10 +264,19 @@ def main():
     context_parts.append("  - Research: .claude/research/")
     context_parts.append("  - Manifest: src/app/api-test/api-tests-manifest.json (if exists)")
 
-    # Workflow reminder
+    # Workflow reminder based on type
     context_parts.append("")
-    context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
-    context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
+    if workflow_type == "combine-api":
+        context_parts.append("**Workflow Reminder:** This is a combined API workflow.")
+        context_parts.append("Ensure all source APIs exist in registry before orchestration.")
+        context_parts.append("Test both individual APIs and the combined flow.")
+    elif workflow_type.startswith("ui-create"):
+        context_parts.append("**Workflow Reminder:** This is a UI development workflow.")
+        context_parts.append("Check registry for reusable components before creating new ones.")
+        context_parts.append("Ensure brand guide compliance and accessibility requirements.")
+    else:
+        context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
+        context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
 
     # Build the output
     additional_context = "\n".join(context_parts)