tina4ruby 3.13.38 → 3.13.40

data/lib/tina4/env.rb

@@ -62,8 +62,13 @@ module Tina4
     end
     lines.concat([
                    "",
-                   "Run `tina4 env --migrate` to rewrite your .env automatically,",
-                   "or rename manually. See https://tina4.com/release/3.12.0",
+                   "Note: these may come from a .env file loaded by dotenv, not just",
+                   "the runtime environment - check your image / build context (a .env",
+                   "baked into a Docker image is loaded at startup) as well as k8s/CI env.",
+                   "",
+                   "FIX: run `tina4 env --migrate` to rewrite your .env automatically",
+                   "(it renames every legacy name to its TINA4_ form in place).",
+                   "Or rename manually. See https://tina4.com/release/3.12.0",
                    "Set TINA4_ALLOW_LEGACY_ENV=true to bypass during migration.",
                    sep, ""
                  ])

data/lib/tina4/field_types.rb

@@ -20,8 +20,11 @@ module Tina4
           @table_name = name
         else
           base = self.name.split("::").last.downcase
-          # Pluralize by default (add "s") unless ORM_PLURAL_TABLE_NAMES is explicitly disabled
-          unless ENV.fetch("TINA4_ORM_PLURAL_TABLE_NAMES", "").match?(/\A(false|0|no)\z/i)
+          # Pluralization is OFF by default (canonical, matching the Python
+          # master): the table name is the bare class name lowercased. Opt in by
+          # setting TINA4_ORM_PLURAL_TABLE_NAMES to a truthy value (true/1/yes/on)
+          # to append "s".
+          if ENV.fetch("TINA4_ORM_PLURAL_TABLE_NAMES", "").match?(/\A(true|1|yes|on)\z/i)
             base += "s" unless base.end_with?("s")
           end
           @table_name || base

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

@@ -131,23 +131,76 @@ module Tina4
     schema
   end
 
-  # Check if the server is running on localhost.
+  # Informational only — whether the CONFIGURED host looks local.
+  #
+  # NOT the security gate. This reads TINA4_HOST_NAME (the configured bind
+  # address), which on a 0.0.0.0 bind looks "local" while still accepting
+  # remote clients. Trust decisions use {request_allowed?} with the RAW
+  # socket peer instead. Kept for diagnostics / back-compat.
   def self.is_localhost?
     host = ENV.fetch("TINA4_HOST_NAME", "localhost:7145").split(":").first
     ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
   end
 
-  # Resolve whether the built-in MCP dev server should be active.
+  # Whether an address is a loopback (in-process / same-host) peer.
+  #
+  # Operates on the RAW socket peer, never X-Forwarded-For. Empty means an
+  # in-process / synthetic request (no socket) and is trusted. The `::ffff:`
+  # IPv4-mapped prefix is stripped. NOTE: 0.0.0.0 is a BIND address, never a
+  # client address, so it is deliberately NOT loopback.
+  #
+  # Python master parity: tina4_python.mcp.is_loopback.
+  def self.is_loopback?(ip)
+    return true if ip.nil? || ip.to_s.empty?
+
+    addr = ip.to_s.strip.downcase
+    addr = addr[7..] if addr.start_with?("::ffff:")
+    addr == "::1" || addr == "localhost" || addr.start_with?("127.")
+  end
+
+  # Capability gate — whether the MCP subsystem may run at all.
   #
-  # Precedence:
-  #   * TINA4_MCP set explicitly → use that (truthy/falsey).
-  #   * Otherwise: enabled only when TINA4_DEBUG=true.
+  # Pure capability, host-INDEPENDENT (Python master parity):
+  #   1. TINA4_MCP set explicitly → use it (sysadmin override, any host).
+  #   2. Else TINA4_DEBUG truthy → MCP is a capability of this deployment.
+  #   3. Otherwise off.
+  #
+  # This NO LONGER consults the host. A debug box bound to 0.0.0.0 still "has"
+  # the capability, but {request_allowed?} is what decides whether a given
+  # CALLER may use it — loopback always, remote only with an explicit opt-in
+  # plus a valid token. Splitting capability from per-request authorisation
+  # closes the hole where a 0.0.0.0 bind auto-exposed DB/file tools to remote
+  # unauthenticated callers (pre-3.13.40 is_localhost? treated 0.0.0.0 local).
   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)
