tina4ruby 3.11.35 → 3.12.0

data/lib/tina4/env.rb

@@ -2,14 +2,85 @@
 require "digest"
 
 module Tina4
+  # Legacy env var names that v3.12 has retired. If any of these are set in
+  # the environment we refuse to boot — silently ignoring them would cause
+  # auth/db/mail to fall back to defaults with no warning. Each maps to its
+  # new TINA4_-prefixed canonical name.
+  LEGACY_ENV_VARS = {
+    "DATABASE_URL"           => "TINA4_DATABASE_URL",
+    "DATABASE_USERNAME"      => "TINA4_DATABASE_USERNAME",
+    "DATABASE_PASSWORD"      => "TINA4_DATABASE_PASSWORD",
+    "DB_URL"                 => "TINA4_DATABASE_URL",
+    "SECRET"                 => "TINA4_SECRET",
+    "API_KEY"                => "TINA4_API_KEY",
+    "JWT_ALGORITHM"          => "TINA4_JWT_ALGORITHM",
+    "SMTP_HOST"              => "TINA4_MAIL_HOST",
+    "SMTP_PORT"              => "TINA4_MAIL_PORT",
+    "SMTP_USERNAME"          => "TINA4_MAIL_USERNAME",
+    "SMTP_PASSWORD"          => "TINA4_MAIL_PASSWORD",
+    "SMTP_FROM"              => "TINA4_MAIL_FROM",
+    "SMTP_FROM_NAME"         => "TINA4_MAIL_FROM_NAME",
+    "IMAP_HOST"              => "TINA4_MAIL_IMAP_HOST",
+    "IMAP_PORT"              => "TINA4_MAIL_IMAP_PORT",
+    "IMAP_USER"              => "TINA4_MAIL_IMAP_USERNAME",
+    "IMAP_PASS"              => "TINA4_MAIL_IMAP_PASSWORD",
+    "HOST_NAME"              => "TINA4_HOST_NAME",
+    "SWAGGER_TITLE"          => "TINA4_SWAGGER_TITLE",
+    "SWAGGER_DESCRIPTION"    => "TINA4_SWAGGER_DESCRIPTION",
+    "SWAGGER_VERSION"        => "TINA4_SWAGGER_VERSION",
+    "ORM_PLURAL_TABLE_NAMES" => "TINA4_ORM_PLURAL_TABLE_NAMES"
+  }.freeze
+
+  # Raised by check_legacy_env_vars! when the caller opts out of process exit.
+  class LegacyEnvError < StandardError; end
+
+  # Refuse to boot if pre-3.12 un-prefixed env vars are still set.
+  #
+  # Tina4 v3.12 hard-renamed every framework-specific env var to use the
+  # TINA4_ prefix. Booting silently with a legacy DATABASE_URL or SECRET
+  # would let auth, DB, or mail fall back to insecure defaults while the
+  # user thought their config was being read. Better to die loudly with a
+  # list of names to fix.
+  #
+  # Bypass with TINA4_ALLOW_LEGACY_ENV=true in CI / migration scripts that
+  # genuinely need both names set during a transition window.
+  def self.check_legacy_env_vars!(io: $stderr, exit_on_error: true)
+    bypass = ENV["TINA4_ALLOW_LEGACY_ENV"].to_s.downcase
+    return if %w[true 1 yes].include?(bypass)
+
+    found = LEGACY_ENV_VARS.keys.select { |name| ENV.key?(name) }.sort
+    return if found.empty?
+
+    sep = "─" * 72
+    lines = ["", sep,
+             "Tina4 v3.12 requires TINA4_ prefix on all framework env vars.",
+             "Your environment still has these legacy names:",
+             ""]
+    found.each do |old|
+      new_name = LEGACY_ENV_VARS[old]
+      lines << format("    %-28s  →  %s", old, new_name)
+    end
+    lines.concat([
+                   "",
+                   "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, ""
+                 ])
+    io.puts lines.join("\n")
+    raise LegacyEnvError, "Legacy env vars present: #{found.join(', ')}" unless exit_on_error
+
+    exit(2)
+  end
+
   module Env
     DEFAULT_ENV = {
       "PROJECT_NAME" => "Tina4 Ruby Project",
-      "VERSION" => "1.0.0",
+      "TINA4_SWAGGER_VERSION" => "1.0.0",
       "TINA4_LOCALE" => "en",
       "TINA4_DEBUG" => "true",
       "TINA4_LOG_LEVEL" => "[TINA4_LOG_ALL]",
-      "SECRET" => "tina4-secret-change-me"
+      "TINA4_SECRET" => "tina4-secret-change-me"
     }.freeze
 
     # Check if a value is truthy for env boolean checks.
