npm - @hustle-together/api-dev-tools - Versions diffs - 1.7.1 → 1.9.0 - Mend

@hustle-together/api-dev-tools 1.7.1 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +30 -2
package/commands/api-interview.md +245 -121
package/demo/workflow-demo.html +144 -115
package/hooks/enforce-interview.py +204 -33
package/hooks/track-tool-use.py +72 -2
package/package.json +1 -1

package/demo/workflow-demo.html CHANGED Viewed

@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>API Dev Tools - Interactive Workflow Demo</title>
+  <title>API Dev Tools - Interview-Driven API Development Demo</title>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/ScrollTrigger.min.js"></script>
   <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/TextPlugin.min.js"></script>
@@ -957,18 +957,18 @@
     <div class="ascii-border">
       <h1 id="titleText">INTERVIEW-DRIVEN API DEVELOPMENT</h1>
       <div class="package-name" id="packageName">@hustle-together/api-dev-tools</div>
-      <div class="version" id="versionText">v1.6.0</div>
+      <div class="version" id="versionText">v1.9.0</div>
       <p class="tagline">"Interview first, test first, document always"<span class="cursor"></span></p>
       <div class="intro-text">
         <p>
           This tool helps you build APIs the right way by <strong>enforcing a structured workflow</strong>.
-          Instead of letting AI assistants jump straight to code, it ensures they first understand
-          what you actually want, research the right libraries, and follow test-driven development.
+          Instead of letting AI assistants jump straight to code, it ensures they first research,
+          then ask YOU questions with <strong>multiple-choice options</strong> based on what they found.
         </p>
         <p style="margin-top: 20px;">
           <strong>Scroll down</strong> to see how it works, step by step, using a real example:
-          building an AI chat API with the Vercel AI SDK.
+          creating a <strong>Brandfetch API endpoint</strong> from scratch.
         </p>
       </div>
@@ -1253,31 +1253,30 @@
   <section id="walkthrough">
     <div class="ascii-border">
       <h2>REAL EXAMPLE</h2>
-      <h3>Building the AI Chat API</h3>
+      <h3>Creating a Brandfetch API</h3>
       <div class="explanation">
-        <div class="explanation-title">A Real Story</div>
+        <div class="explanation-title">The Complete Flow</div>
         <p>
-          Let's walk through what actually happened when we built an AI chat API
-          using the <strong>Vercel AI SDK</strong>. This shows both <strong>what worked</strong>
-          and <strong>what the system caught</strong> that would have been missed otherwise.
+          Let's walk through what happens when you run <code>/api-create brandfetch</code>.
+          This shows the full interview-driven workflow, from research to implementation,
+          with <strong>structured questions based on real documentation</strong>.
         </p>
       </div>
       <div class="walkthrough-step">
         <div class="walkthrough-header">
           <div class="walkthrough-num">1</div>
-          <div class="walkthrough-title">User Request</div>
+          <div class="walkthrough-title">You Run the Command</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            The user asked for an AI chat API with multi-provider support
-            using a <strong>single API key via Vercel AI Gateway</strong>.
+            You type the command to create a new Brandfetch API endpoint.
+            The workflow immediately begins.
           </div>
           <div class="walkthrough-example">
-            <div class="label">User Said:</div>
-            "I want to use OpenAI, Anthropic, Google, Perplexity - all <strong>via Vercel AI Gateway</strong>
-            so I only need one API key instead of four."
+            <div class="label">Your Command:</div>
+            /api-create brandfetch
           </div>
         </div>
       </div>
@@ -1285,19 +1284,19 @@
       <div class="walkthrough-step">
         <div class="walkthrough-header">
           <div class="walkthrough-num">2</div>
-          <div class="walkthrough-title">Research Phase</div>
+          <div class="walkthrough-title">Research Phase (Automatic)</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            System forced the AI to research before writing any code.
-            It fetched live documentation from Context7 and searched the web.
+            Before asking any questions, the AI is <strong>required</strong> to research.
+            It fetches live documentation from Context7 and searches the web.
           </div>
           <div class="walkthrough-example">
