te.js 2.1.5 → 2.2.0

package/server/errors/channels/channels.test.js

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from 'vitest';
+import { getChannels, buildPayload } from './index.js';
+import { ConsoleChannel } from './console.js';
+import { LogChannel } from './log.js';
+
+describe('getChannels()', () => {
+  it('returns a ConsoleChannel for "console"', () => {
+    const channels = getChannels('console', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(ConsoleChannel);
+  });
+
+  it('returns a LogChannel for "log"', () => {
+    const channels = getChannels('log', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(LogChannel);
+  });
+
+  it('returns both channels for "both"', () => {
+    const channels = getChannels('both', './test.log');
+    expect(channels).toHaveLength(2);
+    const types = channels.map((c) => c.constructor.name);
+    expect(types).toContain('ConsoleChannel');
+    expect(types).toContain('LogChannel');
+  });
+
+  it('defaults to ConsoleChannel for unknown values', () => {
+    const channels = getChannels('unknown', './test.log');
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toBeInstanceOf(ConsoleChannel);
+  });
+
+  it('returns same ConsoleChannel singleton across calls', () => {
+    const a = getChannels('console', './test.log')[0];
+    const b = getChannels('console', './test.log')[0];
+    expect(a).toBe(b);
+  });
+
+  it('LogChannel uses the provided logFile path', () => {
+    const channels = getChannels('log', './my-errors.log');
+    expect(channels[0].logFile).toBe('./my-errors.log');
+  });
+});
+
+describe('buildPayload()', () => {
+  const codeContext = {
+    snippets: [
+      { file: '/app/handler.js', line: 10, snippet: '→ ammo.throw()' },
+    ],
+  };
+
+  it('builds a complete payload', () => {
+    const payload = buildPayload({
+      method: 'POST',
+      path: '/users',
+      originalError: new Error('DB error'),
+      codeContext,
+      statusCode: 500,
+      message: 'Internal Server Error',
+      devInsight: 'DB connection may be down.',
+    });
+
+    expect(payload.method).toBe('POST');
+    expect(payload.path).toBe('/users');
+    expect(payload.statusCode).toBe(500);
+    expect(payload.message).toBe('Internal Server Error');
+    expect(payload.devInsight).toBe('DB connection may be down.');
+    expect(payload.error).toEqual({ type: 'Error', message: 'DB error' });
+    expect(payload.codeContext).toBe(codeContext);
+    expect(typeof payload.timestamp).toBe('string');
+    expect(() => new Date(payload.timestamp)).not.toThrow();
+  });
+
+  it('handles string error', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/items',
+      originalError: 'Not found',
+      codeContext,
+      statusCode: 404,
+      message: 'Not found',
+    });
+    expect(payload.error).toEqual({ type: 'string', message: 'Not found' });
+  });
+
+  it('sets error to null when no originalError', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+    });
+    expect(payload.error).toBeNull();
+  });
+
+  it('includes cached flag when provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 404,
+      message: 'Not found',
+      cached: true,
+    });
+    expect(payload.cached).toBe(true);
+  });
+
+  it('includes rateLimited flag when provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+      rateLimited: true,
+    });
+    expect(payload.rateLimited).toBe(true);
+  });
+
+  it('omits cached and rateLimited when not provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 200,
+      message: 'OK',
+    });
+    expect(payload).not.toHaveProperty('cached');
+    expect(payload).not.toHaveProperty('rateLimited');
+  });
+
+  it('omits devInsight when not provided', () => {
+    const payload = buildPayload({
+      method: 'GET',
+      path: '/',
+      originalError: null,
+      codeContext,
+      statusCode: 500,
+      message: 'Error',
+    });
+    expect(payload).not.toHaveProperty('devInsight');
+  });
+});

package/server/errors/channels/console.js

@@ -0,0 +1,64 @@
+/**
+ * Console channel: pretty-prints LLM error results to the terminal using ansi-colors.
+ */
+
+import ansi from 'ansi-colors';
+import { ErrorChannel } from './base.js';
+
+const { red, yellow, cyan, white, bold, dim, italic } = ansi;
+
+/**
+ * Format an HTTP status code with color (red for 5xx, yellow for 4xx, white for others).
+ * @param {number} statusCode
+ * @returns {string}
+ */
+function colorStatus(statusCode) {
+  if (statusCode >= 500) return red(bold(String(statusCode)));
+  if (statusCode >= 400) return yellow(bold(String(statusCode)));
+  return white(bold(String(statusCode)));
+}
+
+export class ConsoleChannel extends ErrorChannel {
+  async dispatch(payload) {
+    const {
+      timestamp,
+      method,
+      path,
+      statusCode,
+      message,
+      devInsight,
+      error,
+      cached,
+      rateLimited,
+    } = payload;
+
+    const time = dim(italic(new Date(timestamp).toLocaleTimeString()));
+    const route = white(`${method} ${path}`);
+    const status = colorStatus(statusCode);
+
+    const flags = [];
+    if (cached) flags.push(cyan('[CACHED]'));
+    if (rateLimited) flags.push(yellow('[RATE LIMITED]'));
+    const flagStr = flags.length ? ' ' + flags.join(' ') : '';
+
+    const lines = [
+      ``,
+      `${time} ${red('[LLM ERROR]')} ${route} → ${status}${flagStr}`,
+      `  ${white(message)}`,
+    ];
+
+    if (devInsight) {
+      lines.push(`  ${cyan('⟶')} ${cyan(devInsight)}`);
+    }
+
+    if (error?.message && !rateLimited) {
+      lines.push(
+        `  ${dim(`original: ${error.type ? error.type + ': ' : ''}${error.message}`)}`,
+      );
+    }
+
+    lines.push('');
+
+    process.stderr.write(lines.join('\n'));
+  }
+}

package/server/errors/channels/index.js

@@ -0,0 +1,111 @@
+/**
+ * Channel registry for LLM error output.
+ * Maps channel config values ('console' | 'log' | 'both') to channel instances.
+ */
+
+import { ConsoleChannel } from './console.js';
+import { LogChannel } from './log.js';
+
+/** @type {ConsoleChannel|null} */
+let _console = null;
+
+/** @type {Map<string, LogChannel>} */
+const _logInstances = new Map();
+
+/**
+ * Get (or create) the singleton ConsoleChannel.
+ * @returns {ConsoleChannel}
+ */
+function getConsoleChannel() {
+  if (!_console) _console = new ConsoleChannel();
+  return _console;
+}
+
+/**
+ * Get (or create) a LogChannel for the given file path.
+ * @param {string} logFile
+ * @returns {LogChannel}
+ */
+function getLogChannel(logFile) {
+  if (!_logInstances.has(logFile)) {
+    _logInstances.set(logFile, new LogChannel(logFile));
+  }
+  return _logInstances.get(logFile);
+}
+
+/**
+ * Resolve channel instances for the given config value and log file.
+ * @param {'console'|'log'|'both'} channel
+ * @param {string} logFile
+ * @returns {import('./base.js').ErrorChannel[]}
+ */
+export function getChannels(channel, logFile) {
+  switch (channel) {
+    case 'log':
+      return [getLogChannel(logFile)];
+    case 'both':
+      return [getConsoleChannel(), getLogChannel(logFile)];
+    case 'console':
+    default:
+      return [getConsoleChannel()];
+  }
+}
+
+/**
+ * Build the standard channel payload from available context and LLM result.
+ * @param {object} opts
+ * @param {string} opts.method
+ * @param {string} opts.path
+ * @param {Error|string|null|undefined} opts.originalError
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} opts.codeContext
+ * @param {number} opts.statusCode
+ * @param {string} opts.message
+ * @param {string} [opts.devInsight]
+ * @param {boolean} [opts.cached]
+ * @param {boolean} [opts.rateLimited]
+ * @returns {import('./base.js').ChannelPayload}
+ */
+export function buildPayload({
+  method,
+  path,
+  originalError,
+  codeContext,
+  statusCode,
+  message,
+  devInsight,
+  cached,
+  rateLimited,
+}) {
+  let errorSummary = null;
+  if (originalError != null && typeof originalError.message === 'string') {
+    errorSummary = {
+      type: originalError.constructor?.name ?? 'Error',
+      message: originalError.message ?? '',
+    };
+  } else if (originalError != null) {
+    errorSummary = { type: 'string', message: String(originalError) };
+  }
+
+  return {
+    timestamp: new Date().toISOString(),
+    method: method ?? '',
+    path: path ?? '',
+    statusCode,
+    message,
+    ...(devInsight != null && { devInsight }),
+    error: errorSummary,
+    codeContext: codeContext ?? { snippets: [] },
+    ...(cached != null && { cached }),
+    ...(rateLimited != null && { rateLimited }),
+  };
+}
+
+/**
+ * Dispatch a payload to all resolved channels, swallowing individual channel errors.
+ * @param {import('./base.js').ErrorChannel[]} channels
+ * @param {import('./base.js').ChannelPayload} payload
+ * @returns {Promise<void>}
+ */
+export async function dispatchToChannels(channels, payload) {
+  await Promise.allSettled(channels.map((ch) => ch.dispatch(payload)));
+}

package/server/errors/channels/log.js