@@ -72,7 +143,7 @@ module Tina4
       def create_default_env(path)
         api_key = Digest::MD5.hexdigest(Time.now.to_s)
         content = DEFAULT_ENV.map { |k, v| "#{k}=\"#{v}\"" }.join("\n")
-        content += "\nAPI_KEY=\"#{api_key}\"\n"
+        content += "\nTINA4_API_KEY=\"#{api_key}\"\n"
         File.write(path, content)
       end
 

data/lib/tina4/field_types.rb

@@ -21,7 +21,7 @@ module Tina4
         else
           base = self.name.split("::").last.downcase
           # Pluralize by default (add "s") unless ORM_PLURAL_TABLE_NAMES is explicitly disabled
-          unless ENV.fetch("ORM_PLURAL_TABLE_NAMES", "").match?(/\A(false|0|no)\z/i)
+          unless ENV.fetch("TINA4_ORM_PLURAL_TABLE_NAMES", "").match?(/\A(false|0|no)\z/i)
             base += "s" unless base.end_with?("s")
           end
           @table_name || base

data/lib/tina4/frond.rb

@@ -548,6 +548,20 @@ module Tina4
       value = eval_expr(var_name, context)
       filters.each do |fname, args|
         next if fname == "raw" || fname == "safe"
+
+        # Filter + property-access chain: `first.groupSummary` — apply
+        # the filter, then traverse the path on the result using a
+        # synthetic context so eval_expr's dotted resolution does the
+        # work. Parity with tina4-python + tina4-php.
+        real_fname, tail_path = split_filter_name_and_path(fname)
+        if !tail_path.empty? && @filters[real_fname]
+          evaluated_args = args.map { |a| eval_filter_arg(a, context) }
+          value = @filters[real_fname].call(value, *evaluated_args)
+          value = eval_expr("__frond_filter_tmp.#{tail_path}",
+                            { "__frond_filter_tmp" => value })
+          next
+        end
+
         fn = @filters[fname]
         if fn
           evaluated_args = args.map { |a| eval_filter_arg(a, context) }
@@ -611,6 +625,19 @@ module Tina4
           next
         end
 
+        # Filter + property-access chain: `first.groupSummary` — apply
+        # the filter, then traverse the path on the result. Done BEFORE
+        # the inline fast-path so cases like `items|first.name` work
+        # regardless of whether `first` is an inline filter too.
+        real_fname, tail_path = split_filter_name_and_path(fname)
+        if !tail_path.empty? && @filters[real_fname]
+          evaluated_args = args.map { |a| eval_filter_arg(a, context) }
+          value = @filters[real_fname].call(value, *evaluated_args)
+          value = eval_expr("__frond_filter_tmp.#{tail_path}",
+                            { "__frond_filter_tmp" => value })
+          next
+        end
+
         # Inline common no-arg filters for speed (skip generic dispatch)
         if args.empty? && INLINE_FILTERS.include?(fname)
           value = case fname
@@ -756,6 +783,41 @@ module Tina4
     # Filter chain parser
     # -----------------------------------------------------------------------
 
