tina4ruby 3.12.3 → 3.12.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 02f359671ab67c2f4d7f3202e8e02f6fcd432690ce034d5951cb84d7c0c297c5
-  data.tar.gz: de61dd0e21ad0c9e979a6049b67d3bba6acfe34ada9540564230a352a71927cf
+  metadata.gz: be4da6079e890067fdf914b4dc287a01f68eeee914a51cd97f13e1d768d3d334
+  data.tar.gz: 61df8b97ae56df7aba1d40feee95d5f0208b969c5166cce97d8e6b65289ed720
 SHA512:
-  metadata.gz: 44af7a12ed2e7cc6175f59549a4984cc24c2e6a411493fc03e7ec7e742179fb162aaea3d85f89ff48989a018f2174b77a7eb12073f05f665fa705784bc698df5
-  data.tar.gz: 677420505af7fbbbe8f5606dd563fbcce96fecb16757ff4d952fe5155b19defbf992d5e86c8bcf9b7449f5082bfcaf742551cb3c3bc92a5312d69e9269b0c31e
+  metadata.gz: c2b2f07c1a30c66c114b7c77845751d6b8125125392cf8adf49689b23378c73d61b79a8882013eeccc6b28ce86dd15121437ec51e228690345c08f32d10572cf
+  data.tar.gz: b63ed9e9ffedece9880e1e57c43e355ec6b8ed4c5418914557ebb163e020728c5b8c0b4cfa41c08f86aae70160b2862eebbc52f128a0116cb6bc700bf4b63105

data/lib/tina4/database.rb

@@ -83,7 +83,7 @@ module Tina4
     }.freeze
 
     # Static factory — cross-framework consistency: Database.create(url)
-    def self.create(url, username: "", password: "", pool: 0)
+    def self.create(url, username: "", password: "", pool: nil)
       new(url, username: username.empty? ? nil : username,
                password: password.empty? ? nil : password,
                pool: pool)
@@ -91,7 +91,7 @@ module Tina4
 
     # Construct a Database from environment variables.
     # Returns nil if the named env var is not set.
-    def self.from_env(env_key: "TINA4_DATABASE_URL", pool: 0)
+    def self.from_env(env_key: "TINA4_DATABASE_URL", pool: nil)
       url = ENV[env_key]
       return nil if url.nil? || url.strip.empty?
 
@@ -101,12 +101,18 @@ module Tina4
           pool: pool)
     end
 
-    def initialize(connection_string = nil, username: nil, password: nil, driver_name: nil, pool: 0)
+    def initialize(connection_string = nil, username: nil, password: nil, driver_name: nil, pool: nil)
       @connection_string = connection_string || ENV["TINA4_DATABASE_URL"]
       @username = username || ENV["TINA4_DATABASE_USERNAME"]
       @password = password || ENV["TINA4_DATABASE_PASSWORD"]
       @driver_name = driver_name || detect_driver(@connection_string)
-      @pool_size = pool  # 0 = single connection, N>0 = N pooled connections
+      # TINA4_DB_POOL falls back when caller doesn't pass `pool:` explicitly.
+      # Default 0 = single connection, N>0 = N pooled connections (round-robin).
+      @pool_size = if pool.nil?
+                     (ENV["TINA4_DB_POOL"] || "0").to_i
+                   else
+                     pool
+                   end
       @connected = false
 
       # Per-instance thread-local key for the transaction adapter pin.

data/lib/tina4/env.rb

