rird 2.1.231 → 2.3.0

package/src/lib/errors.ts

@@ -0,0 +1,285 @@
+/**
+ * Custom error classes for RIRD CLI production error handling
+ * Provides structured error information with user-facing messages and error codes
+ */
+
+export interface ErrorContext {
+  code: string
+  statusCode: number
+  suggestion?: string
+  details?: Record<string, any>
+  originalError?: Error
+}
+
+/**
+ * Base RIRD error class with structure for production logging
+ */
+export class RirdError extends Error implements ErrorContext {
+  code: string
+  statusCode: number
+  suggestion?: string
+  details?: Record<string, any>
+  originalError?: Error
+
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message)
+    this.name = this.constructor.name
+    this.code = context.code || "RIRD_ERROR"
+    this.statusCode = context.statusCode || 500
+    this.suggestion = context.suggestion
+    this.details = context.details
+    this.originalError = context.originalError
+
+    // Maintain proper prototype chain
+    Object.setPrototypeOf(this, RirdError.prototype)
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      suggestion: this.suggestion,
+      details: this.details,
+      stack: this.stack,
+    }
+  }
+}
+
+/**
+ * Network-related errors (timeouts, connection failures)
+ */
+export class NetworkError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "NETWORK_ERROR",
+      statusCode: 503,
+      suggestion:
+        "Check your internet connection, firewall settings, or try again later",
+      ...context,
+    })
+    Object.setPrototypeOf(this, NetworkError.prototype)
+  }
+}
+
+/**
+ * Provider/API errors (model not found, invalid endpoints, API failures)
+ */
+export class ProviderError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "PROVIDER_ERROR",
+      statusCode: 502,
+      suggestion:
+        "Verify your provider configuration and API credentials. Check rird status for details.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, ProviderError.prototype)
+  }
+}
+
+/**
+ * License/authentication errors
+ */
+export class LicenseError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "LICENSE_ERROR",
+      statusCode: 401,
+      suggestion: "Run 'rird activate <license-key>' to validate your license",
+      ...context,
+    })
+    Object.setPrototypeOf(this, LicenseError.prototype)
+  }
+}
+
+/**
+ * Input validation errors
+ */
+export class ValidationError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "VALIDATION_ERROR",
+      statusCode: 400,
+      suggestion: "Check the provided inputs and try again",
+      ...context,
+    })
+    Object.setPrototypeOf(this, ValidationError.prototype)
+  }
+}
+
+/**
+ * Configuration errors
+ */
+export class ConfigError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "CONFIG_ERROR",
+      statusCode: 500,
+      suggestion:
+        "Check your RIRD configuration file or run 'rird setup' to initialize",
+      ...context,
+    })
+    Object.setPrototypeOf(this, ConfigError.prototype)
+  }
+}
+
+/**
+ * File system errors
+ */
+export class FileSystemError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "FILESYSTEM_ERROR",
+      statusCode: 500,
+      suggestion:
+        "Check file permissions and disk space. Ensure the file path is valid.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, FileSystemError.prototype)
+  }
+}
+
+/**
+ * Timeout errors
+ */
+export class TimeoutError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "TIMEOUT_ERROR",
+      statusCode: 504,
+      suggestion: "The operation took too long. Try again or increase timeout.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, TimeoutError.prototype)
+  }
+}
+
+/**
+ * Server/process errors
+ */
+export class ServerError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "SERVER_ERROR",
+      statusCode: 500,
+      suggestion:
+        "The RIRD server encountered an error. Check logs or try restarting.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, ServerError.prototype)
+  }
+}
+
+/**
+ * Installation/upgrade errors
+ */
+export class InstallationError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "INSTALLATION_ERROR",
+      statusCode: 500,
+      suggestion:
+        "Installation failed. Ensure you have proper permissions and dependencies installed.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, InstallationError.prototype)
+  }
+}
+
+/**
+ * Tool/command execution errors
+ */
+export class ToolError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "TOOL_ERROR",
+      statusCode: 500,
+      suggestion: "A tool execution failed. Check the error details above.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, ToolError.prototype)
+  }
+}
+
+/**
+ * Browser automation errors
+ */
+export class BrowserError extends RirdError {
+  constructor(message: string, context: Partial<ErrorContext> = {}) {
+    super(message, {
+      code: "BROWSER_ERROR",
+      statusCode: 500,
+      suggestion:
+        "Browser operation failed. Ensure no other instances are running and try again.",
+      ...context,
+    })
+    Object.setPrototypeOf(this, BrowserError.prototype)
+  }
+}
+
+/**
+ * Type guard to check if an error is a RirdError
+ */
+export function isRirdError(error: unknown): error is RirdError {
+  return error instanceof RirdError
+}
+
+/**
+ * Convert any error to RirdError
+ */
+export function toRirdError(error: unknown, defaultCode = "UNKNOWN_ERROR"): RirdError {
+  if (isRirdError(error)) {
+    return error
+  }
+
+  if (error instanceof Error) {
+    // Check if this is a NamedError with data (e.g., Storage.NotFoundError)
+    const namedError = error as { data?: Record<string, unknown>; name?: string }
+    let message = error.message
+    let details: Record<string, unknown> | undefined
+
+    // NamedError stores its data in .data property
+    if (namedError.data && typeof namedError.data === "object") {
+      details = namedError.data as Record<string, unknown>
+      // Extract message from data if the error message is just the error name
+      if (namedError.data.message && typeof namedError.data.message === "string") {
+        message = namedError.data.message as string
+      } else if (error.message === error.name || !error.message) {
+        // Build a descriptive message from the data
+        message = `${error.name || defaultCode}: ${JSON.stringify(namedError.data)}`
+      }
+    }
+
+    return new RirdError(message, {
+      code: error.name || defaultCode,
+      originalError: error,
+      details,
+    })
+  }
+
+  return new RirdError(String(error), { code: defaultCode })
+}
+
+/**
+ * Format error for user-friendly display
+ */
+export function formatErrorMessage(error: RirdError): string {
+  const lines: string[] = []
+
+  lines.push(`Error [${error.code}]: ${error.message}`)
+
+  if (error.suggestion) {
+    lines.push(`Suggestion: ${error.suggestion}`)
+  }
+
+  if (error.details && Object.keys(error.details).length > 0) {
+    lines.push("Details:")
+    for (const [key, value] of Object.entries(error.details)) {
+      lines.push(`  ${key}: ${JSON.stringify(value)}`)
+    }
+  }
+
+  return lines.join("\n")
+}

