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

package/hooks/enforce-dry-run.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Enforce Dry-Run Mode Hook
+
+This hook blocks Write and Edit operations when --dry-run mode is active.
+It allows the workflow to run completely (research, interviews, schema generation)
+but prevents any files from being written.
+
+Hook Type: PreToolUse (matcher: Write, Edit)
+
+Use Cases:
+- Preview what a workflow will create before committing
+- Test autonomous mode without modifying files
+- Validate workflow logic without side effects
+
+v4.5.0: Initial implementation
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+# Import shared utilities
+try:
+    from hook_utils import (
+        check_dry_run_mode,
+        log_workflow_event,
+        load_state
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
+
+def get_file_path_from_env():
+    """Extract file path from tool input environment variable."""
+    tool_input = os.environ.get("CLAUDE_TOOL_INPUT", "{}")
+    try:
+        data = json.loads(tool_input)
+        return data.get("file_path", "unknown")
+    except json.JSONDecodeError:
+        return "unknown"
+
+
+def main():
+    """Main hook entry point."""
+    tool_name = os.environ.get("CLAUDE_TOOL_NAME", "")
+
+    # Only enforce for Write and Edit tools
+    if tool_name not in ["Write", "Edit"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Check if dry-run mode is active
+    dry_run_active = False
+
+    if UTILS_AVAILABLE:
+        try:
+            dry_run_active = check_dry_run_mode()
+        except Exception:
+            pass
+    else:
+        # Fallback: check state file directly
+        try:
+            project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+            state_file = Path(project_dir) / ".claude" / "api-dev-state.json"
+            if state_file.exists():
+                state = json.loads(state_file.read_text())
+                dry_run_active = state.get("dry_run_mode", False) or state.get("flags", {}).get("dry_run", False)
+        except Exception:
+            pass
+
+    if not dry_run_active:
+        # Normal mode - allow the operation
+        print(json.dumps({"continue": True}))
+        return
+
+    # Dry-run mode active - block the write
+    file_path = get_file_path_from_env()
+
+    # Log the blocked operation
+    if UTILS_AVAILABLE:
+        try:
+            log_workflow_event("dry_run_block", {
+                "tool": tool_name,
+                "file_path": file_path,
+                "action": "blocked"
+            })
+        except Exception:
+            pass
+
+    # Return blocking result with informative message
+    result = {
+        "continue": False,
+        "reason": f"""## 🔒 Dry-Run Mode Active
+
+**Tool:** {tool_name}
+**Would write to:** `{file_path}`
+
+In dry-run mode, no files are modified. The workflow continues to show
+what WOULD be created, but Write and Edit operations are blocked.
+
+### To Execute For Real:
+1. Run the same command without `--dry-run`
+2. Or disable dry-run: Update state with `dry_run_mode: false`
+
+### Preview Summary:
+This operation would {_get_operation_description(tool_name, file_path)}
+
+---
+_Dry-run preview - no files were modified_
+"""
+    }
+    print(json.dumps(result))
+
+
+def _get_operation_description(tool_name, file_path):
+    """Generate a human-readable description of the blocked operation."""
+    path = Path(file_path)
+
+    if tool_name == "Write":
+        if not path.exists() if file_path != "unknown" else True:
+            return f"create a new file at `{file_path}`"
+        return f"overwrite the file at `{file_path}`"
+
+    if tool_name == "Edit":
+        return f"modify the file at `{file_path}`"
+
+    return f"perform a {tool_name} operation on `{file_path}`"
+
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-external-research.py

@@ -16,6 +16,9 @@ The hook triggers on:
 - ANY questions about tools, services, or platforms
 - ANY request for implementation, editing, or changes
 
+v3.12.13 Fix:
+- Skip enforcement when running in source repository (developing the package)
+
 Returns:
   - Prints context to stdout (injected into conversation)
   - Exit 0 to allow the prompt to proceed
@@ -26,6 +29,28 @@ import re
 from pathlib import Path
 from datetime import datetime
 
+# Import shared utilities
+try:
+    from hook_utils import is_source_repository
+except ImportError:
+    # Fallback if import fails
+    def is_source_repository():
+        try:
+            package_json = Path.cwd() / "package.json"
+            if package_json.exists():
+                data = json.loads(package_json.read_text())
+                if data.get("name") == "@hustle-together/api-dev-tools":
+                    return True
+            if (Path.cwd() / "templates").is_dir():
+                return True
+        except Exception:
+            pass
+        return False
+
+# Skip enforcement in source repository
+if is_source_repository():
+    sys.exit(0)
+
 # State file is in .claude/ directory (sibling to hooks/)
 STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 

package/hooks/enforce-interview.py

@@ -27,6 +27,13 @@ import json
 import sys
 from pathlib import Path
 
+# Import shared utilities for logging (v4.5.0)
+try:
+    from hook_utils import log_workflow_event
+    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"
 
@@ -333,6 +340,19 @@ WHY: User must approve their decisions before they drive implementation."""
         # Build a reminder of what the user decided
         decision_summary = _build_decision_summary(decisions)
 
+        # Log the interview decision being applied (v4.5.0)
+        if UTILS_AVAILABLE:
+            try:
+                log_workflow_event("interview_decision", {
+                    "action": "applying_decisions",
+                    "file_path": file_path,
+                    "decision_count": len(decisions),
+                    "decisions": {k: v.get("value", v.get("response", ""))[:100]
+                                  for k, v in decisions.items()}
+                })
+            except Exception:
+                pass
+
         # Allow but inject context about user decisions
         print(json.dumps({
             "permissionDecision": "allow",

package/hooks/generate-adr-options.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""
+ADR Options Generator Hook (v2.0 - Deep Research)
+
+Automatically creates ADR research REQUESTS when research discovers
+multiple options for significant decisions (database, auth, caching, etc.).
+
+Hook Type: PostToolUse (matcher: WebSearch, WebFetch, mcp__context7)
+
+Flow:
+1. Research phase discovers options (e.g., "Supabase vs Firebase vs Postgres")
+2. Hook detects multiple options for significant decision category
+3. Creates RESEARCH REQUEST file (not placeholder ADR)
+4. Injects context telling AI to run /adr-deep-research
+5. Deep research skill spawns parallel agents to research each option
+6. Real ADR with substantive pros/cons is created
+7. Interview phase presents these informed options to user
+"""
+
+import json
+import os
+import re
+from datetime import datetime
+from pathlib import Path
+
+
+def load_config():
+    """Load ADR configuration from hustle-build-defaults.json"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+
+    # Check project-specific config
+    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
+
+    # Fall back to template
+    template_file = Path(project_dir) / "templates" / "hustle-build-defaults.json"
+    if template_file.exists():
+        try:
+            config = json.loads(template_file.read_text())
+            return config.get("adr", {})
+        except Exception:
+            pass
+
+    # Default config
+    return {
+        "enabled": True,
+        "significant_decisions": {
+            "database": ["supabase", "firebase", "postgres", "mysql", "mongodb", "sqlite", "planetscale", "neon"],
+            "auth": ["api key", "oauth", "jwt", "session", "cookie", "basic auth", "api-key", "bearer"],
+            "cache": ["redis", "memcached", "in-memory", "cdn", "edge", "vercel kv"],
+            "hosting": ["vercel", "netlify", "aws", "cloudflare", "railway", "render", "fly.io"],
+            "state": ["redux", "zustand", "jotai", "context", "mobx", "recoil", "valtio"],
+            "styling": ["tailwind", "css modules", "styled-components", "emotion", "vanilla-extract"],
+        },
+        "min_options_for_adr": 2
+    }
+
+
+def load_state():
+    """Load current workflow state"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    state_file = Path(project_dir) / ".claude" / "api-dev-state.json"
+
+    if state_file.exists():
+        try:
+            return json.loads(state_file.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def get_next_adr_number():
+    """Get the next ADR number from existing ADRs"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    adrs_dir = Path(project_dir) / ".claude" / "adrs"
+
+    if not adrs_dir.exists():
+        return 1
+
+    existing = list(adrs_dir.glob("*.md"))
+    if not existing:
+        return 1
+
+    numbers = []
+    for f in existing:
+        match = re.match(r"(\d+)-", f.name)
+        if match:
+            numbers.append(int(match.group(1)))
+
+    return max(numbers, default=0) + 1
+
+
+def detect_decision_points(content, config):
+    """
+    Check if research content contains multiple options for significant decisions.
+    Returns list of (category, matched_options) tuples.
+    """
+    if not config.get("enabled", True):
+        return []
+
+    significant = config.get("significant_decisions", {})
+    min_options = config.get("min_options_for_adr", 2)
+
+    content_lower = content.lower()
+    detected = []
+
+    for category, keywords in significant.items():
+        matches = [k for k in keywords if k.lower() in content_lower]
+        if len(matches) >= min_options:
+            detected.append((category, matches))
+
+    return detected
+
+
+def create_adr_research_request(category, options, context, endpoint):
+    """Create a research REQUEST file for deep ADR research.
+
+    Instead of creating a placeholder ADR with empty pros/cons,
+    we create a request file that triggers /adr-deep-research skill.
+    """
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    requests_dir = Path(project_dir) / ".claude" / "adr-requests"
+    requests_dir.mkdir(parents=True, exist_ok=True)
+
+    # Check if request already exists for this category
+    pending_file = requests_dir / f"pending-{category}.json"
+    if pending_file.exists():
+        return None  # Already pending
+
+    # Check if ADR already exists for this category
+    adrs_dir = Path(project_dir) / ".claude" / "adrs"
+    if adrs_dir.exists():
+        existing = list(adrs_dir.glob(f"*-{category}-choice.md"))
+        if existing:
+            return None  # ADR already created
+
+    # Create research request
+    request = {
+        "category": category,
+        "options": options,
+        "context": context[:1000] if context else "",
+        "endpoint": endpoint,
+        "status": "pending",
+        "created_at": datetime.now().isoformat(),
+        "adr_number": get_next_adr_number()
+    }
+
+    pending_file.write_text(json.dumps(request, indent=2))
+
+    return request
+
+
+def update_registry(adr_number, category, options, endpoint, filename):
+    """Add ADR to registry"""
+    project_dir = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    registry_file = Path(project_dir) / ".claude" / "registry.json"
+
+    if registry_file.exists():
+        try:
+            registry = json.loads(registry_file.read_text())
+        except Exception:
+            registry = {}
+    else:
+        registry = {}
+
+    if "adrs" not in registry:
+        registry["adrs"] = {}
+
+    adr_key = f"{adr_number:04d}-{category}-choice"
+    registry["adrs"][adr_key] = {
+        "number": adr_number,
+        "title": f"{category.title()} Choice",
+        "status": "proposed",
+        "date": datetime.now().strftime("%Y-%m-%d"),
+        "phase": "initial_research",
+        "endpoint": endpoint,
+        "category": category,
+        "decision": None,
+        "options_considered": options,
+        "file": f".claude/adrs/{filename}"
+    }
+
+    registry_file.parent.mkdir(parents=True, exist_ok=True)
+    registry_file.write_text(json.dumps(registry, indent=2))
+
+
+def main():
+    # Get tool output from environment
+    tool_output = os.environ.get("CLAUDE_TOOL_OUTPUT", "")
+    tool_name = os.environ.get("CLAUDE_TOOL_NAME", "")
+
+    # Only process research tools
+    if tool_name not in ["WebSearch", "WebFetch", "mcp__context7__get-library-docs"]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Load config
+    config = load_config()
+    if not config.get("enabled", True):
+        print(json.dumps({"continue": True}))
+        return
+
+    # Get current workflow context
+    state = load_state()
+    current_phase = state.get("current_phase", "")
+    endpoint = state.get("current_endpoint", state.get("workflow_id", "unknown"))
+
+    # Only generate ADRs during research phases
+    if current_phase not in ["initial_research", "deep_research", ""]:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Detect decision points in research content
+    decision_points = detect_decision_points(tool_output, config)
+
+    if not decision_points:
+        print(json.dumps({"continue": True}))
+        return
+
+    # Create research requests for each decision point
+    created_requests = []
+    for category, options in decision_points:
+        request = create_adr_research_request(
+            category=category,
+            options=options,
+            context=tool_output[:1000],
+            endpoint=endpoint
+        )
+
+        if request:
+            created_requests.append({
+                "category": category,
+                "options": options,
+                "adr_number": request["adr_number"]
+            })
+
+    if created_requests:
+        # Build list of research commands to run
+        research_commands = "\n".join([
+            f"- `/adr-deep-research {r['category']}` - Research {', '.join(r['options'])}"
+            for r in created_requests
+        ])
+
+        # Build summary of what was detected
+        detection_summary = "\n".join([
+            f"- **{r['category'].title()}**: {', '.join(r['options'])}"
+            for r in created_requests
+        ])
+
+        result = {
+            "continue": True,
+            "additionalContext": f"""## ADR Research Needed
+
+Research discovered significant decision points that require deeper investigation:
+
+{detection_summary}
+
+**Next Step:** Run deep research to get real pros/cons before the interview:
+
+{research_commands}
+
+This will:
+1. Spawn parallel research agents (one per option)
+2. Fetch official documentation for each technology
+3. Extract real pros, cons, pricing, and best-use cases
+4. Create a substantive ADR with informed recommendations
+
+The ADR will then be referenced during the interview phase.
+"""
+        }
+        print(json.dumps(result))
+    else:
+        print(json.dumps({"continue": True}))
+
+
+if __name__ == "__main__":
+    main()