tina4ruby 3.13.93 → 3.13.94

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7b916f1f99717b6933e8d4376b760d2c975daefec3b5507d9827480522cfe8f
-  data.tar.gz: e800d0a184690267eb84976193744593eea98b2ec355405f15a32214d12e31a0
+  metadata.gz: a56dae3f83633c16250748c98a0cc2507c1309db74552c55914555da4b34356d
+  data.tar.gz: 661237a63c06e576343655d847088e47becdd1c934e0f34f1f3691494993b09a
 SHA512:
-  metadata.gz: 6428126904b059c914f08ca0fc446622a07447075c23e4a20ba12b01f93cf6a5c48454cab6cebfdc98da615f9fbb9ba57d4e3021d6b26d688cb92cdf5a553cb3
-  data.tar.gz: 7fb13ab4b8cae5c60ad932ed1a9de7750881381451b294747b6f90441b682dd5658f49394fd29707144fe2e4ae95a5639cb47cc50a6a1a87aae6b4d60eab0e29
+  metadata.gz: ec26f2cbe92f9acd95ec969a62aff4586c7b2f97cdee9cef39173bf3e34532ff0273dc42df079c0aec0ed89f67a46b0ab802c963d220aeecf8bee9e09e7bbbbd
+  data.tar.gz: 12fff1300e24b224979b14ce160e8cf1f0f0878faa5c1845861f5f27eb9063e71af13cafb1f026058cab0617c0c3975df7789e91fe9679f78de430c596b25689

data/lib/tina4/cli.rb

@@ -3223,10 +3223,18 @@ module Tina4
 
           EXPOSE 7147
 
-          # Swagger defaults (override with env vars in docker-compose/k8s if needed)
-          ENV SWAGGER_TITLE="Tina4 API"
-          ENV SWAGGER_VERSION="0.1.0"
-          ENV SWAGGER_DESCRIPTION="Auto-generated API documentation"
+          # Swagger defaults (override with env vars in docker-compose/k8s if needed).
+          # The TINA4_ prefix is REQUIRED: the un-prefixed names are the legacy
+          # v2/v3.11 forms, and check_legacy_env_vars! refuses to boot when it
+          # finds one, so a generated image would exit 2 during startup.
+          ENV TINA4_SWAGGER_TITLE="Tina4 API"
+          ENV TINA4_SWAGGER_VERSION="0.1.0"
+          ENV TINA4_SWAGGER_DESCRIPTION="Auto-generated API documentation"
+
+          # Required: WebServer#start exits 1 unless the tina4 CLI launched it
+          # (--managed) or this is set. A container has no CLI supervising it.
+          ENV TINA4_OVERRIDE_CLIENT=true
+          ENV TINA4_DEBUG=false
 
           # Start the server on all interfaces
           CMD ["bundle", "exec", "tina4ruby", "start", "-p", "7147", "-h", "0.0.0.0", "--production"]

data/lib/tina4/database.rb

@@ -5,6 +5,15 @@ require "digest"
 require "weakref"
 
 module Tina4
+  # Raised at the first USE of a database whose connect failed.
+  #
+  # Connecting is deliberately non-fatal at boot (log loud, then degrade - the same
+  # policy the session backends follow), so the failure has to resurface somewhere.
+  # It used to resurface as a nil dereference inside the driver
+  # ("NoMethodError: private method `exec' called for nil:NilClass"), which named
+  # neither the database nor the reason. This carries both.
+  class DatabaseConnectionError < StandardError; end
+
   # Thread-safe connection pool with round-robin rotation.
   # Connections are created lazily on first use.
   class ConnectionPool
@@ -191,6 +200,9 @@ module Tina4
                      pool
                    end
       @connected = false
+      # Set by #connect when connecting fails; re-raised with context by
+      # #current_driver so the first real call says what went wrong.
+      @connect_error = nil
 
       # Per-instance thread-local key for the transaction adapter pin.
       # Without this pin, every Database method call rotates to a different
