tina4-nodejs 3.13.38 → 3.13.40

package/packages/orm/src/index.ts

@@ -39,6 +39,10 @@ export {
   createMigration,
   status,
   Migration,
+  splitStatements,
+  normalizeQuotes,
+  sortMigrationFiles,
+  shouldSkipCreateTable,
 } from "./migration.js";
 export type { MigrationResult, MigrationStatus } from "./migration.js";
 export { AutoCrud, generateCrudRoutes } from "./autoCrud.js";
@@ -54,6 +58,16 @@ export { FakeData } from "./fakeData.js";
 export { seedTable, seedOrm, seedModels } from "./seeder.js";
 export type { SeedSummary, SeedOptions } from "./seeder.js";
 
+// DocStore — pymongo-style document store with a zero-config SQLite (JSON1) fallback
+export {
+  ObjectId, InvalidId, SqliteDatabase, SqliteCollection, Cursor,
+  getCollection, isServerless, resetDefaultStore,
+  encodeValue, decodeValue, compileFilter,
+} from "./docstore.js";
+export type {
+  InsertOneResult, InsertManyResult, UpdateResult, DeleteResult,
+} from "./docstore.js";
+
 // Database adapters
 export { SQLiteAdapter } from "./adapters/sqlite.js";
 export { PostgresAdapter } from "./adapters/postgres.js";

package/packages/orm/src/migration.ts

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
+import { Log } from "@tina4/core";
 import type { FieldDefinition, DatabaseAdapter } from "./types.js";
 import type { SQLiteAdapter } from "./adapters/sqlite.js";
 import type { DiscoveredModel } from "./model.js";
@@ -76,6 +77,55 @@ async function shouldSkipForFirebird(
   return null;
 }
 
+/**
+ * Match CREATE TABLE <name> — name may be quoted ("x"), bracketed ([x] MSSQL),
+ * or bare. Captures the table name.
+ */
+const CREATE_TABLE_RE =
+  /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?(?:"([^"]+)"|\[([^\]]+)\]|(\w+))/i;
+
+/**
+ * Identify the database engine via the adapter's class name.
+ * (constructor.name is the engine discriminator used throughout this package.)
+ */
+function engineOf(db: DatabaseAdapter): "firebird" | "mssql" | "other" {
+  const name = db.constructor.name;
+  if (name === "FirebirdAdapter") return "firebird";
+  if (name === "MssqlAdapter") return "mssql";
+  return "other";
+}
+
+/**
+ * Make CREATE TABLE idempotent on engines lacking IF NOT EXISTS.
+ *
+ * Firebird and MSSQL do not support `CREATE TABLE IF NOT EXISTS`, so a raw
+ * CREATE in a re-run migration raises "object already exists". When the target
+ * table already exists on those engines, return a skip reason so the statement
+ * is skipped (mirrors the Firebird ALTER-TABLE-ADD idempotency guard).
+ * 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.
+ */
+export async function shouldSkipCreateTable(
+  db: DatabaseAdapter,
+  stmt: string,
+): Promise<string | null> {
+  const engine = engineOf(db);
+  if (engine !== "firebird" && engine !== "mssql") return null;
+
+  const m = stmt.match(CREATE_TABLE_RE);
+  if (!m) return null;
+
+  const table = m[1] ?? m[2] ?? m[3];
+  try {
+    if (await adapterTableExists(db, table)) {
+      return `Table ${table} already exists, skipping CREATE TABLE`;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
 /**
  * Sync model definitions to the database (create tables, add columns).
  */
@@ -411,13 +461,44 @@ export interface MigrationStatus {
   pending: string[];
 }
 
+/**
+ * Smart/curly quotes — editors, word processors, docs and chat apps silently
+ * convert a straight " to “ ” and a straight ' to ‘ ’ (plus primes ′ ″). Those
+ * characters are NOT valid SQL string/identifier delimiters, so a pasted-in
+ * migration fails to run ("syntax error near …"). Map them back to straight
+ * ASCII quotes. (Real string CONTENTS are unaffected by intent — we only swap
+ * the lookalike code points for their ASCII equivalents.)
+ */
+const SMART_QUOTES: Record<string, string> = {
+  // Double-quote lookalikes → straight " (U+0022)
+  "“": '"', "”": '"', "„": '"', "‟": '"', "″": '"',
+  // Single-quote / apostrophe lookalikes → straight ' (U+0027)
+  "‘": "'", "’": "'", "‚": "'", "‛": "'", "′": "'",
+};
+const SMART_QUOTE_RE = new RegExp(`[${Object.keys(SMART_QUOTES).join("")}]`, "g");
+
+/**
+ * Replace smart/curly quotes with straight ASCII quotes so migration SQL
+ * authored or pasted from an editor/doc actually runs (those code points are
+ * not valid SQL delimiters). Already-straight quotes and ordinary string
+ * content are returned byte-for-byte unchanged.
+ */
+export function normalizeQuotes(sql: string): string {
+  return sql.replace(SMART_QUOTE_RE, (ch) => SMART_QUOTES[ch]);
+}
+
 /**
  * Split SQL text into individual statements on the given delimiter.
  *
  * Strips line comments (`-- ...`) and block comments, handles stored
  * procedure blocks delimited by `$$` or `//`.
  */
-function splitStatements(sql: string, delimiter = ";"): string[] {
+export function splitStatements(sql: string, delimiter = ";"): string[] {
+  // Normalize smart/curly quotes to straight ASCII first, so SQL pasted from
+  // an editor/doc (which converts " → “ ” and ' → ‘ ’) actually runs. Mirrors
+  // Python's _split_statements applying _normalize_quotes as its first line.
+  sql = normalizeQuotes(sql);
+
   // Extract blocks delimited by $$ or // first, replacing with placeholders
   const blocks: string[] = [];
   const saveBlock = (_match: string, _p1: string): string => {
@@ -426,7 +507,12 @@ function splitStatements(sql: string, delimiter = ";"): string[] {
   };
 
   let processed = sql.replace(/\$\$([\s\S]*?)\$\$/g, saveBlock);
-  processed = processed.replace(/\/\/([\s\S]*?)\/\//g, saveBlock);
+  // The `//` delimiters must NOT be preceded by a colon, so a URL scheme
+  // (`https://…`) or other `://` literal inside a migration is never captured
+  // as an opaque stored-proc block (it would otherwise swallow everything
+  // between two `//` occurrences and skip statement splitting/cleaning).
+  // Negative lookbehind `(?<!:)` mirrors Python's runner.
+  processed = processed.replace(/(?<!:)\/\/([\s\S]*?)(?<!:)\/\//g, saveBlock);
 
   // Remove block comments (/* ... */)
   const clean = processed.replace(/\/\*[\s\S]*?\*\//g, "");
@@ -458,25 +544,43 @@ function splitStatements(sql: string, delimiter = ";"): string[] {
  * - Sequential: 000001_name.sql, 000002_name.sql
  * - Timestamp: 20240315120000_name.sql (YYYYMMDDHHMMSS)
  *
- * Both patterns start with digits followed by underscore, so alphabetical
- * sort works correctly for both (zero-padded sequential and timestamp).
+ * Numeric-aware: a file with a leading numeric/timestamp prefix sorts first by
+ * that number (so `9_*` applies before `10_*` — a plain lexical sort misorders
+ * unpadded prefixes because "10" < "9"). Files with NO numeric prefix sort
+ * AFTER the numbered ones, then lexically. Mirrors Python's `_migration_sort_key`.
  */
-function sortMigrationFiles(files: string[]): string[] {
+export function sortMigrationFiles(files: string[]): string[] {
+  // Returns a tuple-like key: [group, numeric, name].
+  // group 0 = has numeric prefix (sorts first); group 1 = no prefix (sorts after).
+  const key = (name: string): [number, bigint, string] => {
+    const m = name.match(/^(\d+)/);
+    return m ? [0, BigInt(m[1]), name] : [1, 0n, name];
+  };
   return [...files].sort((a, b) => {
-    const aPrefix = a.match(/^(\d+)/);
-    const bPrefix = b.match(/^(\d+)/);
-    if (aPrefix && bPrefix) {
-      // Compare numeric prefixes — handles both 000001 and 20240315120000
-      const aNum = BigInt(aPrefix[1]);
-      const bNum = BigInt(bPrefix[1]);
-      if (aNum < bNum) return -1;
-      if (aNum > bNum) return 1;
-      return a.localeCompare(b);
-    }
-    return a.localeCompare(b);
+    const [ag, an, anm] = key(a);
+    const [bg, bn, bnm] = key(b);
+    if (ag !== bg) return ag - bg;
+    if (an < bn) return -1;
+    if (an > bn) return 1;
+    return anm.localeCompare(bnm);
   });
 }
 
+/**
+ * Warn (once) about migration filenames without a recognized NNNNNN_/timestamp
+ * prefix — their ordering relative to numbered migrations is undefined, a silent
+ * out-of-order-apply footgun. Mirrors Python's runner.
+ */
+function warnUnprefixedMigrations(files: string[]): void {
+  const unprefixed = files.filter((f) => !/^\d+[_-]/.test(f));
+  if (unprefixed.length > 0) {
+    Log.warning(
+      "Migration file(s) without a numeric/timestamp prefix may apply out of order: " +
+        unprefixed.join(", "),
+    );
+  }
+}
+
 /**
  * Run all pending SQL-file migrations.
  *
@@ -533,7 +637,19 @@ export async function migrate(
         batch INTEGER NOT NULL DEFAULT 1,
         applied_at TEXT NOT NULL
       )`);
+    } else if (engineOf(db) === "mssql") {
+      // MSSQL has no AUTOINCREMENT / IF NOT EXISTS — route the bootstrap
+      // through the adapter's engine-aware createTable (IDENTITY(1,1) etc.),
+      // exactly like ensureMigrationTable does. Emitting raw
+      // AUTOINCREMENT/IF NOT EXISTS here is invalid on SQL Server.
+      await adapterCreateTable(db, MIGRATION_TABLE, {
+        id: { type: "integer", primaryKey: true, autoIncrement: true },
+        name: { type: "string", required: true },
+        batch: { type: "integer", required: true },
+        applied_at: { type: "datetime", default: "now" },
+      });
     } else {
+      // SQLite / MySQL — both support IF NOT EXISTS + AUTOINCREMENT/AUTO_INCREMENT.
       await adapterExecute(db, `CREATE TABLE IF NOT EXISTS "${MIGRATION_TABLE}" (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         name TEXT NOT NULL,
@@ -553,13 +669,17 @@ export async function migrate(
     }
   }
 
-  // Collect .sql files (exclude .down.sql), sorted by prefix
+  // Collect .sql files (exclude .down.sql), numeric-aware sorted (9_ before 10_).
   const files = sortMigrationFiles(
     readdirSync(dir).filter((f) => f.endsWith(".sql") && !f.endsWith(".down.sql")),
   );
 
   if (files.length === 0) return result;
 
+  // Warn about files without a recognized numeric/timestamp prefix — their
+  // ordering relative to numbered migrations is undefined.
+  warnUnprefixedMigrations(files);
+
   // Determine the batch number for this run
   let currentBatch = 1;
   try {
@@ -621,10 +741,12 @@ export async function migrate(
       await adapterStartTransaction(db);
 
       for (const stmt of statements) {
-        // Firebird lacks IF NOT EXISTS for ALTER TABLE ADD.
-        // Pre-check the system catalogue so duplicate columns are
-        // silently skipped instead of raising an error.
-        const skipReason = await shouldSkipForFirebird(db, stmt);
+        // Idempotency on engines lacking IF NOT EXISTS: Firebird ALTER-TABLE-ADD,
+        // and CREATE TABLE on Firebird/MSSQL. Pre-check the catalogue so a genuine
+        // already-exists is skipped instead of raising — every other error still
+        // raises (rolls the file back).
+        const skipReason =
+          (await shouldSkipForFirebird(db, stmt)) ?? (await shouldSkipCreateTable(db, stmt));
         if (skipReason) {
           console.log(`  Migration ${file}: ${skipReason}`);
           continue;
@@ -671,7 +793,12 @@ export async function migrate(
       const msg = err instanceof Error ? err.message : String(err);
       console.error(`  Migration failed: ${file} — ${msg}`);
       result.failed.push(file);
-      // Continue to next file (matching Python behaviour)
+      // STOP at the first failure (parity with Python/PHP/Ruby). The file rolled
+      // back; later migrations must NOT be applied on top of a missing earlier
+      // one (a missing column / table would cascade silent corruption). Already-
+      // applied files stay applied — fix the bad file and re-run.
+      Log.error(`Migration stopped at first failure: ${file} — ${msg}`);
+      break;
     }
   }
 

package/packages/orm/src/queryBuilder.ts

@@ -428,8 +428,20 @@ export class QueryBuilder {
       return [{ [field]: { [mongoOp]: val } }, paramIndex + 1];
     }
 
-    // Fallback
-    return [{ $where: cond }, paramIndex];
+    // Canonical #5: no silent $where fallback. Previously an unparseable
+    // condition was wrapped as `{ $where: <raw condition string> }` — a raw-JS
+    // sink that is both injection-shaped (the WHERE string runs as JavaScript
+    // on the MongoDB server) and silently different semantics from the SQL the
+    // caller wrote. Fail loud instead: name the clause so the caller fixes it
+    // rather than shipping a surprise $where.
+    throw new Error(
+      `QueryBuilder.toMongo(): cannot translate WHERE clause to a MongoDB ` +
+        `filter: "${cond}". Supported forms: "<field> <op> ?" ` +
+        `(=, !=, <>, >, >=, <, <=), "<field> LIKE ?", ` +
+        `"<field> [NOT] IN (?)", "<field> IS [NOT] NULL". Rewrite the ` +
+        `condition in one of those forms (toMongo() will not silently emit a ` +
+        `raw $where JavaScript expression).`,
+    );
   }
 
   /**

package/packages/orm/src/types.ts

@@ -20,6 +20,13 @@ export interface FieldDefinition {
 export interface RelationshipDefinition {
   model: string;
   foreignKey: string;
+  /**
+   * The relationship accessor/include name on the OWNING model. For an
+   * FK-auto-wired has-many this is the declaring class name lowercased + "s"
+   * (Python master rule) or the `relatedName` override. Used by eager-load
+   * include resolution so an `include: ["posts"]` matches the wired relation.
+   */
+  relatedName?: string;
 }
 
 export interface ModelDefinition {

package/packages/orm/src/validation.ts

@@ -86,6 +86,20 @@ export function validate(
           errors.push({ field: name, message: "must be a valid date/time" });
         }
         break;
+
+      case "foreignKey": {
+        // Outlier D: previously there was no foreignKey case, so ANY value
+        // passed validation silently. A foreign key references another model's
+        // primary key — by default an auto-increment integer — so validate it
+        // as an integer (a numeric string like "12" is coerced and accepted).
+        // This catches the common bug of assigning a whole object / array /
+        // non-numeric string to an *_id column before it reaches the driver.
+        const fkNum = typeof value === "string" ? Number(value) : value;
+        if (typeof fkNum !== "number" || isNaN(fkNum) || !Number.isInteger(fkNum)) {
+          errors.push({ field: name, message: "must be a valid foreign key (integer)" });
+        }
+        break;
+      }
     }
   }
 

package/packages/swagger/src/generator.ts

@@ -12,10 +12,14 @@ interface OpenAPISpecInfo {
 interface OpenAPISpec {
   openapi: string;
   info: OpenAPISpecInfo;
+  servers?: { url: string }[];
   paths: Record<string, Record<string, unknown>>;
-  components?: { schemas?: Record<string, unknown> };
+  components?: { schemas?: Record<string, unknown>; securitySchemes?: Record<string, unknown> };
+  tags?: { name: string }[];
 }
 
+const WRITE_METHODS = new Set(["post", "put", "patch", "delete"]);
+
 export function generate(
   routes: RouteDefinition[],
   models: ModelDefinition[] = []
@@ -26,12 +30,16 @@ export function generate(
     description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
   };
 
-  // Optional contact email — surfaced in the OpenAPI `info.contact.email`
-  // field when set. Matches the python `SWAGGER_CONTACT_EMAIL` convention.
+  // Optional contact — email, plus name/url (the interface declares them; they
+  // were never populated before). Matches the python SWAGGER_CONTACT_* convention.
   const contactEmail = (process.env.TINA4_SWAGGER_CONTACT_EMAIL ?? "").trim();
-  if (contactEmail.length > 0) {
-    info.contact = { email: contactEmail };
-  }
+  const contactName = (process.env.TINA4_SWAGGER_CONTACT_TEAM ?? "").trim();
+  const contactUrl = (process.env.TINA4_SWAGGER_CONTACT_URL ?? "").trim();
+  const contact: { name?: string; url?: string; email?: string } = {};
+  if (contactName.length > 0) contact.name = contactName;
+  if (contactUrl.length > 0) contact.url = contactUrl;
+  if (contactEmail.length > 0) contact.email = contactEmail;
+  if (Object.keys(contact).length > 0) info.contact = contact;
 
   // Optional license — accepts a plain SPDX identifier ("MIT", "Apache-2.0")
   // or a "Name|URL" pair. Empty string disables license output entirely.
@@ -44,8 +52,16 @@ export function generate(
   const spec: OpenAPISpec = {
     openapi: "3.0.3",
     info,
+    servers: resolveServers(),
     paths: {},
-    components: { schemas: {} },
+    components: {
+      schemas: {},
+      // bearerAuth was never defined before — secured routes were documented
+      // identically to public ones (audit P1). Define it once and reference it.
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+      },
+    },
   };
 
   // Generate schemas from models
@@ -54,6 +70,9 @@ export function generate(
     spec.components!.schemas![model.tableName] = schema;
   }
 
+  const usedTags: string[] = [];
+  const seenIds = new Set<string>();
+
   // Generate paths from routes
   for (const route of routes) {
     const openApiPath = patternToOpenAPI(route.pattern);
@@ -63,14 +82,23 @@ export function generate(
       spec.paths[openApiPath] = {};
     }
 
+    const tags = route.meta?.tags ?? inferTags(route.pattern);
+    for (const t of tags) {
+      if (!usedTags.includes(t)) usedTags.push(t);
+    }
+
     const operation: Record<string, unknown> = {
+      operationId: uniqueOperationId(method, openApiPath, seenIds),
       summary: route.meta?.summary ?? `${route.method} ${route.pattern}`,
-      tags: route.meta?.tags ?? inferTags(route.pattern),
+      tags,
       responses: route.meta?.responses ?? {
         "200": { description: "Successful response" },
       },
     };
 
+    if (route.meta?.description) operation.description = route.meta.description;
+    if (route.meta?.deprecated) operation.deprecated = true;
+
     // Add path parameters
     const pathParams = extractPathParams(route.pattern);
     if (pathParams.length > 0) {
@@ -99,13 +127,13 @@ export function generate(
     if (method === "post" || method === "put") {
       const modelName = inferModelFromPath(route.pattern);
       if (modelName && models.some((m) => m.tableName === modelName)) {
+        const media: Record<string, unknown> = {
+          schema: { $ref: `#/components/schemas/${modelName}` },
+        };
+        if (route.meta?.example !== undefined) media.example = route.meta.example;
         operation.requestBody = {
           required: true,
-          content: {
-            "application/json": {
-              schema: { $ref: `#/components/schemas/${modelName}` },
-            },
-          },
+          content: { "application/json": media },
         };
 
         // Add response schema
@@ -115,15 +143,47 @@ export function generate(
             : { "200": { description: "Updated", content: { "application/json": { schema: { $ref: `#/components/schemas/${modelName}` } } } } }),
           "422": { description: "Validation failed" },
         };
+      } else if (route.meta?.example !== undefined) {
+        // Non-model body with an explicit example.
+        operation.requestBody = {
+          content: { "application/json": { schema: inferSchema(route.meta.example), example: route.meta.example } },
+        };
       }
     }
 
+    // Security — a secured route emits operation.security + 401. Mirrors the
+    // router's enforcement (writes secure by default unless noAuth; GET secure
+    // only when marked). Before, no route ever got a security requirement.
+    if (routeRequiresAuth(route, method)) {
+      operation.security = [{ bearerAuth: [] }];
+      const responses = operation.responses as Record<string, unknown>;
+      if (!responses["401"]) responses["401"] = { description: "Unauthorized" };
+    }
+
     spec.paths[openApiPath][method] = operation;
   }
 
+  if (usedTags.length > 0) {
+    spec.tags = usedTags.map((name) => ({ name }));
+  }
+
   return spec;
 }
 
+function routeRequiresAuth(route: RouteDefinition, method: string): boolean {
+  if (route.noAuth) return false;
+  if (WRITE_METHODS.has(method)) return true; // secure by default (router parity)
+  return route.secure === true;
+}
+
+function resolveServers(): { url: string }[] {
+  const raw = (process.env.TINA4_SWAGGER_SERVERS ?? "").trim();
+  const urls = raw.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (urls.length > 0) return urls.map((url) => ({ url }));
+  const dev = (process.env.SWAGGER_DEV_URL ?? "").trim();
+  return dev.length > 0 ? [{ url: dev }] : [{ url: "/" }];
+}
+
 function modelToSchema(model: ModelDefinition): Record<string, unknown> {
   const properties: Record<string, unknown> = {};
   const required: string[] = [];
@@ -171,8 +231,16 @@ function fieldToSchemaProperty(def: FieldDefinition): Record<string, unknown> {
       prop.type = "string";
       prop.format = "date-time";
       break;
+    case "foreignKey":
+      // A foreign-key column is an integer reference. Before, it had no case
+      // and produced an empty {} schema (audit P2).
+      prop.type = "integer";
+      break;
+    default:
+      prop.type = "string";
   }
 
+  if (def.default !== undefined) prop.default = def.default;
   if (def.primaryKey && def.autoIncrement) {
     prop.readOnly = true;
   }
@@ -180,6 +248,22 @@ function fieldToSchemaProperty(def: FieldDefinition): Record<string, unknown> {
   return prop;
 }
 
+function inferSchema(value: unknown): Record<string, unknown> {
+  if (Array.isArray(value)) {
+    return { type: "array", items: value.length > 0 ? inferSchema(value[0]) : {} };
+  }
+  if (value !== null && typeof value === "object") {
+    const properties: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+      properties[k] = inferSchema(v);
+    }
+    return { type: "object", properties };
+  }
+  if (typeof value === "boolean") return { type: "boolean" };
+  if (typeof value === "number") return { type: Number.isInteger(value) ? "integer" : "number" };
+  return { type: "string" };
+}
+
 function patternToOpenAPI(pattern: string): string {
   return pattern.replace(/\[\.\.\.(\w+)\]/g, "{$1}").replace(/\[(\w+)\]/g, "{$1}");
 }
@@ -207,8 +291,27 @@ function inferTags(pattern: string): string[] {
 function inferModelFromPath(pattern: string): string | null {
   const parts = pattern.split("/").filter(Boolean);
   const apiIndex = parts.indexOf("api");
-  if (apiIndex !== -1 && parts[apiIndex + 1]) {
-    return parts[apiIndex + 1];
-  }
+  if (apiIndex === -1 || !parts[apiIndex + 1]) return null;
+  const candidate = parts[apiIndex + 1];
+  // Only a SIMPLE resource binds a model: /api/<model> or /api/<model>/[id].
+  // A deeper nested path (/api/users/[id]/comments) must NOT attach the parent
+  // resource's body/schema to the sub-resource endpoint (audit P2).
+  const rest = parts.slice(apiIndex + 2);
+  if (rest.length === 0) return candidate;
+  if (rest.length === 1 && /^[[{]\.{0,3}\w+[\]}]$/.test(rest[0])) return candidate;
   return null;
 }
+
+function uniqueOperationId(method: string, openApiPath: string, seen: Set<string>): string {
+  const base = (method + openApiPath.replace(/[/{}]/g, "_"))
+    .replace(/_+/g, "_")
+    .replace(/_$/, "");
+  let oid = base;
+  let n = 2;
+  while (seen.has(oid)) {
+    oid = `${base}_${n}`;
+    n += 1;
+  }
+  seen.add(oid);
+  return oid;
+}

package/packages/swagger/src/ui.ts

@@ -1,11 +1,19 @@
 import type { Tina4Request, Tina4Response, RouteDefinition } from "@tina4/core";
 
+// The UI assets load from a CDN by default (a documented architecture decision —
+// we don't vendor ~1.4MB of swagger-ui-dist, to stay small). Air-gapped
+// deployments point TINA4_SWAGGER_UI_CDN at a self-hosted mirror (a base URL
+// serving swagger-ui.css + swagger-ui-bundle.js).
+function swaggerUiCdn(): string {
+  return (process.env.TINA4_SWAGGER_UI_CDN ?? "https://unpkg.com/swagger-ui-dist@5").replace(/\/+$/, "");
+}
+
 const SWAGGER_UI_HTML = (specUrl: string) => `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <title>Tina4 API Documentation</title>
-  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5/swagger-ui.css">
+  <link rel="stylesheet" href="${swaggerUiCdn()}/swagger-ui.css">
   <style>
     body { margin: 0; background: #fafafa; }
     .topbar { display: none !important; }
@@ -13,7 +21,7 @@ const SWAGGER_UI_HTML = (specUrl: string) => `<!DOCTYPE html>
 </head>
 <body>
   <div id="swagger-ui"></div>
-  <script src="https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js"></script>
+  <script src="${swaggerUiCdn()}/swagger-ui-bundle.js"></script>
   <script>
     SwaggerUIBundle({
       url: "${specUrl}",