@@ -0,0 +1,27 @@
+/**
+ * Log channel: appends a full JSONL entry to a log file for each LLM error result.
+ * Each line is a self-contained JSON object with all fields for post-mortem debugging.
+ */
+
+import { appendFile } from 'node:fs/promises';
+import { ErrorChannel } from './base.js';
+
+export class LogChannel extends ErrorChannel {
+  /**
+   * @param {string} logFile - Absolute or relative path to the JSONL log file.
+   */
+  constructor(logFile) {
+    super();
+    this.logFile = logFile;
+  }
+
+  async dispatch(payload) {
+    const line = JSON.stringify(payload) + '\n';
+    try {
+      await appendFile(this.logFile, line, 'utf-8');
+    } catch {
+      // Silently ignore write failures (e.g. permissions, disk full) so logging never
+      // crashes the process or blocks error handling.
+    }
+  }
+}

package/server/errors/llm-cache.js

@@ -0,0 +1,102 @@
+/**
+ * In-memory TTL cache for LLM error inference results.
+ * Key: file:line:errorMessage -- deduplicates repeated errors at the same throw site.
+ * Shared singleton across the process; configured from errors.llm.cacheTTL.
+ */
+
+const SWEEP_INTERVAL_MS = 5 * 60 * 1000; // prune expired entries every 5 minutes
+
+class LLMErrorCache {
+  /**
+   * @param {number} ttl - Time-to-live in milliseconds for each cached result.
+   */
+  constructor(ttl) {
+    this.ttl = ttl > 0 ? ttl : 3_600_000;
+    /** @type {Map<string, { statusCode: number, message: string, devInsight?: string, cachedAt: number }>} */
+    this._store = new Map();
+    this._sweepTimer =
+      setInterval(() => this._sweep(), SWEEP_INTERVAL_MS).unref?.() ?? null;
+  }
+
+  /**
+   * Build a cache key from code context and error.
+   * Uses the first (throw-site) snippet's file and line + error text.
+   * @param {{ snippets?: Array<{ file: string, line: number }> }} codeContext
+   * @param {Error|string|undefined} error
+   * @returns {string}
+   */
+  buildKey(codeContext, error) {
+    const snippet = codeContext?.snippets?.[0];
+    const location = snippet ? `${snippet.file}:${snippet.line}` : 'unknown';
+    let errText = '';
+    if (error != null && typeof error.message === 'string') {
+      errText = error.message ?? '';
+    } else if (error != null) {
+      errText = String(error);
+    }
+    return `${location}:${errText}`;
+  }
+
+  /**
+   * Get a cached result. Returns null if missing or expired (and prunes the entry).
+   * @param {string} key
+   * @returns {{ statusCode: number, message: string, devInsight?: string } | null}
+   */
+  get(key) {
+    const entry = this._store.get(key);
+    if (!entry) return null;
+    if (Date.now() - entry.cachedAt > this.ttl) {
+      this._store.delete(key);
+      return null;
+    }
+    const { cachedAt: _removed, ...result } = entry;
+    return result;
+  }
+
+  /**
+   * Store a result in the cache.
+   * @param {string} key
+   * @param {{ statusCode: number, message: string, devInsight?: string }} result
+   */
+  set(key, result) {
+    this._store.set(key, { ...result, cachedAt: Date.now() });
+  }
+
+  /**
+   * Remove all expired entries (called periodically by the sweep timer).
+   */
+  _sweep() {
+    const now = Date.now();
+    for (const [key, entry] of this._store) {
+      if (now - entry.cachedAt > this.ttl) {
+        this._store.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Number of entries currently in the cache (including potentially stale ones not yet swept).
+   * @returns {number}
+   */
+  get size() {
+    return this._store.size;
+  }
+}
+
+/** @type {LLMErrorCache|null} */
+let _instance = null;
+
+/**
+ * Get (or create) the singleton cache.
+ * Re-initializes if ttl changes.
+ * @param {number} ttl
+ * @returns {LLMErrorCache}
+ */
+export function getCache(ttl) {
+  if (!_instance || _instance.ttl !== ttl) {
+    _instance = new LLMErrorCache(ttl);
+  }
+  return _instance;
+}
+
+export { LLMErrorCache };

package/server/errors/llm-cache.test.js

@@ -0,0 +1,160 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { LLMErrorCache, getCache } from './llm-cache.js';
+
+describe('LLMErrorCache', () => {
+  describe('constructor', () => {
+    it('uses provided ttl', () => {
+      const cache = new LLMErrorCache(5000);
+      expect(cache.ttl).toBe(5000);
+    });
+
+    it('defaults to 3600000 for invalid ttl', () => {
+      expect(new LLMErrorCache(0).ttl).toBe(3_600_000);
+      expect(new LLMErrorCache(-1).ttl).toBe(3_600_000);
+    });
+  });
+
+  describe('buildKey()', () => {
+    it('builds key from first snippet file, line, and error message', () => {
+      const cache = new LLMErrorCache(1000);
+      const codeContext = {
+        snippets: [{ file: '/app/routes/users.js', line: 42 }],
+      };
+      const error = new Error('User not found');
+      const key = cache.buildKey(codeContext, error);
+      expect(key).toBe('/app/routes/users.js:42:User not found');
+    });
+
+    it('handles string error', () => {
+      const cache = new LLMErrorCache(1000);
+      const codeContext = { snippets: [{ file: '/app/handler.js', line: 10 }] };
+      const key = cache.buildKey(codeContext, 'Validation failed');
+      expect(key).toBe('/app/handler.js:10:Validation failed');
+    });
+
+    it('handles no error (empty string suffix)', () => {
+      const cache = new LLMErrorCache(1000);
+      const codeContext = { snippets: [{ file: '/app/handler.js', line: 5 }] };
+      const key = cache.buildKey(codeContext, undefined);
+      expect(key).toBe('/app/handler.js:5:');
+    });
+
+    it('uses "unknown" when codeContext has no snippets', () => {
+      const cache = new LLMErrorCache(1000);
+      const key = cache.buildKey({ snippets: [] }, new Error('oops'));
+      expect(key).toBe('unknown:oops');
+    });
+
+    it('uses "unknown" when codeContext is missing', () => {
+      const cache = new LLMErrorCache(1000);
+      const key = cache.buildKey(null, new Error('oops'));
+      expect(key).toBe('unknown:oops');
+    });
+  });
+
+  describe('set() and get()', () => {
+    it('stores and retrieves a result', () => {
+      const cache = new LLMErrorCache(10_000);
+      cache.set('key1', { statusCode: 404, message: 'Not found' });
+      const result = cache.get('key1');
+      expect(result).toEqual({ statusCode: 404, message: 'Not found' });
+    });
+
+    it('returns null for missing keys', () => {
+      const cache = new LLMErrorCache(10_000);
+      expect(cache.get('nonexistent')).toBeNull();
+    });
+
+    it('does not return cachedAt in the result', () => {
+      const cache = new LLMErrorCache(10_000);
+      cache.set('key1', { statusCode: 500, message: 'Error' });
+      const result = cache.get('key1');
+      expect(result).not.toHaveProperty('cachedAt');
+    });
+
+    it('includes devInsight when stored', () => {
+      const cache = new LLMErrorCache(10_000);
+      cache.set('key1', {
+        statusCode: 404,
+        message: 'Not found',
+        devInsight: 'Check the ID param.',
+      });
+      const result = cache.get('key1');
+      expect(result.devInsight).toBe('Check the ID param.');
+    });
+  });
+
+  describe('TTL expiry', () => {
+    it('returns null for expired entries', () => {
+      vi.useFakeTimers();
+
+      const cache = new LLMErrorCache(1000);
+      cache.set('key1', { statusCode: 404, message: 'Not found' });
+      expect(cache.get('key1')).not.toBeNull();
+
+      vi.advanceTimersByTime(1001);
+
+      expect(cache.get('key1')).toBeNull();
+
+      vi.useRealTimers();
+    });
+
+    it('removes expired entry from the store on access', () => {
+      vi.useFakeTimers();
+
+      const cache = new LLMErrorCache(500);
+      cache.set('key1', { statusCode: 500, message: 'Error' });
+      expect(cache.size).toBe(1);
+
+      vi.advanceTimersByTime(600);
+      cache.get('key1');
+
+      expect(cache.size).toBe(0);
+
+      vi.useRealTimers();
+    });
+
+    it('non-expired entries remain accessible', () => {
+      vi.useFakeTimers();
+
+      const cache = new LLMErrorCache(5000);
+      cache.set('key1', { statusCode: 200, message: 'OK' });
+
+      vi.advanceTimersByTime(4999);
+
+      expect(cache.get('key1')).not.toBeNull();
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('size', () => {
+    it('tracks the number of entries', () => {
+      const cache = new LLMErrorCache(10_000);
+      expect(cache.size).toBe(0);
+      cache.set('a', { statusCode: 200, message: 'OK' });
+      cache.set('b', { statusCode: 404, message: 'Not found' });
+      expect(cache.size).toBe(2);
+    });
+  });
+});
+
+describe('getCache (singleton)', () => {
+  it('returns a LLMErrorCache instance', () => {
+    const cache = getCache(3600000);
+    expect(cache).toBeInstanceOf(LLMErrorCache);
+  });
+
+  it('returns same instance for same ttl', () => {
+    const a = getCache(3600000);
+    const b = getCache(3600000);
+    expect(a).toBe(b);
+  });
+
+  it('creates a new instance when ttl changes', () => {
+    const a = getCache(1000);
+    const b = getCache(2000);
+    expect(a).not.toBe(b);
+    expect(b.ttl).toBe(2000);
+  });
+});