@hustle-together/api-dev-tools 1.0.0

package/bin/cli.js

@@ -0,0 +1,322 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * API Development Tools Installer
+ *
+ * Installs slash commands AND enforcement hooks for interview-driven API development.
+ *
+ * Features:
+ *   - Slash commands in .claude/commands/
+ *   - Python hooks for programmatic enforcement
+ *   - Settings configuration for hook registration
+ *   - State file template for progress tracking
+ *
+ * Usage: npx @mirror-factory/api-dev-tools --scope=project
+ */
+
+// Parse command-line arguments
+const args = process.argv.slice(2);
+const scope = args.find(arg => arg.startsWith('--scope='))?.split('=')[1] || 'project';
+
+// Colors for terminal output
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+/**
+ * Check if Python 3 is available
+ */
+function checkPython() {
+  const pythonCommands = ['python3', 'python'];
+
+  for (const cmd of pythonCommands) {
+    try {
+      const version = execSync(`${cmd} --version 2>&1`, { encoding: 'utf8' }).trim();
+      if (version.includes('Python 3')) {
+        return { available: true, command: cmd, version };
+      }
+    } catch (e) {
+      // Command not found, try next
+    }
+  }
+
+  return { available: false, command: null, version: null };
+}
+
+/**
+ * Verify installation was successful
+ */
+function verifyInstallation(claudeDir, hooksDir) {
+  const checks = [
+    { path: path.join(claudeDir, 'commands'), name: 'Commands directory' },
+    { path: path.join(claudeDir, 'settings.json'), name: 'Settings file' },
+    { path: path.join(claudeDir, 'api-dev-state.json'), name: 'State file' },
+  ];
+
+  // Add hook checks if hooks directory exists
+  if (fs.existsSync(hooksDir)) {
+    checks.push(
+      { path: path.join(hooksDir, 'enforce-research.py'), name: 'enforce-research.py' },
+      { path: path.join(hooksDir, 'track-tool-use.py'), name: 'track-tool-use.py' },
+      { path: path.join(hooksDir, 'api-workflow-check.py'), name: 'api-workflow-check.py' }
+    );
+  }
+
+  const failures = [];
+  for (const check of checks) {
+    if (!fs.existsSync(check.path)) {
+      failures.push(check.name);
+    }
+  }
+
+  return { success: failures.length === 0, failures };
+}
+
+function main() {
+  log('\n🚀 Installing API Development Tools for Claude Code...\n', 'bright');
+
+  // Check Python availability first
+  const python = checkPython();
+  if (!python.available) {
+    log('⚠️  Warning: Python 3 not found', 'yellow');
+    log('   Enforcement hooks require Python 3 to run.', 'yellow');
+    log('   Hooks will be installed but may not work until Python 3 is available.', 'yellow');
+    log('   Install Python 3: https://www.python.org/downloads/\n', 'yellow');
+  } else {
+    log(`✅ Found ${python.version}`, 'green');
+  }
+
+  // Get target directory (where user ran the command)
+  const targetDir = process.cwd();
+  const claudeDir = path.join(targetDir, '.claude');
+  const commandsDir = path.join(claudeDir, 'commands');
+  const hooksDir = path.join(claudeDir, 'hooks');
+
+  // Get source directories from this package
+  const packageDir = path.dirname(__dirname);
+  const sourceCommandsDir = path.join(packageDir, 'commands');
+  const sourceHooksDir = path.join(packageDir, 'hooks');
+  const sourceTemplatesDir = path.join(packageDir, 'templates');
+
+  // Verify source commands exist
+  if (!fs.existsSync(sourceCommandsDir)) {
+    log('❌ Error: Commands directory not found in package', 'red');
+    log(`   Looking for: ${sourceCommandsDir}`, 'red');
+    process.exit(1);
+  }
+
+  // ========================================
+  // 1. Install Commands
+  // ========================================
+  if (!fs.existsSync(commandsDir)) {
+    log(`📁 Creating directory: ${commandsDir}`, 'blue');
+    fs.mkdirSync(commandsDir, { recursive: true });
+  }
+
+  const commandFiles = fs.readdirSync(sourceCommandsDir).filter(file =>
+    file.endsWith('.md')
+  );
+
+  if (commandFiles.length === 0) {
+    log('⚠️  Warning: No command files found to install', 'yellow');
+  } else {
+    log('📦 Installing commands:', 'blue');
+    commandFiles.forEach(file => {
+      const source = path.join(sourceCommandsDir, file);
+      const dest = path.join(commandsDir, file);
+
+      try {
+        fs.copyFileSync(source, dest);
+        log(`   ✅ ${file}`, 'green');
+      } catch (error) {
+        log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
+      }
+    });
+  }
+
+  // ========================================
+  // 2. Install Hooks (Programmatic Enforcement)
+  // ========================================
+  if (fs.existsSync(sourceHooksDir)) {
+    if (!fs.existsSync(hooksDir)) {
+      log(`\n📁 Creating directory: ${hooksDir}`, 'blue');
+      fs.mkdirSync(hooksDir, { recursive: true });
+    }
+
+    const hookFiles = fs.readdirSync(sourceHooksDir).filter(file =>
+      file.endsWith('.py')
+    );
+
+    if (hookFiles.length > 0) {
+      log('\n🔒 Installing enforcement hooks:', 'cyan');
+      hookFiles.forEach(file => {
+        const source = path.join(sourceHooksDir, file);
+        const dest = path.join(hooksDir, file);
+
+        try {
+          fs.copyFileSync(source, dest);
+          // Make executable
+          fs.chmodSync(dest, '755');
+          log(`   ✅ ${file}`, 'green');
+        } catch (error) {
+          log(`   ❌ Failed to copy ${file}: ${error.message}`, 'red');
+        }
+      });
+
+      log('\n   Hook purposes:', 'blue');
+      log('   • enforce-research.py  - Blocks code writing without research', 'blue');
+      log('   • track-tool-use.py    - Logs all research activity', 'blue');
+      log('   • api-workflow-check.py - Prevents stopping until complete', 'blue');
+    }
+  }
+
+  // ========================================
+  // 3. Install/Merge Settings (Hook Registration)
+  // ========================================
+  const settingsSource = path.join(sourceTemplatesDir, 'settings.json');
+  const settingsDest = path.join(claudeDir, 'settings.json');
+
+  if (fs.existsSync(settingsSource)) {
+    log('\n⚙️  Configuring hook settings:', 'cyan');
+
+    try {
+      const newSettings = JSON.parse(fs.readFileSync(settingsSource, 'utf8'));
+
+      if (fs.existsSync(settingsDest)) {
+        // Merge with existing settings
+        const existingSettings = JSON.parse(fs.readFileSync(settingsDest, 'utf8'));
+        const mergedSettings = mergeSettings(existingSettings, newSettings);
+        fs.writeFileSync(settingsDest, JSON.stringify(mergedSettings, null, 2));
+        log('   ✅ Merged with existing settings.json', 'green');
+      } else {
+        // Create new settings file
+        fs.writeFileSync(settingsDest, JSON.stringify(newSettings, null, 2));
+        log('   ✅ Created settings.json with hook configuration', 'green');
+      }
+    } catch (error) {
+      log(`   ❌ Failed to configure settings: ${error.message}`, 'red');
+    }
+  }
+
+  // ========================================
+  // 4. Install State File Template
+  // ========================================
+  const stateSource = path.join(sourceTemplatesDir, 'api-dev-state.json');
+  const stateDest = path.join(claudeDir, 'api-dev-state.json');
+
+  if (fs.existsSync(stateSource)) {
+    log('\n📊 Setting up state tracking:', 'cyan');
+
+    if (!fs.existsSync(stateDest)) {
+      try {
+        fs.copyFileSync(stateSource, stateDest);
+        log('   ✅ Created api-dev-state.json template', 'green');
+      } catch (error) {
+        log(`   ❌ Failed to create state file: ${error.message}`, 'red');
+      }
+    } else {
+      log('   ℹ️  State file already exists (preserved)', 'blue');
+    }
+  }
+
+  // ========================================
+  // Success Summary
+  // ========================================
+  log('\n' + '═'.repeat(60), 'green');
+  log('🎉 API Development Tools installed successfully!', 'green');
+  log('═'.repeat(60) + '\n', 'green');
+
+  log('📋 What was installed:', 'bright');
+  log('   Commands:  .claude/commands/*.md', 'blue');
+  log('   Hooks:     .claude/hooks/*.py', 'blue');
+  log('   Settings:  .claude/settings.json', 'blue');
+  log('   State:     .claude/api-dev-state.json', 'blue');
+
+  log('\n🔒 Enforcement Features:', 'bright');
+  log('   • Research MUST happen before code writing', 'cyan');
+  log('   • All research activity is logged to state file', 'cyan');
+  log('   • Workflow completion is verified before stopping', 'cyan');
+  log('   • Progress is tracked and visible in state file', 'cyan');
+
+  log('\n📚 Available Commands:', 'bright');
+  log('  /api-create [endpoint]    - Complete API development workflow', 'blue');
+  log('  /api-interview [endpoint] - Structured interview about endpoint', 'blue');
+  log('  /api-research [library]   - Deep research of external APIs/SDKs', 'blue');
+  log('  /api-env [endpoint]       - Check API keys and environment', 'blue');
+  log('  /api-status [endpoint]    - Track implementation progress', 'blue');
+
+  log('\n🚀 Quick Start:', 'bright');
+  log('   /api-create my-endpoint', 'blue');
+
+  log('\n💡 Check progress anytime:', 'yellow');
+  log('   cat .claude/api-dev-state.json | jq \'.phases\'', 'yellow');
+
+  log('\n📖 Documentation:', 'bright');
+  log(`   ${path.join(commandsDir, 'README.md')}\n`, 'blue');
+
+  // ========================================
+  // 5. Verify Installation
+  // ========================================
+  const verification = verifyInstallation(claudeDir, hooksDir);
+  if (!verification.success) {
+    log('⚠️  Installation verification found issues:', 'yellow');
+    verification.failures.forEach(f => log(`   • Missing: ${f}`, 'yellow'));
+    log('   Some features may not work correctly.\n', 'yellow');
+  }
+}
+
+/**
+ * Merge two settings objects, combining hooks arrays
+ */
+function mergeSettings(existing, newSettings) {
+  const merged = { ...existing };
+
+  // Merge hooks
+  if (newSettings.hooks) {
+    merged.hooks = merged.hooks || {};
+
+    for (const hookType of Object.keys(newSettings.hooks)) {
+      if (!merged.hooks[hookType]) {
+        merged.hooks[hookType] = [];
+      }
+
+      // Add new hooks that don't already exist (check by command path)
+      for (const newHook of newSettings.hooks[hookType]) {
+        const hookCommand = newHook.hooks?.[0]?.command || '';
+        const exists = merged.hooks[hookType].some(existing => {
+          const existingCommand = existing.hooks?.[0]?.command || '';
+          return existingCommand === hookCommand;
+        });
+
+        if (!exists) {
+          merged.hooks[hookType].push(newHook);
+        }
+      }
+    }
+  }
+
+  return merged;
+}
+
+// Run installer
+try {
+  main();
+} catch (error) {
+  log(`\n❌ Installation failed: ${error.message}`, 'red');
+  log(`   ${error.stack}\n`, 'red');
+  process.exit(1);
+}

