te.js 2.1.1 → 2.1.3

package/auto-docs/analysis/handler-analyzer.js

@@ -15,9 +15,49 @@ const ALL_METHODS = [
 ];
 
 /**
- * Detects which HTTP methods the handler checks (e.g. ammo.GET, ammo.POST).
- * Matches property access patterns like `.GET`, `ammo.GET`, avoiding false positives
- * in strings or unrelated identifiers.
+ * Extracts allowed methods from .only('GET'), .only("POST", "PUT"), etc. in source.
+ * Returns a non-empty array only when at least one valid quoted method is found;
+ * otherwise [] so caller can fall back to other detection.
+ *
+ * @param {string} src - Handler source (e.g. handler.toString())
+ * @returns {string[]} Normalized method names (uppercase, HEAD added when GET present), or []
+ */
+function detectOnlyMethods(src) {
+  const startMarker = '.only(';
+  const start = src.indexOf(startMarker);
+  if (start === -1) return [];
+
+  let depth = 1;
+  let pos = start + startMarker.length;
+  while (pos < src.length && depth > 0) {
+    const ch = src[pos];
+    if (ch === '(') depth += 1;
+    else if (ch === ')') depth -= 1;
+    pos += 1;
+  }
+  const argsStr = src.slice(start + startMarker.length, pos - 1);
+
+  // Match quoted method names: 'GET', "POST", etc. Only accept known methods.
+  const quotedMethodRe = /['"](GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)['"]/gi;
+  const seen = new Set();
+  let match;
+  while ((match = quotedMethodRe.exec(argsStr)) !== null) {
+    seen.add(match[1].toUpperCase());
+  }
+  if (seen.size === 0) return [];
+
+  const list = [...seen];
+  if (list.includes('GET') && !list.includes('HEAD')) {
+    list.push('HEAD');
+  }
+  return list;
+}
+
+/**
+ * Detects which HTTP methods the handler checks (e.g. ammo.GET, ammo.POST)
+ * or restricts via ammo.only('GET'), ammo.only('GET','POST').
+ * Prefers .only(...) when present with valid string args; otherwise matches
+ * property access like `.GET`, `ammo.GET`.
  *
  * When no method checks are found, the endpoint is treated as method-agnostic
  * and accepts ALL methods (te.js default behavior).
@@ -29,8 +69,10 @@ function detectMethods(handler) {
   if (typeof handler !== 'function') return [...ALL_METHODS];
 
   const src = handler.toString();
-  const detected = [];
+  const onlyMethods = detectOnlyMethods(src);
+  if (onlyMethods.length > 0) return onlyMethods;
 
+  const detected = [];
   for (const m of ALL_METHODS) {
     // Match property access patterns like .GET, ammo.GET, avoiding
     // false positives in strings or unrelated identifiers

package/cors/index.js

@@ -0,0 +1,71 @@
+/**
+ * CORS middleware factory. Handles OPTIONS preflight with 204 and sets CORS response headers.
+ *
+ * @param {Object} config - CORS configuration
+ * @param {string|string[]|((origin: string) => boolean)} [config.origin='*'] - Allowed origin(s): '*' or array of origins or function
+ * @param {string[]} [config.methods=['GET','POST','PUT','DELETE','PATCH','HEAD','OPTIONS']] - Allowed methods for Access-Control-Allow-Methods
+ * @param {string[]} [config.allowedHeaders=['Content-Type','Authorization']] - Allowed request headers for Access-Control-Allow-Headers
+ * @param {boolean} [config.credentials=false] - Access-Control-Allow-Credentials (use with specific origin, not '*')
+ * @param {number} [config.maxAge] - Access-Control-Max-Age in seconds for preflight cache
+ * @returns {Function} Middleware (ammo, next)
+ */
+function corsMiddleware(config = {}) {
+  const {
+    origin = '*',
+    methods = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'],
+    allowedHeaders = ['Content-Type', 'Authorization'],
+    credentials = false,
+    maxAge,
+  } = config;
+
+  const methodsList = Array.isArray(methods)
+    ? methods.map((m) => String(m).toUpperCase()).join(', ')
+    : String(methods);
+  const headersList = Array.isArray(allowedHeaders)
+    ? allowedHeaders.join(', ')
+    : String(allowedHeaders);
+
+  const resolveOrigin = (requestOrigin) => {
+    if (typeof origin === 'function') {
+      return origin(requestOrigin) ? requestOrigin || '*' : null;
+    }
+    if (origin === '*') {
+      return credentials ? (requestOrigin || '*') : '*';
+    }
+    if (Array.isArray(origin)) {
+      const normalized = (requestOrigin || '').toLowerCase();
+      const allowed = origin.some(
+        (o) => String(o).toLowerCase() === normalized,
+      );
+      return allowed ? requestOrigin : null;
+    }
+    return String(origin) === (requestOrigin || '') ? requestOrigin : null;
+  };
+
+  return async (ammo, next) => {
+    const requestOrigin = ammo.req.headers.origin;
+
+    const allowOrigin = resolveOrigin(requestOrigin);
+    if (allowOrigin != null) {
+      ammo.res.setHeader('Access-Control-Allow-Origin', allowOrigin);
+    }
+    ammo.res.setHeader('Access-Control-Allow-Methods', methodsList);
+    ammo.res.setHeader('Access-Control-Allow-Headers', headersList);
+    if (credentials) {
+      ammo.res.setHeader('Access-Control-Allow-Credentials', 'true');
+    }
+    if (maxAge != null && Number.isFinite(maxAge)) {
+      ammo.res.setHeader('Access-Control-Max-Age', String(maxAge));
+    }
+
+    if (ammo.req.method === 'OPTIONS') {
+      ammo.res.writeHead(204);
+      ammo.res.end();
+      return;
+    }
+
+    await next();
+  };
+}
+
+export default corsMiddleware;

package/docs/configuration.md

@@ -59,6 +59,16 @@ app.takeoff();
 | `log.http_requests` | `LOG_HTTP_REQUESTS` | boolean | `false` | Log incoming HTTP requests (method, path, status, time) |
 | `log.exceptions` | `LOG_EXCEPTIONS` | boolean | `false` | Log unhandled exceptions and errors |
 
+### Developer warnings
+
+When an endpoint is called and it has no allowed methods defined (see [Routing — Endpoint Metadata](./routing.md#endpoint-metadata)), the framework logs a warning once per path so you can restrict methods for security (405 and `Allow` header). To disable this warning:
+
+| Config Key | Env Variable | Type | Default | Description |
+|------------|-------------|------|---------|-------------|
+| `warn_missing_allowed_methods` | `WARN_MISSING_ALLOWED_METHODS` | boolean/string | *(warn)* | Set to `false` to disable the runtime warning for endpoints without allowed methods. |
+
+Example: in `tejas.config.json` use `"warn_missing_allowed_methods": false`, or in `.env` use `WARN_MISSING_ALLOWED_METHODS=false`.
+
 ### Request Body
 
 | Config Key | Env Variable | Type | Default | Description |
@@ -178,6 +188,9 @@ LLM_MODEL=gpt-4o-mini
 # ERRORS_LLM_API_KEY=...
 # ERRORS_LLM_MODEL=...
 # ERRORS_LLM_MESSAGE_TYPE=endUser   # or "developer" for technical messages
+
+# Optional: disable runtime warning for endpoints without allowed methods
+# WARN_MISSING_ALLOWED_METHODS=false
 ```
 
 ## Constructor Options

package/docs/routing.md

@@ -214,6 +214,8 @@ target.register('/users', {
 
 When metadata is omitted, the auto-docs LLM infers everything from the handler source code.
 
+If an endpoint has no `methods` in its metadata (and does not use `ammo.only()` to restrict methods), the framework logs a warning the first time that path is called. You can disable this warning via config: set `WARN_MISSING_ALLOWED_METHODS=false` (env) or `warn_missing_allowed_methods: false` in config. See [Configuration — Developer warnings](./configuration.md#developer-warnings).
+
 ## Method-Agnostic Handlers
 
 If a handler does not check any method flags (`ammo.GET`, `ammo.POST`, etc.), it is treated as accepting **all HTTP methods**. This is useful for simple endpoints:

package/lib/llm/client.js

@@ -0,0 +1,73 @@
+/**
+ * Generic OpenAI-compatible LLM client for te.js.
+ * POSTs to {baseURL}/chat/completions; used by auto-docs, error-inference, and future LLM features.
+ * No provider-specific npm dependencies — uses fetch() only.
+ */
+
+const DEFAULT_BASE_URL = 'https://api.openai.com/v1';
+const DEFAULT_MODEL = 'gpt-4o-mini';
+
+/**
+ * OpenAI-compatible LLM provider. Exposes only constructor and analyze(prompt).
+ */
+class LLMProvider {
+  constructor(options = {}) {
+    this.baseURL = (options.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, '');
+    this.model = options.model ?? DEFAULT_MODEL;
+    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+    this.options = options;
+  }
+
+  /**
+   * Send a prompt to the LLM and return the raw text response and usage.
+   * @param {string} prompt
+   * @returns {Promise<{ content: string, usage: { prompt_tokens: number, completion_tokens: number, total_tokens: number } }>}
+   */
+  async analyze(prompt) {
+    const url = `${this.baseURL}/chat/completions`;
+    const headers = {
+      'Content-Type': 'application/json',
+      ...(this.apiKey && { Authorization: `Bearer ${this.apiKey}` }),
+    };
+    const body = {
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    };
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`LLM request failed (${res.status}): ${text.slice(0, 300)}`);
+    }
+
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content ?? '';
+    const text = typeof content === 'string' ? content : JSON.stringify(content);
+    const rawUsage = data.usage;
+    const usage = {
+      prompt_tokens: rawUsage?.prompt_tokens ?? 0,
+      completion_tokens: rawUsage?.completion_tokens ?? 0,
+      total_tokens: rawUsage?.total_tokens ?? (rawUsage?.prompt_tokens ?? 0) + (rawUsage?.completion_tokens ?? 0),
+    };
+    return { content: text, usage };
+  }
+}
+
+/**
+ * Create an LLM provider from config.
+ * @param {object} config - { baseURL?, apiKey?, model? }
+ * @returns {LLMProvider}
+ */
+function createProvider(config) {
+  if (!config || typeof config !== 'object') {
+    return new LLMProvider({});
+  }
+  return new LLMProvider(config);
+}
+
+export { LLMProvider, createProvider };

package/lib/llm/index.js

@@ -0,0 +1,7 @@
+/**
+ * Shared LLM module for te.js: generic client and parse utilities.
+ * Used by auto-docs, error-inference, and future LLM features.
+ */
+
+export { LLMProvider, createProvider } from './client.js';
+export { extractJSON, extractJSONArray, reconcileOrderedTags } from './parse.js';

package/lib/llm/parse.js

@@ -0,0 +1,89 @@
+/**
+ * Parse JSON from LLM response text (handles markdown code blocks).
+ * Shared by auto-docs, error-inference, and other LLM features.
+ */
+
+/**
+ * Extract the first JSON object from a string.
+ * @param {string} str - Raw LLM response
+ * @returns {object|null}
+ */
+export function extractJSON(str) {
+  if (!str || typeof str !== 'string') return null;
+  const trimmed = str.trim();
+  const open = trimmed.indexOf('{');
+  if (open === -1) return null;
+  let depth = 0;
+  let end = -1;
+  for (let i = open; i < trimmed.length; i++) {
+    if (trimmed[i] === '{') depth++;
+    else if (trimmed[i] === '}') {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) return null;
+  try {
+    return JSON.parse(trimmed.slice(open, end));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extract the first JSON array from a string.
+ * @param {string} str - Raw LLM response
+ * @returns {Array|null}
+ */
+export function extractJSONArray(str) {
+  if (!str || typeof str !== 'string') return null;
+  const trimmed = str.trim();
+  const open = trimmed.indexOf('[');
+  if (open === -1) return null;
+  let depth = 0;
+  let end = -1;
+  for (let i = open; i < trimmed.length; i++) {
+    if (trimmed[i] === '[') depth++;
+    else if (trimmed[i] === ']') {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === -1) return null;
+  try {
+    return JSON.parse(trimmed.slice(open, end));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Reconcile LLM-ordered tag names with actual tag objects. Returns tags in desired order;
+ * any tag not in orderedTagNames is appended at the end.
+ * @param {string[]} orderedTagNames - Tag names in desired order (from LLM)
+ * @param {Array<{ name: string, description?: string }>} tags - Current spec.tags
+ * @returns {Array<{ name: string, description?: string }>} Tags reordered
+ */
+export function reconcileOrderedTags(orderedTagNames, tags) {
+  if (!Array.isArray(tags) || !tags.length) return [];
+  if (!Array.isArray(orderedTagNames) || !orderedTagNames.length) return [...tags];
+  const byName = new Map(tags.map((t) => [t.name, t]));
+  const ordered = [];
+  for (const name of orderedTagNames) {
+    const tag = byName.get(name);
+    if (tag) {
+      ordered.push(tag);
+      byName.delete(name);
+    }
+  }
+  for (const [, tag] of byName) {
+    ordered.push(tag);
+  }
+  return ordered;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "te.js",
-  "version": "2.1.1",
-  "description": "A nodejs framework",
+  "version": "2.1.3",
+  "description": "AI Native Node.js Framework",
   "type": "module",
   "main": "te.js",
   "bin": {
@@ -30,10 +30,12 @@
   "files": [
     "te.js",
     "cli",
+    "cors",
     "server",
     "database",
     "rate-limit",
     "utils",
+    "lib",
     "auto-docs",
     "README.md",
     "docs"

package/server/handler.js

@@ -7,6 +7,9 @@ import TejError from './error.js';
 import targetRegistry from './targets/registry.js';
 
 const errorLogger = new TejLogger('Tejas.Exception');
+const logger = new TejLogger('Tejas');
+/** Paths we have already warned about (missing allowed methods). */
+const warnedPaths = new Set();
 
 const DEFAULT_ALLOWED_METHODS = [
   'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
@@ -134,6 +137,12 @@ const handler = async (req, res) => {
           await errorHandler(ammo, new TejError(405, 'Method Not Allowed'));
           return;
         }
+      } else if (env('WARN_MISSING_ALLOWED_METHODS') !== 'false') {
+        const path = match.target.getPath();
+        if (!warnedPaths.has(path)) {
+          warnedPaths.add(path);
+          logger.warn(`Endpoint missing allowed methods: ${path}`);
+        }
       }
 
       // Add route parameters to ammo.payload