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

package/hooks/generate-manifest-entry.py

@@ -787,8 +787,169 @@ def generate_test_cases(schema: dict) -> list:
     return test_cases
 
 
+def generate_orchestration_examples(endpoint: str, combine_config: dict, method: str) -> list:
+    """Generate orchestration examples for combined API endpoints.
+
+    Shows how multiple APIs are called in sequence/parallel and how data flows.
+    """
+    examples = []
+    source_elements = combine_config.get("source_elements", [])
+    flow_type = combine_config.get("flow_type", "sequential")
+    error_strategy = combine_config.get("error_strategy", "fail-fast")
+
+    if len(source_elements) < 2:
+        return examples
+
+    base_url = f"http://localhost:3001/api/v2/{endpoint}"
+
+    # Get source API names
+    source_names = []
+    for elem in source_elements:
+        if isinstance(elem, dict):
+            source_names.append(elem.get("name", "unknown"))
+        else:
+            source_names.append(str(elem))
+
+    # ================================================================
+    # Example 1: Sequential flow
+    # ================================================================
+    if flow_type == "sequential":
+        seq_body = {
+            "steps": [
+                {"api": source_names[0], "params": {"input": "example"}},
+                {"api": source_names[1], "params": {"useResultFrom": source_names[0]}}
+            ]
+        }
+        curl = f'curl -X {method} {base_url} \\\n'
+        curl += '  -H "Content-Type: application/json" \\\n'
+        curl += f"  -d '{json.dumps(seq_body, indent=2)}'"
+
+        examples.append({
+            "name": "Sequential orchestration",
+            "description": f"Calls {source_names[0]} first, then {source_names[1]} with results",
+            "request": seq_body,
+            "curl": curl,
+            "flow": f"{source_names[0]} → {source_names[1]}"
+        })
+
+    # ================================================================
+    # Example 2: Parallel flow
+    # ================================================================
+    elif flow_type == "parallel":
+        par_body = {
+            "parallel": True,
+            "apis": [
+                {"name": source_names[0], "params": {"query": "example1"}},
+                {"name": source_names[1], "params": {"query": "example2"}}
+            ],
+            "merge_strategy": "combine"
+        }
+        curl = f'curl -X {method} {base_url} \\\n'
+        curl += '  -H "Content-Type: application/json" \\\n'
+        curl += f"  -d '{json.dumps(par_body, indent=2)}'"
+
+        examples.append({
+            "name": "Parallel orchestration",
+            "description": f"Calls {source_names[0]} and {source_names[1]} simultaneously",
+            "request": par_body,
+            "curl": curl,
+            "flow": f"[{source_names[0]} || {source_names[1]}] → merge"
+        })
+
+    # ================================================================
+    # Example 3: Conditional flow
+    # ================================================================
+    elif flow_type == "conditional":
+        cond_body = {
+            "condition": {
+                "check": source_names[0],
+                "if_success": source_names[1],
+                "if_failure": "fallback"
+            },
+            "params": {"input": "example"}
+        }
+        curl = f'curl -X {method} {base_url} \\\n'
+        curl += '  -H "Content-Type: application/json" \\\n'
+        curl += f"  -d '{json.dumps(cond_body, indent=2)}'"
+
+        examples.append({
+            "name": "Conditional orchestration",
+            "description": f"Calls {source_names[1]} only if {source_names[0]} succeeds",
+            "request": cond_body,
+            "curl": curl,
+            "flow": f"{source_names[0]} ? {source_names[1]} : fallback"
+        })
+
+    # ================================================================
+    # Example 4: With error handling
+    # ================================================================
+    error_body = {
+        "steps": [
+            {"api": source_names[0], "params": {"input": "data"}},
+            {"api": source_names[1], "params": {"input": "data"}}
+        ],
+        "error_strategy": error_strategy,
+        "retry": {"attempts": 3, "delay_ms": 1000}
+    }
+    curl = f'curl -X {method} {base_url} \\\n'
+    curl += '  -H "Content-Type: application/json" \\\n'
+    curl += f"  -d '{json.dumps(error_body, indent=2)}'"
+
+    examples.append({
+        "name": f"With {error_strategy} error handling",
+        "description": f"Orchestration with {error_strategy} strategy and retry logic",
+        "request": error_body,
+        "curl": curl
+    })
+
+    # ================================================================
+    # Example 5: Full data flow
+    # ================================================================
+    full_body = {
+        "input": {
+            "source": "user-provided",
+            "data": {"query": "example query", "options": {"format": "json"}}
+        },
+        "flow": [
+            {
+                "step": 1,
+                "api": source_names[0],
+                "transform": "extract.content"
+            },
+            {
+                "step": 2,
+                "api": source_names[1],
+                "input_mapping": {"content": "$.step1.result"},
+                "transform": "format.output"
+            }
+        ],
+        "output": {"include": ["final_result", "metadata"]}
+    }
+    curl = f'curl -X {method} {base_url} \\\n'
+    curl += '  -H "Content-Type: application/json" \\\n'
+    curl += f"  -d '{json.dumps(full_body, indent=2)}'"
+
+    examples.append({
+        "name": "Complete orchestration with transforms",
+        "description": "Full data flow with input mapping and output transformation",
+        "request": full_body,
+        "curl": curl,
+        "flow_diagram": f"""
+Input → [{source_names[0]}] → transform → [{source_names[1]}] → Output
+           ↑                                    ↑
+      extract.content                    format.output
+"""
+    })
+
+    return examples
+
+
 def generate_manifest_entry(endpoint: str, endpoint_data: dict, state: dict) -> dict:
     """Generate a complete manifest entry for the endpoint."""