+    # Split "first.groupSummary" into ["first", "groupSummary"] so a
+    # filter segment followed by property access — `{{ x | first.name }}`
+    # — applies the filter then traverses the path on the result.
+    # Returns [fname, ""] when no structural dot is present.
+    #
+    # The split point must sit outside parens/brackets/braces and quotes
+    # so filter args like `round(1.5)` or `date("Y.m.d")` don't false-
+    # trigger. Parity with tina4-python and tina4-php.
+    def split_filter_name_and_path(fname)
+      depth = 0
+      in_q  = nil
+      i     = 0
+      n     = fname.length
+      while i < n
+        ch = fname[i]
+        if in_q
+          in_q = nil if ch == in_q && (i.zero? || fname[i - 1] != "\\")
+          i += 1
+          next
+        end
+        case ch
+        when '"', "'"
+          in_q = ch
+        when "(", "[", "{"
+          depth += 1
+        when ")", "]", "}"
+          depth -= 1
+        when "."
+          return [fname[0...i], fname[(i + 1)..]] if depth.zero?
+        end
+        i += 1
+      end
+      [fname, ""]
+    end
+
     def parse_filter_chain(expr)
       cached = @filter_chain_cache[expr]
       return cached if cached

data/lib/tina4/mcp.rb

@@ -132,7 +132,7 @@ module Tina4
 
   # Check if the server is running on localhost.
   def self.is_localhost?
-    host = ENV.fetch("HOST_NAME", "localhost:7145").split(":").first
+    host = ENV.fetch("TINA4_HOST_NAME", "localhost:7145").split(":").first
     ["localhost", "127.0.0.1", "0.0.0.0", "::1", ""].include?(host)
   end
 
@@ -680,6 +680,196 @@ module Tina4
         end
       }, "Seed a table with fake data")
 
