@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/cli/api-reference-tool.js

@@ -0,0 +1,368 @@
+/**
+ * api-reference-tool.js
+ *
+ * Provides an OpenAI-compatible tool definition and handler that fetches
+ * real API reference documentation from the internet.  Designed to be used
+ * with local LLMs that support tool/function calling so that context writers
+ * can look up accurate payload formats, field names, and auth mechanisms
+ * instead of hallucinating them.
+ */
+
+// ---------------------------------------------------------------------------
+// Known API documentation sources
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps service names to documentation URLs.
+ * Each entry can have:
+ *   - `openapi`  — OpenAPI/Swagger spec URL (JSON or YAML)
+ *   - `docs`     — Human-readable docs index URL
+ *   - `topics`   — Map of topic keywords → specific doc URLs
+ */
+// No hardcoded URLs — all API references fetched dynamically via Context7.
+// This avoids stale/broken URLs and ensures consistent, up-to-date documentation.
+const SERVICE_REGISTRY = {};
+
+// Aliases: normalize common service name variants
+const SERVICE_ALIASES = {
+  // Twilio variants
+  'twilio-whatsapp': 'twilio',
+  'twilio-sms': 'twilio',
+  // Meta/WhatsApp variants (model uses many forms)
+  'meta': 'whatsapp',
+  'meta-cloud-api': 'whatsapp',
+  'meta cloud api': 'whatsapp',
+  'whatsapp-cloud': 'whatsapp',
+  'whatsapp-business': 'whatsapp',
+  'whatsapp cloud api': 'whatsapp',
+  'whatsapp business api': 'whatsapp',
+  // Express variants
+  'express.js': 'express',
+  'expressjs': 'express',
+  // AWS variants
+  's3': 'aws-s3',
+  'amazon-s3': 'aws-s3',
+  // React ecosystem
+  'react-query': 'tanstack-query',
+  'tanstack query': 'tanstack-query',
+  '@tanstack/react-query': 'tanstack-query',
+};
+
+// ---------------------------------------------------------------------------
+// Dynamic discovery via Context7 (Upstash)
+// ---------------------------------------------------------------------------
+
+const CONTEXT7_BASE = 'https://context7.com/api/v2';
+
+/**
+ * Fetch topic-specific documentation from Context7.
+ * Two-step: resolve library ID → fetch docs.
+ * Works without API key; optional CONTEXT7_API_KEY env var for higher rate limits.
+ * @returns {{ libraryId: string, text: string } | null}
+ */
+async function fetchFromContext7(serviceName, topic) {
+  const headers = {};
+  const apiKey = process.env.CONTEXT7_API_KEY;
+  if (apiKey) headers['Authorization'] = `Bearer ${apiKey}`;
+
+  // Step 1: Resolve library ID
+  const searchUrl = `${CONTEXT7_BASE}/libs/search?query=${encodeURIComponent(serviceName)}`;
+  const searchResult = await fetchWithLimit(searchUrl, 10_000, headers);
+  if (!searchResult.ok) return null;
+
+  let libraryId;
+  try {
+    const data = JSON.parse(searchResult.body);
+    const libs = data.libraries || data;
+    if (!Array.isArray(libs) || libs.length === 0) return null;
+    // Pick highest trust match — require trust >= 5 to avoid fuzzy noise
+    // (Context7 never returns empty results; garbage queries get fuzzy matches)
+    const best = libs.sort((a, b) => (b.trust || 0) - (a.trust || 0))[0];
+    if ((best.trust || 0) < 5) return null;
+    libraryId = best.id; // format: "owner/repo" e.g. "stripe/stripe-node"
+  } catch { return null; }
+
+  // Step 2: Fetch topic-specific documentation
+  const contextUrl = `${CONTEXT7_BASE}/context?libraryId=${encodeURIComponent(libraryId)}&query=${encodeURIComponent(topic)}&type=txt&tokenLimit=5000`;
+  const contextResult = await fetchWithLimit(contextUrl, 12_000, headers);
+  if (!contextResult.ok) return null;
+
+  const text = contextResult.body?.trim();
+  if (!text || text.length < 50) return null;
+
+  return { libraryId, text };
+}
+
+// ---------------------------------------------------------------------------
+// Tool definition (OpenAI function-calling format)
+// ---------------------------------------------------------------------------
+
+export const API_REFERENCE_TOOL = {
+  type: 'function',
+  function: {
+    name: 'fetch_api_reference',
+    description:
+      'Fetch API reference documentation for any external service or API. ' +
+      'Supports thousands of libraries and APIs — documentation is discovered automatically. ' +
+      'Use this when you need accurate payload formats, field names, authentication mechanisms, ' +
+      'endpoint signatures, or webhook specifications.',
+    parameters: {
+      type: 'object',
+      properties: {
+        service: {
+          type: 'string',
+          description:
+            'Service or API name (e.g. "twilio", "stripe", "prisma", "shopify", "express", "supabase")',
+        },
+        topic: {
+          type: 'string',
+          description:
+            'Specific topic to look up (e.g. "webhook-payload", "authentication", "send-message", "signature-verification", "rate-limit")',
+        },
+      },
+      required: ['service', 'topic'],
+    },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Fetch helper with timeout and size limit
+// ---------------------------------------------------------------------------
+
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 512_000; // 500 KB — enough for most doc pages
+
+async function fetchWithLimit(url, timeoutMs = FETCH_TIMEOUT_MS, extraHeaders = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, {
+      signal: controller.signal,
+      headers: { 'Accept': 'text/html, application/json, text/plain, */*', ...extraHeaders },
+    });
+    if (!resp.ok) {
+      return { ok: false, error: `HTTP ${resp.status} ${resp.statusText}` };
+    }
+    const contentType = resp.headers.get('content-type') || '';
+    const buffer = await resp.arrayBuffer();
+    const body = new TextDecoder().decode(buffer.slice(0, MAX_BODY_BYTES));
+    return { ok: true, body, contentType, truncated: buffer.byteLength > MAX_BODY_BYTES };
+  } catch (err) {
+    return { ok: false, error: err.name === 'AbortError' ? 'Request timed out' : err.message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Content extractors
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract relevant text from an HTML page — strips tags, scripts, styles,
+ * and collapses whitespace.  Returns a readable text summary.
+ */
+function extractTextFromHTML(html, maxChars = 8000) {
+  let text = html;
+  // Remove script, style, nav, footer, header blocks
+  text = text.replace(/<(script|style|nav|footer|header|aside|svg)\b[^>]*>[\s\S]*?<\/\1>/gi, ' ');
+  // Remove HTML comments
+  text = text.replace(/<!--[\s\S]*?-->/g, ' ');
+  // Convert common block elements to newlines
+  text = text.replace(/<\/(p|div|h[1-6]|li|tr|br|hr)\s*>/gi, '\n');
+  text = text.replace(/<(br|hr)\s*\/?>/gi, '\n');
+  // Strip remaining tags
+  text = text.replace(/<[^>]+>/g, ' ');
+  // Decode basic HTML entities
+  text = text.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, ' ');
+  // Collapse whitespace
+  text = text.replace(/[ \t]+/g, ' ').replace(/\n[ \t]+/g, '\n').replace(/\n{3,}/g, '\n\n');
+  return text.trim().slice(0, maxChars);
+}
+
+/**
+ * Extract a relevant section from an OpenAPI spec JSON for a given topic.
+ */
+function extractFromOpenAPI(specJson, topic) {
+  const topicLower = topic.toLowerCase();
+  const lines = [];
+  const paths = specJson.paths || {};
+
+  // Find paths matching the topic keywords
+  const keywords = topicLower.split(/[-_\s]+/);
+  const matchingPaths = Object.entries(paths).filter(([pathStr]) => {
+    const pathLower = pathStr.toLowerCase();
+    return keywords.some(kw => kw.length >= 3 && pathLower.includes(kw));
+  });
+
+  // Limit to first 5 matching paths
+  for (const [pathStr, methods] of matchingPaths.slice(0, 5)) {
+    lines.push(`\n### ${pathStr}`);
+    for (const [method, spec] of Object.entries(methods)) {
+      if (typeof spec !== 'object' || !spec) continue;
+      lines.push(`**${method.toUpperCase()}** — ${spec.summary || spec.description || ''}`);
+      // Request body schema
+      const reqBody = spec.requestBody?.content;
+      if (reqBody) {
+        for (const [contentType, media] of Object.entries(reqBody)) {
+          lines.push(`- Content-Type: ${contentType}`);
+          if (media.schema?.properties) {
+            const props = Object.entries(media.schema.properties).slice(0, 15);
+            for (const [prop, propSpec] of props) {
+              const req = (media.schema.required || []).includes(prop) ? ' (required)' : '';
+              lines.push(`  - ${prop}: ${propSpec.type || 'any'}${req} — ${propSpec.description || ''}`);
+            }
+          }
+        }
+      }
+      // Response schema summary
+      const responses = spec.responses || {};
+      const successResp = responses['200'] || responses['201'] || responses['204'];
+      if (successResp) {
+        lines.push(`- Success: ${successResp.description || 'OK'}`);
+      }
+    }
+  }
+
+  if (lines.length === 0) {
+    // Fallback: show info section
+    const info = specJson.info || {};
+    return `API: ${info.title || 'Unknown'} (v${info.version || '?'})\n` +
+      `${info.description || ''}\n\n` +
+      `No paths matching topic "${topic}" found. Available paths (first 20):\n` +
+      Object.keys(paths).slice(0, 20).map(p => `- ${p}`).join('\n');
+  }
+
+  const info = specJson.info || {};
+  return `API: ${info.title || 'Unknown'} (v${info.version || '?'})\n` +
+    `Topic: ${topic}\n` +
+    lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Tool handler
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle a fetch_api_reference tool call.
+ * @param {{ service: string, topic: string }} args - Tool call arguments
+ * @returns {Promise<string>} The fetched API reference text
+ */
+export async function handleFetchApiReference({ service, topic }) {
+  const serviceLower = (service || '').toLowerCase().trim();
+  const topicLower = (topic || '').toLowerCase().trim();
+
+  // Resolve aliases
+  const resolvedService = SERVICE_ALIASES[serviceLower] || serviceLower;
+  const registry = SERVICE_REGISTRY[resolvedService];
+
+  // Tier 0: Curated registry (fastest, best quality for known services)
+  if (registry) {
+    // 1. Try topic-specific URL first
+    const topicUrl = findTopicUrl(registry.topics, topicLower);
+    if (topicUrl) {
+      console.log(`[DEBUG] API reference tool: fetching ${resolvedService}/${topicLower} from ${topicUrl}`);
+      const result = await fetchWithLimit(topicUrl);
+      if (result.ok) {
+        const text = extractTextFromHTML(result.body);
+        if (text.length > 100) {
+          return `## ${resolvedService} — ${topic}\nSource: ${topicUrl}\n\n${text}`;
+        }
+      } else {
+        console.log(`[DEBUG] API reference fetch failed: ${result.error}`);
+      }
+    }
+
+    // 2. Try OpenAPI spec for structured data
+    if (registry.openapi) {
+      console.log(`[DEBUG] API reference tool: fetching OpenAPI spec for ${resolvedService}`);
+      const specResult = await fetchWithLimit(registry.openapi, 20_000);
+      if (specResult.ok) {
+        try {
+          const spec = JSON.parse(specResult.body);
+          const extracted = extractFromOpenAPI(spec, topicLower);
+          if (extracted) {
+            return `## ${resolvedService} — ${topic} (from OpenAPI spec)\n\n${extracted}`;
+          }
+        } catch {
+          // Not valid JSON or truncated — fall through
+        }
+      }
+    }
+
+    // 3. Fall back to general docs page
+    if (registry.docs) {
+      console.log(`[DEBUG] API reference tool: falling back to general docs for ${resolvedService}`);
+      const docsResult = await fetchWithLimit(registry.docs);
+      if (docsResult.ok) {
+        const text = extractTextFromHTML(docsResult.body, 4000);
+        return `## ${resolvedService} — general documentation\nSource: ${registry.docs}\n\n${text}\n\n` +
+          `Note: Could not find specific docs for topic "${topic}". Above is the general API docs page.`;
+      }
+    }
+  }
+
+  // Tier 1: Dynamic discovery via Context7
+  console.log(`[DEBUG] API reference: "${service}" not in registry, trying Context7`);
+  const ctx7 = await fetchFromContext7(serviceLower, topicLower);
+  if (ctx7) {
+    return `## ${service} — ${topic} (via Context7: ${ctx7.libraryId})\n\n${ctx7.text}`;
+  }
+
+  return `Could not find API documentation for "${service}/${topic}". ` +
+    `The service may not have indexed documentation available. ` +
+    `Use your training knowledge as a fallback.`;
+}
+
+/**
+ * Find the best matching topic URL from the topics map.
+ */
+function findTopicUrl(topics, topicLower) {
+  if (!topics) return null;
+
+  // Exact match
+  if (topics[topicLower]) return topics[topicLower];
+
+  // Partial match — find topic key that shares keywords with the query
+  const queryWords = topicLower.split(/[-_\s]+/);
+  let bestMatch = null;
+  let bestOverlap = 0;
+
+  for (const [key, url] of Object.entries(topics)) {
+    const keyWords = key.split(/[-_\s]+/);
+    const overlap = queryWords.filter(w => keyWords.includes(w)).length;
+    if (overlap > bestOverlap) {
+      bestOverlap = overlap;
+      bestMatch = url;
+    }
+  }
+
+  return bestOverlap > 0 ? bestMatch : null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports for provider integration
+// ---------------------------------------------------------------------------
+
+/**
+ * All tools available for context generation.
+ * Providers can pass this array in the `tools` parameter of chat completions.
+ */
+export const CONTEXT_GENERATION_TOOLS = [API_REFERENCE_TOOL];
+
+/**
+ * Dispatch a tool call by name.
+ * @param {string} name - Tool function name
+ * @param {Object} args - Tool call arguments (parsed JSON)
+ * @returns {Promise<string>} Tool result text
+ */
+export async function dispatchToolCall(name, args) {
+  if (name === 'fetch_api_reference') {
+    return handleFetchApiReference(args);
+  }
+  return `Unknown tool: ${name}`;
+}
+
+// Exported for unit testing
+export { findTopicUrl, extractFromOpenAPI, extractTextFromHTML, fetchFromContext7 };

package/cli/build-docs.js

@@ -25,6 +25,13 @@ export class DocumentationBuilder {
     return fs.existsSync(this.docsDir);
   }
 
+  /**
+   * Check if synced project docs directory exists inside documentation
+   */
+  hasProjectDocs() {
+    return fs.existsSync(path.join(this.docsDir, 'project'));
+  }
+
   /**
    * Get documentation server port from avc.json config
    * Returns default port 4173 if not configured
@@ -40,7 +47,7 @@ export class DocumentationBuilder {
       const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
       return config.settings?.documentation?.port || 4173;
     } catch (error) {
-      console.warn(`⚠️  Could not read port from avc.json: ${error.message}`);
+      console.warn(`Could not read port from avc.json: ${error.message}`);
       return 4173;
     }
   }
@@ -197,13 +204,9 @@ export class DocumentationBuilder {
     const port = this.getPort();
 
     try {
-      // Build the documentation asynchronously to avoid blocking
-      await execAsync('npx vitepress build', {
-        cwd: this.docsDir
-      });
-
-      // Start the preview server
-      const serverProcess = spawn('npx', ['vitepress', 'preview', '--port', String(port)], {
+      // Start the dev server — no initial build needed, vitepress dev builds on-demand
+      // and hot-reloads the browser whenever source .md files change
+      const serverProcess = spawn('npx', ['vitepress', 'dev', '--port', String(port)], {
         cwd: this.docsDir,
         stdio: 'pipe'
       });
@@ -256,6 +259,22 @@ export class DocumentationBuilder {
     }
   }
 
+  /**
+   * Ensure ignoreDeadLinks: true is present in the VitePress config.
+   * Patches existing project configs that were created before this option was added.
+   */
+  _ensureIgnoreDeadLinks() {
+    const configPath = path.join(this.docsDir, '.vitepress', 'config.mts');
+    if (!fs.existsSync(configPath)) return;
+    const content = fs.readFileSync(configPath, 'utf8');
+    if (content.includes('ignoreDeadLinks')) return;
+    const patched = content.replace(
+      /defineConfig\(\{/,
+      'defineConfig({\n  ignoreDeadLinks: true,'
+    );
+    fs.writeFileSync(configPath, patched, 'utf8');
+  }
+
   /**
    * Build documentation without starting server
    */
@@ -264,6 +283,8 @@ export class DocumentationBuilder {
       throw new Error('Documentation not found. Run /init first to create documentation structure.');
     }
 
+    this._ensureIgnoreDeadLinks();
+
     try {
       // Build asynchronously to avoid blocking the event loop
       await execAsync('npx vitepress build', {