-            <div class="label">Research Sources Logged:</div>
-            - Context7: Vercel AI SDK docs<br>
-            - WebSearch: GPT-5.1 models<br>
-            - WebSearch: Gemini 3 Pro<br>
-            - Context7: generateText, streamText functions
+            <div class="label">Research Logged to State File:</div>
+            - Context7: Brandfetch SDK docs → found logos, colors, fonts endpoints<br>
+            - WebSearch: "Brandfetch API rate limits 2025" → 5 req/second<br>
+            - WebSearch: "Brandfetch API response format" → JSON with asset URLs<br>
+            - Context7: Authentication → Bearer token required
           </div>
         </div>
       </div>
@@ -1305,75 +1304,87 @@
       <div class="walkthrough-step">
         <div class="walkthrough-header">
           <div class="walkthrough-num">3</div>
-          <div class="walkthrough-title">Interview Phase</div>
+          <div class="walkthrough-title">Structured Interview (Based on Research)</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            AI asked 6 questions about requirements.
-            User specified: providers, capabilities, streaming modes, default models.
+            Now the AI asks YOU questions - but with <strong>multiple-choice options</strong>
+            derived from what it actually found in the documentation. No guessing!
           </div>
           <div class="walkthrough-example">
-            <div class="label">Interview Results Recorded:</div>
-            - Providers: OpenAI, Anthropic, Google, Perplexity <strong>via Vercel AI Gateway</strong><br>
-            - Capabilities: Chat, image, speech, transcription, embeddings<br>
-            - Default model: Budget tier for cost efficiency
+            <div class="label">Question 1 (with options from research):</div>
+            "What's the primary purpose of this endpoint?"<br><br>
+            <strong>1.</strong> Brand lookup (get brand by domain)<br>
+            <strong>2.</strong> Logo extraction (get logo assets)<br>
+            <strong>3.</strong> Color palette extraction<br>
+            <strong>4.</strong> Full brand kit (all assets)<br>
+            <strong>5.</strong> Type something else...<br><br>
+            <em>You select: "4. Full brand kit (all assets)"</em>
           </div>
         </div>
       </div>
-      <div class="walkthrough-step" style="border-color: var(--white);">
+      <div class="walkthrough-step">
         <div class="walkthrough-header">
-          <div class="walkthrough-num">!</div>
-          <div class="walkthrough-title">Gap Detected</div>
+          <div class="walkthrough-num">4</div>
+          <div class="walkthrough-title">More Questions, All Tracked</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            The AI wrote the implementation using <strong>direct provider SDKs</strong>
-            instead of the Vercel AI Gateway. The verification hook caught this mismatch!
+            Each question is tracked with your answer. These decisions are stored
+            in the state file and <strong>injected during implementation</strong> to ensure consistency.
           </div>
           <div class="walkthrough-example">
-            <div class="label">What Happened:</div>
-            Interview said: "via Vercel AI Gateway"<br>
-            Code used: @ai-sdk/openai, @ai-sdk/anthropic (direct calls)<br><br>
-            <strong>DETECTED:</strong> Implementation doesn't match interview requirements!
+            <div class="label">Decisions Captured:</div>
+            • Purpose: full_brand_kit<br>
+            • Response Format: JSON with asset URLs<br>
+            • API Key Handling: server environment variables only<br>
+            • Error Handling: detailed (error, code, details)<br>
+            • Required Params: domain (string)<br>
+            • Optional Params: include_colors, include_fonts
           </div>
         </div>
       </div>
       <div class="walkthrough-step">
         <div class="walkthrough-header">
