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

package/hooks/enforce-brand-guide.py

@@ -1,20 +1,21 @@
 #!/usr/bin/env python3
 """
 Hook: PreToolUse for Write/Edit
-Purpose: Inject brand guide content during UI implementation
+Purpose: Inject brand guide content and validate color compliance during UI implementation
 
 This hook runs before writing component/page files. When use_brand_guide=true
 in the state, it logs the brand guide summary to remind Claude to apply
-consistent branding.
+consistent branding and validates that only approved colors are used.
 
-Version: 3.9.0
+Version: 3.10.0
 
 Returns:
-  - {"continue": true} - Always continues
-  - May include "notify" with brand guide summary
+  - {"continue": true} - Always continues (notifies on violations)
+  - May include "notify" with brand guide summary or color violations
 """
 import json
 import sys
+import re
 from pathlib import Path
 
 # State file is in .claude/ directory (sibling to hooks/)
@@ -22,6 +23,102 @@ STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 BRAND_GUIDE_FILE = Path(__file__).parent.parent / "BRAND_GUIDE.md"
 
 
+def extract_brand_colors(content):
+    """Extract all brand colors from brand guide markdown.
+
+    Returns a set of allowed colors (hex values, CSS variables, Tailwind classes).
+    """
+    allowed_colors = set()
+
+    # Extract hex colors from brand guide
+    hex_pattern = r'#[0-9A-Fa-f]{3,8}'
+    for match in re.finditer(hex_pattern, content):
+        allowed_colors.add(match.group(0).upper())
+
+    # Extract CSS variable names
+    css_var_pattern = r'var\(--([a-zA-Z0-9-]+)\)'
+    for match in re.finditer(css_var_pattern, content):
+        allowed_colors.add(f"--{match.group(1)}")
+
+    # Extract Tailwind color classes mentioned in brand guide
+    tailwind_pattern = r'(?:bg|text|border|ring)-([a-zA-Z]+-[0-9]+|[a-zA-Z]+)'
+    for match in re.finditer(tailwind_pattern, content):
+        allowed_colors.add(match.group(0))
+
+    # Always allow these common values
+    allowed_colors.update([
+        'transparent', 'inherit', 'currentColor', 'current',
+        'white', 'black', 'bg-white', 'bg-black', 'text-white', 'text-black',
+        'bg-transparent', 'border-transparent',
+        # Common utility colors
+        'bg-background', 'text-foreground', 'border-border',
+        'bg-primary', 'text-primary', 'border-primary',
+        'bg-secondary', 'text-secondary', 'border-secondary',
+        'bg-accent', 'text-accent', 'border-accent',
+        'bg-muted', 'text-muted', 'border-muted',
+        'bg-destructive', 'text-destructive', 'border-destructive',
+    ])
+
+    return allowed_colors
+
+
+def extract_colors_from_code(code_content):
+    """Extract colors used in component code.
+
+    Returns a list of color usages found.
+    """
+    used_colors = []
+
+    # Find hex colors
+    hex_pattern = r'#[0-9A-Fa-f]{3,8}'
+    for match in re.finditer(hex_pattern, code_content):
+        used_colors.append(('hex', match.group(0).upper()))
+
+    # Find Tailwind color classes (excluding allowed dynamic patterns)
+    tailwind_pattern = r'(?:bg|text|border|ring|from|to|via)-([a-zA-Z]+-[0-9]+)'
+    for match in re.finditer(tailwind_pattern, code_content):
+        # Skip if it's a dynamic value like bg-[#xxx]
+        full_match = match.group(0)
+        if '[' not in full_match:
+            used_colors.append(('tailwind', full_match))
+
+    # Find inline style colors
+    style_pattern = r'(?:color|backgroundColor|borderColor):\s*["\']([^"\']+)["\']'
+    for match in re.finditer(style_pattern, code_content):
+        value = match.group(1)
+        if value.startswith('#'):
+            used_colors.append(('style', value.upper()))
+
+    return used_colors
+
+
+def validate_color_compliance(code_content, allowed_colors):
+    """Check if code uses only brand-approved colors.
+
+    Returns list of violations found.
+    """
+    violations = []
+    used_colors = extract_colors_from_code(code_content)
+
+    for color_type, color_value in used_colors:
+        # Check if color is allowed
+        is_allowed = False
+
+        if color_type == 'hex':
+            is_allowed = color_value in allowed_colors
+        elif color_type == 'tailwind':
+            is_allowed = color_value in allowed_colors or color_value.split('-')[0] in ['bg', 'text', 'border']
+        elif color_type == 'style':
+            is_allowed = color_value in allowed_colors
+
+        if not is_allowed:
+            # Check against all allowed colors more loosely
+            if color_value not in allowed_colors:
+                violations.append(f"{color_type}: {color_value}")
+
+    return violations
+
+
 def extract_brand_summary(content):
     """Extract key brand values from brand guide markdown."""
     summary = []
