tina4-nodejs 3.13.37 → 3.13.39

package/CLAUDE.md

@@ -50,7 +50,7 @@ tina4-nodejs/
           firebird.ts      # Firebird adapter
         baseModel.ts     # Base model class
         fakeData.ts      # ORM-aware fake data (extends core, field-type heuristics)
-        seeder.ts        # Database seeding (seedTable, seedOrm)
+        seeder.ts        # Database seeding (seedTable, seedOrm, seedModels)
         sqlTranslation.ts # Cross-engine SQL translator + query cache
     swagger/    # OpenAPI spec generator, Swagger UI
     frond/      # Zero-dependency Twig-compatible template engine
@@ -120,18 +120,18 @@ 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 pub/sub (`TINA4_WS_BACKPLANE`, `TINA4_WS_BACKPLANE_URL`). Rooms API: `wss.joinRoom(clientId, room)`, `wss.leaveRoom(clientId, room)`, `wss.broadcastToRoom(room, msg, excludeIds?)`, `wss.getRoomConnections(room)`, `wss.roomCount(room)`, `wss.getClientRooms(clientId)`
+- `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
+- `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
 - `scss.ts` — SCSS compilation
 - `messenger.ts` — Messaging system
 - `service.ts` — Service layer helpers
-- `wsdl.ts` — WSDL / SOAP support
+- `wsdl.ts` — WSDL / SOAP support. **Hardening:** a SOAP message containing a `<!DOCTYPE>` is rejected with a `Client` fault ("DOCTYPE declarations are not allowed in SOAP messages") BEFORE the body is parsed and the operation never runs — SOAP 1.1 forbids DTDs and this closes the XML entity-expansion (billion-laughs) / external-entity (XXE) surface (defence in depth — the hand-rolled parser is already immune). `convertValue` for an `int`/`float`/`integer`/`double`/`number` param throws on a non-numeric value (matching Python's `int()`/`float()` raise) so it becomes a `Server` fault instead of a silent `NaN`. An operation that throws is logged via `Log.error`; the real cause reaches the client **only** under `TINA4_DEBUG` (`isDebugMode()`), else a generic `Internal server error`.
 
 ### @tina4/orm (`packages/orm/`)
 Database layer with auto-CRUD generation, seeding, fake data, and SQL translation.
@@ -150,7 +150,7 @@ Database layer with auto-CRUD generation, seeding, fake data, and SQL translatio
 - `validation.ts` — Validates request bodies against model field definitions
 - `types.ts` — `FieldDefinition`, `ModelDefinition`, `DatabaseAdapter`, `QueryOptions`
 - `fakeData.ts` — ORM-aware fake data extending core (adds `forField()` with column-name heuristics)
-- `seeder.ts` — Database seeding (`seedTable` for raw SQL, `seedOrm` for model-based)
+- `seeder.ts` — Database seeding (`seedTable` raw SQL, `seedOrm` model-based, `seedModels` FK-ordered batch). All return a `SeedSummary { seeded, failed, errors }`; per-row failures are logged + counted + skipped (`strict` re-raises). Options: `{ overrides, clear, seed, strict }`.
 - `sqlTranslation.ts` — Cross-engine SQL translator (`SQLTranslator`) and TTL query cache (`QueryCache`)
 - **Instance methods:** `save(): this|false` (fluent, false on failure), `delete()`, `forceDelete()`, `restore()`, `load(sql, params?, include?): boolean`, `validate(): string[]`, `toDict(include?)`, `toAssoc(include?)`, `toObject()`, `toArray(): unknown[]`, `toList()`, `toJson(include?)`, `hasOne(class, fk)`, `hasMany(class, fk, limit?, offset?)`, `belongsTo(class, fk)`
 - **Static methods:** `find(id, include?)`, `findById(id, include?)`, `findOrFail(id)`, `create(data)`, `all(where?, params?, include?)`, `select(sql, params?)`, `selectOne(sql, params?, include?)`, `where(conditions, params?, limit?, offset?, include?)`, `count(conditions?, params?)`, `withTrashed(conditions?, params?, limit?, offset?)`, `scope(name, filterSql, params?)` (registers reusable method), `createTable()`, `query()`, `_processForeignKeys()`, `_applyFkRegistry()`
@@ -223,10 +223,12 @@ session.gc(): void
 
 Backends: file, redis, redis-npm, valkey, mongodb, database.
 
+**Backend-failure policy (all 4 frameworks): log-loud + degrade.** A backend (Redis/Valkey/Mongo/DB) that becomes unreachable mid-request is logged via `Log.error` and degraded rather than crashing the app or losing data silently. The external handlers now **throw** a transport error on an unreachable server (previously they swallowed it to an empty string — silent data loss); the `Session` boundary catches it: a read failure yields an empty session (the request still serves), and `save()` returns `false` (best-effort, dirty flag retained for a later retry). A genuine key/doc miss still returns empty **without** logging — empty is not a failure. Set `TINA4_SESSION_STRICT=true` to re-throw instead. Call `regenerate()` right after a successful login or privilege change to defeat session fixation.
+
 ### Database extras
 
 ```typescript
-db.execute(sql, params?): boolean | unknown  // bool for writes, result for RETURNING/CALL/EXEC
+db.execute(sql, params?): boolean | unknown  // RAISES on SQL error (never returns false; cause on getError()); on success: bool for writes, result for RETURNING/CALL/EXEC. try/catch — don't test the return.
 db.getLastId(): string | number
 db.getError(): string | null
 db.cacheStats(): { enabled, size, ttl }
@@ -243,6 +245,8 @@ response.xml(content, status?): Tina4Response
 response.stream(source: AsyncIterable<string | Buffer>, contentType?: string): Promise<Tina4Response>  // SSE/streaming
 ```
 
+`response.stream()` is hardened: it bails cleanly when the client disconnects mid-stream (`res.writableEnded`/`res.socket.destroyed`), catches a generator/source error (logs via `Log.error`, ends the stream cleanly — never crashes the handler), applies slow-client backpressure (awaits `drain` when `res.write()` returns false rather than buffering ahead of a stalled client), and writes a periodic `:` keep-alive comment every `TINA4_SSE_HEARTBEAT` seconds (default 15; set `0` to opt out). On disconnect/error it best-effort closes the source (`.return()`/`.close()`/`.aclose()`).
+
 `res.json(model)`, `res.json(arrayOfModels)`, and `res.json(db.fetch(...))` auto-serialize to JSON — a single model becomes a JSON object, an array of models or a `DatabaseResult` becomes a JSON array. No manual `toDict()`/`toJson()` needed.
 
 ### Queue
@@ -423,7 +427,7 @@ reset();
 Database seeding with fake data generation. The ORM `FakeData` extends core `FakeData` (which provides names, emails, addresses, etc.) and adds `forField()` for auto-generating values based on ORM field definitions with column-name heuristics.
 
 ```typescript
-import { FakeData, seedTable, seedOrm } from "@tina4/orm";
+import { FakeData, seedTable, seedOrm, seedModels } from "@tina4/orm";
 
 // FakeData — deterministic with optional seed
 const fake = new FakeData(42);
@@ -445,18 +449,36 @@ fake.forField({ type: "string", maxLength: 50 }, "email");   // generates email
 fake.forField({ type: "integer", min: 0, max: 100 });        // random integer
 fake.forField({ type: "boolean" });                           // true/false
 
-// seedTable — raw SQL inserts with generator functions
-await seedTable(db, "users", 50, {
+// seedTable — raw SQL inserts with generator functions.
+// Returns a SeedSummary { seeded, failed, errors } (NOT a bare number).
+const summary = await seedTable(db, "users", 50, {
   name: () => fake.name(),
   email: () => fake.email(),
   role: "user",  // static values also accepted
-}, { active: true });  // overrides applied to every row
+}, undefined, { clear: true, seed: 42, strict: false });
+// summary.seeded / summary.failed / summary.errors[{ row, message }]
+// (legacy positional 5th arg overrides also still works: seedTable(..., { active: true }))
 
 // seedOrm — auto-seed from model field definitions
 import User from "./src/models/User.js";
-await seedOrm(User, 100, { role: "user" }, 42);  // optional seed for determinism
+await seedOrm(User, 100, { role: "user" }, 42);                  // legacy positional
+await seedOrm(User, 100, undefined, undefined, { clear: true, seed: 42, strict: true });
+
+// seedModels — batch-seed FK-related models in dependency order (parents first,
+// reverse-order clear, FK columns resolved to real parent PKs). Topo-sorts by the
+// `references` graph so the declared order doesn't matter.
+const results = await seedModels([Book, Author], 10, { clear: true, seed: 7 });
+// → { Author: SeedSummary, Book: SeedSummary }
 ```
 
+**Visible-but-resilient seeding (P1-P4).** Every row is wrapped: a failing row is
+logged (with its index + cause) and skipped, incrementing `summary.failed` — never
+silent, never a crash. `strict: true` re-raises on the first failure instead of
+skipping. `clear: true` truncates the target first (idempotent re-runs). `seed`
+makes a run reproducible. `seedModels()` orders by the foreignKey dependency graph.
+The dev-admin seed endpoint (`POST /__dev/api/seed`) routes through `seedTable`,
+accepts `seed`/`clear`/`strict`, and returns `{ seeded, failed, errors, table }`.
+
 Column-name heuristics in `forField()`: columns named `email`, `phone`, `name`, `address`, `city`, `country`, `company`, `url`, `uuid`, `ip`, `currency`, etc. get contextually appropriate fake data.
 
 ## Module: SQL Translation (`packages/orm/src/sqlTranslation.ts`)
@@ -564,7 +586,13 @@ const db = await initDatabase({ url: "sqlite:///app.db" });
 db.fetch(sql, params?, limit?, offset?): DatabaseResult           // .records, .count, .limit, .offset
 db.fetchOne<T>(sql, params?): T | null
 
-// Writes — return boolean for simple writes, result for RETURNING / CALL / EXEC / SELECT
+// Writes — execute() RAISES on a SQL error (bad SQL, constraint violation,
+// dead connection, missing driver): it records the cause on getError() then
+// re-throws — it never swallows and returns false (mirrors fetch()/fetchOne()).
+// On SUCCESS it returns boolean for simple writes, the result set for
+// RETURNING / CALL / EXEC / SELECT. Callers needing a bool (ORM save(),
+// createTable(), migration runner, dev-admin/MCP DB tools) try/catch and
+// convert — they must NOT test the return value for false.
 db.execute(sql, params?): boolean | unknown
 db.executeMany(sql, paramSets): unknown[]                         // wrapped in a transaction
 db.insert(table, data): DatabaseWriteResult
@@ -592,9 +620,13 @@ db.getColumns(table): { name, type, nullable?, default?, primaryKey? }[]
 // auto-creates Postgres sequences, and uses native Firebird generators.
 db.getNextId(table, pkColumn?, generatorName?): number
 
-// DB query cache — request-scoped auto cache is ON by default (TINA4_AUTO_CACHING=true,
-// TTL TINA4_AUTO_CACHING_TTL=5s): dedupes identical db.fetch()/ORM reads within a request,
-// flushed on any write (always in-process, fastest). Persistent cross-request cache opt-in
+// DB query cache — request-scoped auto cache is OFF by default (opt-in via
+// TINA4_AUTO_CACHING=true, TTL TINA4_AUTO_CACHING_TTL=5s): when enabled it dedupes
+// identical db.fetch()/ORM reads within a request, flushed on any write (always
+// in-process, fastest). Default OFF because a request-scoped cache defaulting ON is a
+// footgun — a read-after-write in one request (e.g. SELECT MAX(id) then INSERT) returns a
+// cached pre-write value (duplicate PKs / stale state); enable it for read-heavy endpoints.
+// Persistent cross-request cache opt-in
 // via TINA4_DB_CACHE=true (TTL TINA4_DB_CACHE_TTL=30s), configured via TINA4_DB_CACHE_BACKEND
 // + TINA4_DB_CACHE_URL. The persistent layer routes through the SAME unified async backend
 // set (memory default = in-process; redis/valkey/memcached/mongodb/database distribute), so
@@ -743,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,
@@ -756,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`)
 
@@ -789,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";
 
@@ -1125,7 +1170,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Frond template engine optimizations**: pre-compiled regexes, lazy loop context (copy-on-write), filter chain caching, path split caching, inline common filters (11-15% speedup)
 - **Production server auto-detect**: `npx tina4nodejs serve --production` auto-uses cluster mode
 - **`npx tina4nodejs generate`**: model, route, migration, middleware scaffolding
-- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **on by default** (`TINA4_AUTO_CACHING=true`, TTL `TINA4_AUTO_CACHING_TTL=5`s) dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes (always in-process); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
+- **Database**: 5 engines (SQLite, PostgreSQL, MySQL, MSSQL, Firebird), DB query caching — request-scoped auto cache **off by default — opt-in via `TINA4_AUTO_CACHING=true`** (TTL `TINA4_AUTO_CACHING_TTL=5`s) which dedupes identical `db.fetch()`/ORM reads within a request and flushes on writes (always in-process); default OFF because a request-scoped cache defaulting on is a read-after-write footgun (cached pre-write `SELECT MAX(id)` → duplicate PKs); persistent cross-request cache opt-in via `TINA4_DB_CACHE=true` (TTL `TINA4_DB_CACHE_TTL=30`s) routed through the unified async backend set via `TINA4_DB_CACHE_BACKEND` (memory/file/redis/valkey/memcached/mongodb/database) + `TINA4_DB_CACHE_URL`, so instances share one cache with global write-invalidation (full parity with Python/PHP/Ruby). `db.cacheStats()` reports `mode` (request/persistent/off) + `backend`
 - **Cache**: unified backend set — `memory` (default), `file`, `redis`, `valkey`, `memcached`, `mongodb`, `database` — via `TINA4_CACHE_BACKEND` (+ `TINA4_CACHE_URL`/credentials); file-backend fallback if a backend is unreachable. The KV API, the `responseCache` middleware, and the persistent DB query cache all route through this async backend set (native async clients, no child processes) — a network backend distributes them cross-instance, full parity with Python/PHP/Ruby; `memory` (default) keeps them in-process. `await` the async API (`cacheGet`/`cacheSet`/`clearCache`)
 - **Sessions**: file backend (default). `TINA4_SESSION_SAMESITE` env var (default: Lax)
 - **Queue**: file/RabbitMQ/Kafka/MongoDB backends, configured via env vars
@@ -1134,11 +1179,11 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **ORM relationships**: `hasMany`, `hasOne`, `belongsTo` with eager loading (`include`)
 - **Frond pre-compilation**: 2.8x template render improvement
 - **QueryBuilder** with NoSQL/MongoDB support (`toMongo()`)
-- **WebSocket backplane** (Redis pub/sub) for horizontal scaling
+- **WebSocket backplane** (Redis/NATS pub/sub) for horizontal scaling — wired for real: local-first resilient delivery, then publish a `{src,kind,exclude,room,path,text|b64}` envelope to the `tina4:ws` channel (cross-framework wire shape); subscribe relays directly with an origin guard (no own-echo) and never re-publishes. Origin allow-list (`TINA4_WS_ALLOWED_ORIGINS`), idle reaper (`TINA4_WS_IDLE_TIMEOUT`), and slow-client drop (`TINA4_WS_MAX_BACKLOG`) — all opt-in/non-breaking
 - **SameSite=Lax** default on session cookies (`TINA4_SESSION_SAMESITE`)
 - **`tina4 deploy docker`** generates Dockerfile and .dockerignore
 - **Gallery**: 7 interactive examples with Try It deploy at `/_dev/`
-- **SSE/Streaming**: `response.stream()` for Server-Sent Events — pass an async generator, framework handles chunked transfer encoding and keep-alive
+- **SSE/Streaming**: `response.stream()` for Server-Sent Events — pass an async generator; framework handles chunked transfer encoding plus a periodic keep-alive heartbeat (`TINA4_SSE_HEARTBEAT`, default 15s, `0` to disable). Hardened against client disconnect (bails when the socket is gone), a generator error mid-stream (logs + ends cleanly, never crashes the worker), and slow clients (awaits socket drain instead of unbounded buffering)
 
 ## Don'ts
 

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.37",
+  "version": "3.13.39",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",
@@ -57,7 +57,8 @@
   "scripts": {
     "build": "npm run build --workspaces",
     "clean": "rm -rf packages/*/dist",
-    "test": "tsx test/run-all.ts"
+    "test": "tsx test/run-all.ts",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -67,6 +68,7 @@
     "typescript": "^5.7.0",
     "tsx": "^4.19.0",
     "esbuild": "^0.24.0",
-    "mongodb": "^6.0.0"
+    "mongodb": "^6.0.0",
+    "@types/node": "^22.10.0"
   }
 }

package/packages/cli/src/bin.ts

@@ -8,6 +8,7 @@ import { listRoutes } from "./commands/routes.js";
 import { runTests } from "./commands/test.js";
 import { generate } from "./commands/generate.js";
 import { runSeeds } from "./commands/seed.js";
+import { runMetrics } from "./commands/metrics.js";
 import { execSync } from "node:child_process";
 
 const args = process.argv.slice(2);
@@ -26,6 +27,8 @@ const HELP = `
     tina4nodejs routes                List all registered routes
     tina4nodejs test [file]           Run project tests
     tina4nodejs seed [file]           Run database seed files from src/seeds/
+    tina4nodejs metrics [--top N] [--json] [--fail-on warn|error] [--path DIR]
+                                      Rank top code-quality offenders
     tina4nodejs console               Open an interactive REPL with the framework loaded
     tina4nodejs ai                    Install AI coding assistant context files
     tina4nodejs help                  Show this help message
@@ -131,6 +134,10 @@ async function main(): Promise<void> {
       await runSeeds(args[1]);
       break;
     }
+    case "metrics": {
+      const code = runMetrics(args.slice(1));
+      process.exit(code);
+    }
     case "console": {
       const repl = await import("node:repl");
       const { loadEnv, Router, Log } = await import("../../core/src/index.js");

package/packages/cli/src/commands/init.ts

@@ -109,6 +109,7 @@ dist/
 *.db
 *.sqlite
 .env
+.env.local
 .DS_Store
 data/
 `

package/packages/cli/src/commands/metrics.ts

@@ -0,0 +1,154 @@
+/**
+ * CLI command: metrics — Rank top code-quality offenders.
+ *
+ * Exposes the existing static analyzer (cyclomatic complexity, maintainability,
+ * large-file, too-many-functions, and the now-precise has_tests) on the CLI as
+ * a self-monitoring tool.
+ *
+ *   tina4nodejs metrics                          # human report, scans src/ (or framework)
+ *   tina4nodejs metrics --top 10                 # only the worst 10
+ *   tina4nodejs metrics --path packages/core/src # scan a specific directory
+ *   tina4nodejs metrics --json                   # machine-readable for CI (ONLY json printed)
+ *   tina4nodejs metrics --fail-on warn           # exit 1 if any warn/error offender
+ *   tina4nodejs metrics --fail-on error          # exit 1 only on error-severity
+ *
+ * Returns the intended process exit code (the caller exits). Splitting "compute
+ * exit code" from "exit the process" keeps the handler unit-testable.
+ */
+import { offenders } from "../../../core/src/metrics.js";
+
+type Flags = {
+  top: number;
+  json: boolean;
+  path: string;
+  failOn: "warn" | "error" | null;
+};
+
+/** Parse `--top N`, `--json`, `--fail-on warn|error`, `--path DIR` out of argv. */
+function parseFlags(args: string[]): Flags | { error: string } {
+  const flags: Flags = { top: 20, json: false, path: "src", failOn: null };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case "--json":
+        flags.json = true;
+        break;
+      case "--top": {
+        const v = args[++i];
+        if (v === undefined || !/^\d+$/.test(v)) {
+          return { error: `--top expects a number (got '${v ?? ""}')` };
+        }
+        flags.top = parseInt(v, 10);
+        break;
+      }
+      case "--path": {
+        const v = args[++i];
+        if (v === undefined) return { error: "--path expects a directory" };
+        flags.path = v;
+        break;
+      }
+      case "--fail-on": {
+        const v = args[++i];
+        if (v !== "warn" && v !== "error") {
+          return { error: `invalid --fail-on '${v ?? ""}' (use warn or error)` };
+        }
+        flags.failOn = v;
+        break;
+      }
+      default:
+        return { error: `unknown option '${a}'` };
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Run the metrics report. Returns the process exit code; does NOT call
+ * process.exit (the bin wrapper does). 0 = ok / below threshold, 1 = gated
+ * failure, 2 = bad arguments / analysis error.
+ */
+export function runMetrics(args: string[] = []): number {
+  const parsed = parseFlags(args);
+  if ("error" in parsed) {
+    console.log(`  ${parsed.error}`);
+    return 2;
+  }
+  const { top, json, path, failOn } = parsed;
+
+  const result = offenders(path, top);
+  const summary = result.summary;
+  const found = result.offenders;
+
+  if (summary.error) {
+    console.log(`  metrics error: ${summary.error}`);
+    return 2;
+  }
+
+  // Decide exit code from the FULL offender set, not just the printed top-N.
+  // offenders()/fullAnalysis() is mtime-cached, so this reuses the same analysis.
+  const allOffenders = offenders(path, summary.total_offenders || 1).offenders;
+  const severities = new Set(allOffenders.map((o) => o.severity));
+  let exitCode = 0;
+  if (failOn === "warn" && (severities.has("warn") || severities.has("error"))) {
+    exitCode = 1;
+  } else if (failOn === "error" && severities.has("error")) {
+    exitCode = 1;
+  }
+
+  if (json) {
+    // Print ONLY the JSON — machine-readable for CI / tooling.
+    console.log(JSON.stringify({ summary, offenders: found }, null, 2));
+    return exitCode;
+  }
+
+  // ── Human report ──────────────────────────────────────────────────
+  const useColor = Boolean(process.stdout.isTTY);
+  const c = (text: string, code: string): string =>
+    useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
+  const sevColor: Record<string, string> = { error: "31", warn: "33", info: "2" }; // red / yellow / dim
+
+  console.log("");
+  console.log(`  Tina4 Metrics — ${summary.scan_mode} scan (${summary.scan_root})`);
+  console.log(
+    `  files: ${summary.files_analyzed}   ` +
+      `functions: ${summary.total_functions}   ` +
+      `avg complexity: ${summary.avg_complexity}   ` +
+      `avg maintainability: ${summary.avg_maintainability}`
+  );
+  console.log(
+    `  offenders: ${summary.total_offenders} total` +
+      (found.length ? ` (showing top ${found.length})` : "")
+  );
+  console.log("");
+
+  if (found.length === 0) {
+    console.log("  " + c("✓ no offenders — clean", "32"));
+    console.log("");
+    return exitCode;
+  }
+
+  // Column widths so the table lines up.
+  const locs = found.map((o) => `${o.file}:${o.line}`);
+  const locW = Math.max("FILE:LINE".length, ...locs.map((s) => s.length));
+  const kindW = Math.max("KIND".length, ...found.map((o) => o.kind.length));
+
+  const pad = (s: string, w: number) => s.padEnd(w);
+  const header = `  ${pad("#", 3)}  ${pad("SEVERITY", 8)}  ${pad("KIND", kindW)}  ${pad(
+    "FILE:LINE",
+    locW
+  )}  DETAIL`;
+  console.log(c(header, "1"));
+  console.log("  " + "-".repeat(header.length - 2));
+  found.forEach((o, idx) => {
+    const i = idx + 1;
+    const sevCell = c(pad(o.severity, 8), sevColor[o.severity]);
+    console.log(
+      `  ${String(i).padStart(3)}  ${sevCell}  ${pad(o.kind, kindW)}  ` +
+        `${pad(locs[idx], locW)}  ${o.detail}`
+    );
+  });
+  console.log("");
+  return exitCode;
+}

package/packages/cli/src/commands/routes.ts

@@ -32,8 +32,8 @@ export async function listRoutes(): Promise<void> {
   }
 
   // Sort by path then method
-  routes.sort((a: { path: string; method: string }, b: { path: string; method: string }) => {
-    const pathCmp = a.path.localeCompare(b.path);
+  routes.sort((a, b) => {
+    const pathCmp = a.pattern.localeCompare(b.pattern);
     return pathCmp !== 0 ? pathCmp : a.method.localeCompare(b.method);
   });
 
@@ -50,7 +50,7 @@ export async function listRoutes(): Promise<void> {
 
   for (const route of routes) {
     const method = route.method.toUpperCase().padEnd(10);
-    const path = route.path.padEnd(40);
+    const path = route.pattern.padEnd(40);
     const summary = route.meta?.summary ?? "";
     console.log(`  ${method}${path}${summary}`);
   }

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,