@brainfish-ai/devdoc 0.1.42 → 0.1.44

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

@@ -1,171 +0,0 @@
-/**
- * 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

@@ -1,278 +0,0 @@
-/**
- * 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 ?? [],
-        operationId: (info as any).operationId ?? undefined,
-      })
-
-      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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,107 +0,0 @@
-'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

@@ -1,124 +0,0 @@
-'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
-}