te.js 2.0.3 → 2.1.1

package/server/endpoint.js

@@ -1,74 +1,97 @@
-import isMiddlewareValid from './targets/middleware-validator.js';
-import { isPathValid, standardizePath } from './targets/path-validator.js';
-import isShootValid from './targets/shoot-validator.js';
-
-class Endpoint {
-  constructor() {
-    this.path = '';
-    this.middlewares = [];
-    this.handler = null;
-    this.metadata = null;
-    /** Source group (e.g. target file id) for grouping in docs. Set by loader before register(). */
-    this.group = null;
-  }
-
-  setPath(base, path) {
-    const standardizedBase = standardizePath(base);
-    const standardizedPath = standardizePath(path);
-
-    let fullPath = `${standardizedBase}${standardizedPath}`;
-    if (fullPath.length === 0) fullPath = '/';
-
-    if (!isPathValid(fullPath)) return this;
-
-    this.path = fullPath;
-    return this;
-  }
-
-  setMiddlewares(middlewares) {
-    const validMiddlewares = middlewares.filter(isMiddlewareValid);
-    if (validMiddlewares.length === 0) return this;
-
-    this.middlewares = this.middlewares.concat(validMiddlewares);
-    return this;
-  }
-
-  setHandler(handler) {
-    if (!isShootValid(handler)) return this;
-    this.handler = handler;
-
-    return this;
-  }
-
-  setMetadata(metadata) {
-    this.metadata = metadata ?? null;
-    return this;
-  }
-
-  setGroup(group) {
-    this.group = group ?? null;
-    return this;
-  }
-
-  getPath() {
-    return this.path;
-  }
-
-  getMiddlewares() {
-    return this.middlewares;
-  }
-
-  getHandler() {
-    return this.handler;
-  }
-
-  getMetadata() {
-    return this.metadata;
-  }
-
-  getGroup() {
-    return this.group;
-  }
-}
-
-export default Endpoint;
+import isMiddlewareValid from './targets/middleware-validator.js';
+import { isPathValid, standardizePath } from './targets/path-validator.js';
+import isShootValid from './targets/shoot-validator.js';
+
+class Endpoint {
+  constructor() {
+    this.path = '';
+    this.middlewares = [];
+    this.handler = null;
+    this.metadata = null;
+    /** Allowed HTTP methods (e.g. ['GET', 'POST']). null = method-agnostic. */
+    this.methods = null;
+    /** Source group (e.g. target file id) for grouping in docs. Set by loader before register(). */
+    this.group = null;
+  }
+
+  setPath(base, path) {
+    const standardizedBase = standardizePath(base);
+    const standardizedPath = standardizePath(path);
+
+    let fullPath = `${standardizedBase}${standardizedPath}`;
+    if (fullPath.length === 0) fullPath = '/';
+
+    if (!isPathValid(fullPath)) return this;
+
+    this.path = fullPath;
+    return this;
+  }
+
+  setMiddlewares(middlewares) {
+    const validMiddlewares = middlewares.filter(isMiddlewareValid);
+    if (validMiddlewares.length === 0) return this;
+
+    this.middlewares = this.middlewares.concat(validMiddlewares);
+    return this;
+  }
+
+  setHandler(handler) {
+    if (!isShootValid(handler)) return this;
+    this.handler = handler;
+
+    return this;
+  }
+
+  setMetadata(metadata) {
+    this.metadata = metadata ?? null;
+    return this;
+  }
+
+  /**
+   * @param {string[]|null} methods - Allowed HTTP methods (e.g. ['GET', 'POST']). null = method-agnostic.
+   */
+  setMethods(methods) {
+    if (methods == null) {
+      this.methods = null;
+      return this;
+    }
+    const arr = Array.isArray(methods) ? methods : [methods];
+    let normalized = arr.map((m) => String(m).toUpperCase()).filter(Boolean);
+    if (normalized.includes('GET') && !normalized.includes('HEAD')) {
+      normalized = [...normalized, 'HEAD'];
+    }
+    this.methods = normalized.length > 0 ? normalized : null;
+    return this;
+  }
+
+  setGroup(group) {
+    this.group = group ?? null;
+    return this;
+  }
+
+  getPath() {
+    return this.path;
+  }
+
+  getMiddlewares() {
+    return this.middlewares;
+  }
+
+  getHandler() {
+    return this.handler;
+  }
+
+  getMetadata() {
+    return this.metadata;
+  }
+
+  getMethods() {
+    return this.methods;
+  }
+
+  getGroup() {
+    return this.group;
+  }
+}
+
+export default Endpoint;

