@hustle-together/api-dev-tools 3.11.1 → 3.12.1

package/scripts/generate-test-manifest.ts

@@ -14,8 +14,8 @@
  * @generated by @hustle-together/api-dev-tools v3.0
  */
 
-import fs from 'fs';
-import path from 'path';
+import fs from "fs";
+import path from "path";
 
 // ============================================
 // Types
@@ -80,7 +80,11 @@ interface ManifestOutput {
 // File Discovery
 // ============================================
 
-function findFiles(baseDir: string, pattern: RegExp, exclude: string[] = ['node_modules', '.git', 'dist']): string[] {
+function findFiles(
+  baseDir: string,
+  pattern: RegExp,
+  exclude: string[] = ["node_modules", ".git", "dist"],
+): string[] {
   const files: string[] = [];
 
   function walk(dir: string) {
@@ -109,9 +113,13 @@ function findFiles(baseDir: string, pattern: RegExp, exclude: string[] = ['node_
 // 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');
+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[] = [];
@@ -130,7 +138,9 @@ function parseTestFile(filePath: string): { groups: TestGroup[]; endpoint?: stri
   }
 
   // Look for HTTP method
-  const methodMatch = content.match(/(?:GET|POST|PUT|DELETE|PATCH)\s*(?:request|endpoint)?/i);
+  const methodMatch = content.match(
+    /(?:GET|POST|PUT|DELETE|PATCH)\s*(?:request|endpoint)?/i,
+  );
   if (methodMatch) {
     method = methodMatch[0].split(/\s/)[0].toUpperCase();
   }
@@ -145,7 +155,7 @@ function parseTestFile(filePath: string): { groups: TestGroup[]; endpoint?: stri
       const group: TestGroup = {
         name: describeMatch[1],
         tests: [],
-        groups: []
+        groups: [],
       };
 
       if (groupStack.length > 0) {
@@ -163,11 +173,11 @@ function parseTestFile(filePath: string): { groups: TestGroup[]; endpoint?: stri
     if (testMatch && groupStack.length > 0) {
       const testCase: TestCase = {
         name: testMatch[1],
-        line: lineNum
+        line: lineNum,
       };
 
       // Extract description from test name
-      if (testCase.name.includes('should')) {
+      if (testCase.name.includes("should")) {
         testCase.description = testCase.name;
       }
 
@@ -196,7 +206,7 @@ function parseTestFile(filePath: string): { groups: TestGroup[]; endpoint?: stri
 // ============================================
 
 function parseZodSchema(filePath: string): ParameterInfo[] {
-  const content = fs.readFileSync(filePath, 'utf-8');
+  const content = fs.readFileSync(filePath, "utf-8");
   const parameters: ParameterInfo[] = [];
 
   // Match z.object({ ... }) blocks
@@ -215,11 +225,15 @@ function parseZodSchema(filePath: string): ParameterInfo[] {
       const param: ParameterInfo = {
         name,
         type: mapZodType(type),
-        required: !modifiers.includes('.optional()') && !modifiers.includes('.nullable()')
+        required:
+          !modifiers.includes(".optional()") &&
+          !modifiers.includes(".nullable()"),
       };
 
       // Extract description from .describe()
-      const descMatch = modifiers.match(/\.describe\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/);
+      const descMatch = modifiers.match(
+        /\.describe\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/,
+      );
       if (descMatch) {
         param.description = descMatch[1];
       }
@@ -235,12 +249,12 @@ function parseZodSchema(filePath: string): ParameterInfo[] {
       }
 
       // Extract enum values for z.enum()
-      if (type === 'enum' && typeArgs) {
+      if (type === "enum" && typeArgs) {
         const enumMatch = typeArgs.match(/\[([^\]]+)\]/);
         if (enumMatch) {
           param.enum = enumMatch[1]
-            .split(',')
-            .map(s => s.trim().replace(/['"`]/g, ''));
+            .split(",")
+            .map((s) => s.trim().replace(/['"`]/g, ""));
         }
       }
 
@@ -253,23 +267,23 @@ function parseZodSchema(filePath: string): ParameterInfo[] {
 
 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'
+    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;
 }
@@ -278,14 +292,17 @@ function mapZodType(zodType: string): string {
 // Route File Parser
 // ============================================
 
-function parseRouteFile(filePath: string): { methods: string[]; description?: string } {
-  const content = fs.readFileSync(filePath, 'utf-8');
+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
+    /export\s+const\s+(GET|POST|PUT|DELETE|PATCH)\s*=/g,
   ];
 
   for (const pattern of methodPatterns) {
@@ -314,8 +331,10 @@ interface InterviewState {
   phase: number;
 }
 
-function readInterviewState(baseDir: string): Map<string, Record<string, string>> {
-  const stateFile = path.join(baseDir, '.claude', 'api-dev-state.json');
+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)) {
@@ -323,7 +342,7 @@ function readInterviewState(baseDir: string): Map<string, Record<string, string>
   }
 
   try {
-    const content = fs.readFileSync(stateFile, 'utf-8');
+    const content = fs.readFileSync(stateFile, "utf-8");
     const state = JSON.parse(content);
 
     if (Array.isArray(state.endpoints)) {
@@ -345,7 +364,7 @@ function readInterviewState(baseDir: string): Map<string, Record<string, string>
 // ============================================
 
 function generateManifest(baseDir: string): ManifestOutput {
-  console.log('🔍 Scanning for test files...');
+  console.log("🔍 Scanning for test files...");
 
   // Find all test files
   const testFiles = findFiles(baseDir, /\.(test|spec)\.(ts|tsx)$/);
@@ -393,9 +412,9 @@ function generateManifest(baseDir: string): ManifestOutput {
 
     // Determine category from path
     const pathParts = relativePath.split(path.sep);
-    let category = 'General';
-    if (pathParts.includes('api')) {
-      const apiIndex = pathParts.indexOf('api');
+    let category = "General";
+    if (pathParts.includes("api")) {
+      const apiIndex = pathParts.indexOf("api");
       if (apiIndex + 1 < pathParts.length) {
         category = pathParts[apiIndex + 1];
       }
@@ -403,14 +422,20 @@ function generateManifest(baseDir: string): ManifestOutput {
     categories.add(category);
 
     // Find matching route file
-    const routeDir = path.dirname(testFile).replace('__tests__', '').replace('.test', '');
+    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')
+      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 };
+    let routeInfo = {
+      methods: [method || "GET"],
+      description: undefined as string | undefined,
+    };
     for (const routePath of possibleRoutes) {
       if (fs.existsSync(routePath)) {
         routeInfo = parseRouteFile(routePath);
@@ -419,9 +444,11 @@ function generateManifest(baseDir: string): ManifestOutput {
     }
 
     // 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())
+    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[] = [];
@@ -434,49 +461,53 @@ function generateManifest(baseDir: string): ManifestOutput {
 
     // Generate endpoint ID
     const endpointId = endpoint
-      .replace(/^\/api\//, '')
-      .replace(/\//g, '-')
-      .replace(/[^a-z0-9-]/gi, '');
+      .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',
+      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: []
+        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' },
+        success: { status: 200, description: "Successful response" },
         error: [
-          { status: 400, description: 'Bad request' },
-          { status: 500, description: 'Internal server error' }
-        ]
+          { status: 400, description: "Bad request" },
+          { status: 500, description: "Internal server error" },
+        ],
       },
       testFile: relativePath,
       testCount,
       testCases,
       interviewDecisions: decisions,
-      generatedAt: new Date().toISOString()
+      generatedAt: new Date().toISOString(),
     };
 
     endpoints.push(manifest);
-    console.log(`   ✅ Generated manifest for ${endpoint} (${testCount} tests)`);
+    console.log(
+      `   ✅ Generated manifest for ${endpoint} (${testCount} tests)`,
+    );
   }
 
   return {
-    version: '3.0.0',
+    version: "3.0.0",
     generatedAt: new Date().toISOString(),
     endpoints,
     summary: {
       totalEndpoints: endpoints.length,
       totalTests,
-      categories: Array.from(categories)
-    }
+      categories: Array.from(categories),
+    },
   };
 }
 
@@ -487,12 +518,18 @@ function generateManifest(baseDir: string): ManifestOutput {
 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('═══════════════════════════════════════════════════════════════');
+  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`);
 
@@ -507,13 +544,17 @@ function main() {
   // Write manifest
   fs.writeFileSync(outputPath, JSON.stringify(manifest, null, 2));
 
-  console.log('\n═══════════════════════════════════════════════════════════════');
-  console.log('  ✅ Manifest generated successfully!');
-  console.log('═══════════════════════════════════════════════════════════════');
+  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(`   • Categories: ${manifest.summary.categories.join(", ")}`);
   console.log(`\n📄 Output: ${outputPath}\n`);
 }
 

package/templates/.env.example

@@ -0,0 +1,57 @@
+# =============================================================================
+# API Dev Tools - Environment Configuration
+# =============================================================================
+# Copy this file to .env in your project root and fill in your values.
+# Never commit .env files with real credentials to git!
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# NTFY Notifications (Optional)
+# -----------------------------------------------------------------------------
+# Get a free topic at https://ntfy.sh or self-host
+NTFY_ENABLED=false
+NTFY_SERVER=https://ntfy.sh
+NTFY_TOPIC=your-unique-topic-name
+
+# -----------------------------------------------------------------------------
+# GitHub Integration
+# -----------------------------------------------------------------------------
+# Create at: https://github.com/settings/tokens
+# Required scopes: repo, read:org
+GITHUB_PERSONAL_ACCESS_TOKEN=
+
+# -----------------------------------------------------------------------------
+# Common API Keys (Add as needed for your integrations)
+# -----------------------------------------------------------------------------
+# These are examples - add keys for the APIs you integrate
+
+# OpenAI
+OPENAI_API_KEY=
+
+# Anthropic
+ANTHROPIC_API_KEY=
+
+# Vercel AI SDK
+# (Uses OPENAI_API_KEY or ANTHROPIC_API_KEY automatically)
+
+# -----------------------------------------------------------------------------
+# Development Settings
+# -----------------------------------------------------------------------------
+# Storybook URL for visual testing
+STORYBOOK_URL=http://localhost:6006
+
+# API base URL for testing
+API_BASE_URL=http://localhost:3000
+
+# -----------------------------------------------------------------------------
+# Token Usage Tracking
+# -----------------------------------------------------------------------------
+# Track Claude Code token usage per session
+TRACK_TOKEN_USAGE=true
+
+# -----------------------------------------------------------------------------
+# TypeDoc Documentation
+# -----------------------------------------------------------------------------
+# Auto-generate docs after Phase 12
+TYPEDOC_AUTO_GENERATE=true
+TYPEDOC_OUTPUT_DIR=docs/api