tina4-nodejs 3.12.3 → 3.12.4

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.3)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.12.4)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.12.3 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.12.4 — The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 
@@ -1094,3 +1094,32 @@ Always read and follow the instructions in .claude/skills/tina4-developer/SKILL.
 
 ## Tina4-js Frontend Skill
 Always read and follow the instructions in .claude/skills/tina4-js/SKILL.md when working with tina4-js frontend code. Read its referenced files in .claude/skills/tina4-js/references/ as needed.
+
+## First Principle: Documentation Matches Code Reality
+
+**This rule overrides everything else in this file.**
+
+Every command, env var, method, class, or feature mentioned in any
+documentation file (`*.md` in this repo, or any tina4-book chapter,
+or `tina4-documentation/docs/`) MUST exist in code. No exceptions.
+No "we'll build it later" entries. No Laravel/Rails-style commands
+that look right but don't exist. No env vars that the framework
+doesn't actually read.
+
+When you add a doc reference, add the implementation in the same PR.
+When you remove a feature, remove every doc reference in the same PR.
+When you find drift, fix it both ways: build the real thing OR delete
+the doc.
+
+The `tina4-documentation/scripts/audit-truth.py` script is the source
+of truth. It runs as a CI gate (`audit-truth.yml`) on every PR — the
+build fails on CLI drift. Run it locally before pushing if you've
+touched docs:
+
+```bash
+cd /path/to/tina4-documentation
+python3 scripts/audit-truth.py --strict
+```
+
+If you're unsure whether something exists, run `tina4 <command> --help`
+or grep the framework source. Don't guess.

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.12.3",
+  "version": "3.12.4",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript — 54 built-in features, zero dependencies",

package/packages/core/src/dotenv.ts