-          <div class="walkthrough-num">4</div>
-          <div class="walkthrough-title">Fixed Implementation</div>
+          <div class="walkthrough-num">5</div>
+          <div class="walkthrough-title">Implementation (With Decision Reminders)</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            After the gap was caught, the code was updated to actually use
-            <strong>@ai-sdk/gateway</strong> with a single API key.
+            When the AI writes code, the hook <strong>injects your decisions</strong> as a reminder.
+            This ensures the implementation matches what you actually asked for.
           </div>
           <div class="walkthrough-example">
-            <div class="label">Corrected Code:</div>
-            import { gateway } from '@ai-sdk/gateway';<br>
-            const client = createAIClient({ apiKey: AI_GATEWAY_API_KEY });
+            <div class="label">Injected on Every Write:</div>
+            ✅ Interview complete. REMEMBER THE USER'S DECISIONS:<br><br>
+            • Purpose: Full brand kit (all assets)<br>
+            • Response Format: JSON with asset URLs<br>
+            • API Key Handling: server environment variables only<br>
+            • Error Handling: detailed (error, code, details)<br><br>
+            <em>Your implementation MUST align with these choices.</em>
           </div>
         </div>
       </div>
       <div class="walkthrough-step">
         <div class="walkthrough-header">
-          <div class="walkthrough-num">5</div>
-          <div class="walkthrough-title">Final Result</div>
+          <div class="walkthrough-num">6</div>
+          <div class="walkthrough-title">TDD + Final Result</div>
         </div>
         <div class="walkthrough-content">
           <div class="walkthrough-desc">
-            Complete implementation with 160 tests, proper documentation,
-            and code that actually matches what the user asked for.
+            Tests are written first (TDD), then implementation, then docs.
+            Everything is tracked and verified against your interview decisions.
           </div>
           <div class="walkthrough-example">
             <div class="label">Files Created:</div>
-            - src/lib/ai/client.ts (gateway implementation)<br>
-            - src/lib/ai/schemas.ts (Zod validation)<br>
-            - src/app/api/v2/ai/chat/route.ts<br>
-            - 160 tests passing
+            - src/lib/schemas/brandfetch.ts (Zod validation)<br>
+            - src/lib/__tests__/brandfetch.test.ts (tests first!)<br>
+            - src/app/api/v2/brandfetch/route.ts<br>
+            - Interview doc: src/v2/docs/endpoints/brandfetch.md<br>
+            - All tests passing ✓
           </div>
         </div>
       </div>
@@ -1386,14 +1397,14 @@
   <section id="demo">
     <div class="ascii-border">
       <h2>LIVE SIMULATION</h2>
-      <h3>See the Hooks in Action</h3>
+      <h3>The Interview Flow</h3>
       <div class="explanation">
-        <div class="explanation-title">Watch the Enforcement</div>
+        <div class="explanation-title">Structured Questions in Action</div>
         <p>
-          This simulates what happens during a Claude Code session.
-          Notice how actions get <strong>BLOCKED</strong> until prerequisites are met,
-          and how everything gets <strong>LOGGED</strong> for verification.
+          This simulates the interview phase. Notice how the AI uses
+          <strong>AskUserQuestion with options</strong> based on research findings.
+          Your answers are captured and used throughout implementation.
         </p>
       </div>
@@ -1402,70 +1413,80 @@
           <div class="terminal-dot"></div>
           <div class="terminal-dot"></div>
           <div class="terminal-dot"></div>
-          <div class="terminal-title">claude-code session</div>
+          <div class="terminal-title">claude-code session: /api-create brandfetch</div>
         </div>
-        <div class="terminal-comment" data-step="0">// AI tries to write code immediately</div>
+        <div class="terminal-comment" data-step="0">// Step 1: Research phase starts automatically</div>
         <div class="terminal-line" data-step="1">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">Write src/app/api/v2/ai/chat/route.ts</span>
+          <span class="terminal-command">mcp__context7__get-library-docs("brandfetch")</span>
         </div>
         <div class="terminal-line terminal-result" data-step="2">