@@ -301,9 +313,21 @@ module Tina4
       @driver.autocommit = @autocommit if @driver.respond_to?(:autocommit=)
 
       Tina4::Log.info("Database connected: #{@driver_name}")
+      @connect_error = nil
     rescue => e
       Tina4::Log.error("Database connection failed: #{e.message}")
       @connected = false
+      # REMEMBER the cause. Logging alone is not enough: the driver's own
+      # connection stays nil, so the next call used to die inside the driver as
+      #   NoMethodError: private method `exec' called for nil:NilClass
+      # which names neither the database it failed to reach nor why. That cost
+      # real debugging time when a missing test database looked like a driver
+      # bug. current_driver re-raises this with context instead.
+      #
+      # Boot still does NOT crash on an unreachable database (deliberate, and
+      # the same log-loud-then-degrade policy the session backends use) - the
+      # error surfaces at the first actual USE.
+      @connect_error = e
     end
 
     def close
@@ -324,6 +348,11 @@ module Tina4
     def current_driver
       pinned = Thread.current[@tx_pin_key]
       return pinned if pinned
+
+      # Fail with the REAL reason, at the point of use. Without this the caller
+      # gets a nil dereference from deep inside the driver and has to guess.
+      raise Tina4::DatabaseConnectionError, connect_error_message if @connect_error
+
       if @pool
         @pool.checkout
       else
@@ -331,6 +360,22 @@ module Tina4
       end
     end
 
