@brainfish-ai/devdoc 0.1.21

package/renderer/lib/api-docs/parsers/openapi/index.ts

@@ -0,0 +1,171 @@
+/**
+ * OpenAPI Importer
+ * 
+ * Main entry point for importing OpenAPI specifications
+ * Ported from Hoppscotch's openapi/index.ts
+ */
+
+import yaml from 'js-yaml'
+import type { OpenAPI, OpenAPIV2, OpenAPIV3 } from 'openapi-types'
+import type { BrainfishCollection } from '../../types'
+import { objectHasProperty } from '../../utils'
+import { validateOpenAPISpec } from './validator'
+import { dereferenceOpenAPISpec, hasUnresolvedRefs } from './dereferencer'
+import { convertOpenAPIToCollection } from './transformer'
+
+export const OPENAPI_DEREF_ERROR = 'openapi/deref_error' as const
+export const IMPORTER_INVALID_FILE_FORMAT = 'importer/invalid_file_format' as const
+
+/**
+ * Safely parses JSON string
+ */
+function safeParseJSON(str: string): unknown | null {
+  try {
+    return JSON.parse(str)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Safely parses YAML string
+ */
+function safeParseYAML(str: string): unknown | null {
+  try {
+    return yaml.load(str)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Parses OpenAPI document content (JSON or YAML)
+ */
+function parseOpenAPIDocContent(str: string): unknown | null {
+  const jsonResult = safeParseJSON(str)
+  if (jsonResult !== null) {
+    return jsonResult
+  }
+  return safeParseYAML(str)
+}
+
+/**
+ * Checks if document is OpenAPI v2
+ */
+function isOpenAPIV2Document(doc: unknown): doc is OpenAPIV2.Document {
+  return (
+    objectHasProperty(doc, 'swagger') &&
+    typeof doc.swagger === 'string' &&
+    doc.swagger === '2.0'
+  )
+}
+
+/**
+ * Checks if document is OpenAPI v3
+ */
+function isOpenAPIV3Document(
+  doc: unknown
+): doc is OpenAPIV3.Document {
+  return (
+    objectHasProperty(doc, 'openapi') &&
+    typeof doc.openapi === 'string' &&
+    doc.openapi.startsWith('3.')
+  )
+}
+
+/**
+ * Imports OpenAPI specification from file contents or document
+ * 
+ * @param input - OpenAPI document object or array of file contents (strings)
+ * @returns Promise resolving to BrainfishCollection array
+ */
+export async function importOpenAPISpec(
+  input: OpenAPI.Document | string | string[]
+): Promise<BrainfishCollection[]> {
+  let docArr: unknown[]
+
+  // Handle different input types
+  if (typeof input === 'string') {
+    // Single file content string
+    const parsed = parseOpenAPIDocContent(input)
+    if (!parsed) {
+      throw new Error(IMPORTER_INVALID_FILE_FORMAT)
+    }
+    docArr = [parsed]
+  } else if (Array.isArray(input)) {
+    // Array of file content strings
+    docArr = input
+      .map((str) => parseOpenAPIDocContent(str))
+      .filter((doc): doc is unknown => doc !== null)
+    
+    if (docArr.length === 0) {
+      throw new Error(IMPORTER_INVALID_FILE_FORMAT)
+    }
+  } else {
+    // Already a parsed OpenAPI document
+    docArr = [input]
+  }
+
+  // Validate documents
+  const validatedDocs: OpenAPI.Document[] = []
+  
+  for (const docObj of docArr) {
+    try {
+      // More lenient check - if it has paths, we'll try to import it
+      const isValidOpenAPISpec =
+        objectHasProperty(docObj, 'paths') &&
+        (isOpenAPIV2Document(docObj) ||
+          isOpenAPIV3Document(docObj) ||
+          objectHasProperty(docObj, 'info'))
+
+      if (!isValidOpenAPISpec) {
+        throw new Error('INVALID_OPENAPI_SPEC')
+      }
+
+      try {
+        const validatedDoc = await validateOpenAPISpec(docObj)
+        validatedDocs.push(validatedDoc)
+      } catch (validationError) {
+        // If validation fails but it has basic OpenAPI structure, add it anyway
+        if (objectHasProperty(docObj, 'paths')) {
+          validatedDocs.push(docObj as OpenAPI.Document)
+        } else {
+          throw validationError
+        }
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message === 'INVALID_OPENAPI_SPEC') {
+        throw new Error('INVALID_OPENAPI_SPEC')
+      }
+      // Continue with other documents
+      console.warn('Failed to validate document:', err)
+    }
+  }
+
+  if (validatedDocs.length === 0) {
+    throw new Error(IMPORTER_INVALID_FILE_FORMAT)
+  }
+
+  // Dereference documents
+  const dereferencedDocs: OpenAPI.Document[] = []
+
+  for (const docObj of validatedDocs) {
+    try {
+      const dereferencedDoc = await dereferenceOpenAPISpec(docObj)
+      dereferencedDocs.push(dereferencedDoc)
+    } catch {
+      // Check if the document has unresolved references
+      if (hasUnresolvedRefs(docObj)) {
+        console.warn(
+          'Document contains unresolved references which may affect import quality'
+        )
+      }
+
+      // If dereferencing fails, use the original document
+      dereferencedDocs.push(docObj)
+    }
+  }
+
+  // Convert to BrainfishCollections
+  return convertOpenAPIToCollection(dereferencedDocs)
+}

package/renderer/lib/api-docs/parsers/openapi/transformer.ts

@@ -0,0 +1,277 @@
+/**
+ * OpenAPI Transformer
+ * 
+ * Ported from Hoppscotch's openapi/index.ts
+ * Converts OpenAPI Document to BrainfishCollection
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type {
+  OpenAPI,
+  OpenAPIV2,
+  OpenAPIV3,
+} from 'openapi-types'
+import type {
+  BrainfishCollection,
+  BrainfishRESTRequest,
+  BrainfishRESTResponseOriginalRequest,
+} from '../../types'
+import {
+  makeBrainfishCollection,
+  makeBrainfishRESTRequest,
+  makeBrainfishRESTResponseOriginalRequest,
+} from '../../factories'
+import { objectHasProperty, cloneDeep } from '../../utils'
+import { hasUnresolvedRefs } from './dereferencer'
+import {
+  replaceOpenApiPathTemplating,
+  parseOpenAPIParams,
+  parseOpenAPIHeaders,
+  parseOpenAPIVariables,
+  parseOpenAPIResponses,
+  type OpenAPIPathInfoType,
+  type OpenAPIOperationType,
+} from './extractors'
+import { parseOpenAPIBody } from './extractors/body'
+import { parseOpenAPIAuth, extractSecurityHeaders, getDefaultAuth } from './extractors/auth'
+
+/**
+ * Formats an operation name for display
+ * Converts snake_case/kebab-case operationIds to readable Title Case
+ * Prefers summary over operationId if available
+ */
+function formatOperationName(info: any): string {
+  const summary = info.summary?.trim()
+  const operationId = info.operationId?.trim()
+  
+  // Prefer summary as it's usually more human-readable
+  if (summary) {
+    return summary
+  }
+  
+  // If only operationId is available, convert to readable format
+  if (operationId) {
+    return operationId
+      // Replace underscores and hyphens with spaces
+      .replace(/[_-]/g, ' ')
+      // Handle camelCase by adding space before capital letters
+      .replace(/([a-z])([A-Z])/g, '$1 $2')
+      // Capitalize first letter of each word
+      .replace(/\b\w/g, (char: string) => char.toUpperCase())
+      // Clean up multiple spaces
+      .replace(/\s+/g, ' ')
+      .trim()
+  }
+  
+  return 'Untitled Request'
+}
+
+/**
+ * Parses OpenAPI URL from document (v2 or v3)
+ */
+function parseOpenAPIUrl(
+  doc: OpenAPI.Document | OpenAPIV2.Document | OpenAPIV3.Document
+): string {
+  // OpenAPI V2 has host and basePath in document properties
+  if (objectHasProperty(doc, 'swagger')) {
+    const host = (doc as OpenAPIV2.Document).host?.trim() || '<<baseUrl>>'
+    const basePath = (doc as OpenAPIV2.Document).basePath?.trim() || ''
+    return `${host}${basePath}`
+  }
+
+  // OpenAPI V3 has servers array
+  if (objectHasProperty(doc, 'servers')) {
+    const serverUrl = (doc as OpenAPIV3.Document).servers?.[0]?.url
+    return !serverUrl || serverUrl === './' ? '<<baseUrl>>' : serverUrl
+  }
+
+  // Fallback
+  return '<<baseUrl>>'
+}
+
+/**
+ * Converts an OpenAPI path to Brainfish requests
+ */
+function convertPathToBrainfishReqs(
+  doc: OpenAPI.Document,
+  pathName: string,
+  pathObj: OpenAPIPathInfoType
+): Array<{
+  request: BrainfishRESTRequest
+  metadata: {
+    tags: string[]
+  }
+}> {
+  const methods = ['get', 'head', 'post', 'put', 'delete', 'options', 'patch'] as const
+
+  return methods
+    .filter((method) => !!pathObj[method])
+    .map((method) => {
+      const info = pathObj[method]! as OpenAPIOperationType
+      const openAPIUrl = parseOpenAPIUrl(doc)
+      const openAPIPath = replaceOpenApiPathTemplating(pathName)
+
+      const endpoint =
+        openAPIUrl.endsWith('/') && openAPIPath.startsWith('/')
+          ? openAPIUrl + openAPIPath.slice(1)
+          : openAPIUrl + openAPIPath
+
+      const params = parseOpenAPIParams(
+        (info.parameters as any) ?? []
+      )
+      const baseHeaders = parseOpenAPIHeaders(
+        (info.parameters as any) ?? []
+      )
+      
+      // Get the primary auth key (handled by global auth) to exclude from additional headers
+      const defaultAuth = getDefaultAuth(doc)
+      const primaryAuthKey = defaultAuth?.authType === 'api-key' ? defaultAuth.key : undefined
+      
+      // Extract additional security headers (e.g., agent-key when access-token is primary)
+      const securityHeaders = extractSecurityHeaders(doc, info, primaryAuthKey)
+      
+      // Merge headers: base headers + security headers (avoiding duplicates)
+      const existingKeys = new Set(baseHeaders.map(h => h.key.toLowerCase()))
+      const additionalSecurityHeaders = securityHeaders
+        .filter(h => !existingKeys.has(h.key.toLowerCase()))
+        .map(h => ({
+          key: h.key,
+          value: h.value,
+          active: h.active,
+          description: h.description,
+        }))
+      
+      const headers = [...baseHeaders, ...additionalSecurityHeaders]
+      
+      const requestVariables = parseOpenAPIVariables(
+        (info.parameters as any) ?? []
+      )
+      const auth = parseOpenAPIAuth(doc, info)
+      const body = parseOpenAPIBody(doc, info)
+
+      const displayName = formatOperationName(info)
+
+      const originalRequest: BrainfishRESTResponseOriginalRequest =
+        makeBrainfishRESTResponseOriginalRequest({
+          name: displayName,
+          method: method.toUpperCase() as any,
+          endpoint,
+          params,
+          headers,
+          body,
+          auth,
+          requestVariables,
+        })
+
+      const responses = parseOpenAPIResponses(doc, info, originalRequest)
+
+      const request = makeBrainfishRESTRequest({
+        name: displayName,
+        description: (info as any).description ?? null,
+        method: method.toUpperCase() as any,
+        endpoint,
+        params,
+        headers,
+        auth,
+        body,
+        requestVariables,
+        responses,
+        tags: (info as any).tags ?? [],
+      })
+
+      return {
+        request,
+        metadata: {
+          tags: (info as any).tags ?? [],
+        },
+      }
+    })
+}
+
+/**
+ * Converts OpenAPI documents to BrainfishCollections
+ */
+export function convertOpenAPIToCollection(
+  docs: OpenAPI.Document[]
+): BrainfishCollection[] {
+  // Check for unresolved references before conversion
+  for (const doc of docs) {
+    if (hasUnresolvedRefs(doc)) {
+      console.warn(
+        'Document contains unresolved references which may affect import quality'
+      )
+      // Continue anyway to provide a best-effort import
+    }
+  }
+
+  const collections = docs.map((doc) => {
+    const name = doc.info.title
+    const description = doc.info.description ?? null
+
+    // Extract tag descriptions from OpenAPI spec
+    const tagDescriptions: Record<string, string> = {}
+    if ('tags' in doc && Array.isArray(doc.tags)) {
+      doc.tags.forEach((tag: any) => {
+        if (tag.name && tag.description) {
+          tagDescriptions[tag.name] = tag.description
+        }
+      })
+    }
+
+    // Convert all paths to requests
+    const paths = Object.entries(doc.paths ?? {})
+      .map(([pathName, pathObj]) =>
+        convertPathToBrainfishReqs(doc, pathName, pathObj as OpenAPIPathInfoType)
+      )
+      .flat()
+
+    // Organize requests by tags
+    const requestsByTags: Record<string, BrainfishRESTRequest[]> = {}
+    const requestsWithoutTags: BrainfishRESTRequest[] = []
+
+    paths.forEach(({ metadata, request }) => {
+      const tags = metadata.tags
+
+      if (tags.length === 0) {
+        requestsWithoutTags.push(request)
+        return
+      }
+
+      for (const tag of tags) {
+        if (!requestsByTags[tag]) {
+          requestsByTags[tag] = []
+        }
+
+        // Clone request for each tag (request can belong to multiple tags)
+        requestsByTags[tag].push(cloneDeep(request))
+      }
+    })
+
+    // Create folders (collections) for each tag
+    const folders = Object.entries(requestsByTags).map(([tagName, requests]) =>
+      makeBrainfishCollection({
+        name: tagName,
+        description: tagDescriptions[tagName] ?? null,
+        requests,
+        folders: [],
+        variables: [],
+        auth: { authType: 'inherit', authActive: true },
+        headers: [],
+      })
+    )
+
+    // Create main collection
+    return makeBrainfishCollection({
+      name,
+      description,
+      folders,
+      requests: requestsWithoutTags,
+      variables: [],
+      auth: { authType: 'inherit', authActive: true },
+      headers: [],
+    })
+  })
+
+  return collections
+}

package/renderer/lib/api-docs/parsers/openapi/validator.ts

@@ -0,0 +1,31 @@
+/**
+ * OpenAPI Validator
+ * 
+ * Ported from Hoppscotch's openapi-import-worker.ts
+ * Converts Web Worker pattern to direct function calls for Next.js
+ */
+
+import SwaggerParser from '@apidevtools/swagger-parser'
+import type { OpenAPI } from 'openapi-types'
+
+/**
+ * Validates an OpenAPI document using SwaggerParser
+ * 
+ * @param docs - The OpenAPI document to validate
+ * @returns Promise resolving to validated OpenAPI document
+ * @throws Error if validation fails
+ */
+export async function validateOpenAPISpec(
+  docs: unknown
+): Promise<OpenAPI.Document> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const validated = await SwaggerParser.validate(docs as any, {
+      // @ts-expect-error - this is a valid option, but types may not be updated
+      continueOnError: true,
+    })
+    return validated as unknown as OpenAPI.Document
+  } catch {
+    throw new Error('COULD_NOT_VALIDATE')
+  }
+}

package/renderer/lib/api-docs/playground/context.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import { createContext, useContext, useState, useCallback, type ReactNode } from 'react'
+import type { PrefillData } from '@/lib/api-docs/agent/types'
+
+/** Current request payload from the playground */
+export interface CurrentRequestPayload {
+  method: string
+  endpoint: string
+  params: Array<{ key: string; value: string; active: boolean }>
+  headers: Array<{ key: string; value: string; active: boolean }>
+  body: string | null
+  bodyContentType: string | null
+}
+
+interface PlaygroundContextValue {
+  /** Pending prefill data to be applied */
+  pendingPrefill: PrefillData | null
+  /** Set prefill data - will be consumed by playground */
+  setPrefill: (data: PrefillData) => void
+  /** Clear pending prefill after it's been applied */
+  clearPrefill: () => void
+  /** Current request payload from the playground */
+  currentRequestPayload: CurrentRequestPayload | null
+  /** Set current request payload - called by playground when values change */
+  setCurrentRequestPayload: (payload: CurrentRequestPayload | null) => void
+  /** Trigger to send request from agent */
+  triggerSend: boolean
+  /** Call to trigger send from agent */
+  requestSend: () => void
+  /** Clear send trigger after playground handles it */
+  clearSendTrigger: () => void
+}
+
+const PlaygroundContext = createContext<PlaygroundContextValue | null>(null)
+
+export function PlaygroundProvider({ children }: { children: ReactNode }) {
+  const [pendingPrefill, setPendingPrefill] = useState<PrefillData | null>(null)
+  const [currentRequestPayload, setCurrentRequestPayloadState] = useState<CurrentRequestPayload | null>(null)
+  const [triggerSend, setTriggerSend] = useState(false)
+  
+  const setPrefill = useCallback((data: PrefillData) => {
+    setPendingPrefill(data)
+  }, [])
+  
+  const clearPrefill = useCallback(() => {
+    setPendingPrefill(null)
+  }, [])
+  
+  const setCurrentRequestPayload = useCallback((payload: CurrentRequestPayload | null) => {
+    setCurrentRequestPayloadState(payload)
+  }, [])
+  
+  const requestSend = useCallback(() => {
+    setTriggerSend(true)
+  }, [])
+  
+  const clearSendTrigger = useCallback(() => {
+    setTriggerSend(false)
+  }, [])
+  
+  return (
+    <PlaygroundContext.Provider value={{ 
+      pendingPrefill, 
+      setPrefill, 
+      clearPrefill,
+      currentRequestPayload,
+      setCurrentRequestPayload,
+      triggerSend,
+      requestSend,
+      clearSendTrigger,
+    }}>
+      {children}
+    </PlaygroundContext.Provider>
+  )
+}
+
+export function usePlaygroundPrefill() {
+  const context = useContext(PlaygroundContext)
+  if (!context) {
+    throw new Error('usePlaygroundPrefill must be used within a PlaygroundProvider')
+  }
+  return context
+}
+
+export function useCurrentRequestPayload() {
+  const context = useContext(PlaygroundContext)
+  if (!context) {
+    throw new Error('useCurrentRequestPayload must be used within a PlaygroundProvider')
+  }
+  return {
+    currentRequestPayload: context.currentRequestPayload,
+    setCurrentRequestPayload: context.setCurrentRequestPayload,
+  }
+}
+
+export function useSendTrigger() {
+  const context = useContext(PlaygroundContext)
+  if (!context) {
+    throw new Error('useSendTrigger must be used within a PlaygroundProvider')
+  }
+  return {
+    triggerSend: context.triggerSend,
+    requestSend: context.requestSend,
+    clearSendTrigger: context.clearSendTrigger,
+  }
+}

package/renderer/lib/api-docs/playground/navigation-context.tsx

@@ -0,0 +1,124 @@
+'use client'
+
+import { createContext, useContext, useState, useCallback, ReactNode } from 'react'
+
+// Tabs that can be navigated to
+export type PlaygroundTab = 'params' | 'body' | 'headers' | 'auth'
+
+// Fields that can be highlighted
+export type HighlightField = 
+  | { type: 'param'; key?: string }
+  | { type: 'header'; key?: string }
+  | { type: 'body' }
+  | { type: 'auth'; field?: 'apiKey' | 'bearerToken' | 'basicUsername' | 'basicPassword' }
+
+interface PlaygroundNavigationState {
+  /** Currently active tab (controlled externally) */
+  activeTab: PlaygroundTab | null
+  /** Field to highlight */
+  highlightField: HighlightField | null
+  /** Whether to show error styling on highlighted field */
+  showError: boolean
+}
+
+interface PlaygroundNavigationContextType {
+  state: PlaygroundNavigationState
+  /** Navigate to a specific tab */
+  navigateToTab: (tab: PlaygroundTab) => void
+  /** Navigate to tab and highlight a field */
+  navigateAndHighlight: (tab: PlaygroundTab, field?: HighlightField, showError?: boolean) => void
+  /** Clear highlight */
+  clearHighlight: () => void
+  /** Set active tab (called by RequestTabs) */
+  setActiveTab: (tab: PlaygroundTab) => void
+  /** Reset navigation state (called when endpoint changes) */
+  resetNavigation: () => void
+}
+
+const PlaygroundNavigationContext = createContext<PlaygroundNavigationContextType | undefined>(undefined)
+
+export function PlaygroundNavigationProvider({ children }: { children: ReactNode }) {
+  const [state, setState] = useState<PlaygroundNavigationState>({
+    activeTab: null,
+    highlightField: null,
+    showError: false,
+  })
+
+  const navigateToTab = useCallback((tab: PlaygroundTab) => {
+    setState(prev => ({
+      ...prev,
+      activeTab: tab,
+      highlightField: null,
+      showError: false,
+    }))
+  }, [])
+
+  const navigateAndHighlight = useCallback((
+    tab: PlaygroundTab, 
+    field?: HighlightField, 
+    showError: boolean = true
+  ) => {
+    setState({
+      activeTab: tab,
+      highlightField: field || null,
+      showError,
+    })
+    
+    // Auto-clear highlight after a delay
+    if (field) {
+      setTimeout(() => {
+        setState(prev => ({
+          ...prev,
+          highlightField: null,
+          showError: false,
+        }))
+      }, 3000)
+    }
+  }, [])
+
+  const clearHighlight = useCallback(() => {
+    setState(prev => ({
+      ...prev,
+      highlightField: null,
+      showError: false,
+    }))
+  }, [])
+
+  const setActiveTab = useCallback((tab: PlaygroundTab) => {
+    setState(prev => ({
+      ...prev,
+      activeTab: tab,
+    }))
+  }, [])
+
+  const resetNavigation = useCallback(() => {
+    setState({
+      activeTab: null,
+      highlightField: null,
+      showError: false,
+    })
+  }, [])
+
+  return (
+    <PlaygroundNavigationContext.Provider 
+      value={{ 
+        state, 
+        navigateToTab, 
+        navigateAndHighlight, 
+        clearHighlight,
+        setActiveTab,
+        resetNavigation,
+      }}
+    >
+      {children}
+    </PlaygroundNavigationContext.Provider>
+  )
+}
+
+export function usePlaygroundNavigation() {
+  const context = useContext(PlaygroundNavigationContext)
+  if (context === undefined) {
+    throw new Error('usePlaygroundNavigation must be used within a PlaygroundNavigationProvider')
+  }
+  return context
+}