@hustle-together/api-dev-tools 1.0.0

package/commands/api-research.md

@@ -0,0 +1,279 @@
+# API Research - Documentation Discovery & Schema Extraction
+
+**Usage:** `/api-research [library-or-service-name]`
+
+**Purpose:** Automatically research external APIs, SDKs, and libraries to discover ALL available parameters, options, and features.
+
+## What This Command Does
+
+1. **Searches for Official Documentation**
+   - Official API docs
+   - SDK/library documentation
+   - GitHub repositories
+   - npm package pages (if applicable)
+
+2. **Extracts Complete Schemas**
+   - All request parameters (required + optional)
+   - All response fields
+   - Type definitions
+   - Validation rules
+   - Default values
+
+3. **Discovers Hidden Features**
+   - Undocumented parameters (from source code)
+   - Advanced configuration options
+   - Beta/experimental features
+   - Deprecated options to avoid
+
+4. **Documents Integration Requirements**
+   - Required environment variables
+   - API key setup
+   - Rate limits and quotas
+   - Pricing/cost information
+   - Version compatibility
+
+## Research Process
+
+### Step 1: Find Official Sources
+```
+- Web search for "[library-name] documentation"
+- Check npm registry for package info
+- Find GitHub repository
+- Look for TypeScript definitions
+- Search for community resources
+```
+
+### Step 2: Deep Dive into Documentation
+```
+- Read API reference pages
+- Review SDK documentation
+- Check TypeScript type definitions (.d.ts files)
+- Look at example code
+- Find changelog for recent changes
+```
+
+### Step 3: Source Code Analysis
+```
+- Review actual implementation code
+- Check for undocumented parameters
+- Find default values in source
+- Identify validation logic
+- Discover error cases
+```
+
+### Step 4: Test & Verify
+```
+- Check what parameters are actually used
+- Verify parameter names and types
+- Test edge cases
+- Document observed behavior
+```
+
+## Output Format
+
+Creates: `/src/v2/docs/research/[library-name].md`
+
+```markdown
+# Research: [Library/Service Name]
+
+**Date:** [current-date]
+**Version:** [version-number]
+**Status:** Research Complete
+
+## 1. Official Documentation Links
+- Main docs: [URL]
+- API reference: [URL]
+- GitHub repo: [URL]
+- npm package: [URL]
+- TypeScript types: [URL]
+
+## 2. Installation & Setup
+### Installation
+```bash
+[installation command]
+```
+
+### Environment Variables
+```env
+[required env vars]
+```
+
+### API Key Setup
+[How to obtain and configure]
+
+## 3. Complete Request Schema
+### Required Parameters
+| Parameter | Type | Description | Validation |
+|-----------|------|-------------|------------|
+| [name] | [type] | [desc] | [rules] |
+
+### Optional Parameters
+| Parameter | Type | Default | Description | Notes |
+|-----------|------|---------|-------------|-------|
+| [name] | [type] | [default] | [desc] | [notes] |
+
+### Zod Schema (Preliminary)
+```typescript
+const RequestSchema = z.object({
+  // Required
+  requiredParam: z.string().min(1),
+
+  // Optional with defaults
+  optionalParam: z.string().default('default-value'),
+
+  // Enums
+  mode: z.enum(['option1', 'option2']).default('option1'),
+
+  // Nested objects
+  config: z.object({
+    setting: z.boolean().default(true),
+  }).optional(),
+});
+```
+
+## 4. Complete Response Schema
+### Success Response
+```typescript
+interface SuccessResponse {
+  [field]: [type]; // [description]
+}
+```
+
+### Error Response
+```typescript
+interface ErrorResponse {
+  error: string;
+  code?: string;
+  details?: unknown;
+}
+```
+
+### Zod Schema (Preliminary)
+```typescript
+const ResponseSchema = z.object({
+  // Response fields
+});
+```
+
+## 5. Features & Capabilities
+### Core Features
+- [Feature 1]: [description]
+- [Feature 2]: [description]
+
+### Advanced Features
+- [Advanced 1]: [description + how to enable]
+- [Advanced 2]: [description + how to enable]
+
+### Experimental/Beta Features
+- [Beta feature]: [description + stability notes]
+
+## 6. Limitations & Constraints
+- Rate limits: [details]
+- Size limits: [details]
+- Timeout: [details]
+- Quotas: [details]
+- Costs: [details]
+
+## 7. Integration Notes
+### Vercel AI SDK Integration
+[If using AI SDK, document integration patterns]
+
+### Error Handling
+[Common errors and how to handle]
+
+### Best Practices
+- [Practice 1]
+- [Practice 2]
+
+## 8. Code Examples
+### Basic Usage
+```typescript
+[minimal example]
+```
+
+### Advanced Usage
+```typescript
+[example with optional parameters]
+```
+
+### Error Handling
+```typescript
+[example with try/catch]
+```
+
+## 9. Testing Considerations
+- [ ] Test basic success case
+- [ ] Test all optional parameters
+- [ ] Test validation failures
+- [ ] Test rate limiting
+- [ ] Test timeout scenarios
+- [ ] Test error responses
+
+## 10. Version History & Changes
+[Notable changes in recent versions]
+
+## 11. Related Resources
+- [Community examples]
+- [Blog posts]
+- [Stack Overflow discussions]
+- [Alternative libraries]
+```
+
+## Usage Examples
+
+### Research an AI SDK
+```bash
+/api-research vercel-ai-sdk-generateText
+```
+
+### Research an External API
+```bash
+/api-research firecrawl-api
+```
+
+### Research a Library
+```bash
+/api-research anthropic-sdk
+```
+
+## Research Workflow
+
+1. **Execute command**: `/api-research [name]`
+2. **I search and analyze**: Web search → Documentation → Source code
+3. **Document everything**: Create comprehensive research doc
+4. **Review together**: You verify accuracy and completeness
+5. **Use in implementation**: Reference during TDD cycle
+
+## Why This Matters
+
+Without thorough research:
+- ❌ Miss optional parameters that users need
+- ❌ Don't test edge cases properly
+- ❌ Implement wrong validation rules
+- ❌ Create brittle integrations
+
+With thorough research:
+- ✅ Know ALL available options
+- ✅ Test comprehensively
+- ✅ Proper validation
+- ✅ Robust implementation
+- ✅ Better documentation
+
+<claude-commands-template>
+## Research Guidelines
+
+1. **Read actual code** - TypeScript definitions reveal truth
+2. **Test assumptions** - Verify parameters actually work
+3. **Document sources** - Track ALL links for future reference
+4. **Check versions** - Note version-specific features
+5. **Find examples** - Real code > documentation
+6. **Look for gotchas** - Common mistakes, limitations, bugs
+
+## Integration with API Development
+
+After research:
+- Use in `/api-interview` to ask informed questions
+- Reference in `/api-create` for schema creation
+- Base tests on discovered parameters
+- Update if API changes
+</claude-commands-template>

package/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/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