tina4-nodejs 3.13.37 → 3.13.39

package/packages/core/src/logger.ts

@@ -100,7 +100,7 @@ const COLORS: Record<LogLevel, string> = {
 const RESET = "\x1b[0m";
 
 /** Regex to strip ANSI escape codes */
-const ANSI_RE = /\033\[[0-9;]*m/g;
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
 
 /** Default log directory */
 const DEFAULT_LOG_DIR = "logs";
@@ -136,18 +136,23 @@ function resolveLogFilePath(logDir: string, logFile: string): string {
 /**
  * Structured logger for Tina4.
  *
- * Production (TINA4_DEBUG not truthy): JSON or text lines to logs/tina4.log
- * Development (TINA4_DEBUG=true): Colorized human-readable to stdout + file
+ * Development (TINA4_DEBUG=true): colorized human-readable to stdout + file.
+ * Production (TINA4_DEBUG not truthy): clean structured JSON to stdout ONLY —
+ *   no log file by default (writing logs/tina4.log inside a container bloats the
+ *   writable layer + disk; 12-factor wants logs on stdout). stdout is ALWAYS on.
+ *
+ * Default file-output rule (TINA4_LOG_OUTPUT unset): the log FILE is written
+ * only in development. An explicit TINA4_LOG_OUTPUT=file/both, OR an explicit
+ * TINA4_LOG_FILE path, always forces a file (explicit wins).
  *
  * Env vars:
- *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Empty = use TINA4_LOG_DIR + tina4.log
+ *   TINA4_LOG_FILE          — explicit log file (absolute or relative). Setting it forces a file even in production. Empty = use TINA4_LOG_DIR + tina4.log
  *   TINA4_LOG_DIR           — directory for log files (default: "logs")
  *   TINA4_LOG_FORMAT        — "text" | "json" (default: "text")
- *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout")
- *   TINA4_LOG_CRITICAL      — "true" to enable CRITICAL level shortcut (default: "false")
+ *   TINA4_LOG_OUTPUT        — "stdout" | "file" | "both" (default: "stdout" → file only in dev)
  *   TINA4_LOG_ROTATE_SIZE   — bytes; 0 disables rotation (default: 10485760 = 10MB)
  *   TINA4_LOG_ROTATE_KEEP   — number of historical files to keep (default: 5)
- *   TINA4_LOG_LEVEL         — minimum console level (default: "DEBUG")
+ *   TINA4_LOG_LEVEL         — minimum console level: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
  *
  * Rotation is stdlib roll-your-own:
  *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
@@ -171,10 +176,11 @@ export class Log {
     minLevel: number;
     format: "text" | "json";
     output: "stdout" | "file" | "both";
-    criticalEnabled: boolean;
+    fileEnabled: boolean;
   } {
     const logDir = process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
-    const logFile = (process.env.TINA4_LOG_FILE ?? "").trim() || DEFAULT_LOG_FILE;
+    const explicitFile = (process.env.TINA4_LOG_FILE ?? "").trim();
+    const logFile = explicitFile || DEFAULT_LOG_FILE;
 
     const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
     let rotateSize = DEFAULT_ROTATE_SIZE;
@@ -203,9 +209,57 @@ export class Log {
     if (out === "file") output = "file";
     else if (out === "both") output = "both";
 
-    const criticalEnabled = isTruthy(process.env.TINA4_LOG_CRITICAL);
+    // v3.13.39: dev/prod-aware default file output (Python master, 4c6d881).
+    // When TINA4_LOG_OUTPUT is unset (default "stdout"), the log FILE is written
+    // only in development (TINA4_DEBUG truthy). In production / containers the
+    // logger is stdout-only — writing logs/tina4.log inside a container just
+    // bloats the writable layer + disk, and 12-factor wants logs on stdout for
+    // the platform to capture. Explicit TINA4_LOG_OUTPUT=file/both OR an explicit
+    // TINA4_LOG_FILE path always wins (explicit forces a file regardless of env).
+    let fileEnabled: boolean;
+    if (output === "file" || output === "both") {
+      fileEnabled = true;
+    } else if (explicitFile !== "") {
+      fileEnabled = true;
+    } else {
+      fileEnabled = !Log.isProduction();
+    }
+
+    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled };
+  }
+
+  /**
+   * The single console-threshold predicate: does a message at `level` clear
+   * the configured minimum console level? This is the ONE place level
+   * comparison lives — both the live log() gate and the public isEnabled()
+   * predicate call it, so they can never disagree about what actually prints.
+   */
+  private static passesThreshold(level: LogLevel, minLevel: number): boolean {
+    return (LEVEL_PRIORITY[level] ?? 0) >= minLevel;
+  }
 
-    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, criticalEnabled };
+  /**
+   * Return true if a message at `level` would pass the configured minimum
+   * console level (TINA4_LOG_LEVEL) — the same threshold that gates stdout.
+   *
+   * This reflects CONSOLE (stdout) visibility only. The log file always
+   * records every level regardless of this threshold, so don't use it to
+   * decide whether something gets persisted — use it to skip building an
+   * expensive payload that would not be shown:
+   *
+   *     if (Log.isEnabled("debug")) {
+   *       Log.debug("state", expensiveSnapshot());
+   *     }
+   *
+   * `level` is case-insensitive. "critical" is the highest severity (priority
+   * 4 > error 3) and flows through the ordinary threshold check like every
+   * other level — there is no toggle. It reuses the same passesThreshold()
+   * check the logger itself uses, so it never drifts from what print does.
+   */
+  static isEnabled(level: string): boolean {
+    const cfg = Log.readEnv();
+    const lvl = (level ?? "").toUpperCase() as LogLevel;
+    return Log.passesThreshold(lvl, cfg.minLevel);
   }
 
   /**
@@ -257,9 +311,12 @@ export class Log {
   }
 
   /**
-   * Log a critical message. Only emitted when TINA4_LOG_CRITICAL=true,
-   * otherwise this is a no-op (matches Python parity — critical is the
-   * highest-severity bucket and is opt-in to avoid drowning noisy apps).
+   * Log a critical message. CRITICAL is the highest severity (priority 4 >
+   * error 3) and ALWAYS emits like every other level — subject only to the
+   * console threshold, which it always passes at normal levels — and is always
+   * persisted to the log file (Node tees every level to a single tina4.log;
+   * critical 4 >= warning 2 so it would be in error.log on a split-file model).
+   * Matches Python master parity — there is no enable toggle.
    */
   static critical(message: string, data?: unknown): void {
     Log.log("CRITICAL", message, data);
@@ -355,9 +412,6 @@ export class Log {
   private static log(level: LogLevel, message: string, data?: unknown): void {
     const cfg = Log.readEnv();
 
-    // Critical level is opt-in; treat as no-op when disabled.
-    if (level === "CRITICAL" && !cfg.criticalEnabled) return;
-
     const entry: LogEntry = {
       timestamp: Log.timestamp(),
       level,
@@ -393,7 +447,7 @@ export class Log {
     const fileLine =
       cfg.format === "json" || Log.isProduction() ? JSON.stringify(entry) : humanLine;
 
-    const shouldLog = (LEVEL_PRIORITY[level] ?? 0) >= cfg.minLevel;
+    const shouldLog = Log.passesThreshold(level, cfg.minLevel);
 
     // Console output. v3.13.14: stdout is NOT suppressed in production —
     // containers read PID 1 stdout (docker logs / k8s) and the old
@@ -410,17 +464,20 @@ export class Log {
       }
     }
 
-    // File output: always teed for dev (legacy behaviour), and either always
-    // (production default) or honoured per output mode.
+    // File output (v3.13.39 — Python master, 4c6d881): gated on cfg.fileEnabled.
     //
-    //   output=stdout (default): file in dev + prod (legacy parity)
-    //   output=file              file only — no console
-    //   output=both              file + console (already handled above)
+    //   output=stdout (default): file ONLY in dev (TINA4_DEBUG truthy);
+    //                            production / containers are stdout-only — no
+    //                            file to bloat the writable layer / disk.
+    //   output=file              file only — no console (always writes a file)
+    //   output=both              file + console (always writes a file)
+    //   explicit TINA4_LOG_FILE  always writes a file (explicit wins)
     //
-    // The "stdout-only without file" mode that some Python deployments want
-    // is gated on TINA4_LOG_OUTPUT=stdout combined with TINA4_LOG_FILE set
-    // explicitly to an empty string in env — we treat empty file as default.
-    const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
-    Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
+    // readEnv() resolves all of the above into cfg.fileEnabled, so flipping
+    // that one flag gates the whole file writer (the only persisted sink).
+    if (cfg.fileEnabled) {
+      const filePath = resolveLogFilePath(cfg.logDir, cfg.logFile);
+      Log.writeToFile(filePath, fileLine, cfg.rotateSize, cfg.rotateKeep);
+    }
   }
 }

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

@@ -6,7 +6,7 @@ import {
   encodeResponse, encodeError, encodeNotification, decodeRequest,
   McpServer, isLocalhost, schemaFromParams, registerDevTools,
   PARSE_ERROR, METHOD_NOT_FOUND, INTERNAL_ERROR,
-} from "./mcp.ts";
+} from "./mcp.js";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";

package/packages/core/src/mcp.ts

@@ -202,18 +202,35 @@ function envTruthy(val: string | undefined): boolean {
 }
 
 /**
- * Whether the built-in MCP server should auto-start.
+ * Whether the built-in MCP dev tools / `/__dev/mcp` endpoint should be enabled.
  *
- * Default: `true` when `TINA4_DEBUG=true`, `false` otherwise. The `TINA4_MCP`
- * env var can force either state explicitly. Matches the Python framework
- * which only exposes MCP endpoints in dev mode by default.
+ * Resolution order (highest priority first), matching Python master
+ * `tina4_python.mcp.is_enabled()`:
+ *   1. `TINA4_MCP` — explicit on/off override, honoured on ANY host. An
+ *      explicit truthy value opts a remote / debug-disabled deployment in
+ *      (e.g. for a remote AI assistant); an explicit falsy value force-disables
+ *      it everywhere.
+ *   2. `TINA4_DEBUG=true` — implicit on for dev, but LOCALHOST-ONLY unless
+ *      `TINA4_MCP_REMOTE=true`. The MCP dev tools expose powerful operations
+ *      (DB query, file read/WRITE, route listing), so they never auto-expose on
+ *      a non-localhost host without an explicit opt-in.
+ *   3. Otherwise off.
+ *
+ * Wired in v3.13.39: previously this was `TINA4_MCP` else `TINA4_DEBUG`, with
+ * `isLocalhost()` unused for the gate and `TINA4_MCP_REMOTE` read by zero code
+ * — so the documented localhost guard was not actually enforced and a
+ * non-localhost `TINA4_DEBUG=true` deployment auto-exposed the dev tools.
  */
 export function mcpEnabled(): boolean {
-  const raw = process.env.TINA4_MCP;
-  if (raw === undefined || raw.trim() === "") {
-    return envTruthy(process.env.TINA4_DEBUG);
+  const explicit = process.env.TINA4_MCP;
+  if (explicit !== undefined && explicit.trim() !== "") {
+    return envTruthy(explicit);
+  }
+  if (!envTruthy(process.env.TINA4_DEBUG)) {
+    return false;
   }
-  return envTruthy(raw);
+  // Dev auto-enable: localhost only, unless explicitly opted into remote.
+  return isLocalhost() || envTruthy(process.env.TINA4_MCP_REMOTE);
 }
 
 /**

package/packages/core/src/messenger.ts

@@ -28,6 +28,19 @@ import tls from "node:tls";
 import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { randomUUID } from "node:crypto";
+import { isTruthy } from "./dotenv.js";
+import { Log } from "./logger.js";
+
+/**
+ * TLS certificate validation defaults to SECURE (rejectUnauthorized: true).
+ * Set TINA4_MAIL_TLS_INSECURE=true to disable validation for dev / self-signed
+ * certificates ONLY — never in production. Previously this was hard-coded to
+ * `rejectUnauthorized: false`, silently disabling certificate validation for
+ * every TLS connection (a man-in-the-middle risk).
+ */
+function tlsRejectUnauthorized(): boolean {
+  return !isTruthy(process.env.TINA4_MAIL_TLS_INSECURE);
+}
 
 // ── Types ────────────────────────────────────────────────────
 
@@ -37,6 +50,23 @@ export interface SendResult {
   id?: string;
 }
 
+/**
+ * Raised when an IMAP read fails to connect, authenticate, or speak the
+ * protocol (a `NO`/`BAD` tagged response, a refused/reset socket, a TLS or
+ * DNS failure). Distinct from a SUCCESSFUL fetch that simply has no messages —
+ * that still returns an empty result ([] / 0 / {}), NOT an error.
+ *
+ * inbox()/read()/unread()/search()/folders() LOG and then RAISE this on a
+ * connection/protocol failure so a dead mailbox is never silently mistaken for
+ * an empty one. send() is unchanged — it keeps returning { success, error }.
+ */
+export class MessengerConnectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MessengerConnectionError";
+  }
+}
+
 export interface EmailMessage {
   id: string;
   type: "inbox" | "outbox";
@@ -402,7 +432,7 @@ export class Messenger {
 
       if (this.port === 465) {
         // Implicit TLS (SMTPS)
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: false });
+        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
         await new Promise<void>((resolve, reject) => {
           socket.once("secureConnect", resolve);
           socket.once("error", reject);
@@ -440,7 +470,7 @@ export class Messenger {
         // Upgrade to TLS
         const plainSocket = socket as net.Socket;
         socket = tls.connect(
-          { socket: plainSocket, host: this.host, rejectUnauthorized: false },
+          { socket: plainSocket, host: this.host, rejectUnauthorized: tlsRejectUnauthorized() },
         );
         await new Promise<void>((resolve, reject) => {
           (socket as tls.TLSSocket).once("secureConnect", resolve);
@@ -541,7 +571,7 @@ export class Messenger {
       let socket: net.Socket | tls.TLSSocket;
 
       if (this.port === 465) {
-        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: false });
+        socket = tls.connect({ host: this.host, port: this.port, rejectUnauthorized: tlsRejectUnauthorized() });
         await new Promise<void>((resolve, reject) => {
           socket.once("secureConnect", resolve);
           socket.once("error", reject);
@@ -595,7 +625,7 @@ export class Messenger {
       || (this.imapEncryption === "" && this.imapPort === 993);
 
     if (useTls) {
-      socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: false });
+      socket = tls.connect({ host: this.imapHost, port: this.imapPort, rejectUnauthorized: tlsRejectUnauthorized() });
       await new Promise<void>((resolve, reject) => {
         socket.once("secureConnect", resolve);
         socket.once("error", reject);
@@ -638,7 +668,12 @@ export class Messenger {
    * Returns list of message summaries.
    */
   async inbox(limit: number = 20, offset: number = 0, folder: string = "INBOX"): Promise<ImapMessage[]> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("inbox", err);
+    }
     try {
       // Select folder
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
@@ -660,6 +695,8 @@ export class Messenger {
       }
 
       return messages;
+    } catch (err) {
+      throw imapFail("inbox", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -669,15 +706,28 @@ export class Messenger {
    * Read a single message by sequence number or UID.
    */
   async read(uid: string, folder: string = "INBOX"): Promise<ImapFullMessage> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("read", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const fetchResp = await imapCommand(socket, `FETCH ${uid} (FLAGS BODY[])`);
 
+      // A genuinely missing UID is a tagged OK with no message body literal —
+      // that is NOT an error: return an empty message (parity with Python's {}).
+      if (!/\{\d+\}/.test(fetchResp)) {
+        return emptyFullMessage(uid);
+      }
+
       // Mark as seen
       await imapCommand(socket, `STORE ${uid} +FLAGS (\\Seen)`);
 
       return parseFullMessage(uid, fetchResp);
+    } catch (err) {
+      throw imapFail("read", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -704,7 +754,12 @@ export class Messenger {
     if (unseenOnly) criteria.push("UNSEEN");
 
     const query = criteria.join(" ");
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("search", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const searchResp = await imapCommand(socket, `SEARCH ${query}`);
@@ -718,6 +773,8 @@ export class Messenger {
         messages.push(parseHeaderResponse(uid, fetchResp));
       }
       return messages;
+    } catch (err) {
+      throw imapFail("search", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -754,11 +811,18 @@ export class Messenger {
    * Count unseen messages in a folder.
    */
   async unread(folder: string = "INBOX"): Promise<number> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("unread", err);
+    }
     try {
       await imapCommand(socket, `SELECT ${imapQuote(folder)}`);
       const searchResp = await imapCommand(socket, "SEARCH UNSEEN");
       return parseSearchResponse(searchResp).length;
+    } catch (err) {
+      throw imapFail("unread", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -768,7 +832,12 @@ export class Messenger {
    * List available IMAP folders/mailboxes.
    */
   async folders(): Promise<string[]> {
-    const socket = await this.imapConnect();
+    let socket: net.Socket | tls.TLSSocket;
+    try {
+      socket = await this.imapConnect();
+    } catch (err) {
+      throw imapFail("folders", err);
+    }
     try {
       const resp = await imapCommand(socket, 'LIST "" "*"');
       const result: string[] = [];
@@ -778,6 +847,8 @@ export class Messenger {
         if (m) result.push(m[1]);
       }
       return result;
+    } catch (err) {
+      throw imapFail("folders", err);
     } finally {
       await this.imapDisconnect(socket);
     }
@@ -840,11 +911,20 @@ function imapCommand(socket: net.Socket | tls.TLSSocket, command: string): Promi
     let buffer = "";
     const onData = (chunk: Buffer) => {
       buffer += chunk.toString("utf-8");
-      // Look for tagged response line indicating completion
-      if (buffer.includes(`${tag} OK`) || buffer.includes(`${tag} NO`) || buffer.includes(`${tag} BAD`)) {
+      // Tagged OK = success.
+      if (buffer.includes(`${tag} OK`)) {
         socket.removeListener("data", onData);
         socket.removeListener("error", onError);
         resolve(buffer);
+        return;
+      }
+      // Tagged NO / BAD = protocol failure — fail loud (mirrors Python's
+      // non-OK status raise). A genuinely empty mailbox is a tagged OK with an
+      // empty SEARCH result, which still resolves above.
+      if (buffer.includes(`${tag} NO`) || buffer.includes(`${tag} BAD`)) {
+        socket.removeListener("data", onData);
+        socket.removeListener("error", onError);
+        reject(new MessengerConnectionError(`IMAP command failed: ${command.split(" ")[0]} → ${buffer.trim()}`));
       }
     };
 
@@ -859,6 +939,17 @@ function imapCommand(socket: net.Socket | tls.TLSSocket, command: string): Promi
   });
 }
 
+/**
+ * Log an IMAP connection/protocol failure and return the error to throw.
+ * A genuinely empty mailbox is NOT an error and never reaches here.
+ */
+function imapFail(method: string, err: unknown): MessengerConnectionError {
+  const e = err instanceof Error ? err : new Error(String(err));
+  Log.error(`Messenger IMAP ${method}() failed: ${e.name}: ${e.message}`);
+  if (e instanceof MessengerConnectionError) return e;
+  return new MessengerConnectionError(`IMAP ${method} failed: ${e.message}`);
+}
+
 function parseSearchResponse(response: string): string[] {
   // SEARCH response: * SEARCH 1 2 3 4 5
   const match = response.match(/\* SEARCH (.+)/);
@@ -898,6 +989,15 @@ function parseHeaderResponse(uid: string, response: string): ImapMessage {
   };
 }
 
+/**
+ * An empty full message — returned when a FETCH succeeds (tagged OK) but the
+ * UID does not exist, so there is no message body. Mirrors Python's {} return:
+ * a missing UID is NOT an error.
+ */
+function emptyFullMessage(uid: string): ImapFullMessage {
+  return { uid, subject: "", from: "", to: "", cc: "", date: "", bodyText: "", bodyHtml: "", headers: {} };
+}
+
 function parseFullMessage(uid: string, response: string): ImapFullMessage {
   // Extract the raw message body from FETCH response
   const bodyMatch = response.match(/\{(\d+)\}\r\n([\s\S]*)/);