+    # A message that says which database, on which driver, and why - the three
+    # things the old nil-dereference told you nothing about.
+    def connect_error_message
+      target = safe_connection_target
+      "Database not connected (#{@driver_name}#{target.empty? ? '' : " -> #{target}"}): " \
+        "#{@connect_error.class}: #{@connect_error.message}"
+    end
+
+    # The connection string with any password stripped, so a raised error can name
+    # the target without leaking a credential into a log or an HTTP 500 body.
+    def safe_connection_target
+      return '' if @connection_string.nil? || @connection_string.empty?
+
+      @connection_string.sub(%r{://([^:/@]+):[^@]*@}, '://\1:***@')
+    end
+
     # ── Query Cache ──────────────────────────────────────────────
 
     def cache_stats
@@ -542,57 +587,122 @@ module Tina4
     end
     private :write_affected
 
+    # The table's primary-key columns, introspected once and cached.
+    #
+    # Returns an ARRAY because a primary key may span several columns. A
+    # composite key is still one primary key; it just has more than one column.
+    # Returns [] when the table has no primary key or cannot be introspected.
+    #
+    # Uses the cross-engine columns() contract (v3.13.14, #48), which reports
+    # :primary_key per column on every driver.
+    def primary_key(table)
+      @pk_cache ||= {}
+      unless @pk_cache.key?(table)
+        @pk_cache[table] = begin
+          columns(table).select { |c| c[:primary_key] }.map { |c| c[:name].to_s }
+        rescue StandardError
+          []
+        end
+      end
+      @pk_cache[table]
+    end
+
+    # Normalise a filter to [sql, params], accepting a Hash or a String.
+    def as_where(filter, params)
+      return ["", []] if filter.nil?
+
+      if filter.is_a?(Hash)
+        return ["", []] if filter.empty?
+
+        drv = current_driver
+        [filter.keys.map { |k| "#{k} = #{drv.placeholder}" }.join(" AND "), filter.values]
+      else
+        [filter.to_s, Array(params)]
+      end
+    end
+    private :as_where
+
+    # Update rows. A write with no filter is an error, not a full-table write.
+    #
+    # With no explicit filter the primary key is taken out of `data` and used as
+    # the WHERE clause. With neither a filter nor a primary key in `data` this
+    # raises rather than overwriting every row (audit feature 4, P1).
     def update(table, data, filter = {}, params = nil)
-      cache_invalidate if @cache_enabled
-      drv = current_driver
+      where_sql, where_params = as_where(filter, params)
+      data = data.dup
+
+      if where_sql.empty?
+        pk_columns = primary_key(table)
+        # Resolve each key column to whichever form the caller used (String or
+        # Symbol); nil marks one that is absent from the data.
+        pk_keys = pk_columns.map do |col|
+          if data.key?(col) then col
+          elsif data.key?(col.to_sym) then col.to_sym
+          end
+        end
+        missing = pk_columns.each_with_index.reject { |_, i| pk_keys[i] }.map(&:first)
+
+        if pk_columns.empty? || !missing.empty?
+          raise ArgumentError,
+                "update requires a filter or the complete primary key in the data; " \
+                "pass a filter explicitly to update multiple rows " \
+                "(table=#{table.inspect}, primary key=#{pk_columns.inspect}, " \
+                "missing from data=#{missing.inspect}). " \
+                "To empty a table use truncate(#{table.inspect})."
+        end
 
-      # String filter with explicit params array
-      if filter.is_a?(String) && !params.nil?
-        set_parts = data.keys.map { |k| "#{k} = #{drv.placeholder}" }
-        sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
-        sql += " WHERE #{filter}" unless filter.empty?
-        drv.execute(sql, data.values + Array(params))
-        autocommit_standalone_write(drv)
-        return Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+        # EVERY key column goes into the WHERE. A composite key built from only
+        # its first column would match every row sharing that value - the
+        # data-loss bug this method exists to prevent, reintroduced.
+        where_params = pk_keys.map { |k| data.delete(k) }
+        if data.empty?
+          raise ArgumentError,
+                "update was given only the primary key #{pk_columns.inspect} and no " \
+                "columns to set (table=#{table.inspect})"
+        end
+
+        where_sql = pk_columns.map { |c| "#{c} = #{current_driver.placeholder}" }.join(" AND ")
       end
 
+      cache_invalidate if @cache_enabled
+      drv = current_driver
       set_parts = data.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      where_parts = filter.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
-      sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
-      values = data.values + filter.values
-      drv.execute(sql, values)
+      sql = "UPDATE #{table} SET #{set_parts.join(', ')} WHERE #{where_sql}"
+      drv.execute(sql, data.values + where_params)
       autocommit_standalone_write(drv)
-      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
     end
 
+    # Delete rows. A filterless delete raises; use truncate() to empty a table.
     def delete(table, filter = {}, params = nil)
-      cache_invalidate if @cache_enabled
-      drv = current_driver
-
       # List of hashes — delete each row
       if filter.is_a?(Array)
         total = 0
         filter.each { |row| total += delete(table, row).affected_rows }
-        return Tina4::DatabaseResult.new([], affected_rows: total)
+        return Tina4::DatabaseResult.new([], affected_rows: total, last_id: nil)
       end
 
-      # String filter — raw WHERE clause with optional params
-      if filter.is_a?(String)
-        sql = "DELETE FROM #{table}"
-        sql += " WHERE #{filter}" unless filter.empty?
-        drv.execute(sql, Array(params))
-        autocommit_standalone_write(drv)
-        return Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      where_sql, where_params = as_where(filter, params)
+      if where_sql.empty?
+        raise ArgumentError,
+              "delete requires a filter (table=#{table.inspect}). " \
+              "To remove every row use truncate(#{table.inspect})."
       end
 
-      # Hash filter — build WHERE from keys
-      where_parts = filter.keys.map { |k| "#{k} = #{drv.placeholder}" }
-      sql = "DELETE FROM #{table}"
-      sql += " WHERE #{where_parts.join(' AND ')}" unless filter.empty?
-      drv.execute(sql, filter.values)
+      cache_invalidate if @cache_enabled
+      drv = current_driver
+      drv.execute("DELETE FROM #{table} WHERE #{where_sql}", where_params)
+      autocommit_standalone_write(drv)
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
+    end
+
+    # Remove every row. The explicit spelling of a whole-table delete.
+    def truncate(table)
+      cache_invalidate if @cache_enabled
+      drv = current_driver
+      drv.execute("DELETE FROM #{table} WHERE 1 = 1", [])
       autocommit_standalone_write(drv)
-      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv))
+      Tina4::DatabaseResult.new([], affected_rows: write_affected(drv), last_id: nil)
     end
 
     # Return the last execute() error message, or nil.

