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

package/.claude/commands/api-status.md

@@ -0,0 +1,259 @@
+# API Status - Track Implementation Progress
+
+**Usage:** `/api-status [endpoint-name]` or `/api-status --all`
+
+**Purpose:** View and update API implementation status, track progress, and manage V2 migration.
+
+## State File Integration
+
+This command reads from `.claude/api-dev-state.json` which is automatically updated by the enforcement hooks.
+
+### Reading Current State
+
+**FIRST: Read the state file to understand current progress:**
+
+```
+Tool: Read
+Path: .claude/api-dev-state.json
+```
+
+Parse the JSON and display a formatted status report showing:
+- Current endpoint being worked on
+- Phase completion status (scope, research, interview, TDD, docs)
+- Sources consulted during research
+- Timestamps for each phase
+- Verification status
+
+### Example State Display
+
+```
+📊 API Development Progress
+
+Endpoint: stream-text
+Library: vercel-ai-sdk
+Started: 2025-12-06T20:00:00Z
+
+PHASES:
+  ✅ Scope defined (20:00:30)
+  ✅ Initial research - 4 sources consulted (20:02:00)
+  🔄 Interview - in progress
+  ⬜ Deep research
+  ⬜ Schema creation
+  ⬜ Environment check
+  ⬜ TDD Red
+  ⬜ TDD Green
+  ⬜ TDD Refactor
+  ⬜ Documentation
+
+RESEARCH SOURCES:
+  • context7: @ai-sdk/core (20:01:00)
+  • websearch: "Vercel AI SDK streamText 2025" (20:01:30)
+  • webfetch: https://sdk.vercel.ai/docs (20:01:45)
+
+VERIFICATION:
+  ❌ All sources fetched: false
+  ❌ Schema matches docs: false
+  ❌ Tests cover params: false
+  ❌ All tests passing: false
+```
+
+## What This Shows
+
+### For Specific Endpoint
+```
+📊 Status: /api/v2/generate-css
+
+Phase: ✅ Complete
+Tests: 33/33 passing (100% coverage)
+Documentation: ✅ Complete
+
+Timeline:
+✅ Interview completed (2025-12-06)
+✅ Research completed (2025-12-06)
+✅ Environment verified (2025-12-06)
+✅ Tests written (Red phase)
+✅ Implementation complete (Green phase)
+✅ Refactored (Refactor phase)
+✅ Documentation updated
+✅ Committed to git
+
+Files:
+- Route: src/app/api/v2/generate-css/route.ts
+- Tests: src/app/api/v2/generate-css/__tests__/generate-css.api.test.ts
+- Docs: src/v2/docs/endpoints/generate-css.md
+- Research: src/v2/docs/research/gemini-flash.md
+
+Next Steps: None - endpoint complete
+```
+
+### For All Endpoints
+```
+📊 V2 API Implementation Status
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ COMPLETE (2)
+  • /api/v2/health (15 tests)
+  • /api/v2/monitor (23 tests)
+
+🚧 IN PROGRESS (1)
+  • /api/v2/generate-css (interview complete, implementing)
+
+📋 PLANNED (3)
+  • /api/v2/generate-html
+  • /api/v2/chat
+  • /api/v2/scrape
+
+❌ NOT STARTED (0)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Summary:
+  Total endpoints: 6
+  Complete: 2 (33%)
+  In progress: 1 (17%)
+  Planned: 3 (50%)
+  Total tests: 38
+  Coverage: 100%
+
+Last updated: 2025-12-06
+```
+
+## Commands
+
+### View Status
+```bash
+/api-status generate-css    # Specific endpoint
+/api-status --all           # All endpoints
+```
+
+### Update Status
+```bash
+/api-status generate-css --phase=testing
+/api-status generate-css --complete
+```
+
+## Status Tracking File
+
+Updates: `/src/v2/docs/v2-api-implementation-status.md`
+
+**Format:**
+```markdown
+# V2 API Implementation Status
+
+**Last Updated:** 2025-12-06
+**Total Endpoints:** 6
+**Completed:** 2 (33%)
+
+## Endpoints
+
+### ✅ /api/v2/health
+- **Status:** Complete
+- **Tests:** 15/15 passing
+- **Coverage:** 100%
+- **Interview:** [Link to docs]
+- **Implemented:** 2025-12-06
+- **Purpose:** System health check with dependency validation
+
+### 🚧 /api/v2/generate-css
+- **Status:** In Progress (Testing)
+- **Tests:** 20/33 passing
+- **Coverage:** 85%
+- **Interview:** [Link to docs]
+- **Started:** 2025-12-06
+- **Blocked by:** None
+- **Next:** Complete remaining tests
+
+### 📋 /api/v2/generate-html
+- **Status:** Planned
+- **Priority:** High
+- **Dependencies:** None
+- **Interview:** Not started
+- **Estimated effort:** Medium
+```
+
+## Integration with Workflow
+
+### After Interview
+```bash
+/api-interview generate-css
+/api-status generate-css --phase=interview-complete
+```
+
+### After Research
+```bash
+/api-research gemini-flash
+/api-status generate-css --phase=research-complete
+```
+
+### After TDD Cycle
+```bash
+/cycle generate CSS with Gemini
+/api-status generate-css --complete
+```
+
+### Before Commit
+```bash
+pnpm test:run
+/api-status --all  # Verify all green
+/commit
+```
+
+## Automatic Updates
+
+The `/api-create` command automatically updates status:
+- Interview phase → "Interview Complete"
+- Red phase → "Tests Written"
+- Green phase → "Implementation Complete"
+- Refactor phase → "Refactored"
+- Documentation → "Documentation Updated"
+- Commit → "Complete"
+
+## Status Phases
+
+1. **Not Started** - No work begun
+2. **Interview Complete** - Understanding documented
+3. **Research Complete** - External docs reviewed
+4. **Environment Ready** - API keys verified
+5. **Tests Written** - Red phase complete
+6. **Implementation Complete** - Green phase complete
+7. **Refactored** - Code cleaned up
+8. **Documentation Updated** - Manifests updated
+9. **Complete** - All tests passing, committed
+
+## Reports
+
+### Coverage Report
+```bash
+/api-status --coverage
+```
+Shows test coverage for all V2 endpoints.
+
+### Migration Report
+```bash
+/api-status --migration
+```
+Shows progress from legacy to V2.
+
+### Blockers Report
+```bash
+/api-status --blocked
+```
+Shows endpoints blocked by missing keys, dependencies, etc.
+
+<claude-commands-template>
+## Status Management
+
+- Update status after each phase completion
+- Keep v2-api-implementation-status.md current
+- Use status to plan next work
+- Reference in standup/progress reports
+- Track blockers and dependencies
+
+## Integration Points
+
+- Used by /api-create to track progress
+- Used by /commit to verify readiness
+- Used by team to see what's done
+- Used for planning future work
+</claude-commands-template>

