te.js 1.3.1 → 2.0.0

package/auto-docs/openapi/spec-builders.js

@@ -0,0 +1,244 @@
+/**
+ * Pure OpenAPI 3.0 schema and operation builders for auto-documentation.
+ * No LLM, file I/O, or registry dependencies.
+ */
+
+import { ALL_METHODS } from '../analysis/handler-analyzer.js';
+import { METHOD_KEYS } from '../constants.js';
+
+/**
+ * Returns true if the object is method-keyed metadata (keys are HTTP methods, values are { summary?, description?, request?, response? }).
+ * @param {object} obj - Parsed LLM response
+ * @returns {boolean}
+ */
+export function isMethodKeyed(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  for (const key of Object.keys(obj)) {
+    if (METHOD_KEYS.has(key.toLowerCase())) {
+      const val = obj[key];
+      if (val && typeof val === 'object' && (val.summary != null || val.response != null)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Convert te.js path pattern to OpenAPI path (e.g. /users/:id -> /users/{id}).
+ * @param {string} path - Route path possibly containing :param segments
+ * @returns {string}
+ */
+export function toOpenAPIPath(path) {
+  if (!path || typeof path !== 'string') return '/';
+  return path.replace(/:([^/]+)/g, '{$1}');
+}
+
+/**
+ * Extract path parameter definitions from a te.js path for OpenAPI.
+ * @param {string} path - Route path (e.g. /users/:id)
+ * @returns {Array<{ name: string, in: string, required: boolean, schema: object }>}
+ */
+export function getPathParameters(path) {
+  if (!path || typeof path !== 'string') return [];
+  const params = [];
+  const segmentRegex = /:([^/]+)/g;
+  let match;
+  while ((match = segmentRegex.exec(path)) !== null) {
+    params.push({
+      name: match[1],
+      in: 'path',
+      required: true,
+      description: `Path parameter: ${match[1]}`,
+      schema: { type: 'string' },
+    });
+  }
+  return params;
+}
+
+/**
+ * Build OpenAPI query parameter list from request.query metadata.
+ * @param {object} queryMeta - e.g. { limit: { type: 'integer', required: false }, q: { type: 'string', required: true } }
+ * @returns {Array<{ name: string, in: string, required: boolean, description?: string, schema: object }>}
+ */
+export function getQueryParameters(queryMeta) {
+  if (!queryMeta || typeof queryMeta !== 'object') return [];
+  const params = [];
+  for (const [name, spec] of Object.entries(queryMeta)) {
+    if (!spec || typeof spec !== 'object' || !spec.type) continue;
+    params.push({
+      name,
+      in: 'query',
+      required: spec.required === true || spec.required === 'true',
+      ...(spec.description && { description: spec.description }),
+      schema: { type: spec.type, ...(spec.format && { format: spec.format }) },
+    });
+  }
+  return params;
+}
+
+/**
+ * Convert simple metadata schema (field -> { type, description? }) to OpenAPI schema.
+ * @param {object} meta - e.g. { name: { type: 'string' }, email: { type: 'string' } }
+ * @returns {object} OpenAPI schema with properties
+ */
+export function buildSchemaFromMetadata(meta) {
+  if (!meta || typeof meta !== 'object') return {};
+  const properties = {};
+  const required = [];
+  for (const [key, value] of Object.entries(meta)) {
+    if (value && typeof value === 'object' && value.type) {
+      properties[key] = {
+        type: value.type,
+        ...(value.description && { description: value.description }),
+        ...(value.format && { format: value.format }),
+      };
+      if (value.required === true || value.required === 'true') required.push(key);
+    }
+  }
+  if (Object.keys(properties).length === 0) return {};
+  return {
+    type: 'object',
+    properties,
+    ...(required.length > 0 && { required }),
+  };
+}
+
+/**
+ * Build request body schema for an operation from metadata or empty.
+ * @param {object} requestMeta - metadata.request (body schema)
+ * @returns {object|undefined} OpenAPI requestBody or undefined
+ */
+export function buildRequestBody(requestMeta) {
+  if (!requestMeta?.body || typeof requestMeta.body !== 'object') return undefined;
+  const schema = buildSchemaFromMetadata(requestMeta.body);
+  if (!schema || Object.keys(schema).length === 0) return undefined;
+  return {
+    required: true,
+    content: {
+      'application/json': {
+        schema,
+      },
+    },
+  };
+}
+
+/**
+ * Build response object for an operation from metadata.
+ * @param {object} responseMeta - metadata.response (e.g. { 200: { description, schema? }, 201: { ... } })
+ * @returns {object} OpenAPI responses
+ */
+export function buildResponses(responseMeta) {
+  const responses = {};
+  if (!responseMeta || typeof responseMeta !== 'object') {
+    responses['200'] = { description: 'Success' };
+    return responses;
+  }
+  for (const [code, spec] of Object.entries(responseMeta)) {
+    if (!spec || typeof spec !== 'object') continue;
+    responses[String(code)] = {
+      description: spec.description || `Response ${code}`,
+      ...(spec.schema && {
+        content: {
+          'application/json': {
+            schema: typeof spec.schema === 'object' && spec.schema.type
+              ? spec.schema
+              : { type: 'object' },
+          },
+        },
+      }),
+    };
+  }
+  if (Object.keys(responses).length === 0) {
+    responses['200'] = { description: 'Success' };
+  }
+  return responses;
+}
+
+/**
+ * Returns true when the endpoint accepts all standard HTTP methods (method-agnostic).
+ * @param {string[]} methods
+ * @returns {boolean}
+ */
+export function isMethodAgnostic(methods) {
+  if (!Array.isArray(methods) || methods.length !== ALL_METHODS.length) return false;
+  const set = new Set(methods.map((m) => m.toUpperCase()));
+  return ALL_METHODS.every((m) => set.has(m));
+}
+
+/**
+ * Build a single OpenAPI operation for one HTTP method.
+ * @param {string} method - HTTP method (GET, POST, etc.)
+ * @param {object} meta - Merged metadata (explicit + LLM-enhanced): summary, description?, request?, response?
+ * @param {Array} pathParams - Path parameters for this path
+ * @param {object} [options] - { methodAgnostic?: boolean } - when true, description notes all accepted methods
+ * @returns {object} OpenAPI operation object
+ */
+export function buildOperation(method, meta, pathParams, options = {}) {
+  const { methodAgnostic = false } = options;
+  let description = meta.description || '';
+  if (methodAgnostic) {
+    const methodList = ALL_METHODS.join(', ');
+    description = description
+      ? `${description}\n\nAccepts any HTTP method: ${methodList}.`
+      : `Accepts any HTTP method: ${methodList}.`;
+  }
+  const queryParams = getQueryParameters(meta.request?.query);
+  const allParams = [...pathParams, ...queryParams];
+  const op = {
+    summary: meta.summary || '',
+    ...(description && { description }),
+    parameters: allParams.length > 0 ? allParams : undefined,
+  };
+  const methodUpper = method.toUpperCase();
+  const body = buildRequestBody(meta.request);
+  if (body && (methodAgnostic || (methodUpper !== 'GET' && methodUpper !== 'HEAD'))) {
+    op.requestBody = body;
+  }
+  op.responses = buildResponses(meta.response);
+  return op;
+}
+
+/**
+ * Merge explicit endpoint metadata with LLM-enhanced result.
+ * @param {object} explicit - From endpoint.getMetadata()
+ * @param {object} enhanced - From llm.enhanceEndpointDocs() or per-method enhancer
+ * @param {object} [options] - { preferEnhanced?: boolean } - when true (level 2), LLM response wins over explicit
+ * @returns {object}
+ */
+export function mergeMetadata(explicit, enhanced, options = {}) {
+  const preferEnhanced = options.preferEnhanced === true;
+  const summary = preferEnhanced
+    ? (enhanced?.summary ?? explicit?.summary ?? '')
+    : (explicit?.summary ?? enhanced?.summary ?? '');
+  const description = preferEnhanced
+    ? (enhanced?.description ?? explicit?.description ?? '')
+    : (explicit?.description ?? enhanced?.description ?? '');
+  const request = preferEnhanced
+    ? (enhanced?.request ?? explicit?.request)
+    : (explicit?.request ?? enhanced?.request);
+  const response = preferEnhanced
+    ? (enhanced?.response ?? explicit?.response)
+    : (explicit?.response ?? enhanced?.response);
+  return {
+    summary: summary || 'Endpoint',
+    description: description || undefined,
+    ...(request && { request }),
+    ...(response && { response }),
+  };
+}
+
+/**
+ * Merge method-keyed metadata for a method-agnostic endpoint into a single meta (preferred order).
+ * @param {Map<string,object>} metaByMethod
+ * @param {string[]} methods
+ * @param {object} fallbackMeta
+ * @returns {object}
+ */
+export function mergeMethodAgnosticMeta(metaByMethod, methods, fallbackMeta) {
+  const preferredOrder = ['post', 'put', 'patch', 'get', 'delete', 'head', 'options'];
+  for (const k of preferredOrder) {
+    const m = metaByMethod.get(k);
+    if (m && (m.summary || m.description)) return m;
+  }
+  const first = metaByMethod.values().next().value;
+  return first || fallbackMeta;
+}

package/auto-docs/ui/docs-ui.js

@@ -0,0 +1,186 @@
+/**
+ * Serves interactive API docs at /docs with try-out functionality.
+ * Uses Scalar API Reference (modern UI, try-it-out, themes). MIT.
+ * Registers internal routes: GET /docs (HTML page) and GET /docs/openapi.json (spec).
+ *
+ * @see https://scalar.com/products/api-references/integrations/html-js
+ * @see https://scalar.com/products/api-references/configuration
+ */
+
+import Endpoint from '../../server/endpoint.js';
+import targetRegistry from '../../server/targets/registry.js';
+
+/** Scalar API Reference browser standalone (IIFE, sets window.Scalar). Pinned for stability. */
+const SCALAR_VERSION = '1.46.0';
+const SCALAR_STANDALONE = `https://cdn.jsdelivr.net/npm/@scalar/api-reference@${SCALAR_VERSION}/dist/browser/standalone.js`;
+
+/**
+ * Default Scalar API Reference config. Use layout: 'classic' to show the test request
+ * inline on the same page instead of opening a dialog (modern layout).
+ *
+ * @see https://scalar.com/products/api-references/configuration
+ */
+const DEFAULT_SCALAR_CONFIG = {
+  layout: 'modern',
+  theme: 'default',
+  showSidebar: true,
+  hideDownloadButton: false,
+  hideModels: false,
+  hideSearch: false,
+  hideDarkModeToggle: false,
+  hideTestRequestButton: false,
+  showDeveloperTools: 'localhost',
+  documentDownloadType: 'both',
+  defaultOpenAllTags: false,
+  defaultOpenFirstTag: true,
+  expandAllModelSections: false,
+  expandAllResponses: false,
+  withDefaultFonts: true,
+};
+
+/**
+ * Build HTML shell for Scalar docs: script tag + inline config and mount logic.
+ * @param {string} scriptUrl - URL to Scalar standalone JS
+ * @param {string} configJson - JSON string (already escaped for embedding in JS)
+ * @returns {string} Full HTML document
+ */
+function buildDocsHtmlShell(scriptUrl, configJson) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>API Reference</title>
+  <style>
+    body { margin: 0; min-height: 100vh; font-family: system-ui, sans-serif; }
+    #scalar-app { min-height: 100vh; width: 100%; }
+  </style>
+</head>
+<body>
+  <div id="scalar-app"></div>
+  <script src="${scriptUrl}" id="scalar-script"><\/script>
+  <script>
+    (function() {
+      var config = JSON.parse('${configJson}');
+      function mount() {
+        if (typeof Scalar !== 'undefined' && typeof Scalar.createApiReference === 'function') {
+          Scalar.createApiReference('#scalar-app', config);
+          return true;
+        }
+        return false;
+      }
+      var el = document.getElementById('scalar-script');
+      if (el) {
+        el.addEventListener('load', function() { mount(); });
+        if (el.readyState === 'complete') setTimeout(function() { mount(); }, 0);
+      }
+      if (!mount()) setTimeout(function() { mount(); }, 100);
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+/**
+ * Builds the HTML page that embeds Scalar and points to the spec URL.
+ * @param {string} specUrl - URL to the OpenAPI spec (e.g. '/docs/openapi.json' or full URL).
+ * @param {object} [scalarConfig] - Optional Scalar API Reference config (merged with defaults).
+ * @returns {string} Full HTML document.
+ */
+function buildDocsPage(specUrl, scalarConfig = {}) {
+  const url = specUrl || '/docs/openapi.json';
+  const config = { ...DEFAULT_SCALAR_CONFIG, ...scalarConfig, url };
+  const configJson = JSON.stringify(config)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e');
+  return buildDocsHtmlShell(SCALAR_STANDALONE, configJson);
+}
+
+/**
+ * Create endpoint that serves the docs HTML page at GET docsPath.
+ * @param {string} docsPath - e.g. '/docs'
+ * @param {string} htmlContent - Full HTML document
+ * @returns {Endpoint}
+ */
+function createDocsHtmlEndpoint(docsPath, htmlContent) {
+  const endpoint = new Endpoint();
+  endpoint.setPath('', docsPath);
+  endpoint.setMiddlewares([]);
+  endpoint.setHandler((ammo) => {
+    if (!ammo.GET) return ammo.notAllowed();
+    ammo.fire(200, htmlContent, 'text/html');
+  });
+  return endpoint;
+}
+
+/**
+ * Create endpoint that serves the OpenAPI spec JSON at GET specPath.
+ * @param {string} specPath - e.g. '/docs/openapi.json'
+ * @param {() => object | Promise<object>} getSpec - Function that returns the current spec
+ * @returns {Endpoint}
+ */
+function createSpecJsonEndpoint(specPath, getSpec) {
+  const endpoint = new Endpoint();
+  endpoint.setPath('', specPath);
+  endpoint.setMiddlewares([]);
+  endpoint.setHandler(async (ammo) => {
+    if (!ammo.GET) return ammo.notAllowed();
+    try {
+      const spec = await Promise.resolve(getSpec());
+      ammo.fire(200, spec);
+    } catch (err) {
+      ammo.fire(500, {
+        error: 'Failed to generate OpenAPI spec',
+        message: err?.message,
+      });
+    }
+  });
+  return endpoint;
+}
+
+/**
+ * Registers the docs and openapi.json routes (or returns endpoints when mutateRegistry is false).
+ * Call this after the OpenAPI spec is available (e.g. after generateOpenAPISpec).
+ *
+ * @param {object} [options]
+ * @param {() => object | Promise<object>} options.getSpec - Function that returns the current OpenAPI spec (sync or async). Used for GET {docsPath}/openapi.json.
+ * @param {string} [options.docsPath='/docs'] - Base path for docs (HTML page and spec URL). Routes: GET {docsPath}, GET {docsPath}/openapi.json.
+ * @param {string} [options.specUrl] - Override for the spec URL shown in the docs page (default: '{docsPath}/openapi.json'). Use when serving behind a proxy with a different base path.
+ * @param {object} [options.scalarConfig] - Optional Scalar API Reference config (e.g. { layout: 'classic' } for try-it on the same page).
+ * @param {boolean} [options.mutateRegistry=true] - If true, push endpoints to registry. If false, return [docsEndpoint, specEndpoint] without mutating.
+ * @param {object} [registry] - Target registry to register routes on when mutateRegistry is true. Defaults to the module's targetRegistry.
+ * @returns {undefined | [Endpoint, Endpoint]} When mutateRegistry is false, returns the two endpoints for the caller to register.
+ */
+export function registerDocRoutes(options = {}, registry = targetRegistry) {
+  const {
+    getSpec,
+    docsPath = '/docs',
+    specUrl: specUrlOption,
+    scalarConfig,
+    mutateRegistry = true,
+  } = options;
+
+  if (typeof getSpec !== 'function') {
+    throw new Error(
+      'registerDocRoutes requires options.getSpec (function returning the OpenAPI spec)',
+    );
+  }
+
+  const basePath = docsPath.replace(/\/$/, '');
+  const specUrl = specUrlOption ?? `${basePath}/openapi.json`;
+  const specPath = `${basePath}/openapi.json`;
+  const htmlContent = buildDocsPage(specUrl, scalarConfig);
+
+  const docsEndpoint = createDocsHtmlEndpoint(docsPath, htmlContent);
+  const specEndpoint = createSpecJsonEndpoint(specPath, getSpec);
+
+  if (mutateRegistry) {
+    registry.targets.push(docsEndpoint);
+    registry.targets.push(specEndpoint);
+    return;
+  }
+  return [docsEndpoint, specEndpoint];
+}
+
+export { buildDocsPage };
+export default registerDocRoutes;

package/auto-docs/utils/logger.js

@@ -0,0 +1,17 @@
+/**
+ * Verbose logging helper for auto-docs.
+ * Returns a no-op when verbose is false or logger has no info method.
+ */
+
+/**
+ * Create a logger that only logs when verbose is true and logger.info exists.
+ * @param {object|null} logger - Logger with .info(msg) method
+ * @param {boolean} verbose - Whether to log
+ * @returns {(msg: string) => void} Function that logs or does nothing
+ */
+export function createVerboseLogger(logger, verbose) {
+  if (!verbose || !logger || typeof logger.info !== 'function') {
+    return () => {};
+  }
+  return (msg) => logger.info(msg);
+}

package/auto-docs/utils/strip-usage.js

@@ -0,0 +1,10 @@
+/**
+ * Strip LLM-only fields from response so they are not merged into metadata.
+ * @param {object|null} obj - Raw LLM response (may contain _usage, _fallback)
+ * @returns {object|null} Same object without _usage and _fallback
+ */
+export function stripLlmUsage(obj) {
+  if (!obj || typeof obj !== 'object') return obj;
+  const { _usage, _fallback, ...rest } = obj;
+  return rest;
+}