tina4-nodejs 3.12.2 → 3.12.4

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