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

package/.claude/agents/test-writer.md

@@ -0,0 +1,104 @@
+---
+name: test-writer
+description: Test case generator from schemas and interview decisions. Use during Phase 8 (TDD Red) to create comprehensive failing tests before implementation.
+tools: Read, Write, Grep, Glob
+model: sonnet
+---
+
+# Test Writer Agent
+
+You are a TDD specialist that writes comprehensive, failing tests based on schemas and interview decisions.
+
+## Your Role
+
+1. **Analyze schemas** - Understand request/response structure
+2. **Apply interview decisions** - Test user-specified behaviors
+3. **Write failing tests** - Tests that define expected behavior
+4. **Cover edge cases** - Error handling, validation, edge cases
+
+## Input Format
+
+You will receive:
+
+- Zod schemas for request/response
+- Interview decisions (error handling, formats, etc.)
+- Target test file path
+- Endpoint path and method
+
+## Output Format
+
+Generate comprehensive test file:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest } from "next/server";
+import { POST } from "../route";
+
+describe("[Endpoint] API", () => {
+  describe("POST /api/v2/[endpoint]", () => {
+    // Happy path tests
+    it("should return data with valid request", async () => {
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({
+          /* valid data */
+        }),
+      });
+
+      const response = await POST(request);
+      const data = await response.json();
+
+      expect(response.status).toBe(200);
+      expect(data).toHaveProperty("result");
+    });
+
+    // Validation tests
+    it("should return 400 for missing required fields", async () => {
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({}),
+      });
+
+      const response = await POST(request);
+      expect(response.status).toBe(400);
+    });
+
+    // Error handling tests (from interview)
+    it("should handle API errors gracefully", async () => {
+      // Mock external API failure
+      vi.spyOn(global, "fetch").mockRejectedValueOnce(new Error("API down"));
+
+      const request = new NextRequest("http://localhost/api/v2/endpoint", {
+        method: "POST",
+        body: JSON.stringify({
+          /* valid data */
+        }),
+      });
+
+      const response = await POST(request);
+      expect(response.status).toBe(500);
+    });
+
+    // Format tests (from interview)
+    it("should return requested format", async () => {
+      // Test based on interview format decisions
+    });
+  });
+});
+```
+
+## Test Categories
+
+1. **Happy Path** - Valid requests return expected data
+2. **Validation** - Invalid input returns 400 with helpful message
+3. **Error Handling** - API failures handled per interview decisions
+4. **Authentication** - API key handling
+5. **Edge Cases** - Empty data, nulls, large payloads
+
+## Guidelines
+
+1. **Tests MUST fail initially** - Implementation doesn't exist yet
+2. **One assertion per test** - Clear failure messages
+3. **Use interview decisions** - Error strategy, formats, etc.
+4. **Mock external APIs** - Don't make real API calls in tests
+5. **Cover 100%** - Every schema field should be tested

package/.claude/api-dev-state.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.0",
+  "version": "3.12.0",
   "created_at": null,
   "endpoint": null,
   "library": null,
@@ -63,87 +63,336 @@
         "confidence": "critical"
       },
       "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:31:26.336088",
+      "prompt_preview": "1. CREATE PR\n   - Go to GitHub: https://github.com/hustle-together/api-dev-tools\n   - Create PR from...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "create pr",
+          "update version (i can do this for you now)",
+          "api",
+          "package",
+          "test",
+          "publish",
+          "@hustle-together/api-dev-tools",
+          "1.0.0",
+          "3.12.0",
+          "package.json"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "question_pattern",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:32:03.480897",
+      "prompt_preview": "File    Purpose\nworkflow-demo.html (247KB)    Main interactive workflow demo\nexecution-trace-COMPREH...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "write integration demo",
+          "api",
+          "interview-driven-api"
+        ],
+        "patterns_matched": [
+          "question_pattern",
+          "always_research",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:35:36.217406",
+      "prompt_preview": "> File    Purpose\nworkflow-demo.html (247KB)    Main interactive workflow demo\nexecution-trace-COMPR...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "write integration demo",
+          "api",
+          "view",
+          "interview-driven-api"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "question_pattern",
+          "always_research"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:36:41.163781",
+      "prompt_preview": "how do i merge it i am on the comment page ",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "how do"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:40:21.674198",
+      "prompt_preview": "ok i did it check the main now please",
+      "detection": {
+        "detected": false,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "none"
+      },
+      "injected": false
+    },
+    {
+      "timestamp": "2025-12-27T22:43:21.172124",
+      "prompt_preview": "wait was the github master updated witht he most current push?",
+      "detection": {
+        "detected": true,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "low"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:45:59.739199",
+      "prompt_preview": "ok now update the npm package, make a skill for this as well based on my api-dev-tools and mcp if th...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "update the npm package, make a skill for this as w",
+          "package",
+          "api"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:49:36.519292",
+      "prompt_preview": "/Users/alfonso/Documents/GitHub/api-dev-tools/demo/hustle-together/workflow-demo-backup-20251212-134...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "api",
+          "0.0.1"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:52:43.366799",
+      "prompt_preview": "help me use that publish skill how do i get that code?",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "how do",
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "always_research",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:53:54.327491",
+      "prompt_preview": "id rather use the terminal command to open the pafge",
+      "detection": {
+        "detected": true,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "low"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:58:35.375132",
+      "prompt_preview": "No no, I use a secret key, so you just open my page for me, and I just gave it access by using my se...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "secret",
+          "key"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:59:14.000695",
+      "prompt_preview": "No, that's dumb. Normally you just give me some commands that I run in terminal and they just work.N...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T22:59:56.192298",
+      "prompt_preview": "  npm login run that and i will tap the security code access then you can run the publish command",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "publish"
+        ],
+        "patterns_matched": [
+          "technical_term"
+        ],
+        "confidence": "high"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T23:02:25.007015",
+      "prompt_preview": "ok i pushed it already",
+      "detection": {
+        "detected": false,
+        "terms": [],
+        "patterns_matched": [],
+        "confidence": "none"
+      },
+      "injected": false
+    },
+    {
+      "timestamp": "2025-12-27T23:05:45.854012",
+      "prompt_preview": "Yeah, let's create a new project with maybe a base Next.js application in it. We'll install the npm ...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "create a new project with maybe a base next.js app",
+          "install the npm command for this, so that we can t",
+          "test",
+          "install",
+          "next.js"
+        ],
+        "patterns_matched": [
+          "technical_term",
+          "question_pattern",
+          "always_research"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T23:10:02.864062",
+      "prompt_preview": "alfonso@Alfonsos-MacBook-Pro test-api-dev-tools % /api-create brandfetch\nzsh: no such file or direct...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "create brandfetch",
+          "api",
+          "test",
+          "test-api"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "question_pattern",
+          "technical_term"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
+    },
+    {
+      "timestamp": "2025-12-27T23:12:38.166540",
+      "prompt_preview": "\n  A gift for you\n  Your rate limits are 2x higher through 12/31. Enjoy the extra room to think!\n  \u23bf...",
+      "detection": {
+        "detected": true,
+        "terms": [
+          "create brandfetch ",
+          "error",
+          "api",
+          "test",
+          "hook",
+          "hustle-api",
+          "test-api",
+          "v2.0.76",
+          "4.5"
+        ],
+        "patterns_matched": [
+          "always_research",
+          "technical_term",
+          "question_pattern"
+        ],
+        "confidence": "critical"
+      },
+      "injected": true
     }
   ],
   "phases": {
     "disambiguation": {
-      "status": "not_started",
-      "clarified": null,
-      "search_variations": [],
-      "description": "Pre-research disambiguation to clarify ambiguous requests"
+      "status": "not_started"
     },
     "scope": {
-      "status": "not_started",
-      "confirmed": false,
-      "description": "Initial scope understanding and confirmation"
+      "status": "not_started"
     },
     "research_initial": {
-      "status": "not_started",
-      "sources": [],
-      "summary_approved": false,
-      "description": "Context7/WebSearch research for live documentation"
+      "status": "not_started"
     },
     "interview": {
-      "status": "not_started",
-      "questions": [],
-      "user_question_count": 0,
-      "structured_question_count": 0,
-      "decisions": {},
-      "description": "Structured interview about requirements (generated FROM research)"
+      "status": "not_started"
     },
     "research_deep": {
-      "status": "not_started",
-      "sources": [],
-      "proposed_searches": [],
-      "approved_searches": [],
-      "skipped_searches": [],
-      "description": "Deep dive based on interview answers (adaptive, not shotgun)"
+      "status": "not_started"
     },
     "schema_creation": {
-      "status": "not_started",
-      "schema_file": null,
-      "schema_approved": false,
-      "description": "Zod schema creation from research"
+      "status": "not_started"
     },
     "environment_check": {
-      "status": "not_started",
-      "keys_verified": [],
-      "keys_missing": [],
-      "confirmed": false,
-      "description": "API key and environment verification"
+      "status": "not_started"
     },
     "tdd_red": {
-      "status": "not_started",
-      "test_file": null,
-      "test_count": 0,
-      "test_matrix_approved": false,
-      "description": "Write failing tests first"
+      "status": "not_started"
     },
     "tdd_green": {
-      "status": "not_started",
-      "implementation_file": null,
-      "all_tests_passing": false,
-      "description": "Minimal implementation to pass tests"
+      "status": "not_started"
     },
     "verify": {
-      "status": "not_started",
-      "gaps_found": 0,
-      "gaps_fixed": 0,
-      "intentional_omissions": [],
-      "re_research_done": false,
-      "description": "Re-research after Green to verify implementation matches docs"
+      "status": "not_started"
     },
     "tdd_refactor": {
-      "status": "not_started",
-      "description": "Code cleanup while keeping tests green"
+      "status": "not_started"
     },
     "documentation": {
-      "status": "not_started",
-      "files_updated": [],
-      "manifest_updated": false,
-      "openapi_updated": false,
-      "research_cached": false,
-      "description": "Update manifests, OpenAPI, cache research"
+      "status": "not_started"
     }
   },
   "verification": {

package/.claude/commands/README.md

@@ -13,23 +13,24 @@
 
 ## Hook Architecture (9 Hooks)
 
-| Hook | Event | Purpose |
-|------|-------|---------|
-| `session-startup.py` | SessionStart | Inject state at session start |
+| Hook                           | Event            | Purpose                            |
+| ------------------------------ | ---------------- | ---------------------------------- |
+| `session-startup.py`           | SessionStart     | Inject state at session start      |
 | `enforce-external-research.py` | UserPromptSubmit | Detect API terms, require research |
-| `enforce-research.py` | PreToolUse | Block writes until research done |
-| `enforce-interview.py` | PreToolUse | Inject interview decisions |
-| `verify-implementation.py` | PreToolUse | Require test file before route |
-| `track-tool-use.py` | PostToolUse | Log research, count turns |
-| `periodic-reground.py` | PostToolUse | Re-ground every 7 turns |
-| `verify-after-green.py` | PostToolUse | Trigger Phase 10 after test pass |
-| `api-workflow-check.py` | Stop | Block if phases incomplete |
+| `enforce-research.py`          | PreToolUse       | Block writes until research done   |
+| `enforce-interview.py`         | PreToolUse       | Inject interview decisions         |
+| `verify-implementation.py`     | PreToolUse       | Require test file before route     |
+| `track-tool-use.py`            | PostToolUse      | Log research, count turns          |
+| `periodic-reground.py`         | PostToolUse      | Re-ground every 7 turns            |
+| `verify-after-green.py`        | PostToolUse      | Trigger Phase 10 after test pass   |
+| `api-workflow-check.py`        | Stop             | Block if phases incomplete         |
 
 ## Available Commands
 
 ### Complete Workflow
 
 **`/api-create [endpoint-name]`**
+
 - Runs all 13 phases automatically
 - Loop-back architecture at every checkpoint
 - See [api-create.md](api-create.md) for full flow
@@ -37,32 +38,38 @@
 ### Individual Phases
 
 **`/api-interview [endpoint-name]`**
+
 - Questions GENERATED from research findings
 - Different question types: enum, continuous, boolean
 - See [api-interview.md](api-interview.md)
 
 **`/api-research [library-or-service]`**
+
 - Adaptive propose-approve flow (not shotgun)
 - Research cached with 7-day freshness
 - See [api-research.md](api-research.md)
 
 **`/api-verify [endpoint-name]`** (NEW)
+
 - Manual Phase 10 verification
 - Re-read docs, compare to implementation
 - Report gaps, loop back or document omissions
 - See [api-verify.md](api-verify.md)
 
 **`/api-env [endpoint-name]`**
+
 - Check API keys and environment
 - See [api-env.md](api-env.md)
 
 **`/api-status [endpoint-name]`**
+
 - Track progress through 13 phases
 - See [api-status.md](api-status.md)
 
 ### TDD Commands
 
 From [@wbern/claude-instructions](https://github.com/wbern/claude-instructions):
+
 - `/red` - Write ONE failing test
 - `/green` - Minimal implementation to pass
 - `/refactor` - Clean up while tests pass
@@ -131,11 +138,13 @@ Research cached in `.claude/research/`:
 ## Quick Start
 
 ### Automated
+
 ```bash
 /api-create my-endpoint
 ```
 
 ### Manual Step-by-Step
+
 ```bash
 /api-research [library]      # Initial research
 /api-interview [endpoint]    # Questions from research