-          <span class="terminal-blocked">BLOCKED: Research phase not complete.<br>Run /api-research first to fetch live documentation.</span>
-        </div>
-        <div class="terminal-comment" data-step="3">// AI does research - gets logged</div>
-        <div class="terminal-line" data-step="4">
-          <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">WebSearch "Vercel AI Gateway documentation"</span>
-        </div>
-        <div class="terminal-line terminal-result" data-step="5">
-          <span class="terminal-logged">[LOGGED] Research source added to api-dev-state.json</span>
+          <span class="terminal-logged">[LOGGED] Context7 source: brandfetch SDK documentation</span>
         </div>
-        <div class="terminal-comment" data-step="6">// AI tries to write code again</div>
-        <div class="terminal-line" data-step="7">
+        <div class="terminal-line" data-step="3">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">Write src/app/api/v2/ai/chat/route.ts</span>
+          <span class="terminal-command">WebSearch "Brandfetch API endpoints 2025"</span>
         </div>
-        <div class="terminal-line terminal-result" data-step="8">
-          <span class="terminal-blocked">BLOCKED: Interview phase not complete.<br>Use AskUserQuestion to understand requirements.</span>
+        <div class="terminal-line terminal-result" data-step="4">
+          <span class="terminal-logged">[LOGGED] WebSearch: found /v2/brands, /v2/search, /v2/logos</span>
         </div>
-        <div class="terminal-comment" data-step="9">// AI asks user a question</div>
-        <div class="terminal-line" data-step="10">
+        <div class="terminal-comment" data-step="5">// Step 2: Interview with structured options (from research)</div>
+        <div class="terminal-line" data-step="6">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">AskUserQuestion "Which providers should this support?"</span>
+          <span class="terminal-command">AskUserQuestion(<br>
+            &nbsp;&nbsp;question: "What's the primary purpose?"<br>
+            &nbsp;&nbsp;options: [<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "lookup", label: "Brand lookup by domain"},<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "logos", label: "Logo extraction only"},<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "full_kit", label: "Full brand kit"},<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "custom", label: "Type something..."}<br>
+            &nbsp;&nbsp;]<br>
+          )</span>
         </div>
-        <div class="terminal-line terminal-result" data-step="11">
-          <span class="terminal-logged">[TRACKED] Question logged with tool_used: true</span>
+        <div class="terminal-line terminal-result" data-step="7">
+          <span class="terminal-allowed">[USER] Selected: "full_kit"<br>[TRACKED] decisions.purpose = "full_kit"</span>
         </div>
-        <div class="terminal-comment" data-step="12">// After 3+ questions, AI can write code</div>
-        <div class="terminal-line" data-step="13">
+        <div class="terminal-line" data-step="8">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">Write src/app/api/v2/ai/chat/route.ts</span>
+          <span class="terminal-command">AskUserQuestion(<br>
+            &nbsp;&nbsp;question: "How should API keys be handled?"<br>
+            &nbsp;&nbsp;options: [<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "server_only", label: "Server env vars only"},<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "header", label: "Custom header override"},<br>
+            &nbsp;&nbsp;&nbsp;&nbsp;{value: "both", label: "Both methods"},<br>
+            &nbsp;&nbsp;]<br>
+          )</span>
         </div>
-        <div class="terminal-line terminal-result" data-step="14">
-          <span class="terminal-allowed">ALLOWED: All prerequisites met. Writing file...</span>
+        <div class="terminal-line terminal-result" data-step="9">
+          <span class="terminal-allowed">[USER] Selected: "server_only"<br>[TRACKED] decisions.api_key_handling = "server_only"</span>
         </div>
-        <div class="terminal-comment" data-step="15">// AI tries to stop before finishing all phases</div>
-        <div class="terminal-line" data-step="16">
+        <div class="terminal-comment" data-step="10">// Step 3: Interview complete, now writing code</div>
+        <div class="terminal-line" data-step="11">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">[STOP - end conversation]</span>
+          <span class="terminal-command">Write src/app/api/v2/brandfetch/route.ts</span>
         </div>