package/server/error.js

@@ -1,9 +1,9 @@
-class TejError extends Error {
-  constructor(code, message) {
-    super(message);
-    this.name = this.constructor.name;
-    this.code = code;
-  }
-}
-
-export default TejError;
+class TejError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+  }
+}
+
+export default TejError;

package/server/errors/code-context.js

@@ -0,0 +1,125 @@
+/**
+ * Capture code context from the call stack: surrounding source with line numbers,
+ * including upstream callers and downstream code. Used by LLM error inference.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+/** Path segments that identify te.js internals (excluded from "user" stack frames). */
+const INTERNAL_PATTERNS = [
+  'server/ammo.js',
+  'server/handler.js',
+  'server/errors/llm-error-service.js',
+  'server/errors/code-context.js',
+  'node_modules',
+];
+
+const LINES_ABOVE = 25;
+const LINES_BELOW = 25;
+const MAX_FRAMES = 6;
+
+/**
+ * Parse a single stack frame line to extract file path, line, and column.
+ * Handles "at fn (file:///path:line:col)" and "at file:///path:line:col" and "at /path:line:col".
+ * @param {string} line
+ * @returns {{ filePath: string, line: number, column: number } | null}
+ */
+function parseStackFrame(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('at ')) return null;
+  // Last occurrence of :number:number is line:column (path may contain colons on Windows/file URL)
+  const match = trimmed.match(/:(\d+):(\d+)\s*\)?\s*$/);
+  if (!match) return null;
+  const lineNum = parseInt(match[1], 10);
+  const colNum = parseInt(match[2], 10);
+  const before = trimmed.slice(0, trimmed.lastIndexOf(':' + match[1] + ':' + match[2]));
+  // Strip "at ... (" or "at " prefix to get path
+  let filePath = before.replace(/^\s*at\s+(?:.*?\s+\()?/, '').replace(/\)?\s*$/, '').trim();
+  if (filePath.startsWith('file://')) {
+    try {
+      filePath = fileURLToPath(filePath);
+    } catch {
+      return null;
+    }
+  }
+  if (!filePath || lineNum <= 0) return null;
+  return { filePath, line: lineNum, column: colNum };
+}
+
+/**
+ * Return true if this file path is internal (te.js / node_modules) and should be skipped for user context.
+ * @param {string} filePath - Absolute or relative path
+ */
+function isInternalFrame(filePath) {
+  const normalized = path.normalize(filePath).replace(/\\/g, '/');
+  return INTERNAL_PATTERNS.some((p) => normalized.includes(p));
+}
+
+/**
+ * Read source file and return lines [lineNum - LINES_ABOVE, lineNum + LINES_BELOW] with line numbers.
+ * @param {string} filePath - Absolute path
+ * @param {number} lineNum - Center line (1-based)
+ * @returns {Promise<{ file: string, line: number, snippet: string } | null>}
+ */
+async function readSnippet(filePath, lineNum) {
+  let content;
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+  const lines = content.split(/\r?\n/);
+  const start = Math.max(0, lineNum - 1 - LINES_ABOVE);
+  const end = Math.min(lines.length, lineNum + LINES_BELOW);
+  const snippet = lines
+    .slice(start, end)
+    .map((text, i) => {
+      const num = start + i + 1;
+      const marker = num === lineNum ? ' →' : '  ';
+      return `${String(num).padStart(4)}${marker} ${text}`;
+    })
+    .join('\n');
+
+  return {
+    file: filePath,
+    line: lineNum,
+    snippet,
+  };
+}
+
+/**
+ * Capture code context from the current call stack: parse stack, filter to user frames,
+ * and read surrounding source (with line numbers) for each frame. First frame is the
+ * throw site; remaining frames are upstream callers. Each snippet includes lines
+ * above and below (downstream in the same function).
+ *
+ * @param {string} [stack] - Stack string (e.g. new Error().stack). If omitted, captures current stack.
+ * @param {{ maxFrames?: number, linesAround?: number }} [options]
+ * @returns {Promise<{ snippets: Array<{ file: string, line: number, snippet: string }> }>}
+ */
+export async function captureCodeContext(stack, options = {}) {
+  const stackStr = typeof stack === 'string' && stack ? stack : new Error().stack;
+  if (!stackStr) return { snippets: [] };
+
+  const maxFrames = options.maxFrames ?? MAX_FRAMES;
+  const lines = stackStr.split('\n');
+  const frames = [];
+
+  for (const line of lines) {
+    const parsed = parseStackFrame(line);
+    if (!parsed) continue;
+    if (isInternalFrame(parsed.filePath)) continue;
+    frames.push(parsed);
+    if (frames.length >= maxFrames) break;
+  }
+
+  const snippets = [];
+  for (const { filePath, line } of frames) {
+    const one = await readSnippet(filePath, line);
+    if (one) snippets.push(one);
+  }
+
+  return { snippets };
+}