package/src/lib/performance.ts

@@ -0,0 +1,70 @@
+/**
+ * Performance monitoring and profiling utilities for RIRD CLI
+ * Tracks startup time, command execution time, and memory usage
+ */
+
+const perfMarks = new Map<string, number>();
+const startTime = Date.now();
+
+export const Performance = {
+  /**
+   * Mark a performance checkpoint
+   */
+  mark(label: string) {
+    const elapsed = Date.now() - startTime;
+    perfMarks.set(label, elapsed);
+    if (process.env.RIRD_PERF_DEBUG) {
+      console.error(`[${elapsed}ms] ${label}`);
+    }
+  },
+
+  /**
+   * Get elapsed time for a mark
+   */
+  getTime(label: string): number | undefined {
+    return perfMarks.get(label);
+  },
+
+  /**
+   * Get elapsed time since startup
+   */
+  elapsed(): number {
+    return Date.now() - startTime;
+  },
+
+  /**
+   * Get current memory usage in MB
+   */
+  memoryUsage(): number {
+    const usage = process.memoryUsage();
+    return Math.round((usage.heapUsed / 1024 / 1024) * 100) / 100;
+  },
+
+  /**
+   * Report all performance metrics
+   */
+  report(): Record<string, number> {
+    const report: Record<string, number> = {};
+    perfMarks.forEach((time, label) => {
+      report[label] = time;
+    });
+    report.total = Performance.elapsed();
+    report.memory_mb = Performance.memoryUsage();
+    return report;
+  },
+
+  /**
+   * Check if startup performance is acceptable
+   * Returns null if ok, error message if slow
+   */
+  checkStartupPerformance(): string | null {
+    const total = Performance.elapsed();
+    if (total > 1000) {
+      return `Slow startup detected: ${total}ms (target: <1000ms)`;
+    }
+    return null;
+  },
+};
+
+// Mark startup
+Performance.mark("startup");