+    # Check if this is a combined workflow
+    combine_config = state.get("combine_config", {})
+    is_combined = bool(combine_config.get("source_elements"))
+
     # Find schema file
     schema_file = endpoint_data.get("phases", {}).get("schema_creation", {}).get("schema_file")
     if not schema_file:
@@ -819,6 +980,11 @@ def generate_manifest_entry(endpoint: str, endpoint_data: dict, state: dict) ->
     # Generate examples
     examples = generate_curl_examples(endpoint, method, request_schema)
 
+    # Add orchestration examples for combined endpoints
+    if is_combined:
+        orchestration_examples = generate_orchestration_examples(endpoint, combine_config, method)
+        examples.extend(orchestration_examples)
+
     # Generate test cases
     test_cases = generate_test_cases(request_schema)
 
@@ -853,12 +1019,26 @@ def generate_manifest_entry(endpoint: str, endpoint_data: dict, state: dict) ->
         "testCases": test_cases,
         "metadata": {
             "generatedAt": datetime.now().isoformat(),
-            "generatedBy": "api-dev-tools v3.6.7",
+            "generatedBy": "api-dev-tools v3.10.0",
             "schemaFile": schema_file,
             "researchFresh": True
         }
     }
 
+    # Add combined workflow metadata
+    if is_combined:
+        source_names = []
+        for elem in combine_config.get("source_elements", []):
+            if isinstance(elem, dict):
+                source_names.append(elem.get("name", "unknown"))
+            else:
+                source_names.append(str(elem))
+
+        entry["metadata"]["isCombined"] = True
+        entry["metadata"]["sourceApis"] = source_names
+        entry["metadata"]["flowType"] = combine_config.get("flow_type", "sequential")
+        entry["metadata"]["errorStrategy"] = combine_config.get("error_strategy", "fail-fast")
+
     return entry
 
 

package/hooks/session-startup.py

@@ -30,6 +30,22 @@ STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
 RESEARCH_INDEX = Path(__file__).parent.parent / "research" / "index.json"
 
 
+def get_workflow_type(state):
+    """Detect the workflow type from state."""
+    workflow = state.get("workflow", "")
+    if workflow:
+        return workflow
+
+    # Infer from state structure
+    if state.get("combine_config"):
+        return "combine-api"
+    if state.get("ui_config"):
+        mode = state.get("ui_config", {}).get("mode", "")
+        return f"ui-create-{mode}" if mode else "ui-create-component"
+
+    return "api-create"
+
+
 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
@@ -39,12 +55,24 @@ def get_active_endpoint(state):
             return active, state["endpoints"][active]
         return None, None
 
