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

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-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": "3.12.16",
   "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"

package/scripts/extract-schema-docs.cjs

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+/**
+ * Extract Schema Documentation
+ *
+ * Parses Zod schema files and extracts parameter documentation
+ * for use in the API Showcase registry.
+ *
+ * Usage:
+ *   node scripts/extract-schema-docs.cjs <schema-file-path>
+ *
+ * Output: JSON with parameter documentation
+ *
+ * Example:
+ *   node scripts/extract-schema-docs.cjs src/lib/schemas/unsplash.ts
+ *
+ * Created with Hustle API Dev Tools (v3.12.10)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Parse Zod schema file and extract documentation
+ * Uses regex-based parsing since we can't import TypeScript directly
+ */
+function parseZodSchema(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+
+  const result = {
+    file: filePath,
+    actions: [],
+    schemas: {},
+    enums: {},
+    constants: {}
+  };
+
+  // Extract action enum values
+  const actionMatch = content.match(/ActionSchema\s*=\s*z\.enum\(\[([^\]]+)\]\)/);
+  if (actionMatch) {
+    result.actions = actionMatch[1]
+      .split(',')
+      .map(s => s.trim().replace(/['"]/g, ''))
+      .filter(Boolean);
+  }
+
+  // Extract all enums
+  const enumRegex = /export const (\w+Schema)\s*=\s*z\.enum\(\[([^\]]+)\]\)/g;
+  let enumMatch;
+  while ((enumMatch = enumRegex.exec(content)) !== null) {
+    const name = enumMatch[1].replace('Schema', '');
+    const values = enumMatch[2]
+      .split(',')
+      .map(s => s.trim().replace(/['"]/g, ''))
+      .filter(Boolean);
+    result.enums[name] = values;
+  }
+
+  // Extract request schemas (z.object definitions)
+  const schemaRegex = /export const (\w+RequestSchema)\s*=\s*z\s*\.?\s*object\(\{([^}]+(?:\{[^}]*\}[^}]*)*)\}\)/gs;
+  let schemaMatch;
+
+  while ((schemaMatch = schemaRegex.exec(content)) !== null) {
+    const schemaName = schemaMatch[1];
+    const schemaBody = schemaMatch[2];
+    const params = parseSchemaParams(schemaBody, result.enums);
+
+    // Get action name from schema name (e.g., SearchRequestSchema -> search)
+    const actionName = schemaName
+      .replace('RequestSchema', '')
+      .replace(/([A-Z])/g, (m, p1, offset) => offset > 0 ? '_' + p1.toLowerCase() : p1.toLowerCase())
+      .replace(/^_/, '');
+
+    result.schemas[actionName] = {
+      name: schemaName,
+      params: params
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Parse individual parameters from schema body
+ */
+function parseSchemaParams(schemaBody, enums) {
+  const params = [];
+
+  // Split by lines and process each field
+  const lines = schemaBody.split('\n');
+
+  for (const line of lines) {
+    // Match field definitions like: fieldName: z.string().min(1)...
+    const fieldMatch = line.match(/^\s*(\w+)\s*:\s*z\.(.+)/);
+    if (!fieldMatch) continue;
+
+    const [, name, definition] = fieldMatch;
+    const param = {
+      name,
+      type: 'string',
+      required: true,
+      description: '',
+      default: null,
+      enum: null
+    };
+
+    // Determine type
+    if (definition.includes('string()') || definition.includes('literal(')) {
+      param.type = 'string';
+    } else if (definition.includes('number()') || definition.includes('coerce.number()')) {
+      param.type = 'number';
+    } else if (definition.includes('boolean()') || definition.includes('coerce.boolean()')) {
+      param.type = 'boolean';
+    } else if (definition.includes('array(')) {
+      param.type = 'array';
+    }
+
+    // Check if it references an enum
+    for (const [enumName, enumValues] of Object.entries(enums)) {
+      if (definition.includes(enumName + 'Schema')) {
+        param.type = 'enum';
+        param.enum = enumValues;
+        break;
+      }
+    }
+
+    // Check if optional
+    if (definition.includes('.optional()')) {
+      param.required = false;
+    }
+
+    // Extract default value
+    const defaultMatch = definition.match(/\.default\(([^)]+)\)/);
+    if (defaultMatch) {
+      let defaultVal = defaultMatch[1].trim();
+      // Parse the default value
+      if (defaultVal === 'true') param.default = true;
+      else if (defaultVal === 'false') param.default = false;
+      else if (/^\d+$/.test(defaultVal)) param.default = parseInt(defaultVal);
+      else param.default = defaultVal.replace(/['"]/g, '');
+      param.required = false;
+    }
+
+    // Extract description from validation messages
+    const descMatch = definition.match(/['"]([^'"]+is required|[^'"]+too long|[^'"]+invalid)['"]/i);
+    if (descMatch) {
+      param.description = descMatch[1];
+    }
+
+    // Extract min/max for numbers
+    const minMatch = definition.match(/\.min\((\d+)/);
+    const maxMatch = definition.match(/\.max\((\d+)/);
+    if (minMatch) param.min = parseInt(minMatch[1]);
+    if (maxMatch) param.max = parseInt(maxMatch[1]);
+
+    params.push(param);
+  }
+
+  return params;
+}
+
+/**
+ * Generate example value for a parameter
+ */
+function generateExample(param) {
+  if (param.default !== null && param.default !== undefined) {
+    return param.default;
+  }
+
+  if (param.enum && param.enum.length > 0) {
+    return param.enum[0];
+  }
+
+  // Generate based on param name and type
+  const name = param.name.toLowerCase();
+
+  if (param.type === 'number') {
+    if (param.min !== undefined) return param.min;
+    if (name.includes('page')) return 1;
+    if (name.includes('per_page') || name.includes('count')) return 10;
+    return 10;
+  }
+
+  if (param.type === 'boolean') {
+    return true;
+  }
+
+  // String examples based on common param names
+  if (name === 'query' || name === 'q' || name === 'search') return 'nature sunset';
+  if (name.includes('id')) return 'abc123';
+  if (name.includes('url')) return 'https://example.com';
+  if (name.includes('color')) return 'blue';
+  if (name.includes('orientation')) return 'landscape';
+  if (name.includes('size')) return 'regular';
+
+  return 'example';
+}
+
+/**
+ * Generate working examples for an endpoint
+ */
+function generateExamples(action, params, apiId) {
+  const examples = {};
+  const baseUrl = `http://localhost:3000/api/v2/${apiId}`;
+
+  // Build query parts from required params
+  const buildQuery = (includeOptional = false) => {
+    const parts = [`action=${action}`];
+    for (const param of params) {
+      if (param.name === 'action') continue;
+      if (param.required || includeOptional) {
+        const val = generateExample(param);
+        if (val !== null && val !== undefined) {
+          parts.push(`${param.name}=${encodeURIComponent(String(val))}`);
+        }
+      }
+    }
+    return parts.join('&');
+  };
+
+  // Basic example with required params only
+  const basicQuery = buildQuery(false);
+  examples.basic = {
+    description: `Basic ${action} request`,
+    query: basicQuery,
+    curl: `curl -X GET '${baseUrl}?${basicQuery}'`
+  };
+
+  // Full example with all params
+  const fullQuery = buildQuery(true);
+  if (fullQuery !== basicQuery) {
+    examples.full = {
+      description: `${action} with all parameters`,
+      query: fullQuery,
+      curl: `curl -X GET '${baseUrl}?${fullQuery}'`
+    };
+  }
+
+  // If there are enums, generate examples for each enum value
+  for (const param of params) {
+    if (param.enum && param.enum.length > 1) {
+      for (const enumVal of param.enum.slice(0, 3)) { // First 3 enum values
+        const enumQuery = basicQuery.replace(
+          `${param.name}=${encodeURIComponent(String(generateExample(param)))}`,
+          `${param.name}=${encodeURIComponent(enumVal)}`
+        );
+        // Only add if different from basic
+        if (enumQuery !== basicQuery) {
+          examples[`${param.name}_${enumVal}`] = {
+            description: `${action} with ${param.name}=${enumVal}`,
+            query: enumQuery,
+            curl: `curl -X GET '${baseUrl}?${enumQuery}'`
+          };
+        }
+      }
+    }
+  }
+
+  return examples;
+}
+
+/**
+ * Format output for registry.json
+ */
+function formatForRegistry(parsed, apiId = 'api') {
+  const endpoints = {};
+
+  for (const [action, schema] of Object.entries(parsed.schemas)) {
+    const params = schema.params.map(p => ({
+      name: p.name,
+      type: p.type,
+      required: p.required,
+      description: p.description || `The ${p.name} parameter`,
+      default: p.default,
+      enum: p.enum,
+      min: p.min,
+      max: p.max,
+      example: String(generateExample(p))
+    })).filter(p => p.name !== 'action'); // Filter out the action param itself
+
+    endpoints[action] = {
+      method: 'GET', // Default, could be enhanced
+      description: `${action.charAt(0).toUpperCase() + action.slice(1).replace(/_/g, ' ')} action`,
+      params: params,
+      examples: generateExamples(action, params, apiId)
+    };
+  }
+
+  return {
+    actions: parsed.actions,
+    endpoints: endpoints
+  };
+}
+
+// Main execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0) {
+    console.error('Usage: node extract-schema-docs.cjs <schema-file-path> [api-id]');
+    console.error('  api-id: Optional API identifier for generating curl examples (e.g., "unsplash")');
+    process.exit(1);
+  }
+
+  const schemaPath = args[0];
+  const apiId = args[1] || path.basename(schemaPath, '.ts');
+
+  if (!fs.existsSync(schemaPath)) {
+    console.error(`File not found: ${schemaPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const parsed = parseZodSchema(schemaPath);
+    const formatted = formatForRegistry(parsed, apiId);
+    console.log(JSON.stringify(formatted, null, 2));
+  } catch (error) {
+    console.error('Error parsing schema:', error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { parseZodSchema, formatForRegistry, generateExample, generateExamples };

package/templates/CLAUDE-SECTION.md

@@ -1,21 +1,37 @@
-## Hustle API Development Workflow (v3.7.0)
+## Hustle API Development Workflow (v4.0.0)
 
-This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first API development.
+This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first development.
+
+### Project Context
+
+<!-- INSTALLER: Replace these with actual project values -->
+**Tech Stack:** [Framework] + [Language] + [Database]
+**UI Library:** [UI framework or component library]
+**Testing:** [Test framework] + [E2E framework]
+
+### Existing Elements
+
+<!-- AUTO-POPULATED: Updated by registry hooks -->
+**APIs:** (check `.claude/registry.json`)
+**Components:** (check `.claude/registry.json`)
+**Pages:** (check `.claude/registry.json`)
 
 ### Available Commands
 
 | Command                            | Purpose                               |
 | ---------------------------------- | ------------------------------------- |
-| `/hustle-api-create [endpoint]`    | Complete 13-phase workflow            |
-| `/hustle-api-interview [endpoint]` | Questions FROM research findings      |
-| `/hustle-api-research [library]`   | Adaptive propose-approve research     |
-| `/hustle-api-verify [endpoint]`    | Re-research and verify implementation |
-| `/hustle-api-env [endpoint]`       | Check API keys                        |
-| `/hustle-api-status [endpoint]`    | Track progress                        |
-| `/hustle-api-continue [endpoint]`  | Resume interrupted workflow           |
-| `/hustle-api-sessions`             | Browse saved session logs             |
-
-### 13-Phase Flow
+| `/hustle-build [description]`      | Orchestrated multi-workflow build     |
+| `/api-create [endpoint]`           | Complete 14-phase API workflow        |
+| `/hustle-ui-create [component]`    | Component with Storybook              |
+| `/hustle-ui-create-page [page]`    | Page with Playwright E2E             |
+| `/hustle-combine [name]`           | Combine multiple APIs                 |
+| `/api-research [library]`          | Adaptive propose-approve research     |
+| `/api-interview [endpoint]`        | Questions FROM research findings      |
+| `/api-verify [endpoint]`           | Re-research and verify implementation |
+| `/api-env [endpoint]`              | Check API keys                        |
+| `/api-status [endpoint]`           | Track progress                        |
+
+### 14-Phase Flow
 
 ```
 Phase 1:  DISAMBIGUATION     - Clarify ambiguous terms before research
@@ -28,18 +44,20 @@ Phase 7:  ENVIRONMENT        - Verify API keys exist
 Phase 8:  TDD RED            - Write failing tests from schema
 Phase 9:  TDD GREEN          - Minimal implementation to pass tests
 Phase 10: VERIFY             - Re-research docs, compare to implementation
-Phase 11: TDD REFACTOR       - Clean up code while tests pass
-Phase 12: DOCUMENTATION      - Update manifests, cache research
-Phase 13: COMPLETION         - Final verification, commit
+Phase 11: CODE REVIEW        - AI review (bugs, security, performance)
+Phase 12: TDD REFACTOR       - Fix review issues + clean up code
+Phase 13: DOCUMENTATION      - Update manifests, cache research
+Phase 14: COMPLETION         - Final verification, commit
 ```
 
 ### Key Principles
 
-1. **Loop Until Green** - Every verification phase loops back if not successful
+1. **Research-First** - Never write code from memory, always verify docs
 2. **Questions FROM Research** - Never use generic template questions
-3. **Adaptive Research** - Propose searches based on context, not shotgun
+3. **Loop Until Green** - Every verification phase loops back if not successful
 4. **7-Turn Re-grounding** - Context injected every 7 turns to prevent dilution
 5. **Verify After Green** - Re-research to catch memory-based implementation errors
+6. **Registry Awareness** - Don't recreate existing elements
 
 ### State Tracking
 
@@ -49,7 +67,17 @@ All progress is tracked in `.claude/api-dev-state.json`:
 - Interview decisions (injected during implementation)
 - Research sources with freshness tracking
 - Turn count for re-grounding
-- Multi-API support with active endpoint pointer
+- Deferred features list
+- Test run history
+
+### Registry
+
+`.claude/registry.json` tracks all created elements:
+
+- APIs with endpoints, schemas, and examples
+- Components with props and variants
+- Pages with routes and data requirements
+- Combined APIs with orchestration patterns
 
 ### Research Cache
 
@@ -59,61 +87,58 @@ Research is cached in `.claude/research/` with 7-day freshness:
 - `[api-name]/CURRENT.md` - Latest research
 - `[api-name]/sources.json` - Research sources
 - `[api-name]/interview.json` - Interview decisions
-- `[api-name]/schema.json` - Schema snapshot
 - Stale research (>7 days) triggers re-research prompt
 
-### Hooks (25 Total - Automatic Enforcement)
-
-| Hook                               | Event            | Action                               |
-| ---------------------------------- | ---------------- | ------------------------------------ |
-| `session-startup.py`               | SessionStart     | Inject state context                 |
-| `detect-interruption.py`           | SessionStart     | Detect interrupted workflows         |
-| `enforce-external-research.py`     | UserPromptSubmit | Require research first               |
-| `enforce-disambiguation.py`        | PreToolUse       | Phase 1 enforcement                  |
-| `enforce-scope.py`                 | PreToolUse       | Phase 2 enforcement                  |
-| `enforce-research.py`              | PreToolUse       | Phase 3 enforcement                  |
-| `enforce-interview.py`             | PreToolUse       | Phase 4 - inject decisions           |
-| `enforce-deep-research.py`         | PreToolUse       | Phase 5 enforcement                  |
-| `enforce-schema.py`                | PreToolUse       | Phase 6 enforcement                  |
-| `enforce-environment.py`           | PreToolUse       | Phase 7 enforcement                  |
-| `enforce-tdd-red.py`               | PreToolUse       | Phase 8 enforcement                  |
-| `verify-implementation.py`         | PreToolUse       | Phase 9 helper                       |
-| `enforce-verify.py`                | PreToolUse       | Phase 10 enforcement                 |
-| `enforce-refactor.py`              | PreToolUse       | Phase 11 enforcement                 |
-| `enforce-documentation.py`         | PreToolUse       | Phase 12 enforcement                 |
-| `enforce-questions-sourced.py`     | PreToolUse       | Validate questions from research     |
-| `enforce-schema-from-interview.py` | PreToolUse       | Validate schema from interview       |
-| `track-tool-use.py`                | PostToolUse      | Log research, count turns            |
-| `periodic-reground.py`             | PostToolUse      | Re-inject context every 7 turns      |
-| `track-scope-coverage.py`          | PostToolUse      | Track implemented vs deferred        |
-| `verify-after-green.py`            | PostToolUse      | Trigger Phase 10 after tests pass    |
-| `cache-research.py`                | PostToolUse      | Create research cache files          |
-| `generate-manifest-entry.py`       | PostToolUse      | Auto-generate API documentation      |
-| `api-workflow-check.py`            | Stop             | Block if incomplete, generate output |
-| `session-logger.py`                | Stop             | Save session to api-sessions         |
-
-### Auto-Generated Documentation
-
-When Phase 12 completes, `generate-manifest-entry.py` automatically creates:
-
-- **Comprehensive curl examples** (minimal, full, auth, enum variations, boundary values)
-- **Complete test cases** (success, validation, required fields, types, boundaries, arrays)
-- **Parameter documentation** with all possible values
-- **Ready-to-use entries** for `api-tests-manifest.json`
+### Re-grounding System
+
+Every 7 turns, the system injects a reminder with:
+
+- Current endpoint and phase progress
+- Key interview decisions
+- Existing registry elements (don't recreate)
+- Deferred features (don't re-suggest)
+- Last test status (GREEN/RED)
+- Brand guide status
+- Research freshness warnings
+- Orchestrator progress (if in /hustle-build)
+
+See: [docs/REGROUNDING.md](./docs/REGROUNDING.md)
+
+### Brand Guide
+
+If `.claude/BRAND_GUIDE.md` exists:
+
+- All UI components use brand colors/fonts
+- Enforce hook checks before component creation
+- Re-grounding reminds about brand guide
+
+### Hooks (45+ Automatic Enforcement)
+
+| Category | Hooks | Purpose |
+| -------- | ----- | ------- |
+| SessionStart | 4 | Inject state, detect interruptions, check updates |
+| UserPromptSubmit | 1 | Require research before API questions |
+| PreToolUse | 22 | Phase enforcement, schema validation |
+| PostToolUse | 12 | Tracking, re-grounding, registry updates |
+| Stop | 2 | Workflow completion, session logging |
 
 ### Usage
 
 ```bash
-# Full automated workflow
-/hustle-api-create my-endpoint
+# Orchestrated build (recommended for features)
+/hustle-build dashboard with user stats and activity charts
 
-# Manual step-by-step
-/hustle-api-research [library]
-/hustle-api-interview [endpoint]
-/hustle-api-env [endpoint]
+# Individual workflows
+/api-create stripe-checkout
+/hustle-ui-create StatCard
+/hustle-ui-create-page Dashboard
+
+# TDD cycle
 /red
 /green
-/hustle-api-verify [endpoint]
 /refactor
+
+# Git
 /commit
+/pr
 ```