@brainfish-ai/devdoc 0.1.42 → 0.1.43

package/renderer/lib/api-docs/agent/indexer.ts

@@ -1,323 +0,0 @@
-/**
- * Collection Indexer
- * Builds a searchable index of all API endpoints for the AI agent
- */
-
-import type { BrainfishCollection, BrainfishRESTRequest, FormDataKeyValue } from '../types'
-import type { EndpointIndex } from './types'
-
-/**
- * Find a request by ID in the collection (recursive)
- */
-export function findRequestById(
-  collection: BrainfishCollection, 
-  id: string
-): BrainfishRESTRequest | null {
-  // Check direct requests
-  const found = collection.requests.find(r => r.id === id)
-  if (found) return found
-  
-  // Check folders recursively
-  for (const folder of collection.folders) {
-    const request = findRequestById(folder, id)
-    if (request) return request
-  }
-  return null
-}
-
-/**
- * Format full request details for AI context
- * Returns a structured object with all the information the AI needs
- */
-export function formatRequestForAI(request: BrainfishRESTRequest): {
-  id: string
-  name: string
-  method: string
-  path: string
-  description: string | null
-  parameters: Array<{ name: string; description: string; required: boolean }>
-  headers: Array<{ name: string; description: string; required: boolean }>
-  auth: { type: string; details?: Record<string, unknown> }
-  body: {
-    required: boolean
-    contentType: string | null
-    schema: string | Array<{ key: string; isFile: boolean }> | null
-    example?: string
-  }
-  responses: Array<{
-    code: number
-    status: string
-    description?: string
-    example?: string
-  }>
-} {
-  // Format parameters
-  const parameters = request.params.map(p => ({
-    name: p.key,
-    description: p.description || '',
-    required: p.active,
-  }))
-
-  // Format headers
-  const headers = request.headers
-    .filter(h => !['Content-Type', 'Authorization'].includes(h.key)) // Filter out auto-managed headers
-    .map(h => ({
-      name: h.key,
-      description: h.description || '',
-      required: h.active,
-    }))
-
-  // Format auth
-  const auth: { type: string; details?: Record<string, unknown> } = {
-    type: request.auth.authType,
-  }
-  if (request.auth.authType === 'api-key') {
-    auth.details = {
-      keyName: request.auth.key,
-      location: request.auth.addTo === 'HEADERS' ? 'header' : 'query',
-    }
-  } else if (request.auth.authType === 'bearer') {
-    auth.details = { headerFormat: 'Bearer <token>' }
-  } else if (request.auth.authType === 'basic') {
-    auth.details = { format: 'Basic base64(username:password)' }
-  }
-
-  // Format body
-  const body: {
-    required: boolean
-    contentType: string | null
-    schema: string | Array<{ key: string; isFile: boolean }> | null
-    example?: string
-  } = {
-    required: request.body.body !== null,
-    contentType: request.body.contentType,
-    schema: null,
-  }
-
-  if (request.body.body !== null) {
-    if (Array.isArray(request.body.body)) {
-      // Form data
-      body.schema = (request.body.body as FormDataKeyValue[]).map(item => ({
-        key: item.key,
-        isFile: item.isFile,
-      }))
-    } else if (typeof request.body.body === 'string') {
-      // JSON or raw body - try to parse and extract schema info
-      try {
-        const parsed = JSON.parse(request.body.body)
-        body.example = request.body.body
-        // Extract field names and types from example
-        body.schema = JSON.stringify(
-          extractSchemaFromExample(parsed),
-          null,
-          2
-        )
-      } catch {
-        // Raw string body
-        body.example = request.body.body.slice(0, 500)
-        body.schema = 'raw text'
-      }
-    }
-  }
-
-  // Format responses
-  const responses = Object.entries(request.responses).map(([name, resp]) => ({
-    code: resp.code,
-    status: resp.status,
-    description: name !== resp.status ? name : undefined,
-    example: resp.body ? resp.body.slice(0, 500) : undefined,
-  }))
-
-  return {
-    id: request.id,
-    name: request.name,
-    method: request.method,
-    path: request.endpoint,
-    description: request.description,
-    parameters,
-    headers,
-    auth,
-    body,
-    responses,
-  }
-}
-
-/**
- * Extract a simple schema from a JSON example
- */
-function extractSchemaFromExample(obj: unknown, depth = 0): unknown {
-  if (depth > 3) return '...' // Prevent deep recursion
-  
-  if (obj === null) return 'null'
-  if (typeof obj === 'string') return 'string'
-  if (typeof obj === 'number') return 'number'
-  if (typeof obj === 'boolean') return 'boolean'
-  
-  if (Array.isArray(obj)) {
-    if (obj.length === 0) return '[]'
-    return [extractSchemaFromExample(obj[0], depth + 1)]
-  }
-  
-  if (typeof obj === 'object') {
-    const result: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = extractSchemaFromExample(value, depth + 1)
-    }
-    return result
-  }
-  
-  return 'unknown'
-}
-
-/**
- * Recursively extracts all requests from a collection and its nested folders
- */
-function extractRequests(
-  collection: BrainfishCollection,
-  parentTags: string[] = []
-): { request: BrainfishRESTRequest; tags: string[] }[] {
-  const results: { request: BrainfishRESTRequest; tags: string[] }[] = []
-  
-  // Add requests from this level
-  for (const request of collection.requests) {
-    results.push({
-      request,
-      tags: [...parentTags, collection.name].filter(t => t !== 'root'),
-    })
-  }
-  
-  // Recursively process folders
-  for (const folder of collection.folders) {
-    const folderResults = extractRequests(folder, [...parentTags, collection.name])
-    results.push(...folderResults)
-  }
-  
-  return results
-}
-
-/**
- * Builds an endpoint index for AI context
- */
-export function buildEndpointIndex(collection: BrainfishCollection): EndpointIndex[] {
-  const allRequests = extractRequests(collection)
-  
-  return allRequests.map(({ request, tags }) => ({
-    id: request.id,
-    name: request.name,
-    method: request.method,
-    path: request.endpoint,
-    description: request.description,
-    parameters: request.params.map(p => p.key),
-    hasBody: request.body.body !== null,
-    tags: [...new Set([...tags, ...request.tags])].filter(Boolean),
-  }))
-}
-
-/**
- * Formats the endpoint index as a string for the AI system prompt
- */
-export function formatEndpointsForContext(endpoints: EndpointIndex[]): string {
-  return endpoints
-    .map((ep, i) => {
-      const params = ep.parameters.length > 0 
-        ? `\n   Parameters: ${ep.parameters.join(', ')}` 
-        : ''
-      const tags = ep.tags.length > 0 
-        ? `\n   Tags: ${ep.tags.join(', ')}` 
-        : ''
-      
-      return `${i + 1}. [${ep.method}] ${ep.path}
-   ID: ${ep.id}
-   Name: ${ep.name}${ep.description ? `\n   Description: ${ep.description.slice(0, 200)}${ep.description.length > 200 ? '...' : ''}` : ''}${params}${tags}`
-    })
-    .join('\n\n')
-}
-
-/**
- * Fuzzy/BM25-like search over endpoints
- */
-export function searchEndpoints(
-  endpoints: EndpointIndex[],
-  query: string,
-  method?: string
-): EndpointIndex[] {
-  // Tokenize query
-  const queryTokens = query.toLowerCase().split(/\s+/).filter(t => t.length > 1)
-  const queryLower = query.toLowerCase()
-  
-  // Score each endpoint
-  const scoredEndpoints = endpoints
-    .filter(ep => !method || ep.method === method)
-    .map(ep => {
-      let score = 0
-      const nameLower = ep.name.toLowerCase()
-      const pathLower = ep.path.toLowerCase()
-      const descLower = (ep.description || '').toLowerCase()
-      const tagsLower = ep.tags.map(t => t.toLowerCase())
-      const paramsLower = ep.parameters.map(p => p.toLowerCase())
-      
-      // Exact phrase match (highest priority)
-      if (nameLower.includes(queryLower)) score += 100
-      if (pathLower.includes(queryLower)) score += 80
-      if (descLower.includes(queryLower)) score += 60
-      
-      // Token matching
-      for (const token of queryTokens) {
-        // Name matches (most important)
-        if (nameLower === token) score += 50
-        else if (nameLower.startsWith(token)) score += 30
-        else if (nameLower.includes(token)) score += 20
-        
-        // Path segment matches
-        const pathParts = pathLower.split('/').filter(Boolean)
-        if (pathParts.some(part => part === token)) score += 40
-        if (pathParts.some(part => part.startsWith(token))) score += 25
-        if (pathParts.some(part => part.includes(token))) score += 15
-        
-        // Description matches
-        if (descLower.includes(token)) score += 15
-        
-        // Tag matches
-        if (tagsLower.some(tag => tag === token)) score += 30
-        if (tagsLower.some(tag => tag.includes(token))) score += 15
-        
-        // Parameter matches
-        if (paramsLower.some(param => param === token)) score += 25
-        if (paramsLower.some(param => param.includes(token))) score += 10
-        
-        // HTTP method relevance
-        if (ep.method.toLowerCase() === token) score += 20
-        
-        // Fuzzy matching for similar words
-        const allWords = [nameLower, ...pathParts, ...tagsLower, ...paramsLower]
-        for (const word of allWords) {
-          if (word.length > 2 && token.length > 2) {
-            const minLen = Math.min(word.length, token.length)
-            let matches = 0
-            for (let i = 0; i < minLen; i++) {
-              if (word[i] === token[i]) matches++
-            }
-            if (matches / minLen > 0.7) score += 5
-          }
-        }
-      }
-      
-      return { ...ep, score }
-    })
-  
-  // Filter and sort by score
-  return scoredEndpoints
-    .filter(ep => ep.score > 0)
-    .sort((a, b) => b.score - a.score)
-    .slice(0, 10)
-    .map(ep => ({
-      id: ep.id,
-      name: ep.name,
-      method: ep.method,
-      path: ep.path,
-      description: ep.description,
-      parameters: ep.parameters,
-      hasBody: ep.hasBody,
-      tags: ep.tags,
-    }))
-}

