octocode-cli 1.2.6 → 1.2.8

package/skills/octocode-research/src/utils/errorQueue.ts

@@ -0,0 +1,71 @@
+/**
+ * Bounded queue for fire-and-forget operation errors.
+ * Provides visibility into async errors without blocking main flow.
+ *
+ * @module utils/errorQueue
+ */
+
+interface QueuedError {
+  timestamp: Date;
+  error: Error;
+  context?: string;
+}
+
+/**
+ * Bounded error queue that stores recent errors from async operations.
+ * Prevents unbounded memory growth while maintaining error visibility.
+ */
+class ErrorQueue {
+  private errors: QueuedError[] = [];
+  private readonly maxSize: number;
+
+  constructor(maxSize = 100) {
+    this.maxSize = maxSize;
+  }
+
+  /**
+   * Add an error to the queue.
+   * If queue is full, oldest error is removed.
+   */
+  push(error: unknown, context?: string): void {
+    const normalizedError =
+      error instanceof Error ? error : new Error(String(error));
+
+    this.errors.push({
+      timestamp: new Date(),
+      error: normalizedError,
+      context,
+    });
+
+    // Bounded: remove oldest when full
+    if (this.errors.length > this.maxSize) {
+      this.errors.shift();
+    }
+  }
+
+  /**
+   * Get the most recent errors.
+   */
+  getRecent(count = 10): QueuedError[] {
+    return this.errors.slice(-count);
+  }
+
+  /**
+   * Clear all errors from the queue.
+   */
+  clear(): void {
+    this.errors = [];
+  }
+
+  /**
+   * Get current queue size.
+   */
+  get size(): number {
+    return this.errors.length;
+  }
+}
+
+/**
+ * Global error queue instance for fire-and-forget operations.
+ */
+export const errorQueue = new ErrorQueue();

package/skills/octocode-research/src/utils/logEmoji.ts

@@ -0,0 +1,103 @@
+/**
+ * Environment-aware emoji toggle for log messages.
+ *
+ * Disables emojis in production or when LOG_NO_EMOJI is set,
+ * as they can cause issues with log parsing tools.
+ *
+ * @module utils/logEmoji
+ */
+
+// =============================================================================
+// Configuration
+// =============================================================================
+
+/**
+ * Check if emojis should be used in logs.
+ * Returns false when:
+ * - NODE_ENV is 'production'
+ * - LOG_NO_EMOJI env var is truthy ('true', '1', 'yes')
+ */
+export function shouldUseEmoji(): boolean {
+  if (process.env.NODE_ENV === 'production') return false;
+  const noEmoji = process.env.LOG_NO_EMOJI;
+  if (noEmoji === 'true' || noEmoji === '1' || noEmoji === 'yes') return false;
+  return true;
+}
+
+// =============================================================================
+// Emoji Registry
+// =============================================================================
+
+/**
+ * Supported emoji keys for logging
+ */
+export type LogEmojiKey =
+  | 'server'
+  | 'shutdown'
+  | 'logs'
+  | 'routes'
+  | 'success'
+  | 'error'
+  | 'warning'
+  | 'info'
+  | 'circuit_open'
+  | 'circuit_closed'
+  | 'circuit_half_open'
+  | 'cleanup'
+  | 'reset'
+  | 'retry'
+  | 'evict';
+
+/**
+ * Emoji map with fallback text alternatives
+ */
+const EMOJI_MAP: Record<LogEmojiKey, { emoji: string; fallback: string }> = {
+  server: { emoji: '🔍', fallback: '[SERVER]' },
+  shutdown: { emoji: '🛑', fallback: '[SHUTDOWN]' },
+  logs: { emoji: '📁', fallback: '[LOGS]' },
+  routes: { emoji: '📋', fallback: '[ROUTES]' },
+  success: { emoji: '✅', fallback: '[OK]' },
+  error: { emoji: '❌', fallback: '[ERROR]' },
+  warning: { emoji: '⚠️', fallback: '[WARN]' },
+  info: { emoji: 'ℹ️', fallback: '[INFO]' },
+  circuit_open: { emoji: '🔴', fallback: '[OPEN]' },
+  circuit_closed: { emoji: '🟢', fallback: '[CLOSED]' },
+  circuit_half_open: { emoji: '🟡', fallback: '[HALF-OPEN]' },
+  cleanup: { emoji: '🧹', fallback: '[CLEANUP]' },
+  reset: { emoji: '🔄', fallback: '[RESET]' },
+  retry: { emoji: '⟳', fallback: '[RETRY]' },
+  evict: { emoji: '⚠️', fallback: '[EVICT]' },
+};
+
+// =============================================================================
+// Public API
+// =============================================================================
+
+/**
+ * Get the appropriate emoji or fallback text for a log key.
+ *
+ * @param key - The emoji key to retrieve
+ * @returns Emoji string or fallback text based on environment
+ */
+export function getLogEmoji(key: LogEmojiKey): string {
+  const entry = EMOJI_MAP[key];
+  return shouldUseEmoji() ? entry.emoji : entry.fallback;
+}
+
+/**
+ * Prefix a message with the appropriate emoji or fallback.
+ *
+ * @param key - The emoji key to use
+ * @param message - The message to prefix
+ * @returns Formatted message with emoji/fallback prefix
+ *
+ * @example
+ * ```typescript
+ * // Development: "🔍 Server running on port 1987"
+ * // Production:  "[SERVER] Server running on port 1987"
+ * console.log(prefixLog('server', 'Server running on port 1987'));
+ * ```
+ */
+export function prefixLog(key: LogEmojiKey, message: string): string {
+  return `${getLogEmoji(key)} ${message}`;
+}