data/lib/tina4/dev_mailbox.rb

@@ -16,7 +16,10 @@ module Tina4
     end
 
     # Capture an outgoing email to the local filesystem instead of sending
-    def capture(to:, subject:, body:, html: false, cc: [], bcc: [],
+    # text: carries the plain-text alternative onto the dev path. Every framework
+    # used to drop it, so what you inspected in the mailbox was not what would have
+    # been sent -- a mailbox that shows you a different message is worse than none.
+    def capture(to:, subject:, body:, html: false, text: nil, cc: [], bcc: [],
                 reply_to: nil, from_address: nil, from_name: nil, attachments: [])
       msg_id = SecureRandom.uuid
       timestamp = Time.now
@@ -30,6 +33,7 @@ module Tina4
         reply_to: reply_to,
         subject: subject,
         body: body,
+        text: text,
         html: html,
         attachments: store_attachments(msg_id, attachments),
         read: false,

data/lib/tina4/drivers/sqlite_driver.rb

@@ -169,7 +169,10 @@ module Tina4
             type: r[:type],
             nullable: r[:notnull] == 0,
             default: r[:dflt_value],
-            primary_key: r[:pk] == 1
+            # PRAGMA table_info reports `pk` as the 1-BASED POSITION within the
+            # primary key, not a boolean: a composite key gives pk=1, pk=2, ...
+            # Testing `== 1` reported only the first column of a composite key.
+            primary_key: r[:pk].to_i.positive?
           }
         end
       end

data/lib/tina4/frond.rb

@@ -163,6 +163,29 @@ module Tina4
       elif else elseif endautoescape endblock endcache endfor endif endlive
       endmacro endraw endset endspaceless
     ].freeze
+
+    # Author-written tags the sandbox allow-list governs. Mirrors Python's
+    # _GATEABLE_TAGS and PHP's GATEABLE_TAGS. A tag absent from this list is
+    # structural, not an author capability, and is never gated -- `block` and
+    # `extends` are template inheritance, and `raw` is consumed by the tokenizer.
+    # Both spellings of set ({% set x = 1 %} and {% set x %}...{% endset %})
+    # dispatch under "set", so one entry covers the pair.
+    GATEABLE_TAGS = %w[
+      autoescape cache for from if import include live macro set spaceless
+    ].freeze
+
+    # Gateable tags that OWN A BODY, mapped to the terminator closing it. A
+    # denied tag has to consume its body -- see skip_block.
+    BLOCK_TAG_ENDS = {
+      "autoescape" => "endautoescape",
+      "cache" => "endcache",
+      "for" => "endfor",
+      "if" => "endif",
+      "live" => "endlive",
+      "macro" => "endmacro",
+      "set" => "endset",
+      "spaceless" => "endspaceless"
+    }.freeze
     AUTOESCAPE_RE   = /\Aautoescape\s+(false|true)/
     STRIPTAGS_RE    = /<[^>]+>/
     THOUSANDS_RE    = /(\d)(?=(\d{3})+(?!\d))/
@@ -444,6 +467,28 @@ module Tina4
       self
     end
 
+    # May this filter RUN under the current sandbox?
+    #
+    # The escaping decision has to ask this rather than read the filter name out
+    # of the source: a denied `raw` that still marked its value safe made the
+    # allow-list entry governing XSS escaping inert.
+    def filter_permitted?(name)
+      return true unless @sandbox && @allowed_filters
+
+      @allowed_filters.include?(name.to_s)
+    end
+
+    # May this tag run under the current sandbox?
+    #
+    # One gate for every tag, so the allow-list governs the whole tag vocabulary
+    # instead of whichever names somebody remembered to check individually.
+    def tag_permitted?(tag)
+      return true unless @sandbox && @allowed_tags
+      return true unless GATEABLE_TAGS.include?(tag)
+
+      @allowed_tags.include?(tag)
+    end
+
     # Utility: HTML escape
     def self.escape_html(str)
       str.to_s.gsub(HTML_ESCAPE_RE, HTML_ESCAPE_MAP)
