@hustle-together/api-dev-tools 3.12.3 → 4.5.1

package/hooks/session-startup.py

@@ -18,6 +18,12 @@ 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
+
+Updated in v4.5.0:
+  - Ensure .claude/ directories exist on session start
+  - Create registry.json from template if not exists
+  - Log session_start event to workflow logs
+  - Detect --dry-run and --resume flags
 """
 import json
 import sys
@@ -25,6 +31,20 @@ import os
 from datetime import datetime
 from pathlib import Path
 
+# Import shared utilities
+try:
+    from hook_utils import (
+        ensure_directories,
+        ensure_registry,
+        log_workflow_event,
+        load_state as utils_load_state,
+        save_state as utils_save_state,
+        get_project_dir
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
@@ -99,6 +119,93 @@ def calculate_days_old(timestamp_str):
         return 0
 
 
+def setup_session():
+    """
+    Initialize session: create directories, registry, log session start.
+    Called at the beginning of every session (v4.5.0).
+
+    Returns:
+        dict: Setup results with directories created, registry status
+    """
+    results = {
+        "directories_created": [],
+        "registry_created": False,
+        "session_logged": False
+    }
+
+    if not UTILS_AVAILABLE:
+        return results
+
+    # Ensure directories exist
+    try:
+        results["directories_created"] = ensure_directories()
+    except Exception:
+        pass
+
+    # Ensure registry exists
+    try:
+        success, created = ensure_registry()
+        results["registry_created"] = created
+    except Exception:
+        pass
+
+    # Log session start event
+    try:
+        log_workflow_event("session_start", {
+            "directories_created": results["directories_created"],
+            "registry_created": results["registry_created"]
+        })
+        results["session_logged"] = True
+    except Exception:
+        pass
+
+    return results
+
+
+def detect_flags(input_data):
+    """
+    Detect --dry-run, --resume, and other flags from conversation context.
+    Sets flags in state for other hooks to use (v4.5.0).
+
+    Args:
+        input_data: Hook input from stdin
+
+    Returns:
+        dict: Detected flags
+    """
+    flags = {
+        "dry_run": False,
+        "resume": None,
+        "parallel": False
+    }
+
+    if not UTILS_AVAILABLE:
+        return flags
+
+    # The conversation context might contain flags
+    # Note: In SessionStart, we have limited context - flags are typically
+    # detected by skills reading the user's initial message
+    # This function prepares the state structure for flag detection
+
+    try:
+        state = utils_load_state()
+
+        # Initialize flags structure if not present
+        if "flags" not in state:
+            state["flags"] = {
+                "dry_run": False,
+                "resume": None,
+                "parallel": False
+            }
+            utils_save_state(state)
+
+        flags = state.get("flags", flags)
+    except Exception:
+        pass
+
+    return flags
+
+
 def main():
     # Read hook input from stdin
     try:
@@ -108,6 +215,12 @@ def main():
 
     cwd = input_data.get("cwd", os.getcwd())
 
+    # v4.5.0: Initialize session (directories, registry, logging)
+    setup_results = setup_session()
+
+    # v4.5.0: Detect and store flags
+    flags = detect_flags(input_data)
+
     # Check if state file exists
     if not STATE_FILE.exists():
         # No active workflow - just continue without injection

package/hooks/update-adr-decision.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+ADR Decision Updater Hook
+
+Updates Architecture Decision Records when user makes a decision during interview.
+Changes status from PROPOSED to ACCEPTED and records the decision with reasoning.
+
+Hook Type: PostToolUse (matcher: AskUserQuestion)
+
+Flow:
+1. Interview phase presents options to user (referencing ADR)
+2. User selects an option
+3. Hook detects the answer relates to a PROPOSED ADR
+4. Updates ADR with decision, reasoning, and consequences
+5. Updates registry with decision
+"""
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+def load_config():
+    """Load ADR configuration"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+
+    config_file = Path(project_dir) / ".claude" / "hustle-build-defaults.json"
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text())
+            return config.get("adr", {})
+        except Exception:
+            pass
+
+    return {"enabled": True}
+
+
+def load_registry():
+    """Load current registry"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    registry_file = Path(project_dir) / ".claude" / "registry.json"
+
+    if registry_file.exists():
+        try:
+            return json.loads(registry_file.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def save_registry(registry):
+    """Save registry"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    registry_file = Path(project_dir) / ".claude" / "registry.json"
+    registry_file.parent.mkdir(parents=True, exist_ok=True)
+    registry_file.write_text(json.dumps(registry, indent=2))
+
+
+def find_matching_adr(question_text, answer_text, registry):
+    """
+    Find a PROPOSED ADR that matches the question/answer.
+    Matches based on category keywords in question and answer options.
+    """
+    adrs = registry.get("adrs", {})
+
+    for adr_key, adr in adrs.items():
+        if adr.get("status") != "proposed":
+            continue
+
+        category = adr.get("category", "")
+        options = adr.get("options_considered", [])
+
+        # Check if question mentions the category
+        if category.lower() in question_text.lower():
+            # Check if answer matches one of the options
+            for opt in options:
+                if opt.lower() in answer_text.lower():
+                    return adr_key, adr, opt
+
+        # Check if answer directly matches an option
+        for opt in options:
+            if opt.lower() in answer_text.lower():
+                # Verify category is relevant to question
+                category_keywords = {
+                    "database": ["database", "storage", "data", "db"],
+                    "auth": ["auth", "authentication", "login", "security"],
+                    "cache": ["cache", "caching", "performance"],
+                    "hosting": ["host", "deploy", "platform"],
+                    "state": ["state", "store", "management"],
+                    "styling": ["style", "css", "design", "ui"],
+                }
+                keywords = category_keywords.get(category, [category])
+                if any(kw in question_text.lower() for kw in keywords):
+                    return adr_key, adr, opt
+
+    return None, None, None
+
+
+def update_adr_file(adr, decision):
+    """Update the ADR markdown file with the decision"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    adr_file = Path(project_dir) / adr.get("file", "")
+
+    if not adr_file.exists():
+        return False
+
+    content = adr_file.read_text()
+
+    # Update status
+    content = re.sub(
+        r"\*\*Status:\*\* PROPOSED",
+        "**Status:** ACCEPTED",
+        content
+    )
+
+    # Update decision section
+    decision_section = f"""## Decision
+
+We will use **{decision.title()}** based on user selection during interview.
+
+**Reasoning:** User prioritized this option based on project requirements.
+"""
+
+    content = re.sub(
+        r"## Decision\n\n_Pending user selection during interview phase\._",
+        decision_section,
+        content
+    )
+
+    # Update consequences section
+    consequences_section = f"""## Consequences
+
+### Positive
+- Decision has been made, enabling implementation to proceed
+- Choice aligns with user's stated requirements
+
+### Negative
+- Alternative options were not selected (may revisit if requirements change)
+
+### Implementation Notes
+- Proceed with {decision.title()} integration
+- Update environment variables as needed
+- Follow {decision.title()} best practices
+"""
+
+    content = re.sub(
+        r"## Consequences\n\n_To be documented after decision is made\._",
+        consequences_section,
+        content
+    )
+
+    # Add decision timestamp
+    content = content.replace(
+        "_This ADR was auto-generated during research.",
+        f"_Decision recorded: {datetime.now().strftime('%Y-%m-%d %H:%M')}_\n\n_This ADR was auto-generated during research."
+    )
+
+    adr_file.write_text(content)
+    return True
+
+
+def main():
+    # Get tool info
+    tool_name = os.environ.get("CLAUDE_TOOL_NAME", "")
+    tool_output = os.environ.get("CLAUDE_TOOL_OUTPUT", "")
+    tool_input = os.environ.get("CLAUDE_TOOL_INPUT", "{}")
+
+    # Only process AskUserQuestion results
+    if tool_name != "AskUserQuestion":
+        print(json.dumps({"continue": True}))
+        return
+
+    # Load config
+    config = load_config()
+    if not config.get("enabled", True):
+        print(json.dumps({"continue": True}))
+        return
+
+    # Parse question and answer
+    try:
+        input_data = json.loads(tool_input)
+        questions = input_data.get("questions", [])
+        if not questions:
+            print(json.dumps({"continue": True}))
+            return
+
+        question_text = questions[0].get("question", "")
+    except Exception:
+        question_text = ""
+
+    # The answer is in tool_output
+    answer_text = tool_output
+
+    if not question_text or not answer_text:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Load registry and find matching ADR
+    registry = load_registry()
+    adr_key, adr, decision = find_matching_adr(question_text, answer_text, registry)
+
+    if not adr_key:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Update ADR file
+    update_adr_file(adr, decision)
+
+    # Update registry
+    registry["adrs"][adr_key]["status"] = "accepted"
+    registry["adrs"][adr_key]["decision"] = decision
+    registry["adrs"][adr_key]["phase"] = "interview"
+    registry["adrs"][adr_key]["decided_at"] = datetime.now().isoformat()
+    save_registry(registry)
+
+    # Notify about ADR update
+    result = {
+        "continue": True,
+        "additionalContext": f"""## ADR Updated
+
+**ADR-{adr.get('number', 0):04d}: {adr.get('title', '')}** has been updated.
+
+- **Status:** PROPOSED → ACCEPTED
+- **Decision:** {decision.title()}
+- **File:** {adr.get('file', '')}
+
+This decision is now recorded for future reference.
+"""
+    }
+    print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/update-api-showcase.py

@@ -27,12 +27,15 @@ 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"
+    shared_templates_dir = Path(__file__).parent.parent / "templates" / "shared"
 
     # Destination
     showcase_dir = cwd / "src" / "app" / "api-showcase"
+    shared_dir = cwd / "src" / "app" / "shared"
 
-    # Create directory if needed
+    # Create directories if needed
     showcase_dir.mkdir(parents=True, exist_ok=True)
+    shared_dir.mkdir(parents=True, exist_ok=True)
 
     # Copy template files
     templates_to_copy = [
@@ -55,6 +58,15 @@ def copy_showcase_templates(cwd):
             shutil.copy2(src_path, dest_path)
             created_files.append(str(dest_path.relative_to(cwd)))
 
+    # Also copy shared components (HeroHeader, etc.)
+    if shared_templates_dir.exists():
+        for src_file in shared_templates_dir.iterdir():
+            if src_file.is_file():
+                dest_path = shared_dir / src_file.name
+                if not dest_path.exists():
+                    shutil.copy2(src_file, dest_path)
+                    created_files.append(str(dest_path.relative_to(cwd)))
+
     return created_files
 
 

package/hooks/update-testing-checklist.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Auto-update TESTING_CHECKLIST.md when tests pass.
+
+Hook Type: PostToolUse (matcher: Bash)
+
+Detects test pass patterns and updates the checklist file with:
+- Test results (PASS/FAIL)
+- Timestamp
+- Comments
+
+Works by:
+1. Detecting test-related Bash commands
+2. Parsing output for pass/fail patterns
+3. Updating the corresponding checklist rows
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+
+def get_tool_result():
+    """Get the tool result from environment"""
+    result = os.environ.get("CLAUDE_TOOL_RESULT", "")
+    return result
+
+
+def get_tool_input():
+    """Get the tool input from environment"""
+    try:
+        input_json = os.environ.get("CLAUDE_TOOL_INPUT", "{}")
+        return json.loads(input_json)
+    except Exception:
+        return {}
+
+
+def detect_test_type(command: str, output: str) -> dict:
+    """Detect what type of test was run and if it passed"""
+    result = {
+        "is_test": False,
+        "test_type": None,
+        "passed": None,
+        "hook_name": None,
+        "details": None
+    }
+
+    command_lower = command.lower()
+
+    # Hook compilation test
+    if "python3" in command_lower and ".py" in command_lower:
+        if "hooks/" in command or ".claude/hooks/" in command:
+            result["is_test"] = True
+            result["test_type"] = "hook_compile"
+            # Extract hook name
+            match = re.search(r'(?:hooks/|\.claude/hooks/)([^/\s]+\.py)', command)
+            if match:
+                result["hook_name"] = match.group(1)
+            # Check for pass/fail
+            if "Traceback" in output or "Error" in output or "SyntaxError" in output:
+                result["passed"] = False
+                result["details"] = "Syntax/import error"
+            elif "exit code" in output.lower():
+                exit_match = re.search(r'exit code[:\s]+(\d+)', output.lower())
+                if exit_match:
+                    result["passed"] = exit_match.group(1) == "0"
+            else:
+                result["passed"] = True
+                result["details"] = "Compiles"
+
+    # Hook enforcement test
+    if "python3" in command_lower and ("enforce" in command_lower or "verify" in command_lower):
+        result["is_test"] = True
+        result["test_type"] = "hook_enforcement"
+        match = re.search(r'(?:hooks/|\.claude/hooks/)([^/\s]+\.py)', command)
+        if match:
+            result["hook_name"] = match.group(1)
+
+        # Check for blocking behavior
+        if '"permissionDecision": "deny"' in output or "BLOCKED" in output:
+            result["passed"] = True
+            result["details"] = "BLOCKS correctly"
+        elif '"permissionDecision": "allow"' in output:
+            result["passed"] = True
+            result["details"] = "ALLOWS correctly"
+        elif '"continue": true' in output:
+            result["passed"] = True
+            result["details"] = "Continues"
+
+    # pnpm test
+    if "pnpm test" in command_lower or "npm test" in command_lower:
+        result["is_test"] = True
+        result["test_type"] = "unit_test"
+        if "PASS" in output or "passed" in output.lower():
+            result["passed"] = True
+        elif "FAIL" in output or "failed" in output.lower():
+            result["passed"] = False
+
+    return result
+
+
+def update_checklist(hook_name: str, status: str, comment: str):
+    """Update the TESTING_CHECKLIST.md file with test results"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    checklist_path = Path(project_dir) / "TESTING_CHECKLIST.md"
+
+    if not checklist_path.exists():
+        return False
+
+    try:
+        content = checklist_path.read_text()
+        today = datetime.now().strftime("%Y-%m-%d")
+
+        # Pattern to find hook row in table (with empty Status column)
+        # Format: | `hook_name` | Type | Phase/Trigger | | |
+        pattern = rf'(\| `{re.escape(hook_name)}` \|[^|]+\|[^|]+\|)\s*\|\s*\|'
+        replacement = rf'\1 {status} | {comment} ({today}) |'
+
+        new_content = re.sub(pattern, replacement, content)
+
+        if new_content != content:
+            checklist_path.write_text(new_content)
+            return True
+
+        # Try alternate pattern for already-filled rows (update existing)
+        pattern2 = rf'(\| `{re.escape(hook_name)}` \|[^|]+\|[^|]+\|)[^|]+\|[^|]+\|'
+        replacement2 = rf'\1 {status} | {comment} ({today}) |'
+
+        new_content = re.sub(pattern2, replacement2, content)
+        if new_content != content:
+            checklist_path.write_text(new_content)
+            return True
+
+    except Exception as e:
+        # Log error but don't fail
+        pass
+
+    return False
+
+
+def main():
+    tool_input = get_tool_input()
+    command = tool_input.get("command", "")
+    output = get_tool_result()
+
+    # Detect what test was run
+    test_info = detect_test_type(command, output)
+
+    if not test_info["is_test"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Update checklist if we have a hook name
+    if test_info["hook_name"] and test_info["passed"] is not None:
+        status = "PASS" if test_info["passed"] else "FAIL"
+        comment = test_info["details"] or ("Tested" if test_info["passed"] else "Failed")
+
+        updated = update_checklist(
+            test_info["hook_name"],
+            status,
+            comment
+        )
+
+        if updated:
+            # Log the update
+            project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+            logs_dir = Path(project_dir) / ".claude" / "workflow-logs"
+            logs_dir.mkdir(parents=True, exist_ok=True)
+
+            log_file = logs_dir / "checklist-updates.json"
+            try:
+                if log_file.exists():
+                    log = json.loads(log_file.read_text())
+                else:
+                    log = {"updates": []}
+
+                log["updates"].append({
+                    "timestamp": datetime.now().isoformat(),
+                    "hook": test_info["hook_name"],
+                    "status": status,
+                    "comment": comment
+                })
+
+                log_file.write_text(json.dumps(log, indent=2))
+            except Exception:
+                pass
+
+    print(json.dumps({"continue": True}))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/update-ui-showcase.py

@@ -84,12 +84,15 @@ def copy_showcase_templates(cwd):
     """Copy UI showcase templates to src/app/ui-showcase/."""
     # Source templates (installed by CLI)
     templates_dir = Path(__file__).parent.parent / "templates" / "ui-showcase"
+    shared_templates_dir = Path(__file__).parent.parent / "templates" / "shared"
 
     # Destination
     showcase_dir = cwd / "src" / "app" / "ui-showcase"
+    shared_dir = cwd / "src" / "app" / "shared"
 
-    # Create directory if needed
+    # Create directories if needed
     showcase_dir.mkdir(parents=True, exist_ok=True)
+    shared_dir.mkdir(parents=True, exist_ok=True)
 
     # Copy template files
     templates_to_copy = [
@@ -111,6 +114,15 @@ def copy_showcase_templates(cwd):
             shutil.copy2(src_path, dest_path)
             created_files.append(str(dest_path.relative_to(cwd)))
 
+    # Also copy shared components (HeroHeader, etc.)
+    if shared_templates_dir.exists():
+        for src_file in shared_templates_dir.iterdir():
+            if src_file.is_file():
+                dest_path = shared_dir / src_file.name
+                if not dest_path.exists():
+                    shutil.copy2(src_file, dest_path)
+                    created_files.append(str(dest_path.relative_to(cwd)))
+
     return created_files
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.12.3",
+  "version": "4.5.1",
   "description": "Interview-driven, research-first API development toolkit with 14-phase TDD workflow, enforcement hooks, and 23 Agent Skills for cross-platform AI agents",
   "main": "bin/cli.js",
   "bin": {
@@ -23,11 +23,15 @@
     "test": "node bin/cli.js --scope=project",
     "usage": "ccusage",
     "format": "prettier --write .",
-    "lint": "eslint . --fix"
+    "lint": "eslint . --fix",
+    "typedoc": "typedoc",
+    "typedoc:watch": "typedoc --watch"
   },
   "devDependencies": {
     "prettier": "^3.0.0",
-    "eslint": "^8.0.0"
+    "eslint": "^8.0.0",
+    "typedoc": "^0.27.0",
+    "typedoc-plugin-markdown": "^4.4.0"
   },
   "optionalDependencies": {
     "ccusage": "^1.0.0"