claude-brain 0.3.0

package/src/utils/error-messages.ts

@@ -0,0 +1,60 @@
+export class ErrorMessages {
+  static format(error: Error, context?: Record<string, unknown>): string {
+    const errorMap: Record<string, string> = {
+      'ENOENT': 'File or directory not found',
+      'EACCES': 'Permission denied',
+      'ECONNREFUSED': 'Connection refused - service may be down',
+      'ETIMEDOUT': 'Operation timed out',
+      'SQLITE_BUSY': 'Database is busy, please try again',
+      'Project not found': 'Project does not exist in vault'
+    }
+
+    for (const [key, message] of Object.entries(errorMap)) {
+      if (error.message.includes(key)) {
+        return this.formatWithSolution(message, key, context)
+      }
+    }
+
+    return `Error: ${error.message}`
+  }
+
+  private static formatWithSolution(
+    message: string,
+    errorType: string,
+    context?: Record<string, unknown>
+  ): string {
+    let output = `❌ ${message}\n`
+
+    const solutions: Record<string, string[]> = {
+      'ENOENT': [
+        'Verify the file path is correct',
+        'Check that the project exists in your vault'
+      ],
+      'EACCES': [
+        'Check file permissions',
+        'Ensure you have write access to the directory'
+      ],
+      'ECONNREFUSED': [
+        'Verify the service is running',
+        'Check your network connection'
+      ],
+      'SQLITE_BUSY': [
+        'Close other applications accessing the database',
+        'Try again in a moment'
+      ]
+    }
+
+    if (solutions[errorType]) {
+      output += '\n💡 Possible solutions:\n'
+      solutions[errorType].forEach((solution, i) => {
+        output += `   ${i + 1}. ${solution}\n`
+      })
+    }
+
+    if (context) {
+      output += `\n📋 Context: ${JSON.stringify(context)}\n`
+    }
+
+    return output
+  }
+}

package/src/utils/fallback.ts

