tina4ruby 3.13.37 → 3.13.39

data/lib/tina4/log.rb

@@ -12,11 +12,12 @@ module Tina4
       "[TINA4_LOG_INFO]" => 1,
       "[TINA4_LOG_WARNING]" => 2,
       "[TINA4_LOG_ERROR]" => 3,
-      "[TINA4_LOG_NONE]" => 4
+      "[TINA4_LOG_CRITICAL]" => 4,
+      "[TINA4_LOG_NONE]" => 5
     }.freeze
 
     SEVERITY_MAP = {
-      debug: 0, info: 1, warn: 2, error: 3
+      debug: 0, info: 1, warn: 2, error: 3, critical: 4
     }.freeze
 
     COLORS = {
@@ -65,15 +66,36 @@ module Tina4
         @format = format_env && !format_env.empty? ? format_env.downcase : (production? ? "json" : "text")
         @json_mode = @format == "json"
 
-        # TINA4_LOG_OUTPUT — "stdout", "file", or "both". Defaults to "both".
+        # TINA4_LOG_OUTPUT — "stdout", "file", or "both".
+        #
+        # Default (UNSET): stdout is ALWAYS on. The log FILE (tina4.log + any
+        # error log) is written ONLY in development — i.e. when TINA4_DEBUG is
+        # truthy. In production / containers (TINA4_DEBUG falsy) the logger is
+        # stdout-only: writing a log file inside a container just bloats the
+        # writable layer + disk, and 12-factor wants logs on stdout for the
+        # platform to capture. An explicit TINA4_LOG_OUTPUT=file/both (or an
+        # explicit TINA4_LOG_FILE path) overrides this and STILL writes a file.
+        # Mirrors the Python master (debug/__init__.py configure()).
+        # An explicit TINA4_LOG_FILE always wins: a path the operator named must
+        # be written even in production (parity with the Python master, where an
+        # explicit log_file builds a writer unconditionally), so the dev-gated
+        # default below resolves to "both" (stdout + file) rather than "stdout".
+        explicit_file = !(log_file_env.nil? || log_file_env.empty?)
+        default_output = if explicit_file || truthy?(ENV["TINA4_DEBUG"])
+                           "both"
+                         else
+                           "stdout"
+                         end
         output_env = ENV["TINA4_LOG_OUTPUT"]
-        @output = output_env && !output_env.empty? ? output_env.downcase : "both"
-        unless %w[stdout file both].include?(@output)
-          @output = "both"
-        end
+        @output = if output_env && !output_env.empty?
+                    output_env.downcase
+                  else
+                    default_output
+                  end
+        @output = default_output unless %w[stdout file both].include?(@output)
 
-        # TINA4_LOG_CRITICAL — when true, raise on log write failures instead of swallowing.
-        @critical = truthy?(ENV["TINA4_LOG_CRITICAL"])
+        # TINA4_LOG_STRICT — when true, raise on log write failures instead of swallowing.
+        @strict = truthy?(ENV["TINA4_LOG_STRICT"])
 
         @console_level = resolve_level
         @request_id = nil
@@ -122,6 +144,28 @@ module Tina4
         @json_mode
       end
 
+      # Would a message at `level` pass the configured MINIMUM CONSOLE LEVEL
+      # (TINA4_LOG_LEVEL)? Returns true iff `log` would print it to stdout —
+      # it reflects CONSOLE visibility only. The log FILE records every level
+      # regardless of this threshold, so this never gates file output.
+      #
+      # `level` accepts a String or Symbol and is case-insensitive
+      # ("INFO", :info, "Warning", :warning all work). Mirrors Python's
+      # Log.is_enabled. It REUSES the exact severity >= @console_level
+      # comparison the console branch in `log` uses (line ~167) via
+      # SEVERITY_MAP / resolve_level — it never re-implements level
+      # comparison, so it can never disagree with what the logger prints.
+      #
+      # "critical" is a FIRST-CLASS top-level severity (4 — above error 3),
+      # not a parity alias for error. It is evaluated with ordinary threshold
+      # logic (critical 4 >= @console_level), so it passes at every level
+      # except none (5) — matching the Python master.
+      def enabled?(level)
+        sym = normalize_level(level)
+        severity = SEVERITY_MAP[sym] || 0
+        severity >= console_level
+      end
+
       def info(message, context = {})
         log(:info, message, context)
       end
@@ -138,6 +182,14 @@ module Tina4
         log(:error, message, context)
       end
 
+      # critical is the HIGHEST severity (4, above error). Like every other
+      # level it ALWAYS emits, subject only to the TINA4_LOG_LEVEL threshold
+      # (which critical passes at every level except none). A critical log is
+      # never a silent no-op. Mirrors the Python master.
+      def critical(message, context = {})
+        log(:critical, message, context)
+      end
+
       # Test/teardown helper — closes the underlying Logger so the file
       # handle is released (Windows / tmpdir cleanup).
       def close_file_logger
@@ -181,6 +233,28 @@ module Tina4
         @current_context = {}
       end
 
+      # The current minimum console level as an integer (the same value
+      # the console branch in `log` compares against). Ensures the logger
+      # is configured so `enabled?` works before any log call has run.
+      def console_level
+        configure unless @initialized
+        @console_level
+      end
+
+      # Map a level (String or Symbol, case-insensitive) onto the symbol
+      # space used by SEVERITY_MAP. Accepts the public method names
+      # (debug/info/warning/error/critical) and the internal :warn symbol.
+      # critical is a FIRST-CLASS level (severity 4), not an alias for error.
+      # Unknown levels fall through to their own symbol and resolve to
+      # severity 0 in `enabled?`.
+      def normalize_level(level)
+        sym = level.to_s.strip.downcase.to_sym
+        case sym
+        when :warning then :warn
+        else sym
+        end
+      end
+
       def resolve_level
         # v3.13.14: default is INFO (was ALL) so a deployed app surfaces
         # request/startup/warn/error without debug noise, matching
@@ -199,6 +273,7 @@ module Tina4
         when :info  then "INFO"
         when :warn  then "WARNING"
         when :error then "ERROR"
+        when :critical then "CRITICAL"
         else level.to_s.upcase
         end
       end
@@ -278,6 +353,7 @@ module Tina4
                 when :info    then COLORS[:green]
                 when :warn    then COLORS[:yellow]
                 when :error   then COLORS[:red]
+                when :critical then COLORS[:magenta]
                 else COLORS[:reset]
                 end
         "#{color}#{line}#{COLORS[:reset]}"
@@ -288,7 +364,7 @@ module Tina4
         # Use << to bypass Logger's severity filtering — we already filtered above.
         @file_logger << "#{line}\n"
       rescue IOError, SystemCallError => e
-        raise if @critical
+        raise if @strict
         # Don't crash on log write failure
       end
     end

data/lib/tina4/mcp.rb

@@ -139,15 +139,35 @@ module Tina4
 
   # Resolve whether the built-in MCP dev server should be active.
   #
-  # Precedence:
-  #   * TINA4_MCP set explicitly → use that (truthy/falsey).
-  #   * Otherwise: enabled only when TINA4_DEBUG=true.
+  # Resolution order (highest priority first):
+  #   1. TINA4_MCP set explicitly → use that (truthy/falsey). Honoured on ANY
+  #      host. An explicit `true` is how a sysadmin opts a remote /
+  #      debug-disabled deployment in (e.g. for a remote AI assistant); an
+  #      explicit `false` 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.
+  #
+  # Mirrors the Python master (tina4_python/mcp/__init__.py is_enabled). Before
+  # v3.13.39 is_localhost? was dead code and TINA4_MCP_REMOTE was never read, so
+  # the documented localhost guard was not actually enforced — a non-localhost
+  # TINA4_DEBUG=true deployment auto-exposed the dev tools. This wires it.
   def self.mcp_enabled?
     explicit = ENV["TINA4_MCP"]
     if explicit && !explicit.empty?
-      return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
+      return truthy?(explicit)
     end
-    %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
+    return false unless truthy?(ENV["TINA4_DEBUG"])
+
+    # Dev auto-enable: localhost only, unless explicitly opted into remote.
+    is_localhost? || truthy?(ENV["TINA4_MCP_REMOTE"])
+  end
+
+  # Case-insensitive truthiness for env values: true/1/yes/on.
+  def self.truthy?(val)
+    %w[true 1 yes on].include?(val.to_s.strip.downcase)
   end
 
   # Resolve the dedicated MCP port. Defaults to (server port + 2000) — keeps
@@ -651,9 +671,16 @@ module Tina4
         db = Tina4.database
         return { "error" => "No database connection" } if db.nil?
         param_list = params.is_a?(String) ? JSON.parse(params) : params
-        result = db.execute(sql, param_list)
-        db.commit rescue nil
-        { "success" => true, "affected_rows" => (result.respond_to?(:count) ? result.count : 0) }
+        # db.execute() now RAISES on a SQL error (it no longer returns false).
+        # Catch it and return a clean { error: } payload instead of letting the
+        # exception escape the tool handler.
+        begin
+          result = db.execute(sql, param_list)
+          db.commit rescue nil
+          { "success" => true, "affected_rows" => (result.respond_to?(:count) ? result.count : 0) }
+        rescue => e
+          { "error" => db.get_error || e.message }
+        end
       }, "Execute arbitrary SQL (INSERT/UPDATE/DELETE/DDL)")
 
       server.register_tool("database_tables", lambda {

data/lib/tina4/messenger.rb

@@ -13,8 +13,44 @@ end
 require "base64"
 require "securerandom"
 require "time"
+require "socket"
+require "timeout"
+begin
+  require "openssl"
+rescue LoadError
+  # openssl is part of stdlib; absence only affects TLS error classification
+end
 
 module Tina4
+  # Raised on a messenger failure (base class).
+  class MessengerError < StandardError; end
+
+  # Raised when an IMAP read fails to connect, authenticate, or speak the
+  # protocol. Distinct from a successful fetch that simply has no messages —
+  # that still returns an empty result ([]/nil/0/{}), NOT an error.
+  #
+  # Subclasses MessengerError so existing `rescue Tina4::MessengerError`
+  # handlers still catch it.
+  class MessengerConnectionError < MessengerError; end
+
+  # Errors that mean "we could not talk to the mail server", as opposed to
+  # "we talked fine and the mailbox is empty". These must fail loud — LOG and
+  # RAISE — never be silently swallowed into an empty result. Mirrors the
+  # Python master's _IMAP_CONNECTION_ERRORS tuple.
+  #
+  # Built lazily so a missing net/imap gem (LoadError above) doesn't break
+  # loading this file.
+  IMAP_CONNECTION_ERRORS = [
+    SocketError,            # DNS / host resolution failures
+    IOError,                # closed/broken stream, EOF mid-conversation
+    SystemCallError,        # Errno::ECONNREFUSED / ECONNRESET / ETIMEDOUT etc.
+    Timeout::Error,         # connect/read timeout (Net::OpenTimeout descends from this)
+    MessengerError          # our own protocol-failure signal (re-raised as-is)
+  ].tap do |errors|
+    errors << Net::IMAP::Error if defined?(Net::IMAP::Error)
+    errors << OpenSSL::SSL::SSLError if defined?(OpenSSL::SSL::SSLError)
+  end.freeze
+
   # Tina4 Messenger — Email sending (SMTP) and reading (IMAP).
   #
   # Unified .env-driven configuration with constructor override.
@@ -120,9 +156,14 @@ module Tina4
 
     # ── IMAP operations ──────────────────────────────────────────────────
 
-    # List messages in a folder
+    # List messages in a folder.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/auth/protocol
+    # failure (FAILS LOUD — never returns [] to hide it). A successful fetch
+    # from an empty folder returns [] (that is NOT an error).
     def inbox(folder: "INBOX", limit: 20, offset: 0)
-      imap_connect do |imap|
+      imap = imap_open("inbox")
+      begin
         imap.select(folder)
         uids = imap.uid_search(["ALL"])
         uids = uids.reverse # newest first
@@ -131,15 +172,20 @@ module Tina4
 
         envelopes = imap.uid_fetch(page, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
         (envelopes || []).map { |msg| parse_envelope(msg) }
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("inbox", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP inbox failed: #{e.message}")
-      []
     end
 
-    # Read a single message by UID
+    # Read a single message by UID.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful fetch for a non-existent UID returns nil (that is NOT an error).
     def read(uid, folder: "INBOX", mark_read: true)
-      imap_connect do |imap|
+      imap = imap_open("read")
+      begin
         imap.select(folder)
         data = imap.uid_fetch(uid, ["ENVELOPE", "FLAGS", "BODY[]", "RFC822.SIZE"])
         return nil if data.nil? || data.empty?
@@ -150,28 +196,38 @@ module Tina4
 
         msg = data.first
         parse_full_message(msg)
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("read", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP read failed: #{e.message}")
-      nil
     end
 
-    # Count unread messages
+    # Count unread messages.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful query with no unseen messages returns 0 (NOT an error).
     def unread(folder: "INBOX")
-      imap_connect do |imap|
+      imap = imap_open("unread")
+      begin
         imap.select(folder)
         uids = imap.uid_search(["UNSEEN"])
         uids.length
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("unread", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP unread count failed: #{e.message}")
-      0
     end
 
-    # Search messages with filters
+    # Search messages with filters.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
+    # A successful search with no matches returns [] (NOT an error).
     def search(folder: "INBOX", subject: nil, sender: nil, since: nil,
                before: nil, unseen_only: false, limit: 20)
-      imap_connect do |imap|
+      imap = imap_open("search")
+      begin
         imap.select(folder)
         criteria = build_search_criteria(
           subject: subject, sender: sender, since: since,
@@ -184,21 +240,26 @@ module Tina4
 
         envelopes = imap.uid_fetch(page, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
         (envelopes || []).map { |msg| parse_envelope(msg) }
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("search", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP search failed: #{e.message}")
-      []
     end
 
-    # List all IMAP folders
+    # List all IMAP folders.
+    #
+    # Raises Tina4::MessengerConnectionError on a connection/protocol failure.
     def folders
-      imap_connect do |imap|
+      imap = imap_open("folders")
+      begin
         boxes = imap.list("", "*")
         (boxes || []).map(&:name)
+      rescue *IMAP_CONNECTION_ERRORS => e
+        raise imap_fail("folders", e)
+      ensure
+        imap_cleanup(imap)
       end
-    rescue => e
-      Tina4::Log.error("IMAP folders failed: #{e.message}")
-      []
     end
 
     # Mark a message as read (set \Seen flag).
@@ -393,6 +454,50 @@ module Tina4
 
     # ── IMAP helpers ─────────────────────────────────────────────────────
 
+    # Open and authenticate an IMAP connection. On a connection/auth/protocol
+    # failure this FAILS LOUD — logs and raises MessengerConnectionError —
+    # rather than swallowing the error into an empty result.
+    def imap_open(method)
+      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
+      imap.login(@username, @password)
+      imap
+    rescue *IMAP_CONNECTION_ERRORS => e
+      raise imap_fail(method, e)
+    end
+
+    # Best-effort teardown of an IMAP connection. Never raises.
+    def imap_cleanup(imap)
+      return if imap.nil?
+
+      begin
+        imap.logout
+      rescue StandardError
+        # ignore — already closing
+      end
+      begin
+        imap.disconnect
+      rescue StandardError
+        # ignore — already closed
+      end
+    end
+
+    # Log an IMAP connection/protocol failure and return the error to raise.
+    # A genuinely empty mailbox is NOT an error and never reaches here.
+    # Re-raises a MessengerError as-is; otherwise wraps in
+    # MessengerConnectionError. Callers do `raise imap_fail(name, exc)`.
+    def imap_fail(method, exc)
+      Tina4::Log.error(
+        "Messenger IMAP #{method}() failed: #{exc.class}: #{exc.message}"
+      )
+      return exc if exc.is_a?(MessengerError)
+
+      MessengerConnectionError.new("IMAP #{method} failed: #{exc.message}")
+    end
+
+    # Connect, yield, then tear down — used by the mutators / connectivity test
+    # that keep their own result-style error handling (mark_read,
+    # test_imap_connection). Read methods use imap_open + ensure directly so
+    # they can fail loud.
     def imap_connect(&block)
       imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
       imap.login(@username, @password)