package/server/errors/llm-error-service.js

@@ -0,0 +1,140 @@
+/**
+ * LLM-based error inference: given code context (surrounding + upstream/downstream),
+ * 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.
+ */
+
+import { createProvider } from '../../lib/llm/index.js';
+import { extractJSON } from '../../lib/llm/parse.js';
+import { getErrorsLlmConfig } from '../../utils/errors-llm-config.js';
+
+const DEFAULT_STATUS = 500;
+const DEFAULT_MESSAGE = 'Internal Server Error';
+
+/**
+ * Build prompt text from code context (and optional error) for the LLM.
+ * @param {object} context
+ * @param {{ snippets: Array<{ file: string, line: number, snippet: string }> }} context.codeContext - Source snippets with line numbers (first = throw site, rest = upstream).
+ * @param {string} [context.method] - HTTP method.
+ * @param {string} [context.path] - Request path.
+ * @param {boolean} [context.includeDevInsight] - If true, ask for devInsight.
+ * @param {'endUser'|'developer'} [context.messageType] - Message tone.
+ * @param {string|Error|undefined} [context.error] - Optional error if one was passed (secondary signal).
+ * @returns {string}
+ */
+function buildPrompt(context) {
+  const { codeContext, method, path, includeDevInsight, messageType, error } = context;
+  const forDeveloper = messageType === 'developer';
+
+  const requestPart = [method, path].filter(Boolean).length
+    ? `Request: ${[method, path].filter(Boolean).join(' ')}`
+    : '';
+
+  let codePart = 'No code context was captured.';
+  if (codeContext?.snippets?.length) {
+    codePart = codeContext.snippets
+      .map((s, 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');
+  }
+
+  let errorPart = '';
+  if (error !== undefined && error !== null) {
+    if (error instanceof Error) {
+      errorPart = `\nOptional error message (may be empty): ${error.message}`;
+    } else {
+      errorPart = `\nOptional error/message: ${String(error)}`;
+    }
+  }
+
+  const devPart = includeDevInsight
+    ? '\nAlso provide a short "devInsight" string (one or two sentences) for the developer: (a) Is this likely a bug in the code or an environment/setup issue? (b) If the developer can fix it, suggest the fix. Be concise.'
+    : '';
+
+  const messageInstruction = forDeveloper
+    ? '- "message": string (short message for developers: may include technical detail, error type, or cause; do not include raw stack traces)'
+    : '- "message": string (short, end-user-facing message: safe for clients; do not expose stack traces, internal details, or technical jargon)';
+
+  return `You are helping map an application error to an HTTP response. The developer called ammo.throw() (or an error was thrown and caught) at the call site below. Use the surrounding code with line numbers and all upstream/downstream context to infer what went wrong and choose an appropriate HTTP status and message.
+
+Consider:
+- The code BEFORE the throw (upstream in the same function and in callers) — what led to this point.
+- The code AFTER the throw line (downstream) — what would have run next; this shows intent and expected flow.
+- The first snippet is the call site (line marked with →); later snippets are upstream callers.
+
+${requestPart ? requestPart + '\n\n' : ''}Code context (with line numbers; → marks the throw line):
+
+${codePart}${errorPart}
+${devPart ? '\n' + devPart : ''}
+
+Respond with only valid JSON, no markdown or explanation. Use this shape:
+- "statusCode": number (HTTP status, typically 4xx or 5xx; use 500 for generic/server errors)
+${messageInstruction}
+${includeDevInsight ? '- "devInsight": string (brief note for the developer only)' : ''}
+
+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.
+ *
+ * @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 }>}
+ */
+export async function inferErrorFromContext(context) {
+  const config = getErrorsLlmConfig();
+  const { baseURL, apiKey, model, messageType: configMessageType } = config;
+  const provider = createProvider({ baseURL, apiKey, model });
+
+  const isProduction = process.env.NODE_ENV === 'production';
+  const includeDevInsight = !isProduction && context.includeDevInsight !== false;
+  const messageType = context.messageType ?? configMessageType;
+
+  const prompt = buildPrompt({
+    codeContext: context.codeContext,
+    method: context.method,
+    path: context.path,
+    includeDevInsight,
+    messageType,
+    error: context.error,
+  });
+
+  const { content } = await provider.analyze(prompt);
+  const parsed = extractJSON(content);
+
+  if (!parsed || typeof parsed !== 'object') {
+    return {
+      statusCode: DEFAULT_STATUS,
+      message: DEFAULT_MESSAGE,
+      ...(includeDevInsight && { devInsight: 'Could not parse LLM response.' }),
+    };
+  }
+
+  let statusCode = Number(parsed.statusCode);
+  if (Number.isNaN(statusCode) || statusCode < 100 || statusCode > 599) {
+    statusCode = DEFAULT_STATUS;
+  }
+
+  const message =
+    typeof parsed.message === 'string' && parsed.message.trim()
+      ? parsed.message.trim()
+      : DEFAULT_MESSAGE;
+
+  const result = { statusCode, message };
+  if (includeDevInsight && typeof parsed.devInsight === 'string' && parsed.devInsight.trim()) {
+    result.devInsight = parsed.devInsight.trim();
+  }
+
+  return result;
+}

package/server/files/helper.js

@@ -1,33 +1,33 @@
-import mime from 'mime';
-
-const paths = (destination, filename) => {
-  const dir = `${process.cwd()}\\${destination}`;
-  const path = `${dir}\\${filename}`;
-
-  const absolute = path;
-  const relative = path.replace(process.cwd(), '');
-
-  return { dir, absolute, relative };
-};
-
-const extAndType = (obj) => {
-  const contentType = obj.headers['content-type'];
-  const ext = mime.getExtension(contentType);
-  const type = mime.getType(ext);
-  return {
-    ext,
-    type,
-  };
-};
-
-const extract = (contentDisposition, key) => {
-  if (!contentDisposition) {
-    return null;
-  }
-
-  const parts = contentDisposition.split(';').map((part) => part.trim());
-  const part = parts.find((part) => part.startsWith(key));
-  return part ? part?.split('=')[1]?.trim()?.replace(/"/g, '') : undefined;
-};
-
-export { extAndType, extract, paths };
+import mime from 'mime';
+
+const paths = (destination, filename) => {
+  const dir = `${process.cwd()}\\${destination}`;
+  const path = `${dir}\\${filename}`;
+
+  const absolute = path;
+  const relative = path.replace(process.cwd(), '');
+
+  return { dir, absolute, relative };
+};
+
+const extAndType = (obj) => {
+  const contentType = obj.headers['content-type'];
+  const ext = mime.getExtension(contentType);
+  const type = mime.getType(ext);
+  return {
+    ext,
+    type,
+  };
+};
+
+const extract = (contentDisposition, key) => {
+  if (!contentDisposition) {
+    return null;
+  }
+
+  const parts = contentDisposition.split(';').map((part) => part.trim());
+  const part = parts.find((part) => part.startsWith(key));
+  return part ? part?.split('=')[1]?.trim()?.replace(/"/g, '') : undefined;
+};
+
+export { extAndType, extract, paths };