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

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,47 @@ STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
 
 
+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 name and the entire state as endpoint data
+        return endpoint, 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,9 +92,9 @@ 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)
@@ -59,8 +105,8 @@ def main():
     context_parts.append("")
     context_parts.append(f"**Active Endpoint:** {endpoint}")
 
-    # 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 +149,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)

package/hooks/track-scope-coverage.py

@@ -0,0 +1,220 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for AskUserQuestion
+Purpose: Track implemented vs deferred features for scope coverage
+
+This hook tracks which features discovered during research are:
+  - Implemented (user chose to include)
+  - Deferred (user chose to skip for later)
+  - Discovered (found in docs but not yet decided)
+
+Added in v3.6.7 for feature scope tracking.
+
+Returns:
+  - JSON with scope coverage update info
+"""
+import json
+import sys
+from datetime import datetime
+from pathlib import Path
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def get_active_endpoint(state):
+    """Get active endpoint - supports both old and new state formats."""
+    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
+
+    endpoint = state.get("endpoint")
+    if endpoint:
+        return endpoint, state
+
+    return None, None
+
+
+def extract_feature_from_question(question, options):
+    """Try to extract a feature name from the question."""
+    # Look for common patterns
+    patterns = [
+        "implement",
+        "include",
+        "support",
+        "enable",
+        "add"
+    ]
+
+    question_lower = question.lower()
+    for pattern in patterns:
+        if pattern in question_lower:
+            # Extract the words after the pattern
+            idx = question_lower.find(pattern)
+            after = question_lower[idx:].split("?")[0]
+            # Clean up
+            words = after.split()[1:4]  # Get 1-3 words after pattern
+            if words:
+                return " ".join(words).strip(",.?")
+
+    return None
+
+
+def is_feature_decision(question, answer, options):
+    """Determine if this was a feature implementation decision."""
+    question_lower = question.lower()
+
+    # Keywords suggesting feature decision
+    feature_keywords = [
+        "implement", "include", "support", "enable", "add",
+        "feature", "functionality", "capability"
+    ]
+
+    has_keyword = any(k in question_lower for k in feature_keywords)
+
+    # Check if answer indicates yes/no/defer decision
+    answer_lower = str(answer).lower() if answer else ""
+    is_decision = any(word in answer_lower for word in [
+        "yes", "no", "skip", "defer", "later", "include", "exclude",
+        "implement", "confirm", "reject"
+    ])
+
+    return has_keyword and is_decision
+
+
+def categorize_decision(answer):
+    """Categorize the decision as implement/defer/skip."""
+    answer_lower = str(answer).lower() if answer else ""
+
+    if any(word in answer_lower for word in ["yes", "include", "implement", "confirm"]):
+        return "implement"
+    elif any(word in answer_lower for word in ["defer", "later", "phase 2", "future"]):
+        return "defer"
+    elif any(word in answer_lower for word in ["no", "skip", "exclude", "reject"]):
+        return "skip"
+
+    return "unknown"
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+    tool_result = input_data.get("tool_result", {})
+
+    if tool_name != "AskUserQuestion":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    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)
+
+    endpoint, endpoint_data = get_active_endpoint(state)
+    if not endpoint or not endpoint_data:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Get question and answer
+    question = tool_input.get("question", "")
+    options = tool_input.get("options", [])
+
+    # Get user's answer from result
+    answer = None
+    if isinstance(tool_result, dict):
+        answer = tool_result.get("answer", tool_result.get("value", ""))
+    elif isinstance(tool_result, str):
+        answer = tool_result
+
+    # Check if this is a feature decision
+    if not is_feature_decision(question, answer, options):
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Extract feature name
+    feature = extract_feature_from_question(question, options)
+    if not feature:
+        feature = f"feature_{datetime.now().strftime('%H%M%S')}"
+
+    # Categorize decision
+    category = categorize_decision(answer)
+
+    # Ensure scope object exists
+    if "endpoints" in state:
+        if "scope" not in state["endpoints"][endpoint]:
+            state["endpoints"][endpoint]["scope"] = {
+                "discovered_features": [],
+                "implemented_features": [],
+                "deferred_features": [],
+                "coverage_percent": 0
+            }
+        scope = state["endpoints"][endpoint]["scope"]
+    else:
+        if "scope" not in state:
+            state["scope"] = {
+                "discovered_features": [],
+                "implemented_features": [],
+                "deferred_features": [],
+                "coverage_percent": 0
+            }
+        scope = state["scope"]
+
+    # Add to discovered if not already there
+    feature_entry = {
+        "name": feature,
+        "discovered_at": datetime.now().isoformat(),
+        "question": question[:100],
+        "decision": category
+    }
+
+    if feature not in [f.get("name") if isinstance(f, dict) else f for f in scope["discovered_features"]]:
+        scope["discovered_features"].append(feature_entry)
+
+    # Add to appropriate category
+    if category == "implement":
+        if feature not in scope["implemented_features"]:
+            scope["implemented_features"].append(feature)
+    elif category == "defer":
+        defer_entry = {
+            "name": feature,
+            "reason": f"User chose to defer: {str(answer)[:50]}",
+            "deferred_at": datetime.now().isoformat()
+        }
+        if feature not in [f.get("name") if isinstance(f, dict) else f for f in scope["deferred_features"]]:
+            scope["deferred_features"].append(defer_entry)
+
+    # Calculate coverage
+    total = len(scope["discovered_features"])
+    implemented = len(scope["implemented_features"])
+    if total > 0:
+        scope["coverage_percent"] = round((implemented / total) * 100, 1)
+
+    # Save state
+    STATE_FILE.write_text(json.dumps(state, indent=2))
+
+    output = {
+        "hookSpecificOutput": {
+            "featureTracked": feature,
+            "decision": category,
+            "coveragePercent": scope["coverage_percent"]
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()