+    # Support for elements (UI workflow)
+    if "elements" in state and "active_element" in state:
+        active = state.get("active_element")
+        if active and active in state["elements"]:
+            return active, state["elements"][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
 
+    # Try active_element without elements dict
+    active = state.get("active_element")
+    if active:
+        return active, state
+
     return None, None
 
 
@@ -99,11 +127,64 @@ def main():
         print(json.dumps({"continue": True}))
         sys.exit(0)
 
+    # Detect workflow type
+    workflow_type = get_workflow_type(state)
+
     # Build context summary
     context_parts = []
-    context_parts.append("## API Development Session Context")
+
+    # Header based on workflow type
+    if workflow_type == "combine-api":
+        context_parts.append("## Combined API Development Session Context")
+    elif workflow_type.startswith("ui-create"):
+        mode = "Page" if "page" in workflow_type else "Component"
+        context_parts.append(f"## UI {mode} Development Session Context")
+    else:
+        context_parts.append("## API Development Session Context")
+
     context_parts.append("")
-    context_parts.append(f"**Active Endpoint:** {endpoint}")
+    context_parts.append(f"**Workflow:** {workflow_type}")
+    context_parts.append(f"**Active Element:** {endpoint}")
+
+    # Add combine-specific context
+    if workflow_type == "combine-api":
+        combine_config = state.get("combine_config", {})
+        source_elements = combine_config.get("source_elements", [])
+        flow_type = combine_config.get("flow_type", "sequential")
+        error_strategy = combine_config.get("error_strategy", "fail-fast")
+
+        if source_elements:
+            source_names = []
+            for elem in source_elements:
+                if isinstance(elem, dict):
+                    source_names.append(elem.get("name", "unknown"))
+                else:
+                    source_names.append(str(elem))
+
+            context_parts.append("")
+            context_parts.append("**Combining APIs:**")
+            for name in source_names:
+                context_parts.append(f"  - {name}")
+            context_parts.append(f"  Flow: {flow_type}")
+            context_parts.append(f"  Error Strategy: {error_strategy}")
+
+    # Add UI-specific context
+    elif workflow_type.startswith("ui-create"):
+        ui_config = state.get("ui_config", {})
+        if not ui_config and endpoint_data:
+            ui_config = endpoint_data.get("ui_config", {})
+
+        if ui_config:
+            context_parts.append("")
+            context_parts.append("**UI Configuration:**")
+            if ui_config.get("use_brand_guide"):
+                context_parts.append("  - Brand guide: Applied")
+            if ui_config.get("component_type"):
+                context_parts.append(f"  - Type: {ui_config['component_type']}")
+            if ui_config.get("accessibility_level"):
+                context_parts.append(f"  - A11y: {ui_config['accessibility_level']}")
+            if ui_config.get("data_sources"):
+                context_parts.append(f"  - Data sources: {len(ui_config['data_sources'])}")
 
     # Get phase status (from endpoint_data for multi-API, or state for legacy)
     phases = endpoint_data.get("phases", {})
@@ -183,10 +264,19 @@ def main():
     context_parts.append("  - Research: .claude/research/")
     context_parts.append("  - Manifest: src/app/api-test/api-tests-manifest.json (if exists)")
 
-    # Workflow reminder
+    # Workflow reminder based on type
     context_parts.append("")
-    context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
-    context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
+    if workflow_type == "combine-api":
+        context_parts.append("**Workflow Reminder:** This is a combined API workflow.")
+        context_parts.append("Ensure all source APIs exist in registry before orchestration.")
+        context_parts.append("Test both individual APIs and the combined flow.")
+    elif workflow_type.startswith("ui-create"):
+        context_parts.append("**Workflow Reminder:** This is a UI development workflow.")
+        context_parts.append("Check registry for reusable components before creating new ones.")
+        context_parts.append("Ensure brand guide compliance and accessibility requirements.")
+    else:
+        context_parts.append("**Workflow Reminder:** This project uses interview-driven API development.")
+        context_parts.append("Phases loop back if verification fails. Research before answering API questions.")
 
     # Build the output
     additional_context = "\n".join(context_parts)

package/hooks/update-ui-showcase.py

@@ -2,12 +2,15 @@
 """
 Hook: PostToolUse for Write/Edit
 Purpose: Auto-create UI Showcase page when first component/page is created
+         and auto-populate showcase data from registry.
 
 This hook monitors for new component or page registrations. When the first
 UI element is added to registry.json, it creates the UI Showcase page
 at src/app/ui-showcase/ if it doesn't exist.
 
-Version: 3.9.0
+Also generates src/app/ui-showcase/data.json from registry for auto-population.
+
+Version: 3.10.0
 
 Returns:
   - {"continue": true} - Always continues
@@ -17,12 +20,66 @@ import json
 import sys
 from pathlib import Path
 import shutil
+from datetime import datetime
 
 # 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 generate_showcase_data(registry, cwd):
+    """Generate showcase data file from registry for auto-population.
+
+    Creates src/app/ui-showcase/data.json with component/page listings.
+    """
+    components = registry.get("components", {})
+    pages = registry.get("pages", {})
+
+    showcase_data = {
+        "version": "3.10.0",
+        "generated_at": datetime.now().isoformat(),
+        "components": [],
+        "pages": []
+    }
+
+    # Process components
+    for name, comp in components.items():
+        showcase_data["components"].append({
+            "id": name,
+            "name": comp.get("name", name),
+            "description": comp.get("description", ""),
+            "type": comp.get("type", "atom"),
+            "path": comp.get("path", f"src/components/{name}/{name}.tsx"),
+            "storybook_url": comp.get("storybook_url", f"/?path=/story/{name.lower()}--default"),
+            "variants": comp.get("variants", []),
+            "props": list(comp.get("props", {}).keys()) if isinstance(comp.get("props"), dict) else [],
+            "created_at": comp.get("created_at", ""),
+            "status": comp.get("status", "ready")
+        })
+
+    # Process pages
+    for name, page in pages.items():
+        showcase_data["pages"].append({
+            "id": name,
+            "name": page.get("name", name),
+            "description": page.get("description", ""),
+            "route": page.get("route", f"/{name}"),
+            "page_type": page.get("page_type", "landing"),
+            "path": page.get("path", f"src/app/{name}/page.tsx"),
+            "requires_auth": page.get("requires_auth", False),
+            "data_sources": page.get("data_sources", []),
+            "created_at": page.get("created_at", ""),
+            "status": page.get("status", "ready")
+        })
+
+    # Write data file
+    data_file = cwd / "src" / "app" / "ui-showcase" / "data.json"
+    data_file.parent.mkdir(parents=True, exist_ok=True)
+    data_file.write_text(json.dumps(showcase_data, indent=2))
+
+    return str(data_file.relative_to(cwd))
+
+
 def copy_showcase_templates(cwd):
     """Copy UI showcase templates to src/app/ui-showcase/."""
     # Source templates (installed by CLI)
@@ -131,13 +188,20 @@ def main():
     if components or pages:
         created_files = copy_showcase_templates(cwd)
 
+        # Always update data.json from registry
+        data_file = generate_showcase_data(registry, cwd)
+
         if created_files:
             print(json.dumps({
                 "continue": True,
-                "notify": f"Created UI Showcase at /ui-showcase ({len(created_files)} files)"
+                "notify": f"Created UI Showcase at /ui-showcase ({len(created_files)} files) + data.json"
             }))
         else:
-            print(json.dumps({"continue": True}))
+            # Just updated data.json
+            print(json.dumps({
+                "continue": True,
+                "notify": f"Updated UI Showcase data ({len(components)} components, {len(pages)} pages)"
+            }))
     else:
         print(json.dumps({"continue": True}))
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hustle-together/api-dev-tools",
-  "version": "3.9.2",
+  "version": "3.10.0",
   "description": "Interview-driven, research-first API and UI development workflow with continuous verification loops for Claude Code",
   "main": "bin/cli.js",
   "bin": {
@@ -12,7 +12,6 @@
     "hooks/",
     "scripts/",
     "templates/",
-    "demo/",
     "README.md",
     "LICENSE"
   ],

package/templates/api-dev-state.json

@@ -1,8 +1,46 @@
 {
-  "version": "3.7.0",
+  "version": "3.10.0",
   "created_at": null,
+  "workflow": null,
+  "_workflow_options": ["api-create", "combine-api", "ui-create-component", "ui-create-page"],
   "active_endpoint": null,
+  "active_element": null,
   "endpoints": {},
+  "elements": {},
+  "combine_config": {
+    "_comment": "Configuration for combine-api workflow",
+    "mode": null,
+    "_mode_options": ["api", "ui"],
+    "source_elements": [],
+    "_source_elements_example": [
+      { "type": "api", "name": "openai", "registry_ref": "apis.openai" },
+      { "type": "api", "name": "wordpress", "registry_ref": "apis.wordpress" }
+    ],
+    "flow_type": null,
+    "_flow_type_options": ["sequential", "parallel", "conditional"],
+    "error_strategy": null,
+    "_error_strategy_options": ["fail-fast", "partial", "retry"],
+    "orchestration": {
+      "input_mapping": {},
+      "output_mapping": {},
+      "transforms": []
+    }
+  },
+  "ui_config": {
+    "_comment": "Configuration for ui-create-* workflows",
+    "mode": null,
+    "_mode_options": ["component", "page"],
+    "use_brand_guide": false,
+    "component_type": null,
+    "_component_type_options": ["atom", "molecule", "organism", "template"],
+    "page_type": null,
+    "_page_type_options": ["landing", "dashboard", "form", "list", "detail", "auth"],
+    "accessibility_level": null,
+    "_accessibility_level_options": ["AA", "AAA"],
+    "data_sources": [],
+    "variants": [],
+    "sizes": []
+  },
   "turn_count": 0,
   "last_turn_timestamp": null,
   "research_queries": [],

package/templates/settings.json

@@ -119,6 +119,18 @@
           {
             "type": "command",
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-playwright-setup.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-api-routes.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-page-components.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-page-data-schema.py"
           }
         ]
       },
@@ -181,6 +193,10 @@
           {
             "type": "command",
             "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/update-ui-showcase.py"
+          },
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/enforce-a11y-audit.py"
           }
         ]
       }

package/templates/shared/HeroHeader.tsx

@@ -237,7 +237,7 @@ export function HeroHeader({ title, description, badge }: HeroHeaderProps) {
       {/* Animated Grid Canvas */}
       <canvas
         ref={canvasRef}
-        className="pointer-events-none absolute inset-0 z-0 opacity-60 blur-[1.5px]"
+        className="pointer-events-none absolute inset-0 z-0 opacity-80 dark:opacity-60 dark:blur-[0.5px]"
       />
 
       {/* Content - Uses same container as main content for alignment */}