@@ -154,6 +163,7 @@ npx @hustle-together/api-dev-tools --scope=project
 ```
 
 Installs:
+
 - Commands in `.claude/commands/`
 - Hooks in `.claude/hooks/`
 - Settings in `.claude/settings.json`
@@ -163,6 +173,7 @@ Installs:
 ### Team-Wide
 
 Add to `package.json`:
+
 ```json
 {
   "scripts": {

package/.claude/commands/add-command.md

@@ -54,7 +54,7 @@ Bash command output: (exclamation)git status(backticks)
 **Bash Commands (exclamation prefix)**: Limited to current working directory only.
 
 - ✅ Works: `! + backtick + git status + backtick` (in project dir)
-- ❌ Blocked: `! + backtick + ls /outside/project + backtick` (outside project)  
+- ❌ Blocked: `! + backtick + ls /outside/project + backtick` (outside project)
 - ❌ Blocked: `! + backtick + pwd + backtick` (if referencing dirs outside project)
 
 **File References (`@` prefix)**: No directory restrictions.
@@ -90,6 +90,7 @@ Compare @src/old.js with @src/new.js and explain differences
 ---
 allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git log:*)
 ---
+
 Current status: (!)git status(`)
 Current branch: (!)git branch --show-current(`)
 Recent commits: (!)git log --oneline -5(`)
@@ -123,7 +124,8 @@ echo "Ask GPT-5 about: ＄ARGUMENTS" > ~/.claude/commands/ai/gpt5.md
 ### Safe Commands (No Security Issues)
 
 ```markdown
-# System prompt editor (file reference only)  
+# System prompt editor (file reference only)
+
 (@)path/to/system/prompt.md
 
 Edit your system prompt above.
@@ -135,6 +137,7 @@ Edit your system prompt above.
 ---
 allowed-tools: Bash(git status:*), Bash(npm list:*)
 ---
+
 Current git status: (!)git status(`)
 Package info: (!)npm list --depth=0(`)
 
@@ -145,6 +148,7 @@ Review project state and suggest next steps.
 
 ```markdown
 # Compare config files
+
 Compare (@)path/to/system.md with (@)project/config.md
 
 Show differences and suggest improvements.
@@ -156,7 +160,6 @@ After creating: `/<command-name> [arguments]`
 
 Example: `/review` or `/ai:gpt5 "explain this code"`
 
-
 ## 🛡 Project Rules (Injected into every command)
 
 1. **NO BROKEN BUILDS:**
@@ -181,7 +184,7 @@ Example: `/review` or `/ai:gpt5 "explain this code"`
 4. **API KEY MANAGEMENT:**
    - Support three loading methods:
      - Server environment variables
-     - NEXT_PUBLIC_ variables (client-side)
+     - NEXT*PUBLIC* variables (client-side)
      - Custom headers (X-OpenAI-Key, X-Anthropic-Key, etc.)
    - Never hardcode API keys
    - Always validate key availability before use
@@ -206,4 +209,4 @@ Example: `/review` or `/ai:gpt5 "explain this code"`
      - Code examples
      - Testing notes
    - Document expected behavior and edge cases
-   - Include real-world output examples
+   - Include real-world output examples