@@ -76,11 +76,18 @@ function parseEnvContent(content: string): Record<string, string> {
  * Load environment variables from a .env file into process.env.
  * Does not override existing process.env values unless they are undefined.
  *
- * @param path - Path to the .env file. Defaults to ".env" in the current working directory.
+ * Resolution order for the env file path:
+ *   1. Explicit `path` argument
+ *   2. `TINA4_ENV_FILE` env var (if set and non-empty)
+ *   3. `.env` in the current working directory
+ *
+ * @param path - Path to the .env file. Optional override.
  * @returns The parsed key-value pairs, or an empty object if the file doesn't exist.
  */
 export function loadEnv(path?: string): Record<string, string> {
-  const envPath = resolve(path ?? ".env");
+  const fromEnv = (process.env.TINA4_ENV_FILE ?? "").trim();
+  const target = path ?? (fromEnv.length > 0 ? fromEnv : ".env");
+  const envPath = resolve(target);
 
   if (!existsSync(envPath)) {
     return {};

package/packages/core/src/graphql.ts

@@ -374,6 +374,29 @@ interface QueryConfig {
   resolver: ResolverFn;
 }
 
+// ── Env-driven config ────────────────────────────────────────
+
+/**
+ * URL the GraphQL handler should be mounted at.
+ * `TINA4_GRAPHQL_ENDPOINT` overrides the default `/graphql`.
+ */
+export function graphqlEndpoint(): string {
+  const raw = (process.env.TINA4_GRAPHQL_ENDPOINT ?? "").trim();
+  if (raw.length === 0) return "/graphql";
+  return raw.startsWith("/") ? raw : `/${raw}`;
+}
+
+/**
+ * Whether to auto-generate the schema from registered ORM models.
+ * `TINA4_GRAPHQL_AUTO_SCHEMA=true` (default) lets the dev server build a
+ * usable schema with no manual wiring; set to `false` to require explicit
+ * `addType` / `addQuery` calls.
+ */
+export function graphqlAutoSchemaEnabled(): boolean {
+  const raw = (process.env.TINA4_GRAPHQL_AUTO_SCHEMA ?? "true").trim().toLowerCase();
+  return ["true", "1", "yes", "on"].includes(raw);
+}
+
 // ── GraphQL Engine ───────────────────────────────────────────
 
 export class GraphQL {

package/packages/core/src/health.ts

@@ -1,27 +1,46 @@
-import type { RouteDefinition } from "./types.js";
+import type { RouteDefinition, RouteHandler } from "./types.js";
 
 /** Server start time, set when health route is created */
 let startTime: number;
 
 /**
- * Create the /health route definition.
- * Returns a RouteDefinition that can be added to the router.
+ * Resolve the health route path. Priority:
+ *   1. `TINA4_HEALTH_PATH` env var
+ *   2. Default `/__health` (matches Python parity — under-prefix avoids
+ *      colliding with app routes named /health)
+ */
+export function healthPath(): string {
+  const raw = (process.env.TINA4_HEALTH_PATH ?? "").trim();
+  if (raw.length === 0) return "/__health";
+  return raw.startsWith("/") ? raw : `/${raw}`;
+}
+
+function buildHandler(version: string): RouteHandler {
+  return (_req, res) => {
+    const uptimeSeconds = (Date.now() - startTime) / 1000;
+    res.json({
+      status: "ok",
+      version,
+      uptime: Math.round(uptimeSeconds * 100) / 100,
+      framework: "tina4-nodejs",
+    });
+  };
+}
+
+/**
+ * Create the primary health route definition.
+ *
+ * Tests use this directly. Server bootstrap goes through createHealthRoutes()
+ * to also register the legacy `/health` alias when TINA4_HEALTH_PATH points
+ * elsewhere — matching Python behaviour so existing probes don't break.
  */
 export function createHealthRoute(version: string = "3.0.0"): RouteDefinition {
   startTime = Date.now();
 
   return {
     method: "GET",
-    pattern: "/health",
-    handler: (_req, res) => {
-      const uptimeSeconds = (Date.now() - startTime) / 1000;
-      res.json({
-        status: "ok",
-        version,
-        uptime: Math.round(uptimeSeconds * 100) / 100,
-        framework: "tina4-nodejs",
-      });
-    },
+    pattern: healthPath(),
+    handler: buildHandler(version),
     meta: {
       summary: "Health check",
       description: "Returns server health status, version, and uptime.",
@@ -29,3 +48,42 @@ export function createHealthRoute(version: string = "3.0.0"): RouteDefinition {
     },
   };
 }
+
+/**
+ * Create one or two health routes — the env-defined path always, plus a
+ * legacy `/health` alias when the env path differs. Mirrors
+ * tina4-python's two-line registration in `core/server.py`.
+ */
+export function createHealthRoutes(version: string = "3.0.0"): RouteDefinition[] {
+  startTime = Date.now();
+  const routes: RouteDefinition[] = [];
+  const path = healthPath();
+
+  routes.push({
+    method: "GET",
+    pattern: path,
+    handler: buildHandler(version),
+    meta: {
+      summary: "Health check",
+      description: "Returns server health status, version, and uptime.",
+      tags: ["System"],
+    },
+  });
+
+  // Always register /health for backwards compatibility with existing probes
+  // (Kubernetes liveness/readiness, load balancers, monitoring scripts).
+  if (path !== "/health") {
+    routes.push({
+      method: "GET",
+      pattern: "/health",
+      handler: buildHandler(version),
+      meta: {
+        summary: "Health check (legacy alias)",
+        description: "Backwards-compatible alias for the configured health path.",
+        tags: ["System"],
+      },
+    });
+  }
+
+  return routes;
+}

package/packages/core/src/index.ts

@@ -12,9 +12,9 @@ export type {
   WebSocketRouteDefinition,
 } from "./types.js";
 
-export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled } from "./server.js";
+export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled, isBannerSuppressed } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
-export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
+export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares, isTrailingSlashRedirectEnabled } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";
 export type { RouteInfo } from "./router.js";
 export { discoverRoutes } from "./routeDiscovery.js";
@@ -25,7 +25,7 @@ export { createResponse, errorResponse, setDefaultTemplatesDir, getFrond, setFro
 export { tryServeStatic } from "./static.js";
 export { loadEnv, getEnv, requireEnv, hasEnv, allEnv, resetEnv, isTruthy } from "./dotenv.js";
 export { Log } from "./logger.js";
-export { createHealthRoute } from "./health.js";
+export { createHealthRoute, createHealthRoutes, healthPath } from "./health.js";
 export { rateLimiter } from "./rateLimiter.js";
 export type { RateLimiterConfig } from "./rateLimiter.js";
 export {
@@ -45,7 +45,7 @@ export {
   refreshToken, authenticateRequest, validateApiKey,
   Auth,
 } from "./auth.js";
-export { Session, FileSessionHandler, RedisSessionHandler } from "./session.js";
+export { Session, FileSessionHandler, RedisSessionHandler, buildSessionCookie } from "./session.js";
 export type { SessionConfig, SessionHandler } from "./session.js";
 export { I18n } from "./i18n.js";
 export { FakeData } from "./fakeData.js";
@@ -55,7 +55,7 @@ export { Queue } from "./queue.js";
 export type { QueueConfig, QueueJob, ProcessOptions } from "./queue.js";
 export { createJob } from "./job.js";
 export type { JobData, JobQueueBridge } from "./job.js";
-export { GraphQL, ParseError } from "./graphql.js";
+export { GraphQL, ParseError, graphqlEndpoint, graphqlAutoSchemaEnabled } from "./graphql.js";
 export type { GraphQLField, ResolverFn, GraphQLResult } from "./graphql.js";
 export {
   WebSocketServer,
@@ -108,7 +108,7 @@ export type { WebSocketBackplane } from "./websocketBackplane.js";
 export {
   McpServer, mcpTool, mcpResource, registerDevTools,
   encodeResponse, encodeError, encodeNotification, decodeRequest,
-  schemaFromParams, isLocalhost,
+  schemaFromParams, isLocalhost, mcpEnabled, mcpPort,
   PARSE_ERROR, INVALID_REQUEST, METHOD_NOT_FOUND, INVALID_PARAMS, INTERNAL_ERROR,
 } from "./mcp.js";
 export type { JsonRpcMessage, McpToolDefinition, McpResourceDefinition, JsonSchema, McpToolParam } from "./mcp.js";

package/packages/core/src/logger.ts

@@ -5,12 +5,13 @@ import {
   renameSync,
   statSync,
   unlinkSync,
+  writeFileSync,
 } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, isAbsolute } from "node:path";
 import { isTruthy } from "./dotenv.js";
 
 /** Log level severity */
-type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR";
+type LogLevel = "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
 
 /** Log level priority for filtering */
 const LEVEL_PRIORITY: Record<LogLevel, number> = {
@@ -18,6 +19,7 @@ const LEVEL_PRIORITY: Record<LogLevel, number> = {
   INFO: 1,
   WARNING: 2,
   ERROR: 3,
+  CRITICAL: 4,
 };
 
 /** Structured log entry for JSON output */
@@ -31,10 +33,11 @@ interface LogEntry {
 
 /** ANSI color codes for terminal output */
 const COLORS: Record<LogLevel, string> = {
-  DEBUG: "\x1b[36m",   // cyan
-  INFO: "\x1b[32m",    // green
-  WARNING: "\x1b[33m", // yellow
-  ERROR: "\x1b[31m",   // red
+  DEBUG: "\x1b[36m",    // cyan
+  INFO: "\x1b[32m",     // green
+  WARNING: "\x1b[33m",  // yellow
+  ERROR: "\x1b[31m",    // red
+  CRITICAL: "\x1b[35m", // magenta
 };
 const RESET = "\x1b[0m";
 
@@ -47,28 +50,103 @@ const DEFAULT_LOG_DIR = "logs";
 /** Default log filename */
 const DEFAULT_LOG_FILE = "tina4.log";
 
+/** Default rotation size — 10 MB */
+const DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024;
+
+/** Default rotation keep count */
+const DEFAULT_ROTATE_KEEP = 5;
+
 /** Strip ANSI escape codes from a string */
 function stripAnsi(text: string): string {
   return text.replace(ANSI_RE, "");
 }
 
+/**
+ * Resolve the log file path from env (or constructor options).
+ *
+ * If `TINA4_LOG_FILE` is set:
+ *   - absolute path → used as-is.
+ *   - relative      → resolved against `TINA4_LOG_DIR` (default `logs`).
+ *
+ * Otherwise the directory is `TINA4_LOG_DIR` and filename is `tina4.log`.
+ */
+function resolveLogFilePath(logDir: string, logFile: string): string {
+  if (isAbsolute(logFile)) return logFile;
+  return join(logDir, logFile);
+}
+
 /**
  * Structured logger for Tina4.
  *
- * Production (TINA4_DEBUG not truthy): JSON lines to logs/tina4.log
+ * Production (TINA4_DEBUG not truthy): JSON or text lines to logs/tina4.log
  * Development (TINA4_DEBUG=true): Colorized human-readable to stdout + file
  *
- * Log rotation: numbered scheme (tina4.log -> tina4.log.1 -> ... -> tina4.log.{keep})
- * Raw log file always writes ALL levels (no filtering), plain text (no ANSI codes).
- * Console output respects TINA4_LOG_LEVEL.
+ * Env vars:
+ *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Empty = use TINA4_LOG_DIR + tina4.log
+ *   TINA4_LOG_DIR           — directory for log files (default: "logs")
+ *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text")
+ *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout")
+ *   TINA4_LOG_CRITICAL      — "true" to enable CRITICAL level shortcut (default: "false")
+ *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
+ *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
+ *   TINA4_LOG_LEVEL         — minimum console level (default: "DEBUG")
+ *
+ * Rotation is stdlib roll-your-own:
+ *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
+ *   - app.log.{N-1} → app.log.{N}, …, app.log → app.log.1 via fs.renameSync.
+ *   - Files beyond _KEEP are dropped via fs.unlinkSync.
+ *   - _SIZE=0 disables rotation entirely.
  */
 export class Log {
   private static requestId: string | undefined;
-  private static logDir: string = DEFAULT_LOG_DIR;
-  private static logFile: string = DEFAULT_LOG_FILE;
-  private static maxFileSize: number = 10 * 1024 * 1024;
-  private static keepFiles: number = 5;
-  private static minLevel: number = 0;
+
+  /**
+   * Re-read all log-related env vars. Called on every log() so tests that
+   * mutate process.env between calls see the new values without having to
+   * call configure() each time.
+   */
+  private static readEnv(): {
+    logDir: string;
+    logFile: string;
+    rotateSize: number;
+    rotateKeep: number;
+    minLevel: number;
+    format: "text" | "json";
+    output: "stdout" | "file" | "both";
+    criticalEnabled: boolean;
+  } {
+    const logDir = process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
+    const logFile = (process.env.TINA4_LOG_FILE ?? "").trim() || DEFAULT_LOG_FILE;
+
+    const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
+    let rotateSize = DEFAULT_ROTATE_SIZE;
+    if (rawSize !== undefined) {
+      const n = parseInt(rawSize, 10);
+      rotateSize = isNaN(n) || n < 0 ? DEFAULT_ROTATE_SIZE : n;
+    }
+
+    const rawKeep = process.env.TINA4_LOG_ROTATE_KEEP;
+    let rotateKeep = DEFAULT_ROTATE_KEEP;
+    if (rawKeep !== undefined) {
+      const n = parseInt(rawKeep, 10);
+      rotateKeep = isNaN(n) || n < 1 ? DEFAULT_ROTATE_KEEP : n;
+    }
+
+    const levelEnv = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
+    const minLevel = LEVEL_PRIORITY[levelEnv as LogLevel] ?? 0;
+
+    const fmt = (process.env.TINA4_LOG_FORMAT ?? "text").trim().toLowerCase();
+    const format: "text" | "json" = fmt === "json" ? "json" : "text";
+
+    const out = (process.env.TINA4_LOG_OUTPUT ?? "stdout").trim().toLowerCase();
+    let output: "stdout" | "file" | "both" = "stdout";
+    if (out === "file") output = "file";
+    else if (out === "both") output = "both";
+
+    const criticalEnabled = isTruthy(process.env.TINA4_LOG_CRITICAL);
+
+    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, criticalEnabled };
+  }
 
   /**
    * Set the current request ID for log correlation.
@@ -85,21 +163,12 @@ export class Log {
   }
 
   /**
-   * Configure the log directory, filename, and rotation settings.
+   * Configure the log directory / filename. Mostly a no-op now —
+   * env vars are re-read on every call. Kept for backwards compatibility.
    */
   static configure(options: { logDir?: string; logFile?: string }): void {
-    if (options.logDir) Log.logDir = options.logDir;
-    if (options.logFile) Log.logFile = options.logFile;
-
-    // Read rotation config from env (with defaults)
-    const maxSizeMb = parseInt(process.env.TINA4_LOG_MAX_SIZE ?? "10", 10);
-    Log.maxFileSize = (isNaN(maxSizeMb) ? 10 : maxSizeMb) * 1024 * 1024;
-    const keep = parseInt(process.env.TINA4_LOG_KEEP ?? "5", 10);
-    Log.keepFiles = isNaN(keep) ? 5 : keep;
-
-    // Resolve minimum console log level
-    const levelEnv = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
-    Log.minLevel = LEVEL_PRIORITY[levelEnv as LogLevel] ?? 0;
+    if (options.logDir) process.env.TINA4_LOG_DIR = options.logDir;
+    if (options.logFile) process.env.TINA4_LOG_FILE = options.logFile;
   }
 
   /** Log an informational message. */
@@ -117,11 +186,25 @@ export class Log {
     Log.log("WARNING", message, data);
   }
 
+  /** Backwards-compat alias for warning(). */
+  static warn(message: string, data?: unknown): void {
+    Log.log("WARNING", message, data);
+  }
+
   /** Log an error message. */
   static error(message: string, data?: unknown): void {
     Log.log("ERROR", message, data);
   }
 
+  /**
+   * Log a critical message. Only emitted when TINA4_LOG_CRITICAL=true,
+   * otherwise this is a no-op (matches Python parity — critical is the
+   * highest-severity bucket and is opt-in to avoid drowning noisy apps).
+   */
+  static critical(message: string, data?: unknown): void {
+    Log.log("CRITICAL", message, data);
+  }
+
   /** Check if running in production mode (TINA4_DEBUG is not truthy). */
   private static isProduction(): boolean {
     return !isTruthy(process.env.TINA4_DEBUG);
@@ -132,43 +215,59 @@ export class Log {
     return new Date().toISOString();
   }
 
-  /** Get the full path to the current log file */
-  private static logFilePath(): string {
-    return join(Log.logDir, Log.logFile);
-  }
-
   /** Ensure the log directory exists */
-  private static ensureLogDir(): void {
-    const dir = dirname(Log.logFilePath());
+  private static ensureLogDir(filePath: string): void {
+    const dir = dirname(filePath);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
     }
   }
 
   /**
-   * Rotate using numbered scheme: tina4.log.{keep} is deleted, all others shift up by 1.
+   * Roll-your-own rotation, stdlib only.
+   *
+   * Sequence on each write:
+   *   1. statSync the current file. If size < rotateSize, return.
+   *   2. Drop any file beyond keep via unlinkSync (cap the historical count).
+   *   3. Atomic shift: app.log.{N-1} → app.log.{N}, …, app.log.1 → app.log.2.
+   *   4. Rename current app.log → app.log.1.
+   *   5. Truncate via writeFileSync(path, "") so subsequent appends start fresh.
+   *
+   * Sync calls per write are fine — the worst case is contention on a single
+   * file, and the OS atomically serialises rename/unlink anyway.
+   *
+   * `rotateSize` of 0 disables rotation entirely.
    */
-  private static rotateIfNeeded(): void {
-    const filePath = Log.logFilePath();
+  private static rotateIfNeeded(filePath: string, rotateSize: number, rotateKeep: number): void {
+    if (rotateSize <= 0) return;
     if (!existsSync(filePath)) return;
 
+    let size = 0;
     try {
-      const stats = statSync(filePath);
-      if (stats.size < Log.maxFileSize) return;
+      size = statSync(filePath).size;
     } catch {
       return;
     }
+    if (size < rotateSize) return;
+
+    // Drop files beyond keep
+    for (let n = rotateKeep + 1; n <= rotateKeep + 10; n++) {
+      const stale = `${filePath}.${n}`;
+      if (existsSync(stale)) {
+        try { unlinkSync(stale); } catch { /* ignore */ }
+      } else {
+        break;
+      }
+    }
 
-    const keep = Log.keepFiles;
-
-    // Delete the oldest rotated file if it exists
-    const oldest = `${filePath}.${keep}`;
+    // Drop the oldest in-window file if at capacity
+    const oldest = `${filePath}.${rotateKeep}`;
     if (existsSync(oldest)) {
       try { unlinkSync(oldest); } catch { /* ignore */ }
     }
 
-    // Shift existing rotated files: .{n} -> .{n+1}
-    for (let n = keep - 1; n >= 1; n--) {
+    // Shift: .{N-1} -> .{N}, ..., .1 -> .2
+    for (let n = rotateKeep - 1; n >= 1; n--) {
       const src = `${filePath}.${n}`;
       const dst = `${filePath}.${n + 1}`;
       if (existsSync(src)) {
@@ -176,16 +275,17 @@ export class Log {
       }
     }
 
-    // Rename current log to .1
+    // Move current → .1, then truncate
     try { renameSync(filePath, `${filePath}.1`); } catch { /* ignore */ }
+    try { writeFileSync(filePath, "", "utf-8"); } catch { /* ignore */ }
   }
 
-  /** Write a line to the log file, stripping ANSI codes */
-  private static writeToFile(line: string): void {
+  /** Write a line to the log file, stripping ANSI codes. */
+  private static writeToFile(filePath: string, line: string, rotateSize: number, rotateKeep: number): void {
     try {
-      Log.ensureLogDir();
-      Log.rotateIfNeeded();
-      appendFileSync(Log.logFilePath(), stripAnsi(line) + "\n", "utf-8");
+      Log.ensureLogDir(filePath);
+      Log.rotateIfNeeded(filePath, rotateSize, rotateKeep);
+      appendFileSync(filePath, stripAnsi(line) + "\n", "utf-8");
     } catch {
       // Silently fail — logging should never crash the app
     }
@@ -193,6 +293,11 @@ export class Log {
 
   /** Core log method */
   private static log(level: LogLevel, message: string, data?: unknown): void {
+    const cfg = Log.readEnv();
+
+    // Critical level is opt-in; treat as no-op when disabled.
+    if (level === "CRITICAL" && !cfg.criticalEnabled) return;
+
     const entry: LogEntry = {
       timestamp: Log.timestamp(),
       level,
@@ -207,20 +312,35 @@ export class Log {
       entry.context = data;
     }
 
-    // Build human-readable line for file/console
-    const paddedLevel = level.padEnd(7);
+    // Build human-readable line
+    const paddedLevel = level.padEnd(8);
     const reqPart = Log.requestId ? ` [${Log.requestId}]` : "";
     const dataPart = data !== undefined ? ` ${JSON.stringify(data)}` : "";
     const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart} ${message}${dataPart}`;
 
-    // Console output respects TINA4_LOG_LEVEL
-    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= Log.minLevel;
-    if (!Log.isProduction() && shouldLog) {
+    // Build the file-format line based on TINA4_LOG_FORMAT
+    const fileLine = cfg.format === "json" ? JSON.stringify(entry) : humanLine;
+
+    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= cfg.minLevel;
+
+    // Console output. TINA4_LOG_OUTPUT="file" disables stdout entirely;
+    // anything else (stdout, both) prints to console in dev, suppresses in prod.
+    if (shouldLog && cfg.output !== "file" && !Log.isProduction()) {
       const color = COLORS[level];
       console.log(`${color}${humanLine}${RESET}`);
     }
 
-    // File always gets ALL levels (raw log, no filtering), plain text (no ANSI)
-    Log.writeToFile(humanLine);
+    // File output: always teed for dev (legacy behaviour), and either always
+    // (production default) or honoured per output mode.
+    //
+    //   output=stdout (default): file in dev + prod (legacy parity)
+    //   output=file              file only — no console
+    //   output=both              file + console (already handled above)
+    //
+    // The "stdout-only without file" mode that some Python deployments want
+    // is gated on TINA4_LOG_OUTPUT=stdout combined with TINA4_LOG_FILE set
+    // explicitly to an empty string in env — we treat empty file as default.
+    const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
+    Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
   }
 }

package/packages/core/src/mcp.ts

@@ -162,6 +162,44 @@ export function isLocalhost(): boolean {
   return ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].includes(host);
 }
 
+// ── MCP env config (Python parity) ───────────────────────────
+
+/** Truthy check that mirrors `dotenv.isTruthy` without the import cycle. */
+function envTruthy(val: string | undefined): boolean {
+  if (val == null) return false;
+  return ["true", "1", "yes", "on"].includes(val.trim().toLowerCase());
+}
+
+/**
+ * Whether the built-in MCP server should auto-start.
+ *
+ * Default: `true` when `TINA4_DEBUG=true`, `false` otherwise. The `TINA4_MCP`
+ * env var can force either state explicitly. Matches the Python framework
+ * which only exposes MCP endpoints in dev mode by default.
+ */
+export function mcpEnabled(): boolean {
+  const raw = process.env.TINA4_MCP;
+  if (raw === undefined || raw.trim() === "") {
+    return envTruthy(process.env.TINA4_DEBUG);
+  }
+  return envTruthy(raw);
+}
+
+/**
+ * Resolve the MCP HTTP port. Default: HTTP server port + 2000.
+ *
+ * `TINA4_MCP_PORT` overrides directly. The `mainPort` argument is the
+ * primary HTTP port (the framework passes `port` from `resolvePortAndHost`).
+ */
+export function mcpPort(mainPort: number = 7148): number {
+  const raw = process.env.TINA4_MCP_PORT;
+  if (raw && raw.trim() !== "") {
+    const n = parseInt(raw, 10);
+    if (!isNaN(n) && n > 0) return n;
+  }
+  return mainPort + 2000;
+}
+
 // ── McpServer class ──────────────────────────────────────────
 
 export class McpServer {

package/packages/core/src/messenger.ts

@@ -67,6 +67,8 @@ interface MessengerOptions {
   imapPort?: number;
   imapUser?: string;
   imapPass?: string;
+  /** IMAP transport security: "tls" (default), "starttls", or "none". */
+  imapEncryption?: string;
 }
 
 export interface ImapMessage {
@@ -300,6 +302,7 @@ export class Messenger {
   private imapPort: number;
   private imapUser: string;
   private imapPass: string;
+  private imapEncryption: string;
 
   constructor(options?: MessengerOptions) {
     // Priority: constructor > TINA4_MAIL_* > sensible default.
@@ -345,6 +348,22 @@ export class Messenger {
     this.imapPass = options?.imapPass
       ?? process.env.TINA4_MAIL_IMAP_PASSWORD
       ?? this.password;
+
+    // IMAP encryption — separate from SMTP encryption because IMAP almost
+    // always uses port 993 + implicit TLS while SMTP toggles between 587
+    // (STARTTLS) and 465 (implicit TLS). Default is "tls" to match
+    // industry-standard IMAPS port 993 behaviour.
+    this.imapEncryption = (options?.imapEncryption
+      ?? process.env.TINA4_MAIL_IMAP_ENCRYPTION
+      ?? "tls").toLowerCase();
+  }
+
+  /**
+   * Read-only IMAP encryption mode for inspection / tests.
+   * Returns one of "tls", "starttls", "none", "ssl".
+   */
+  getImapEncryption(): string {
+    return this.imapEncryption;
   }
 
   /**
@@ -570,7 +589,12 @@ export class Messenger {
 
     let socket: net.Socket | tls.TLSSocket;
 
-    if (this.imapPort === 993) {
+    // Honour TINA4_MAIL_IMAP_ENCRYPTION when set; otherwise infer from port.
+    // "tls" / "ssl" → implicit TLS connect; anything else → plain connect.
+    const useTls = this.imapEncryption === "tls" || this.imapEncryption === "ssl"
+      || (this.imapEncryption === "" && this.imapPort === 993);
+
+    if (useTls) {
       socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: false });
       await new Promise<void>((resolve, reject) => {
         socket.once("secureConnect", resolve);

package/packages/core/src/router.ts

@@ -1,4 +1,16 @@
 import type { RouteHandler, RouteDefinition, RouteMeta, Middleware, Tina4Request, Tina4Response, WebSocketRouteHandler, WebSocketRouteDefinition } from "./types.js";
+import { isTruthy } from "./dotenv.js";
+
+/**
+ * Whether `TINA4_TRAILING_SLASH_REDIRECT` is enabled.
+ *
+ * Default: false. When true, a request to `/foo/` that has no exact match
+ * but matches `/foo` will be treated as a hit on `/foo` — callers can use
+ * the returned pattern to issue a 308 redirect (Python parity).
+ */
+export function isTrailingSlashRedirectEnabled(): boolean {
+  return isTruthy(process.env.TINA4_TRAILING_SLASH_REDIRECT);
+}
 
 interface MatchResult {
   handler: RouteHandler;
@@ -199,6 +211,11 @@ export class Router {
 
   /**
    * Match a request method + pathname to a registered route.
+   *
+   * When `TINA4_TRAILING_SLASH_REDIRECT=true` and the request path ends in
+   * a trailing slash that doesn't match a registered route, retry without
+   * the trailing slash. Returning the de-slashed pattern lets callers issue
+   * a 308 redirect instead of a hard 404 — Python parity.
    */
   match(method: string, path: string): MatchResult | null {
     const upperMethod = method.toUpperCase();
@@ -207,6 +224,28 @@ export class Router {
     const routes = this.routes.get(upperMethod);
     if (!routes) return null;
 
+    const direct = this.matchRoute(routes, path);
+    if (direct) return direct;
+
+    // Trailing-slash redirect — strip a single trailing "/" and retry.
+    // Root "/" is intentionally excluded (it's its own route).
+    if (
+      isTrailingSlashRedirectEnabled() &&
+      path.length > 1 &&
+      path.endsWith("/")
+    ) {
+      const stripped = path.replace(/\/+$/, "");
+      if (stripped.length > 0) {
+        const retry = this.matchRoute(routes, stripped);
+        if (retry) return retry;
+      }
+    }
+
+    return null;
+  }
+
+  /** Inner match against a list of compiled routes, no trailing-slash logic. */
+  private matchRoute(routes: CompiledRoute[], path: string): MatchResult | null {
     for (const route of routes) {
       const match = route.regex.exec(path);
       if (match) {
@@ -227,7 +266,6 @@ export class Router {
         };
       }
     }
-
     return null;
   }
 

package/packages/core/src/server.ts

@@ -15,7 +15,7 @@ import { createResponse, setDefaultTemplatesDir } from "./response.js";
 import { MiddlewareChain, cors, requestLogger } from "./middleware.js";
 import { tryServeStatic } from "./static.js";
 import { loadEnv, isTruthy } from "./dotenv.js";
-import { createHealthRoute } from "./health.js";
+import { createHealthRoutes } from "./health.js";
 import { rateLimiter } from "./rateLimiter.js";
 import { Log } from "./logger.js";
 import { DevAdmin, RequestInspector } from "./devAdmin.js";
@@ -114,7 +114,7 @@ export function _checkLegacyEnvVars(): void {
   }
   lines.push(
     "",
-    "Run `tina4 env-migrate` to rewrite your .env automatically,",
+    "Run `tina4 env --migrate` to rewrite your .env automatically,",
     "or rename manually. See https://tina4.com/release/3.12.0",
     "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
     bar,
@@ -198,17 +198,32 @@ function openBrowser(url: string) {
 /**
  * Resolve port and host with priority: explicit config > ENV var > default.
  * Exported for testability.
+ *
+ * Host resolution prefers `TINA4_HOST` (the framework-prefixed name —
+ * matches Python parity) and falls back to the unprefixed `HOST` env var
+ * for backwards compatibility.
  */
 export function resolvePortAndHost(config?: { port?: number; host?: string }): { port: number; host: string } {
   const port = config?.port
     ?? (process.env.PORT ? parseInt(process.env.PORT, 10) : undefined)
     ?? 7148;
   const host = config?.host
+    ?? process.env.TINA4_HOST
     ?? process.env.HOST
     ?? "0.0.0.0";
   return { port, host };
 }
 
+/**
+ * Whether the boot banner should be suppressed. Set TINA4_SUPPRESS=true to
+ * silence the ASCII-art banner and route table on startup — useful in CI,
+ * test runners, and embedded contexts where stdout is consumed by another
+ * process.
+ */
+export function isBannerSuppressed(): boolean {
+  return isTruthy(process.env.TINA4_SUPPRESS);
+}
+
 function isDevMode(): boolean {
   return isTruthy(process.env.TINA4_DEBUG);
 }
@@ -677,7 +692,8 @@ export async function startServer(config?: Tina4Config): Promise<{
       const reset = isTty ? "\x1b[0m" : "";
       const logLevel = (process.env.TINA4_LOG_LEVEL ?? "DEBUG").toUpperCase();
 
-      console.log(`${color}
+      if (!isBannerSuppressed()) {
+        console.log(`${color}
   ______ _             __ __
  /_  __/(_)___  ____ _/ // /
   / /  / / __ \\/ __ \`/ // /_
@@ -691,6 +707,7 @@ ${reset}
   Dashboard: http://localhost:${port}/__dev
   Debug:     OFF (Log level: ${logLevel})
 `);
+      }
 
       for (let i = 0; i < numCPUs; i++) {
         cluster.fork();
@@ -737,9 +754,11 @@ ${reset}
     router.addRoute(route);
   }
 
-  // Register health check endpoint
-  const healthRoute = createHealthRoute(TINA4_VERSION);
-  router.addRoute(healthRoute);
+  // Register health check endpoint(s). createHealthRoutes returns both the
+  // env-configured path (default /__health) and a /health legacy alias.
+  for (const healthRoute of createHealthRoutes(TINA4_VERSION)) {
+    router.addRoute(healthRoute);
+  }
 
   // Initialize Frond template engine
   let frondEngine: any = null;
@@ -837,9 +856,16 @@ ${reset}
     }
   }
 
-  // Initialize Swagger
+  // Initialize Swagger — gated on TINA4_SWAGGER_ENABLED (default: enabled
+  // in debug mode, off in production). Loading the swagger module also
+  // pulls in route discovery for the generator, so skip the import entirely
+  // when disabled.
   try {
     const swagger = await import("../../swagger/src/index.js");
+    if (!swagger.swaggerEnabled()) {
+      // Skip the rest of the swagger block when disabled.
+      throw new Error("__swagger_disabled__");
+    }
     const allRoutes = router.getRoutes();
 
     // Collect model definitions for schema generation
@@ -889,9 +915,12 @@ ${reset}
 
     // Auto-start session — read cookie, create session, save + set cookie on response end
     {
-      const { Session } = await import("./session.js");
+      const { Session, buildSessionCookie } = await import("./session.js");
       const cookieHeader = rawReq.headers.cookie ?? "";
-      const sidMatch = cookieHeader.match(/tina4_session=([^;]+)/);
+      const cookieName = process.env.TINA4_SESSION_NAME ?? "tina4_session";
+      // Build a regex from the (possibly customised) cookie name. Escape regex meta-chars.
+      const escapedName = cookieName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const sidMatch = cookieHeader.match(new RegExp(`${escapedName}=([^;]+)`));
       const existingSid = sidMatch ? sidMatch[1] : undefined;
       const sess = new Session();
       sess.start(existingSid);
@@ -909,8 +938,7 @@ ${reset}
         const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
         if (newSid && newSid !== existingSid && !rawRes.headersSent) {
           const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-          const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
-          rawRes.setHeader("Set-Cookie", `tina4_session=${newSid}; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=${ttl}`);
+          rawRes.setHeader("Set-Cookie", buildSessionCookie(newSid, ttl));
         }
         return origEnd(...args);
       } as typeof rawRes.end;
@@ -1234,7 +1262,8 @@ ${reset}
         ? `\n  Test Port: http://localhost:${testPort} (stable — no hot-reload)`
         : "";
 
-      console.log(`${color}
+      if (!isBannerSuppressed()) {
+        console.log(`${color}
   ______ _             __ __
  /_  __/(_)___  ____ _/ // /
   / /  / / __ \\/ __ \`/ // /_
@@ -1248,6 +1277,7 @@ ${reset}
   Dashboard: http://localhost:${port}/__dev
   Debug:     ${isDebug ? "ON" : "OFF"} (Log level: ${logLevel})${dualPortLines}
 `);
+      }
       const noBrowser = isTruthy(process.env.TINA4_NO_BROWSER);
       if (!noBrowser) {
         // Open browser on test port (hot-reload) if available, otherwise main port

package/packages/core/src/session.ts

@@ -531,10 +531,15 @@ export class Session {
 
   /**
    * Return a Set-Cookie header value for this session.
+   *
+   * Honours these env vars (cross-framework parity):
+   *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+   *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+   *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+   *   TINA4_SESSION_SECURE    — emit Secure (default: false)
    */
-  cookieHeader(cookieName: string = "tina4_session"): string {
-    const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
-    return `${cookieName}=${this.sessionId}; Path=/; HttpOnly; SameSite=${sameSite}; Max-Age=${this.ttl}`;
+  cookieHeader(cookieName?: string): string {
+    return buildSessionCookie(this.sessionId, this.ttl, cookieName);
   }
 
   /**
@@ -555,3 +560,38 @@ export class Session {
     this.handler.write(this.sessionId, this.data, this.ttl);
   }
 }
+
+/**
+ * Build the `Set-Cookie` header value for a Tina4 session. Centralised so
+ * the auto-cookie path in server.ts and `Session.cookieHeader()` agree on
+ * which env vars are honoured and what the defaults are.
+ *
+ * Env vars (Python parity):
+ *   TINA4_SESSION_NAME      — cookie name (default: "tina4_session")
+ *   TINA4_SESSION_SAMESITE  — SameSite attribute (default: "Lax")
+ *   TINA4_SESSION_HTTPONLY  — emit HttpOnly (default: true)
+ *   TINA4_SESSION_SECURE    — emit Secure (default: false)
+ */
+export function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string): string {
+  const name = cookieName ?? process.env.TINA4_SESSION_NAME ?? "tina4_session";
+  const sameSite = process.env.TINA4_SESSION_SAMESITE ?? "Lax";
+
+  // HttpOnly defaults to TRUE (matches existing behaviour and Python parity).
+  // Treat any explicit non-truthy value (false/0/no/off) as opt-out.
+  const httpOnlyRaw = process.env.TINA4_SESSION_HTTPONLY;
+  const httpOnly = httpOnlyRaw === undefined
+    ? true
+    : !["false", "0", "no", "off"].includes(httpOnlyRaw.trim().toLowerCase());
+
+  // Secure defaults to FALSE — only emit when the operator opts in (https
+  // deployments). Setting it eagerly would break http://localhost dev cookies.
+  const secureRaw = process.env.TINA4_SESSION_SECURE ?? "";
+  const secure = ["true", "1", "yes", "on"].includes(secureRaw.trim().toLowerCase());
+
+  const parts = [`${name}=${sessionId ?? ""}`, "Path=/"];
+  if (httpOnly) parts.push("HttpOnly");
+  parts.push(`SameSite=${sameSite}`);
+  if (secure) parts.push("Secure");
+  parts.push(`Max-Age=${ttl}`);
+  return parts.join("; ");
+}

package/packages/frond/src/engine.ts

@@ -1327,10 +1327,16 @@ export class Frond {
   private _allowedVars: Set<string> | null;
   private fragmentCache: Map<string, [string, number]>;
   private _autoEscape: boolean;
-  /** Token pre-compilation cache for file templates */
-  private compiled = new Map<string, { tokens: Token[]; mtime: number }>();
+  /**
+   * Token pre-compilation cache for file templates.
+   *
+   * `cachedAt` is captured so the TINA4_TEMPLATE_CACHE_TTL env var can
+   * force re-compilation after N seconds even in production. TTL of 0
+   * means "no time-based invalidation" — entries live forever.
+   */
+  private compiled = new Map<string, { tokens: Token[]; mtime: number; cachedAt: number }>();
   /** Token pre-compilation cache for string templates */
-  private compiledStrings = new Map<string, Token[]>();
+  private compiledStrings = new Map<string, { tokens: Token[]; cachedAt: number }>();
 
   getTemplateDir(): string { return this.templateDir; }
 
@@ -1386,6 +1392,20 @@ export class Frond {
     this.tests[name] = fn;
   }
 
+  /**
+   * Read the cache TTL in seconds. `TINA4_TEMPLATE_CACHE_TTL=0` (the
+   * default) keeps the existing "cache forever in prod" behaviour — any
+   * positive value invalidates compiled tokens after N seconds, useful
+   * when running long-lived servers behind a slow file sync where mtime
+   * isn't a reliable freshness signal.
+   */
+  private cacheTtlSeconds(): number {
+    const raw = process.env.TINA4_TEMPLATE_CACHE_TTL;
+    if (raw === undefined) return 0;
+    const n = parseInt(raw, 10);
+    return isNaN(n) || n < 0 ? 0 : n;
+  }
+
   render(template: string, data?: Record<string, unknown>): string {
     const context = { ...this.globals, ...(data || {}) };
     const filePath = join(this.templateDir, template);
@@ -1395,12 +1415,17 @@ export class Frond {
     }
 
     const debugMode = (process.env.TINA4_DEBUG || "").toLowerCase() === "true";
+    const ttlMs = this.cacheTtlSeconds() * 1000;
 
     if (!debugMode) {
       // Production: use permanent cache (no filesystem checks)
       const cached = this.compiled.get(template);
       if (cached) {
-        return this.executeCached(cached.tokens, context);
+        // TTL=0 means cache forever; any positive value invalidates the
+        // compiled tokens after N seconds.
+        if (ttlMs === 0 || (Date.now() - cached.cachedAt) < ttlMs) {
+          return this.executeCached(cached.tokens, context);
+        }
       }
     }
     // Dev mode: skip cache entirely — always re-read and re-tokenize
@@ -1410,7 +1435,7 @@ export class Frond {
     const source = readFileSync(filePath, "utf-8");
     const mtime = statSync(filePath).mtimeMs;
     const tokens = tokenize(source);
-    this.compiled.set(template, { tokens, mtime });
+    this.compiled.set(template, { tokens, mtime, cachedAt: Date.now() });
     return this.executeWithSource(source, tokens, context);
   }
 
@@ -1418,13 +1443,16 @@ export class Frond {
     const context = { ...this.globals, ...(data || {}) };
 
     const key = createHash("md5").update(source).digest("hex");
-    const cachedTokens = this.compiledStrings.get(key);
-    if (cachedTokens) {
-      return this.executeCached(cachedTokens, context);
+    const ttlMs = this.cacheTtlSeconds() * 1000;
+    const cached = this.compiledStrings.get(key);
+    if (cached) {
+      if (ttlMs === 0 || (Date.now() - cached.cachedAt) < ttlMs) {
+        return this.executeCached(cached.tokens, context);
+      }
     }
 
     const tokens = tokenize(source);
-    this.compiledStrings.set(key, tokens);
+    this.compiledStrings.set(key, { tokens, cachedAt: Date.now() });
     return this.executeCached(tokens, context);
   }
 

package/packages/orm/src/database.ts

@@ -830,6 +830,21 @@ async function createAdapterFromUrl(url: string, username?: string, password?: s
  *   2. process.env.TINA4_DATABASE_URL
  *   3. config.type + config.path (legacy)
  */
+/**
+ * Resolve the connection-pool size from `TINA4_DB_POOL`.
+ *
+ * Default: 0 (single-connection mode). Any positive integer enables
+ * round-robin pooling with that many connections — Database.create() honours
+ * this transparently. The env var is the simple deploy-time override; tests
+ * and library users can still pass `pool` directly to Database.create().
+ */
+export function resolveDbPool(): number {
+  const raw = process.env.TINA4_DB_POOL;
+  if (raw === undefined || raw.trim() === "") return 0;
+  const n = parseInt(raw, 10);
+  return isNaN(n) || n < 0 ? 0 : n;
+}
+
 export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   // Resolve credentials: config.user > config.username > env TINA4_DATABASE_USERNAME
   const resolvedUser = config?.user ?? config?.username ?? process.env.TINA4_DATABASE_USERNAME;
@@ -839,6 +854,12 @@ export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
   const url = config?.url ?? process.env.TINA4_DATABASE_URL;
 
   if (url) {
+    const pool = resolveDbPool();
+    if (pool > 0) {
+      // Pool-aware path — delegate to Database.create which manages
+      // round-robin adapter rotation and async-local-storage transaction pinning.
+      return Database.create(url, resolvedUser, resolvedPassword, pool);
+    }
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);
     setAdapter(adapter);
     return new Database(adapter);

package/packages/orm/src/index.ts

@@ -14,7 +14,7 @@ export { FetchResult } from "./types.js";
 
 export { DatabaseResult } from "./databaseResult.js";
 export type { ColumnInfoResult } from "./databaseResult.js";
-export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter } from "./database.js";
+export { Database, initDatabase, getAdapter, setAdapter, closeDatabase, parseDatabaseUrl, setNamedAdapter, getNamedAdapter, resolveDbPool } from "./database.js";
 export type { DatabaseConfig, ParsedDatabaseUrl } from "./database.js";
 export { discoverModels } from "./model.js";
 export type { DiscoveredModel } from "./model.js";

package/packages/swagger/src/generator.ts

@@ -1,9 +1,17 @@
 import type { RouteDefinition } from "@tina4/core";
 import type { ModelDefinition, FieldDefinition } from "@tina4/orm";
 
+interface OpenAPISpecInfo {
+  title: string;
+  version: string;
+  description?: string;
+  contact?: { name?: string; url?: string; email?: string };
+  license?: { name: string; url?: string };
+}
+
 interface OpenAPISpec {
   openapi: string;
-  info: { title: string; version: string; description?: string };
+  info: OpenAPISpecInfo;
   paths: Record<string, Record<string, unknown>>;
   components?: { schemas?: Record<string, unknown> };
 }
@@ -12,13 +20,30 @@ export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
 ): OpenAPISpec {
+  const info: OpenAPISpecInfo = {
+    title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
+    version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
+    description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
+  };
+
+  // Optional contact email — surfaced in the OpenAPI `info.contact.email`
+  // field when set. Matches the python `SWAGGER_CONTACT_EMAIL` convention.
+  const contactEmail = (process.env.TINA4_SWAGGER_CONTACT_EMAIL ?? "").trim();
+  if (contactEmail.length > 0) {
+    info.contact = { email: contactEmail };
+  }
+
+  // Optional license — accepts a plain SPDX identifier ("MIT", "Apache-2.0")
+  // or a "Name|URL" pair. Empty string disables license output entirely.
+  const licenseRaw = (process.env.TINA4_SWAGGER_LICENSE ?? "").trim();
+  if (licenseRaw.length > 0) {
+    const [name, url] = licenseRaw.split("|").map((s) => s.trim());
+    info.license = url ? { name, url } : { name };
+  }
+
   const spec: OpenAPISpec = {
     openapi: "3.0.3",
-    info: {
-      title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
-      version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
-      description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
-    },
+    info,
     paths: {},
     components: { schemas: {} },
   };

package/packages/swagger/src/index.ts

@@ -1,2 +1,2 @@
 export { generate } from "./generator.js";
-export { createSwaggerRoutes } from "./ui.js";
+export { createSwaggerRoutes, swaggerEnabled } from "./ui.js";

package/packages/swagger/src/ui.ts

@@ -26,6 +26,23 @@ const SWAGGER_UI_HTML = (specUrl: string) => `<!DOCTYPE html>
 </body>
 </html>`;
 
+/**
+ * Whether the Swagger UI + spec routes should be registered at boot.
+ *
+ * Default: enabled when `TINA4_DEBUG=true`, disabled otherwise. Operators
+ * can force either state with `TINA4_SWAGGER_ENABLED=true|false`. Matches
+ * Python parity: dev-only by default to keep production attack surface
+ * minimal, but easy to expose intentionally for public APIs.
+ */
+export function swaggerEnabled(): boolean {
+  const raw = (process.env.TINA4_SWAGGER_ENABLED ?? "").trim().toLowerCase();
+  if (raw === "") {
+    const debug = (process.env.TINA4_DEBUG ?? "").trim().toLowerCase();
+    return ["true", "1", "yes", "on"].includes(debug);
+  }
+  return ["true", "1", "yes", "on"].includes(raw);
+}
+
 export function createSwaggerRoutes(
   getSpec: () => Record<string, unknown>
 ): RouteDefinition[] {