@hustle-together/api-dev-tools 2.0.6 → 3.0.0

package/demo/audio/generate-all-narrations.js

@@ -0,0 +1,516 @@
+#!/usr/bin/env node
+/**
+ * Generate full narration audio with word-level timestamps for ALL voices
+ *
+ * Usage: ELEVENLABS_API_KEY=your_key node generate-all-narrations.js
+ *
+ * Output:
+ *   - narration-adam.mp3 + narration-adam-timing.json
+ *   - narration-mark.mp3 + narration-mark-timing.json
+ *   - narration-hope.mp3 + narration-hope-timing.json
+ *   - narration-creature.mp3 + narration-creature-timing.json
+ *   - narration-gaming.mp3 + narration-gaming-timing.json
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ElevenLabs API configuration
+const API_BASE = 'https://api.elevenlabs.io/v1';
+const MODEL_ID = 'eleven_turbo_v2_5'; // Fast, high-quality model
+
+// Voice configurations - All available voices
+const VOICES = [
+  {
+    id: 'pNInz6obpgDQGcFmaJgB',
+    name: 'adam',
+    displayName: 'Adam',
+    description: 'Deep, professional'
+  },
+  {
+    id: 'UgBBYS2sOqTuMpoF3BR0',
+    name: 'mark',
+    displayName: 'Mark',
+    description: 'Warm, conversational'
+  },
+  {
+    id: 'tnSpp4vdxKPjI9w0GnoV',
+    name: 'hope',
+    displayName: 'Hope',
+    description: 'Bright, energetic'
+  },
+  {
+    id: 'Z7RrOqZFTyLpIlzCgfsp',
+    name: 'creature',
+    displayName: 'Creature',
+    description: 'Unique, character voice'
+  },
+  {
+    id: 'YOq2y2Up4RgXP2HyXjE5',
+    name: 'gaming',
+    displayName: 'Gaming',
+    description: 'Dynamic, enthusiastic'
+  }
+];
+
+// The narration script with section markers and highlight triggers
+const NARRATION_SCRIPT = `
+[SECTION:intro]
+Welcome to Hustle API Dev Tools.
+
+[HIGHLIGHT:#hustleBrand]
+This package enforces a structured workflow for AI-assisted API development.
+
+[HIGHLIGHT:[data-phase="research"]]
+First, you research. No assumptions. No training data. Real documentation.
+
+[HIGHLIGHT:[data-phase="interview"]]
+Then you interview. The AI asks YOU questions with structured options based on what it learned.
+
+[HIGHLIGHT:[data-phase="test"]]
+Next, you write tests first. Red, green, refactor. No implementation without a failing test.
+
+[HIGHLIGHT:[data-phase="code"]]
+Only then do you write code. Minimal. Just enough to pass the tests.
+
+[HIGHLIGHT:[data-phase="docs"]]
+Finally, documentation. Every endpoint documented with real examples and schemas.
+
+The philosophy is simple: Hustle together. Share resources. Build stronger.
+
+[SECTION:problems]
+[HIGHLIGHT:#problems h2]
+Let's talk about the problem. What goes wrong when AI builds APIs without structure?
+
+[HIGHLIGHT:.gap-item:nth-child(1)]
+Gap one: AI doesn't use your exact words. You say Vercel AI Gateway but it searches for Vercel AI SDK. Wrong library. Wrong documentation. Wrong code.
+
+[HIGHLIGHT:.gap-item:nth-child(2)]
+Gap two: AI claims files are updated without proof. It says I've updated the file but there's no git diff. No verification. You're trusting on faith.
+
+[HIGHLIGHT:.gap-item:nth-child(3)]
+Gap three: Skipped tests are accepted. The AI runs tests, some fail, and it moves on. We can fix those later. Those later fixes never come.
+
+[HIGHLIGHT:.gap-item:nth-child(4)]
+Gap four: Tasks marked complete without verification. The AI says Done but the feature doesn't work. No one actually checked.
+
+[HIGHLIGHT:.gap-item:nth-child(5)]
+Gap five: Environment variable mismatch. Tests pass locally but fail in production. The AI used different values than what's actually deployed.
+
+These gaps compound. One wrong assumption leads to another. By the time you notice, you've built on a broken foundation.
+
+[SECTION:solution]
+[HIGHLIGHT:#solution h2]
+The solution is enforcement. Python hooks that intercept every tool call.
+
+[HIGHLIGHT:.solution-grid .solution-card:nth-child(1)]
+PreToolUse hooks run before Claude can write or edit any file. They check: Did you research first? Did you interview the user? Did you write a failing test?
+
+[HIGHLIGHT:.solution-grid .solution-card:nth-child(2)]
+PostToolUse hooks run after research and interviews. They track what was learned. They log every query. They build a paper trail.
+
+[HIGHLIGHT:.solution-grid .solution-card:nth-child(3)]
+The Stop hook runs when Claude tries to mark a task complete. It checks: Are all phases done? Did tests pass? Is documentation updated? If not, blocked.
+
+This isn't about limiting AI. It's about holding it to the same standards we hold ourselves.
+
+[SECTION:workflow]
+[HIGHLIGHT:#workflow h2]
+The workflow has ten phases. Let's walk through each one.
+
+[HIGHLIGHT:.phase-box[data-phase='1']]
+Phase one: Scope. Define what you're building. What's the endpoint? What does it do?
+
+[HIGHLIGHT:.phase-box[data-phase='2']]
+Phase two: Initial research. Use Context7 or web search. Find the real documentation. No guessing.
+
+[HIGHLIGHT:.phase-box[data-phase='3']]
+Phase three: Interview. Ask the user questions with multiple choice options. What provider? What format? What error handling?
+
+[HIGHLIGHT:.phase-box[data-phase='4']]
+Phase four: Deep research. Based on interview answers, research specific APIs and SDKs.
+
+[HIGHLIGHT:.phase-box[data-phase='5']]
+Phase five: Schema design. Define request and response schemas with Zod. Types before code.
+
+[HIGHLIGHT:.phase-box[data-phase='6']]
+Phase six: Environment setup. Check API keys. Verify environment variables. Test connectivity.
+
+[HIGHLIGHT:.phase-box[data-phase='7']]
+Phase seven: Red. Write a failing test. Define what success looks like before writing any implementation.
+
+[HIGHLIGHT:.phase-box[data-phase='8']]
+Phase eight: Green. Write minimal code to pass the test. No extra features. No premature optimization.
+
+[HIGHLIGHT:.phase-box[data-phase='9']]
+Phase nine: Refactor. Clean up the code. Extract utilities. Improve readability. Tests stay green.
+
+[HIGHLIGHT:.phase-box[data-phase='10']]
+Phase ten: Documentation. Update OpenAPI spec. Add to test manifest. Include real examples.
+
+Only when all ten phases are complete can the workflow finish.
+
+[SECTION:installation]
+[HIGHLIGHT:#installation h2]
+Installation takes one command.
+
+[HIGHLIGHT:.install-command]
+Run npx @hustle-together/api-dev-tools. That's it.
+
+The CLI copies slash commands to your .claude/commands folder. Red, green, refactor, cycle, and the API development commands.
+
+It copies Python hooks to .claude/hooks. These are the enforcers. The gatekeepers.
+
+It merges settings into your settings.json. Hooks are registered. Permissions are configured.
+
+And it offers to add the Context7 MCP server for live documentation lookup.
+
+Your project is now enforced. Every API you build follows the workflow.
+
+[SECTION:credits]
+[HIGHLIGHT:#credits h2]
+This project builds on the work of others.
+
+The TDD workflow commands are based on @wbern/claude-instructions by William Bernmalm. The red, green, refactor pattern that makes AI development rigorous.
+
+The interview methodology is inspired by Anthropic's Interviewer approach. Structured discovery before implementation.
+
+And Context7 provides live documentation lookup. Current docs, not stale training data.
+
+Thank you to the Claude Code community. Together, we're making AI development better.
+
+[SECTION:outro]
+[HIGHLIGHT:#intro]
+Hustle API Dev Tools. Research first. Interview second. Test before code. Document everything.
+
+Build together. Share resources. Grow stronger.
+
+Install it now with npx @hustle-together/api-dev-tools.
+`.trim();
+
+/**
+ * Extract plain text from the narration script (remove markers)
+ */
+function extractPlainText(script) {
+  return script
+    .replace(/\[SECTION:[^\]]+\]/g, '')
+    .replace(/\[HIGHLIGHT:[^\]]+\]/g, '')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Parse the script to extract section and highlight markers with their positions
+ */
+function parseMarkers(script) {
+  const markers = [];
+  const lines = script.split('\n');
+  let charPosition = 0;
+  let currentSection = 'intro';
+
+  for (const line of lines) {
+    // Check for section marker
+    const sectionMatch = line.match(/\[SECTION:([^\]]+)\]/);
+    if (sectionMatch) {
+      currentSection = sectionMatch[1];
+      markers.push({
+        type: 'section',
+        id: currentSection,
+        charPosition
+      });
+    }
+
+    // Check for highlight marker
+    const highlightMatch = line.match(/\[HIGHLIGHT:([^\]]+)\]/);
+    if (highlightMatch) {
+      markers.push({
+        type: 'highlight',
+        selector: highlightMatch[1],
+        section: currentSection,
+        charPosition
+      });
+    }
+
+    // Update char position (for plain text, not including markers)
+    const plainLine = line
+      .replace(/\[SECTION:[^\]]+\]/g, '')
+      .replace(/\[HIGHLIGHT:[^\]]+\]/g, '');
+    if (plainLine.trim()) {
+      charPosition += plainLine.length + 1; // +1 for newline
+    }
+  }
+
+  return markers;
+}
+
+/**
+ * Convert character-level timestamps to word-level timestamps
+ */
+function characterToWordTimestamps(alignment) {
+  const words = [];
+  let currentWord = '';
+  let wordStart = null;
+  let wordEnd = null;
+
+  for (let i = 0; i < alignment.characters.length; i++) {
+    const char = alignment.characters[i];
+    const startTime = alignment.character_start_times_seconds[i];
+    const endTime = alignment.character_end_times_seconds[i];
+
+    if (char === ' ' || char === '\n') {
+      if (currentWord) {
+        words.push({
+          word: currentWord,
+          start: wordStart,
+          end: wordEnd,
+          charIndex: i - currentWord.length
+        });
+        currentWord = '';
+        wordStart = null;
+        wordEnd = null;
+      }
+    } else {
+      if (wordStart === null) {
+        wordStart = startTime;
+      }
+      wordEnd = endTime;
+      currentWord += char;
+    }
+  }
+
+  // Don't forget the last word
+  if (currentWord) {
+    words.push({
+      word: currentWord,
+      start: wordStart,
+      end: wordEnd,
+      charIndex: alignment.characters.length - currentWord.length
+    });
+  }
+
+  return words;
+}
+
+/**
+ * Match markers to timestamps based on text position
+ */
+function matchMarkersToTimestamps(markers, wordTimestamps, plainText) {
+  const timedMarkers = [];
+
+  for (const marker of markers) {
+    // Find the word closest to this marker's position
+    let closestWord = wordTimestamps[0];
+    let minDiff = Infinity;
+
+    for (const word of wordTimestamps) {
+      const diff = Math.abs(word.charIndex - marker.charPosition);
+      if (diff < minDiff) {
+        minDiff = diff;
+        closestWord = word;
+      }
+    }
+
+    timedMarkers.push({
+      ...marker,
+      timestamp: closestWord ? closestWord.start : 0
+    });
+  }
+
+  return timedMarkers;
+}
+
+/**
+ * Call ElevenLabs API to generate speech with timestamps
+ */
+async function generateSpeech(text, voiceId, apiKey) {
+  const url = `${API_BASE}/text-to-speech/${voiceId}/with-timestamps`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'xi-api-key': apiKey,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      text,
+      model_id: MODEL_ID,
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+        use_speaker_boost: true
+      }
+    })
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`ElevenLabs API error: ${response.status} - ${error}`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Generate narration for a single voice
+ */
+async function generateForVoice(voice, plainText, markers, apiKey, outputDir) {
+  console.log(`\n=== Generating narration for ${voice.displayName} ===`);
+  console.log(`Voice ID: ${voice.id}`);
+
+  const audioPath = path.join(outputDir, `narration-${voice.name}.mp3`);
+  const timingPath = path.join(outputDir, `narration-${voice.name}-timing.json`);
+
+  try {
+    // Generate speech with timestamps
+    const result = await generateSpeech(plainText, voice.id, apiKey);
+
+    console.log(`Audio generated successfully!`);
+
+    // Decode and save audio
+    const audioBuffer = Buffer.from(result.audio_base64, 'base64');
+    fs.writeFileSync(audioPath, audioBuffer);
+    console.log(`Audio saved: ${audioPath}`);
+    console.log(`Audio size: ${(audioBuffer.length / 1024 / 1024).toFixed(2)} MB`);
+
+    // Convert character timestamps to word timestamps
+    const wordTimestamps = characterToWordTimestamps(result.alignment);
+    console.log(`Extracted ${wordTimestamps.length} word timestamps`);
+
+    // Match markers to timestamps
+    const timedMarkers = matchMarkersToTimestamps(markers, wordTimestamps, plainText);
+
+    // Calculate duration
+    const lastWord = wordTimestamps[wordTimestamps.length - 1];
+    const duration = lastWord ? lastWord.end : 0;
+
+    // Build timing data
+    const timingData = {
+      generated: new Date().toISOString(),
+      voice: voice.displayName,
+      voiceId: voice.id,
+      duration,
+      wordCount: wordTimestamps.length,
+      sections: [],
+      highlights: [],
+      words: wordTimestamps.map(w => ({
+        word: w.word,
+        start: w.start,
+        end: w.end
+      }))
+    };
+
+    // Separate sections and highlights
+    for (const marker of timedMarkers) {
+      if (marker.type === 'section') {
+        timingData.sections.push({
+          id: marker.id,
+          timestamp: marker.timestamp
+        });
+      } else if (marker.type === 'highlight') {
+        timingData.highlights.push({
+          selector: marker.selector,
+          section: marker.section,
+          timestamp: marker.timestamp
+        });
+      }
+    }
+
+    // Save timing data
+    fs.writeFileSync(timingPath, JSON.stringify(timingData, null, 2));
+    console.log(`Timing saved: ${timingPath}`);
+
+    console.log(`Duration: ${duration.toFixed(1)} seconds`);
+    console.log(`Sections: ${timingData.sections.length}`);
+    console.log(`Highlights: ${timingData.highlights.length}`);
+
+    return {
+      voice: voice.displayName,
+      name: voice.name,
+      audioFile: `narration-${voice.name}.mp3`,
+      timingFile: `narration-${voice.name}-timing.json`,
+      duration,
+      wordCount: wordTimestamps.length,
+      audioSize: audioBuffer.length
+    };
+
+  } catch (error) {
+    console.error(`Error generating for ${voice.displayName}: ${error.message}`);
+    return null;
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+
+  if (!apiKey) {
+    console.error('Error: ELEVENLABS_API_KEY environment variable is required');
+    console.error('Usage: ELEVENLABS_API_KEY=your_key node generate-all-narrations.js');
+    process.exit(1);
+  }
+
+  // Parse command line args for specific voice
+  const args = process.argv.slice(2);
+  const specificVoice = args[0];
+
+  const outputDir = __dirname;
+
+  // Extract plain text for TTS
+  const plainText = extractPlainText(NARRATION_SCRIPT);
+  console.log('Plain text extracted:', plainText.substring(0, 100) + '...');
+  console.log(`Total characters: ${plainText.length}`);
+
+  // Parse markers from script
+  const markers = parseMarkers(NARRATION_SCRIPT);
+  console.log(`Found ${markers.length} markers`);
+
+  // Filter voices if specific one requested
+  let voicesToGenerate = VOICES;
+  if (specificVoice) {
+    voicesToGenerate = VOICES.filter(v =>
+      v.name.toLowerCase() === specificVoice.toLowerCase() ||
+      v.displayName.toLowerCase() === specificVoice.toLowerCase()
+    );
+    if (voicesToGenerate.length === 0) {
+      console.error(`Voice "${specificVoice}" not found. Available: ${VOICES.map(v => v.name).join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  console.log(`\nGenerating ${voicesToGenerate.length} voice narration(s)...`);
+
+  const results = [];
+
+  for (const voice of voicesToGenerate) {
+    const result = await generateForVoice(voice, plainText, markers, apiKey, outputDir);
+    if (result) {
+      results.push(result);
+    }
+
+    // Add delay between API calls to avoid rate limiting
+    if (voicesToGenerate.indexOf(voice) < voicesToGenerate.length - 1) {
+      console.log('\nWaiting 5 seconds before next voice...');
+      await new Promise(resolve => setTimeout(resolve, 5000));
+    }
+  }
+
+  // Write manifest
+  const manifestPath = path.join(outputDir, 'voices-manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify({
+    generated: new Date().toISOString(),
+    voices: results
+  }, null, 2));
+
+  console.log('\n=== SUMMARY ===');
+  console.log(`Generated ${results.length}/${voicesToGenerate.length} voice narrations`);
+  console.log(`Manifest: ${manifestPath}`);
+
+  for (const result of results) {
+    console.log(`  ${result.voice}: ${result.duration.toFixed(1)}s, ${(result.audioSize / 1024 / 1024).toFixed(2)} MB`);
+  }
+}
+
+main();

package/demo/audio/generate-voice-previews.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Generate voice preview clips with different ElevenLabs voices
+ *
+ * Usage: ELEVENLABS_API_KEY=your_key node generate-voice-previews.js
+ *
+ * Output: Creates preview MP3 files in ./previews/ directory
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ElevenLabs API configuration
+const API_BASE = 'https://api.elevenlabs.io/v1';
+const MODEL_ID = 'eleven_turbo_v2_5'; // Fast, high-quality model
+
+// Voice configurations
+const VOICES = [
+  {
+    id: 'UgBBYS2sOqTuMpoF3BR0',
+    name: 'mark',
+    displayName: 'Mark'
+  },
+  {
+    id: 'tnSpp4vdxKPjI9w0GnoV',
+    name: 'hope',
+    displayName: 'Hope'
+  },
+  {
+    id: 'Z7RrOqZFTyLpIlzCgfsp',
+    name: 'creature',
+    displayName: 'Creature'
+  },
+  {
+    id: 'YOq2y2Up4RgXP2HyXjE5',
+    name: 'gaming',
+    displayName: 'Gaming'
+  }
+];
+
+// Preview text - short snippet that showcases the voice
+const PREVIEW_TEXT = `Welcome to Hustle API Dev Tools. Build APIs the right way. Research first. Interview second. Test before code. Document everything.`;
+
+/**
+ * Generate speech for a single voice
+ */
+async function generateVoicePreview(voice, text, apiKey) {
+  const url = `${API_BASE}/text-to-speech/${voice.id}`;
+
+  console.log(`Generating preview for ${voice.displayName}...`);
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'xi-api-key': apiKey,
+      'Content-Type': 'application/json',
+      'Accept': 'audio/mpeg'
+    },
+    body: JSON.stringify({
+      text,
+      model_id: MODEL_ID,
+      voice_settings: {
+        stability: 0.5,
+        similarity_boost: 0.75,
+        style: 0.3,
+        use_speaker_boost: true
+      }
+    })
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`ElevenLabs API error for ${voice.name}: ${response.status} - ${error}`);
+  }
+
+  // Get audio as buffer
+  const arrayBuffer = await response.arrayBuffer();
+  return Buffer.from(arrayBuffer);
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  const apiKey = process.env.ELEVENLABS_API_KEY;
+
+  if (!apiKey) {
+    console.error('Error: ELEVENLABS_API_KEY environment variable is required');
+    console.error('Usage: ELEVENLABS_API_KEY=your_key node generate-voice-previews.js');
+    process.exit(1);
+  }
+
+  const outputDir = path.join(__dirname, 'previews');
+
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  console.log('Generating voice previews...');
+  console.log(`Text: "${PREVIEW_TEXT}"`);
+  console.log('');
+
+  const results = [];
+
+  for (const voice of VOICES) {
+    try {
+      const audioBuffer = await generateVoicePreview(voice, PREVIEW_TEXT, apiKey);
+      const outputPath = path.join(outputDir, `preview-${voice.name}.mp3`);
+      fs.writeFileSync(outputPath, audioBuffer);
+
+      const sizeMB = (audioBuffer.length / 1024 / 1024).toFixed(2);
+      console.log(`  ✓ ${voice.displayName}: ${outputPath} (${sizeMB} MB)`);
+
+      results.push({
+        voice: voice.displayName,
+        id: voice.id,
+        file: `preview-${voice.name}.mp3`,
+        size: audioBuffer.length
+      });
+    } catch (error) {
+      console.error(`  ✗ ${voice.displayName}: ${error.message}`);
+    }
+  }
+
+  // Write manifest
+  const manifestPath = path.join(outputDir, 'manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify({
+    generated: new Date().toISOString(),
+    text: PREVIEW_TEXT,
+    voices: results
+  }, null, 2));
+
+  console.log('');
+  console.log(`=== Done ===`);
+  console.log(`Generated ${results.length}/${VOICES.length} voice previews`);
+  console.log(`Manifest: ${manifestPath}`);
+}
+
+main();