markupr 2.1.8 → 2.5.0

package/src/main/ErrorHandler.ts

@@ -1,703 +0,0 @@
-/**
- * ErrorHandler - Centralized Error Management for markupr
- *
- * Provides:
- * - Categorized error handling (permission, API key, network, capture, critical)
- * - User-friendly error dialogs and notifications
- * - Persistent logging to disk for debugging
- * - Recovery suggestions and system preferences access
- */
-
-import { app, dialog, shell, BrowserWindow, Notification } from 'electron';
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { IPC_CHANNELS } from '../shared/types';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface ErrorContext {
-  component: string;
-  operation: string;
-  data?: Record<string, unknown>;
-}
-
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-
-export interface LogEntry {
-  timestamp: string;
-  level: LogLevel;
-  message: string;
-  component?: string;
-  operation?: string;
-  data?: Record<string, unknown>;
-  error?: string;
-  stack?: string;
-}
-
-export type ErrorCategory =
-  | 'permission'
-  | 'api_key'
-  | 'network'
-  | 'capture'
-  | 'transcription'
-  | 'audio'
-  | 'file'
-  | 'unknown';
-
-// ============================================================================
-// Constants
-// ============================================================================
-
-const MAX_LOG_SIZE_BYTES = 5 * 1024 * 1024; // 5MB
-const MAX_LOG_LINES = 10000;
-const LOG_ROTATION_CHECK_INTERVAL_MS = 60000; // Check every minute
-
-// ============================================================================
-// ErrorHandler Class
-// ============================================================================
-
-class ErrorHandler {
-  private logPath: string;
-  private mainWindow: BrowserWindow | null = null;
-  private logBuffer: string[] = [];
-  private flushTimer: NodeJS.Timeout | null = null;
-  private rotationTimer: NodeJS.Timeout | null = null;
-  private isInitialized: boolean = false;
-
-  constructor() {
-    this.logPath = path.join(app.getPath('logs'), 'markupr.log');
-  }
-
-  /**
-   * Initialize the error handler
-   */
-  async initialize(): Promise<void> {
-    if (this.isInitialized) return;
-
-    try {
-      // Ensure log directory exists
-      const logDir = path.dirname(this.logPath);
-      await fs.mkdir(logDir, { recursive: true });
-
-      // Start log rotation check
-      this.rotationTimer = setInterval(
-        () => this.checkLogRotation(),
-        LOG_ROTATION_CHECK_INTERVAL_MS
-      );
-
-      // Start flush timer for buffered logs
-      this.flushTimer = setInterval(() => this.flushLogs(), 5000);
-
-      this.isInitialized = true;
-      this.log('info', 'ErrorHandler initialized', { component: 'ErrorHandler' });
-    } catch (error) {
-      console.error('[ErrorHandler] Failed to initialize:', error);
-    }
-  }
-
-  /**
-   * Set the main window for IPC communication
-   */
-  setMainWindow(window: BrowserWindow): void {
-    this.mainWindow = window;
-  }
-
-  // ==========================================================================
-  // Permission Errors
-  // ==========================================================================
-
-  /**
-   * Handle permission errors and guide user to system settings
-   */
-  async handlePermissionError(type: 'microphone' | 'screen'): Promise<boolean> {
-    const messages = {
-      microphone: {
-        title: 'Microphone Access Required',
-        message: 'markupr needs microphone access to capture your voice feedback.',
-        detail:
-          'Click "Open Settings" to grant microphone permission in System Settings.' +
-          '\n\nAfter enabling, you may need to restart the app.',
-        pane: 'Privacy_Microphone',
-      },
-      screen: {
-        title: 'Screen Recording Required',
-        message: 'markupr needs screen recording permission to capture screenshots.',
-        detail:
-          'Click "Open Settings" to grant screen recording permission in System Settings.' +
-          '\n\nYou will need to restart the app after enabling.',
-        pane: 'Privacy_ScreenCapture',
-      },
-    };
-
-    const config = messages[type];
-
-    this.log('warn', `Permission denied: ${type}`, {
-      component: 'ErrorHandler',
-      operation: 'handlePermissionError',
-      data: { permissionType: type },
-    });
-
-    const { response } = await dialog.showMessageBox({
-      type: 'warning',
-      buttons: ['Open Settings', 'Cancel'],
-      defaultId: 0,
-      cancelId: 1,
-      title: config.title,
-      message: config.message,
-      detail: config.detail,
-    });
-
-    if (response === 0) {
-      // Open system preferences
-      if (process.platform === 'darwin') {
-        await shell.openExternal(
-          `x-apple.systempreferences:com.apple.preference.security?${config.pane}`
-        );
-        this.log('info', `Opened system preferences for ${type}`);
-      } else if (process.platform === 'win32') {
-        // Windows: Open Settings app to privacy section
-        await shell.openExternal('ms-settings:privacy-microphone');
-      }
-      return true;
-    }
-
-    return false;
-  }
-
-  // ==========================================================================
-  // API Key Errors
-  // ==========================================================================
-
-  /**
-   * Handle API key errors - invalid, missing, or expired
-   */
-  handleApiKeyError(error?: Error): void {
-    const errorMessage = error?.message || 'API key validation failed';
-
-    this.log('error', 'API key error', {
-      component: 'ErrorHandler',
-      operation: 'handleApiKeyError',
-      error: errorMessage,
-    });
-
-    // Notify renderer to show settings
-    this.emitToRenderer(IPC_CHANNELS.SHOW_SETTINGS, { tab: 'api-key' });
-
-    // Show notification
-    this.notifyUser('API Key Invalid', 'Please check your OpenAI API key in settings.');
-
-    // Also show dialog for critical operations
-    dialog.showMessageBox({
-      type: 'warning',
-      title: 'API Key Required',
-      message: 'Your OpenAI API key is missing or invalid.',
-      detail:
-        'markupr uses OpenAI for post-session narration transcription. ' +
-        'Please enter a valid API key in Settings.\n\n' +
-        'Create a key at platform.openai.com/api-keys',
-      buttons: ['Open Settings', 'OK'],
-      defaultId: 0,
-    }).then(({ response }) => {
-      if (response === 0) {
-        this.emitToRenderer(IPC_CHANNELS.SHOW_SETTINGS, { tab: 'api-key' });
-      }
-    });
-  }
-
-  // ==========================================================================
-  // Network Errors
-  // ==========================================================================
-
-  /**
-   * Handle network errors with user-friendly messaging
-   */
-  handleNetworkError(error: Error, context: ErrorContext): void {
-    this.log('error', 'Network error', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      data: context.data,
-    });
-
-    // Emit to renderer for UI updates
-    this.emitToRenderer(IPC_CHANNELS.NETWORK_ERROR, {
-      message: 'Connection issue detected',
-      isBuffering: true,
-    });
-
-    // Show non-intrusive notification
-    this.notifyUser(
-      'Connection Issue',
-      'Check your internet connection. Audio is being buffered locally.'
-    );
-  }
-
-  /**
-   * Handle network recovery
-   */
-  handleNetworkRecovery(): void {
-    this.log('info', 'Network connection restored', {
-      component: 'ErrorHandler',
-      operation: 'handleNetworkRecovery',
-    });
-
-    this.emitToRenderer(IPC_CHANNELS.NETWORK_RESTORED, {});
-    this.notifyUser('Connection Restored', 'Transcription service reconnected.');
-  }
-
-  // ==========================================================================
-  // Capture Errors
-  // ==========================================================================
-
-  /**
-   * Handle screen capture errors
-   * These are usually non-critical - we can continue the session
-   */
-  handleCaptureError(error: Error, context: ErrorContext): void {
-    this.log('warn', 'Capture failed', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      data: context.data,
-    });
-
-    // Don't show notification for capture errors - they're expected sometimes
-    // (e.g., window closed, minimized, etc.)
-
-    // Just emit to renderer for potential UI feedback
-    this.emitToRenderer(IPC_CHANNELS.CAPTURE_WARNING, {
-      message: 'Screenshot capture skipped',
-      reason: error.message,
-    });
-  }
-
-  // ==========================================================================
-  // Audio Errors
-  // ==========================================================================
-
-  /**
-   * Handle audio capture errors
-   */
-  handleAudioError(error: Error, context: ErrorContext): void {
-    this.log('error', 'Audio error', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      data: context.data,
-    });
-
-    // Check if it's a permission error
-    if (
-      error.message.includes('permission') ||
-      error.message.includes('denied') ||
-      error.message.includes('NotAllowedError')
-    ) {
-      this.handlePermissionError('microphone');
-      return;
-    }
-
-    // Check if it's a device error
-    if (
-      error.message.includes('device') ||
-      error.message.includes('NotFoundError') ||
-      error.message.includes('NotReadableError')
-    ) {
-      this.notifyUser(
-        'Microphone Error',
-        'Could not access microphone. Please check your audio device.'
-      );
-      return;
-    }
-
-    // Generic audio error
-    this.emitToRenderer(IPC_CHANNELS.AUDIO_ERROR, {
-      message: error.message,
-    });
-  }
-
-  // ==========================================================================
-  // Transcription Errors
-  // ==========================================================================
-
-  /**
-   * Handle transcription service errors
-   */
-  handleTranscriptionError(error: Error, context: ErrorContext): void {
-    this.log('error', 'Transcription error', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      data: context.data,
-    });
-
-    // Check for auth errors
-    if (this.isAuthError(error)) {
-      this.handleApiKeyError(error);
-      return;
-    }
-
-    // Check for rate limit errors
-    if (this.isRateLimitError(error)) {
-      this.notifyUser('Rate Limited', 'Too many requests. Please wait a moment before retrying.');
-      return;
-    }
-
-    // Network errors
-    if (this.isNetworkError(error)) {
-      this.handleNetworkError(error, context);
-      return;
-    }
-
-    // Generic transcription error
-    this.emitToRenderer(IPC_CHANNELS.TRANSCRIPTION_ERROR, {
-      message: 'Transcription service error',
-      detail: error.message,
-    });
-  }
-
-  // ==========================================================================
-  // File System Errors
-  // ==========================================================================
-
-  /**
-   * Handle file system errors
-   */
-  handleFileError(error: Error, context: ErrorContext): void {
-    this.log('error', 'File system error', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      data: context.data,
-    });
-
-    const nodeError = error as NodeJS.ErrnoException;
-
-    switch (nodeError.code) {
-      case 'ENOENT':
-        this.notifyUser('File Not Found', 'The requested file or directory does not exist.');
-        break;
-      case 'EACCES':
-      case 'EPERM':
-        this.notifyUser(
-          'Permission Denied',
-          'Cannot access this file. Check folder permissions.'
-        );
-        break;
-      case 'ENOSPC':
-        this.notifyUser(
-          'Disk Full',
-          'Not enough disk space. Please free up some space and try again.'
-        );
-        break;
-      default:
-        this.notifyUser('File Error', `Could not complete file operation: ${error.message}`);
-    }
-  }
-
-  // ==========================================================================
-  // Critical Errors
-  // ==========================================================================
-
-  /**
-   * Handle critical errors that require app restart
-   */
-  handleCriticalError(error: Error, context: ErrorContext): void {
-    this.log('error', 'CRITICAL ERROR', {
-      component: context.component,
-      operation: context.operation,
-      error: error.message,
-      stack: error.stack,
-      data: context.data,
-    });
-
-    // Flush logs immediately
-    this.flushLogs();
-
-    // Show blocking dialog
-    dialog
-      .showMessageBox({
-        type: 'error',
-        title: 'Something Went Wrong',
-        message: `An error occurred in ${context.component}`,
-        detail:
-          `${error.message}\n\n` +
-          'Your session data has been saved.\n' +
-          'Please restart the app to continue.',
-        buttons: ['Restart', 'Quit'],
-        defaultId: 0,
-        cancelId: 1,
-      })
-      .then(({ response }) => {
-        if (response === 0) {
-          app.relaunch();
-        }
-        app.quit();
-      });
-  }
-
-  // ==========================================================================
-  // Notifications
-  // ==========================================================================
-
-  /**
-   * Show a non-blocking notification to the user
-   */
-  notifyUser(title: string, message: string): void {
-    // First try to use renderer notification
-    this.emitToRenderer(IPC_CHANNELS.NOTIFICATION, { title, message });
-
-    // Also show system notification if supported
-    if (Notification.isSupported()) {
-      new Notification({
-        title: `markupr: ${title}`,
-        body: message,
-        silent: true,
-      }).show();
-    }
-  }
-
-  // ==========================================================================
-  // Logging
-  // ==========================================================================
-
-  /**
-   * Log a message with context
-   */
-  log(
-    level: LogLevel,
-    message: string,
-    context?: Partial<ErrorContext> & { error?: string; stack?: string }
-  ): void {
-    const entry: LogEntry = {
-      timestamp: new Date().toISOString(),
-      level,
-      message,
-      component: context?.component,
-      operation: context?.operation,
-      data: context?.data,
-      error: context?.error,
-      stack: context?.stack,
-    };
-
-    // Console output with color
-    const colors = {
-      debug: '\x1b[90m', // gray
-      info: '\x1b[36m', // cyan
-      warn: '\x1b[33m', // yellow
-      error: '\x1b[31m', // red
-    };
-    const reset = '\x1b[0m';
-    const prefix = `${colors[level]}[${level.toUpperCase()}]${reset}`;
-    const componentStr = context?.component ? ` [${context.component}]` : '';
-
-    console.log(`${prefix}${componentStr} ${message}`, context?.data || '');
-
-    // Buffer for file output
-    this.logBuffer.push(JSON.stringify(entry));
-
-    // Flush immediately on error
-    if (level === 'error') {
-      this.flushLogs();
-    }
-  }
-
-  /**
-   * Flush buffered logs to disk
-   */
-  private async flushLogs(): Promise<void> {
-    if (this.logBuffer.length === 0) return;
-
-    const logs = this.logBuffer.splice(0);
-
-    try {
-      await fs.appendFile(this.logPath, logs.join('\n') + '\n', 'utf-8');
-    } catch (error) {
-      // Log write failure - output to console only
-      console.error('[ErrorHandler] Failed to write logs:', error);
-    }
-  }
-
-  /**
-   * Check if log rotation is needed
-   */
-  private async checkLogRotation(): Promise<void> {
-    try {
-      const stats = await fs.stat(this.logPath);
-
-      if (stats.size > MAX_LOG_SIZE_BYTES) {
-        await this.rotateLogs();
-      }
-    } catch (error) {
-      // File doesn't exist yet or other error - ignore
-    }
-  }
-
-  /**
-   * Rotate logs - keep last N lines
-   */
-  private async rotateLogs(): Promise<void> {
-    try {
-      const content = await fs.readFile(this.logPath, 'utf-8');
-      const lines = content.split('\n');
-
-      if (lines.length > MAX_LOG_LINES) {
-        // Keep last MAX_LOG_LINES/2 lines
-        const keepLines = lines.slice(-(MAX_LOG_LINES / 2));
-        await fs.writeFile(this.logPath, keepLines.join('\n'), 'utf-8');
-        this.log('info', 'Log file rotated', { component: 'ErrorHandler' });
-      }
-    } catch (error) {
-      console.error('[ErrorHandler] Log rotation failed:', error);
-    }
-  }
-
-  /**
-   * Get recent logs for error reporting
-   */
-  async getRecentLogs(lines: number = 100): Promise<LogEntry[]> {
-    try {
-      const content = await fs.readFile(this.logPath, 'utf-8');
-      const logLines = content.trim().split('\n').slice(-lines);
-
-      return logLines
-        .filter((line) => line.trim())
-        .map((line) => {
-          try {
-            return JSON.parse(line) as LogEntry;
-          } catch {
-            return { timestamp: '', level: 'info' as LogLevel, message: line };
-          }
-        });
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Get log file path for support
-   */
-  getLogPath(): string {
-    return this.logPath;
-  }
-
-  // ==========================================================================
-  // Error Classification Helpers
-  // ==========================================================================
-
-  private isAuthError(error: Error): boolean {
-    const message = error.message.toLowerCase();
-    return (
-      message.includes('401') ||
-      message.includes('unauthorized') ||
-      message.includes('invalid api key') ||
-      message.includes('authentication') ||
-      message.includes('forbidden')
-    );
-  }
-
-  private isRateLimitError(error: Error): boolean {
-    const message = error.message.toLowerCase();
-    return (
-      message.includes('429') || message.includes('rate limit') || message.includes('too many')
-    );
-  }
-
-  private isNetworkError(error: Error): boolean {
-    const message = error.message.toLowerCase();
-    return (
-      message.includes('network') ||
-      message.includes('connection') ||
-      message.includes('timeout') ||
-      message.includes('econnrefused') ||
-      message.includes('enotfound') ||
-      message.includes('socket')
-    );
-  }
-
-  /**
-   * Categorize an error for logging/reporting
-   */
-  categorizeError(error: Error): ErrorCategory {
-    const message = error.message.toLowerCase();
-
-    if (message.includes('permission') || message.includes('denied')) {
-      return 'permission';
-    }
-    if (this.isAuthError(error)) {
-      return 'api_key';
-    }
-    if (this.isNetworkError(error)) {
-      return 'network';
-    }
-    if (message.includes('capture') || message.includes('screenshot')) {
-      return 'capture';
-    }
-    if (message.includes('transcri')) {
-      return 'transcription';
-    }
-    if (
-      message.includes('audio') ||
-      message.includes('microphone') ||
-      message.includes('media')
-    ) {
-      return 'audio';
-    }
-    if (
-      message.includes('file') ||
-      message.includes('directory') ||
-      message.includes('enoent') ||
-      message.includes('eacces')
-    ) {
-      return 'file';
-    }
-
-    return 'unknown';
-  }
-
-  // ==========================================================================
-  // IPC Helper
-  // ==========================================================================
-
-  /**
-   * Send event to renderer
-   */
-  private emitToRenderer(channel: string, data: unknown): void {
-    if (this.mainWindow && !this.mainWindow.isDestroyed()) {
-      this.mainWindow.webContents.send(channel, data);
-    }
-  }
-
-  // ==========================================================================
-  // Cleanup
-  // ==========================================================================
-
-  /**
-   * Clean up resources
-   */
-  async destroy(): Promise<void> {
-    if (this.flushTimer) {
-      clearInterval(this.flushTimer);
-      this.flushTimer = null;
-    }
-
-    if (this.rotationTimer) {
-      clearInterval(this.rotationTimer);
-      this.rotationTimer = null;
-    }
-
-    // Final log flush
-    await this.flushLogs();
-
-    this.mainWindow = null;
-    this.isInitialized = false;
-  }
-}
-
-// ============================================================================
-// Singleton Export
-// ============================================================================
-
-export const errorHandler = new ErrorHandler();
-export default ErrorHandler;