@@ -0,0 +1,45 @@
+import type { Logger } from 'pino'
+
+export interface FallbackStrategy<T> {
+  primary: () => Promise<T>
+  fallback: () => Promise<T>
+  condition?: (error: Error) => boolean
+}
+
+export class FallbackManager {
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'fallback-manager' })
+  }
+
+  async execute<T>(strategy: FallbackStrategy<T>): Promise<T> {
+    try {
+      return await strategy.primary()
+
+    } catch (error) {
+      if (strategy.condition && !strategy.condition(error as Error)) {
+        throw error
+      }
+
+      this.logger.warn(
+        { error: (error as Error).message },
+        'Primary operation failed, using fallback'
+      )
+
+      try {
+        return await strategy.fallback()
+
+      } catch (fallbackError) {
+        this.logger.error(
+          {
+            primaryError: (error as Error).message,
+            fallbackError: (fallbackError as Error).message
+          },
+          'Both primary and fallback failed'
+        )
+        throw fallbackError
+      }
+    }
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,54 @@
+export {
+  createLogger,
+  createComponentLogger,
+  createRequestLogger,
+  generateRequestId
+} from './logger'
+
+export {
+  logToolCall,
+  logToolResult,
+  logAgentActivity,
+  logPerformance,
+  logError,
+  logVaultOperation,
+  logMemoryOperation,
+  createTimer
+} from './logger-utils'
+
+export {
+  GlobalErrorHandler,
+  AppError,
+  isOperationalError
+} from './error-handler'
+
+export {
+  RetryManager
+} from './retry'
+
+export {
+  CircuitBreaker,
+  CircuitState
+} from './circuit-breaker'
+
+export {
+  FallbackManager
+} from './fallback'
+
+export {
+  TransactionManager
+} from './transaction'
+
+export {
+  CleanupManager
+} from './cleanup'
+
+export {
+  ErrorMessages
+} from './error-messages'
+
+export {
+  isPhase12Available,
+  getPhase12Instance,
+  resetPhase12Cache
+} from './phase12-helper'

package/src/utils/logger-utils.ts

@@ -0,0 +1,80 @@
+import type { Logger } from 'pino'
+
+/** Log an MCP tool call with parameters */
+export function logToolCall(logger: Logger, toolName: string, params: Record<string, unknown>): void {
+  logger.info({
+    event: 'tool_call',
+    tool: toolName,
+    params
+  }, `Tool called: ${toolName}`)
+}
+
+/** Log an MCP tool result */
+export function logToolResult(logger: Logger, toolName: string, success: boolean, duration: number): void {
+  logger.info({
+    event: 'tool_result',
+    tool: toolName,
+    success,
+    durationMs: duration
+  }, `Tool ${success ? 'completed' : 'failed'}: ${toolName}`)
+}
+
+/** Log agent activity and decisions */
+export function logAgentActivity(logger: Logger, action: string, context: Record<string, unknown>): void {
+  logger.info({
+    event: 'agent_activity',
+    action,
+    ...context
+  }, `Agent: ${action}`)
+}
+
+/** Log performance metrics */
+export function logPerformance(logger: Logger, operation: string, durationMs: number, metadata?: Record<string, unknown>): void {
+  logger.info({
+    event: 'performance',
+    operation,
+    durationMs,
+    ...metadata
+  }, `Performance: ${operation} took ${durationMs}ms`)
+}
+
+/** Log an error with full context */
+export function logError(logger: Logger, error: Error, context?: Record<string, unknown>): void {
+  logger.error({
+    event: 'error',
+    error: {
+      name: error.name,
+      message: error.message,
+      stack: error.stack
+    },
+    ...context
+  }, `Error: ${error.message}`)
+}
+
+/** Log vault file operations */
+export function logVaultOperation(logger: Logger, operation: string, filePath: string, metadata?: Record<string, unknown>): void {
+  logger.debug({
+    event: 'vault_operation',
+    operation,
+    filePath,
+    ...metadata
+  }, `Vault: ${operation} - ${filePath}`)
+}
+
+/** Log memory/embedding operations */
+export function logMemoryOperation(logger: Logger, operation: string, count: number, metadata?: Record<string, unknown>): void {
+  logger.debug({
+    event: 'memory_operation',
+    operation,
+    count,
+    ...metadata
+  }, `Memory: ${operation} (${count} items)`)
+}
+
+/** Create a timer utility for measuring operation duration */
+export function createTimer(): { stop: () => number } {
+  const start = performance.now()
+  return {
+    stop: () => Math.round(performance.now() - start)
+  }
+}

package/src/utils/logger.ts

@@ -0,0 +1,88 @@
+import pino, { type Logger, type LoggerOptions } from 'pino'
+import { mkdirSync, existsSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { LogLevel } from '@/config'
+
+/** Create the log directory if it doesn't exist */
+function ensureLogDir(logFilePath: string): void {
+  const dir = dirname(logFilePath)
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true })
+  }
+}
+
+/** Create a configured Pino logger instance */
+export function createLogger(level: LogLevel, logFilePath: string): Logger {
+  ensureLogDir(logFilePath)
+
+  const isDev = process.env.NODE_ENV !== 'production'
+
+  const baseOptions: LoggerOptions = {
+    level,
+    timestamp: pino.stdTimeFunctions.isoTime,
+    base: {
+      pid: process.pid,
+      hostname: undefined // Remove hostname for cleaner logs
+    }
+  }
+
+  if (isDev) {
+    // Development: pretty print to console AND write to file
+    const targets: pino.TransportTargetOptions[] = [
+      {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'SYS:standard',
+          ignore: 'pid',
+          destination: 2 // stderr for console
+        },
+        level
+      },
+      {
+        target: 'pino/file',
+        options: { destination: logFilePath },
+        level
+      }
+    ]
+
+    return pino({
+      ...baseOptions,
+      transport: { targets }
+    })
+  }
+
+  // Production: write to file only (MCP uses stdout for JSON-RPC)
+  const targets: pino.TransportTargetOptions[] = [
+    {
+      target: 'pino/file',
+      options: { destination: logFilePath },
+      level
+    },
+    {
+      target: 'pino/file',
+      options: { destination: 2 }, // stderr instead of stdout
+      level
+    }
+  ]
+
+  return pino({
+    ...baseOptions,
+    transport: { targets }
+  })
+}
+
+/** Create a child logger with component context */
+export function createComponentLogger(parentLogger: Logger, component: string): Logger {
+  return parentLogger.child({ component })
+}
+
+/** Generate a unique request ID */
+export function generateRequestId(): string {
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`
+}
+
+/** Create a child logger with request ID context */
+export function createRequestLogger(parentLogger: Logger, requestId: string): Logger {
+  return parentLogger.child({ requestId })
+}

package/src/utils/phase12-helper.ts

@@ -0,0 +1,56 @@
+/**
+ * Phase 12 Helper
+ * Utilities for checking Phase 12 availability
+ * Allows Phase 6.5 to gracefully degrade if Phase 12 isn't fully implemented
+ */
+
+import type { Phase12Manager } from '@/phase12'
+
+// Cache for Phase 12 availability check
+let phase12Available: boolean | null = null
+
+/**
+ * Check if Phase 12 features are available
+ */
+export function isPhase12Available(): boolean {
+  if (phase12Available !== null) {
+    return phase12Available
+  }
+
+  try {
+    // Check if the module can be loaded
+    require('@/phase12')
+    phase12Available = true
+    return true
+  } catch {
+    phase12Available = false
+    return false
+  }
+}
+
+/**
+ * Get Phase 12 instance if available
+ * Returns null if Phase 12 is not available or not initialized
+ */
+export function getPhase12Instance(): Phase12Manager | null {
+  try {
+    // Import the service getter
+    const { getPhase12Service, isServicesInitialized } = require('@/server/services')
+
+    if (!isServicesInitialized()) {
+      return null
+    }
+
+    return getPhase12Service()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Reset the Phase 12 availability cache
+ * Useful for testing
+ */
+export function resetPhase12Cache(): void {
+  phase12Available = null
+}

package/src/utils/retry.ts

@@ -0,0 +1,94 @@
+import type { Logger } from 'pino'
+
+export interface RetryOptions {
+  maxRetries: number
+  initialDelay: number
+  maxDelay: number
+  backoffMultiplier: number
+  retryCondition?: (error: Error) => boolean
+  onRetry?: (error: Error, attempt: number) => void
+}
+
+export class RetryManager {
+  private logger: Logger
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'retry-manager' })
+  }
+
+  async execute<T>(
+    fn: () => Promise<T>,
+    options: Partial<RetryOptions> = {}
+  ): Promise<T> {
+    const opts: RetryOptions = {
+      maxRetries: 3,
+      initialDelay: 1000,
+      maxDelay: 30000,
+      backoffMultiplier: 2,
+      ...options
+    }
+
+    let lastError: Error | undefined
+    let attempt = 0
+
+    while (attempt <= opts.maxRetries) {
+      try {
+        return await fn()
+
+      } catch (error) {
+        lastError = error as Error
+        attempt++
+
+        if (attempt > opts.maxRetries) {
+          this.logger.error(
+            { error: lastError, attempts: attempt },
+            'Max retries exceeded'
+          )
+          throw lastError
+        }
+
+        if (opts.retryCondition && !opts.retryCondition(lastError)) {
+          this.logger.debug(
+            { error: lastError },
+            'Retry condition not met, not retrying'
+          )
+          throw lastError
+        }
+
+        const delay = Math.min(
+          opts.initialDelay * Math.pow(opts.backoffMultiplier, attempt - 1),
+          opts.maxDelay
+        )
+
+        this.logger.info(
+          { error: lastError.message, attempt, delay },
+          'Retrying after delay'
+        )
+
+        if (opts.onRetry) {
+          opts.onRetry(lastError, attempt)
+        }
+
+        await this.sleep(delay)
+      }
+    }
+
+    throw lastError!
+  }
+
+  static isRetryableError(error: Error): boolean {
+    if (error.message.includes('ECONNREFUSED')) return true
+    if (error.message.includes('ETIMEDOUT')) return true
+    if (error.message.includes('ENOTFOUND')) return true
+    if (error.message.includes('SQLITE_BUSY')) return true
+    if (error.message.includes('database is locked')) return true
+    if (error.message.includes('EBUSY')) return true
+    if (error.message.includes('EMFILE')) return true
+
+    return false
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms))
+  }
+}

package/src/utils/transaction.ts

@@ -0,0 +1,63 @@
+import type { Logger } from 'pino'
+
+export class TransactionManager {
+  private logger: Logger
+  private operations: Array<() => Promise<void>> = []
+  private rollbacks: Array<() => Promise<void>> = []
+
+  constructor(logger: Logger) {
+    this.logger = logger.child({ component: 'transaction-manager' })
+  }
+
+  add(
+    operation: () => Promise<void>,
+    rollback: () => Promise<void>
+  ): void {
+    this.operations.push(operation)
+    this.rollbacks.unshift(rollback)
+  }
+
+  async execute(): Promise<void> {
+    const executedCount = 0
+
+    try {
+      for (let i = 0; i < this.operations.length; i++) {
+        await this.operations[i]()
+      }
+
+      this.logger.info(
+        { operationCount: this.operations.length },
+        'Transaction completed successfully'
+      )
+
+    } catch (error) {
+      this.logger.error(
+        { error, executedCount },
+        'Transaction failed, rolling back'
+      )
+
+      await this.rollback()
+      throw error
+    }
+  }
+
+  private async rollback(): Promise<void> {
+    for (const rollback of this.rollbacks) {
+      try {
+        await rollback()
+      } catch (error) {
+        this.logger.error(
+          { error },
+          'Rollback operation failed'
+        )
+      }
+    }
+
+    this.logger.info('Rollback completed')
+  }
+
+  clear(): void {
+    this.operations = []
+    this.rollbacks = []
+  }
+}