@@ -692,6 +737,43 @@ module Tina4
     # Token renderer
     # -----------------------------------------------------------------------
 
+    # Consume a denied tag WITHOUT running it, returning the index past its body.
+    #
+    # Ruby walks a token stream, so a denied tag cannot simply be dropped the way
+    # an AST node can. Advancing by one token would leave the body's tokens to
+    # render at the TOP level, leaking exactly the content the sandbox denied.
+    # Running the handler and discarding its output is no better: handle_set binds
+    # its variable before it returns. Consuming the block gives all three
+    # properties at once -- no output, no side effects, correct index.
+    def skip_block(tokens, i, tag, content)
+      terminator = BLOCK_TAG_ENDS[tag]
+      # {% set x = 1 %} is an assignment and owns no body; {% set x %}...{% endset %}
+      # captures one. Same exact-"=" test the dispatch uses.
+      terminator = nil if tag == "set" && content.include?("=")
+      return i + 1 if terminator.nil?
+
+      depth = 1
+      j = i + 1
+      while j < tokens.length
+        if tokens[j][0] == BLOCK
+          inner = strip_tag(tokens[j][1])[0]
+          case inner.split[0]
+          when tag
+            # A nested assignment-form set opens no body, so it must not nest.
+            depth += 1 unless tag == "set" && inner.include?("=")
+          when terminator
+            depth -= 1
+            return j + 1 if depth.zero?
+          end
+        end
+        j += 1
+      end
+
+      # Unterminated block: consume to the end. Nothing renders, which is the
+      # safe answer -- the alternative leaks the body of a denied tag.
+      tokens.length
+    end
+
     def render_tokens(tokens, context)
       output = []
       i = 0
@@ -725,6 +807,18 @@ module Tina4
 
           tag = content.split[0] || ""
 
+          # ONE sandbox gate for the whole tag vocabulary. Previously only
+          # `include` was checked, so every other tag ignored the allow-list --
+          # {% autoescape false %} could switch escaping off from inside a
+          # sandbox whose tags were restricted to something else entirely.
+          unless tag_permitted?(tag)
+            i = skip_block(tokens, i, tag, content)
+            if strip_a && i < tokens.length && tokens[i][0] == TEXT
+              tokens[i] = [TEXT, tokens[i][1].lstrip]
+            end
+            next
+          end
+
           case tag
           when "if"
             result, i = handle_if(tokens, i, context)
@@ -745,12 +839,8 @@ module Tina4
               i = handle_set_block(tokens, i, context)
             end
           when "include"
-            if @sandbox && @allowed_tags && !@allowed_tags.include?("include")
-              i += 1
-            else
-              output << handle_include(content, context)
-              i += 1
-            end
+            output << handle_include(content, context)
+            i += 1
           when "macro"
             i = handle_macro(tokens, i, context)
           when "import"
@@ -913,14 +1003,16 @@ module Tina4
       is_safe = false
       filters.each do |fname, args|
         if fname == "raw" || fname == "safe"
-          is_safe = true
+          # Decide from what was permitted to RUN, not from what the source
+          # asked for. Marking the value safe here regardless meant a DENIED
+          # raw produced byte-identical output to an allowed one -- the
+          # allow-list entry that governs XSS escaping did nothing at all.
+          is_safe = true if filter_permitted?(fname)
           next
         end
 
         # Sandbox: check filter access
-        if @sandbox && @allowed_filters && !@allowed_filters.include?(fname)
-          next
-        end
+        next if @sandbox && @allowed_filters && !@allowed_filters.include?(fname)
 
         # Filter + property-access chain: `first.groupSummary` — apply
         # the filter, then traverse the path on the result. Done BEFORE

data/lib/tina4/messenger.rb

@@ -71,6 +71,28 @@ module Tina4
   #   mail.send(to: "user@test.com", subject: "Welcome", body: "<h1>Hello!</h1>", html: true, text: "Hello!")
   #
   class Messenger