package/skills/octocode-research/src/utils/logger.ts

@@ -0,0 +1,413 @@
+import { errorLog, warnLog } from './colors.js';
+import { errorQueue } from './errorQueue.js';
+/**
+ * Cross-platform logging utility for Octocode Research Server
+ *
+ * Logs to ~/.octocode/logs/ (or %USERPROFILE%\.octocode\logs on Windows)
+ * - errors.log: All errors and warnings
+ * - tools.log: Tool invocation data and results
+ * 
+ * PERFORMANCE: Uses async file operations to avoid blocking event loop
+ */
+
+import fs from 'node:fs';
+import { promises as fsAsync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+const HOME = os.homedir();
+const OCTOCODE_DIR = process.env.OCTOCODE_HOME || path.join(HOME, '.octocode');
+const LOGS_DIR = path.join(OCTOCODE_DIR, 'logs');
+const ERROR_LOG = path.join(LOGS_DIR, 'errors.log');
+const TOOLS_LOG = path.join(LOGS_DIR, 'tools.log');
+
+// Max log file size before rotation (10MB)
+const MAX_LOG_SIZE = 10 * 1024 * 1024;
+
+// Max size for JSON.stringify to prevent memory spikes (100KB)
+const MAX_LOG_DATA_SIZE = 100 * 1024;
+
+// ============================================================================
+// Directory Initialization (async with sync fallback for startup)
+// ============================================================================
+
+let initialized = false;
+let fileLoggingEnabled = true;
+let initPromise: Promise<void> | null = null;
+
+/**
+ * Ensure the logs directory exists (async).
+ * Safe to call multiple times (idempotent).
+ */
+async function ensureLogsDirAsync(): Promise<void> {
+  if (initialized) return;
+  if (initPromise) return initPromise;
+
+  initPromise = (async () => {
+    try {
+      await fsAsync.mkdir(OCTOCODE_DIR, { recursive: true, mode: 0o700 });
+      await fsAsync.mkdir(LOGS_DIR, { recursive: true, mode: 0o700 });
+      initialized = true;
+    } catch (err) {
+      process.stderr.write(
+        `[Logger] Failed to create logs directory: ${err}\n` +
+        `Falling back to console-only logging.\n`
+      );
+      fileLoggingEnabled = false;
+    }
+  })();
+
+  return initPromise;
+}
+
+/**
+ * Sync initialization for startup only (blocking but necessary)
+ */
+function ensureLogsDirSync(): void {
+  if (initialized) return;
+
+  try {
+    if (!fs.existsSync(OCTOCODE_DIR)) {
+      fs.mkdirSync(OCTOCODE_DIR, { recursive: true, mode: 0o700 });
+    }
+    if (!fs.existsSync(LOGS_DIR)) {
+      fs.mkdirSync(LOGS_DIR, { recursive: true, mode: 0o700 });
+    }
+    initialized = true;
+  } catch (err) {
+    process.stderr.write(
+      `[Logger] Failed to create logs directory: ${err}\n` +
+      `Falling back to console-only logging.\n`
+    );
+    fileLoggingEnabled = false;
+  }
+}
+
+// ============================================================================
+// Log Rotation (async)
+// ============================================================================
+
+/**
+ * Rotate log file if it exceeds max size (async).
+ */
+async function rotateIfNeededAsync(logPath: string): Promise<void> {
+  try {
+    const stats = await fsAsync.stat(logPath).catch(() => null);
+    if (!stats || stats.size < MAX_LOG_SIZE) return;
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const ext = path.extname(logPath);
+    const base = path.basename(logPath, ext);
+    const rotatedPath = path.join(LOGS_DIR, `${base}.${timestamp}${ext}`);
+    
+    await fsAsync.rename(logPath, rotatedPath);
+    await cleanupOldLogsAsync(base, ext, 5);
+  } catch {
+    // Silently fail - logging should never crash the server
+  }
+}
+
+/**
+ * Remove old rotated log files, keeping only the most recent ones (async).
+ */
+async function cleanupOldLogsAsync(baseName: string, ext: string, keep: number): Promise<void> {
+  try {
+    const files = await fsAsync.readdir(LOGS_DIR);
+    const rotatedFiles = files
+      .filter((f) => f.startsWith(baseName + '.') && f.endsWith(ext) && f !== baseName + ext)
+      .sort()
+      .reverse();
+
+    // Remove files beyond the keep limit
+    const toDelete = rotatedFiles.slice(keep);
+    await Promise.all(
+      toDelete.map((f) => fsAsync.unlink(path.join(LOGS_DIR, f)).catch(err => errorQueue.push(err, 'cleanupOldLogs')))
+    );
+  } catch {
+    // Silently fail
+  }
+}
+
+// ============================================================================
+// Log Entry Formatting
+// ============================================================================
+
+/**
+ * Safely stringify data with size limit to prevent memory spikes.
+ * Uses single-pass approach with size tracking to avoid double serialization.
+ */
+function safeStringify(data: unknown): string {
+  if (data === undefined) return '';
+
+  try {
+    let size = 0;
+    let truncated = false;
+    const seen = new WeakSet<object>();
+
+    // Custom replacer that tracks size and detects circular refs
+    const replacer = (_key: string, value: unknown): unknown => {
+      // Check for circular references
+      if (value !== null && typeof value === 'object') {
+        if (seen.has(value)) {
+          return '[Circular]';
+        }
+        seen.add(value);
+      }
+
+      // Estimate size contribution (rough but fast)
+      const valueStr = typeof value === 'string' ? value : String(value ?? '');
+      size += valueStr.length + 10; // +10 for key, quotes, colons, etc.
+
+      // If we've exceeded limit, mark as truncated and return placeholder
+      if (size > MAX_LOG_DATA_SIZE && !truncated) {
+        truncated = true;
+      }
+
+      return value;
+    };
+
+    const result = JSON.stringify(data, replacer, 2);
+
+    // If truncated during serialization, return truncation notice
+    if (truncated) {
+      return JSON.stringify({
+        _truncated: true,
+        _estimatedSize: size,
+        _message: 'Data too large for logging',
+      }, null, 2);
+    }
+
+    return result;
+  } catch {
+    return '[Circular or non-serializable data]';
+  }
+}
+
+/**
+ * Format a log entry with timestamp and level.
+ */
+function formatLogEntry(level: string, message: string, data?: unknown): string {
+  const timestamp = new Date().toISOString();
+  const dataStr = data !== undefined ? `\n${safeStringify(data)}` : '';
+  return `[${timestamp}] [${level}] ${message}${dataStr}\n`;
+}
+
+// ============================================================================
+// Core Logging Functions (async with fire-and-forget pattern)
+// ============================================================================
+
+/**
+ * Write to a log file asynchronously (fire-and-forget).
+ * Never blocks the event loop.
+ */
+function writeLogAsync(logPath: string, entry: string): void {
+  if (!fileLoggingEnabled) return;
+
+  // Fire and forget - don't await
+  (async () => {
+    try {
+      await ensureLogsDirAsync();
+      await rotateIfNeededAsync(logPath);
+      await fsAsync.appendFile(logPath, entry, { encoding: 'utf-8' });
+    } catch (err) {
+      // Disable file logging on persistent failure
+      fileLoggingEnabled = false;
+      process.stderr.write(`[Logger] File write failed, disabling: ${err}\n`);
+    }
+  })();
+}
+
+// ============================================================================
+// Public API - Error Logger
+// ============================================================================
+
+/**
+ * Log an error message (async, non-blocking).
+ */
+export function logError(message: string, error?: Error | unknown): void {
+  const errorData =
+    error instanceof Error
+      ? { name: error.name, message: error.message, stack: error.stack }
+      : error;
+
+  const entry = formatLogEntry('ERROR', message, errorData);
+  writeLogAsync(ERROR_LOG, entry);
+
+  // Also write to console for visibility (redact stack in production)
+  const consoleError = process.env.NODE_ENV === 'development'
+    ? error
+    : (error instanceof Error ? error.message : String(error || ''));
+  // Use %s format specifier to prevent format string injection from user-controlled message
+  console.error('%s %o', errorLog('[ERROR] ' + message), consoleError);
+}
+
+/**
+ * Log a warning message (async, non-blocking).
+ */
+export function logWarn(message: string, data?: unknown): void {
+  const entry = formatLogEntry('WARN', message, data);
+  writeLogAsync(ERROR_LOG, entry);
+  // Use %s format specifier to prevent format string injection from user-controlled message
+  console.warn('%s', warnLog('[WARN] ' + message));
+}
+
+// ============================================================================
+// Public API - Tools Logger
+// ============================================================================
+
+export interface ToolLogEntry {
+  tool: string;
+  route: string;
+  method: string;
+  params: Record<string, unknown>;
+  duration?: number;
+  success: boolean;
+  error?: string;
+  resultSize?: number;
+  requestId?: string;
+}
+
+/**
+ * Log a tool invocation (async, non-blocking).
+ */
+export function logToolCall(entry: ToolLogEntry): void {
+  const logEntry = formatLogEntry('TOOL', `${entry.method} ${entry.route}`, entry);
+  writeLogAsync(TOOLS_LOG, logEntry);
+}
+
+/**
+ * Log a successful tool result.
+ */
+export function logToolSuccess(
+  tool: string,
+  route: string,
+  method: string,
+  params: Record<string, unknown>,
+  duration: number,
+  resultSize: number
+): void {
+  logToolCall({
+    tool,
+    route,
+    method,
+    params,
+    duration,
+    success: true,
+    resultSize,
+  });
+}
+
+/**
+ * Log a failed tool invocation.
+ */
+export function logToolError(
+  tool: string,
+  route: string,
+  method: string,
+  params: Record<string, unknown>,
+  duration: number,
+  error: string
+): void {
+  logToolCall({
+    tool,
+    route,
+    method,
+    params,
+    duration,
+    success: false,
+    error,
+  });
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Get the path to the logs directory.
+ */
+export function getLogsPath(): string {
+  return LOGS_DIR;
+}
+
+/**
+ * Get the path to the errors log file.
+ */
+export function getErrorLogPath(): string {
+  return ERROR_LOG;
+}
+
+/**
+ * Get the path to the tools log file.
+ */
+export function getToolsLogPath(): string {
+  return TOOLS_LOG;
+}
+
+/**
+ * Initialize logger synchronously (call at startup).
+ * After startup, all operations are async.
+ */
+export function initializeLogger(): void {
+  ensureLogsDirSync();
+}
+
+// ============================================================================
+// Express Middleware Integration
+// ============================================================================
+
+/**
+ * Create a logging middleware that logs tool invocations.
+ * Use this to wrap route handlers for automatic logging.
+ */
+export function createToolLogger(toolName: string) {
+  return (
+    req: { method: string; path: string; query: unknown },
+    res: { statusCode: number; on: (event: string, cb: () => void) => void },
+    next: () => void
+  ): void => {
+    const start = Date.now();
+
+    res.on('finish', () => {
+      const duration = Date.now() - start;
+      const success = res.statusCode < 400;
+
+      logToolCall({
+        tool: toolName,
+        route: req.path,
+        method: req.method,
+        params: req.query as Record<string, unknown>,
+        duration,
+        success,
+        error: success ? undefined : `HTTP ${res.statusCode}`,
+      });
+    });
+
+    next();
+  };
+}
+
+// ============================================================================
+// Security Utilities
+// ============================================================================
+
+const SENSITIVE_KEYS = ['token', 'key', 'secret', 'password', 'auth', 'credential', 'api_key', 'apikey'];
+
+/**
+ * Sanitize query parameters by redacting sensitive values.
+ * Prevents accidental exposure of secrets in logs.
+ */
+export function sanitizeQueryParams(query: Record<string, unknown>): Record<string, unknown> {
+  const sanitized: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    const isSensitive = SENSITIVE_KEYS.some((s) => key.toLowerCase().includes(s));
+    sanitized[key] = isSensitive ? '[REDACTED]' : value;
+  }
+
+  return sanitized;
+}