package/renderer/lib/api-docs/agent/spec-summary.ts

@@ -1,335 +0,0 @@
-import type { BrainfishCollection, BrainfishRESTRequest, HTTPMethod } from '../types'
-
-interface EndpointSummary {
-  name: string
-  method: HTTPMethod
-  path: string
-  description: string | null
-  tags: string[]
-  hasAuth: boolean
-  hasBody: boolean
-  paramCount: number
-}
-
-interface ResourceGroup {
-  name: string
-  endpoints: EndpointSummary[]
-  operations: {
-    create: number
-    read: number
-    update: number
-    delete: number
-  }
-}
-
-interface AuthSummary {
-  types: string[]
-  primaryMethod: string | null
-}
-
-interface APISummary {
-  name: string
-  description: string | null
-  baseUrl: string | null
-  totalEndpoints: number
-  authSummary: AuthSummary
-  resourceGroups: ResourceGroup[]
-  commonPatterns: string[]
-  suggestedUseCases: string[]
-}
-
-/**
- * Recursively collect all requests from a collection
- */
-function collectAllRequests(collection: BrainfishCollection): BrainfishRESTRequest[] {
-  const requests: BrainfishRESTRequest[] = [...collection.requests]
-  
-  for (const folder of collection.folders) {
-    requests.push(...collectAllRequests(folder))
-  }
-  
-  return requests
-}
-
-/**
- * Extract base URL from endpoints
- */
-function extractBaseUrl(requests: BrainfishRESTRequest[]): string | null {
-  if (requests.length === 0) return null
-  
-  const firstEndpoint = requests[0].endpoint
-  try {
-    const url = new URL(firstEndpoint)
-    return `${url.protocol}//${url.host}`
-  } catch {
-    // Try to extract from path pattern
-    const match = firstEndpoint.match(/^(https?:\/\/[^\/]+)/)
-    return match ? match[1] : null
-  }
-}
-
-/**
- * Analyze authentication patterns across endpoints
- */
-function analyzeAuth(requests: BrainfishRESTRequest[]): AuthSummary {
-  const authTypes = new Set<string>()
-  const authCounts: Record<string, number> = {}
-  
-  for (const req of requests) {
-    const type = req.auth.authType
-    if (type !== 'none' && type !== 'inherit') {
-      authTypes.add(type)
-      authCounts[type] = (authCounts[type] || 0) + 1
-    }
-  }
-  
-  // Find primary auth method (most common)
-  let primaryMethod: string | null = null
-  let maxCount = 0
-  for (const [type, count] of Object.entries(authCounts)) {
-    if (count > maxCount) {
-      maxCount = count
-      primaryMethod = type
-    }
-  }
-  
-  return {
-    types: Array.from(authTypes),
-    primaryMethod,
-  }
-}
-
-/**
- * Group endpoints by resource/tag
- */
-function groupByResource(requests: BrainfishRESTRequest[]): ResourceGroup[] {
-  const groups: Map<string, EndpointSummary[]> = new Map()
-  
-  for (const req of requests) {
-    // Use first tag, or extract from path, or use "Other"
-    let groupName = req.tags[0] || extractResourceFromPath(req.endpoint) || 'Other'
-    groupName = groupName.charAt(0).toUpperCase() + groupName.slice(1)
-    
-    const summary: EndpointSummary = {
-      name: req.name,
-      method: req.method,
-      path: req.endpoint,
-      description: req.description,
-      tags: req.tags,
-      hasAuth: req.auth.authType !== 'none',
-      hasBody: req.body.body !== null,
-      paramCount: req.params.filter(p => p.active).length,
-    }
-    
-    if (!groups.has(groupName)) {
-      groups.set(groupName, [])
-    }
-    groups.get(groupName)!.push(summary)
-  }
-  
-  // Convert to array and calculate operations
-  return Array.from(groups.entries()).map(([name, endpoints]) => ({
-    name,
-    endpoints,
-    operations: {
-      create: endpoints.filter(e => e.method === 'POST').length,
-      read: endpoints.filter(e => e.method === 'GET').length,
-      update: endpoints.filter(e => e.method === 'PUT' || e.method === 'PATCH').length,
-      delete: endpoints.filter(e => e.method === 'DELETE').length,
-    },
-  }))
-}
-
-/**
- * Extract resource name from path
- */
-function extractResourceFromPath(path: string): string | null {
-  // Remove base URL and extract first path segment
-  const pathMatch = path.match(/\/api\/v?\d*\/?([^\/]+)/) || path.match(/\/([^\/]+)/)
-  if (pathMatch) {
-    return pathMatch[1].replace(/[-_]/g, ' ')
-  }
-  return null
-}
-
-/**
- * Detect common API patterns
- */
-function detectPatterns(groups: ResourceGroup[]): string[] {
-  const patterns: string[] = []
-  
-  // Check for RESTful CRUD patterns
-  const hasCRUD = groups.some(g => 
-    g.operations.create > 0 && 
-    g.operations.read > 0 && 
-    (g.operations.update > 0 || g.operations.delete > 0)
-  )
-  if (hasCRUD) {
-    patterns.push('RESTful CRUD operations')
-  }
-  
-  // Check for authentication endpoints
-  const hasAuthEndpoints = groups.some(g => 
-    g.name.toLowerCase().includes('auth') ||
-    g.endpoints.some(e => 
-      e.name.toLowerCase().includes('login') ||
-      e.name.toLowerCase().includes('token') ||
-      e.name.toLowerCase().includes('session')
-    )
-  )
-  if (hasAuthEndpoints) {
-    patterns.push('Authentication/Authorization flows')
-  }
-  
-  // Check for search/filter patterns
-  const hasSearch = groups.some(g =>
-    g.endpoints.some(e => 
-      e.name.toLowerCase().includes('search') ||
-      e.name.toLowerCase().includes('filter') ||
-      e.paramCount > 2
-    )
-  )
-  if (hasSearch) {
-    patterns.push('Search and filtering capabilities')
-  }
-  
-  // Check for batch operations
-  const hasBatch = groups.some(g =>
-    g.endpoints.some(e => 
-      e.name.toLowerCase().includes('batch') ||
-      e.name.toLowerCase().includes('bulk')
-    )
-  )
-  if (hasBatch) {
-    patterns.push('Batch/bulk operations')
-  }
-  
-  // Check for webhooks
-  const hasWebhooks = groups.some(g =>
-    g.name.toLowerCase().includes('webhook') ||
-    g.endpoints.some(e => e.name.toLowerCase().includes('webhook'))
-  )
-  if (hasWebhooks) {
-    patterns.push('Webhook integrations')
-  }
-  
-  return patterns
-}
-
-/**
- * Generate suggested use cases based on resources
- */
-function generateUseCases(groups: ResourceGroup[], _apiName: string): string[] {
-  const useCases: string[] = []
-  
-  for (const group of groups.slice(0, 5)) { // Top 5 groups
-    if (group.operations.create > 0) {
-      useCases.push(`Create and manage ${group.name.toLowerCase()}`)
-    }
-    if (group.operations.read > 0 && group.endpoints.length > 1) {
-      useCases.push(`List and retrieve ${group.name.toLowerCase()} data`)
-    }
-  }
-  
-  // Add generic use cases based on patterns
-  const hasAuth = groups.some(g => g.name.toLowerCase().includes('auth'))
-  if (hasAuth) {
-    useCases.push('Implement user authentication flow')
-  }
-  
-  return useCases.slice(0, 6) // Limit to 6 use cases
-}
-
-/**
- * Generate a comprehensive API summary from a collection
- */
-export function generateAPISummary(collection: BrainfishCollection): APISummary {
-  const requests = collectAllRequests(collection)
-  const groups = groupByResource(requests)
-  const patterns = detectPatterns(groups)
-  
-  return {
-    name: collection.name,
-    description: collection.description,
-    baseUrl: extractBaseUrl(requests),
-    totalEndpoints: requests.length,
-    authSummary: analyzeAuth(requests),
-    resourceGroups: groups,
-    commonPatterns: patterns,
-    suggestedUseCases: generateUseCases(groups, collection.name),
-  }
-}
-
-/**
- * Format API summary as a string for the LLM system prompt
- */
-export function formatAPISummaryForPrompt(summary: APISummary): string {
-  const sections: string[] = []
-  
-  // Header
-  sections.push(`# API Overview: ${summary.name}`)
-  if (summary.description) {
-    sections.push(summary.description)
-  }
-  
-  // Stats
-  sections.push(`\n## Quick Stats`)
-  sections.push(`- Total Endpoints: ${summary.totalEndpoints}`)
-  if (summary.baseUrl) {
-    sections.push(`- Base URL: ${summary.baseUrl}`)
-  }
-  
-  // Auth
-  if (summary.authSummary.types.length > 0) {
-    sections.push(`- Authentication: ${summary.authSummary.types.join(', ')}`)
-    if (summary.authSummary.primaryMethod) {
-      sections.push(`- Primary Auth Method: ${summary.authSummary.primaryMethod}`)
-    }
-  }
-  
-  // Resources
-  sections.push(`\n## API Resources (${summary.resourceGroups.length} groups)`)
-  for (const group of summary.resourceGroups) {
-    const ops = []
-    if (group.operations.create) ops.push(`${group.operations.create} create`)
-    if (group.operations.read) ops.push(`${group.operations.read} read`)
-    if (group.operations.update) ops.push(`${group.operations.update} update`)
-    if (group.operations.delete) ops.push(`${group.operations.delete} delete`)
-    
-    sections.push(`\n### ${group.name} (${group.endpoints.length} endpoints)`)
-    if (ops.length > 0) {
-      sections.push(`Operations: ${ops.join(', ')}`)
-    }
-    
-    // List key endpoints (up to 5 per group)
-    const keyEndpoints = group.endpoints.slice(0, 5)
-    for (const ep of keyEndpoints) {
-      const authIndicator = ep.hasAuth ? '🔐' : ''
-      sections.push(`- [${ep.method}] ${ep.name} ${authIndicator}`)
-      if (ep.description) {
-        sections.push(`  ${ep.description.slice(0, 100)}${ep.description.length > 100 ? '...' : ''}`)
-      }
-    }
-    if (group.endpoints.length > 5) {
-      sections.push(`  ... and ${group.endpoints.length - 5} more`)
-    }
-  }
-  
-  // Patterns
-  if (summary.commonPatterns.length > 0) {
-    sections.push(`\n## Common Patterns`)
-    for (const pattern of summary.commonPatterns) {
-      sections.push(`- ${pattern}`)
-    }
-  }
-  
-  // Use cases
-  if (summary.suggestedUseCases.length > 0) {
-    sections.push(`\n## Suggested Use Cases`)
-    for (const useCase of summary.suggestedUseCases) {
-      sections.push(`- ${useCase}`)
-    }
-  }
-  
-  return sections.join('\n')
-}