-        <div class="terminal-line terminal-result" data-step="17">
-          <span class="terminal-blocked">BLOCKED: Required phases incomplete.<br>- TDD Green phase (not started)<br>- Documentation (not started)</span>
+        <div class="terminal-line terminal-result" data-step="12">
+          <span class="terminal-allowed">✅ Interview complete. REMEMBER THE USER'S DECISIONS:<br>
+          &nbsp;&nbsp;• Purpose: full_kit<br>
+          &nbsp;&nbsp;• API Key Handling: server_only<br>
+          ALLOWED: Writing file...</span>
         </div>
-        <div class="terminal-comment" data-step="18">// After completing all phases</div>
-        <div class="terminal-line" data-step="19">
+        <div class="terminal-comment" data-step="13">// Decisions are injected on EVERY write operation</div>
+        <div class="terminal-line" data-step="14">
           <span class="terminal-prompt">claude></span>
-          <span class="terminal-command">[STOP - all phases complete]</span>
+          <span class="terminal-command">Write src/lib/schemas/brandfetch.ts</span>
         </div>
-        <div class="terminal-line terminal-result" data-step="20">
-          <span class="terminal-allowed">ALLOWED: Workflow complete!<br>Files created: 12 | Tests: 160 passing</span>
+        <div class="terminal-line terminal-result" data-step="15">
+          <span class="terminal-allowed">✅ REMEMBER THE USER'S DECISIONS:<br>
+          &nbsp;&nbsp;• Purpose: full_kit<br>
+          &nbsp;&nbsp;• API Key Handling: server_only<br>
+          ALLOWED: Writing schema file...</span>
         </div>
       </div>
     </div>
@@ -1483,33 +1504,41 @@
         <div class="explanation-title">Everything Gets Recorded</div>
         <p>
           All progress is saved to <code>.claude/api-dev-state.json</code>.