+    # Factory: returns a Messenger configured for the current environment.
+    #
+    # Returns ONE concrete type, always. It used to return either a Messenger or a
+    # DevMessengerProxy; both happened to expose #send, so Ruby escaped the crash that
+    # nodejs#41 describes by luck of naming rather than by design -- but the proxy's
+    # #send took no text: keyword, so the documented call raised ArgumentError on a dev
+    # messenger. Capture is now a branch inside Messenger#send.
+    #
+    # The gate is availability, not verbosity: capture when no SMTP host is configured,
+    # send when one is EVEN WITH TINA4_DEBUG ON, and TINA4_MAIL_CAPTURE forces capture.
+    def self.create_messenger(**options)
+      mailbox_dir = options.delete(:mailbox_dir) || ENV["TINA4_MAILBOX_DIR"]
+      messenger = Messenger.new(**options)
+      messenger.instance_variable_set(:@mailbox_dir, mailbox_dir)
+
+      # Attach the mailbox eagerly when this messenger will capture, so callers (and
+      # the dev dashboard) can inspect it before the first send.
+      messenger.dev_mailbox = DevMailbox.new(mailbox_dir: mailbox_dir) if messenger.should_capture?
+
+      messenger
+    end
+
     attr_reader :host, :port, :username, :from_address, :from_name,
                 :imap_host, :imap_port, :use_tls, :encryption,
                 :imap_encryption, :imap_use_tls
@@ -80,6 +102,14 @@ module Tina4
     def initialize(host: nil, port: nil, username: nil, password: nil,
                    from_address: nil, from_name: nil, encryption: nil, use_tls: nil,
                    imap_host: nil, imap_port: nil, imap_encryption: nil)
+      # Whether a host was actually CONFIGURED, which is not the same as @host being
+      # set: it falls back to "localhost", so it is never nil and cannot answer
+      # "can this messenger send?". The capture gate needs that answer, so record it
+      # here while the real inputs are still in scope.
+      configured_host = host || ENV["TINA4_MAIL_HOST"]
+      @smtp_configured = !configured_host.nil? && !configured_host.to_s.empty?
+      @mailbox_dir = nil
+      @dev_mailbox = nil
       @host         = host         || ENV["TINA4_MAIL_HOST"]     || "localhost"
       @port         = (port        || ENV["TINA4_MAIL_PORT"]     || 587).to_i
       @username     = username     || ENV["TINA4_MAIL_USERNAME"]
@@ -113,8 +143,47 @@ module Tina4
 
     # Send email using Ruby's Net::SMTP
     # Returns { success: true/false, message: "...", id: "..." }
+    # The local mailbox, present only once this messenger has captured something
+    # (or eagerly, when create_messenger knows it will).
+    attr_accessor :dev_mailbox
+
+    # Should send capture locally instead of talking to SMTP?
+    #
+    # Availability decides, not verbosity. With no SMTP host configured sending is
+    # impossible, so simulate it into a folder rather than failing -- that is what
+    # makes a laptop with no mail server usable, and it is the original Tina4
+    # "messages folder" behaviour restored. TINA4_MAIL_CAPTURE forces capture even
+    # when a host IS configured.
+    #
+    # TINA4_DEBUG deliberately does NOT gate this. Debug must still be able to send:
+    # tying capture to it means nobody can test a real send from a dev box. The old
+    # gate required debug AND no SMTP host, so a dev box with neither set went
+    # straight to localhost:587 and failed.
+    def should_capture?
+      return true if Tina4::Env.is_truthy(ENV["TINA4_MAIL_CAPTURE"])
+
+      !@smtp_configured
+    end
+
+    def dev_mailbox
+      @dev_mailbox ||= DevMailbox.new(mailbox_dir: @mailbox_dir)
+    end
+
     def send(to:, subject:, body:, html: false, text: nil, cc: [], bcc: [],
              reply_to: nil, attachments: [], headers: {})
