@hustle-together/api-dev-tools 3.0.0 → 3.2.0

package/scripts/generate-test-manifest.ts

@@ -0,0 +1,520 @@
+#!/usr/bin/env npx tsx
+/**
+ * Generate Test Manifest Script
+ *
+ * Programmatically generates api-tests-manifest.json by parsing:
+ * 1. Vitest test files (*.test.ts, *.spec.ts)
+ * 2. Zod schemas (for parameter extraction)
+ * 3. API route files (for endpoint metadata)
+ * 4. Interview state file (.claude/api-dev-state.json)
+ *
+ * IMPORTANT: This is 100% programmatic - NO LLM involvement.
+ * Tests are the SOURCE OF TRUTH.
+ *
+ * @generated by @hustle-together/api-dev-tools v3.0
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// ============================================
+// Types
+// ============================================
+
+interface TestCase {
+  name: string;
+  line: number;
+  description?: string;
+}
+
+interface TestGroup {
+  name: string;
+  tests: TestCase[];
+  groups: TestGroup[];
+}
+
+interface ParameterInfo {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+  default?: unknown;
+  enum?: string[];
+}
+
+interface EndpointManifest {
+  id: string;
+  name: string;
+  endpoint: string;
+  method: string;
+  description: string;
+  category: string;
+  parameters: {
+    query?: ParameterInfo[];
+    body?: ParameterInfo[];
+    headers?: ParameterInfo[];
+  };
+  responses: {
+    success: { status: number; description: string };
+    error: { status: number; description: string }[];
+  };
+  testFile: string;
+  testCount: number;
+  testCases: string[];
+  interviewDecisions?: Record<string, string>;
+  generatedAt: string;
+}
+
+interface ManifestOutput {
+  version: string;
+  generatedAt: string;
+  endpoints: EndpointManifest[];
+  summary: {
+    totalEndpoints: number;
+    totalTests: number;
+    categories: string[];
+  };
+}
+
+// ============================================
+// File Discovery
+// ============================================
+
+function findFiles(baseDir: string, pattern: RegExp, exclude: string[] = ['node_modules', '.git', 'dist']): string[] {
+  const files: string[] = [];
+
+  function walk(dir: string) {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (exclude.includes(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          walk(fullPath);
+        } else if (entry.isFile() && pattern.test(entry.name)) {
+          files.push(fullPath);
+        }
+      }
+    } catch {
+      // Skip directories we can't read
+    }
+  }
+
+  walk(baseDir);
+  return files;
+}
+
+// ============================================
+// Test File Parser
+// ============================================
+
+function parseTestFile(filePath: string): { groups: TestGroup[]; endpoint?: string; method?: string } {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n');
+
+  const rootGroups: TestGroup[] = [];
+  const groupStack: TestGroup[] = [];
+
+  let braceCount = 0;
+  let describeStartBrace = 0;
+
+  // Extract endpoint from test file comments or describe blocks
+  let endpoint: string | undefined;
+  let method: string | undefined;
+
+  // Look for endpoint pattern in describe or comments
+  const endpointMatch = content.match(/(?:\/api\/[\w\/-]+)/);
+  if (endpointMatch) {
+    endpoint = endpointMatch[0];
+  }
+
+  // Look for HTTP method
+  const methodMatch = content.match(/(?:GET|POST|PUT|DELETE|PATCH)\s*(?:request|endpoint)?/i);
+  if (methodMatch) {
+    method = methodMatch[0].split(/\s/)[0].toUpperCase();
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    // Match describe blocks
+    const describeMatch = line.match(/describe\s*\(\s*['"`]([^'"`]+)['"`]/);
+    if (describeMatch) {
+      const group: TestGroup = {
+        name: describeMatch[1],
+        tests: [],
+        groups: []
+      };
+
+      if (groupStack.length > 0) {
+        groupStack[groupStack.length - 1].groups.push(group);
+      } else {
+        rootGroups.push(group);
+      }
+
+      groupStack.push(group);
+      describeStartBrace = braceCount;
+    }
+
+    // Match it/test blocks
+    const testMatch = line.match(/(?:it|test)\s*\(\s*['"`]([^'"`]+)['"`]/);
+    if (testMatch && groupStack.length > 0) {
+      const testCase: TestCase = {
+        name: testMatch[1],
+        line: lineNum
+      };
+
+      // Extract description from test name
+      if (testCase.name.includes('should')) {
+        testCase.description = testCase.name;
+      }
+
+      groupStack[groupStack.length - 1].tests.push(testCase);
+    }
+
+    // Track braces for scope
+    const openBraces = (line.match(/{/g) || []).length;
+    const closeBraces = (line.match(/}/g) || []).length;
+    braceCount += openBraces - closeBraces;
+
+    // Pop stack when scope closes
+    if (braceCount <= describeStartBrace && groupStack.length > 0) {
+      groupStack.pop();
+      if (groupStack.length > 0) {
+        describeStartBrace = braceCount;
+      }
+    }
+  }
+
+  return { groups: rootGroups, endpoint, method };
+}
+
+// ============================================
+// Zod Schema Parser
+// ============================================
+
+function parseZodSchema(filePath: string): ParameterInfo[] {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const parameters: ParameterInfo[] = [];
+
+  // Match z.object({ ... }) blocks
+  const objectMatch = content.match(/z\.object\s*\(\s*\{([^}]+)\}/gs);
+  if (!objectMatch) return parameters;
+
+  for (const block of objectMatch) {
+    // Extract individual field definitions
+    // Pattern: fieldName: z.type().modifier()
+    const fieldRegex = /(\w+)\s*:\s*z\.(\w+)\s*\(\s*([^)]*)\s*\)([^,\n]*)/g;
+    let match;
+
+    while ((match = fieldRegex.exec(block)) !== null) {
+      const [, name, type, typeArgs, modifiers] = match;
+
+      const param: ParameterInfo = {
+        name,
+        type: mapZodType(type),
+        required: !modifiers.includes('.optional()') && !modifiers.includes('.nullable()')
+      };
+
+      // Extract description from .describe()
+      const descMatch = modifiers.match(/\.describe\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+      if (descMatch) {
+        param.description = descMatch[1];
+      }
+
+      // Extract default value
+      const defaultMatch = modifiers.match(/\.default\s*\(\s*([^)]+)\s*\)/);
+      if (defaultMatch) {
+        try {
+          param.default = JSON.parse(defaultMatch[1]);
+        } catch {
+          param.default = defaultMatch[1];
+        }
+      }
+
+      // Extract enum values for z.enum()
+      if (type === 'enum' && typeArgs) {
+        const enumMatch = typeArgs.match(/\[([^\]]+)\]/);
+        if (enumMatch) {
+          param.enum = enumMatch[1]
+            .split(',')
+            .map(s => s.trim().replace(/['"`]/g, ''));
+        }
+      }
+
+      parameters.push(param);
+    }
+  }
+
+  return parameters;
+}
+
+function mapZodType(zodType: string): string {
+  const typeMap: Record<string, string> = {
+    'string': 'string',
+    'number': 'number',
+    'boolean': 'boolean',
+    'array': 'array',
+    'object': 'object',
+    'enum': 'enum',
+    'literal': 'literal',
+    'union': 'union',
+    'date': 'date',
+    'any': 'any',
+    'unknown': 'unknown',
+    'null': 'null',
+    'undefined': 'undefined',
+    'void': 'void',
+    'never': 'never',
+    'bigint': 'bigint',
+    'symbol': 'symbol'
+  };
+  return typeMap[zodType] || zodType;
+}
+
+// ============================================
+// Route File Parser
+// ============================================
+
+function parseRouteFile(filePath: string): { methods: string[]; description?: string } {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const methods: string[] = [];
+
+  // Find exported HTTP method handlers
+  const methodPatterns = [
+    /export\s+(?:async\s+)?function\s+(GET|POST|PUT|DELETE|PATCH)/g,
+    /export\s+const\s+(GET|POST|PUT|DELETE|PATCH)\s*=/g
+  ];
+
+  for (const pattern of methodPatterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      if (!methods.includes(match[1])) {
+        methods.push(match[1]);
+      }
+    }
+  }
+
+  // Extract description from JSDoc
+  const jsdocMatch = content.match(/\/\*\*\s*\n\s*\*\s*([^\n*]+)/);
+  const description = jsdocMatch ? jsdocMatch[1].trim() : undefined;
+
+  return { methods, description };
+}
+
+// ============================================
+// Interview State Reader
+// ============================================
+
+interface InterviewState {
+  endpoint: string;
+  decisions: Record<string, string>;
+  phase: number;
+}
+
+function readInterviewState(baseDir: string): Map<string, Record<string, string>> {
+  const stateFile = path.join(baseDir, '.claude', 'api-dev-state.json');
+  const decisions = new Map<string, Record<string, string>>();
+
+  if (!fs.existsSync(stateFile)) {
+    return decisions;
+  }
+
+  try {
+    const content = fs.readFileSync(stateFile, 'utf-8');
+    const state = JSON.parse(content);
+
+    if (Array.isArray(state.endpoints)) {
+      for (const ep of state.endpoints) {
+        if (ep.endpoint && ep.decisions) {
+          decisions.set(ep.endpoint, ep.decisions);
+        }
+      }
+    }
+  } catch {
+    // Invalid state file, return empty
+  }
+
+  return decisions;
+}
+
+// ============================================
+// Main Generator
+// ============================================
+
+function generateManifest(baseDir: string): ManifestOutput {
+  console.log('🔍 Scanning for test files...');
+
+  // Find all test files
+  const testFiles = findFiles(baseDir, /\.(test|spec)\.(ts|tsx)$/);
+  console.log(`   Found ${testFiles.length} test files`);
+
+  // Find all schema files
+  const schemaFiles = findFiles(baseDir, /schema.*\.ts$/);
+  console.log(`   Found ${schemaFiles.length} schema files`);
+
+  // Read interview decisions
+  const interviewDecisions = readInterviewState(baseDir);
+  console.log(`   Found ${interviewDecisions.size} interview records`);
+
+  const endpoints: EndpointManifest[] = [];
+  const categories = new Set<string>();
+  let totalTests = 0;
+
+  for (const testFile of testFiles) {
+    const relativePath = path.relative(baseDir, testFile);
+    console.log(`\n📄 Processing: ${relativePath}`);
+
+    // Parse test file
+    const { groups, endpoint, method } = parseTestFile(testFile);
+
+    // Count tests and extract names
+    const testCases: string[] = [];
+    function countTests(grps: TestGroup[]): number {
+      let count = 0;
+      for (const g of grps) {
+        for (const t of g.tests) {
+          count++;
+          testCases.push(t.name);
+        }
+        count += countTests(g.groups);
+      }
+      return count;
+    }
+    const testCount = countTests(groups);
+    totalTests += testCount;
+
+    if (!endpoint) {
+      console.log(`   ⚠️  No endpoint detected, skipping`);
+      continue;
+    }
+
+    // Determine category from path
+    const pathParts = relativePath.split(path.sep);
+    let category = 'General';
+    if (pathParts.includes('api')) {
+      const apiIndex = pathParts.indexOf('api');
+      if (apiIndex + 1 < pathParts.length) {
+        category = pathParts[apiIndex + 1];
+      }
+    }
+    categories.add(category);
+
+    // Find matching route file
+    const routeDir = path.dirname(testFile).replace('__tests__', '').replace('.test', '');
+    const possibleRoutes = [
+      path.join(routeDir, 'route.ts'),
+      path.join(routeDir, 'route.tsx'),
+      testFile.replace(/\.(test|spec)\.(ts|tsx)$/, '.ts')
+    ];
+
+    let routeInfo = { methods: [method || 'GET'], description: undefined as string | undefined };
+    for (const routePath of possibleRoutes) {
+      if (fs.existsSync(routePath)) {
+        routeInfo = parseRouteFile(routePath);
+        break;
+      }
+    }
+
+    // Find matching schema file
+    const schemaBaseName = path.basename(testFile).replace(/\.(test|spec)\.(ts|tsx)$/, '');
+    const matchingSchemas = schemaFiles.filter(s =>
+      s.includes(schemaBaseName) || s.includes(category.toLowerCase())
+    );
+
+    let parameters: ParameterInfo[] = [];
+    for (const schemaFile of matchingSchemas) {
+      parameters = [...parameters, ...parseZodSchema(schemaFile)];
+    }
+
+    // Get interview decisions if available
+    const decisions = interviewDecisions.get(endpoint);
+
+    // Generate endpoint ID
+    const endpointId = endpoint
+      .replace(/^\/api\//, '')
+      .replace(/\//g, '-')
+      .replace(/[^a-z0-9-]/gi, '');
+
+    const manifest: EndpointManifest = {
+      id: endpointId,
+      name: groups[0]?.name || endpointId,
+      endpoint,
+      method: routeInfo.methods[0] || method || 'GET',
+      description: routeInfo.description || `API endpoint: ${endpoint}`,
+      category,
+      parameters: {
+        query: parameters.filter(p => !p.name.startsWith('body')),
+        body: parameters.filter(p => p.name.startsWith('body') || p.name === 'data'),
+        headers: []
+      },
+      responses: {
+        success: { status: 200, description: 'Successful response' },
+        error: [
+          { status: 400, description: 'Bad request' },
+          { status: 500, description: 'Internal server error' }
+        ]
+      },
+      testFile: relativePath,
+      testCount,
+      testCases,
+      interviewDecisions: decisions,
+      generatedAt: new Date().toISOString()
+    };
+
+    endpoints.push(manifest);
+    console.log(`   ✅ Generated manifest for ${endpoint} (${testCount} tests)`);
+  }
+
+  return {
+    version: '3.0.0',
+    generatedAt: new Date().toISOString(),
+    endpoints,
+    summary: {
+      totalEndpoints: endpoints.length,
+      totalTests,
+      categories: Array.from(categories)
+    }
+  };
+}
+
+// ============================================
+// CLI Entry Point
+// ============================================
+
+function main() {
+  const args = process.argv.slice(2);
+  const baseDir = args[0] || process.cwd();
+  const outputPath = args[1] || path.join(baseDir, 'src', 'app', 'api-test', 'api-tests-manifest.json');
+
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log('  📋 API Test Manifest Generator');
+  console.log('  @hustle-together/api-dev-tools v3.0');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log(`\n📁 Base directory: ${baseDir}`);
+  console.log(`📄 Output file: ${outputPath}\n`);
+
+  const manifest = generateManifest(baseDir);
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Write manifest
+  fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
+
+  console.log('\n═══════════════════════════════════════════════════════════════');
+  console.log('  ✅ Manifest generated successfully!');
+  console.log('═══════════════════════════════════════════════════════════════');
+  console.log(`\n📊 Summary:`);
+  console.log(`   • Endpoints: ${manifest.summary.totalEndpoints}`);
+  console.log(`   • Tests: ${manifest.summary.totalTests}`);
+  console.log(`   • Categories: ${manifest.summary.categories.join(', ')}`);
+  console.log(`\n📄 Output: ${outputPath}\n`);
+}
+
+main();

package/templates/CLAUDE-SECTION.md

@@ -0,0 +1,84 @@
+## API Development Workflow (v3.0)
+
+This project uses **@hustle-together/api-dev-tools** for interview-driven, research-first API development.
+
+### Available Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/api-create [endpoint]` | Complete 12-phase workflow |
+| `/api-interview [endpoint]` | Questions FROM research findings |
+| `/api-research [library]` | Adaptive propose-approve research |
+| `/api-verify [endpoint]` | Re-research and verify implementation |
+| `/api-env [endpoint]` | Check API keys |
+| `/api-status [endpoint]` | Track progress |
+
+### 12-Phase Flow
+
+```
+Phase 0:  DISAMBIGUATION     - Clarify ambiguous terms before research
+Phase 1:  SCOPE              - Confirm understanding of endpoint
+Phase 2:  INITIAL RESEARCH   - 2-3 targeted searches (Context7, WebSearch)
+Phase 3:  INTERVIEW          - Questions generated FROM discovered params
+Phase 4:  DEEP RESEARCH      - Propose additional searches based on answers
+Phase 5:  SCHEMA             - Create Zod schema from research + interview
+Phase 6:  ENVIRONMENT        - Verify API keys exist
+Phase 7:  TDD RED            - Write failing tests from schema
+Phase 8:  TDD GREEN          - Minimal implementation to pass tests
+Phase 9:  VERIFY             - Re-research docs, compare to implementation
+Phase 10: TDD REFACTOR       - Clean up code while tests pass
+Phase 11: DOCUMENTATION      - Update manifests, cache research
+Phase 12: COMPLETION         - Final verification, commit
+```
+
+### Key Principles
+
+1. **Loop Until Green** - Every verification phase loops back if not successful
+2. **Questions FROM Research** - Never use generic template questions
+3. **Adaptive Research** - Propose searches based on context, not shotgun
+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
+
+### State Tracking
+
+All progress is tracked in `.claude/api-dev-state.json`:
+- Current phase and status for each
+- Interview decisions (injected during implementation)
+- Research sources with freshness tracking
+- Turn count for re-grounding
+
+### Research Cache
+
+Research is cached in `.claude/research/` with 7-day freshness:
+- `index.json` - Freshness tracking
+- `[api-name]/CURRENT.md` - Latest research
+- Stale research (>7 days) triggers re-research prompt
+
+### Hooks (Automatic Enforcement)
+
+| Hook | When | Action |
+|------|------|--------|
+| `session-startup.py` | Session start | Inject state context |
+| `enforce-external-research.py` | API questions | Require research first |
+| `enforce-research.py` | Write/Edit | Block without research |
+| `enforce-interview.py` | Write/Edit | Inject interview decisions |
+| `verify-after-green.py` | Tests pass | Trigger Phase 9 |
+| `periodic-reground.py` | Every 7 turns | Re-inject context |
+| `api-workflow-check.py` | Stop | Block if incomplete |
+
+### Usage
+
+```bash
+# Full automated workflow
+/api-create my-endpoint
+
+# Manual step-by-step
+/api-research [library]
+/api-interview [endpoint]
+/api-env [endpoint]
+/red
+/green
+/api-verify [endpoint]
+/refactor
+/commit
+```