tina4-nodejs 3.11.19 → 3.12.0

package/packages/core/src/devAdmin.ts

@@ -1206,9 +1206,9 @@ function parseEnvFile(): Record<string, string> {
 const handleConnections: RouteHandler = (_req, res) => {
   const env = parseEnvFile();
   res.json({
-    url: env.DATABASE_URL ?? "",
-    username: env.DATABASE_USERNAME ?? "",
-    password: env.DATABASE_PASSWORD ? "***" : "",
+    url: env.TINA4_DATABASE_URL ?? "",
+    username: env.TINA4_DATABASE_USERNAME ?? "",
+    password: env.TINA4_DATABASE_PASSWORD ? "***" : "",
   });
 };
 
@@ -1274,7 +1274,7 @@ const handleConnectionsSave: RouteHandler = (req, res) => {
   try {
     const envPath = join(process.cwd(), ".env");
     const lines = existsSync(envPath) ? readFileSync(envPath, "utf-8").split("\n") : [];
-    const keysFound: Record<string, boolean> = { DATABASE_URL: false, DATABASE_USERNAME: false, DATABASE_PASSWORD: false };
+    const keysFound: Record<string, boolean> = { TINA4_DATABASE_URL: false, TINA4_DATABASE_USERNAME: false, TINA4_DATABASE_PASSWORD: false };
     const newLines: string[] = [];
     for (const line of lines) {
       const trimmed = line.trim();
@@ -1283,12 +1283,12 @@ const handleConnectionsSave: RouteHandler = (req, res) => {
         continue;
       }
       const key = trimmed.split("=", 1)[0].trim();
-      if (key === "DATABASE_URL") { newLines.push(`DATABASE_URL=${url}`); keysFound.DATABASE_URL = true; }
-      else if (key === "DATABASE_USERNAME") { newLines.push(`DATABASE_USERNAME=${username}`); keysFound.DATABASE_USERNAME = true; }
-      else if (key === "DATABASE_PASSWORD") { newLines.push(`DATABASE_PASSWORD=${password}`); keysFound.DATABASE_PASSWORD = true; }
+      if (key === "TINA4_DATABASE_URL") { newLines.push(`TINA4_DATABASE_URL=${url}`); keysFound.TINA4_DATABASE_URL = true; }
+      else if (key === "TINA4_DATABASE_USERNAME") { newLines.push(`TINA4_DATABASE_USERNAME=${username}`); keysFound.TINA4_DATABASE_USERNAME = true; }
+      else if (key === "TINA4_DATABASE_PASSWORD") { newLines.push(`TINA4_DATABASE_PASSWORD=${password}`); keysFound.TINA4_DATABASE_PASSWORD = true; }
       else { newLines.push(line); }
     }
-    const values: Record<string, string> = { DATABASE_URL: url, DATABASE_USERNAME: username, DATABASE_PASSWORD: password };
+    const values: Record<string, string> = { TINA4_DATABASE_URL: url, TINA4_DATABASE_USERNAME: username, TINA4_DATABASE_PASSWORD: password };
     for (const [key, found] of Object.entries(keysFound)) {
       if (!found) newLines.push(`${key}=${values[key]}`);
     }

package/packages/core/src/devMailbox.ts

@@ -57,7 +57,7 @@ export class DevMailbox {
     const message: EmailMessage = {
       id,
       type: "outbox",
-      from: from ?? process.env.SMTP_FROM ?? "dev@localhost",
+      from: from ?? process.env.TINA4_MAIL_FROM ?? "dev@localhost",
       to: toList,
       cc,
       bcc,
@@ -286,7 +286,7 @@ export class DevMailbox {
  *
  * Returns DevMailbox when:
  *   - TINA4_DEBUG is "true", OR
- *   - No SMTP_HOST is configured
+ *   - No TINA4_MAIL_HOST is configured
  *
  * Returns a real Messenger otherwise (SMTP configured + not debug mode).
  *
@@ -294,7 +294,7 @@ export class DevMailbox {
  */
 export function createMessenger(): Messenger | DevMailbox {
   const debug = process.env.TINA4_DEBUG;
-  const smtpHost = process.env.SMTP_HOST;
+  const smtpHost = process.env.TINA4_MAIL_HOST;
 
   // Force dev mode when TINA4_DEBUG is truthy
   if (isTruthy(debug)) {

package/packages/core/src/index.ts

@@ -12,7 +12,7 @@ export type {
   WebSocketRouteDefinition,
 } from "./types.js";
 
-export { startServer, resolvePortAndHost, handle, start, stop } from "./server.js";
+export { startServer, resolvePortAndHost, handle, start, stop, httpReason, resolveTemplate, resetTemplateCache, templateAutoRoutingEnabled } from "./server.js";
 export { background, stopAllBackgroundTasks, backgroundTaskCount } from "./background.js";
 export { Router, RouteGroup, RouteRef, defaultRouter, runRouteMiddlewares } from "./router.js";
 export { get, post, put, patch, del, any, websocket, del as delete } from "./router.js";

package/packages/core/src/mcp.test.ts

@@ -300,25 +300,25 @@ console.log("\nResource Registration and Read");
 console.log("\nLocalhost Detection");
 
 {
-  const oldHost = process.env.HOST_NAME;
+  const oldHost = process.env.TINA4_HOST_NAME;
 
-  process.env.HOST_NAME = "localhost:7148";
+  process.env.TINA4_HOST_NAME = "localhost:7148";
   assert("isLocalhost — localhost", isLocalhost() === true);
 
-  process.env.HOST_NAME = "127.0.0.1:7148";
+  process.env.TINA4_HOST_NAME = "127.0.0.1:7148";
   assert("isLocalhost — 127.0.0.1", isLocalhost() === true);
 
-  process.env.HOST_NAME = "0.0.0.0:7148";
+  process.env.TINA4_HOST_NAME = "0.0.0.0:7148";
   assert("isLocalhost — 0.0.0.0", isLocalhost() === true);
 
-  process.env.HOST_NAME = "myserver.example.com:7148";
+  process.env.TINA4_HOST_NAME = "myserver.example.com:7148";
   assert("isLocalhost — remote false", isLocalhost() === false);
 
   // Restore
   if (oldHost !== undefined) {
-    process.env.HOST_NAME = oldHost;
+    process.env.TINA4_HOST_NAME = oldHost;
   } else {
-    delete process.env.HOST_NAME;
+    delete process.env.TINA4_HOST_NAME;
   }
 }
 

package/packages/core/src/mcp.ts

@@ -157,7 +157,7 @@ export function schemaFromParams(params: McpToolParam[]): JsonSchema {
 // ── Localhost detection ──────────────────────────────────────
 
 export function isLocalhost(): boolean {
-  const hostEnv = process.env.HOST_NAME || "localhost:7148";
+  const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
   return ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].includes(host);
 }

package/packages/core/src/messenger.ts

@@ -302,28 +302,24 @@ export class Messenger {
   private imapPass: string;
 
   constructor(options?: MessengerOptions) {
-    // Priority: constructor > TINA4_MAIL_* > SMTP_* > sensible default
+    // Priority: constructor > TINA4_MAIL_* > sensible default.
+    // Legacy SMTP_*/IMAP_* env vars were removed in v3.12 — boot guard rejects them.
     this.host = options?.host
       ?? process.env.TINA4_MAIL_HOST
-      ?? process.env.SMTP_HOST
       ?? "localhost";
     this.port = options?.port
-      ?? parseInt(process.env.TINA4_MAIL_PORT ?? process.env.SMTP_PORT ?? "587", 10);
+      ?? parseInt(process.env.TINA4_MAIL_PORT ?? "587", 10);
     this.username = options?.username
       ?? process.env.TINA4_MAIL_USERNAME
-      ?? process.env.SMTP_USERNAME
       ?? "";
     this.password = options?.password
       ?? process.env.TINA4_MAIL_PASSWORD
-      ?? process.env.SMTP_PASSWORD
       ?? "";
     this.fromAddress = options?.fromAddress
       ?? process.env.TINA4_MAIL_FROM
-      ?? process.env.SMTP_FROM
       ?? (this.username || "noreply@localhost");
     this.fromName = options?.fromName
       ?? process.env.TINA4_MAIL_FROM_NAME
-      ?? process.env.SMTP_FROM_NAME
       ?? "";
 
     // Encryption: constructor > .env > backward-compat useTls > default "tls"
@@ -340,15 +336,14 @@ export class Messenger {
 
     this.imapHost = options?.imapHost
       ?? process.env.TINA4_MAIL_IMAP_HOST
-      ?? process.env.IMAP_HOST
       ?? "";
     this.imapPort = options?.imapPort
-      ?? parseInt(process.env.TINA4_MAIL_IMAP_PORT ?? process.env.IMAP_PORT ?? "993", 10);
+      ?? parseInt(process.env.TINA4_MAIL_IMAP_PORT ?? "993", 10);
     this.imapUser = options?.imapUser
-      ?? process.env.IMAP_USER
+      ?? process.env.TINA4_MAIL_IMAP_USERNAME
       ?? this.username;
     this.imapPass = options?.imapPass
-      ?? process.env.IMAP_PASS
+      ?? process.env.TINA4_MAIL_IMAP_PASSWORD
       ?? this.password;
   }
 

package/packages/core/src/server.ts

@@ -47,6 +47,83 @@ const TINA4_VERSION = readPackageVersion();
 /** Cache Frond instances by template directory to avoid repeated instantiation. */
 const frondCache = new Map<string, InstanceType<any>>();
 
+// ─── Legacy env var guard (v3.12 hard rename) ────────────────────────────
+// All framework env vars now require the TINA4_ prefix. If any of these
+// pre-3.12 names are present in the environment we refuse to boot —
+// silently ignoring them would cause auth/db/mail to fall back to
+// defaults with no warning. Each maps to its new TINA4_-prefixed
+// canonical name.
+const _LEGACY_ENV_VARS: Record<string, string> = {
+  DATABASE_URL:           "TINA4_DATABASE_URL",
+  DATABASE_USERNAME:      "TINA4_DATABASE_USERNAME",
+  DATABASE_PASSWORD:      "TINA4_DATABASE_PASSWORD",
+  DB_URL:                 "TINA4_DATABASE_URL",
+  SECRET:                 "TINA4_SECRET",
+  API_KEY:                "TINA4_API_KEY",
+  JWT_ALGORITHM:          "TINA4_JWT_ALGORITHM",
+  SMTP_HOST:              "TINA4_MAIL_HOST",
+  SMTP_PORT:              "TINA4_MAIL_PORT",
+  SMTP_USERNAME:          "TINA4_MAIL_USERNAME",
+  SMTP_PASSWORD:          "TINA4_MAIL_PASSWORD",
+  SMTP_FROM:              "TINA4_MAIL_FROM",
+  SMTP_FROM_NAME:         "TINA4_MAIL_FROM_NAME",
+  IMAP_HOST:              "TINA4_MAIL_IMAP_HOST",
+  IMAP_PORT:              "TINA4_MAIL_IMAP_PORT",
+  IMAP_USER:              "TINA4_MAIL_IMAP_USERNAME",
+  IMAP_PASS:              "TINA4_MAIL_IMAP_PASSWORD",
+  HOST_NAME:              "TINA4_HOST_NAME",
+  SWAGGER_TITLE:          "TINA4_SWAGGER_TITLE",
+  SWAGGER_DESCRIPTION:    "TINA4_SWAGGER_DESCRIPTION",
+  SWAGGER_VERSION:        "TINA4_SWAGGER_VERSION",
+  ORM_PLURAL_TABLE_NAMES: "TINA4_ORM_PLURAL_TABLE_NAMES",
+};
+
+/**
+ * Refuse to boot if pre-3.12 un-prefixed env vars are still set.
+ *
+ * Tina4 v3.12 hard-renamed every framework-specific env var to use the
+ * `TINA4_` prefix. Booting silently with a legacy `DATABASE_URL` or
+ * `SECRET` would let auth, DB, or mail fall back to insecure defaults
+ * while the user thought their config was being read. Better to die
+ * loudly with a list of names to fix.
+ *
+ * Bypass with `TINA4_ALLOW_LEGACY_ENV=true` in CI / migration scripts
+ * that genuinely need both names set during a transition window.
+ */
+export function _checkLegacyEnvVars(): void {
+  if (isTruthy(process.env.TINA4_ALLOW_LEGACY_ENV)) {
+    return;
+  }
+  const found = Object.keys(_LEGACY_ENV_VARS)
+    .filter((name) => process.env[name] !== undefined)
+    .sort();
+  if (found.length === 0) {
+    return;
+  }
+  const bar = "─".repeat(72);
+  const lines: string[] = [
+    "",
+    bar,
+    "Tina4 v3.12 requires TINA4_ prefix on all framework env vars.",
+    "Your environment still has these legacy names:",
+    "",
+  ];
+  for (const old of found) {
+    const next = _LEGACY_ENV_VARS[old];
+    lines.push(`    ${old.padEnd(28)}  →  ${next}`);
+  }
+  lines.push(
+    "",
+    "Run `tina4 env-migrate` to rewrite your .env automatically,",
+    "or rename manually. See https://tina4.com/release/3.12.0",
+    "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
+    bar,
+    "",
+  );
+  process.stderr.write(lines.join("\n") + "\n");
+  process.exit(2);
+}
+
 /**
  * Kill whatever process is listening on *port*.
  * Uses lsof on macOS/Linux and netstat + taskkill on Windows.
@@ -231,23 +308,96 @@ function getGalleryDeployedState(): Record<string, boolean> {
   return state;
 }
 
+/**
+ * Auto-routing scans this single subdirectory of src/templates/. Only files
+ * in src/templates/pages/ become URLs — everything else (partials, layouts,
+ * base.twig, errors, components, macros) is never URL-exposed and remains
+ * renderable only via {% include %} / {% extends %} / res.render().
+ *
+ * Convention adapted from Next.js' pages/ directory and Nuxt's pages/ folder.
+ * Explicit, secure by default, no skip lists to maintain.
+ */
+const TEMPLATE_PAGES_DIR = "pages";
+
+/**
+ * Honour TINA4_TEMPLATE_ROUTING=off|false|0|no|disabled as an explicit kill
+ * switch. Default: enabled. Drop a file in src/templates/pages/ and it serves
+ * at the matching URL — the zero-config Tina4 convention. Operators who want
+ * explicit-only routing can set TINA4_TEMPLATE_ROUTING=off and every URL
+ * must be registered via get() / post() (or be a static file).
+ */
+export function templateAutoRoutingEnabled(): boolean {
+  const val = (process.env.TINA4_TEMPLATE_ROUTING ?? "on").trim().toLowerCase();
+  return !["off", "false", "0", "no", "disabled"].includes(val);
+}
+
+/**
+ * RFC 7231 / RFC 9110 status reason phrases. Used to write a correct HTTP
+ * status line — previously some paths wrote "HTTP/1.1 404 OK" because the
+ * canonical phrase wasn't being looked up per code.
+ */
+const HTTP_REASON_PHRASES: Record<number, string> = {
+  100: "Continue", 101: "Switching Protocols",
+  200: "OK", 201: "Created", 202: "Accepted", 204: "No Content",
+  206: "Partial Content",
+  301: "Moved Permanently", 302: "Found", 303: "See Other",
+  304: "Not Modified", 307: "Temporary Redirect", 308: "Permanent Redirect",
+  400: "Bad Request", 401: "Unauthorized", 403: "Forbidden",
+  404: "Not Found", 405: "Method Not Allowed", 406: "Not Acceptable",
+  409: "Conflict", 410: "Gone", 413: "Content Too Large",
+  415: "Unsupported Media Type", 422: "Unprocessable Content",
+  429: "Too Many Requests",
+  500: "Internal Server Error", 501: "Not Implemented",
+  502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
+};
+
+/**
+ * Return the canonical HTTP reason phrase for `status`. Falls back to a
+ * sensible label when an exotic status is used. Never returns an empty string.
+ */
+export function httpReason(status: number): string {
+  const phrase = HTTP_REASON_PHRASES[status];
+  if (phrase) return phrase;
+  return status >= 200 && status < 300 ? "OK" : "Error";
+}
+
 /** Template cache: url_path -> template_file. Null until first production lookup. */
 let templateCache: Map<string, string> | null = null;
 
 /**
- * Resolve a URL path to a template file in src/templates/.
+ * Reset the production template cache. Tests use this between scenarios so
+ * a fresh scan picks up fixture files in a tmp project.
+ */
+export function resetTemplateCache(): void {
+  templateCache = null;
+}
+
+/**
+ * Resolve a URL path to a template file in src/templates/pages/.
+ *
+ * Only files inside `src/templates/pages/` auto-route from a URL. Anything
+ * in `src/templates/` outside `pages/` (partials, layouts, base.twig,
+ * errors, components) is never served standalone.
+ *
  * Dev mode: checks filesystem every time for live changes.
  * Production: uses a cached lookup built once at startup.
+ *
+ * The whole feature can be turned off with `TINA4_TEMPLATE_ROUTING=off`.
  */
-function resolveTemplate(pathname: string, templatesDir: string): string | null {
-  const cleanPath = pathname.replace(/^\//, "") || "index";
+export function resolveTemplate(pathname: string, templatesDir: string): string | null {
+  if (!templateAutoRoutingEnabled()) return null;
+
+  const cleanPath = pathname.replace(/^\/+/, "").replace(/\/+$/, "") || "index";
   const isDev = (process.env.TINA4_DEBUG ?? "false").toLowerCase() === "true";
 
   if (isDev) {
+    // Skip underscore-prefixed files even within pages/ — they're private
+    // by Hugo/Jekyll convention (helpers, fragments) and shouldn't auto-serve.
+    if (cleanPath.split("/").some((seg) => seg.startsWith("_"))) return null;
+    const pagesDir = resolve(templatesDir, TEMPLATE_PAGES_DIR);
     for (const ext of [".twig", ".html"]) {
-      const candidate = cleanPath + ext;
-      if (existsSync(resolve(templatesDir, candidate))) {
-        return candidate;
+      if (existsSync(resolve(pagesDir, cleanPath + ext))) {
+        return `${TEMPLATE_PAGES_DIR}/${cleanPath}${ext}`;
       }
     }
     return null;
@@ -256,21 +406,24 @@ function resolveTemplate(pathname: string, templatesDir: string): string | null
   // Production: cached lookup
   if (!templateCache) {
     templateCache = new Map();
-    if (existsSync(templatesDir)) {
+    const pagesDir = resolve(templatesDir, TEMPLATE_PAGES_DIR);
+    if (existsSync(pagesDir)) {
       const scan = (dir: string, prefix: string) => {
         for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          // Skip private files even within pages/ (e.g. pages/_helper.twig)
+          if (entry.name.startsWith("_")) continue;
           const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
           if (entry.isDirectory()) {
             scan(resolve(dir, entry.name), rel);
           } else if (entry.name.endsWith(".twig") || entry.name.endsWith(".html")) {
             const urlPath = rel.replace(/\.(twig|html)$/, "");
             if (!templateCache!.has(urlPath)) {
-              templateCache!.set(urlPath, rel);
+              templateCache!.set(urlPath, `${TEMPLATE_PAGES_DIR}/${rel}`);
             }
           }
         }
       };
-      scan(templatesDir, "");
+      scan(pagesDir, "");
     }
   }
   return templateCache.get(cleanPath) ?? null;
@@ -502,6 +655,9 @@ export async function startServer(config?: Tina4Config): Promise<{
   // Load .env early so TINA4_DEBUG is available for cluster decision
   loadEnv();
 
+  // Refuse to boot with pre-3.12 un-prefixed env vars set.
+  _checkLegacyEnvVars();
+
   const resolved = resolvePortAndHost(config);
   const host = resolved.host;
   let port = resolved.port;
@@ -566,6 +722,9 @@ ${reset}
   const modelsDir = resolve(base, config?.modelsDir ?? "src/models");
   const ormDir = resolve(base, "src/orm");
   const staticDir = resolve(base, config?.staticDir ?? "public");
+  // src/public is the second-tier static dir (Python parity). When the user
+  // ships a Vite/SPA build there, src/public/index.html auto-serves at "/".
+  const srcPublicDir = resolve(base, "src/public");
   const templatesDir = resolve(base, config?.templatesDir ?? "src/templates");
 
   // .env already loaded above for cluster decision
@@ -834,10 +993,14 @@ ${reset}
         res.raw.end = wrappedEnd;
       }
 
-      // Try static files first (project public dir, then framework built-in public dir)
+      // Try static files first (project public dir, src/public dir, then framework built-in)
+      // Index resolution: "/" or "/foo/" picks up index.html so SPA builds Just Work.
       if (existsSync(staticDir) && tryServeStatic(staticDir, req, res)) {
         return;
       }
+      if (existsSync(srcPublicDir) && tryServeStatic(srcPublicDir, req, res)) {
+        return;
+      }
       if (tryServeStatic(BUILTIN_PUBLIC_DIR, req, res)) {
         return;
       }
@@ -944,34 +1107,45 @@ ${reset}
         return;
       }
 
-      // Try serving a template file (e.g. /hello -> src/templates/hello.twig or hello.html)
+      // Try serving a template file (e.g. /hello -> src/templates/pages/hello.twig)
       if ((req.method ?? "GET") === "GET") {
         const tplFile = resolveTemplate(pathname, templatesDir);
         if (tplFile) {
-          const html = readFileSync(resolve(templatesDir, tplFile), "utf-8");
-          res.raw.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-          res.raw.end(html);
+          // Render through Frond so {% include %} / {% extends %} work,
+          // not raw readFileSync.
+          if (frondEngine) {
+            const html = frondEngine.render(tplFile, {});
+            res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
+            res.raw.end(html);
+          } else {
+            const html = readFileSync(resolve(templatesDir, tplFile), "utf-8");
+            res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
+            res.raw.end(html);
+          }
           return;
         }
 
-        // Show landing page for "/" when no template exists
-        if (pathname === "/") {
+        // Landing page renders only at "/" AND only when TINA4_DEBUG=true.
+        // In production "/" with no static index.html and no pages/index.twig
+        // falls through to a clean 404 — the framework's branded welcome,
+        // gallery and version never leak to real users.
+        if (pathname === "/" && isDevMode()) {
           const allRoutes = router.getRoutes().map((r) => ({
             method: r.method,
             pattern: r.pattern,
             flags: [] as string[],
           }));
           const html = renderLandingPage(allRoutes, port);
-          res.raw.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+          res.raw.writeHead(200, undefined, { "Content-Type": "text/html; charset=utf-8" });
           res.raw.end(html);
           return;
         }
       }
 
-      // 404
+      // 404 — pass canonical reason phrase so the status line is well-formed
       const html404 = await renderErrorPage(404, { path: pathname }, templatesDir);
       if (html404) {
-        res.raw.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+        res.raw.writeHead(404, httpReason(404), { "Content-Type": "text/html; charset=utf-8" });
         res.raw.end(html404);
       } else {
         res({ error: "Not Found", statusCode: 404, message: `No route found for ${req.method} ${pathname}` }, 404);

package/packages/core/src/sessionHandlers/databaseHandler.ts

@@ -42,10 +42,10 @@ export class DatabaseSessionHandler implements SessionHandler {
   }
 
   /**
-   * Resolve the database file path from DATABASE_URL or use the default.
+   * Resolve the database file path from TINA4_DATABASE_URL or use the default.
    */
   private resolveDbPath(): string {
-    const url = process.env.DATABASE_URL;
+    const url = process.env.TINA4_DATABASE_URL;
     if (url && url.startsWith("sqlite://")) {
       // sqlite:///path/to/db  or  sqlite://./relative/path
       return url.replace(/^sqlite:\/\//, "");

package/packages/frond/src/engine.ts

@@ -1271,7 +1271,7 @@ export function setFormTokenSessionId(sessionId: string): void {
 }
 
 function _buildFormTokenJwt(descriptor: string = ""): string {
-  const secret = process.env.SECRET || "tina4-default-secret";
+  const secret = process.env.TINA4_SECRET || "tina4-default-secret";
   const ttlMinutes = parseInt(process.env.TINA4_TOKEN_LIMIT || "60", 10);
 
   const header = { alg: "HS256", typ: "JWT" };

package/packages/orm/src/baseModel.ts

@@ -21,11 +21,11 @@ export function camelToSnake(name: string): string {
 }
 
 /**
- * Check whether ORM_PLURAL_TABLE_NAMES is enabled in .env.
+ * Check whether TINA4_ORM_PLURAL_TABLE_NAMES is enabled in .env.
  * When true, hasMany relationship keys get an "s" suffix (e.g. "posts" instead of "post").
  */
 function _pluralRelKeys(): boolean {
-  const v = process.env.ORM_PLURAL_TABLE_NAMES ?? "";
+  const v = process.env.TINA4_ORM_PLURAL_TABLE_NAMES ?? "";
   return /^(true|1|yes)$/i.test(v);
 }
 
@@ -217,8 +217,8 @@ export class BaseModel {
     try {
       return getAdapter();
     } catch {
-      // No adapter registered — try DATABASE_URL auto-discovery
-      const url = process.env.DATABASE_URL;
+      // No adapter registered — try TINA4_DATABASE_URL auto-discovery
+      const url = process.env.TINA4_DATABASE_URL;
       if (url) {
         const parsed = parseDatabaseUrl(url);
         if (parsed.type === "sqlite") {

package/packages/orm/src/database.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { DatabaseAdapter, DatabaseResult as DatabaseWriteResult } from "./types.js";
 import { DatabaseResult } from "./databaseResult.js";
 
@@ -256,6 +257,23 @@ export class Database {
   /** Database engine type (sqlite, postgres, mysql, mssql, firebird) */
   private dbType: string = "sqlite";
 
+  /**
+   * Async-local storage for the adapter pinned to the current transaction.
+   *
+   * With pooling enabled, ordinary calls round-robin through the pool. Inside
+   * a transaction, however, all calls must land on the SAME adapter — otherwise
+   * startTransaction(), execute() and commit() each rotate to a different
+   * connection and the transaction is meaningless (executes autocommit on
+   * whatever adapter they hit; the final commit lands on yet another adapter
+   * that has nothing to commit; rollback() is silently no-op'd).
+   *
+   * AsyncLocalStorage is the Node analog of Python's threading.local. It pins
+   * the adapter to the current async task tree so concurrent transactions on
+   * the same Database don't clobber each other. startTransaction() sets the
+   * pin via .enterWith(); commit()/rollback() clear it.
+   */
+  private txStore: AsyncLocalStorage<{ adapter: DatabaseAdapter | null }> = new AsyncLocalStorage();
+
   /**
    * Create a Database wrapping an existing adapter.
    * For creating a Database from a URL, use the async static factories:
@@ -320,8 +338,15 @@ export class Database {
 
   /**
    * Get the next adapter — from pool (round-robin) or single connection.
+   *
+   * If a transaction is active (an adapter is pinned in async-local storage),
+   * that adapter is returned for every call so the whole transaction is
+   * atomic on one connection. Otherwise pooled mode round-robins.
    */
   private getNextAdapter(): DatabaseAdapter {
+    const pinned = this.txStore.getStore()?.adapter;
+    if (pinned) return pinned;
+
     if (this._poolSize > 0) {
       const idx = this.poolIndex;
       this.poolIndex = (this.poolIndex + 1) % this._poolSize;
@@ -457,19 +482,37 @@ export class Database {
     }
   }
 
-  /** Start a transaction. */
+  /**
+   * Start a transaction. Pins the adapter to the current async context for
+   * the whole transaction so executes and the final commit/rollback all run
+   * on the same connection (critical when pool > 0).
+   */
   startTransaction(): void {
-    this.getNextAdapter().startTransaction();
+    // Pick an adapter using the normal selection logic, then pin it.
+    const adapter = this.getNextAdapter();
+    let store = this.txStore.getStore();
+    if (store) {
+      store.adapter = adapter;
+    } else {
+      this.txStore.enterWith({ adapter });
+    }
+    adapter.startTransaction();
   }
 
-  /** Commit the current transaction. */
+  /** Commit the current transaction and release the adapter pin. */
   commit(): void {
-    this.getNextAdapter().commit();
+    const adapter = this.getNextAdapter();
+    adapter.commit();
+    const store = this.txStore.getStore();
+    if (store) store.adapter = null;
   }
 
-  /** Rollback the current transaction. */
+  /** Rollback the current transaction and release the adapter pin. */
   rollback(): void {
-    this.getNextAdapter().rollback();
+    const adapter = this.getNextAdapter();
+    adapter.rollback();
+    const store = this.txStore.getStore();
+    if (store) store.adapter = null;
   }
 
   /** Check if a table exists. */
@@ -779,21 +822,21 @@ async function createAdapterFromUrl(url: string, username?: string, password?: s
 }
 
 /**
- * Initialize the database from a config object or DATABASE_URL env var.
+ * Initialize the database from a config object or TINA4_DATABASE_URL env var.
  * Now returns a Database wrapper instance.
  *
  * Priority:
  *   1. config.url (explicit URL)
- *   2. process.env.DATABASE_URL
+ *   2. process.env.TINA4_DATABASE_URL
  *   3. config.type + config.path (legacy)
  */
 export async function initDatabase(config?: DatabaseConfig): Promise<Database> {
-  // Resolve credentials: config.user > config.username > env DATABASE_USERNAME
-  const resolvedUser = config?.user ?? config?.username ?? process.env.DATABASE_USERNAME;
-  const resolvedPassword = config?.password ?? process.env.DATABASE_PASSWORD;
+  // Resolve credentials: config.user > config.username > env TINA4_DATABASE_USERNAME
+  const resolvedUser = config?.user ?? config?.username ?? process.env.TINA4_DATABASE_USERNAME;
+  const resolvedPassword = config?.password ?? process.env.TINA4_DATABASE_PASSWORD;
 
   // Resolve from URL if provided
-  const url = config?.url ?? process.env.DATABASE_URL;
+  const url = config?.url ?? process.env.TINA4_DATABASE_URL;
 
   if (url) {
     const adapter = await createAdapterFromUrl(url, resolvedUser, resolvedPassword);

package/packages/swagger/src/generator.ts

@@ -15,9 +15,9 @@ export function generate(
   const spec: OpenAPISpec = {
     openapi: "3.0.3",
     info: {
-      title: process.env.SWAGGER_TITLE ?? "Tina4 API",
-      version: "0.0.1",
-      description: "Auto-generated API documentation",
+      title: process.env.TINA4_SWAGGER_TITLE ?? "Tina4 API",
+      version: process.env.TINA4_SWAGGER_VERSION ?? "0.0.1",
+      description: process.env.TINA4_SWAGGER_DESCRIPTION ?? "Auto-generated API documentation",
     },
     paths: {},
     components: { schemas: {} },