tina4-nodejs 3.13.36 → 3.13.38

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.36)
+# CLAUDE.md — AI Developer Guide for tina4-nodejs (v3.13.37)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -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,9 +120,9 @@ 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.
 - `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
 - `rateLimiter.ts` — Rate limiting middleware
@@ -131,7 +131,7 @@ The HTTP foundation. Handles request/response lifecycle, route matching, middlew
 - `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
@@ -1125,7 +1157,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 +1166,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/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.36",
+  "version": "3.13.38",
 
   "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}`);
   }