tina4-nodejs 3.13.36 → 3.13.38

package/packages/core/src/auth.ts

@@ -12,7 +12,117 @@
  *   checkPassword("secret123", hash);  // true
  */
 import { createHmac, createSign, createVerify, pbkdf2Sync, randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { Middleware, Tina4Request, Tina4Response } from "./types.js";
+import { isTruthy } from "./dotenv.js";
+
+// ── Blank-secret warning + dev-secret bootstrap ────────────────────
+//
+// Mirrors the Python master (tina4_python/auth/__init__.py):
+//   • The default signing secret stays BLANK — never a guessable built-in.
+//   • In DEV (not CI, not production) a blank secret is auto-generated once and
+//     persisted to a gitignored .env.local, so a local dev never has to be told
+//     what to set. INFO, not a warning.
+//   • In CI / production a blank secret keeps the loud, ACTIONABLE warning.
+
+/** Actionable blank-secret warning — emitted from both the bootstrap (CI/prod) and the lazy resolvers. */
+const BLANK_SECRET_WARNING =
+  "Auth: TINA4_SECRET is not set — JWT signing is insecure. Set TINA4_SECRET to a random " +
+  "value (e.g. `openssl rand -hex 32`) in your environment or .env before serving traffic.";
+
+/** True when running under CI — the de-facto `CI` env var (set by every major CI). */
+function _isCi(): boolean {
+  return isTruthy(process.env.CI);
+}
+
+/** True in development — the framework debug flag is truthy (e.g. TINA4_DEBUG=true). */
+function _isDev(): boolean {
+  return isTruthy(process.env.TINA4_DEBUG);
+}
+
+/** True when TINA4_ENV is explicitly "production". */
+function _isProduction(): boolean {
+  return (process.env.TINA4_ENV ?? "development") === "production";
+}
+
+/** INFO log via Tina4 Log when available, else stderr. (Local import avoids a load-time cycle.) */
+async function _logInfo(message: string): Promise<void> {
+  try {
+    const { Log } = await import("./logger.js");
+    Log.info(message);
+  } catch {
+    process.stderr.write(message + "\n");
+  }
+}
+
+/** WARNING log via Tina4 Log when available, else stderr. */
+async function _logWarning(message: string): Promise<void> {
+  try {
+    const { Log } = await import("./logger.js");
+    Log.warning(message);
+  } catch {
+    process.stderr.write(message + "\n");
+  }
+}
+
+/** Emit the shared, actionable blank-secret warning (used by CI/prod bootstrap + lazy resolvers). */
+function _warnBlankSecret(): void {
+  void _logWarning(BLANK_SECRET_WARNING);
+}
+
+/**
+ * Ensure a usable TINA4_SECRET exists. Run ONCE at server boot, after env load
+ * and before auth is used. Mirrors Python's `ensure_dev_secret()`.
+ *
+ * Order:
+ *   1. TINA4_SECRET already set → no-op (return null).
+ *   2. NOT dev, OR CI, OR production → emit the actionable warning, return null.
+ *      NEVER generates or persists a secret in CI / production / non-dev.
+ *   3. Otherwise (dev, not CI, not prod, blank secret) → generate a 32-byte hex
+ *      secret, set it in process.env for THIS run immediately, then try to append
+ *      it to <cwd>/.env.local (create if missing; never touch .env). On a write
+ *      failure keep the in-memory secret and warn — boot must never crash.
+ *
+ * @param cwd - Directory to write .env.local into. Tests pass a temp dir; production passes nothing.
+ * @returns The newly-generated secret, or null when nothing was generated.
+ */
+export function ensureDevSecret(cwd?: string): string | null {
+  if (process.env.TINA4_SECRET) return null; // already configured
+
+  // Only the dev-and-not-CI-and-not-production path may generate / persist.
+  if (!_isDev() || _isCi() || _isProduction()) {
+    _warnBlankSecret();
+    return null;
+  }
+
+  // 32 bytes hex = 64 hex chars (parity with Python's secrets.token_hex(32)).
+  const newSecret = randomBytes(32).toString("hex");
+  // Set immediately so it's available for this run even if the write fails.
+  process.env.TINA4_SECRET = newSecret;
+
+  const baseDir = cwd ?? process.cwd();
+  const envLocalPath = join(baseDir, ".env.local");
+  try {
+    // If the file exists and its content doesn't end in a newline, prepend one
+    // so the new key lands on its own line.
+    let prefix = "";
+    if (existsSync(envLocalPath)) {
+      const existing = readFileSync(envLocalPath, "utf-8");
+      if (existing.length > 0 && !existing.endsWith("\n")) prefix = "\n";
+    }
+    appendFileSync(envLocalPath, `${prefix}TINA4_SECRET=${newSecret}\n`);
+    void _logInfo("Auth: generated a development secret, saved to .env.local (gitignored)");
+  } catch {
+    // Keep the in-memory secret for this run; warn but never crash boot.
+    void _logWarning(
+      "Auth: generated a development secret but could not write .env.local — " +
+        "using it in-memory for this run only.",
+    );
+  }
+
+  return newSecret;
+}
 
 // ── Base64url helpers (RFC 7515) ──────────────────────────────────
 
@@ -58,7 +168,7 @@ export function getToken(
   }
 
   if (!resolvedSecret) {
-    console.warn("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)");
+    _warnBlankSecret();
   }
   const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
 
@@ -95,7 +205,7 @@ export function getToken(
 export function validToken(token: string, secret?: string, algorithm?: string): Record<string, unknown> | null {
   const resolvedSecret = secret ?? process.env.TINA4_SECRET ?? "";
   if (!resolvedSecret) {
-    console.warn("Auth: TINA4_SECRET not set in .env — using blank secret (insecure)");
+    _warnBlankSecret();
   }
   const resolvedAlgorithm = algorithm ?? process.env.TINA4_JWT_ALGORITHM ?? "HS256";
   try {

package/packages/core/src/cache.ts

@@ -247,7 +247,7 @@ class RespClient {
   private username: string | null;
   private password: string | null;
   private sock: net.Socket | null = null;
-  private buffer = Buffer.alloc(0);
+  private buffer: Buffer = Buffer.alloc(0);
   private waiters: Array<{ resolve: (r: RespReply) => void; reject: (e: Error) => void }> = [];
   private connecting: Promise<void> | null = null;
   private connected = false;
@@ -662,7 +662,7 @@ class MemcachedClient {
   private host: string;
   private port: number;
   private sock: net.Socket | null = null;
-  private buffer = Buffer.alloc(0);
+  private buffer: Buffer = Buffer.alloc(0);
   private pending: { terminator: string; resolve: (s: string) => void } | null = null;
   private connecting: Promise<void> | null = null;
   private connected = false;

package/packages/core/src/devAdmin.ts

@@ -1041,8 +1041,16 @@ const handleTables: RouteHandler = async (_req, res) => {
 
 const handleSeed: RouteHandler = async (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost");
-  const table = url.searchParams.get("table") ?? (req as any).body?.table ?? "";
-  const count = parseInt(String(url.searchParams.get("count") ?? (req as any).body?.count ?? "10"), 10) || 10;
+  const body = (req as any).body ?? {};
+  const table = url.searchParams.get("table") ?? body?.table ?? "";
+  const count = parseInt(String(url.searchParams.get("count") ?? body?.count ?? "10"), 10) || 10;
+  // P4b — accept seed/clear/strict; drop the previous hard-coded behaviour.
+  const seedRaw = url.searchParams.get("seed") ?? body?.seed;
+  const seed = seedRaw !== undefined && seedRaw !== null && String(seedRaw) !== ""
+    ? (Number.isNaN(parseInt(String(seedRaw), 10)) ? undefined : parseInt(String(seedRaw), 10))
+    : undefined;
+  const clear = String(url.searchParams.get("clear") ?? body?.clear ?? "") === "true" || body?.clear === true;
+  const strict = String(url.searchParams.get("strict") ?? body?.strict ?? "") === "true" || body?.strict === true;
   if (!table) {
     res.json({ error: "Missing table parameter" });
     return;
@@ -1051,43 +1059,36 @@ const handleSeed: RouteHandler = async (req, res) => {
     const orm = await import("@tina4/orm");
     const db = orm.getAdapter();
     const { seedTable } = orm;
-    const fake = new orm.FakeData();
+    // A shared FakeData seeds the RNG so a `seed` makes the run reproducible.
+    const fake = new orm.FakeData(seed);
     const columns = db.columns(table);
     if (!columns.length) {
       res.json({ error: `Table '${table}' not found or has no columns` });
       return;
     }
-    // Build a field map based on column info
+    // Build a field map based on column info (skip auto-increment/id PKs).
     const fieldMap: Record<string, () => unknown> = {};
     for (const col of columns) {
       const name = col.name.toLowerCase();
       const type = col.type.toLowerCase();
-      if (name === "id") continue; // skip primary key
+      if (name === "id" || (col as any).primaryKey === true) continue; // skip primary key
       if (name.includes("email")) { fieldMap[col.name] = () => fake.email(); }
       else if (name.includes("name")) { fieldMap[col.name] = () => fake.name(); }
       else if (name.includes("phone")) { fieldMap[col.name] = () => fake.phone(); }
       else if (name.includes("address") || name.includes("city") || name.includes("country")) { fieldMap[col.name] = () => fake.address(); }
       else if (name.includes("url") || name.includes("website")) { fieldMap[col.name] = () => fake.url(); }
       else if (type.includes("int")) { fieldMap[col.name] = () => fake.integer(1, 1000); }
-      else if (type.includes("real") || type.includes("float") || type.includes("double") || type.includes("numeric") || type.includes("decimal")) { fieldMap[col.name] = () => fake.decimal(0, 1000, 2); }
+      else if (type.includes("real") || type.includes("float") || type.includes("double") || type.includes("numeric") || type.includes("decimal")) { fieldMap[col.name] = () => fake.numeric(0, 1000, 2); }
       else if (type.includes("bool")) { fieldMap[col.name] = () => fake.boolean(); }
       else if (type.includes("date") || type.includes("time")) { fieldMap[col.name] = () => fake.date(); }
       else { fieldMap[col.name] = () => fake.sentence(3); }
     }
-    let inserted = 0;
-    for (let i = 0; i < count; i++) {
-      const row: Record<string, unknown> = {};
-      for (const [col, gen] of Object.entries(fieldMap)) {
-        row[col] = gen();
-      }
-      try {
-        db.insert(table, row);
-        inserted++;
-      } catch { /* skip failed rows */ }
-    }
-    res.json({ inserted, table });
-  } catch {
-    res.json({ error: "Database not connected" });
+    // P1 — delegate to the shared seedTable so each row is wrapped (no
+    // unhandled failure can crash the endpoint) and we get a summary back.
+    const summary = await seedTable(db, table, count, fieldMap, undefined, { clear, seed, strict });
+    res.json({ seeded: summary.seeded, failed: summary.failed, errors: summary.errors, table });
+  } catch (e) {
+    res.json({ error: (e as Error)?.message ?? "Database not connected" });
   }
 };
 
@@ -1495,20 +1496,24 @@ const handleConnectionsTest: RouteHandler = async (req, res) => {
     } catch { tableCount = 0; }
     try {
       const urlLower = url.toLowerCase();
+      // NOTE: db.execute() is async; these calls are intentionally left
+      // un-awaited to preserve the exact existing runtime behaviour during
+      // this type-only cleanup. `row` is therefore a Promise and the `as any`
+      // access below evaluates to the fallback string. See report open question.
       if (urlLower.includes("sqlite")) {
-        const row = db.execute("SELECT sqlite_version() as v") as Record<string, unknown>[] | undefined;
+        const row = db.execute("SELECT sqlite_version() as v");
         version = `SQLite ${(row as any)?.[0]?.v ?? ""}`;
       } else if (urlLower.includes("postgres")) {
-        const row = db.execute("SELECT version() as v") as Record<string, unknown>[] | undefined;
+        const row = db.execute("SELECT version() as v");
         version = ((row as any)?.[0]?.v ?? "PostgreSQL").toString().split(",")[0];
       } else if (urlLower.includes("mysql")) {
-        const row = db.execute("SELECT version() as v") as Record<string, unknown>[] | undefined;
+        const row = db.execute("SELECT version() as v");
         version = `MySQL ${(row as any)?.[0]?.v ?? ""}`;
       } else if (urlLower.includes("mssql")) {
-        const row = db.execute("SELECT @@VERSION as v") as Record<string, unknown>[] | undefined;
+        const row = db.execute("SELECT @@VERSION as v");
         version = ((row as any)?.[0]?.v ?? "MSSQL").toString().split("\n")[0];
       } else if (urlLower.includes("firebird")) {
-        const row = db.execute("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') as v FROM rdb$database") as Record<string, unknown>[] | undefined;
+        const row = db.execute("SELECT rdb$get_context('SYSTEM', 'ENGINE_VERSION') as v FROM rdb$database");
         version = `Firebird ${(row as any)?.[0]?.v ?? ""}`;
       }
     } catch { /* keep version as Connected */ }
@@ -1904,6 +1909,49 @@ const handleFiles: RouteHandler = async (req, res) => {
   res.json({ path: relative(root, target).replace(/\\/g, "/") || ".", branch, entries });
 };
 
+// Canonical extension→language map. Kept identical in coverage to the Python
+// master (tina4_python/tina4_python/dev_admin/__init__.py `lang_map`) and the
+// PHP/Ruby file-read endpoints. The dev-admin SPA maps the returned "language"
+// string to a CodeMirror grammar for syntax highlighting.
+const DEV_ADMIN_LANG_MAP: Record<string, string> = {
+  ".py": "python", ".php": "php", ".rb": "ruby",
+  ".ts": "typescript", ".js": "javascript", ".jsx": "javascript",
+  ".tsx": "typescript", ".json": "json", ".html": "html",
+  ".twig": "html", ".css": "css", ".scss": "css",
+  ".md": "markdown", ".sql": "sql", ".yaml": "yaml",
+  ".yml": "yaml", ".toml": "toml", ".xml": "html",
+  ".env": "env", ".env.example": "env",
+  ".sh": "shell", ".bash": "shell",
+  ".bat": "shell", ".cmd": "shell", ".ps1": "shell",
+  ".rs": "rust", ".go": "go", ".java": "java",
+  ".txt": "text", ".csv": "text", ".log": "text",
+  ".gemspec": "ruby", ".rake": "ruby",
+  ".svg": "svg",
+};
+
+/**
+ * Resolve a CodeMirror-friendly language id from a file path's basename.
+ *
+ * - `Dockerfile` / `Dockerfile.dev` / `Dockerfile.prod` (no extension) → "dockerfile"
+ * - `.env.example` (two-part) and `.env` → "env"
+ * - otherwise the file extension is looked up in DEV_ADMIN_LANG_MAP
+ * - anything unknown → "text"
+ */
+export function devAdminLanguage(rel: string): string {
+  const base = (rel.split(/[\\/]/).pop() ?? "").toLowerCase();
+  if (base === "dockerfile" || base === "dockerfile.dev" || base === "dockerfile.prod") {
+    return "dockerfile";
+  }
+  // Two-part extension first (e.g. ".env.example"), then the single extension.
+  if (base.endsWith(".env.example")) return DEV_ADMIN_LANG_MAP[".env.example"];
+  const dot = base.lastIndexOf(".");
+  // A leading dot with no other dot is a dotfile name, not an extension
+  // (e.g. ".env" → ext ".env"); only treat as "no extension" when there's no dot.
+  if (dot < 0) return "text";
+  const ext = base.slice(dot);
+  return DEV_ADMIN_LANG_MAP[ext] ?? "text";
+}
+
 const handleFileRead: RouteHandler = (req, res) => {
   const url = new URL(req.url ?? "/", "http://localhost");
   const rel = url.searchParams.get("path") ?? "";
@@ -1915,7 +1963,8 @@ const handleFileRead: RouteHandler = (req, res) => {
   }
   try {
     const content = readFileSync(target, "utf-8");
-    res.json({ path: relative(root, target), content, bytes: Buffer.byteLength(content, "utf-8") });
+    const path = relative(root, target);
+    res.json({ path, content, language: devAdminLanguage(path), bytes: Buffer.byteLength(content, "utf-8") });
   } catch (e) {
     res.json({ error: (e as Error).message }, 500);
   }

package/packages/core/src/devMailbox.ts

@@ -296,6 +296,10 @@ export function createMessenger(): Messenger | DevMailbox {
   const debug = process.env.TINA4_DEBUG;
   const smtpHost = process.env.TINA4_MAIL_HOST;
 
+  // Production = NOT debug mode AND NODE_ENV is "production".
+  // Derived here (was previously referenced undefined → ReferenceError).
+  const isProd = !isTruthy(debug) && process.env.NODE_ENV === "production";
+
   // Force dev mode when TINA4_DEBUG is truthy
   if (isTruthy(debug)) {
     return new DevMailbox();

package/packages/core/src/dotenv.ts

@@ -74,17 +74,26 @@ function parseEnvContent(content: string): Record<string, string> {
 
 /**
  * Load environment variables from a .env file into process.env.
- * Does not override existing process.env values unless they are undefined.
+ *
+ * By default does NOT override existing process.env values — it is first-wins:
+ * a key is only set if it is not already present. This is how real env vars
+ * always win. To get the precedence real-env > `.env.local` > `.env`, load
+ * `.env.local` FIRST then `.env`, both with override=false (the default): the
+ * real env (already present) wins over both, `.env.local` fills local-only keys,
+ * and `.env` fills the rest. Do NOT load `.env.local` with override=true — that
+ * would let a stray gitignored `.env.local` clobber an explicitly set real env
+ * var (e.g. a production TINA4_SECRET).
  *
  * Resolution order for the env file path:
  *   1. Explicit `path` argument
  *   2. `TINA4_ENV_FILE` env var (if set and non-empty)
  *   3. `.env` in the current working directory
  *
- * @param path - Path to the .env file. Optional override.
+ * @param path     - Path to the .env file. Optional override.
+ * @param override - When true, overwrite keys already present in process.env.
  * @returns The parsed key-value pairs, or an empty object if the file doesn't exist.
  */
-export function loadEnv(path?: string): Record<string, string> {
+export function loadEnv(path?: string, override = false): Record<string, string> {
   const fromEnv = (process.env.TINA4_ENV_FILE ?? "").trim();
   const target = path ?? (fromEnv.length > 0 ? fromEnv : ".env");
   const envPath = resolve(target);
@@ -97,7 +106,7 @@ export function loadEnv(path?: string): Record<string, string> {
   const parsed = parseEnvContent(content);
 
   for (const [key, value] of Object.entries(parsed)) {
-    if (process.env[key] === undefined) {
+    if (override || process.env[key] === undefined) {
       process.env[key] = value;
       _loadedKeys.push(key);
     }

package/packages/core/src/events.ts

@@ -11,6 +11,8 @@
  *   Events.once("app.ready", () => console.log("App started!"));
  */
 
+import { Log } from "./logger.js";
+
 interface ListenerEntry {
     priority: number;
     callback: (...args: unknown[]) => void;
@@ -19,6 +21,50 @@ interface ListenerEntry {
 
 const _listeners: Map<string, ListenerEntry[]> = new Map();
 
+/**
+ * Log a listener error — NEVER silent. Mirrors Python's _log_listener_error:
+ * routes through the Tina4 Log (warning) with BOTH the event name and the
+ * error type + message. The log call is itself wrapped so a broken logger
+ * can't break the event bus — on any logger failure it falls back to
+ * console.error so the error is still surfaced.
+ */
+function logListenerError(event: string, error: unknown): void {
+    const err = error as { name?: string; message?: string };
+    const type = err?.name ?? (error as object)?.constructor?.name ?? "Error";
+    const message = err?.message ?? String(error);
+    try {
+        Log.warning(`Event listener for '${event}' raised ${type}: ${message}`);
+    } catch {
+        try {
+            console.error(`Event listener for '${event}' raised ${type}: ${message}`);
+        } catch {
+            /* a broken console can't break the bus either */
+        }
+    }
+}
+
+/**
+ * Mirror Python's keyword-only `strict` param within JS's positional-args
+ * model. If the FIRST emit argument is a plain options object carrying a
+ * boolean `strict`, it is consumed as the option and the remaining args are
+ * the event payload; otherwise every arg is treated as payload (so the
+ * common `emit("evt", a, b)` call is unchanged). Listeners never see the
+ * options object.
+ */
+function parseEmitArgs(rest: unknown[]): { strict: boolean; args: unknown[] } {
+    const first = rest[0];
+    if (
+        first !== null &&
+        typeof first === "object" &&
+        !Array.isArray(first) &&
+        Object.prototype.hasOwnProperty.call(first, "strict") &&
+        typeof (first as { strict?: unknown }).strict === "boolean"
+    ) {
+        return { strict: (first as { strict: boolean }).strict, args: rest.slice(1) };
+    }
+    return { strict: false, args: rest };
+}
+
 function getEntries(event: string): ListenerEntry[] {
     let entries = _listeners.get(event);
     if (!entries) {
@@ -68,8 +114,24 @@ export class Events {
 
     /**
      * Fire an event synchronously. Returns array of listener results.
+     *
+     * Listener isolation (E1): each listener call is wrapped — a listener
+     * that THROWS does NOT abort the rest of emit(). The error is LOGGED
+     * (never silent) and the failed listener contributes a `null` slot, so
+     * N listeners always yield N results in priority order; surviving
+     * listeners run regardless of an earlier throw.
+     *
+     * Pass `{ strict: true }` to RE-RAISE on the first listener error
+     * instead of isolating it (later listeners then do NOT run).
+     *
+     * once() cleanup stays correct under isolation: the one-shot listener is
+     * spliced out BEFORE its callback runs, so a throw never leaves it
+     * registered.
      */
-    static emit(event: string, ...args: unknown[]): unknown[] {
+    static emit(event: string, ...args: unknown[]): unknown[];
+    static emit(event: string, options: { strict?: boolean }, ...args: unknown[]): unknown[];
+    static emit(event: string, ...rest: unknown[]): unknown[] {
+        const { strict, args } = parseEmitArgs(rest);
         const entries = _listeners.get(event);
         if (!entries) return [];
 
@@ -81,7 +143,13 @@ export class Events {
                 const idx = entries.indexOf(entry);
                 if (idx !== -1) entries.splice(idx, 1);
             }
-            results.push(entry.callback(...args));
+            try {
+                results.push(entry.callback(...args));
+            } catch (error) {
+                if (strict) throw error;
+                logListenerError(event, error);
+                results.push(null);
+            }
         }
 
         return results;
@@ -90,8 +158,16 @@ export class Events {
     /**
      * Emit an event and await all async listeners.
      * Returns array of resolved results from each listener.
+     *
+     * Listener isolation (E1): identical to emit() — each awaited listener
+     * is isolated; a rejection/throw is LOGGED and contributes a `null`
+     * slot without aborting the others. `{ strict: true }` re-raises on the
+     * first error.
      */
-    static async emitAsync(event: string, ...args: unknown[]): Promise<unknown[]> {
+    static async emitAsync(event: string, ...args: unknown[]): Promise<unknown[]>;
+    static async emitAsync(event: string, options: { strict?: boolean }, ...args: unknown[]): Promise<unknown[]>;
+    static async emitAsync(event: string, ...rest: unknown[]): Promise<unknown[]> {
+        const { strict, args } = parseEmitArgs(rest);
         const entries = _listeners.get(event);
         if (!entries) return [];
 
@@ -103,7 +179,13 @@ export class Events {
                 const idx = entries.indexOf(entry);
                 if (idx !== -1) entries.splice(idx, 1);
             }
-            results.push(await entry.callback(...args));
+            try {
+                results.push(await entry.callback(...args));
+            } catch (error) {
+                if (strict) throw error;
+                logListenerError(event, error);
+                results.push(null);
+            }
         }
 
         return results;