+
+    truthy?(ENV["TINA4_DEBUG"])
+  end
+
+  # Per-request authorisation — whether THIS caller may use MCP.
+  #
+  # @param remote_ip [String] raw socket peer (env["REMOTE_ADDR"]), never XFF.
+  # @param has_valid_token [Boolean] true when the request carried a token
+  #   matching TINA4_MCP_TOKEN.
+  #
+  # Rules (Python master parity, tina4_python.mcp.is_request_allowed):
+  #   - Capability off ({mcp_enabled?} false) → deny.
+  #   - Loopback peer → allow.
+  #   - Remote peer → only when TINA4_MCP_REMOTE is truthy AND a valid token
+  #     was presented. No configured token ⇒ remote can never pass.
+  def self.request_allowed?(remote_ip, has_valid_token: false)
+    return false unless mcp_enabled?
+    return true if is_loopback?(remote_ip)
+
+    truthy?(ENV["TINA4_MCP_REMOTE"]) && has_valid_token
+  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
@@ -573,9 +626,27 @@ module Tina4
         err = looks_like_prose.call(rel_path)
         raise ArgumentError, "Invalid path #{rel_path.inspect}: #{err}" if err
         resolved = File.expand_path(rel_path, project_root)
-        unless resolved.start_with?(project_root)
+        # Compare against root + separator, not a bare prefix: a plain
+        # start_with?(project_root) would also accept a sibling like
+        # "<root>-evil". expand_path already resolves ".." so a climb-out
+        # lands outside root and is rejected here.
+        root_prefix = "#{project_root.chomp(File::SEPARATOR)}#{File::SEPARATOR}"
+        unless resolved == project_root || resolved.start_with?(root_prefix)
           raise ArgumentError, "Path escapes project directory: #{rel_path}"
         end
+        # Belt-and-braces against symlink escapes: if the path already exists,
+        # canonicalise it and re-check containment. A symlink inside the tree
+        # pointing outside would otherwise slip past the textual check. New
+        # paths (parent not created yet) have no realpath and rely on the
+        # expand_path containment above.
+        if File.exist?(resolved)
+          real = File.realpath(resolved)
+          real_root = File.realpath(project_root)
+          real_prefix = "#{real_root.chomp(File::SEPARATOR)}#{File::SEPARATOR}"
+          unless real == real_root || real.start_with?(real_prefix)
+            raise ArgumentError, "Path escapes project directory: #{rel_path}"
+          end
+        end
         resolved
       end
 
@@ -643,7 +714,22 @@ 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.fetch(sql, param_list)
+        param_list = [] unless param_list.is_a?(Array)
+        # Defense-in-depth: this tool is read-only. Strip comments, reject
+        # multiple statements, and require a leading SELECT/WITH so it can
+        # never mutate data even if reached (database_execute is the write
+        # surface, gated separately). Mirrors the Python master.
+        cleaned = sql.to_s.gsub(/--[^\r\n]*/, " ").gsub(%r{/\*.*?\*/}m, " ")
+        cleaned = cleaned.strip.sub(/[;\s]+\z/, "")
+        return { "error" => "database_query rejects multiple statements" } if cleaned.include?(";")
+        unless cleaned =~ /\A(select|with)\b/i
+          return { "error" => "database_query is read-only (SELECT/WITH only)" }
+        end
+        begin
+          result = db.fetch(cleaned, param_list)
+        rescue => e
+          return { "error" => (db.get_error rescue nil) || e.message }
+        end
         { "records" => result.to_a, "count" => result.count }
       }, "Execute a read-only SQL query (SELECT)")
 