@@ -62,7 +62,7 @@ module Tina4
     end
     lines.concat([
                    "",
-                   "Run `tina4 env-migrate` to rewrite your .env automatically,",
+                   "Run `tina4 env --migrate` to rewrite your .env automatically,",
                    "or rename manually. See https://tina4.com/release/3.12.0",
                    "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                    sep, ""
@@ -132,6 +132,12 @@ module Tina4
       private
 
       def resolve_env_file(root_dir)
+        # TINA4_ENV_FILE wins — explicit path or filename (resolved against root_dir).
+        explicit = ENV["TINA4_ENV_FILE"]
+        if explicit && !explicit.empty?
+          return File.absolute_path?(explicit) ? explicit : File.join(root_dir, explicit)
+        end
+
         environment = ENV["ENVIRONMENT"]
         if environment && !environment.empty?
           candidate = File.join(root_dir, ".env.#{environment}")

data/lib/tina4/frond.rb

@@ -190,6 +190,11 @@ module Tina4
     end
 
     # Render a template file with data. Uses token caching for performance.
+    #
+    # Caching strategy:
+    #   * TINA4_DEBUG=true        — never cache (always re-read + re-tokenize).
+    #   * TINA4_TEMPLATE_CACHE_TTL > 0 — cache entries expire after N seconds.
+    #   * TINA4_TEMPLATE_CACHE_TTL == 0 (default in production) — permanent cache.
     def render(template, data = {})
       context = @globals.merge(stringify_keys(data))
 
@@ -197,11 +202,16 @@ module Tina4
       raise "Template not found: #{path}" unless File.exist?(path)
 
       debug_mode = ENV.fetch("TINA4_DEBUG", "").downcase == "true"
+      ttl = (ENV["TINA4_TEMPLATE_CACHE_TTL"] || "0").to_i
 
       unless debug_mode
-        # Production: use permanent cache (no filesystem checks)
         cached = @compiled[template]
-        return execute_cached(cached[0], context) if cached
+        if cached
+          # cached layout: [tokens, mtime, cached_at]
+          tokens, _mtime, cached_at = cached
+          fresh = ttl <= 0 || (Time.now.to_i - cached_at.to_i) < ttl
+          return execute_cached(tokens, context) if fresh
+        end
       end
       # Dev mode: skip cache entirely — always re-read and re-tokenize
       # so edits to partials and extended base templates are detected
@@ -210,7 +220,7 @@ module Tina4
       source = File.read(path, encoding: "utf-8")
       mtime = File.mtime(path)
       tokens = tokenize(source)
-      @compiled[template] = [tokens, mtime]
+      @compiled[template] = [tokens, mtime, Time.now.to_i]
       execute_with_tokens(source, tokens, context)
     end
 

data/lib/tina4/graphql.rb

@@ -845,6 +845,14 @@ module Tina4
   class GraphQL
     attr_reader :schema
 
+    # Class-level toggle for ORM auto-schema generation. Defaults to true,
+    # can be disabled via TINA4_GRAPHQL_AUTO_SCHEMA=false. Initializers and
+    # user app code can branch on this before calling `schema.from_orm(...)`.
+    def self.auto_schema_enabled?
+      val = ENV.fetch("TINA4_GRAPHQL_AUTO_SCHEMA", "true").to_s.strip.downcase
+      !%w[false 0 no off].include?(val)
+    end
+
     def initialize(schema = nil)
       @schema = schema || GraphQLSchema.new
       @executor = GraphQLExecutor.new(@schema)
@@ -916,7 +924,12 @@ module Tina4
     #   gql.register_route           # POST /graphql
     #   gql.register_route("/api/graphql")  # custom path
     #
-    def register_route(path = "/graphql")
+    def register_route(path = nil)
+      # TINA4_GRAPHQL_ENDPOINT — defaults to /graphql when caller doesn't override.
+      path ||= ENV.fetch("TINA4_GRAPHQL_ENDPOINT", "/graphql")
+      path = path.to_s
+      path = "/#{path}" unless path.start_with?("/")
+
       graphql = self
       Tina4.post path, auth: false do |request, response|
         body = request.body

data/lib/tina4/health.rb

@@ -7,8 +7,19 @@ module Tina4
     START_TIME = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
     class << self
+      # Return the configured health endpoint path.
+      # TINA4_HEALTH_PATH overrides the default "/__health" — kept consistent across all 4 frameworks.
+      def path
+        configured = ENV["TINA4_HEALTH_PATH"]
+        return "/__health" if configured.nil? || configured.empty?
+        configured.start_with?("/") ? configured : "/#{configured}"
+      end
+
       def register!
-        Tina4::Router.add("GET", "/health", method(:handle))
+        # Register at the configured path. The legacy "/health" path stays
+        # registered for backward-compat.
+        Tina4::Router.add("GET", path, method(:handle))
+        Tina4::Router.add("GET", "/health", method(:handle)) unless path == "/health"
       end
 
       def handle(_request, response)

data/lib/tina4/log.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "json"
+require "logger"
 
 module Tina4
   module Log
@@ -27,23 +28,74 @@ module Tina4
     # ANSI escape code regex for stripping from file output
     ANSI_RE = /\033\[[0-9;]*m/
 
+    # Defaults used when env vars are unset.
+    DEFAULT_ROTATE_SIZE = 10 * 1024 * 1024 # 10MB
+    DEFAULT_ROTATE_KEEP = 5
+
     class << self
-      attr_reader :log_dir
+      attr_reader :log_dir, :log_file_path
 
       def configure(root_dir = Dir.pwd)
-        @log_dir = File.join(root_dir, "logs")
+        # TINA4_LOG_DIR — relative or absolute. Default "logs".
+        log_dir_env = ENV["TINA4_LOG_DIR"]
+        log_dir_env = "logs" if log_dir_env.nil? || log_dir_env.empty?
+        @log_dir = if File.absolute_path?(log_dir_env)
+                     log_dir_env
+                   else
+                     File.join(root_dir, log_dir_env)
+                   end
         FileUtils.mkdir_p(@log_dir)
 
-        @max_size_mb = (ENV["TINA4_LOG_MAX_SIZE"] || "10").to_i
-        @max_size = @max_size_mb * 1024 * 1024
-        @keep = (ENV["TINA4_LOG_KEEP"] || "5").to_i
-        @json_mode = production?
-        @log_file = File.join(@log_dir, "tina4.log")
+        # TINA4_LOG_FILE — explicit log file path (absolute or relative to log_dir).
+        # Default: <log_dir>/tina4.log.
+        log_file_env = ENV["TINA4_LOG_FILE"]
+        @log_file_path = if log_file_env && !log_file_env.empty?
+                           File.absolute_path?(log_file_env) ? log_file_env : File.join(@log_dir, log_file_env)
+                         else
+                           File.join(@log_dir, "tina4.log")
+                         end
+
+        # TINA4_LOG_ROTATE_SIZE — bytes per file before rotation. 0 = no rotation.
+        @rotate_size = (ENV["TINA4_LOG_ROTATE_SIZE"] || DEFAULT_ROTATE_SIZE).to_i
+        # TINA4_LOG_ROTATE_KEEP — number of rotated backups to keep.
+        @rotate_keep = (ENV["TINA4_LOG_ROTATE_KEEP"] || DEFAULT_ROTATE_KEEP).to_i
+
+        # TINA4_LOG_FORMAT — "text" or "json". Defaults to "json" in production, else "text".
+        format_env = ENV["TINA4_LOG_FORMAT"]
+        @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".
+        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
+
+        # TINA4_LOG_CRITICAL — when true, raise on log write failures instead of swallowing.
+        @critical = truthy?(ENV["TINA4_LOG_CRITICAL"])
 
         @console_level = resolve_level
         @request_id = nil
         @current_context = {}
         @mutex = Mutex.new
+
+        # Build the file logger via stdlib Logger which handles rotation natively.
+        # Logger.new(path, shift_age, shift_size):
+        #   shift_age  = number of files to keep
+        #   shift_size = bytes before rotation
+        # When @rotate_size is 0, omit rotation args.
+        close_file_logger
+        if @output != "stdout"
+          @file_logger = if @rotate_size > 0
+                           ::Logger.new(@log_file_path, @rotate_keep, @rotate_size)
+                         else
+                           ::Logger.new(@log_file_path)
+                         end
+          # We do our own formatting — strip Logger's default formatter.
+          @file_logger.formatter = proc { |_sev, _t, _p, msg| msg.to_s.end_with?("\n") ? msg : "#{msg}\n" }
+        end
+
         @initialized = true
       end
 
@@ -79,8 +131,19 @@ module Tina4
         log(:error, message, context)
       end
 
+      # Test/teardown helper — closes the underlying Logger so the file
+      # handle is released (Windows / tmpdir cleanup).
+      def close_file_logger
+        @file_logger&.close rescue nil
+        @file_logger = nil
+      end
+
       private
 
+      def truthy?(val)
+        %w[true 1 yes on].include?(val.to_s.strip.downcase)
+      end
+
       def production?
         env = ENV["TINA4_ENV"] || ENV["RACK_ENV"] || ENV["RUBY_ENV"] || "development"
         env.downcase == "production"
@@ -92,9 +155,9 @@ module Tina4
 
         formatted = format_line(level, message)
 
-        # Console output respects TINA4_LOG_LEVEL
+        # Console output respects TINA4_LOG_LEVEL and TINA4_LOG_OUTPUT
         severity = SEVERITY_MAP[level] || 0
-        if severity >= @console_level
+        if severity >= @console_level && @output != "file"
           if @json_mode
             $stdout.puts json_line(level, message)
           else
@@ -102,8 +165,11 @@ module Tina4
           end
         end
 
-        # File always gets ALL levels, plain text (no ANSI)
-        write_to_file(strip_ansi(formatted))
+        # File output — always full level (consumer parses themselves) — unless disabled.
+        if @output != "stdout" && @file_logger
+          payload = @json_mode ? json_line(level, message) : strip_ansi(formatted)
+          write_to_file(payload)
+        end
 
         @current_context = {}
       end
@@ -166,37 +232,12 @@ module Tina4
       end
 
       def write_to_file(line)
-        rotate_if_needed
-        begin
-          File.open(@log_file, "a") { |f| f.puts(line) }
-        rescue IOError, SystemCallError
-          # Don't crash on log write failure
-        end
-      end
-
-      # Numbered rotation: tina4.log → tina4.log.1 → tina4.log.2 → ... → tina4.log.{keep}
-      def rotate_if_needed
-        return unless File.exist?(@log_file)
-
-        begin
-          return if File.size(@log_file) < @max_size
-        rescue SystemCallError
-          return
-        end
-
-        # Delete the oldest rotated file if it exists
-        oldest = "#{@log_file}.#{@keep}"
-        File.delete(oldest) if File.exist?(oldest)
-
-        # Shift existing rotated files: .{n} → .{n+1}
-        (@keep - 1).downto(1) do |n|
-          src = "#{@log_file}.#{n}"
-          dst = "#{@log_file}.#{n + 1}"
-          File.rename(src, dst) if File.exist?(src)
-        end
-
-        # Rename current log to .1
-        File.rename(@log_file, "#{@log_file}.1") rescue nil
+        return unless @file_logger
+        # Use << to bypass Logger's severity filtering — we already filtered above.
+        @file_logger << "#{line}\n"
+      rescue IOError, SystemCallError => e
+        raise if @critical
+        # Don't crash on log write failure
       end
     end
   end

data/lib/tina4/mcp.rb

@@ -136,6 +136,30 @@ module Tina4
     ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
   end
 
+  # 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.
+  def self.mcp_enabled?
+    explicit = ENV["TINA4_MCP"]
+    if explicit && !explicit.empty?
+      return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
+    end
+    %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
+  end
+
+  # Resolve the dedicated MCP port. Defaults to (server port + 2000) — keeps
+  # MCP tooling reachable on a stable, predictable channel separate from the
+  # main HTTP port and the AI test port (port + 1000).
+  def self.mcp_port
+    explicit = ENV["TINA4_MCP_PORT"]
+    return explicit.to_i if explicit && !explicit.empty? && explicit.to_i > 0
+
+    base_port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i
+    base_port + 2000
+  end
+
   # ── McpServer ─────────────────────────────────────────────────────
   class McpServer
     attr_reader :path, :name, :version

data/lib/tina4/messenger.rb

@@ -36,13 +36,14 @@ module Tina4
   #
   class Messenger
     attr_reader :host, :port, :username, :from_address, :from_name,
-                :imap_host, :imap_port, :use_tls, :encryption
+                :imap_host, :imap_port, :use_tls, :encryption,
+                :imap_encryption, :imap_use_tls
 
     # Initialize with SMTP config.
     # Priority: constructor params > ENV (TINA4_MAIL_*) > sensible defaults
     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_host: nil, imap_port: nil, imap_encryption: nil)
       @host         = host         || ENV["TINA4_MAIL_HOST"]     || "localhost"
       @port         = (port        || ENV["TINA4_MAIL_PORT"]     || 587).to_i
       @username     = username     || ENV["TINA4_MAIL_USERNAME"]
@@ -53,7 +54,7 @@ module Tina4
 
       @from_name    = from_name    || ENV["TINA4_MAIL_FROM_NAME"] || ""
 
-      # Encryption: constructor > .env > backward-compat use_tls > default "tls"
+      # SMTP encryption: constructor > .env > backward-compat use_tls > default "tls"
       env_encryption = encryption  || ENV["TINA4_MAIL_ENCRYPTION"]
       if env_encryption
         @encryption = env_encryption.downcase
@@ -66,6 +67,12 @@ module Tina4
 
       @imap_host    = imap_host    || ENV["TINA4_MAIL_IMAP_HOST"] || @host
       @imap_port    = (imap_port   || ENV["TINA4_MAIL_IMAP_PORT"] || 993).to_i
+
+      # IMAP encryption: dedicated env var TINA4_MAIL_IMAP_ENCRYPTION (tls/starttls/none).
+      # Defaults to "tls" — IMAPS over implicit TLS on port 993 is the safe industry norm.
+      env_imap_enc = imap_encryption || ENV["TINA4_MAIL_IMAP_ENCRYPTION"]
+      @imap_encryption = (env_imap_enc && !env_imap_enc.to_s.empty?) ? env_imap_enc.to_s.downcase : "tls"
+      @imap_use_tls    = %w[tls starttls ssl].include?(@imap_encryption)
     end
 
     # Send email using Ruby's Net::SMTP
@@ -387,7 +394,7 @@ module Tina4
     # ── IMAP helpers ─────────────────────────────────────────────────────
 
     def imap_connect(&block)
-      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @use_tls)
+      imap = Net::IMAP.new(@imap_host, port: @imap_port, ssl: @imap_use_tls)
       imap.login(@username, @password)
       result = block.call(imap)
       imap.logout

data/lib/tina4/router.rb

@@ -328,6 +328,14 @@ module Tina4
         nil
       end
 
+      # When TINA4_TRAILING_SLASH_REDIRECT is truthy, the rack app uses this
+      # to detect whether the *original* (un-stripped) path differed from the
+      # canonical form so it can issue a 301 redirect. Default false — silent
+      # match keeps backward compatibility.
+      def trailing_slash_redirect?
+        %w[true 1 yes on].include?(ENV.fetch("TINA4_TRAILING_SLASH_REDIRECT", "").to_s.strip.downcase)
+      end
+
       # Find a route matching method + path. Returns [route, params] or nil.
       # match(method, path) — consistent with Python, PHP, and Node.
       def match(method, path)

data/lib/tina4/session.rb

@@ -16,6 +16,11 @@ module Tina4
 
     def initialize(env, options = {})
       @options = DEFAULT_OPTIONS.merge(options)
+      # TINA4_SESSION_NAME — overrides cookie_name unless caller explicitly passed one.
+      env_name = ENV["TINA4_SESSION_NAME"]
+      if !options.key?(:cookie_name) && env_name && !env_name.empty?
+        @options[:cookie_name] = env_name
+      end
       @options[:secret] ||= ENV["TINA4_SECRET"] || "tina4-default-secret"
       @handler = create_handler
       @id = extract_session_id(env) || SecureRandom.hex(32)
@@ -151,7 +156,17 @@ module Tina4
     def cookie_header(cookie_name = nil)
       name = cookie_name || @options[:cookie_name]
       samesite = ENV["TINA4_SESSION_SAMESITE"] || "Lax"
-      "#{name}=#{@id}; Path=/; HttpOnly; SameSite=#{samesite}; Max-Age=#{@options[:max_age]}"
+      # HttpOnly defaults to true (existing behaviour); flip off only when explicitly false.
+      httponly = !%w[false 0 no off].include?((ENV["TINA4_SESSION_HTTPONLY"] || "true").to_s.strip.downcase)
+      # Secure defaults to false; flip on with truthy env var.
+      secure = %w[true 1 yes on].include?((ENV["TINA4_SESSION_SECURE"] || "false").to_s.strip.downcase)
+
+      parts = ["#{name}=#{@id}", "Path=/"]
+      parts << "HttpOnly" if httponly
+      parts << "Secure" if secure
+      parts << "SameSite=#{samesite}"
+      parts << "Max-Age=#{@options[:max_age]}"
+      parts.join("; ")
     end
 
     private

data/lib/tina4/swagger.rb

@@ -13,16 +13,44 @@ module Tina4
         spec
       end
 
+      # TINA4_SWAGGER_ENABLED — defaults to TINA4_DEBUG. When false, callers
+      # can choose to skip mounting /swagger entirely in production.
+      def enabled?
+        explicit = ENV["TINA4_SWAGGER_ENABLED"]
+        if explicit && !explicit.empty?
+          return %w[true 1 yes on].include?(explicit.to_s.strip.downcase)
+        end
+        %w[true 1 yes on].include?(ENV.fetch("TINA4_DEBUG", "").to_s.strip.downcase)
+      end
+
       private
 
       def base_spec
+        info = {
+          "title" => ENV["TINA4_SWAGGER_TITLE"] || ENV["PROJECT_NAME"] || "Tina4 API",
+          "version" => ENV["TINA4_SWAGGER_VERSION"] || Tina4::VERSION,
+          "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || "Auto-generated API documentation"
+        }
+
+        # Optional contact block — only emitted when at least one field is set.
+        contact_email = ENV["TINA4_SWAGGER_CONTACT_EMAIL"]
+        contact_team  = ENV["TINA4_SWAGGER_CONTACT_TEAM"] || ENV["SWAGGER_CONTACT_TEAM"]
+        contact_url   = ENV["TINA4_SWAGGER_CONTACT_URL"]  || ENV["SWAGGER_CONTACT_URL"]
+        contact = {}
+        contact["email"] = contact_email if contact_email && !contact_email.empty?
+        contact["name"]  = contact_team  if contact_team  && !contact_team.empty?
+        contact["url"]   = contact_url   if contact_url   && !contact_url.empty?
+        info["contact"] = contact unless contact.empty?
+
+        # Optional license block — TINA4_SWAGGER_LICENSE is the SPDX name (e.g. "MIT").
+        license_name = ENV["TINA4_SWAGGER_LICENSE"]
+        if license_name && !license_name.empty?
+          info["license"] = { "name" => license_name }
+        end
+
         {
           "openapi" => "3.0.3",
-          "info" => {
-            "title" => ENV["TINA4_SWAGGER_TITLE"] || ENV["PROJECT_NAME"] || "Tina4 API",
-            "version" => ENV["TINA4_SWAGGER_VERSION"] || Tina4::VERSION,
-            "description" => ENV["TINA4_SWAGGER_DESCRIPTION"] || "Auto-generated API documentation"
-          },
+          "info" => info,
           "servers" => [
             { "url" => "/" }
           ],

data/lib/tina4/version.rb

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

data/lib/tina4/webserver.rb

@@ -2,10 +2,16 @@
 
 module Tina4
   class WebServer
-    def initialize(app, host: "0.0.0.0", port: 7147)
+    DEFAULT_HOST = "0.0.0.0"
+    DEFAULT_PORT = 7147
+
+    # TINA4_HOST overrides the bind address when caller doesn't pass `host:`.
+    def initialize(app, host: nil, port: nil)
       @app = app
-      @host = host
-      @port = port
+      env_host = ENV["TINA4_HOST"]
+      @host = host || (env_host && !env_host.empty? ? env_host : DEFAULT_HOST)
+      env_port = ENV["TINA4_PORT"] || ENV["PORT"]
+      @port = port || (env_port && !env_port.empty? ? env_port.to_i : DEFAULT_PORT)
     end
 
     # Kill whatever process is listening on *port*.

data/lib/tina4.rb

@@ -119,6 +119,9 @@ module Tina4
     attr_accessor :root_dir, :database
 
     def print_banner(host: "0.0.0.0", port: 7147, server_name: nil)
+      # TINA4_SUPPRESS — short-circuit ALL banner output for headless / CI runs.
+      return if Tina4::Env.is_truthy(ENV["TINA4_SUPPRESS"])
+
       is_tty = $stdout.respond_to?(:isatty) && $stdout.isatty
       color = is_tty ? "\e[31m" : ""
       reset = is_tty ? "\e[0m" : ""

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.12.3
+  version: 3.12.4
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-05 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack