@brainfish-ai/devdoc 0.1.21

package/renderer/lib/cache.ts

@@ -0,0 +1,193 @@
+/**
+ * Universal caching utility that works in both local and production environments
+ *
+ * - Local development: Uses node-cache (in-memory)
+ * - Production (Vercel): Uses Vercel KV
+ *
+ * Environment-based cache selection:
+ * 1. Explicit override: CACHE_TYPE=local or CACHE_TYPE=kv
+ * 2. Auto-detect: KV_REST_API_URL or KV_URL present → Uses Vercel KV
+ * 3. Fallback: Uses local node-cache
+ *
+ * Example usage:
+ * ```typescript
+ * import { CacheUtils } from '@/utils/cache';
+ *
+ * // Get from cache
+ * const cached = await CacheUtils.get<MyType>('my-key', { logHit: true });
+ *
+ * // Set with TTL
+ * await CacheUtils.set('my-key', data, 3600, { log: true }); // 1 hour TTL
+ *
+ * // Delete
+ * await CacheUtils.del('my-key', { log: true });
+ * ```
+ */
+
+import NodeCache from 'node-cache';
+import { kv } from '@vercel/kv';
+
+/**
+ * Cache environment configuration
+ */
+const CACHE_CONFIG = {
+  // Environment variables that indicate KV should be used
+  KV_INDICATORS: ['KV_REST_API_URL', 'KV_URL'] as const,
+  
+  // Allow explicit override via CACHE_TYPE env var
+  CACHE_TYPE: process.env.CACHE_TYPE as 'local' | 'kv' | undefined,
+} as const;
+
+/**
+ * Determine cache type based on environment variables
+ */
+function getCacheType(): 'local' | 'kv' {
+  // Explicit override takes precedence
+  if (CACHE_CONFIG.CACHE_TYPE === 'local') {
+    return 'local';
+  }
+  
+  if (CACHE_CONFIG.CACHE_TYPE === 'kv') {
+    return 'kv';
+  }
+  
+  // Auto-detect based on KV environment variables
+  const hasKVConfig = CACHE_CONFIG.KV_INDICATORS.some(
+    (envVar) => !!process.env[envVar]
+  );
+  
+  return hasKVConfig ? 'kv' : 'local';
+}
+
+// Determine cache type at module load time
+const cacheType = getCacheType();
+
+// Initialize cache backends based on environment
+let localCache: NodeCache | null = null;
+
+if (cacheType === 'kv') {
+  console.log('[Cache] Using Vercel KV cache');
+} else {
+  console.log('[Cache] Using local node-cache');
+  localCache = new NodeCache({
+    stdTTL: 60 * 60 * 24, // Default 24 hours TTL
+    checkperiod: 60 * 10, // Check for expired keys every 10 minutes
+    useClones: false, // Better performance, but be careful with object mutations
+  });
+}
+
+/**
+ * Universal cache utility functions
+ */
+export class CacheUtils {
+  /**
+   * Get a value from cache with optional logging
+   */
+  static async get<T = unknown>(
+    key: string,
+    options?: { logHit?: boolean }
+  ): Promise<T | null> {
+    try {
+      let value: T | undefined;
+
+      if (cacheType === 'kv') {
+        value = await kv.get(key) as T | undefined;
+      } else {
+        value = localCache?.get<T>(key);
+      }
+
+      // Fix: Only return null for missing keys (undefined), not for falsy values
+      const result = value !== undefined ? value : null;
+
+      if (options?.logHit) {
+        if (result !== null) {
+          console.log(`[Cache] HIT: ${key}`);
+        } else {
+          console.log(`[Cache] MISS: ${key}`);
+        }
+      }
+
+      return result;
+    } catch (error) {
+      console.warn(`[Cache] Get error for key "${key}":`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Set a value in cache with TTL and logging
+   */
+  static async set<T = unknown>(
+    key: string,
+    value: T,
+    ttlSeconds?: number,
+    options?: { log?: boolean }
+  ): Promise<void> {
+    try {
+      if (cacheType === 'kv') {
+        if (ttlSeconds) {
+          await kv.set(key, value, { ex: ttlSeconds });
+        } else {
+          await kv.set(key, value);
+        }
+      } else {
+        const ttl = ttlSeconds || 60 * 60 * 24; // Default to 24 hours
+        localCache?.set(key, value, ttl);
+      }
+
+      if (options?.log) {
+        const ttlInfo = ttlSeconds ? ` (TTL: ${ttlSeconds}s)` : '';
+        console.log(`[Cache] SET: ${key}${ttlInfo}`);
+      }
+    } catch (error) {
+      console.warn(`[Cache] Set error for key "${key}":`, error);
+    }
+  }
+
+  /**
+   * Delete a key from cache
+   */
+  static async del(key: string, options?: { log?: boolean }): Promise<void> {
+    try {
+      if (cacheType === 'kv') {
+        await kv.del(key);
+      } else {
+        localCache?.del(key);
+      }
+
+      if (options?.log) {
+        console.log(`[Cache] DEL: ${key}`);
+      }
+    } catch (error) {
+      console.warn(`[Cache] Delete error for key "${key}":`, error);
+    }
+  }
+
+  /**
+   * Clear all cache entries (use with caution!)
+   */
+  static async clear(): Promise<void> {
+    try {
+      if (cacheType === 'kv') {
+        await kv.flushdb();
+      } else {
+        localCache?.flushAll();
+      }
+      console.log('[Cache] Cleared all entries');
+    } catch (error) {
+      console.warn('[Cache] Clear error:', error);
+    }
+  }
+
+  /**
+   * Get current cache type for debugging/monitoring
+   */
+  static getCacheType(): 'local' | 'kv' {
+    return cacheType;
+  }
+}
+
+// Legacy exports for backward compatibility
+export const cache = CacheUtils;
+export { cacheType };
+export default CacheUtils;

package/renderer/lib/docs/config/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Configuration Module Exports
+ */
+
+export {
+  docsConfigSchema,
+  parseDocsConfig,
+  safeParseDocsConfig,
+  getDefaultDocsConfig,
+  type DocsConfig,
+  type NavigationTab,
+  type NavigationGroup,
+  type NavLink,
+  type Anchor,
+  type ColorConfig,
+  type LogoConfig,
+  type ApiConfig,
+} from './schema'
+
+export {
+  loadDocsConfig,
+  safeLoadDocsConfig,
+  clearConfigCache,
+  hasDocsConfig,
+  getContentDir,
+  resolvePagePath,
+  loadPageContent,
+  listMdxFiles,
+} from './loader'

package/renderer/lib/docs/config/loader.ts

@@ -0,0 +1,142 @@
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { join } from 'path'
+import { parseDocsConfig, type DocsConfig } from './schema'
+
+/**
+ * Configuration Loader
+ * 
+ * Utilities for loading and caching docs.json configuration
+ * Uses synchronous fs operations for compatibility with Next.js Turbopack
+ */
+
+// Cache for loaded configuration
+let configCache: DocsConfig | null = null
+let configCachePath: string | null = null
+
+/**
+ * Load docs.json configuration from a directory
+ */
+export function loadDocsConfig(docsDir: string): DocsConfig {
+  const configFilePath = join(docsDir, 'docs.json')
+  
+  // Return cached config if path matches
+  if (configCache && configCachePath === configFilePath) {
+    return configCache
+  }
+  
+  try {
+    if (!existsSync(configFilePath)) {
+      throw new Error(`docs.json not found at ${configFilePath}`)
+    }
+    
+    const configContent = readFileSync(configFilePath, 'utf-8')
+    const rawConfig = JSON.parse(configContent)
+    const config = parseDocsConfig(rawConfig)
+    
+    // Cache the result
+    configCache = config
+    configCachePath = configFilePath
+    
+    return config
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Failed to load docs.json: ${error.message}`)
+    }
+    throw error
+  }
+}
+
+/**
+ * Load configuration without throwing (returns null on failure)
+ */
+export function safeLoadDocsConfig(docsDir: string): DocsConfig | null {
+  try {
+    return loadDocsConfig(docsDir)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Clear the configuration cache
+ */
+export function clearConfigCache(): void {
+  configCache = null
+  configCachePath = null
+}
+
+/**
+ * Check if a docs.json file exists in a directory
+ */
+export function hasDocsConfig(docsDir: string): boolean {
+  return existsSync(join(docsDir, 'docs.json'))
+}
+
+/**
+ * Get the content directory path from configuration
+ */
+export function getContentDir(docsDir: string): string {
+  return docsDir
+}
+
+/**
+ * Resolve a page path to a file path
+ */
+export function resolvePagePath(
+  docsDir: string, 
+  pagePath: string
+): string | null {
+  const contentDir = getContentDir(docsDir)
+  const extensions = ['.mdx', '.md']
+  
+  // Try different extensions
+  for (const ext of extensions) {
+    const filePath = join(contentDir, `${pagePath}${ext}`)
+    if (existsSync(filePath)) {
+      return filePath
+    }
+  }
+  
+  // Try as directory with index file
+  for (const ext of extensions) {
+    const indexPath = join(contentDir, pagePath, `index${ext}`)
+    if (existsSync(indexPath)) {
+      return indexPath
+    }
+  }
+  
+  return null
+}
+
+/**
+ * Load page content from a resolved path
+ */
+export function loadPageContent(filePath: string): string {
+  return readFileSync(filePath, 'utf-8')
+}
+
+/**
+ * List all MDX files in a directory recursively
+ */
+export function listMdxFiles(dir: string): string[] {
+  const files: string[] = []
+  
+  function walk(currentDir: string) {
+    const entries = readdirSync(currentDir, { withFileTypes: true })
+    
+    for (const entry of entries) {
+      const fullPath = join(currentDir, entry.name)
+      
+      if (entry.isDirectory()) {
+        if (!entry.name.startsWith('.') && entry.name !== 'node_modules') {
+          walk(fullPath)
+        }
+      } else if (entry.isFile() && (entry.name.endsWith('.mdx') || entry.name.endsWith('.md'))) {
+        files.push(fullPath)
+      }
+    }
+  }
+  
+  walk(dir)
+  return files
+}

package/renderer/lib/docs/config/schema.ts

@@ -0,0 +1,298 @@
+import { z } from 'zod'
+
+/**
+ * Documentation Configuration Schema (docs.json)
+ * 
+ * Mintlify-compatible configuration schema for documentation sites.
+ */
+
+// ============================================================================
+// Navigation Schemas
+// ============================================================================
+
+const anchorSchema = z.object({
+  anchor: z.string(),
+  href: z.string(),
+  icon: z.string().optional(),
+})
+
+const navLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+})
+
+// Page can be a string or a nested group
+const pageRefSchema: z.ZodType<string | { group: string; pages: (string | object)[] }> = z.lazy(() => 
+  z.union([
+    z.string(), // Page path like "quickstart" or "guides/intro"
+    z.object({  // Nested group
+      group: z.string(),
+      pages: z.array(z.union([z.string(), z.lazy(() => pageRefSchema)])),
+    }),
+  ])
+)
+
+const groupSchema = z.object({
+  group: z.string(),
+  pages: z.array(pageRefSchema),
+  icon: z.string().optional(),
+})
+
+// OpenAPI version schema
+const openapiVersionSchema = z.object({
+  version: z.string(),
+  spec: z.string(),
+  default: z.boolean().optional(),
+})
+
+// Different tab types
+const docsTabSchema = z.object({
+  tab: z.string(),
+  type: z.literal('docs').optional(),
+  groups: z.array(groupSchema),
+})
+
+const openapiTabSchema = z.object({
+  tab: z.string(),
+  type: z.literal('openapi'),
+  path: z.string().optional(),
+  versions: z.array(openapiVersionSchema).optional(),
+  spec: z.string().optional(),
+})
+
+const changelogTabSchema = z.object({
+  tab: z.string(),
+  type: z.literal('changelog'),
+  path: z.string().optional(),
+})
+
+const tabSchema = z.union([docsTabSchema, openapiTabSchema, changelogTabSchema])
+
+const navigationSchema = z.object({
+  tabs: z.array(tabSchema).optional(),
+  groups: z.array(groupSchema).optional(), // For single-tab sites
+  global: z.object({
+    anchors: z.array(anchorSchema).optional(),
+  }).optional(),
+})
+
+// ============================================================================
+// Theme & Branding Schemas
+// ============================================================================
+
+const colorSchema = z.object({
+  primary: z.string(),
+  light: z.string().optional(),
+  dark: z.string().optional(),
+  background: z.object({
+    light: z.string().optional(),
+    dark: z.string().optional(),
+  }).optional(),
+})
+
+const logoSchema = z.object({
+  light: z.string(),
+  dark: z.string(),
+  href: z.string().optional(),
+})
+
+const faviconSchema = z.string()
+
+// ============================================================================
+// Navbar Schema
+// ============================================================================
+
+const navbarPrimarySchema = z.object({
+  type: z.enum(['button', 'github', 'link']),
+  label: z.string().optional(),
+  href: z.string(),
+})
+
+const navbarSchema = z.object({
+  links: z.array(navLinkSchema).optional(),
+  primary: navbarPrimarySchema.optional(),
+})
+
+// ============================================================================
+// Footer Schema
+// ============================================================================
+
+const footerLinkSchema = z.object({
+  label: z.string(),
+  href: z.string(),
+})
+
+const footerGroupSchema = z.object({
+  title: z.string(),
+  links: z.array(footerLinkSchema),
+})
+
+const footerSchema = z.object({
+  socials: z.record(z.string(), z.string()).optional(),
+  links: z.array(footerGroupSchema).optional(),
+})
+
+// ============================================================================
+// API Configuration Schema
+// ============================================================================
+
+const apiAuthSchema = z.object({
+  method: z.enum(['bearer', 'basic', 'api-key', 'none']),
+  name: z.string().optional(),
+})
+
+const apiPlaygroundSchema = z.object({
+  mode: z.enum(['show', 'simple', 'hide']).optional(),
+})
+
+const apiConfigSchema = z.object({
+  baseUrl: z.string().optional(),
+  auth: apiAuthSchema.optional(),
+  playground: apiPlaygroundSchema.optional(),
+})
+
+// ============================================================================
+// SEO Schema
+// ============================================================================
+
+const seoSchema = z.object({
+  indexHiddenPages: z.boolean().optional(),
+  titleTemplate: z.string().optional(),
+})
+
+// ============================================================================
+// Integrations Schema
+// ============================================================================
+
+const analyticsSchema = z.object({
+  posthog: z.object({ apiKey: z.string() }).optional(),
+  googleAnalytics: z.object({ measurementId: z.string() }).optional(),
+  plausible: z.object({ domain: z.string() }).optional(),
+})
+
+const integrationsSchema = z.object({
+  analytics: analyticsSchema.optional(),
+})
+
+// ============================================================================
+// Contextual Menu Schema
+// ============================================================================
+
+const contextualOptionsEnum = z.enum([
+  'copy',
+  'view',
+  'chatgpt',
+  'claude',
+  'perplexity',
+  'mcp',
+  'cursor',
+  'vscode',
+])
+
+const contextualSchema = z.object({
+  options: z.array(contextualOptionsEnum).optional(),
+})
+
+// ============================================================================
+// Main Configuration Schema
+// ============================================================================
+
+export const docsConfigSchema = z.object({
+  // Schema reference (optional)
+  $schema: z.string().optional(),
+  
+  // Core identity
+  name: z.string(),
+  
+  // Theme
+  theme: z.enum(['default', 'mint', 'quill', 'venus']).optional(),
+  colors: colorSchema.optional(),
+  
+  // Branding
+  favicon: faviconSchema.optional(),
+  logo: logoSchema.optional(),
+  
+  // Navigation
+  navigation: navigationSchema,
+  
+  // Navbar
+  navbar: navbarSchema.optional(),
+  
+  // Footer
+  footer: footerSchema.optional(),
+  
+  // API Configuration
+  api: apiConfigSchema.optional(),
+  openapi: z.union([z.string(), z.array(z.string())]).optional(),
+  
+  // SEO
+  seo: seoSchema.optional(),
+  
+  // Integrations
+  integrations: integrationsSchema.optional(),
+  
+  // Contextual menu
+  contextual: contextualSchema.optional(),
+  
+  // Topbar style
+  topbar: z.object({
+    style: z.enum(['default', 'gradient']).optional(),
+  }).optional(),
+  
+  // Versioning
+  versions: z.array(z.string()).optional(),
+})
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DocsConfig = z.infer<typeof docsConfigSchema>
+export type NavigationTab = z.infer<typeof tabSchema>
+export type NavigationGroup = z.infer<typeof groupSchema>
+export type NavLink = z.infer<typeof navLinkSchema>
+export type Anchor = z.infer<typeof anchorSchema>
+export type ColorConfig = z.infer<typeof colorSchema>
+export type LogoConfig = z.infer<typeof logoSchema>
+export type ApiConfig = z.infer<typeof apiConfigSchema>
+
+// ============================================================================
+// Validation Functions
+// ============================================================================
+
+/**
+ * Parse and validate docs configuration
+ */
+export function parseDocsConfig(data: unknown): DocsConfig {
+  const result = docsConfigSchema.safeParse(data)
+  
+  if (!result.success) {
+    const issues = result.error.issues || []
+    const errors = issues.map((e) => 
+      `${e.path.map(String).join('.')}: ${e.message}`
+    ).join('\n')
+    throw new Error(`Invalid docs.json configuration:\n${errors}`)
+  }
+  
+  return result.data
+}
+
+/**
+ * Safe parse that returns null on failure
+ */
+export function safeParseDocsConfig(data: unknown): DocsConfig | null {
+  const result = docsConfigSchema.safeParse(data)
+  return result.success ? result.data : null
+}
+
+/**
+ * Get default configuration
+ */
+export function getDefaultDocsConfig(): Partial<DocsConfig> {
+  return {
+    theme: 'default',
+    navigation: {
+      groups: [],
+    },
+  }
+}

package/renderer/lib/docs/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Documentation Library Exports
+ */
+
+// MDX
+export * from './mdx'
+
+// Configuration
+export * from './config'
+
+// Navigation
+export * from './navigation'