@@ -118,6 +215,19 @@ def main():
     brand_content = BRAND_GUIDE_FILE.read_text()
     summary = extract_brand_summary(brand_content)
 
+    # For Edit operations, check color compliance
+    tool_input = input_data.get("tool_input", {})
+    if tool_name == "Edit":
+        new_content = tool_input.get("new_string", "")
+        if new_content:
+            allowed_colors = extract_brand_colors(brand_content)
+            violations = validate_color_compliance(new_content, allowed_colors)
+
+            if violations:
+                notify_msg = f"⚠️ Brand color check: {len(violations)} potential non-brand colors: " + ", ".join(violations[:3])
+                print(json.dumps({"continue": True, "notify": notify_msg}))
+                sys.exit(0)
+
     if summary:
         notify_msg = "Applying brand guide: " + " | ".join(summary[:5])
         print(json.dumps({"continue": True, "notify": notify_msg}))

package/hooks/enforce-page-components.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python3
+"""
+Hook: enforce-page-components.py
+Trigger: PreToolUse (Write|Edit)
+Purpose: Check that components from registry are considered before creating new ones
+
+For ui-create-page workflow, ensures Phase 5 (PAGE ANALYSIS) is complete and
+encourages reuse of existing components from the registry.
+"""
+
+import json
+import sys
+import os
+import re
+
+def load_state():
+    """Load the api-dev-state.json file"""
+    state_paths = [
+        ".claude/api-dev-state.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/api-dev-state.json")
+    ]
+
+    for path in state_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return None
+
+def load_registry():
+    """Load the registry.json file"""
+    registry_paths = [
+        ".claude/registry.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/registry.json")
+    ]
+
+    for path in registry_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return {}
+
+def is_page_workflow(state):
+    """Check if current workflow is ui-create-page"""
+    workflow = state.get("workflow", "")
+    return workflow == "ui-create-page"
+
+def get_active_element(state):
+    """Get the active element being worked on"""
+    active = state.get("active_element", "")
+    if not active:
+        active = state.get("endpoint", "")
+    return active
+
+def is_creating_new_component(file_path):
+    """Check if the file path suggests creating a new standalone component"""
+    if not file_path:
+        return False
+
+    # Patterns that suggest a new standalone component (not page-specific)
+    standalone_patterns = [
+        r"src/components/[A-Z]",
+        r"components/ui/",
+        r"components/shared/",
+    ]
+
+    return any(re.search(pattern, file_path) for pattern in standalone_patterns)
+
+def is_page_specific_component(file_path, element_name):
+    """Check if the file is a page-specific component (allowed)"""
+    if not file_path or not element_name:
+        return False
+
+    # Page-specific components in _components folder are allowed
+    patterns = [
+        f"src/app/{element_name}/_components/",
+        f"app/{element_name}/_components/",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def check_page_analysis_phase(state, element_name):
+    """Check if page analysis phase is complete"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    phases = element.get("phases", {})
+
+    page_analysis = phases.get("page_analysis", {})
+    return page_analysis.get("status") == "complete"
+
+def get_available_components(registry):
+    """Get list of available components from registry"""
+    components = registry.get("components", {})
+    return list(components.keys())
+
+def main():
+    try:
+        # Read tool input from stdin
+        input_data = json.loads(sys.stdin.read())
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+
+        # Only check Write tool
+        if tool_name != "Write":
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        file_path = tool_input.get("file_path", "")
+
+        # Load state
+        state = load_state()
+        if not state:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Only apply to ui-create-page workflow
+        if not is_page_workflow(state):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        element_name = get_active_element(state)
+        if not element_name:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow page-specific components (in _components folder)
+        if is_page_specific_component(file_path, element_name):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Check if creating a new standalone component
+        if is_creating_new_component(file_path):
+            # Check if page analysis phase is complete
+            if not check_page_analysis_phase(state, element_name):
+                # Load registry to show available components
+                registry = load_registry()
+                available = get_available_components(registry)
+
+                component_list = "\n".join([f"  - {c}" for c in available[:10]])
+                if len(available) > 10:
+                    component_list += f"\n  ... and {len(available) - 10} more"
+
+                print(json.dumps({
+                    "decision": "block",
+                    "reason": f"""
+PAGE ANALYSIS REQUIRED (Phase 5)
+
+You are creating a new standalone component, but Page Analysis phase is not complete.
+
+Before creating new components:
+1. Check the registry for existing components
+2. Decide which existing components to reuse
+3. Update state: phases.page_analysis.status = "complete"
+
+Available Components in Registry:
+{component_list if available else "  (No components registered yet)"}
+
+If you need a NEW component, consider:
+- Using /ui-create to properly create and document it
+- Or create a page-specific component in src/app/{element_name}/_components/
+"""
+                }))
+                return
+
+            # Even if phase is complete, notify about registry
+            registry = load_registry()
+            available = get_available_components(registry)
+
+            if available:
+                print(json.dumps({
+                    "decision": "allow",
+                    "message": f"Note: {len(available)} components available in registry. Consider reusing existing components."
+                }))
+                return
+
+        # Allow everything else
+        print(json.dumps({"decision": "allow"}))
+
+    except Exception as e:
+        # On error, allow to avoid blocking workflow
+        print(json.dumps({
+            "decision": "allow",
+            "error": str(e)
+        }))
+
+if __name__ == "__main__":
+    main()

package/hooks/enforce-page-data-schema.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Hook: enforce-page-data-schema.py
+Trigger: PreToolUse (Write|Edit)
+Purpose: Validate that API response types are defined before page implementation
+
+For ui-create-page workflow, ensures Phase 6 (DATA SCHEMA) is complete before
+allowing page implementation in Phase 9.
+"""
+
+import json
+import sys
+import os
+import re
+
+def load_state():
+    """Load the api-dev-state.json file"""
+    state_paths = [
+        ".claude/api-dev-state.json",
+        os.path.join(os.environ.get("CLAUDE_PROJECT_DIR", ""), ".claude/api-dev-state.json")
+    ]
+
+    for path in state_paths:
+        if os.path.exists(path):
+            with open(path, 'r') as f:
+                return json.load(f)
+    return None
+
+def is_page_workflow(state):
+    """Check if current workflow is ui-create-page"""
+    workflow = state.get("workflow", "")
+    return workflow == "ui-create-page"
+
+def get_active_element(state):
+    """Get the active element being worked on"""
+    active = state.get("active_element", "")
+    if not active:
+        # Fall back to endpoint for older state files
+        active = state.get("endpoint", "")
+    return active
+
+def is_page_file(file_path, element_name):
+    """Check if the file being written is a page implementation file"""
+    if not file_path or not element_name:
+        return False
+
+    patterns = [
+        f"src/app/{element_name}/page.tsx",
+        f"src/app/{element_name}/layout.tsx",
+        f"src/app/{element_name}/_components/",
+        f"app/{element_name}/page.tsx",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def is_types_file(file_path, element_name):
+    """Check if the file being written is the types/schema file"""
+    if not file_path or not element_name:
+        return False
+
+    patterns = [
+        f"src/app/{element_name}/_types/",
+        f"src/app/{element_name}/types.ts",
+        f"src/lib/schemas/{element_name}",
+    ]
+
+    return any(pattern in file_path for pattern in patterns)
+
+def is_test_file(file_path):
+    """Check if file is a test file"""
+    return "__tests__" in file_path or ".test." in file_path or ".spec." in file_path
+
+def check_data_schema_phase(state, element_name):
+    """Check if data schema phase is complete"""
+    elements = state.get("elements", {})
+    element = elements.get(element_name, {})
+    phases = element.get("phases", {})
+
+    # Check data_schema phase
+    data_schema = phases.get("data_schema", {})
+    return data_schema.get("status") == "complete"
+
+def main():
+    try:
+        # Read tool input from stdin
+        input_data = json.loads(sys.stdin.read())
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+
+        # Only check Write and Edit tools
+        if tool_name not in ["Write", "Edit"]:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        file_path = tool_input.get("file_path", "")
+
+        # Load state
+        state = load_state()
+        if not state:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Only apply to ui-create-page workflow
+        if not is_page_workflow(state):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        element_name = get_active_element(state)
+        if not element_name:
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow writing types/schema files (Phase 6)
+        if is_types_file(file_path, element_name):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Allow writing test files (Phase 8)
+        if is_test_file(file_path):
+            print(json.dumps({"decision": "allow"}))
+            return
+
+        # Check if writing page implementation file
+        if is_page_file(file_path, element_name):
+            # Verify data schema phase is complete
+            if not check_data_schema_phase(state, element_name):
+                print(json.dumps({
+                    "decision": "block",
+                    "reason": f"""
+DATA SCHEMA REQUIRED (Phase 6)
+
+You are trying to implement page code, but the data schema phase is not complete.
+
+Before writing page implementation:
+1. Define TypeScript interfaces for API responses
+2. Create types in src/app/{element_name}/_types/index.ts
+3. Update state: phases.data_schema.status = "complete"
+
+Page implementation requires knowing the data structure first.
+"""
+                }))
+                return
+
+        # Allow everything else
+        print(json.dumps({"decision": "allow"}))
+
+    except Exception as e:
+        # On error, allow to avoid blocking workflow
+        print(json.dumps({
+            "decision": "allow",
+            "error": str(e)
+        }))
+
+if __name__ == "__main__":
+    main()