@@ -672,6 +758,12 @@ module Tina4
       server.register_tool("database_columns", lambda { |table:|
         db = Tina4.database
         return { "error" => "No database connection" } if db.nil?
+        # Constrain the table name to a safe identifier (optionally
+        # schema-qualified) — defense-in-depth so it can never be abused for
+        # injection even if an adapter interpolates it. Parity with Python/PHP.
+        unless table.to_s =~ /\A[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?\z/
+          return { "error" => "Invalid table name" }
+        end
         db.columns(table)
       }, "Get column definitions for a table")
 

data/lib/tina4/metrics.rb

@@ -649,7 +649,10 @@ module Tina4
 
     # Top-level class/module names defined in the file at rel_path (resolved
     # against the last scan root when present). Distinctive names only:
-    # leading-uppercase, longer than 3 chars.
+    # leading-uppercase, longer than 2 chars — so genuine 3-char constants like
+    # ORM (orm.rb) and API (api.rb), which specs reference as `Tina4::ORM` /
+    # `Tina4::API`, are detected as tested instead of being mislabelled
+    # untested. (Was > 3, which silently excluded every 3-char constant.)
     def self._defined_constants(rel_path)
       src_file = if @last_scan_root && !@last_scan_root.empty? && !File.exist?(rel_path)
                    File.join(@last_scan_root, rel_path)
@@ -667,7 +670,7 @@ module Tina4
         m = stripped.match(/\A(?:class|module)\s+([A-Z][A-Za-z0-9_]*)/)
         next unless m
         const = m[1]
-        symbols.add(const) if const.length > 3
+        symbols.add(const) if const.length > 2
       end
       symbols
     end
@@ -702,8 +705,61 @@ module Tina4
       imports
     end
 
-    def self._extract_functions(source, tokens, lines)
+    # Replace the CONTENT of Ruby string literals, regex literals, and comments
+    # with neutral spaces — keeping every line's length and the line count
+    # identical to the original — so decision-point keywords and method-shaped
+    # text that live INSIDE strings/comments are never miscounted. Returns an
+    # array of cleaned lines (chomped) aligned 1:1 with the original lines.
+    #
+    # Ruby's own lexer (Ripper) does the hard parsing: it tags string/heredoc/
+    # regex bodies as :on_tstring_content (and :on_comment, :on_embdoc — the
+    # =begin/=end block-comment body), which we blank out positionally. The
+    # surrounding code structure (def/if/end keywords, operators) is left intact.
+    NOISE_TOKEN_TYPES = %i[
+      on_tstring_content on_comment on_embdoc on_embdoc_beg on_embdoc_end
+    ].freeze
+
+    def self._clean_source(source)
+      lines = source.lines.map(&:chomp)
+      # Mutable per-line character buffers we can blank out by column range.
+      buffers = lines.map(&:dup)
+
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines
+      end
+
+      tokens.each do |(pos, type, token)|
+        next unless NOISE_TOKEN_TYPES.include?(type)
+
+        row = pos[0] - 1
+        col = pos[1]
+        # A noise token may span multiple physical lines (heredocs, block
+        # comments, multi-line strings). Blank each covered line segment.
+        token.to_s.each_line.with_index do |seg, offset|
+          line_idx = row + offset
+          next if line_idx.negative? || line_idx >= buffers.length
+
+          buf = buffers[line_idx]
+          # On the token's first line the content starts at `col`; on
+          # continuation lines it starts at column 0.
+          start = offset.zero? ? col : 0
+          seg_len = seg.chomp.length
+          stop = [start + seg_len, buf.length].min
+          (start...stop).each { |c| buf[c] = ' ' } if stop > start
+        end
+      end
+
+      buffers
+    end
+
+    def self._extract_functions(source, _tokens, _lines)
       functions = []
+      # Operate on a neutralised copy: string/regex/comment CONTENT is blanked
+      # so keywords inside them are never read as real code (line numbers, line
+      # count and column widths are preserved).
+      lines = _clean_source(source)
       # Track class/module nesting for method names
       context_stack = []
       i = 0
@@ -718,7 +774,8 @@ module Tina4
           context_stack.push(class_name) unless class_name.empty?
         end
 
-        # Detect method definitions
+        # Detect method definitions — require a real `def ` declaration so a
+        # `def`-shaped substring inside a (now-blanked) string is never a method.
         if stripped.match?(/\Adef\s+/)
           method_match = stripped.match(/\Adef\s+(self\.)?(\S+?)(\(.*\))?\s*$/)
           if method_match
@@ -779,43 +836,73 @@ module Tina4
       functions
     end
 
+    # Keywords that ALWAYS open a block needing a matching `end`.
+    BLOCK_OPENERS = %w[def class module begin case].freeze
+    # Keywords that open a block ONLY in statement-leading position; in trailing
+    # position they are modifiers (`return x if y`) and need no `end`.
+    CONDITIONAL_OPENERS = %w[if unless while until for].freeze
+
+    # Find the line index where the method that starts at `start_index` ends.
+    #
+    # Token-driven (Ripper) so it is immune to the line-regex footguns that made
+    # this over-run to end-of-file (CC 496 on tiny methods):
+    #   * `self.class` — `class` after a `.` is an identifier, not a block opener
+    #     (Ripper tags it :on_ident), so it no longer bumps depth.
+    #   * modifier `if/unless/while/until/for` (`return x if y`) — only counted
+    #     as an opener in statement-LEADING position (first real token of a
+    #     statement), never trailing.
+    #   * `lines` are already string/comment-cleaned, so keywords inside string
+    #     bodies are gone too.
+    # Falls back to the last line only if no matching `end` is found.
     def self._find_method_end(lines, start_index)
-      depth = 0
-      i = start_index
-      base_indent = lines[i].length - lines[i].lstrip.length
+      source = lines[start_index..].join("\n")
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines.length - 1
+      end
 
-      while i < lines.length
-        stripped = lines[i].strip
+      depth = 0
+      # A keyword is a block opener only when it leads a statement. Track that:
+      # we are at statement start initially and right after a newline / `;`.
+      at_statement_start = true
+      seen_opener = false
 
-        unless stripped.empty? || stripped.start_with?('#')
-          # Count block openers
-          if stripped.match?(/\b(def|class|module|if|unless|case|while|until|for|begin|do)\b/) &&
-             !stripped.match?(/\bend\b/) &&
-             !stripped.end_with?(' if ', ' unless ', ' while ', ' until ') &&
-             !(stripped.match?(/\bif\b|\bunless\b|\bwhile\b|\buntil\b/) && i != start_index && _is_modifier?(stripped))
+      tokens.each do |(pos, type, token)|
+        case type
+        when :on_kw
+          if BLOCK_OPENERS.include?(token)
             depth += 1
-          end
-
-          if stripped == 'end' || stripped.start_with?('end ') || stripped.start_with?('end;')
+            seen_opener = true
+          elsif token == 'do'
+            depth += 1
+            seen_opener = true
+          elsif CONDITIONAL_OPENERS.include?(token)
+            # Leading => real block opener; trailing => modifier (no end).
+            if at_statement_start
+              depth += 1
+              seen_opener = true
+            end
+          elsif token == 'end'
             depth -= 1
-            return i if depth <= 0
+            if seen_opener && depth <= 0
+              return start_index + (pos[0] - 1)
+            end
           end
+          at_statement_start = false
+        when :on_nl, :on_ignored_nl, :on_semicolon
+          at_statement_start = true
+        when :on_sp, :on_comment, :on_embdoc, :on_embdoc_beg, :on_embdoc_end
+          # whitespace/comments don't change statement-start state
+        else
+          at_statement_start = false
         end
-
-        i += 1
       end
 
       # If we never found the end, return last line
       lines.length - 1
     end
 
-    def self._is_modifier?(line)
-      # A rough check: if the keyword is not at the start of the meaningful content,
-      # it's likely a modifier (e.g., "return x if condition")
-      stripped = line.strip
-      !stripped.match?(/\A(if|unless|while|until)\b/)
-    end
-
     def self._cyclomatic_complexity_from_source(source)
       cc = 1