tina4-nodejs 3.13.38 → 3.13.39

package/CLAUDE.md

@@ -120,11 +120,11 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `auth.ts` — Authentication helpers
 - `cache.ts` — In-memory caching
 - `session.ts` — Session management with pluggable handlers. `TINA4_SESSION_SAMESITE` env var (default: Lax)
-- `websocket.ts` — WebSocket support with backplane for scaling via Redis/NATS pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`). The backplane is wired for real: `broadcast`/`broadcastToRoom`/`sendTo` deliver to LOCAL connections first (resiliently — a dead/slow client is pruned, never aborting the loop) then publish an envelope `{src,kind,exclude,room,path,text|b64}` to the shared channel `tina4:ws` (identical wire shape across all 4 frameworks). The subscribe callback relays directly on the event loop with an origin guard (drop our own `src` echo — no double-delivery) and never re-publishes (no cluster loop); binary messages ride as base64. Security/ops knobs (all opt-in, non-breaking): `TINA4_WS_ALLOWED_ORIGINS` (comma-separated origin allow-list enforced on upgrade — empty/unset = allow all), `TINA4_WS_IDLE_TIMEOUT` (seconds; 0/unset disables the idle-connection reaper), `TINA4_WS_MAX_BACKLOG` (bytes; a slow client whose socket write backlog exceeds this is dropped rather than buffered without bound). Rooms API: `wss.joinRoom(clientId, room)`, `wss.leaveRoom(clientId, room)`, `wss.broadcastToRoom(room, msg, excludeIds?)`, `wss.getRoomConnections(room)`, `wss.roomCount(room)`, `wss.getClientRooms(clientId)`. `originAllowed(headers)` is exported for upgrade-path checks.
+- `websocket.ts` — WebSocket support with backplane for scaling via Redis/NATS pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`). The backplane is wired for real: `broadcast`/`broadcastToRoom`/`sendTo` deliver to LOCAL connections first (resiliently — a dead/slow client is pruned, never aborting the loop) then publish an envelope `{src,kind,exclude,room,path,text|b64}` to the shared channel `tina4:ws` (identical wire shape across all 4 frameworks). The subscribe callback relays directly on the event loop with an origin guard (drop our own `src` echo — no double-delivery) and never re-publishes (no cluster loop); binary messages ride as base64. Security/ops knobs (all opt-in, non-breaking): `TINA4_WS_ALLOWED_ORIGINS` (comma-separated origin allow-list enforced on upgrade — empty/unset = allow all), `TINA4_WS_IDLE_TIMEOUT` (seconds; 0/unset disables the idle-connection reaper), `TINA4_WS_MAX_BACKLOG` (bytes; a slow client whose socket write backlog exceeds this is dropped rather than buffered without bound). Rooms API: `wss.joinRoom(clientId, room)`, `wss.leaveRoom(clientId, room)`, `wss.broadcastToRoom(room, msg, excludeIds?)`, `wss.getRoomConnections(room)`, `wss.roomCount(room)`, `wss.getClientRooms(clientId)`. `originAllowed(headers)` is exported for upgrade-path checks. **Per-route auth (v3.13.39, Python master b5976d4):** a WS route is PUBLIC by default (mirrors GET). Mark it secured imperatively — `Router.websocket(path, fn, { secured: true })` / chain `.secure()` on the returned `WsRouteRef` / `WebSocketServer.route(path, fn, { secured: true })` — OR decorator-style via a `_secured` flag on the handler (works in either declaration order). A secured route enforces a valid JWT on the upgrade, AFTER the origin allow-list and BEFORE accept: missing/invalid → reject with HTTP 401 (never accept); public routes always pass (non-breaking). Three token transports (`wsToken(headers, query, subprotocol)`): (1) `Authorization: Bearer <jwt>` header (server/CLI/mobile); (2) the `Sec-WebSocket-Protocol` subprotocol `"bearer, <jwt>"` (browsers — `new WebSocket()` can't set headers; the server echoes `bearer` back as the accepted subprotocol); (3) `?token=<jwt>` query param. Validated via the same `validToken` (Auth) the HTTP routes use. The verified payload is exposed as `connection.auth` (`null` on public routes). `wsAuthorized(route, headers, query, subprotocol) -> [payload, ok]` is the gate. **The integrated server (`server.ts`) now dispatches user WS routes:** its `upgrade` handler routes a non-`/__dev_reload` upgrade through `serveWebSocketRoute(req, socket, head)`, which matches the WS route table, enforces per-route auth, then drives the real open/message/close lifecycle on the connection (`wsRouteManager`) — parity with Python/PHP/Ruby (previously only `/__dev_reload` was wired, so user WS routes never reached a live connection).
 - `queue.ts` — Queue system with pluggable backends
 - `graphql.ts` — GraphQL engine. **Hardening:** selection-set nesting is bounded by `TINA4_GRAPHQL_MAX_DEPTH` (default `50`; `<= 0` disables; exposed as the public `gql.maxDepth` field + `graphqlMaxDepth()` helper). Depth increments on every recursive entry — sub-selections, fragment spreads, AND inline fragments — so an over-deep query or a circular fragment fails with `Query exceeds maximum depth of N` instead of overflowing the stack (top-level starts at depth 1). A resolver exception is logged via `Log.error` and the detail is surfaced to the client **only** under `TINA4_DEBUG` (`isDebugMode()`); otherwise it returns a generic `Internal server error` (path preserved) so internal state never leaks.
 - `i18n.ts` — Internationalization / localization
-- `logger.ts` — Structured logging
+- `logger.ts` — Structured logging. Five first-class severity levels: `debug`(0) < `info`(1) < `warning`(2) < `error`(3) < `critical`(4). `critical` is the HIGHEST level, NOT a relabelled `error`, and renders magenta. `Log.critical()` ALWAYS emits like every other level — subject only to `TINA4_LOG_LEVEL` (which it always clears) and teed to the log file whenever a file is being written. There is NO enable toggle: the old `TINA4_LOG_CRITICAL` opt-in was retired in v3.13.39 (the env var is no longer read), so a critical log is never a silent no-op. `Log.isEnabled("critical")` is ordinary threshold logic (`4 >= configured min`). **Dev/prod-aware default file output (v3.13.39, Python master 4c6d881):** stdout is ALWAYS on. When `TINA4_LOG_OUTPUT` is unset (default), the log FILE (`logs/tina4.log`) is written ONLY in development (`TINA4_DEBUG` truthy); in production / containers (`TINA4_DEBUG` falsy) the logger is stdout-only — no file to bloat the writable layer / disk (12-factor: logs on stdout for the platform to capture). Explicit `TINA4_LOG_OUTPUT=file`/`both`, OR an explicit `TINA4_LOG_FILE` path, always forces a file (explicit wins). `readEnv()` resolves all of this into a single `fileEnabled` flag that gates the file writer. Full parity with Python master.
 - `rateLimiter.ts` — Rate limiting middleware
 - `dotenv.ts` — `.env` file loading
 - `health.ts` — Health check endpoint
@@ -775,6 +775,8 @@ const adults = User.query().where("age > ?", [18]).orderBy("name").get();
 
 SQL-file based migrations under `migrations/`. The framework runs pending migrations on startup; the helpers here are for programmatic control (CLI, scripts, tests).
 
+**Auto-run on startup (`TINA4_AUTO_MIGRATE`, default on).** `startServer()` calls `autoMigrateOnStartup()` (in `server.ts`) AFTER `initDatabase()`/model sync and BEFORE the server listens. When a `migrations/` folder with at least one `.sql` file exists, `TINA4_AUTO_MIGRATE` is not falsy (default `"true"`; `false`/`0`/`no`/`off` disable), and a DB adapter is resolvable, it runs the existing `migrate()` runner so the schema is current with no manual `tina4 migrate` step. It is **non-breaking**: a failure is logged via `Log.error` and the service still starts (a bad migration must never take the backend down). The runner is wrapped in try/catch and `autoMigrateOnStartup()` never rejects/throws out of the boot path. Set `TINA4_AUTO_MIGRATE=false` to disable (e.g. multi-instance production that migrates as a separate deploy step — concurrent first-apply can race). The explicit `tina4 migrate` CLI (`packages/cli/src/commands/migrate.ts`) is unaffected and stays **fail-fast** (`process.exit(1)` on a statement error) so CI keeps the non-zero exit code.
+
 ```typescript
 import {
   migrate, rollback, status, createMigration, syncModels,
@@ -788,7 +790,16 @@ await createMigration("add users table");   // scaffolds migrations/<ts>_add_use
 syncModels(discoveredModels);               // auto-create tables / add columns from `static fields`
 ```
 
-Migration tracking lives in `tina4_migration` (id, name, batch, applied_at). Schema sync runs alongside SQL migrations on boot.
+### How migrations work internally
+
+- SQL files live in `migrations/`, named `NNNNNN_description.sql` (sequential) or `YYYYMMDDHHMMSS_description.sql` (timestamp), and are split on the `;` delimiter.
+- Files are applied in **numeric-prefix order** (`9_` before `10_` — a plain lexical sort misorders unpadded prefixes because `"10" < "9"`). A file with no numeric/timestamp prefix sorts **after** the numbered ones (lexically) and logs a `Log.warning` — its order is undefined.
+- State is tracked by **row existence** in `tina4_migration` (id, name, batch, applied_at), auto-created per engine: a migration runs once — if a row with its `name` exists it is skipped. A FAILED migration is **never** recorded (no row is written, nothing is deleted) — fix the bad file and re-run; the `migrate()` summary's `failed[]` carries the failure.
+- **Each migration FILE is wrapped in its own transaction.** On a failure the file rolls back and `migrate()` **STOPS** — later files are never applied on top of a missing earlier one (parity with Python/PHP/Ruby). Already-applied files stay applied. The explicit `tina4 migrate` CLI surfaces a non-empty `failed[]` as a non-zero exit; startup auto-migration logs it and the service still boots (see `TINA4_AUTO_MIGRATE` above).
+- **Atomicity caveat:** per-file transactions are truly atomic only on engines with **transactional DDL (PostgreSQL)**. MySQL, Firebird, and SQLite auto-commit DDL, so a multi-statement migration that fails midway on those engines leaves earlier statements applied — keep one logical change per file. `CREATE TABLE` and `ALTER TABLE ... ADD` are made idempotent on Firebird/MSSQL (existence-checked via `RDB$RELATION_FIELDS` / `tableExists`) so a re-run with a raw `CREATE`/`ADD` does not error "object already exists"; SQLite/MySQL/PostgreSQL support `IF NOT EXISTS` and are left to the engine. Only a genuine already-exists is skipped — every other error still raises.
+- The stored-proc block delimiters (`$$ … $$` / `// … //`) are extracted before splitting, but a `//` preceded by a colon is **not** treated as a delimiter, so a URL (`https://…`) or any `://` literal inside a migration is never swallowed as an opaque block.
+
+Schema sync (`syncModels`) runs alongside SQL migrations on boot.
 
 ## Module: Frond (`packages/frond/src/engine.ts`)
 
@@ -821,6 +832,8 @@ frond.unsandbox();
 
 Zero-dep HTTP client over `node:http` / `node:https`. Used by integrations, queue producers, health checks, and tests.
 
+**Retry/backoff (opt-in, default off):** pass `maxRetries` (default `0`) and `retryBackoff` (default `0.5`s base, exponential) in the options bag — `new Api(url, { bearerToken, maxRetries: 3, retryBackoff: 0.5 })`. Retries a transport error (`http_code` null) or a retryable status (429/500/502/503/504); 4xx is never retried (a retried non-idempotent request may be re-sent, so retries are opt-in). Node's `node:http`/`node:https` doesn't auto-follow redirects, so there's no cross-host Authorization-leak surface (the redirect auth-strip is Python-only).
+
 ```typescript
 import { Api } from "@tina4/core";
 

package/README.md

@@ -17,7 +17,7 @@
 ## Quick Start
 
 ```bash
-# With the Tina4 CLI (recommended — enables SCSS + live reload)
+# With the Tina4 CLI (recommended, enables SCSS + live reload)
 cargo install tina4    # or grab a binary from https://github.com/tina4stack/tina4/releases
 tina4 init nodejs ./my-app
 cd my-app && tina4 serve
@@ -57,12 +57,12 @@ export default class User {
 | Category | Features |
 |----------|----------|
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
-| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird — unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
+| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
 | **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
-| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters — service runner — event system (on/emit/once/off) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -86,14 +86,14 @@ npx tina4nodejs generate model <name>
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
 | Raw `node:http` | 91,110 | 0 | 1 |
 | **Tina4 Node.js** | **84,771** | 0 | 55 |
 
-Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in features — zero overhead architecture.
+Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in features, a zero-overhead architecture.
 
 **Across all 4 Tina4 implementations:**
 
@@ -107,7 +107,7 @@ Tina4 Node.js runs at **93% of raw Node.js speed** while providing 55 built-in f
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.38",
+  "version": "3.13.39",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/api.ts

@@ -18,6 +18,13 @@ export interface ApiResult {
     error: string | null;
 }
 
+/**
+ * HTTP statuses that warrant an automatic retry when `maxRetries` > 0:
+ * rate-limit (429) plus the transient server-side 5xx family. 4xx client
+ * errors (401, 404, …) are NOT retried — a repeat won't succeed.
+ */
+const RETRY_STATUSES: ReadonlySet<number> = new Set([429, 500, 502, 503, 504]);
+
 /**
  * Constructor options for {@link Api}. Used as the second argument to
  * `new Api(url, { ... })` — cross-framework parity with Python
@@ -33,6 +40,16 @@ export interface ApiOptions {
     username?: string;
     password?: string;
     headers?: Record<string, string>;
+    /**
+     * Maximum automatic retries on a transient failure (default 0 = off, so
+     * existing callers are unaffected). When > 0, a transport error or a
+     * retryable status (429/5xx) is retried up to this many times with
+     * exponential backoff. NOTE: a retried non-idempotent request (POST/…)
+     * may be re-sent — retries are opt-in for that reason.
+     */
+    maxRetries?: number;
+    /** Base backoff in seconds, doubling each attempt (default 0.5). */
+    retryBackoff?: number;
 }
 
 export class Api {
@@ -41,6 +58,8 @@ export class Api {
     private timeout: number;
     private authHeader: string;
     private ignoreSsl: boolean;
+    private maxRetries: number;
+    private retryBackoff: number;
 
     /**
      * Construct an Api client.
@@ -60,6 +79,14 @@ export class Api {
      * Bearer wins over basic-auth when both passed. `verifySsl: false` is
      * the positive form of `ignoreSsl: true`; `ignoreSsl` wins when both
      * supplied for backward compatibility.
+     *
+     * `maxRetries` (default 0 = off) enables automatic retry with
+     * exponential backoff (`retryBackoff` seconds base, doubling each
+     * attempt) on a transport error or a retryable status (429/5xx). A
+     * retried non-idempotent request (POST/…) may be re-sent — retries are
+     * opt-in for that reason.
+     *
+     *     new Api("https://api.example.com", { maxRetries: 3, retryBackoff: 0.5 });
      */
     constructor(
         baseUrl: string = "",
@@ -68,6 +95,9 @@ export class Api {
     ) {
         this.baseUrl = baseUrl.replace(/\/+$/, "");
         this.headers = {};
+        // Retry defaults: off (0) so existing callers are unaffected.
+        this.maxRetries = 0;
+        this.retryBackoff = 0.5;
 
         // Options-bag form — second arg is an object literal
         if (typeof authHeaderOrOptions === "object" && authHeaderOrOptions !== null) {
@@ -75,6 +105,8 @@ export class Api {
             this.authHeader = opts.authHeader ?? "";
             this.timeout = opts.timeout ?? timeout;
             this.ignoreSsl = (opts.ignoreSsl ?? false) || (opts.verifySsl === false);
+            this.maxRetries = Math.max(0, opts.maxRetries ?? 0);
+            this.retryBackoff = opts.retryBackoff ?? 0.5;
 
             // Bearer wins over basic-auth when both are passed
             if (opts.bearerToken != null) {
@@ -189,7 +221,38 @@ export class Api {
         return `${this.baseUrl}/${path.replace(/^\/+/, "")}`;
     }
 
-    private execute(
+    /**
+     * Execute the request with opt-in retry/backoff.
+     *
+     * With `maxRetries` > 0, a transport failure (`http_code` null) or a
+     * retryable status (429/5xx) is retried up to `maxRetries` times with
+     * exponential backoff; any other outcome (2xx, 3xx, other 4xx) returns
+     * at once. A retried non-idempotent request may be re-sent — retries
+     * are opt-in for that reason.
+     */
+    private async execute(
+        method: string,
+        url: string,
+        body?: unknown,
+        contentType: string = "application/json",
+    ): Promise<ApiResult> {
+        const attempts = this.maxRetries + 1;
+        let result: ApiResult = { http_code: null, body: null, headers: {}, error: null };
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            result = await this.attempt(method, url, body, contentType);
+            const code = result.http_code;
+            const retryable = code === null || RETRY_STATUSES.has(code);
+            if (!retryable || attempt === attempts - 1) {
+                return result;
+            }
+            const delayMs = this.retryBackoff * Math.pow(2, attempt) * 1000;
+            await new Promise<void>((r) => setTimeout(r, delayMs));
+        }
+        return result;
+    }
+
+    /** A single HTTP attempt — returns the standardized result. */
+    private attempt(
         method: string,
         url: string,
         body?: unknown,

package/packages/core/src/devAdmin.ts

@@ -19,7 +19,7 @@ import { DevMailbox } from "./devMailbox.js";
 import { isTruthy } from "./dotenv.js";
 import { quickMetrics, fullAnalysis, fileDetail } from "./metrics.js";
 import { registerFeedbackRoutes } from "./feedback.js";
-import { getDefaultDevServer } from "./mcp.js";
+import { getDefaultDevServer, mcpEnabled } from "./mcp.js";
 
 const cpuCount = osCpus().length;
 
@@ -561,18 +561,6 @@ export class DevAdmin {
       { method: "POST", pattern: "/__dev/api/deps/install", handler: handleDepsInstall },
       // Git status
       { method: "GET", pattern: "/__dev/api/git/status", handler: handleGitStatus },
-      // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
-      { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
-      { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
-      // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
-      // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
-      // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mounted
-      // through the same dispatch as the REST shim above and gated by the same
-      // /__dev public-route rule. Mirrors the Python v3 fix (POST /__dev/mcp +
-      // /__dev/mcp/message, GET /__dev/mcp/sse).
-      { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
-      { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
-      { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
       // Scaffolding
       { method: "GET", pattern: "/__dev/api/scaffold", handler: handleScaffoldList },
       { method: "POST", pattern: "/__dev/api/scaffold/run", handler: handleScaffoldRun },
@@ -610,12 +598,41 @@ export class DevAdmin {
       });
     }
 
-    // Ensure the default /__dev/mcp MCP server exists with its dev tools
-    // registered. This is the single shared instance behind both the REST shim
-    // and the JSON-RPC + SSE endpoints registered above. Doing it here (gated by
-    // the same TINA4_DEBUG check that gates DevAdmin.register) means tools/list
-    // and the REST shim return tools immediately, before any first call.
-    getDefaultDevServer();
+    // MCP exposure is gated SEPARATELY from the rest of the dev dashboard.
+    // The MCP dev tools expose powerful operations (DB query, file read/WRITE,
+    // route listing), so they must NOT auto-expose on a non-localhost
+    // TINA4_DEBUG=true deployment. mcpEnabled() honours an explicit TINA4_MCP on
+    // any host, else requires TINA4_DEBUG AND (localhost OR TINA4_MCP_REMOTE) —
+    // full parity with Python master tina4_python.mcp.is_enabled(). When the
+    // gate is closed, neither the REST shim, the JSON-RPC/SSE endpoints, nor the
+    // default dev MCP server (with its dev tools) are registered.
+    if (mcpEnabled()) {
+      const mcpRoutes: Array<{ method: string; pattern: string; handler: RouteHandler }> = [
+        // MCP tool introspection over the built-in MCP server (browser dev-admin REST shim)
+        { method: "GET", pattern: "/__dev/api/mcp/tools", handler: handleMcpTools },
+        { method: "POST", pattern: "/__dev/api/mcp/call", handler: handleMcpCall },
+        // MCP JSON-RPC + SSE endpoints that REAL MCP clients (Claude Code/Desktop)
+        // speak. POST /__dev/mcp[/message] -> JSON-RPC handleMessage; GET
+        // /__dev/mcp/sse -> SSE handshake announcing the message endpoint. Mirrors
+        // the Python v3 fix (POST /__dev/mcp + /__dev/mcp/message, GET /__dev/mcp/sse).
+        { method: "POST", pattern: "/__dev/mcp", handler: handleMcpMessage },
+        { method: "POST", pattern: "/__dev/mcp/message", handler: handleMcpMessage },
+        { method: "GET", pattern: "/__dev/mcp/sse", handler: handleMcpSse },
+      ];
+      for (const route of mcpRoutes) {
+        router.addRoute({
+          method: route.method,
+          pattern: route.pattern,
+          handler: route.handler,
+        });
+      }
+
+      // Ensure the default /__dev/mcp MCP server exists with its dev tools
+      // registered. This is the single shared instance behind both the REST shim
+      // and the JSON-RPC + SSE endpoints registered above, so tools/list and the
+      // REST shim return tools immediately, before any first call.
+      getDefaultDevServer();
+    }
   }
 
   /**

package/packages/core/src/index.ts

@@ -15,7 +15,7 @@ export type {
 
 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, resolveStringMiddleware, isTrailingSlashRedirectEnabled } from "./router.js";
+export { Router, RouteGroup, RouteRef, WsRouteRef, defaultRouter, runRouteMiddlewares, resolveStringMiddleware, 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";
@@ -64,6 +64,7 @@ export {
   WebSocketServer,
   devReloadWs,
   computeAcceptKey, parseUpgradeHeaders, buildFrame, parseFrame, originAllowed,
+  wsToken, wsAuthorized, offeredBearerSubprotocol, serveWebSocketRoute, wsRouteManager,
   OP_TEXT, OP_BINARY, OP_CLOSE, OP_PING, OP_PONG,
   CLOSE_NORMAL, CLOSE_GOING_AWAY, CLOSE_PROTOCOL_ERROR, CLOSE_POLICY_VIOLATION,
 } from "./websocket.js";
@@ -100,8 +101,12 @@ export type { ImapMessage, ImapFullMessage } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";
 export type { RabbitMQConfig } from "./queueBackends/rabbitmqBackend.js";
-export { KafkaBackend } from "./queueBackends/kafkaBackend.js";
-export type { KafkaConfig } from "./queueBackends/kafkaBackend.js";
+export { KafkaBackend, kafkaSecurityConfig } from "./queueBackends/kafkaBackend.js";
+export type {
+  KafkaConfig,
+  KafkaSecurityConfig,
+  KafkaClientConfig,
+} from "./queueBackends/kafkaBackend.js";
 export { MongoBackend } from "./queueBackends/mongoBackend.js";
 export type { MongoConfig as MongoQueueConfig } from "./queueBackends/mongoBackend.js";
 export { DatabaseSessionHandler } from "./sessionHandlers/databaseHandler.js";

package/packages/core/src/logger.ts

@@ -136,18 +136,23 @@ function resolveLogFilePath(logDir: string, logFile: string): string {
 /**
  * Structured logger for Tina4.
  *
- * Production (TINA4_DEBUG not truthy): JSON or text lines to logs/tina4.log
- * Development (TINA4_DEBUG=true): Colorized human-readable to stdout + file
+ * Development (TINA4_DEBUG=true): colorized human-readable to stdout + file.
+ * Production (TINA4_DEBUG not truthy): clean structured JSON to stdout ONLY —
+ *   no log file by default (writing logs/tina4.log inside a container bloats the
+ *   writable layer + disk; 12-factor wants logs on stdout). stdout is ALWAYS on.
+ *
+ * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
+ * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
+ * TINA4_LOG_FILE path, always forces a file (explicit wins).
  *
  * Env vars:
- *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Empty = use TINA4_LOG_DIR + tina4.log
+ *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. 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_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
  *   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")
+ *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
  *
  * Rotation is stdlib roll-your-own:
  *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
@@ -171,10 +176,11 @@ export class Log {
     minLevel: number;
     format: "text" | "json";
     output: "stdout" | "file" | "both";
-    criticalEnabled: boolean;
+    fileEnabled: boolean;
   } {
     const logDir = process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
-    const logFile = (process.env.TINA4_LOG_FILE ?? "").trim() || DEFAULT_LOG_FILE;
+    const explicitFile = (process.env.TINA4_LOG_FILE ?? "").trim();
+    const logFile = explicitFile || DEFAULT_LOG_FILE;
 
     const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
     let rotateSize = DEFAULT_ROTATE_SIZE;
@@ -203,9 +209,57 @@ export class Log {
     if (out === "file") output = "file";
     else if (out === "both") output = "both";
 
-    const criticalEnabled = isTruthy(process.env.TINA4_LOG_CRITICAL);
+    // v3.13.39: dev/prod-aware default file output (Python master, 4c6d881).
+    // When TINA4_LOG_OUTPUT is unset (default "stdout"), the log FILE is written
+    // only in development (TINA4_DEBUG truthy). In production / containers the
+    // logger is stdout-only — writing logs/tina4.log inside a container just
+    // bloats the writable layer + disk, and 12-factor wants logs on stdout for
+    // the platform to capture. Explicit TINA4_LOG_OUTPUT=file/both OR an explicit
+    // TINA4_LOG_FILE path always wins (explicit forces a file regardless of env).
+    let fileEnabled: boolean;
+    if (output === "file" || output === "both") {
+      fileEnabled = true;
+    } else if (explicitFile !== "") {
+      fileEnabled = true;
+    } else {
+      fileEnabled = !Log.isProduction();
+    }
+
+    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled };
+  }
+
+  /**
+   * The single console-threshold predicate: does a message at `level` clear
+   * the configured minimum console level? This is the ONE place level
+   * comparison lives — both the live log() gate and the public isEnabled()
+   * predicate call it, so they can never disagree about what actually prints.
+   */
+  private static passesThreshold(level: LogLevel, minLevel: number): boolean {
+    return (LEVEL_PRIORITY[level] ?? 0) >= minLevel;
+  }
 
-    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, criticalEnabled };
+  /**
+   * Return true if a message at `level` would pass the configured minimum
+   * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
+   *
+   * This reflects CONSOLE (stdout) visibility only. The log file always
+   * records every level regardless of this threshold, so don't use it to
+   * decide whether something gets persisted — use it to skip building an
+   * expensive payload that would not be shown:
+   *
+   *     if (Log.isEnabled("debug")) {
+   *       Log.debug("state", expensiveSnapshot());
+   *     }
+   *
+   * `level` is case-insensitive. "critical" is the highest severity (priority
+   * 4 > error 3) and flows through the ordinary threshold check like every
+   * other level — there is no toggle. It reuses the same passesThreshold()
+   * check the logger itself uses, so it never drifts from what print does.
+   */
+  static isEnabled(level: string): boolean {
+    const cfg = Log.readEnv();
+    const lvl = (level ?? "").toUpperCase() as LogLevel;
+    return Log.passesThreshold(lvl, cfg.minLevel);
   }
 
   /**
@@ -257,9 +311,12 @@ export class Log {
   }
 
   /**
-   * 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).
+   * Log a critical message. CRITICAL is the highest severity (priority 4 >
+   * error 3) and ALWAYS emits like every other level — subject only to the
+   * console threshold, which it always passes at normal levels — and is always
+   * persisted to the log file (Node tees every level to a single tina4.log;
+   * critical 4 >= warning 2 so it would be in error.log on a split-file model).
+   * Matches Python master parity — there is no enable toggle.
    */
   static critical(message: string, data?: unknown): void {
     Log.log("CRITICAL", message, data);
@@ -355,9 +412,6 @@ export class Log {
   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,
@@ -393,7 +447,7 @@ export class Log {
     const fileLine =
       cfg.format === "json" || Log.isProduction() ? JSON.stringify(entry) : humanLine;
 
-    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= cfg.minLevel;
+    const shouldLog = Log.passesThreshold(level, cfg.minLevel);
 
     // Console output. v3.13.14: stdout is NOT suppressed in production —
     // containers read PID 1 stdout (docker logs / k8s) and the old
@@ -410,17 +464,20 @@ export class Log {
       }
     }
 
-    // File output: always teed for dev (legacy behaviour), and either always
-    // (production default) or honoured per output mode.
+    // File output (v3.13.39 — Python master, 4c6d881): gated on cfg.fileEnabled.
     //
-    //   output=stdout (default): file in dev + prod (legacy parity)
-    //   output=file              file only — no console
-    //   output=both              file + console (already handled above)
+    //   output=stdout (default): file ONLY in dev (TINA4_DEBUG truthy);
+    //                            production / containers are stdout-only — no
+    //                            file to bloat the writable layer / disk.
+    //   output=file              file only — no console (always writes a file)
+    //   output=both              file + console (always writes a file)
+    //   explicit TINA4_LOG_FILE  always writes a file (explicit wins)
     //
-    // 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);
+    // readEnv() resolves all of the above into cfg.fileEnabled, so flipping
+    // that one flag gates the whole file writer (the only persisted sink).
+    if (cfg.fileEnabled) {
+      const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
+      Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
+    }
   }
 }

package/packages/core/src/mcp.ts

@@ -202,18 +202,35 @@ function envTruthy(val: string | undefined): boolean {
 }
 
 /**
- * Whether the built-in MCP server should auto-start.
+ * Whether the built-in MCP dev tools / `/__dev/mcp` endpoint should be enabled.
  *
- * 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.
+ * Resolution order (highest priority first), matching Python master
+ * `tina4_python.mcp.is_enabled()`:
+ *   1. `TINA4_MCP` — explicit on/off override, honoured on ANY host. An
+ *      explicit truthy value opts a remote / debug-disabled deployment in
+ *      (e.g. for a remote AI assistant); an explicit falsy value force-disables
+ *      it everywhere.
+ *   2. `TINA4_DEBUG=true` — implicit on for dev, but LOCALHOST-ONLY unless
+ *      `TINA4_MCP_REMOTE=true`. The MCP dev tools expose powerful operations
+ *      (DB query, file read/WRITE, route listing), so they never auto-expose on
+ *      a non-localhost host without an explicit opt-in.
+ *   3. Otherwise off.
+ *
+ * Wired in v3.13.39: previously this was `TINA4_MCP` else `TINA4_DEBUG`, with
+ * `isLocalhost()` unused for the gate and `TINA4_MCP_REMOTE` read by zero code
+ * — so the documented localhost guard was not actually enforced and a
+ * non-localhost `TINA4_DEBUG=true` deployment auto-exposed the dev tools.
  */
 export function mcpEnabled(): boolean {
-  const raw = process.env.TINA4_MCP;
-  if (raw === undefined || raw.trim() === "") {
-    return envTruthy(process.env.TINA4_DEBUG);
+  const explicit = process.env.TINA4_MCP;
+  if (explicit !== undefined && explicit.trim() !== "") {
+    return envTruthy(explicit);
+  }
+  if (!envTruthy(process.env.TINA4_DEBUG)) {
+    return false;
   }
-  return envTruthy(raw);
+  // Dev auto-enable: localhost only, unless explicitly opted into remote.
+  return isLocalhost() || envTruthy(process.env.TINA4_MCP_REMOTE);
 }
 
 /**