-          This creates an <strong>audit trail</strong> of what was researched, what questions
-          were asked, and what was built. You can always check the current state.
+          This includes <strong>your interview decisions</strong>, which are injected
+          during implementation to ensure consistency.
         </p>
       </div>
       <div class="json-viewer">
         <div class="json-line"><span class="json-key">{</span></div>
-        <div class="json-line">  <span class="json-key">"endpoint":</span> <span class="json-string">"ai-foundation"</span>,</div>
-        <div class="json-line">  <span class="json-key">"library":</span> <span class="json-string">"Vercel AI SDK"</span>,</div>
+        <div class="json-line">  <span class="json-key">"endpoint":</span> <span class="json-string">"brandfetch"</span>,</div>
         <div class="json-line">  <span class="json-key">"phases":</span> {</div>
-        <div class="json-line highlight">    <span class="json-key">"research_initial":</span> { <span class="json-key">"status":</span> <span class="json-value">"complete"</span> }, <span class="json-comment">// Logged 6 sources</span></div>
+        <div class="json-line highlight">    <span class="json-key">"research_initial":</span> {</div>
+        <div class="json-line highlight">      <span class="json-key">"status":</span> <span class="json-value">"complete"</span>,</div>
+        <div class="json-line highlight">      <span class="json-key">"sources":</span> [<span class="json-string">"context7"</span>, <span class="json-string">"websearch"</span>, <span class="json-string">"websearch"</span>]</div>
+        <div class="json-line highlight">    },</div>
         <div class="json-line highlight">    <span class="json-key">"interview":</span> {</div>
         <div class="json-line highlight">      <span class="json-key">"status":</span> <span class="json-value">"complete"</span>,</div>
-        <div class="json-line highlight">      <span class="json-key">"user_question_count":</span> <span class="json-value">6</span> <span class="json-comment">// Actual questions asked</span></div>
+        <div class="json-line highlight">      <span class="json-key">"user_question_count":</span> <span class="json-value">6</span>,</div>
+        <div class="json-line highlight">      <span class="json-key">"structured_question_count":</span> <span class="json-value">5</span>, <span class="json-comment">// Questions with options</span></div>
+        <div class="json-line highlight">      <span class="json-key">"decisions":</span> { <span class="json-comment">// YOUR CHOICES - INJECTED ON WRITES</span></div>
+        <div class="json-line highlight">        <span class="json-key">"purpose":</span> {<span class="json-key">"value":</span> <span class="json-string">"full_kit"</span>},</div>
+        <div class="json-line highlight">        <span class="json-key">"api_key_handling":</span> {<span class="json-key">"value":</span> <span class="json-string">"server_only"</span>},</div>
+        <div class="json-line highlight">        <span class="json-key">"response_format":</span> {<span class="json-key">"value":</span> <span class="json-string">"json"</span>},</div>
+        <div class="json-line highlight">        <span class="json-key">"error_handling":</span> {<span class="json-key">"value":</span> <span class="json-string">"detailed"</span>}</div>
+        <div class="json-line highlight">      },</div>
+        <div class="json-line highlight">      <span class="json-key">"questions":</span> [</div>
+        <div class="json-line highlight">        {<span class="json-key">"tool_used":</span> <span class="json-value">true</span>, <span class="json-key">"has_options":</span> <span class="json-value">true</span>, <span class="json-key">"user_response":</span> <span class="json-string">"full_kit"</span>},</div>
+        <div class="json-line highlight">        <span class="json-comment">// ... more questions tracked</span></div>
+        <div class="json-line highlight">      ]</div>
         <div class="json-line highlight">    },</div>
-        <div class="json-line highlight">    <span class="json-key">"tdd_red":</span> { <span class="json-key">"status":</span> <span class="json-value">"complete"</span>, <span class="json-key">"tests_count":</span> <span class="json-value">146</span> },</div>
-        <div class="json-line highlight">    <span class="json-key">"tdd_green":</span> { <span class="json-key">"status":</span> <span class="json-value">"complete"</span> }</div>
-        <div class="json-line">  },</div>
-        <div class="json-line">  <span class="json-key">"verification":</span> {</div>
-        <div class="json-line">    <span class="json-key">"all_sources_fetched":</span> <span class="json-value">true</span>,</div>
-        <div class="json-line">    <span class="json-key">"all_tests_passing":</span> <span class="json-value">true</span></div>
+        <div class="json-line">    <span class="json-key">"tdd_red":</span> { <span class="json-key">"status":</span> <span class="json-value">"complete"</span> },</div>
+        <div class="json-line">    <span class="json-key">"tdd_green":</span> { <span class="json-key">"status":</span> <span class="json-value">"complete"</span> }</div>
         <div class="json-line">  },</div>
         <div class="json-line">  <span class="json-key">"files_created":</span> [</div>
-        <div class="json-line">    <span class="json-string">"src/lib/ai/client.ts"</span>,</div>
-        <div class="json-line">    <span class="json-string">"src/lib/ai/schemas.ts"</span>,</div>
-        <div class="json-line">    <span class="json-string">"src/app/api/v2/ai/chat/route.ts"</span>,</div>
-        <div class="json-line">    <span class="json-string">"... and 9 more"</span></div>
+        <div class="json-line">    <span class="json-string">"src/lib/schemas/brandfetch.ts"</span>,</div>
+        <div class="json-line">    <span class="json-string">"src/app/api/v2/brandfetch/route.ts"</span>,</div>
+        <div class="json-line">    <span class="json-string">"src/v2/docs/endpoints/brandfetch.md"</span></div>
         <div class="json-line">  ]</div>
         <div class="json-line"><span class="json-key">}</span></div>
       </div>
@@ -1604,7 +1633,7 @@
       <div class="made-with">
         <p>Made for developers who want AI assistants<br>that actually follow instructions.</p>
         <p style="margin-top: 20px; color: var(--dark-grey);">
-          v1.6.0 | MIT License<br>
+          v1.9.0 | MIT License<br>
           "Interview first, test first, document always"
         </p>
       </div>