@superdangerous/app-framework 4.9.0

package/src/logging/LogCategories.ts

@@ -0,0 +1,302 @@
+/**
+ * Log Categories System
+ * Provides a declarative way to define log categories with automatic UI generation
+ */
+
+export interface LogLevel {
+  name: "error" | "warn" | "info" | "debug" | "verbose";
+  color: string;
+  badge: string;
+  priority: number;
+}
+
+export const LogLevels: Record<string, LogLevel> = {
+  error: {
+    name: "error",
+    color: "text-red-600 dark:text-red-400",
+    badge: "bg-red-600 text-white",
+    priority: 0,
+  },
+  warn: {
+    name: "warn",
+    color: "text-amber-600 dark:text-amber-400",
+    badge: "bg-amber-500 text-white",
+    priority: 1,
+  },
+  info: {
+    name: "info",
+    color: "text-blue-600 dark:text-blue-400",
+    badge: "bg-blue-600 text-white",
+    priority: 2,
+  },
+  debug: {
+    name: "debug",
+    color: "text-gray-600 dark:text-gray-400",
+    badge: "bg-gray-600 text-white",
+    priority: 3,
+  },
+  verbose: {
+    name: "verbose",
+    color: "text-gray-500 dark:text-gray-500",
+    badge: "bg-gray-500 text-white",
+    priority: 4,
+  },
+};
+
+export interface LogCategory {
+  id: string;
+  label: string;
+  description?: string;
+  color?: string;
+  icon?: string;
+  enabled?: boolean;
+}
+
+export interface LogFilter {
+  levels?: string[];
+  categories?: string[];
+  search?: string;
+  startDate?: Date;
+  endDate?: Date;
+}
+
+export interface LogViewerConfig {
+  categories: LogCategory[];
+  defaultLevel: string;
+  maxLogEntries: number;
+  enableRealtime: boolean;
+  enableExport: boolean;
+  enableArchives: boolean;
+  archiveRetentionDays: number;
+  horizontalScroll: boolean;
+  timestampFormat: string;
+  showCategories: boolean;
+  showMetadata: boolean;
+  theme?: "light" | "dark" | "system";
+}
+
+/**
+ * Default log viewer configuration
+ */
+export const defaultLogViewerConfig: LogViewerConfig = {
+  categories: [
+    {
+      id: "system",
+      label: "System",
+      description: "Core system operations",
+      enabled: true,
+    },
+    {
+      id: "api",
+      label: "API",
+      description: "API requests and responses",
+      enabled: true,
+    },
+    {
+      id: "auth",
+      label: "Authentication",
+      description: "Authentication and authorization",
+      enabled: true,
+    },
+    {
+      id: "database",
+      label: "Database",
+      description: "Database operations",
+      enabled: true,
+    },
+    {
+      id: "service",
+      label: "Services",
+      description: "Background services",
+      enabled: true,
+    },
+  ],
+  defaultLevel: "info",
+  maxLogEntries: 1000,
+  enableRealtime: true,
+  enableExport: true,
+  enableArchives: true,
+  archiveRetentionDays: 7,
+  horizontalScroll: true,
+  timestampFormat: "YYYY-MM-DD HH:mm:ss.SSS",
+  showCategories: true,
+  showMetadata: true,
+  theme: "system",
+};
+
+/**
+ * Log entry interface
+ */
+export interface LogEntry {
+  id: string;
+  timestamp: string;
+  level: keyof typeof LogLevels;
+  category?: string;
+  message: string;
+  metadata?: Record<string, any>;
+  source?: string;
+  userId?: string;
+  sessionId?: string;
+  requestId?: string;
+  stack?: string;
+}
+
+/**
+ * Log aggregation for summary statistics
+ */
+export interface LogStats {
+  total: number;
+  byLevel: Record<string, number>;
+  byCategory: Record<string, number>;
+  errorRate: number;
+  warnRate: number;
+}
+
+/**
+ * Helper to parse log entries from different formats
+ */
+export function parseLogEntry(raw: string | object): LogEntry | null {
+  try {
+    if (typeof raw === "string") {
+      // Try to parse JSON log format
+      if (raw.trim().startsWith("{")) {
+        return JSON.parse(raw);
+      }
+
+      // Parse text log format: "2023-10-20 10:30:45.123 [INFO] [Category] Message"
+      const match = raw.match(
+        /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+\[(\w+)\]\s+(?:\[([^\]]+)\]\s+)?(.*)$/,
+      );
+      if (match) {
+        const [, timestamp, level, category, message] = match;
+        return {
+          id: `${Date.now()}-${Math.random()}`,
+          timestamp: timestamp || "",
+          level: (level?.toLowerCase() || "info") as keyof typeof LogLevels,
+          category: category || "",
+          message: message || "",
+        };
+      }
+    } else if (typeof raw === "object") {
+      return raw as LogEntry;
+    }
+  } catch (_error) {
+    console.error("Failed to parse log entry:", _error);
+  }
+
+  return null;
+}
+
+/**
+ * Helper to format log entries for display
+ */
+export function formatLogEntry(
+  entry: LogEntry,
+  format: "full" | "compact" = "full",
+): string {
+  if (format === "compact") {
+    return `${entry.timestamp} [${entry.level.toUpperCase()}] ${entry.message}`;
+  }
+
+  let formatted = `${entry.timestamp} [${entry.level.toUpperCase()}]`;
+  if (entry.category) {
+    formatted += ` [${entry.category}]`;
+  }
+  formatted += ` ${entry.message}`;
+
+  if (entry.metadata && Object.keys(entry.metadata).length > 0) {
+    formatted += "\n  Metadata: " + JSON.stringify(entry.metadata, null, 2);
+  }
+
+  if (entry.stack) {
+    formatted += "\n  Stack: " + entry.stack;
+  }
+
+  return formatted;
+}
+
+/**
+ * Calculate log statistics
+ */
+export function calculateLogStats(entries: LogEntry[]): LogStats {
+  const stats: LogStats = {
+    total: entries.length,
+    byLevel: {},
+    byCategory: {},
+    errorRate: 0,
+    warnRate: 0,
+  };
+
+  for (const entry of entries) {
+    // Count by level
+    stats.byLevel[entry.level] = (stats.byLevel[entry.level] || 0) + 1;
+
+    // Count by category
+    if (entry.category) {
+      stats.byCategory[entry.category] =
+        (stats.byCategory[entry.category] || 0) + 1;
+    }
+  }
+
+  // Calculate rates
+  if (stats.total > 0) {
+    stats.errorRate = (stats.byLevel.error || 0) / stats.total;
+    stats.warnRate = (stats.byLevel.warn || 0) / stats.total;
+  }
+
+  return stats;
+}
+
+/**
+ * Filter log entries
+ */
+export function filterLogEntries(
+  entries: LogEntry[],
+  filter: LogFilter,
+): LogEntry[] {
+  return entries.filter((entry) => {
+    // Filter by level
+    if (
+      filter.levels &&
+      filter.levels.length > 0 &&
+      !filter.levels.includes(entry.level)
+    ) {
+      return false;
+    }
+
+    // Filter by category
+    if (
+      filter.categories &&
+      filter.categories.length > 0 &&
+      entry.category &&
+      !filter.categories.includes(entry.category)
+    ) {
+      return false;
+    }
+
+    // Filter by search term
+    if (filter.search) {
+      const searchLower = filter.search.toLowerCase();
+      const inMessage = entry.message.toLowerCase().includes(searchLower);
+      const inCategory = entry.category?.toLowerCase().includes(searchLower);
+      const inMetadata = entry.metadata
+        ? JSON.stringify(entry.metadata).toLowerCase().includes(searchLower)
+        : false;
+
+      if (!inMessage && !inCategory && !inMetadata) {
+        return false;
+      }
+    }
+
+    // Filter by date range
+    const entryDate = new Date(entry.timestamp);
+    if (filter.startDate && entryDate < filter.startDate) {
+      return false;
+    }
+    if (filter.endDate && entryDate > filter.endDate) {
+      return false;
+    }
+
+    return true;
+  });
+}