package/.claude/commands/api-verify.md

@@ -0,0 +1,231 @@
+# API Verify - Implementation Verification (Phase 10) v3.0
+
+**Usage:** `/api-verify [endpoint-name]`
+
+**Purpose:** Manually trigger Phase 10 verification - re-research documentation and compare to implementation to catch memory-based errors.
+
+## When to Use
+
+- After tests pass (TDD Green complete)
+- Before proceeding to Refactor phase
+- When unsure if implementation matches documentation
+- After significant time has passed since initial research
+
+## Verification Process
+
+### Step 1: Re-Read Original Documentation
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ RE-RESEARCHING DOCUMENTATION                               │
+│                                                            │
+│ Fetching current documentation for: [endpoint-name]        │
+│                                                            │
+│ Sources:                                                   │
+│ - Context7: [library-name]                                 │
+│ - Official docs: [URL]                                     │
+│ - Cached research: .claude/research/[api]/CURRENT.md       │
+│                                                            │
+│ Freshness: [X days old]                                    │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 2: Feature-by-Feature Comparison
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ IMPLEMENTATION VERIFICATION                                │
+│                                                            │
+│ Comparing documentation to implementation:                 │
+│                                                            │
+│ │ Feature         │ In Docs │ Implemented │ Status        │
+│ ├─────────────────┼─────────┼─────────────┼───────────────│
+│ │ domain param    │ ✓       │ ✓           │ ✅ Match      │
+│ │ format param    │ 4 opts  │ 3 opts      │ ⚠️ Missing    │
+│ │ quality range   │ 1-100   │ 1-100       │ ✅ Match      │
+│ │ size param      │ ✓       │ ✗           │ ⚠️ Missing    │
+│ │ webhook support │ ✓       │ ✗           │ ℹ️ Intentional │
+│ │ batch mode      │ ✓       │ ✗           │ ℹ️ Intentional │
+│                                                            │
+│ MATCHES: 2                                                 │
+│ MISSING: 2                                                 │
+│ INTENTIONAL OMISSIONS: 2                                   │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 3: Gap Analysis
+
+For each discrepancy:
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ GAP #1: format parameter                                   │
+│                                                            │
+│ Documentation says: ["json", "svg", "png", "raw"]          │
+│ Implementation has:  ["json", "svg", "png"]                │
+│                                                            │
+│ Missing: "raw" format                                      │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add "raw" format support                         │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+
+┌────────────────────────────────────────────────────────────┐
+│ GAP #2: size parameter                                     │
+│                                                            │
+│ Documentation says: size parameter exists (16-4096)        │
+│ Implementation has:  not implemented                       │
+│                                                            │
+│ Action?                                                    │
+│ [x] Fix - Add size parameter                               │
+│ [ ] Skip - Mark as intentional omission                    │
+│ [ ] Defer - Add to backlog for later                       │
+└────────────────────────────────────────────────────────────┘
+```
+
+### Step 4: Loop Back or Proceed
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ VERIFICATION SUMMARY                                       │
+│                                                            │
+│ Gaps to fix: 2                                             │
+│ Intentional omissions: 2                                   │
+│                                                            │
+│ DECISION:                                                  │
+│                                                            │
+│ [x] Fix gaps → Return to TDD Red (write tests for gaps)    │
+│ [ ] Skip all → Document as omissions, proceed to Refactor  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## State File Updates
+
+```json
+{
+  "phases": {
+    "verify": {
+      "status": "complete",
+      "gaps_found": 2,
+      "gaps_fixed": 2,
+      "intentional_omissions": [
+        {
+          "feature": "webhook support",
+          "reason": "User declined in interview",
+          "documented_at": "..."
+        },
+        {
+          "feature": "batch mode",
+          "reason": "Out of scope for v1",
+          "documented_at": "..."
+        }
+      ],
+      "re_research_done": true,
+      "completed_at": "..."
+    }
+  }
+}
+```
+
+## Verification Report
+
+Creates: `.claude/research/[api-name]/verification.md`
+
+```markdown
+# Verification Report: [API Name]
+
+**Date:** [current-date]
+**Implementation File:** src/app/api/v2/[endpoint]/route.ts
+**Test File:** src/app/api/v2/[endpoint]/__tests__/[endpoint].api.test.ts
+
+## Documentation Sources Re-Checked
+
+| Source | URL | Checked |
+|--------|-----|---------|
+| Official docs | [URL] | ✓ |
+| Context7 | [library] | ✓ |
+| Cached research | .claude/research/[api]/CURRENT.md | ✓ |
+
+## Feature Comparison
+
+| Feature | In Docs | Implemented | Status |
+|---------|---------|-------------|--------|
+| domain param | ✓ | ✓ | ✅ Match |
+| format param | 4 options | 3 options | ⚠️ Fixed |
+| size param | ✓ | ✓ | ⚠️ Fixed |
+| webhook | ✓ | ✗ | ℹ️ Intentional |
+
+## Gaps Fixed
+
+1. **format parameter** - Added "raw" format support
+   - Test added: test/format-raw.test.ts:15
+   - Implementation: route.ts:45
+
+2. **size parameter** - Added size validation
+   - Test added: test/size-param.test.ts:10
+   - Implementation: route.ts:52
+
+## Intentional Omissions
+
+1. **webhook support**
+   - Reason: User declined in interview (Phase 4)
+   - Decision recorded: api-dev-state.json
+   - May add in v2
+
+2. **batch mode**
+   - Reason: Out of scope for initial release
+   - Documented for future consideration
+
+## Verification Result
+
+- **Status:** PASSED
+- **All documented features accounted for**
+- **Ready for Refactor phase**
+```
+
+## Hook Integration
+
+This command is normally triggered automatically by `verify-after-green.py` hook after tests pass.
+
+Manual invocation is useful when:
+- Hook was skipped or didn't trigger
+- Want to re-verify after changes
+- Research is stale and needs refresh
+
+## Workflow Position
+
+```
+Phase 8: TDD Red (write tests)
+    │
+    ▼
+Phase 9: TDD Green (implementation)
+    │
+    ▼
+Phase 10: VERIFY ← /api-verify triggers this
+    │
+    ├─► Gaps found? → Loop back to Phase 8
+    │
+    └─► All verified → Proceed to Phase 11 (Refactor)
+```
+
+<claude-commands-template>
+## Verification Guidelines
+
+1. **Re-read, don't remember** - Fresh fetch of docs every time
+2. **Feature-by-feature** - Systematic comparison
+3. **Document omissions** - Intentional != forgotten
+4. **Loop back for gaps** - Return to TDD Red if fixes needed
+5. **Update state file** - Track everything
+6. **Create verification report** - Audit trail
+
+## Common Gaps to Check
+
+- Parameter counts match?
+- Enum options complete?
+- Range boundaries correct?
+- Error codes handled?
+- Optional features accounted for?
+- Default values match docs?
+</claude-commands-template>

package/.claude/commands/beepboop.md

@@ -0,0 +1,97 @@
+---
+description: Communicate AI-generated content with transparent attribution
+argument-hint: <task-description>
+---
+
+# AI-Attributed Communication Command
+
+Execute the user's requested task (e.g., posting PR comments, GitHub issue comments, or other communications through various MCPs), but frame the output with clear AI attribution.
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+## Instructions
+
+Arguments: $ARGUMENTS
+
+**IMPORTANT Communication Format:**
+
+1. **Opening**: Begin with "*Beep boop, I am Claude Code 🤖, my user has reviewed and approved the following written by me:*"
+   - Use italics for this line
+   - Clearly establishes AI authorship
+
+2. **Middle**: Perform the requested task (post comment, create review, etc.)
+   - Execute whatever communication task the user requested
+   - Write the actual content that accomplishes the user's goal
+
+3. **Closing**: End with "*Beep boop, Claude Code 🤖 out!*"
+   - Use italics for this line
+   - Provides clear closure
+
+## Purpose
+
+This command ensures transparency about AI usage while maintaining that the user has reviewed and approved the content. It prevents offloading review responsibility to other users while being open about AI assistance.
+
+## Examples
+
+- Posting a GitHub PR review comment
+- Adding a comment to a GitHub issue
+- Responding to feedback with AI-generated explanations
+- Any communication where AI attribution is valuable
+
+
+## 🛡 Project Rules (Injected into every command)
+
+1. **NO BROKEN BUILDS:**
+   - Run `pnpm test` before every `/commit`
+   - Ensure all tests pass
+   - Fix any type errors immediately
+
+2. **API DEVELOPMENT:**
+   - All new APIs MUST have Zod request/response schemas
+   - All APIs MUST be documented in both:
+     - OpenAPI spec ([src/lib/openapi/](src/lib/openapi/))
+     - API test manifest ([src/app/api-test/api-tests-manifest.json](src/app/api-test/api-tests-manifest.json))
+   - Test ALL parameters and edge cases
+   - Include code examples and real-world outputs
+
+3. **TDD WORKFLOW:**
+   - ALWAYS use /red → /green → /refactor cycle
+   - NEVER write implementation without failing test first
+   - Use /cycle for feature development
+   - Use characterization tests for refactoring
+
+4. **API KEY MANAGEMENT:**
+   - Support three loading methods:
+     - Server environment variables
+     - NEXT_PUBLIC_ variables (client-side)
+     - Custom headers (X-OpenAI-Key, X-Anthropic-Key, etc.)
+   - Never hardcode API keys
+   - Always validate key availability before use
+
+5. **COMPREHENSIVE TESTING:**
+   - When researching APIs, read actual implementation code
+   - Discover ALL possible parameters (not just documented ones)
+   - Test with various parameter combinations
+   - Document custom headers, query params, request/response schemas
+   - Include validation rules and testing notes
+
+6. **NO UI BLOAT:**
+   - This is an API project with minimal frontend
+   - Only keep necessary test/documentation interfaces
+   - Delete unused components immediately
+   - No unnecessary UI libraries or features
+
+7. **DOCUMENTATION:**
+   - If you change an API, you MUST update:
+     - OpenAPI spec
+     - api-tests-manifest.json
+     - Code examples
+     - Testing notes
+   - Document expected behavior and edge cases
+   - Include real-world output examples

package/.claude/commands/busycommit.md

@@ -0,0 +1,112 @@
+---
+description: Create multiple atomic git commits, one logical change at a time
+argument-hint: [optional-commit-description]
+---
+
+## General Guidelines
+
+### Output Style
+
+- **Never explicitly mention TDD** in code, comments, commits, PRs, or issues
+- Write natural, descriptive code without meta-commentary about the development process
+- The code should speak for itself - TDD is the process, not the product
+
+Create multiple atomic git commits, committing the smallest possible logical unit at a time
+
+Include any of the following info if specified: $ARGUMENTS
+
+## Process
+
+1. Run `git status` and `git diff` to review changes
+2. Run `git log --oneline -5` to see recent commit style
+3. Stage relevant files with `git add`
+4. Create commit with descriptive message
+5. Verify with `git status`
+
+## Example
+
+```bash
+git add <files>
+git commit -m "feat(#123): add validation to user input form"
+```
+
+## Atomic Commit Approach
+
+Each commit should represent ONE logical change. Do NOT bundle multiple unrelated changes into one commit.
+
+- Identify the smallest atomic units of change
+- For EACH atomic unit: stage only those files/hunks, commit, verify
+- Use `git add -p` to stage partial file changes when a file contains multiple logical changes
+- Repeat until all changes are committed
+- It is OK to create multiple commits without stopping - keep going until `git status` shows clean
+
+## Multi-Commit Example
+
+If a single file contains multiple unrelated changes, use `git add -p` to stage hunks interactively:
+
+```bash
+# Stage only the validation-related hunks from the file
+git add -p src/user-service.ts
+# Select 'y' for validation hunks, 'n' for others
+git commit -m "feat(#123): add email format validation"
+
+# Stage the error handling hunks
+git add -p src/user-service.ts
+git commit -m "fix(#124): handle null user gracefully"
+
+# Stage remaining changes
+git add src/user-service.ts
+git commit -m "refactor: extract user lookup to helper"
+```
+
+
+## 🛡 Project Rules (Injected into every command)
+
+1. **NO BROKEN BUILDS:**
+   - Run `pnpm test` before every `/commit`
+   - Ensure all tests pass
+   - Fix any type errors immediately
+
+2. **API DEVELOPMENT:**
+   - All new APIs MUST have Zod request/response schemas
+   - All APIs MUST be documented in both:
+     - OpenAPI spec ([src/lib/openapi/](src/lib/openapi/))
+     - API test manifest ([src/app/api-test/api-tests-manifest.json](src/app/api-test/api-tests-manifest.json))
+   - Test ALL parameters and edge cases
+   - Include code examples and real-world outputs
+
+3. **TDD WORKFLOW:**
+   - ALWAYS use /red → /green → /refactor cycle
+   - NEVER write implementation without failing test first
+   - Use /cycle for feature development
+   - Use characterization tests for refactoring
+
+4. **API KEY MANAGEMENT:**
+   - Support three loading methods:
+     - Server environment variables
+     - NEXT_PUBLIC_ variables (client-side)
+     - Custom headers (X-OpenAI-Key, X-Anthropic-Key, etc.)
+   - Never hardcode API keys
+   - Always validate key availability before use
+
+5. **COMPREHENSIVE TESTING:**
+   - When researching APIs, read actual implementation code
+   - Discover ALL possible parameters (not just documented ones)
+   - Test with various parameter combinations
+   - Document custom headers, query params, request/response schemas
+   - Include validation rules and testing notes
+
+6. **NO UI BLOAT:**
+   - This is an API project with minimal frontend
+   - Only keep necessary test/documentation interfaces
+   - Delete unused components immediately
+   - No unnecessary UI libraries or features
+
+7. **DOCUMENTATION:**
+   - If you change an API, you MUST update:
+     - OpenAPI spec
+     - api-tests-manifest.json
+     - Code examples
+     - Testing notes
+   - Document expected behavior and edge cases
+   - Include real-world output examples