@hustle-together/api-dev-tools 3.6.5 → 3.10.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()

package/hooks/track-tool-use.py

@@ -10,7 +10,11 @@ It logs each research action to api-dev-state.json for:
   - Providing visibility to the user
   - Tracking turn counts for periodic re-grounding
 
-Version: 3.0.0
+Version: 3.6.7
+
+Updated in v3.6.7:
+  - Support multi-API state structure
+  - Populate .claude/research/index.json for freshness tracking
 
 Returns:
   - {"continue": true} - Always continues (logging only, no blocking)
@@ -22,11 +26,82 @@ from pathlib import Path
 
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+RESEARCH_DIR = Path(__file__).parent.parent / "research"
+RESEARCH_INDEX = RESEARCH_DIR / "index.json"
 
 # Re-grounding interval (also used by periodic-reground.py)
 REGROUND_INTERVAL = 7
 
 
+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 update_research_index(endpoint, source_entry):
+    """Update the research index.json with new research activity."""
+    RESEARCH_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Load existing index
+    if RESEARCH_INDEX.exists():
+        try:
+            index = json.loads(RESEARCH_INDEX.read_text())
+        except json.JSONDecodeError:
+            index = {"version": "3.6.7", "apis": {}}
+    else:
+        index = {"version": "3.6.7", "apis": {}}
+
+    if "apis" not in index:
+        index["apis"] = {}
+
+    # Update endpoint entry
+    now = datetime.now().isoformat()
+    if endpoint not in index["apis"]:
+        index["apis"][endpoint] = {
+            "last_updated": now,
+            "freshness_days": 0,
+            "source_count": 0,
+            "sources": []
+        }
+
+    entry = index["apis"][endpoint]
+    entry["last_updated"] = now
+    entry["freshness_days"] = 0
+    entry["source_count"] = entry.get("source_count", 0) + 1
+
+    # Add source summary (keep last 10)
+    sources = entry.get("sources", [])
+    source_summary = {
+        "type": source_entry.get("type", "unknown"),
+        "timestamp": now
+    }
+    if source_entry.get("query"):
+        source_summary["query"] = source_entry.get("query", "")[:100]
+    if source_entry.get("url"):
+        source_summary["url"] = source_entry.get("url", "")[:200]
+    if source_entry.get("library"):
+        source_summary["library"] = source_entry.get("library", "")
+
+    sources.append(source_summary)
+    entry["sources"] = sources[-10:]  # Keep last 10
+
+    # Save index
+    RESEARCH_INDEX.write_text(json.dumps(index, indent=2))
+    return True
+
+
 def main():
     # Read hook input from stdin
     try:
@@ -261,6 +336,11 @@ def main():
     # Add to sources list
     sources.append(source_entry)
 
+    # v3.6.7: Update research index.json for freshness tracking
+    endpoint, _ = get_active_endpoint(state)
+    if endpoint:
+        update_research_index(endpoint, source_entry)
+
     # Also add to research_queries for prompt verification
     research_queries = state.setdefault("research_queries", [])
     query_entry = {

package/hooks/update-api-showcase.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse for Write/Edit
+Purpose: Auto-create API Showcase page when first API is created
+
+This hook monitors for new API registrations. When the first API is added
+to registry.json, it creates the API Showcase page at src/app/api-showcase/
+if it doesn't exist.
+
+Version: 3.9.0
+
+Returns:
+  - {"continue": true} - Always continues
+  - May include "notify" about showcase creation
+"""
+import json
+import sys
+from pathlib import Path
+import shutil
+
+# State and registry files in .claude/ directory
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+REGISTRY_FILE = Path(__file__).parent.parent / "registry.json"
+
+
+def copy_showcase_templates(cwd):
+    """Copy API showcase templates to src/app/api-showcase/."""
+    # Source templates (installed by CLI)
+    templates_dir = Path(__file__).parent.parent / "templates" / "api-showcase"
+
+    # Destination
+    showcase_dir = cwd / "src" / "app" / "api-showcase"
+
+    # Create directory if needed
+    showcase_dir.mkdir(parents=True, exist_ok=True)
+
+    # Copy template files
+    templates_to_copy = [
+        ("page.tsx", "page.tsx"),
+        ("APIShowcase.tsx", "_components/APIShowcase.tsx"),
+        ("APICard.tsx", "_components/APICard.tsx"),
+        ("APIModal.tsx", "_components/APIModal.tsx"),
+        ("APITester.tsx", "_components/APITester.tsx"),
+    ]
+
+    created_files = []
+    for src_name, dest_name in templates_to_copy:
+        src_path = templates_dir / src_name
+        dest_path = showcase_dir / dest_name
+
+        # Create subdirectories if needed
+        dest_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if src_path.exists() and not dest_path.exists():
+            shutil.copy2(src_path, dest_path)
+            created_files.append(str(dest_path.relative_to(cwd)))
+
+    return created_files
+
+
+def main():
+    # Read hook input from stdin
+    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", "")
+
+    # Only process Write/Edit operations
+    if tool_name not in ["Write", "Edit"]:
+        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)
+
+    # Load state
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    workflow = state.get("workflow", "")
+
+    # Only apply for API workflows
+    if workflow not in ["api-create", "combine-api"]:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if completion phase is complete
+    active_endpoint = state.get("active_endpoint", "")
+    endpoints = state.get("endpoints", {})
+
+    if active_endpoint and active_endpoint in endpoints:
+        phases = endpoints[active_endpoint].get("phases", {})
+    else:
+        phases = state.get("phases", {})
+
+    completion = phases.get("completion", {})
+    if completion.get("status") != "complete":
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if showcase already exists
+    cwd = Path.cwd()
+    showcase_page = cwd / "src" / "app" / "api-showcase" / "page.tsx"
+
+    if showcase_page.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Check if we have APIs in registry
+    if not REGISTRY_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        registry = json.loads(REGISTRY_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    apis = registry.get("apis", {})
+    combined = registry.get("combined", {})
+
+    # Create showcase if we have at least one API
+    if apis or combined:
+        created_files = copy_showcase_templates(cwd)
+
+        if created_files:
+            print(json.dumps({
+                "continue": True,
+                "notify": f"Created API Showcase at /api-showcase ({len(created_files)} files)"
+            }))
+        else:
+            print(json.dumps({"continue": True}))
+    else:
+        print(json.dumps({"continue": True}))
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()