+      # ── File patch ────────────────────────────────────
+      server.register_tool("file_patch", lambda { |path:, old_string:, new_string:, count: 1|
+        p = safe_path.call(path)
+        return { "error" => "File not found: #{path}" } unless File.file?(p)
+        original = File.read(p, encoding: "utf-8")
+        occurrences = original.scan(old_string).size
+        return { "error" => "old_string not found in #{path}" } if occurrences.zero?
+        if occurrences != count.to_i
+          return { "error" => "old_string appears #{occurrences} times, expected #{count}. Expand old_string to make it unique, or set count explicitly." }
+        end
+        updated = original.sub(old_string, new_string)
+        # Ruby String#sub replaces first; if count > 1, do N replacements
+        if count.to_i > 1
+          updated = original.dup
+          count.to_i.times { updated.sub!(old_string, new_string) }
+        end
+        File.write(p, updated, encoding: "utf-8")
+        rel = p.sub("#{project_root}/", "")
+        Tina4::Plan.record_action("patched", rel) if defined?(Tina4::Plan)
+        { "patched" => rel, "replacements" => count.to_i, "bytes" => updated.bytesize }
+      }, "Targeted edit: replace old_string with new_string in a file")
+
+      # ── Docs tools ────────────────────────────────────
+      framework_doc_paths = lambda do
+        gem_root = File.expand_path("..", File.dirname(__FILE__))
+        candidates = [
+          File.join(gem_root, "..", "CLAUDE.md"),
+          File.join(gem_root, "..", "AGENTS.md"),
+          File.join(gem_root, "..", "CONVENTIONS.md"),
+          File.join(gem_root, "..", "README.md"),
+          File.join(Dir.pwd, "CLAUDE.md")
+        ]
+        candidates.map { |p| File.expand_path(p) }.uniq.select { |p| File.file?(p) }
+      end
+
+      server.register_tool("docs_list", lambda {
+        framework_doc_paths.call.map { |p| { "name" => File.basename(p), "bytes" => File.size(p) } }
+      }, "List framework documentation files")
+
+      server.register_tool("docs_search", lambda { |query:, limit: 5, context_lines: 4|
+        return { "error" => "query must be at least 2 characters" } if query.to_s.length < 2
+        needle = query.to_s.downcase
+        hits = []
+        framework_doc_paths.call.each do |p|
+          begin
+            lines = File.read(p, encoding: "utf-8", invalid: :replace, undef: :replace).split("\n")
+          rescue StandardError
+            next
+          end
+          lines.each_with_index do |line, i|
+            next unless line.downcase.include?(needle)
+            start_i = [0, i - context_lines.to_i].max
+            end_i   = [lines.size, i + context_lines.to_i + 1].min
+            score = 1
+            score += 1 if line.include?(query.to_s)
+            score += 2 if line.lstrip.start_with?("#")
+            hits << {
+              "file" => File.basename(p),
+              "line" => i + 1,
+              "score" => score,
+              "snippet" => lines[start_i...end_i].join("\n")
+            }
+          end
+        end
+        hits.sort_by! { |h| -h["score"] }
+        hits.first([1, limit.to_i].max)
+      }, "Search Tina4 framework docs for a query string")
+
+      server.register_tool("docs_section", lambda { |file:, heading:|
+        match = framework_doc_paths.call.find { |p| File.basename(p) == file }
+        return { "error" => "Unknown doc file: #{file}. Try docs_list() first." } unless match
+        text = File.read(match, encoding: "utf-8", invalid: :replace, undef: :replace)
+        lines = text.split("\n")
+        heading_lc = heading.to_s.downcase.strip
+        start_i = -1
+        start_level = 0
+        lines.each_with_index do |line, i|
+          stripped = line.lstrip
+          next unless stripped.start_with?("#")
+          level = stripped.length - stripped.sub(/\A#+/, "").length
+          title = stripped[level..].to_s.strip.downcase
+          if title.include?(heading_lc)
+            start_i = i
+            start_level = level
+            break
+          end
+        end
+        return { "error" => "Heading '#{heading}' not found in #{file}" } if start_i < 0
+        end_i = lines.size
+        (start_i + 1).upto(lines.size - 1) do |j|
+          stripped = lines[j].lstrip
+          next unless stripped.start_with?("#")
+          level = stripped.length - stripped.sub(/\A#+/, "").length
+          if level <= start_level
+            end_i = j
+            break
+          end
+        end
+        { "file" => file, "heading" => lines[start_i].strip, "body" => lines[start_i...end_i].join("\n") }
+      }, "Return a full markdown section from a framework doc file")
+
+      # ── Git / deps / project ──────────────────────────
+      server.register_tool("git_status", lambda {
+        Tina4::DevAdmin.send(:git_status_payload)
+      }, "Show git branch, modified/untracked files, recent commits")
+
+      server.register_tool("deps_list", lambda {
+        gemfile = File.join(Dir.pwd, "Gemfile")
+        return { "error" => "No Gemfile at project root" } unless File.file?(gemfile)
+        deps = File.read(gemfile).scan(/^\s*gem\s+["']([^"']+)["']/).flatten
+        { "name" => File.basename(Dir.pwd), "dependencies" => deps }
+      }, "List this project's declared Ruby dependencies")
+
+      server.register_tool("project_overview", lambda {
+        { "system" => { "framework" => "tina4-ruby", "version" => (defined?(Tina4::VERSION) ? Tina4::VERSION : "unknown"), "ruby" => RUBY_DESCRIPTION, "cwd" => project_root } }
+      }, "One-shot snapshot: system + project info")
+
+      # ── Project index ─────────────────────────────────
+      server.register_tool("index_rebuild", lambda {
+        Tina4::ProjectIndex.refresh
+      }, "Refresh the persistent project index (lazy, mtime-based)")
+
+      server.register_tool("index_search", lambda { |query:, limit: 20|
+        Tina4::ProjectIndex.search(query, limit.to_i)
+      }, "Find files by path, symbol, route, or summary")
+
+      server.register_tool("index_file", lambda { |path:|
+        Tina4::ProjectIndex.file_entry(path)
+      }, "Full index entry for one file")
+
+      server.register_tool("index_overview", lambda {
+        Tina4::ProjectIndex.overview
+      }, "Project shape: files by language, routes, models, recent edits")
+
+      # ── Plan management ───────────────────────────────
+      server.register_tool("plan_current", lambda {
+        Tina4::Plan.current
+      }, "The active plan: title, steps (done/not), next step, progress")
+
+      server.register_tool("plan_list", lambda {
+        Tina4::Plan.list_plans
+      }, "All plans in plan/ with progress and which one is active")
+
+      server.register_tool("plan_create", lambda { |title:, goal: "", steps: nil, make_current: true|
+        Tina4::Plan.create(title, goal: goal, steps: steps, make_current: make_current)
+      }, "Create a new markdown plan in plan/ and make it active")
+
+      server.register_tool("plan_switch_to", lambda { |name:|
+        Tina4::Plan.set_current(name)
+      }, "Make a different plan the active one")
+
+      server.register_tool("plan_complete_step", lambda { |index:|
+        Tina4::Plan.complete_step(index.to_i)
+      }, "Tick a step as done (call the moment the step finishes)")
+
+      server.register_tool("plan_add_step", lambda { |text:|
+        Tina4::Plan.add_step(text)
+      }, "Append a new unchecked step to the current plan")
+
+      server.register_tool("plan_note", lambda { |text:|
+        Tina4::Plan.append_note(text)
+      }, "Append a timestamped note/breadcrumb to the current plan")
+
+      server.register_tool("plan_archive", lambda { |name: ""|
+        Tina4::Plan.archive(name)
+      }, "Move a finished plan to plan/done/")
+
+      server.register_tool("plan_read", lambda { |name:|
+        Tina4::Plan.read(name)
+      }, "Full structured view of any plan by filename")
+
+      server.register_tool("plan_flesh", lambda { |name: "", prompt: ""|
+        Tina4::Plan.flesh(name, prompt)
+      }, "Auto-generate concrete build steps via AI and append them to an existing plan")
+
+      # ── Live API Docs (Live API RAG) ──────────────────
+      server.register_tool("api_search", lambda { |query:, k: 5, source: "all", include_private: false|
+        Tina4::Docs.cached(project_root).search(
+          query.to_s, k: k.to_i, source: source.to_s, include_private: include_private == true || include_private.to_s == "true"
+        )
+      }, "Search the live API index (framework + user code) for ranked hits")
+
+      server.register_tool("api_class", lambda { |name:|
+        Tina4::Docs.cached(project_root).class_spec(name.to_s)
+      }, "Full class reflection (methods, file, line) from the live API index")
+
+      server.register_tool("api_method", lambda { |class_name:, name:|
+        Tina4::Docs.cached(project_root).method_spec(class_name.to_s, name.to_s)
+      }, "Single method spec (signature, summary, file, line) from the live API index")
+
       # ── System Tools ──────────────────────────────────
       server.register_tool("system_info", lambda {
         {

data/lib/tina4/messenger.rb

@@ -18,7 +18,7 @@ module Tina4
   # Tina4 Messenger — Email sending (SMTP) and reading (IMAP).
   #
   # Unified .env-driven configuration with constructor override.
-  # Priority: constructor params > .env (TINA4_MAIL_* with SMTP_* fallback) > sensible defaults
+  # Priority: constructor params > .env (TINA4_MAIL_*) > sensible defaults
   #
   #   # .env
   #   TINA4_MAIL_HOST=smtp.gmail.com
@@ -39,19 +39,19 @@ module Tina4
                 :imap_host, :imap_port, :use_tls, :encryption
 
     # Initialize with SMTP config.
-    # Priority: constructor params > ENV (TINA4_MAIL_* with SMTP_* fallback) > sensible defaults
+    # 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)
-      @host         = host         || ENV["TINA4_MAIL_HOST"]     || ENV["SMTP_HOST"]     || "localhost"
-      @port         = (port        || ENV["TINA4_MAIL_PORT"]     || ENV["SMTP_PORT"]     || 587).to_i
-      @username     = username     || ENV["TINA4_MAIL_USERNAME"] || ENV["SMTP_USERNAME"]
-      @password     = password     || ENV["TINA4_MAIL_PASSWORD"] || ENV["SMTP_PASSWORD"]
+      @host         = host         || ENV["TINA4_MAIL_HOST"]     || "localhost"
+      @port         = (port        || ENV["TINA4_MAIL_PORT"]     || 587).to_i
+      @username     = username     || ENV["TINA4_MAIL_USERNAME"]
+      @password     = password     || ENV["TINA4_MAIL_PASSWORD"]
 
-      resolved_from = from_address || ENV["TINA4_MAIL_FROM"]     || ENV["SMTP_FROM"]
+      resolved_from = from_address || ENV["TINA4_MAIL_FROM"]
       @from_address = resolved_from || @username || "noreply@localhost"
 
-      @from_name    = from_name    || ENV["TINA4_MAIL_FROM_NAME"] || ENV["SMTP_FROM_NAME"] || ""
+      @from_name    = from_name    || ENV["TINA4_MAIL_FROM_NAME"] || ""
 
       # Encryption: constructor > .env > backward-compat use_tls > default "tls"
       env_encryption = encryption  || ENV["TINA4_MAIL_ENCRYPTION"]
@@ -64,8 +64,8 @@ module Tina4
       end
       @use_tls = %w[tls starttls].include?(@encryption)
 
-      @imap_host    = imap_host    || ENV["TINA4_MAIL_IMAP_HOST"] || ENV["IMAP_HOST"] || @host
-      @imap_port    = (imap_port   || ENV["TINA4_MAIL_IMAP_PORT"] || ENV["IMAP_PORT"] || 993).to_i
+      @imap_host    = imap_host    || ENV["TINA4_MAIL_IMAP_HOST"] || @host
+      @imap_port    = (imap_port   || ENV["TINA4_MAIL_IMAP_PORT"] || 993).to_i
     end
 
     # Send email using Ruby's Net::SMTP
@@ -542,8 +542,7 @@ module Tina4
   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?) ||
-                      (ENV["SMTP_HOST"] && !ENV["SMTP_HOST"].empty?)
+    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"]
@@ -560,8 +559,8 @@ module Tina4
 
     def initialize(mailbox, **options)
       @mailbox = mailbox
-      @from_address = options[:from_address] || ENV["TINA4_MAIL_FROM"] || ENV["SMTP_FROM"] || "dev@localhost"
-      @from_name    = options[:from_name]    || ENV["TINA4_MAIL_FROM_NAME"] || ENV["SMTP_FROM_NAME"] || "Dev Mailer"
+      @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: [],

data/lib/tina4/orm.rb

@@ -52,15 +52,31 @@ module Tina4
         @field_mapping = map
       end
 
-      # Auto-map flag (no-op in Ruby since snake_case is native)
+      # Auto-map flag — defaults to TRUE for cross-framework parity (Python's
+      # ORM has auto_map=True by default). The instance variable is treated
+      # as "unset" when nil; only an explicit `false` disables it.
       def auto_map
-        @auto_map || false
+        defined?(@auto_map) && !@auto_map.nil? ? @auto_map : true
       end
 
       def auto_map=(val)
         @auto_map = val
       end
 
+      # auto_crud flag — when set to true, the class registers itself with
+      # Tina4::AutoCrud which auto-generates REST endpoints from the model.
+      # Defaults to false. Cross-framework parity with Python's autoCrud.
+      def auto_crud
+        defined?(@auto_crud) && !@auto_crud.nil? ? @auto_crud : false
+      end
+
+      def auto_crud=(val)
+        @auto_crud = val
+        if val && defined?(::Tina4::AutoCrud)
+          ::Tina4::AutoCrud.models << self unless ::Tina4::AutoCrud.models.include?(self)
+        end
+      end
+
       # Relationship definitions
       def relationship_definitions
         @relationship_definitions ||= {}
@@ -343,8 +359,10 @@ module Tina4
         instance
       end
 
-      private
-
+      # find_by_id is PUBLIC — cross-framework parity with Python's
+      # MyModel.find_by_id(pk_value) and PHP's User::find($id). Spec at
+      # spec/orm_spec.rb:78 verifies public access. find_by_filter stays
+      # public for the same reason; both are part of the documented API.
       def find_by_id(id)
         pk = primary_key_field || :id
         sql = "SELECT * FROM #{table_name} WHERE #{pk} = ?"
@@ -354,6 +372,34 @@ module Tina4
         select_one(sql, [id])
       end
 
+      # Clear the relationship cache on all loaded instances (class-level helper).
+      # Useful after bulk operations when you want to force relationship re-loads.
+      def clear_rel_cache # -> nil
+        @_rel_cache = {}
+        nil
+      end
+
+      # Return the database connection used by this model.
+      def get_db # -> Database
+        db
+      end
+
+      # Map a Ruby property name to its database column name using field_mapping.
+      # Returns the column name as a symbol.
+      def get_db_column(property) # -> Symbol
+        col = field_mapping[property.to_s] || property
+        col.to_sym
+      end
+
+      private
+
+      def auto_discover_db
+        url = ENV["TINA4_DATABASE_URL"]
+        return nil unless url
+        Tina4.database = Tina4::Database.new(url, username: ENV.fetch("TINA4_DATABASE_USERNAME", ""), password: ENV.fetch("TINA4_DATABASE_PASSWORD", ""))
+        Tina4.database
+      end
+
       def find_by_filter(filter)
         where_parts = filter.keys.map { |k| "#{k} = ?" }
         sql = "SELECT * FROM #{table_name} WHERE #{where_parts.join(' AND ')}"
@@ -474,15 +520,30 @@ module Tina4
       errors
     end
 
-    def load(id = nil)
-      pk = self.class.primary_key_field || :id
-      id ||= __send__(pk)
-      return false unless id
+    # load — populate this instance from the database.
+    #
+    # Three forms (parity with Python's model.load(sql, params, include)):
+    #   user.load                                   # reload by primary key from instance
+    #   user.load(123)                              # load by primary key value
+    #   user.load("email = ?", ["a@b.c"])           # load by filter SQL + params (selectOne)
+    #
+    # Returns true on hit, false on miss. Always clears the relationship cache.
+    def load(arg = nil, params = nil)
       @relationship_cache = {} # Clear relationship cache on reload
+      pk = self.class.primary_key_field || :id
 
-      result = self.class.db.fetch_one(
-        "SELECT * FROM #{self.class.table_name} WHERE #{pk} = ?", [id]
-      )
+      if arg.is_a?(String)
+        # Filter-SQL form: user.load("email = ?", ["a@b.c"])
+        sql = "SELECT * FROM #{self.class.table_name} WHERE #{arg} LIMIT 1"
+        result = self.class.db.fetch_one(sql, params || [])
+      else
+        # Primary-key form: user.load OR user.load(123)
+        id = arg || __send__(pk)
+        return false unless id
+        result = self.class.db.fetch_one(
+          "SELECT * FROM #{self.class.table_name} WHERE #{pk} = ?", [id]
+        )
+      end
       return false unless result
 
       mapping_reverse = self.class.field_mapping.invert
@@ -505,7 +566,10 @@ module Tina4
 
     # Convert to hash using Ruby attribute names.
     # Optionally include relationships via the include keyword.
-    def to_h(include: nil)
+    # case: "camel" converts snake_case keys to camelCase (parity with
+    # Python's to_dict(case='camel')). Default keeps native snake_case.
+    def to_h(include: nil, case: nil)
+      key_case = binding.local_variable_get(:case)  # :case is a reserved word
       hash = {}
       self.class.field_definitions.each_key do |name|
         hash[name] = __send__(name)
@@ -534,6 +598,15 @@ module Tina4
         end
       end
 
+      if key_case == "camel" || key_case == :camel
+        # snake_case → camelCase: split on _, capitalize all but the first
+        hash = hash.each_with_object({}) do |(k, v), out|
+          parts = k.to_s.split("_")
+          camel = parts[0] + parts[1..].map(&:capitalize).join
+          out[camel.to_sym] = v
+        end
+      end
+
       hash
     end