+      # Dev capture is a BRANCH here, not a different object handed back by the
+      # factory. create_messenger used to return a DevMessengerProxy whose #send had
+      # no text: keyword at all, so the documented call raised ArgumentError and the
+      # plain-text alternative was silently dropped from the captured message.
+      if should_capture?
+        return dev_mailbox.capture(
+          to: to, subject: subject, body: body, html: html, text: text,
+          cc: cc, bcc: bcc, reply_to: reply_to,
+          from_address: @from_address, from_name: @from_name,
+          attachments: attachments
+        )
+      end
+
       message_id = "<#{SecureRandom.uuid}@#{@host}>"
       raw = build_message(
         to: to, subject: subject, body: body, html: html, text: text,
@@ -649,50 +718,4 @@ module Tina4
     end
   end
 
-  # Factory: returns a DevMailbox-intercepting messenger in dev mode,
-  # or a real Messenger in production.
-  def self.create_messenger(**options)
-    dev_mode = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
-
-    smtp_configured = ENV["TINA4_MAIL_HOST"] && !ENV["TINA4_MAIL_HOST"].empty?
-
-    if dev_mode && !smtp_configured
-      mailbox_dir = options.delete(:mailbox_dir) || ENV["TINA4_MAILBOX_DIR"]
-      mailbox = DevMailbox.new(mailbox_dir: mailbox_dir)
-      DevMessengerProxy.new(mailbox, **options)
-    else
-      Messenger.new(**options)
-    end
-  end
-
-  # Proxy that wraps DevMailbox with the same interface as Messenger#send
-  class DevMessengerProxy
-    attr_reader :mailbox
-
-    def initialize(mailbox, **options)
-      @mailbox = mailbox
-      @from_address = options[:from_address] || ENV["TINA4_MAIL_FROM"] || "dev@localhost"
-      @from_name    = options[:from_name]    || ENV["TINA4_MAIL_FROM_NAME"] || "Dev Mailer"
-    end
-
-    def send(to:, subject:, body:, html: false, cc: [], bcc: [],
-             reply_to: nil, attachments: [], headers: {})
-      @mailbox.capture(
-        to: to, subject: subject, body: body, html: html,
-        cc: cc, bcc: bcc, reply_to: reply_to,
-        from_address: @from_address, from_name: @from_name,
-        attachments: attachments
-      )
-    end
-
-    def test_connection
-      { success: true, message: "DevMailbox mode — no SMTP connection needed" }
-    end
-
-    def inbox(**args)  = @mailbox.inbox(**args)
-    def read(...)      = @mailbox.read(...)
-    def unread(...)    = @mailbox.unread_count
-    def search(**args) = @mailbox.inbox(**args)
-    def folders        = ["inbox", "outbox"]
-  end
 end

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.93"
+  VERSION = "3.13.94"
 end

data/lib/tina4.rb

@@ -127,7 +127,18 @@ module Tina4
   autoload :Messenger,           File.expand_path("tina4/messenger", __dir__)
   autoload :MessengerError,      File.expand_path("tina4/messenger", __dir__)
   autoload :MessengerConnectionError, File.expand_path("tina4/messenger", __dir__)
-  autoload :DevMessengerProxy,   File.expand_path("tina4/messenger", __dir__)
+
+  # Factory for a Messenger configured from the environment.
+  #
+  # Defined HERE, eagerly, and not in messenger.rb: `autoload` only fires on a
+  # CONSTANT reference, and a module function is not a constant. A cold
+  # `require "tina4"; Tina4.create_messenger` therefore raised NoMethodError until
+  # something else happened to touch Tina4::Messenger first -- the documented entry
+  # point was unreachable on a fresh process. Naming the constant below is what
+  # triggers the autoload.
+  def self.create_messenger(**options)
+    Tina4::Messenger.create_messenger(**options)
+  end
   autoload :IMAP_CONNECTION_ERRORS, File.expand_path("tina4/messenger", __dir__)
   autoload :DocStore,            File.expand_path("tina4/docstore", __dir__)
   autoload :ScssCompiler,        File.expand_path("tina4/scss_compiler", __dir__)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.93
+  version: 3.13.94
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack