@brainfish-ai/devdoc 0.1.41 → 0.1.43

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

@@ -0,0 +1,227 @@
+/**
+ * Recursively collect all requests from a collection
+ */ function collectAllRequests(collection) {
+    const requests = [
+        ...collection.requests
+    ];
+    for (const folder of collection.folders){
+        requests.push(...collectAllRequests(folder));
+    }
+    return requests;
+}
+/**
+ * Extract base URL from endpoints
+ */ function extractBaseUrl(requests) {
+    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) {
+    const authTypes = new Set();
+    const authCounts = {};
+    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 = 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) {
+    const groups = 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 = {
+            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) {
+    // 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) {
+    const patterns = [];
+    // 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, _apiName) {
+    const useCases = [];
+    for (const group of groups.slice(0, 5)){
+        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) {
+    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) {
+    const sections = [];
+    // 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');
+}

package/renderer/lib/api-docs/agent/types.js

@@ -0,0 +1,5 @@
+/**
+ * Agent Mode Types
+ * Types for the AI-powered API documentation assistant
+ */ // Navigation action
+export { };

package/renderer/lib/api-docs/auth/auth-context.js

@@ -0,0 +1,157 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useState, useEffect, useCallback, useRef } from 'react';
+import { authStorage, fetchDeviceId } from './auth-storage';
+const AuthContext = /*#__PURE__*/ createContext(null);
+const DEFAULT_AUTH = {
+    authType: 'none',
+    authActive: true
+};
+export function AuthProvider({ children }) {
+    const [globalAuth, setGlobalAuthState] = useState(null);
+    const [isInitialized, setIsInitialized] = useState(false);
+    const [specSchemes, setSpecSchemes] = useState([]);
+    const [specDefaultAuth, setSpecDefaultAuth] = useState(null);
+    const deviceIdRef = useRef(null);
+    // Load auth from localStorage on mount (async with encryption)
+    useEffect(()=>{
+        async function initializeAuth() {
+            try {
+                // Fetch device ID from backend (required for encryption)
+                const deviceId = await fetchDeviceId();
+                deviceIdRef.current = deviceId;
+                // Load encrypted auth from storage
+                const stored = await authStorage.load(deviceId);
+                if (stored) {
+                    setGlobalAuthState(stored);
+                }
+                // Fetch security schemes from the spec
+                const schemesResponse = await fetch('/api/auth-schemes');
+                if (schemesResponse.ok) {
+                    const data = await schemesResponse.json();
+                    setSpecSchemes(data.schemes || []);
+                    setSpecDefaultAuth(data.defaultAuth || null);
+                }
+            } catch (error) {
+                console.error('[AuthProvider] Failed to initialize auth:', error);
+                // Clear any potentially corrupted data
+                authStorage.clear();
+            } finally{
+                setIsInitialized(true);
+            }
+        }
+        initializeAuth();
+    }, []);
+    const setGlobalAuth = useCallback(async (auth)=>{
+        if (!deviceIdRef.current) {
+            console.error('[AuthProvider] Cannot save auth: no device ID');
+            return;
+        }
+        setGlobalAuthState(auth);
+        await authStorage.save(auth, deviceIdRef.current);
+    }, []);
+    const clearAuth = useCallback(()=>{
+        setGlobalAuthState(null);
+        authStorage.clear();
+    }, []);
+    /**
+   * Get effective auth for an endpoint
+   * - If endpoint has 'inherit' auth type, use global auth
+   * - If endpoint has 'none' auth type and global is set, use global
+   * - Otherwise use endpoint's own auth
+   */ const getEffectiveAuth = useCallback((endpointAuth)=>{
+        // If endpoint explicitly wants to inherit, use global
+        if (endpointAuth.authType === 'inherit') {
+            return globalAuth || DEFAULT_AUTH;
+        }
+        // If endpoint has no auth but global is configured, suggest global
+        // but don't override - this allows explicit "no auth" endpoints
+        if (endpointAuth.authType === 'none' && globalAuth && globalAuth.authType !== 'none') {
+            // Return global auth but the UI should indicate it's using global
+            return globalAuth;
+        }
+        // Use endpoint's own auth
+        return endpointAuth;
+    }, [
+        globalAuth
+    ]);
+    /**
+   * Check if an endpoint is using global auth
+   */ const isUsingGlobalAuth = useCallback((endpointAuth)=>{
+        if (!globalAuth || globalAuth.authType === 'none') {
+            return false;
+        }
+        // Using global if inheriting or if endpoint has no auth
+        return endpointAuth.authType === 'inherit' || endpointAuth.authType === 'none';
+    }, [
+        globalAuth
+    ]);
+    const isAuthenticated = globalAuth !== null && globalAuth.authType !== 'none';
+    const value = {
+        globalAuth,
+        isAuthenticated,
+        setGlobalAuth,
+        clearAuth,
+        getEffectiveAuth,
+        isUsingGlobalAuth,
+        specSchemes,
+        specDefaultAuth
+    };
+    // Don't render until we've checked sessionStorage
+    if (!isInitialized) {
+        return null;
+    }
+    return /*#__PURE__*/ _jsx(AuthContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+export function useAuth() {
+    const context = useContext(AuthContext);
+    if (!context) {
+        throw new Error('useAuth must be used within an AuthProvider');
+    }
+    return context;
+}
+/**
+ * Get a human-readable label for auth type
+ */ export function getAuthTypeLabel(auth) {
+    if (!auth || !auth.authType) {
+        return 'Not configured';
+    }
+    switch(auth.authType){
+        case 'none':
+            return 'No Auth';
+        case 'inherit':
+            return 'Inherited';
+        case 'basic':
+            return 'Basic Auth';
+        case 'bearer':
+            return 'Bearer Token';
+        case 'api-key':
+            return `API Key (${auth.key || 'key'})`;
+        case 'oauth-2':
+            return 'OAuth 2.0';
+        default:
+            return 'Not configured';
+    }
+}
+/**
+ * Get a masked preview of auth value
+ */ export function getAuthPreview(auth) {
+    switch(auth.authType){
+        case 'none':
+        case 'inherit':
+            return '';
+        case 'basic':
+            return auth.username ? `${auth.username}:****` : '';
+        case 'bearer':
+            return auth.token ? `${auth.token.slice(0, 8)}••••` : '';
+        case 'api-key':
+            return auth.value ? `${auth.value.slice(0, 4)}••••` : '';
+        case 'oauth-2':
+            return auth.grantTypeInfo.token ? `${auth.grantTypeInfo.token.slice(0, 8)}••••` : '';
+        default:
+            return '';
+    }
+}

package/renderer/lib/api-docs/auth/auth-storage.js

@@ -0,0 +1,66 @@
+'use client';
+import { encrypt, decrypt } from './crypto';
+const AUTH_STORAGE_KEY = 'brainfish-api-global-auth';
+/**
+ * Fetch device ID from backend API
+ * The device ID is stored in an httpOnly cookie
+ * Throws error if device ID cannot be fetched (no fallback)
+ */ export async function fetchDeviceId() {
+    const response = await fetch('/api/device', {
+        credentials: 'include'
+    });
+    if (!response.ok) {
+        throw new Error('Failed to fetch device ID');
+    }
+    const data = await response.json();
+    if (!data.deviceId) {
+        throw new Error('No device ID returned from server');
+    }
+    return data.deviceId;
+}
+/**
+ * Encrypted localStorage wrapper for global authentication
+ * Uses device ID from backend as encryption key
+ * No fallbacks - encryption is required
+ */ export const authStorage = {
+    /**
+   * Save auth configuration to localStorage (encrypted)
+   * Requires valid device ID - throws if missing
+   */ async save (auth, deviceId) {
+        if (!deviceId) {
+            throw new Error('Device ID required for secure storage');
+        }
+        const data = {
+            globalAuth: auth,
+            timestamp: Date.now()
+        };
+        const encrypted = await encrypt(JSON.stringify(data), deviceId);
+        localStorage.setItem(AUTH_STORAGE_KEY, encrypted);
+    },
+    /**
+   * Load auth configuration from localStorage (decrypted)
+   * Returns null if no data or decryption fails
+   */ async load (deviceId) {
+        if (!deviceId) return null;
+        const stored = localStorage.getItem(AUTH_STORAGE_KEY);
+        if (!stored) return null;
+        try {
+            const jsonData = await decrypt(stored, deviceId);
+            const data = JSON.parse(jsonData);
+            if (!data.globalAuth?.authType) {
+                localStorage.removeItem(AUTH_STORAGE_KEY);
+                return null;
+            }
+            return data.globalAuth;
+        } catch  {
+            // Decryption failed - clear corrupted/invalid data
+            localStorage.removeItem(AUTH_STORAGE_KEY);
+            return null;
+        }
+    },
+    /**
+   * Clear stored auth configuration
+   */ clear () {
+        localStorage.removeItem(AUTH_STORAGE_KEY);
+    }
+};

package/renderer/lib/api-docs/auth/crypto.js

@@ -0,0 +1,64 @@
+'use client';
+/**
+ * Web Crypto API utilities for encrypting/decrypting auth credentials
+ * Uses AES-GCM with a key derived from device ID
+ */ const ALGORITHM = 'AES-GCM';
+const KEY_LENGTH = 256;
+const IV_LENGTH = 12 // 96 bits for AES-GCM
+;
+/**
+ * Derive a crypto key from a device ID using PBKDF2
+ */ async function deriveKey(deviceId) {
+    const encoder = new TextEncoder();
+    const keyMaterial = await crypto.subtle.importKey('raw', encoder.encode(deviceId), 'PBKDF2', false, [
+        'deriveKey'
+    ]);
+    // Use a fixed salt (could be made dynamic per-user if needed)
+    const salt = encoder.encode('brainfish-api-docs-v1');
+    return crypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        salt,
+        iterations: 100000,
+        hash: 'SHA-256'
+    }, keyMaterial, {
+        name: ALGORITHM,
+        length: KEY_LENGTH
+    }, false, [
+        'encrypt',
+        'decrypt'
+    ]);
+}
+/**
+ * Encrypt a string using AES-GCM with device ID as key
+ */ export async function encrypt(plaintext, deviceId) {
+    const key = await deriveKey(deviceId);
+    const encoder = new TextEncoder();
+    const data = encoder.encode(plaintext);
+    // Generate random IV
+    const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+    const encrypted = await crypto.subtle.encrypt({
+        name: ALGORITHM,
+        iv
+    }, key, data);
+    // Combine IV + encrypted data and encode as base64
+    const combined = new Uint8Array(iv.length + encrypted.byteLength);
+    combined.set(iv);
+    combined.set(new Uint8Array(encrypted), iv.length);
+    return btoa(String.fromCharCode(...combined));
+}
+/**
+ * Decrypt a string using AES-GCM with device ID as key
+ */ export async function decrypt(ciphertext, deviceId) {
+    const key = await deriveKey(deviceId);
+    // Decode base64
+    const combined = Uint8Array.from(atob(ciphertext), (c)=>c.charCodeAt(0));
+    // Extract IV and encrypted data
+    const iv = combined.slice(0, IV_LENGTH);
+    const encrypted = combined.slice(IV_LENGTH);
+    const decrypted = await crypto.subtle.decrypt({
+        name: ALGORITHM,
+        iv
+    }, key, encrypted);
+    const decoder = new TextDecoder();
+    return decoder.decode(decrypted);
+}

package/renderer/lib/api-docs/auth/index.js

@@ -0,0 +1,3 @@
+export { AuthProvider, useAuth, getAuthTypeLabel, getAuthPreview } from './auth-context';
+export { authStorage, fetchDeviceId } from './auth-storage';
+export { encrypt, decrypt } from './crypto';

package/renderer/lib/api-docs/code-editor/db.js

@@ -0,0 +1,145 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import Dexie from 'dexie';
+/**
+ * Simplified database for Notes workspace
+ * - One workspace per API (not multiple projects)
+ * - Notes are files for brainstorming (code, diagrams, markdown)
+ */ class NotesDatabase extends Dexie {
+    constructor(){
+        super('brainfish-notes'), _define_property(this, "workspaces", void 0), _define_property(this, "notes", void 0), _define_property(this, "editorStates", void 0);
+        this.version(1).stores({
+            // Single workspace per API
+            workspaces: 'id, apiSpecUrl, updatedAt',
+            // Notes/files in workspace
+            notes: 'id, workspaceId, [workspaceId+path], updatedAt',
+            // Editor state per workspace
+            editorStates: 'workspaceId'
+        });
+    }
+}
+// Singleton database instance
+export const db = new NotesDatabase();
+/**
+ * Generate a workspace ID from API spec URL
+ */ export function getWorkspaceId(apiSpecUrl) {
+    // Simple hash for consistent ID
+    let hash = 0;
+    for(let i = 0; i < apiSpecUrl.length; i++){
+        const char = apiSpecUrl.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return `ws-${Math.abs(hash).toString(16)}`;
+}
+/**
+ * Database operations - simplified for notes workspace
+ */ export const dbOperations = {
+    // Workspace operations (auto-created, one per API)
+    async getOrCreateWorkspace (apiSpecUrl, name) {
+        const id = getWorkspaceId(apiSpecUrl);
+        let workspace = await db.workspaces.get(id);
+        if (!workspace) {
+            workspace = {
+                id,
+                name,
+                apiSpecUrl,
+                createdAt: new Date(),
+                updatedAt: new Date()
+            };
+            await db.workspaces.add(workspace);
+        }
+        return workspace;
+    },
+    async getWorkspace (id) {
+        return db.workspaces.get(id);
+    },
+    async updateWorkspace (id, updates) {
+        await db.workspaces.update(id, {
+            ...updates,
+            updatedAt: new Date()
+        });
+    },
+    // Note/file operations
+    async createNote (workspaceId, path, content = '') {
+        const note = {
+            id: crypto.randomUUID(),
+            workspaceId,
+            path,
+            content,
+            createdAt: new Date(),
+            updatedAt: new Date()
+        };
+        await db.notes.add(note);
+        // Update workspace timestamp
+        await db.workspaces.update(workspaceId, {
+            updatedAt: new Date()
+        });
+        return note;
+    },
+    async getNote (workspaceId, path) {
+        return db.notes.where('[workspaceId+path]').equals([
+            workspaceId,
+            path
+        ]).first();
+    },
+    async listNotes (workspaceId) {
+        return db.notes.where('workspaceId').equals(workspaceId).toArray();
+    },
+    async updateNote (workspaceId, path, content) {
+        await db.notes.where('[workspaceId+path]').equals([
+            workspaceId,
+            path
+        ]).modify({
+            content,
+            updatedAt: new Date()
+        });
+        await db.workspaces.update(workspaceId, {
+            updatedAt: new Date()
+        });
+    },
+    async deleteNote (workspaceId, path) {
+        await db.notes.where('[workspaceId+path]').equals([
+            workspaceId,
+            path
+        ]).delete();
+        await db.workspaces.update(workspaceId, {
+            updatedAt: new Date()
+        });
+    },
+    async renameNote (workspaceId, oldPath, newPath) {
+        await db.notes.where('[workspaceId+path]').equals([
+            workspaceId,
+            oldPath
+        ]).modify({
+            path: newPath,
+            updatedAt: new Date()
+        });
+        await db.workspaces.update(workspaceId, {
+            updatedAt: new Date()
+        });
+    },
+    // Editor state operations
+    async getEditorState (workspaceId) {
+        return db.editorStates.get(workspaceId);
+    },
+    async saveEditorState (state) {
+        await db.editorStates.put(state);
+    },
+    // Clear all notes in workspace (reset)
+    async clearWorkspace (workspaceId) {
+        await db.notes.where('workspaceId').equals(workspaceId).delete();
+        await db.editorStates.delete(workspaceId);
+    }
+};