package/src/lib/telemetry.ts

@@ -0,0 +1,282 @@
+import fs from "fs/promises"
+import path from "path"
+import { Global } from "../global"
+import { Log } from "../util/log"
+
+export namespace Telemetry {
+  const log = Log.create({ service: "telemetry" })
+
+  const TELEMETRY_DIR = path.join(Global.Path.log, "telemetry")
+  const ERROR_LOG_DIR = path.join(TELEMETRY_DIR, "errors")
+  const EVENT_LOG_DIR = path.join(TELEMETRY_DIR, "events")
+  const METRICS_LOG_DIR = path.join(TELEMETRY_DIR, "metrics")
+
+  const MAX_LOG_DAYS = 7
+  const MAX_LOGS_PER_DIR = 500
+
+  interface ErrorEntry {
+    timestamp: string
+    message: string
+    error?: string
+    stack?: string
+    context?: Record<string, any>
+    severity: "error" | "warning" | "critical"
+  }
+
+  interface EventEntry {
+    timestamp: string
+    name: string
+    properties?: Record<string, any>
+    duration?: number
+  }
+
+  interface MetricEntry {
+    timestamp: string
+    name: string
+    value: number
+    unit?: string
+    context?: Record<string, any>
+  }
+
+  async function ensureDirectories() {
+    try {
+      await Promise.all([
+        fs.mkdir(TELEMETRY_DIR, { recursive: true }),
+        fs.mkdir(ERROR_LOG_DIR, { recursive: true }),
+        fs.mkdir(EVENT_LOG_DIR, { recursive: true }),
+        fs.mkdir(METRICS_LOG_DIR, { recursive: true }),
+      ])
+    } catch (e) {
+      log.warn("Failed to create telemetry directories", { error: e })
+    }
+  }
+
+  async function rotateOldLogs(dir: string) {
+    try {
+      const files = await fs.readdir(dir)
+      if (files.length > MAX_LOGS_PER_DIR) {
+        const filesToDelete = files.slice(0, files.length - MAX_LOGS_PER_DIR)
+        await Promise.all(
+          filesToDelete.map((file) =>
+            fs.unlink(path.join(dir, file)).catch(() => {})
+          )
+        )
+      }
+
+      // Also clean up logs older than MAX_LOG_DAYS
+      const now = Date.now()
+      const maxAge = MAX_LOG_DAYS * 24 * 60 * 60 * 1000
+
+      for (const file of files) {
+        const filePath = path.join(dir, file)
+        const stat = await fs.stat(filePath).catch(() => null)
+        if (stat && now - stat.mtimeMs > maxAge) {
+          await fs.unlink(filePath).catch(() => {})
+        }
+      }
+    } catch (e) {
+      log.warn("Failed to rotate old logs", { error: e })
+    }
+  }
+
+  async function writeLog(dir: string, filename: string, data: any) {
+    try {
+      await ensureDirectories()
+      const filePath = path.join(dir, filename)
+      const content = typeof data === "string" ? data : JSON.stringify(data)
+      await fs.appendFile(filePath, content + "\n")
+      await rotateOldLogs(dir)
+    } catch (e) {
+      log.warn("Failed to write telemetry log", { error: e, filename })
+    }
+  }
+
+  export async function logError(
+    message: string,
+    error?: Error | unknown,
+    context?: Record<string, any>
+  ) {
+    const timestamp = new Date().toISOString()
+    const errorObj = error instanceof Error ? error : new Error(String(error))
+
+    const entry: ErrorEntry = {
+      timestamp,
+      message,
+      error: errorObj.message,
+      stack: errorObj.stack,
+      context,
+      severity: "error",
+    }
+
+    log.error(message, { error: errorObj, ...context })
+    await writeLog(
+      ERROR_LOG_DIR,
+      `errors-${new Date().toISOString().split("T")[0]}.jsonl`,
+      entry
+    )
+  }
+
+  export async function logWarning(
+    message: string,
+    context?: Record<string, any>
+  ) {
+    const timestamp = new Date().toISOString()
+    const entry: ErrorEntry = {
+      timestamp,
+      message,
+      context,
+      severity: "warning",
+    }
+
+    log.warn(message, context)
+    await writeLog(
+      ERROR_LOG_DIR,
+      `warnings-${new Date().toISOString().split("T")[0]}.jsonl`,
+      entry
+    )
+  }
+
+  export async function logInfo(
+    message: string,
+    context?: Record<string, any>
+  ) {
+    const timestamp = new Date().toISOString()
+    log.info(message, context)
+  }
+
+  export async function logDebug(
+    message: string,
+    context?: Record<string, any>
+  ) {
+    const timestamp = new Date().toISOString()
+    log.debug(message, context)
+  }
+
+  export async function trackEvent(
+    name: string,
+    properties?: Record<string, any>,
+    duration?: number
+  ) {
+    const timestamp = new Date().toISOString()
+    const entry: EventEntry = {
+      timestamp,
+      name,
+      properties,
+      duration,
+    }
+
+    log.info(`event:${name}`, properties)
+    await writeLog(
+      EVENT_LOG_DIR,
+      `events-${new Date().toISOString().split("T")[0]}.jsonl`,
+      entry
+    )
+  }
+
+  export async function trackMetric(
+    name: string,
+    value: number,
+    unit?: string,
+    context?: Record<string, any>
+  ) {
+    const timestamp = new Date().toISOString()
+    const entry: MetricEntry = {
+      timestamp,
+      name,
+      value,
+      unit,
+      context,
+    }
+
+    log.info(`metric:${name}`, { value, unit, ...context })
+    await writeLog(
+      METRICS_LOG_DIR,
+      `metrics-${new Date().toISOString().split("T")[0]}.jsonl`,
+      entry
+    )
+  }
+
+  export async function initialize() {
+    try {
+      await ensureDirectories()
+      log.info("Telemetry initialized", { directory: TELEMETRY_DIR })
+    } catch (e) {
+      log.warn("Failed to initialize telemetry", { error: e })
+    }
+  }
+
+  export async function getLogs(
+    type: "errors" | "warnings" | "events" | "metrics" = "errors",
+    days: number = 1
+  ): Promise<string[]> {
+    try {
+      const dir =
+        type === "errors" || type === "warnings"
+          ? ERROR_LOG_DIR
+          : type === "events"
+            ? EVENT_LOG_DIR
+            : METRICS_LOG_DIR
+
+      const files = await fs.readdir(dir)
+      const now = Date.now()
+      const maxAge = days * 24 * 60 * 60 * 1000
+
+      const relevantFiles = []
+      for (const file of files) {
+        const filePath = path.join(dir, file)
+        const stat = await fs.stat(filePath).catch(() => null)
+        if (stat && now - stat.mtimeMs <= maxAge) {
+          const content = await fs.readFile(filePath, "utf-8")
+          relevantFiles.push(content)
+        }
+      }
+
+      return relevantFiles
+    } catch (e) {
+      log.warn("Failed to read telemetry logs", { error: e, type })
+      return []
+    }
+  }
+
+  export async function printLogs(
+    type: "errors" | "warnings" | "events" | "metrics" = "errors",
+    days: number = 7
+  ) {
+    const logs = await getLogs(type, days)
+    if (logs.length === 0) {
+      console.log(`No ${type} logs found for the last ${days} days`)
+      return
+    }
+
+    console.log(`\n=== ${type.toUpperCase()} LOGS (Last ${days} days) ===\n`)
+    for (const log of logs) {
+      const lines = log.split("\n").filter((l) => l.trim())
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line)
+          console.log(`[${entry.timestamp}] ${entry.message}`)
+          if (entry.error) console.log(`  Error: ${entry.error}`)
+          if (entry.stack) console.log(`  Stack: ${entry.stack}`)
+          if (entry.context) console.log(`  Context: ${JSON.stringify(entry.context)}`)
+        } catch {
+          console.log(line)
+        }
+      }
+    }
+    console.log()
+  }
+
+  export function getLogPath(type: "errors" | "warnings" | "events" | "metrics" = "errors"): string {
+    switch (type) {
+      case "errors":
+      case "warnings":
+        return ERROR_LOG_DIR
+      case "events":
+        return EVENT_LOG_DIR
+      case "metrics":
+        return METRICS_LOG_DIR
+      default:
+        return TELEMETRY_DIR
+    }
+  }
+}