tina4-nodejs 3.13.94 → 3.13.95

package/packages/core/src/logger.ts

@@ -128,6 +128,66 @@ function stripAnsi(text: string): string {
  *
  * Otherwise the directory is `TINA4_LOG_DIR` and filename is `tina4.log`.
  */
+// The logger must never be surprised by what it is handed, and must never be
+// the reason a request dies. Same numbers in all four frameworks (feature 2).
+const STDOUT_MAX_CHARS = 2000;
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g;
+
+/**
+ * Turn anything into a single safe line of text.
+ *
+ * A string passes through. A Buffer is decoded when it is valid UTF-8 and
+ * described when it is not: raw bytes at a terminal garble it and can emit
+ * escape sequences. Anything else becomes JSON, because an object rendered as
+ * text is the whole reason the caller logged it, falling back to String() for a
+ * value JSON cannot represent (a circular reference, a BigInt). Without this an
+ * object logged as a message reached the output as "[object Object]".
+ */
+function coerceMessage(message: unknown): string {
+  let text: string;
+  if (typeof message === "string") {
+    text = message;
+  } else if (message instanceof Uint8Array) {
+    const decoded = new TextDecoder("utf-8", { fatal: false }).decode(message);
+    text = decoded.includes("�") ? `<binary ${message.byteLength} bytes>` : decoded;
+  } else if (message === null || message === undefined) {
+    text = "";
+  } else if (typeof message === "object") {
+    try {
+      text = JSON.stringify(message) ?? String(message);
+    } catch {
+      text = String(message);
+    }
+  } else {
+    text = String(message);
+  }
+  return text.replace(CONTROL_CHARS, "");
+}
+
+/** Cap a console line. The file keeps the whole thing; a terminal does not. */
+function truncateForStdout(line: string): string {
+  if (line.length <= STDOUT_MAX_CHARS) return line;
+  return `${line.slice(0, STDOUT_MAX_CHARS)}... (truncated, ${line.length} chars)`;
+}
+
+/**
+ * Is this target a FILE PATH or a DIRECTORY?
+ *
+ * An existing directory is always a directory, extension or not. Otherwise a
+ * basename with an extension (app.log, app.txt) is a file and anything else is
+ * a directory to create. That keeps `configure("/var/log/myapp")` a directory
+ * and `configure("/var/log/myapp/app.log")` a file without the path needing to
+ * exist yet. Identical rule in all four frameworks.
+ */
+function targetIsFile(path: string): boolean {
+  try {
+    if (existsSync(path) && statSync(path).isDirectory()) return false;
+  } catch { /* fall through to the extension test */ }
+  const base = path.split(/[\\/]/).pop() ?? "";
+  return base.includes(".") && !base.startsWith(".");
+}
+
 function resolveLogFilePath(logDir: string, logFile: string): string {
   if (isAbsolute(logFile)) return logFile;
   return join(logDir, logFile);
@@ -136,23 +196,36 @@ function resolveLogFilePath(logDir: string, logFile: string): string {
 /**
  * Structured logger for Tina4.
  *
- * 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.
+ * FORMAT IS TEXT BY DEFAULT, and TINA4_LOG_FORMAT=json is the ONLY thing that
+ * selects JSON. Nothing else may. Until 3.13.95 an unset TINA4_DEBUG silently
+ * flipped BOTH sinks to JSON here, and "production" meant four different things
+ * across the four frameworks (Node: !TINA4_DEBUG; Ruby: TINA4_ENV/RACK_ENV/
+ * RUBY_ENV == "production"; Python: only configure(production=True); PHP: no
+ * switch at all, JSON always) — same machine, same .env, four log formats. That
+ * implicit switch is deleted; an object passed as the message is still
+ * JSON-encoded INLINE inside the text line, which is the only JSON a default
+ * install emits.
+ *
+ * TINA4_DEBUG still decides COLOUR — a terminal concern, not a format one — so
+ * a production pipe gets clean uncoloured bytes and a dev terminal stays
+ * readable.
  *
  * 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).
+ * TINA4_LOG_FILE path, always forces a file (explicit wins). stdout is ALWAYS on.
  *
  * Env vars:
  *   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_FORMAT        — "text" | "json" (default: "text") — the ONLY format switch
  *   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: DEBUG | INFO | WARNING | ERROR | CRITICAL (default: "INFO")
+ *   TINA4_LOG_STRICT        — truthy: a log-write failure THROWS instead of being swallowed (default: off)
+ *
+ * Every one of these is read LAZILY, on each log() call — a script, worker, CLI
+ * tool or test that never boots a server still gets the operator's configuration.
  *
  * Rotation is stdlib roll-your-own:
  *   - On each write, statSync the file. If size >= TINA4_LOG_ROTATE_SIZE, rotate.
@@ -163,6 +236,22 @@ function resolveLogFilePath(logDir: string, logFile: string): string {
 export class Log {
   private static requestId: string | undefined;
 
+  /**
+   * What configure() was explicitly told, held HERE rather than written back
+   * into process.env (ADR-0041).
+   *
+   * configure() used to assign to process.env.TINA4_LOG_DIR / _LOG_FILE. That
+   * reached the right answer -- the argument won -- through a mechanism no
+   * other framework has: it DESTROYED the operator's value for the rest of the
+   * process, and every child process spawned afterwards inherited the
+   * argument instead of what the operator set. Reading configuration must not
+   * write it. Keeping the explicit values in their own slot means resolution
+   * is explicit > env > default with the environment left intact and still
+   * readable.
+   */
+  private static explicitLogDir: string | undefined;
+  private static explicitLogFile: string | undefined;
+
   /**
    * Re-read all log-related env vars. Called on every log() so tests that
    * mutate process.env between calls see the new values without having to
@@ -177,9 +266,14 @@ export class Log {
     format: "text" | "json";
     output: "stdout" | "file" | "both";
     fileEnabled: boolean;
+    /** True when the operator named ONE file, so no error.log sibling appears. */
+    explicitFile: boolean;
+    /** TINA4_LOG_STRICT — a failed log write throws instead of being swallowed. */
+    strict: boolean;
   } {
-    const logDir = process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
-    const explicitFile = (process.env.TINA4_LOG_FILE ?? "").trim();
+    // explicit argument > environment > default (ADR-0041).
+    const logDir = Log.explicitLogDir ?? process.env.TINA4_LOG_DIR ?? DEFAULT_LOG_DIR;
+    const explicitFile = (Log.explicitLogFile ?? process.env.TINA4_LOG_FILE ?? "").trim();
     const logFile = explicitFile || DEFAULT_LOG_FILE;
 
     const rawSize = process.env.TINA4_LOG_ROTATE_SIZE;
@@ -225,7 +319,17 @@ export class Log {
       fileEnabled = !Log.isProduction();
     }
 
-    return { logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled };
+    // TINA4_LOG_STRICT — documented on all four env-var pages, implemented only
+    // in Ruby until 3.13.95: a documented no-op in three frameworks. When truthy
+    // a log-write failure THROWS instead of being swallowed, so a deploy whose
+    // log directory is read-only fails loudly instead of running blind.
+    const strict = isTruthy(process.env.TINA4_LOG_STRICT);
+
+    return {
+      logDir, logFile, rotateSize, rotateKeep, minLevel, format, output, fileEnabled,
+      explicitFile: explicitFile !== "",
+      strict,
+    };
   }
 
   /**
@@ -277,36 +381,116 @@ export class Log {
   }
 
   /**
-   * Configure the log directory / filename. Mostly a no-op now —
-   * env vars are re-read on every call. Kept for backwards compatibility.
+   * Configure where logs are written.
+   *
+   * Logs land in a `logs/` folder by default. The argument OVERRIDES that, and
+   * it accepts a DIRECTORY or a FILE PATH:
+   *
+   *   configure()                              -> ./logs/tina4.log + ./logs/error.log
+   *   configure("/var/log/myapp")              -> /var/log/myapp/tina4.log + error.log
+   *   configure("/var/log/myapp/app.log")      -> that exact file (no error.log sibling)
+   *   configure({ logDir, logFile })           -> the explicit object form still works
+   *
+   * A plain string used to be accepted and silently ignored, because only the
+   * object form was read - so the call that works in the other three
+   * frameworks produced no log file here and said nothing (feature 2 of the
+   * audit, D4). Both forms now work.
+   */
+  static configure(options?: string | { logDir?: string; logFile?: string }): void {
+    // Record what the caller asked for; never write it back into process.env
+    // (ADR-0041 -- reading configuration must not write it).
+    if (typeof options === "string") {
+      if (targetIsFile(options)) {
+        Log.explicitLogDir = dirname(options);
+        Log.explicitLogFile = options;
+      } else {
+        Log.explicitLogDir = options;
+      }
+      Log.applyAppendMode();
+      return;
+    }
+    if (options) {
+      if (options.logDir) Log.explicitLogDir = options.logDir;
+      if (options.logFile) Log.explicitLogFile = options.logFile;
+    }
+    Log.applyAppendMode();
+  }
+
+  /**
+   * Forget what configure() was told, so resolution falls back to the
+   * environment and then the built-in defaults. Parity with PHP's Log::reset().
+   *
+   * This exists because the explicit values are now HELD here rather than
+   * written back into process.env, and that makes them STICKY for the life of
+   * the process -- which is right for an application (configure() at boot is
+   * the operator's instruction and a later stray env write should not silently
+   * re-point the logs) and wrong for a long-lived test process that wants to
+   * drive the logger purely from the environment afterwards.
+   *
+   * I removed this method once for having no callers. That was correct about
+   * the grep and wrong about the code: the full suite is the caller. Before the
+   * explicit slots existed, configure() ASSIGNED to process.env, so a later
+   * direct assignment simply overwrote it and env-driven cases kept working by
+   * accident. test/logger.test.ts depends on exactly that -- it configures a
+   * file early, then runs the whole default-output block off the environment
+   * (see its own note: "these cases must NOT route through Log.configure").
+   * Three of those cases failed on the lab until this came back.
    */
-  static configure(options: { logDir?: string; logFile?: string }): void {
-    if (options.logDir) process.env.TINA4_LOG_DIR = options.logDir;
-    if (options.logFile) process.env.TINA4_LOG_FILE = options.logFile;
+  static reset(): void {
+    Log.explicitLogDir = undefined;
+    Log.explicitLogFile = undefined;
+  }
+
+  /**
+   * TINA4_LOG_APPEND — append (default) or overwrite on startup.
+   *
+   * APPEND IS THE DEFAULT: a log you can lose by restarting the process is not
+   * a log. Set it false for one file per run (a short CLI, a test fixture, a
+   * container shipping logs elsewhere); the files are truncated once here at
+   * configure time, never per line.
+   */
+  private static applyAppendMode(): void {
+    const raw = process.env.TINA4_LOG_APPEND;
+    const append = raw === undefined || isTruthy(raw);
+    if (append) return;
+    const cfg = Log.readEnv();
+    const targets = cfg.explicitFile
+      ? [resolveLogFilePath(cfg.logDir, cfg.logFile)]
+      : [resolveLogFilePath(cfg.logDir, cfg.logFile), join(cfg.logDir, "error.log")];
+    for (const path of targets) {
+      try {
+        if (existsSync(path)) writeFileSync(path, "", "utf-8");
+      } catch (err) {
+        // Same TINA4_LOG_STRICT contract as writeToFile: this IS a write to the
+        // log file, so under strict it must not be swallowed either.
+        if (cfg.strict) throw err;
+        /* logging must never crash the app */
+      }
+    }
   }
 
   /** Log an informational message. */
-  static info(message: string, data?: unknown): void {
+  static info(message: unknown, data?: unknown): void {
     Log.log("INFO", message, data);
   }
 
   /** Log a debug message. */
-  static debug(message: string, data?: unknown): void {
+  static debug(message: unknown, data?: unknown): void {
     Log.log("DEBUG", message, data);
   }
 
   /** Log a warning message. */
-  static warning(message: string, data?: unknown): void {
+  static warning(message: unknown, data?: unknown): void {
     Log.log("WARNING", message, data);
   }
 
   /** Backwards-compat alias for warning(). */
-  static warn(message: string, data?: unknown): void {
+  static warn(message: unknown, data?: unknown): void {
     Log.log("WARNING", message, data);
   }
 
   /** Log an error message. */
-  static error(message: string, data?: unknown): void {
+  static error(message: unknown, data?: unknown): void {
     Log.log("ERROR", message, data);
   }
 
@@ -318,7 +502,7 @@ export class 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 {
+  static critical(message: unknown, data?: unknown): void {
     Log.log("CRITICAL", message, data);
   }
 
@@ -397,21 +581,40 @@ export class Log {
     try { writeFileSync(filePath, "", "utf-8"); } catch { /* ignore */ }
   }
 
-  /** Write a line to the log file, stripping ANSI codes. */
-  private static writeToFile(filePath: string, line: string, rotateSize: number, rotateKeep: number): void {
+  /**
+   * Write a line to the log file, stripping ANSI codes.
+   *
+   * A failure is swallowed by default — logging must never crash the app. With
+   * TINA4_LOG_STRICT truthy it is RE-THROWN instead: an app that believes it is
+   * writing an audit trail into a read-only directory, and is not, is worse off
+   * than one that dies at the first line. Same contract in all four frameworks.
+   */
+  private static writeToFile(
+    filePath: string,
+    line: string,
+    rotateSize: number,
+    rotateKeep: number,
+    strict: boolean,
+  ): void {
     try {
       Log.ensureLogDir(filePath);
       Log.rotateIfNeeded(filePath, rotateSize, rotateKeep);
       appendFileSync(filePath, stripAnsi(line) + "\n", "utf-8");
-    } catch {
+    } catch (err) {
+      if (strict) throw err;
       // Silently fail — logging should never crash the app
     }
   }
 
   /** Core log method */
-  private static log(level: LogLevel, message: string, data?: unknown): void {
+  private static log(level: LogLevel, rawMessage: unknown, data?: unknown): void {
     const cfg = Log.readEnv();
 
+    // Coerce FIRST, into the local the human line is built from further down.
+    // Anything can arrive as a message: an object from a handler, a Buffer off
+    // a socket, a 10MB string. See coerceMessage.
+    const message = coerceMessage(rawMessage);
+
     const entry: LogEntry = {
       timestamp: Log.timestamp(),
       level,
@@ -441,26 +644,33 @@ export class Log {
     const dataPart = data !== undefined ? ` ${JSON.stringify(data)}` : "";
     const humanLine = `${entry.timestamp} [${paddedLevel}]${reqPart}${fnPart} ${message}${dataPart}`;
 
-    // Build the file-format line. v3.13.14: production always emits JSON
-    // (parity with Python/Ruby) so log aggregators get structured lines;
-    // TINA4_LOG_FORMAT=json forces it in dev too.
-    const fileLine =
-      cfg.format === "json" || Log.isProduction() ? JSON.stringify(entry) : humanLine;
+    // ONE format decision, both sinks, one input: TINA4_LOG_FORMAT. Text is the
+    // default; only an explicit `json` selects JSON. The `|| Log.isProduction()`
+    // that used to live here made an UNSET TINA4_DEBUG silently reformat every
+    // line — the owner's measured defect (four frameworks, four meanings of
+    // "production", four different formats off one .env). An object passed as
+    // the message is still JSON-encoded INLINE by coerceMessage, which is the
+    // only structure a default install emits.
+    const formattedLine = cfg.format === "json" ? JSON.stringify(entry) : humanLine;
 
     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
-    // `!isProduction()` gate meant deployed apps logged nothing. In
-    // production we print the clean structured line (JSON, no ANSI) so it
-    // stays parseable; in dev we keep the coloured human-readable line.
+    // `!isProduction()` gate meant deployed apps logged nothing.
     // TINA4_LOG_OUTPUT="file" still opts out of stdout entirely.
+    //
+    // stdout carries the SAME formattedLine as the file — the format env is the
+    // only thing that picks text vs JSON. TINA4_DEBUG decides COLOUR only: ANSI
+    // is for a human at a terminal, and a production pipe / log shipper must get
+    // clean bytes. Truncate on the CONSOLE only; the file keeps the full line so
+    // a consumer parsing it loses nothing, and a terminal does not need 10MB.
     if (shouldLog && cfg.output !== "file") {
+      const consoleLine = truncateForStdout(formattedLine);
       if (Log.isProduction()) {
-        console.log(fileLine);
+        console.log(consoleLine);
       } else {
-        const color = COLORS[level];
-        console.log(`${color}${humanLine}${RESET}`);
+        console.log(`${COLORS[level]}${consoleLine}${RESET}`);
       }
     }
 
@@ -477,7 +687,18 @@ export class Log {
     // 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);
+      Log.writeToFile(filePath, formattedLine, cfg.rotateSize, cfg.rotateKeep, cfg.strict);
+
+      // Mirror WARNING and above into a dedicated error.log so
+      // `tail -f logs/error.log` gives just the stuff worth looking at. Node
+      // wrote ONE file where Python and PHP wrote two, so anyone whose
+      // alerting tails error.log got silence here (feature 2 of the audit, D3).
+      // Skipped when the operator named ONE file explicitly: they asked for a
+      // single path, so a sibling error.log appearing beside it is a surprise.
+      if (!cfg.explicitFile && LEVEL_PRIORITY[level] >= LEVEL_PRIORITY.WARNING) {
+        const errorPath = join(cfg.logDir, "error.log");
+        Log.writeToFile(errorPath, formattedLine, cfg.rotateSize, cfg.rotateKeep, cfg.strict);
+      }
     }
   }
 }

package/packages/core/src/mcp.ts

@@ -1650,7 +1650,7 @@ export function registerDevTools(server: McpServer): void {
           return { error: "Seeder API not available (install @tina4/orm)" };
         }
         // RAW adapter, NOT globalThis.__tina4_db: autoFieldMap introspects via
-        // adapter.columns() and seedTable inserts via adapter.execute() — the
+        // adapter.getColumns() and seedTable inserts via adapter.execute() — the
         // Database WRAPPER has neither (its introspection method is getColumns).
         // getAdapter() is the same accessor migration_* use above.
         let adapter;

package/packages/core/src/messenger.ts

@@ -717,7 +717,7 @@ export class Messenger {
    * Fetch latest messages from a folder.
    * Returns list of message summaries.
    */
-  async inbox(limit: number = 20, offset: number = 0, folder: string = "INBOX"): Promise<ImapMessage[]> {
+  async inbox(folder: string = "INBOX", limit: number = 20, offset: number = 0): Promise<ImapMessage[]> {
     let socket: net.Socket | tls.TLSSocket;
     try {
       socket = await this.imapConnect();
@@ -755,7 +755,7 @@ export class Messenger {
   /**
    * Read a single message by sequence number or UID.
    */
-  async read(uid: string, folder: string = "INBOX"): Promise<ImapFullMessage> {
+  async read(uid: string, folder: string = "INBOX"): Promise<ImapFullMessage | null> {
     let socket: net.Socket | tls.TLSSocket;
     try {
       socket = await this.imapConnect();
@@ -767,9 +767,14 @@ export class Messenger {
       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 {}).
+      // that is NOT an error, so it must not throw. It returns null: FALSY, so
+      // `if (!msg)` detects it. This used to return emptyFullMessage(uid) under
+      // a comment claiming "parity with Python's {}" -- but that object is
+      // TRUTHY, while Python's {} , PHP's null and Ruby's nil are all falsy, so
+      // Node was the one framework where a caller could not tell "no such
+      // message" from a real one without inspecting individual fields.
       if (!/\{\d+\}/.test(fetchResp)) {
-        return emptyFullMessage(uid);
+        return null;
       }
 
       // Mark as seen
@@ -1039,15 +1044,6 @@ 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]*)/);