package/commands/README.md

@@ -0,0 +1,312 @@
+# API Development Slash Commands
+
+**Comprehensive API development workflow with programmatic enforcement**
+
+## Overview
+
+These slash commands implement an interview-driven, test-first methodology for API development. They automate the workflow described in the V2 Development Patterns and ensure consistent, high-quality API implementations.
+
+## Programmatic Enforcement (Hooks)
+
+This package includes **Python hooks** that provide real programmatic guarantees:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `enforce-research.py` | PreToolUse (Write/Edit) | Blocks API code writing until research is complete |
+| `track-tool-use.py` | PostToolUse (WebSearch/Context7) | Logs all research activity to state file |
+| `api-workflow-check.py` | Stop | Prevents stopping until required phases complete |
+
+### What Gets Enforced
+
+- **Research MUST happen first** - Cannot write API route code without completing research
+- **All research is logged** - WebSearch, WebFetch, Context7 calls tracked in state file
+- **Progress is visible** - Check `.claude/api-dev-state.json` anytime
+- **Workflow completion verified** - Cannot stop until TDD phases complete
+
+### Check Progress
+
+```bash
+# View current state
+cat .claude/api-dev-state.json | jq '.phases'
+
+# Or use the status command
+/api-status
+```
+
+## Available Commands
+
+### 🎯 Complete Workflow
+
+**`/api-create [endpoint-name]`**
+- Orchestrates the entire API development process
+- Runs all phases automatically: Interview → Research → Environment Check → TDD → Documentation
+- Use this for new endpoints to ensure nothing is missed
+
+### 📋 Individual Phases
+
+**`/api-interview [endpoint-name]`**
+- Conducts structured 20-question interview (Anthropic Interviewer methodology)
+- Documents purpose, usage, requirements, edge cases
+- Creates endpoint documentation file
+- **Output:** `/src/v2/docs/endpoints/[endpoint-name].md`
+
+**`/api-research [library-or-service]`**
+- Researches external APIs, SDKs, and libraries
+- Discovers ALL parameters (documented + undocumented)
+- Extracts complete schemas from source code
+- Documents integration requirements
+- **Output:** `/src/v2/docs/research/[library-name].md`
+
+**`/api-env [endpoint-name]`**
+- Checks for required API keys
+- Verifies .env.local and .env.example
+- Provides setup instructions for missing keys
+- **Output:** Terminal report + action items
+
+**`/api-status [endpoint-name]`** or **`/api-status --all`**
+- Shows implementation progress
+- Tracks phases (Interview → Research → Red → Green → Refactor → Complete)
+- Updates V2 implementation status document
+- **Output:** Progress report
+
+### 🔴🟢🔵 TDD Cycle
+
+Use the existing TDD commands from AI_WORKFLOW.md:
+- `/red` - Write ONE failing test
+- `/green` - Minimal implementation to pass
+- `/refactor` - Clean up code while tests pass
+- `/cycle [description]` - Full Red → Green → Refactor loop
+
+## Complete Workflow Example
+
+### Option 1: Fully Automated
+```bash
+/api-create generate-css
+```
+This will:
+1. Interview you about the endpoint
+2. Research required libraries (Gemini SDK, etc.)
+3. Check environment/API keys
+4. Write failing tests (Red)
+5. Implement minimal solution (Green)
+6. Refactor for quality (Refactor)
+7. Update all documentation
+8. Verify tests and coverage
+9. Create commit
+
+### Option 2: Manual Step-by-Step
+```bash
+# Phase 1: Understanding
+/api-interview generate-css
+# (Answer 20 questions about purpose, usage, requirements)
+
+# Phase 2: Research
+/api-research google-generative-ai
+# (Discovers all Gemini SDK parameters)
+
+# Phase 3: Environment
+/api-env generate-css
+# (Verifies GOOGLE_GENERATIVE_AI_API_KEY exists)
+
+# Phase 4: TDD Implementation
+/red
+# (Write failing tests based on interview + research)
+
+/green
+# (Implement route handler with Zod schemas)
+
+/refactor
+# (Clean up, extract patterns, improve code)
+
+# Phase 5: Documentation
+# (Update api-tests-manifest.json, OpenAPI spec, status doc)
+
+# Phase 6: Commit
+pnpm test:run
+/commit
+```
+
+## Command Cheat Sheet
+
+| Command | When to Use | Output |
+|---------|-------------|--------|
+| `/api-create [endpoint]` | Starting new endpoint | Complete implementation |
+| `/api-interview [endpoint]` | Need to understand requirements | Documentation file |
+| `/api-research [library]` | Integrating external API/SDK | Research document |
+| `/api-env [endpoint]` | Before implementation | Environment check report |
+| `/api-status [endpoint]` | Check progress | Status report |
+| `/red` | Write test first | Failing test |
+| `/green` | Make test pass | Working implementation |
+| `/refactor` | Clean up code | Improved code |
+| `/cycle [desc]` | Implement feature | Full TDD cycle |
+
+## File Structure Created
+
+Each endpoint creates this structure:
+```
+src/app/api/v2/[endpoint-name]/
+├── route.ts                               # API handler with Zod schemas
+├── __tests__/
+│   └── [endpoint-name].api.test.ts       # Comprehensive tests
+└── README.md                              # Endpoint documentation
+
+src/v2/docs/
+├── endpoints/
+│   └── [endpoint-name].md                # Interview results
+└── research/
+    └── [library-name].md                 # External API research
+
+src/app/api-test/
+└── api-tests-manifest.json               # Updated with new tests
+
+src/lib/openapi/endpoints/
+└── [endpoint-name].ts                    # OpenAPI spec
+```
+
+## Workflow Principles
+
+### 1. Context First
+**Never write code without understanding WHY it exists.**
+- Interview before implementation
+- Document real-world usage
+- Understand edge cases
+
+### 2. Research Thoroughly
+**Find ALL parameters, not just the documented ones.**
+- Read official docs
+- Check source code
+- Review TypeScript definitions
+- Test assumptions
+
+### 3. Test First (TDD)
+**No implementation without a failing test.**
+- Red: Write test that fails
+- Green: Minimal code to pass
+- Refactor: Improve while tests pass
+
+### 4. Document Everything
+**Future you needs to understand this.**
+- Interview results
+- Research findings
+- API schemas
+- Code examples
+- Testing notes
+
+### 5. Verify Environment
+**Check API keys before starting.**
+- Identify required services
+- Verify keys exist
+- Document setup
+- Test connections
+
+## Integration with Existing Tools
+
+These commands work alongside:
+- **`/plan`** - Create implementation checklist
+- **`/gap`** - Find missing pieces
+- **`/issue [url]`** - Start from GitHub issue
+- **`/commit`** - AI-generated semantic commits
+- **`/pr`** - Create pull request
+
+## Why This Approach Works
+
+### Problems with Previous Approach
+❌ Tests written without understanding purpose
+❌ Missing parameters from incomplete research
+❌ Failed tests due to missing API keys
+❌ No documentation of real-world usage
+❌ Mechanical testing without context
+
+### Benefits of New Approach
+✅ Deep understanding before coding
+✅ Complete parameter coverage
+✅ Environment verified upfront
+✅ Documentation drives implementation
+✅ Tests reflect actual usage patterns
+✅ Consistent, repeatable process
+✅ Nothing gets forgotten
+
+## Getting Started
+
+### First Time Setup
+1. Review this README
+2. Read `/src/v2/docs/AI_WORKFLOW.md`
+3. Read `/src/v2/docs/Main Doc – V2 Development Patterns.md`
+4. Try `/api-create` with a simple endpoint
+
+### For Each New Endpoint
+```bash
+# Quick automated approach
+/api-create [endpoint-name]
+
+# Or manual for learning
+/api-interview [endpoint-name]
+/api-research [library]
+/api-env [endpoint-name]
+/cycle [description]
+/commit
+```
+
+### Checking Progress
+```bash
+/api-status --all           # See all endpoints
+/api-status [endpoint]      # Specific endpoint
+pnpm test:run               # Verify tests pass
+```
+
+## Installation
+
+Install via NPX command:
+```bash
+npx @hustle-together/api-dev-tools --scope=project
+```
+
+This installs:
+- **Commands** in `.claude/commands/` (slash commands)
+- **Hooks** in `.claude/hooks/` (Python enforcement scripts)
+- **Settings** in `.claude/settings.json` (hook registration)
+- **State template** in `.claude/api-dev-state.json` (progress tracking)
+
+### Team-Wide Installation
+
+Add to your project's `package.json`:
+```json
+{
+  "scripts": {
+    "postinstall": "npx @hustle-together/api-dev-tools --scope=project"
+  }
+}
+```
+
+Now `npm install` or `pnpm install` automatically installs the tools for all team members.
+
+## References
+
+- **AI Workflow:** `/src/v2/docs/AI_WORKFLOW.md`
+- **V2 Patterns:** `/src/v2/docs/Main Doc – V2 Development Patterns.md`
+- **AI SDK Catalog:** `/src/v2/docs/ai-sdk-catalog.json`
+- **API Testing Plan:** `/src/v2/docs/API_TESTING_PLAN.md`
+- **Implementation Status:** `/src/v2/docs/v2-api-implementation-status.md`
+
+## Support
+
+If commands aren't working:
+1. Check that files exist in `.claude/commands/`
+2. Verify command syntax matches usage examples
+3. Review error messages for missing dependencies
+4. Check that required docs exist in `/src/v2/docs/`
+
+## Contributing
+
+To improve these commands:
+1. Edit markdown files in `.claude/commands/`
+2. Update this README
+3. Test with real endpoint implementation
+4. Document learnings
+5. Commit improvements
+
+---
+
+**Last Updated:** 2025-12-06
+**Version:** 1.0.0
+**Status:** Ready for use