te.js 2.1.4 → 2.1.6

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 instanceof Error) {
+    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 instanceof Error) {
+      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-error-service.js

@@ -3,11 +3,15 @@
  * returns statusCode and message (and optionally devInsight in non-production).
  * Uses shared lib/llm with errors.llm config. Developers do not pass an error object;
  * the LLM infers from the code where ammo.throw() was called.
+ *
+ * Flow: cache check -> rate limit check -> LLM call -> record rate -> store cache -> return.
  */
 
 import { createProvider } from '../../lib/llm/index.js';
 import { extractJSON } from '../../lib/llm/parse.js';
 import { getErrorsLlmConfig } from '../../utils/errors-llm-config.js';
+import { getRateLimiter } from './llm-rate-limiter.js';
+import { getCache } from './llm-cache.js';
 
 const DEFAULT_STATUS = 500;
 const DEFAULT_MESSAGE = 'Internal Server Error';
@@ -24,7 +28,8 @@ const DEFAULT_MESSAGE = 'Internal Server Error';
  * @returns {string}
  */
 function buildPrompt(context) {
-  const { codeContext, method, path, includeDevInsight, messageType, error } = context;
+  const { codeContext, method, path, includeDevInsight, messageType, error } =
+    context;
   const forDeveloper = messageType === 'developer';
 
   const requestPart = [method, path].filter(Boolean).length
@@ -35,7 +40,10 @@ function buildPrompt(context) {
   if (codeContext?.snippets?.length) {
     codePart = codeContext.snippets
       .map((s, i) => {
-        const label = i === 0 ? 'Call site (where ammo.throw() was invoked)' : `Upstream caller ${i}`;
+        const label =
+          i === 0
+            ? 'Call site (where ammo.throw() was invoked)'
+            : `Upstream caller ${i}`;
         return `--- ${label}: ${s.file} (line ${s.line}) ---\n${s.snippet}`;
       })
       .join('\n\n');
@@ -80,27 +88,65 @@ JSON:`;
 
 /**
  * Infer HTTP statusCode and message (and optionally devInsight) from code context using the LLM.
- * Uses errors.llm config (getErrorsLlmConfig). Call only when errors.llm.enabled is true and config is valid.
- * The primary input is codeContext (surrounding + upstream/downstream snippets); error is optional.
+ * Checks cache first, then rate limit. On success stores result in cache.
  *
  * @param {object} context - Context for the prompt.
- * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext - Source snippets with line numbers (from captureCodeContext).
- * @param {string} [context.method] - HTTP method.
- * @param {string} [context.path] - Request path.
- * @param {boolean} [context.includeDevInsight] - In non-production, dev insight is included by default; set to false to disable.
- * @param {'endUser'|'developer'} [context.messageType] - Override config: 'endUser' or 'developer'. Default from errors.llm.messageType.
- * @param {string|Error|undefined} [context.error] - Optional error if the caller passed one (secondary signal).
- * @returns {Promise<{ statusCode: number, message: string, devInsight?: string }>}
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext
+ * @param {string} [context.method]
+ * @param {string} [context.path]
+ * @param {boolean} [context.includeDevInsight]
+ * @param {'endUser'|'developer'} [context.messageType]
+ * @param {string|Error|undefined} [context.error]
+ * @returns {Promise<{ statusCode: number, message: string, devInsight?: string, cached?: boolean, rateLimited?: boolean }>}
  */
 export async function inferErrorFromContext(context) {
   const config = getErrorsLlmConfig();
-  const { baseURL, apiKey, model, messageType: configMessageType } = config;
-  const provider = createProvider({ baseURL, apiKey, model });
+  const {
+    baseURL,
+    apiKey,
+    model,
+    messageType: configMessageType,
+    timeout,
+    rateLimit,
+    cache: cacheEnabled,
+    cacheTTL,
+  } = config;
 
   const isProduction = process.env.NODE_ENV === 'production';
-  const includeDevInsight = !isProduction && context.includeDevInsight !== false;
+  const includeDevInsight =
+    context.includeDevInsight !== false
+      ? context.forceDevInsight
+        ? true
+        : !isProduction
+      : false;
   const messageType = context.messageType ?? configMessageType;
 
+  // 1. Cache check
+  if (cacheEnabled) {
+    const cache = getCache(cacheTTL);
+    const key = cache.buildKey(context.codeContext, context.error);
+    const cached = cache.get(key);
+    if (cached) {
+      return { ...cached, cached: true };
+    }
+  }
+
+  // 2. Rate limit check
+  const limiter = getRateLimiter(rateLimit);
+  if (!limiter.canCall()) {
+    return {
+      statusCode: DEFAULT_STATUS,
+      message: DEFAULT_MESSAGE,
+      ...(includeDevInsight && {
+        devInsight: 'LLM rate limit exceeded — error was not enhanced.',
+      }),
+      rateLimited: true,
+    };
+  }
+
+  // 3. LLM call
+  const provider = createProvider({ baseURL, apiKey, model, timeout });
+
   const prompt = buildPrompt({
     codeContext: context.codeContext,
     method: context.method,
@@ -111,6 +157,10 @@ export async function inferErrorFromContext(context) {
   });
 
   const { content } = await provider.analyze(prompt);
+
+  // 4. Record the call against the rate limit
+  limiter.record();
+
   const parsed = extractJSON(content);
 
   if (!parsed || typeof parsed !== 'object') {
@@ -132,9 +182,20 @@ export async function inferErrorFromContext(context) {
       : DEFAULT_MESSAGE;
 
   const result = { statusCode, message };
-  if (includeDevInsight && typeof parsed.devInsight === 'string' && parsed.devInsight.trim()) {
+  if (
+    includeDevInsight &&
+    typeof parsed.devInsight === 'string' &&
+    parsed.devInsight.trim()
+  ) {
     result.devInsight = parsed.devInsight.trim();
   }
 
+  // 5. Store in cache
+  if (cacheEnabled) {
+    const cache = getCache(cacheTTL);
+    const key = cache.buildKey(context.codeContext, context.error);
+    cache.set(key, result);
+  }
+
   return result;
 }

package/server/errors/llm-rate-limiter.js

@@ -0,0 +1,72 @@
+/**
+ * In-memory sliding window rate limiter for LLM error inference calls.
+ * Tracks LLM call timestamps in the last 60 seconds.
+ * Shared singleton across the process; configured from errors.llm.rateLimit.
+ */
+
+class LLMRateLimiter {
+  /**
+   * @param {number} maxPerMinute - Maximum LLM calls allowed per 60-second window.
+   */
+  constructor(maxPerMinute) {
+    this.maxPerMinute = maxPerMinute > 0 ? Math.floor(maxPerMinute) : 10;
+    /** @type {number[]} timestamps of recent LLM calls (ms since epoch) */
+    this._timestamps = [];
+  }
+
+  /**
+   * Prune timestamps older than 60 seconds from now.
+   */
+  _prune() {
+    const cutoff = Date.now() - 60_000;
+    let i = 0;
+    while (i < this._timestamps.length && this._timestamps[i] <= cutoff) {
+      i++;
+    }
+    if (i > 0) this._timestamps.splice(0, i);
+  }
+
+  /**
+   * Returns true if an LLM call is allowed under the current rate.
+   * @returns {boolean}
+   */
+  canCall() {
+    this._prune();
+    return this._timestamps.length < this.maxPerMinute;
+  }
+
+  /**
+   * Record that an LLM call was made right now.
+   */
+  record() {
+    this._prune();
+    this._timestamps.push(Date.now());
+  }
+
+  /**
+   * Returns how many calls remain in the current window.
+   * @returns {number}
+   */
+  remaining() {
+    this._prune();
+    return Math.max(0, this.maxPerMinute - this._timestamps.length);
+  }
+}
+
+/** @type {LLMRateLimiter|null} */
+let _instance = null;
+
+/**
+ * Get (or create) the singleton rate limiter.
+ * Re-initializes if maxPerMinute changes.
+ * @param {number} maxPerMinute
+ * @returns {LLMRateLimiter}
+ */
+export function getRateLimiter(maxPerMinute) {
+  if (!_instance || _instance.maxPerMinute !== maxPerMinute) {
+    _instance = new LLMRateLimiter(maxPerMinute);
+  }
+  return _instance;
+}
+
+export { LLMRateLimiter };

package/server/handler.js

@@ -12,7 +12,13 @@ const logger = new TejLogger('Tejas');
 const warnedPaths = new Set();
 
 const DEFAULT_ALLOWED_METHODS = [
-  'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
+  'GET',
+  'POST',
+  'PUT',
+  'DELETE',
+  'PATCH',
+  'HEAD',
+  'OPTIONS',
 ];
 
 /**
@@ -24,9 +30,13 @@ const getAllowedMethods = () => {
   if (raw == null) return new Set(DEFAULT_ALLOWED_METHODS);
   const arr = Array.isArray(raw)
     ? raw
-    : (typeof raw === 'string' ? raw.split(',').map((s) => s.trim()) : []);
+    : typeof raw === 'string'
+      ? raw.split(',').map((s) => s.trim())
+      : [];
   const normalized = arr.map((m) => String(m).toUpperCase()).filter(Boolean);
-  return normalized.length > 0 ? new Set(normalized) : new Set(DEFAULT_ALLOWED_METHODS);
+  return normalized.length > 0
+    ? new Set(normalized)
+    : new Set(DEFAULT_ALLOWED_METHODS);
 };
 
 /**
@@ -58,23 +68,31 @@ const executeChain = async (target, ammo) => {
 
     try {
       const result = await middleware(...args);
-      
+
       // Check again after middleware execution (passport might have redirected)
       if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
         return;
       }
-      
+
       // If middleware returned a promise that resolved, continue chain
       if (result && typeof result.then === 'function') {
         await result;
         // Check one more time after promise resolution
-        if (ammo.res.headersSent || ammo.res.writableEnded || ammo.res.finished) {
+        if (
+          ammo.res.headersSent ||
+          ammo.res.writableEnded ||
+          ammo.res.finished
+        ) {
           return;
         }
       }
     } catch (err) {
       // Only handle error if response hasn't been sent
-      if (!ammo.res.headersSent && !ammo.res.writableEnded && !ammo.res.finished) {
+      if (
+        !ammo.res.headersSent &&
+        !ammo.res.writableEnded &&
+        !ammo.res.finished
+      ) {
         await errorHandler(ammo, err);
       }
     }
@@ -94,7 +112,8 @@ const executeChain = async (target, ammo) => {
  * @returns {Promise<void>}
  */
 const errorHandler = async (ammo, err) => {
-  if (env('LOG_EXCEPTIONS')) errorLogger.error(err);
+  // Pass false as second arg to suppress tej-logger's Console.trace() double-stack output.
+  if (env('LOG_EXCEPTIONS')) errorLogger.error(err, false);
 
   const result = ammo.throw(err);
   if (result != null && typeof result.then === 'function') {
@@ -126,9 +145,11 @@ const handler = async (req, res) => {
   const ammo = new Ammo(req, res);
 
   try {
-    if (match && match.target) {
-      await ammo.enhance();
+    // Enhance ammo for all requests (matched or not) so global middlewares
+    // always receive a fully-populated ammo (method flags, headers, payload, etc.).
+    await ammo.enhance();
 
+    if (match && match.target) {
       const allowedMethods = match.target.getMethods();
       if (allowedMethods != null && allowedMethods.length > 0) {
         const method = ammo.method && String(ammo.method).toUpperCase();
@@ -145,7 +166,8 @@ const handler = async (req, res) => {
         }
       }
 
-      // Add route parameters to ammo.payload
+      // Add route parameters to ammo.params and ammo.payload
+      ammo.params = match.params || {};
       if (match.params && Object.keys(match.params).length > 0) {
         Object.assign(ammo.payload, match.params);
       }
@@ -156,7 +178,23 @@ const handler = async (req, res) => {
       if (req.url === '/') {
         ammo.defaultEntry();
       } else {
-        await errorHandler(ammo, new TejError(404, `URL not found: ${url}`));
+        // Run global middlewares (CORS preflight, auth, logging, etc.) even for
+        // unmatched routes. A pseudo-target with no route-specific middlewares
+        // is used so the 404 response is sent at the end of the global chain.
+        await executeChain(
+          {
+            getMiddlewares: () => [],
+            getHandler: () => async () => {
+              if (!ammo.res.headersSent) {
+                await errorHandler(
+                  ammo,
+                  new TejError(404, `URL not found: ${url}`),
+                );
+              }
+            },
+          },
+          ammo,
+        );
       }
     }
   } catch (err) {

package/server/targets/registry.js

@@ -94,16 +94,16 @@ class TargetRegistry {
     const patternSegments = pattern.split('/').filter((s) => s.length > 0);
     const urlSegments = url.split('/').filter((s) => s.length > 0);
 
-    // Must have same number of segments
-    if (patternSegments.length !== urlSegments.length) {
-      return null;
-    }
-
     // If both are empty (root paths), they match
     if (patternSegments.length === 0 && urlSegments.length === 0) {
       return {};
     }
 
+    // Must have same number of segments
+    if (patternSegments.length !== urlSegments.length) {
+      return null;
+    }
+
     const params = {};
 
     // Match each segment
@@ -133,7 +133,7 @@ class TargetRegistry {
    */
   getAllEndpoints(options = {}) {
     const grouped =
-      typeof options === 'boolean' ? options : (options && options.grouped);
+      typeof options === 'boolean' ? options : options && options.grouped;
     const detailed =
       typeof options === 'object' && options && options.detailed === true;