package/src/middleware/aiErrorHandler.ts

@@ -0,0 +1,278 @@
+/**
+ * AI Error Handler Middleware
+ * Provides user-friendly error messages for AI API errors
+ */
+
+import { Request, Response, NextFunction } from "express";
+import { createLogger } from "../core/index.js";
+import { ApiResponse } from "../types/index.js";
+import { sendError, sendUnauthorized } from "../core/apiResponse.js";
+import { AIError } from "../services/aiService.js";
+
+let logger: any; // Will be initialized when needed
+
+function ensureLogger() {
+  if (!logger) {
+    logger = createLogger("AIError");
+  }
+  return logger;
+}
+
+interface AIErrorResponse {
+  error: string;
+  details?: string[];
+  action?: string;
+  retryAfter?: number;
+  code?: string;
+}
+
+/**
+ * AI-specific error handler middleware
+ */
+export function aiErrorHandler(
+  err: any,
+  _req: Request,
+  res: Response<ApiResponse<any>>,
+  next: NextFunction,
+): void {
+  // Only handle AI-related errors
+  if (!_req.path.startsWith("/api/ai/")) {
+    return next(err);
+  }
+
+  ensureLogger().error("AI Error:", {
+    path: _req.path,
+    method: _req.method,
+    error: err.message,
+    status: err.statusCode || err.status,
+    stack: err.stack,
+    errorType: err.errorType,
+    provider: err.provider,
+  });
+
+  // Handle our custom AIError instances
+  if (err instanceof AIError) {
+    const response: AIErrorResponse = {
+      error: err.message,
+      code: err.errorType,
+    };
+
+    // Add provider-specific information
+    if (err.provider) {
+      response.details = [`Provider: ${err.provider}`];
+    }
+
+    // Handle specific error types
+    switch (err.errorType) {
+      case "AUTH_ERROR":
+        sendUnauthorized(res, err.message);
+        return;
+      case "RATE_LIMIT":
+        sendError(res, err.message, 429, { retryAfter: 60 });
+        return;
+      case "SERVICE_UNAVAILABLE":
+        sendError(res, err.message, 503);
+        return;
+      case "TIMEOUT":
+        sendError(res, err.message, 408);
+        return;
+      default:
+        sendError(res, err.message, err.statusCode, response);
+        return;
+    }
+  }
+
+  // Handle legacy structured AI errors with user-friendly messages
+  if (err.userMessage) {
+    const response: AIErrorResponse = {
+      error: err.userMessage,
+    };
+
+    if (err.details) {
+      response.details = err.details;
+    }
+
+    if (err.actionRequired) {
+      response.action = err.actionRequired;
+    }
+
+    if (err.code) {
+      response.code = err.code;
+    }
+
+    sendError(res, err.userMessage, err.status || 500, {
+      details: err.details,
+      action: err.actionRequired,
+      code: err.code,
+    });
+    return;
+  }
+
+  // Handle OpenAI specific errors
+  if (err.message && err.message.includes("401")) {
+    sendUnauthorized(
+      res,
+      "OpenAI API authentication failed: Invalid or missing API key. Check your OpenAI API key configuration",
+    );
+    return;
+  }
+
+  if (err.message && err.message.includes("429")) {
+    sendError(
+      res,
+      "OpenAI API rate limit exceeded: Too many requests. Please wait a moment before trying again",
+      429,
+    );
+    return;
+  }
+
+  if (err.message && err.message.includes("insufficient_quota")) {
+    sendError(
+      res,
+      "OpenAI API quota exceeded: Your account has insufficient quota. Check your OpenAI account billing and usage limits",
+      402,
+    );
+    return;
+  }
+
+  // Handle Anthropic specific errors
+  if (err.message && err.message.includes("anthropic")) {
+    if (err.message.includes("401")) {
+      sendUnauthorized(
+        res,
+        "Anthropic API authentication failed: Invalid or missing API key",
+      );
+      return;
+    }
+
+    if (err.message.includes("rate")) {
+      sendError(
+        res,
+        "Anthropic API rate limit exceeded: Too many requests",
+        429,
+      );
+      return;
+    }
+  }
+
+  // Handle JSON parse errors
+  if (err.message && err.message.includes("JSON")) {
+    sendError(
+      res,
+      "Failed to generate valid template format: The AI response was not in the expected format",
+      500,
+    );
+    return;
+  }
+
+  // Handle missing required fields
+  if (err.message && err.message.includes("missing required fields")) {
+    sendError(
+      res,
+      "Generated template is incomplete: Missing required fields",
+      500,
+    );
+    return;
+  }
+
+  // Handle API key errors
+  if (err.message && err.message.includes("API key")) {
+    sendUnauthorized(
+      res,
+      "AI API key not configured: Please configure your API key",
+    );
+    return;
+  }
+
+  // Handle timeout errors
+  if (
+    err.message &&
+    (err.message.includes("timeout") || err.message.includes("ETIMEDOUT"))
+  ) {
+    sendError(
+      res,
+      "AI request timed out: The request took too long to complete",
+      504,
+    );
+    return;
+  }
+
+  // Handle network errors
+  if (
+    err.message &&
+    (err.message.includes("ECONNREFUSED") || err.message.includes("ENOTFOUND"))
+  ) {
+    sendError(res, "AI service unavailable: Cannot connect to AI service", 503);
+    return;
+  }
+
+  // Default error response
+  sendError(
+    res,
+    err.message || "An error occurred while processing your AI request",
+    err.status || 500,
+  );
+}
+
+/**
+ * Rate limit handler for AI endpoints
+ */
+export function aiRateLimitHandler(
+  _req: Request,
+  res: Response<ApiResponse<any>>,
+): void {
+  sendError(
+    res,
+    "Too many AI requests: Rate limit exceeded. Please wait a moment before trying again",
+    429,
+  );
+}
+
+/**
+ * Create AI error with user-friendly message
+ */
+export function createAIError(
+  message: string,
+  userMessage: string,
+  status: number = 500,
+  details?: string[],
+  action?: string,
+): AIError {
+  const error = new AIError(message, status, "CUSTOM_ERROR", "unknown");
+  // Additional legacy properties for compatibility
+  (error as any).userMessage = userMessage;
+  (error as any).details = details;
+  (error as any).actionRequired = action;
+  return error;
+}
+
+/**
+ * Wrap async AI handlers with error handling
+ */
+export function wrapAIHandler(
+  handler: (req: Request, res: Response, next: NextFunction) => Promise<void>,
+) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await handler(req, res, next);
+    } catch (_error: any) {
+      // Convert to AI error if needed
+      if (!_error.userMessage && _error.response?.data) {
+        // Handle API response errors
+        const apiError = _error.response.data;
+        _error.userMessage =
+          apiError.error?.message || apiError.message || "AI request failed";
+        _error.status = _error.response.status;
+        _error.details = apiError.error?.details || [apiError.error?.type];
+      }
+      next(_error);
+    }
+  };
+}
+
+export default {
+  aiErrorHandler,
+  aiRateLimitHandler,
+  createAIError,
+  wrapAIHandler,
+};