tina4ruby 3.13.136 → 3.13.138

data/lib/tina4/api.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "net/http"
 require "openssl"
 require "uri"
 require "json"
-require "base64"
+require_relative "base64"
 require "securerandom"
+require_relative "parse_json"
 
 module Tina4
   # Statuses that warrant an automatic retry when max_retries > 0: rate-limit
@@ -258,6 +265,7 @@ module Tina4
       headers = @headers.dup
       cookie = cookie_header
       headers["Cookie"] = cookie if @cookies_enabled && cookie
+      headers = origin_headers(uri, headers)
 
       return download_via_transport(uri, headers, dest_path) if @transport
 
@@ -277,7 +285,7 @@ module Tina4
     end
 
     def set_basic_auth(username, password)
-      @headers["Authorization"] = "Basic #{Base64.strict_encode64("#{username}:#{password}")}"
+      @headers["Authorization"] = "Basic #{Tina4::Base64.strict_encode64("#{username}:#{password}")}"
       self
     end
 
@@ -451,6 +459,10 @@ module Tina4
       apply_headers(request, headers || {})
       cookie = cookie_header
       request["Cookie"] = cookie if @cookies_enabled && cookie
+      unless same_origin?(uri, URI.parse(@base_url))
+        request.delete("Authorization")
+        request.delete("Cookie")
+      end
       if body
         request.body = body.is_a?(String) ? body : JSON.generate(body)
         request["Content-Type"] = content_type if content_type
@@ -458,12 +470,22 @@ module Tina4
         request["Content-Type"] = content_type
       end
 
+      # ADR-0060: connect_timeout (else TINA4_API_CONNECT_TIMEOUT, else 10s)
+      # bounds establishment and raises Net::OpenTimeout; timeout (else
+      # TINA4_API_TIMEOUT, else the client timeout) bounds the WHOLE stream and
+      # raises APIStreamTimeoutError. Both are Timeout::Error. `timeout` used to
+      # be only Net::HTTP's per-read idle timeout, so a server that kept
+      # dripping data streamed forever.
+      connect_bound = connect_timeout || stream_env_seconds("TINA4_API_CONNECT_TIMEOUT", 10.0)
+      total_bound = timeout || stream_env_seconds("TINA4_API_TIMEOUT", @timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + total_bound
+
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
       http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
-      http.open_timeout = connect_timeout || @timeout
-      http.read_timeout = timeout || @timeout
-      http.write_timeout = (timeout || @timeout) if http.respond_to?(:write_timeout=)
+      http.open_timeout = [connect_bound, total_bound].min
+      http.read_timeout = total_bound
+      http.write_timeout = total_bound if http.respond_to?(:write_timeout=)
 
       http.start do |conn|
         conn.request(request) do |response|
@@ -473,9 +495,26 @@ module Tina4
             raise APIStreamError.new("stream returned HTTP #{status}", status)
           end
           store_cookies(response.get_fields("Set-Cookie"))
-          response.read_body { |chunk| yield chunk }
+          response.read_body do |chunk|
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise APIStreamTimeoutError, "stream exceeded its total timeout of #{total_bound}s" unless remaining.positive?
+
+            # The next read may wait only for what is left of the deadline.
+            # tina4: bounded per read, so a server dripping single bytes inside
+            # one chunk header can overrun by one read at most.
+            conn.read_timeout = remaining
+            yield chunk
+          end
         end
       end
+    rescue Net::ReadTimeout, Net::WriteTimeout
+      raise APIStreamTimeoutError, "stream exceeded its total timeout of #{total_bound}s"
+    end
+
+    # A positive number of seconds from an env var; anything else falls back.
+    def stream_env_seconds(name, fallback)
+      seconds = Float(ENV[name].to_s.strip, exception: false)
+      seconds&.positive? ? seconds : fallback
     end
 
     def build_uri(path, params = {})
@@ -488,6 +527,10 @@ module Tina4
       uri
     end
 
+    def origin_headers(uri, headers)
+      same_origin?(uri, URI.parse(@base_url)) ? headers : strip_cross_origin(headers)
+    end
+
     def apply_headers(request, extra_headers)
       @headers.merge(extra_headers).each do |key, value|
         request[key] = value
@@ -523,6 +566,7 @@ module Tina4
       request.each_header { |key, value| headers[key] = value }
       cookie = cookie_header
       headers["cookie"] = cookie if @cookies_enabled && cookie
+      headers = origin_headers(uri, headers)
       body = request.body
 
       if @transport
@@ -803,6 +847,12 @@ module Tina4
     end
   end
 
+  # A stream_* call ran past its total timeout (timeout:, else
+  # TINA4_API_TIMEOUT). A Timeout::Error, as Python's ApiTimeoutError is a
+  # TimeoutError, and deliberately NOT an APIStreamError: callers such as
+  # AiClient treat APIStreamError as an HTTP status failure.
+  class APIStreamTimeoutError < Timeout::Error; end
+
   class APIResponse
     attr_reader :status, :body, :headers, :error, :path
 
@@ -821,7 +871,7 @@ module Tina4
     end
 
     def json
-      @json ||= JSON.parse(@body)
+      @json ||= Tina4.parse_json(@body)
     rescue JSON::ParserError, TypeError
       {}
     end

data/lib/tina4/auth.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "openssl"
-require "base64"
+require_relative "base64"
 require "json"
 require "fileutils"
 require "securerandom"
+require_relative "parse_json"
+require_relative "secret_file"
 
 module Tina4
   module Auth
@@ -100,12 +108,10 @@ module Tina4
           local_path = File.join(root_dir, ".env.local")
           # If the file exists and does not end in a newline, prepend one so the
           # new key lands on its own line rather than gluing onto the last value.
-          prefix = ""
-          if File.exist?(local_path)
-            content = File.read(local_path)
-            prefix = "\n" if !content.empty? && !content.end_with?("\n")
+          SecretFile.update(local_path) do |content|
+            prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+            content + "#{prefix}TINA4_SECRET=#{new_secret}\n"
           end
-          File.open(local_path, "a") { |f| f.write("#{prefix}TINA4_SECRET=#{new_secret}\n") }
           log_info("Auth: generated a development secret, saved to .env.local (gitignored)")
         rescue StandardError => e
           # Keep the in-memory secret for this run; just warn. Never crash boot.
@@ -139,7 +145,7 @@ module Tina4
 
       # Base64url-encode without padding (JWT spec)
       def base64url_encode(data)
-        Base64.urlsafe_encode64(data, padding: false)
+        Tina4::Base64.urlsafe_encode64(data, padding: false)
       end
 
       # Base64url-decode (handles missing padding)
@@ -147,7 +153,7 @@ module Tina4
         # Add back padding
         remainder = str.length % 4
         str += "=" * ((4 - remainder) % 4) if remainder != 0
-        Base64.urlsafe_decode64(str)
+        Tina4::Base64.urlsafe_decode64(str)
       end
 
       # Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else
@@ -200,10 +206,10 @@ module Tina4
       def decode_envelope(token, algorithm)
         parts = token.to_s.split(".")
         return nil unless parts.length == 3
-        return nil unless JSON.parse(base64url_decode(parts[0]))["alg"] == algorithm
+        return nil unless Tina4.parse_json(base64url_decode(parts[0]))["alg"] == algorithm
         return nil unless yield("#{parts[0]}.#{parts[1]}", base64url_decode(parts[2]))
 
-        payload = JSON.parse(base64url_decode(parts[1]))
+        payload = Tina4.parse_json(base64url_decode(parts[1]))
         now = Time.now.to_i
 
         # RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that the
@@ -361,7 +367,7 @@ module Tina4
         return nil unless parts.length == 3
 
         payload_json = base64url_decode(parts[1])
-        JSON.parse(payload_json)
+        Tina4.parse_json(payload_json)
       rescue ArgumentError, JSON::ParserError
         nil
       end
@@ -564,7 +570,7 @@ module Tina4
       def generate_keys
         Tina4::Log.info("Generating RSA key pair for JWT authentication")
         key = OpenSSL::PKey::RSA.generate(2048)
-        File.write(private_key_path, key.to_pem)
+        SecretFile.update(private_key_path) { key.to_pem }
         File.write(public_key_path, key.public_key.to_pem)
         @private_key = nil
         @public_key = nil

data/lib/tina4/auto_crud.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 
 module Tina4
@@ -105,17 +111,46 @@ module Tina4
             page     = [page, 1].max
             limit    = per_page
             offset   = req.query["offset"] ? req.query["offset"].to_i : (page - 1) * per_page
-            order_by = parse_sort(req.query["sort"])
 
-            # Filter support: ?filter[field]=value
+            # Filter support: ?filter[field]=value. ADR-0069: ANY bracket key is
+            # captured and must resolve to a declared field (attribute or its
+            # mapped column); an unknown key is a 400 before any SQL runs.
+            #
+            # The query parser keeps bracketed keys flat, so a list or map shows
+            # up as "sort[...]" or "filter[name][...]": a 400, never ignored.
+            if req.query.keys.any? { |key| key.start_with?("sort[") }
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Query parameter 'sort' must be a single comma-separated string", 400)
+            end
+
             filter_conditions = []
             filter_values = []
+            unknown_filter_field = nil
+            nested_filter_field = nil
             req.query.each do |key, value|
-              if key =~ /\Afilter\[(\w+)\]\z/
-                filter_conditions << "#{$1} = ?"
-                filter_values << value
+              next unless key =~ /\Afilter\[(.*)\]\z/m
+
+              filter_key = Regexp.last_match(1)
+              if filter_key.include?("][")
+                nested_filter_field = filter_key.split("][", 2).first
+                break
               end
+              column = model_class.resolve_field_column(filter_key)
+              unless column
+                unknown_filter_field = filter_key
+                break
+              end
+              filter_conditions << "#{column} = ?"
+              filter_values << value
+            end
+            if nested_filter_field
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Filter value for '#{nested_filter_field}' must be a single value", 400)
             end
+            next res.error("UNKNOWN_FIELD", "Unknown filter field '#{unknown_filter_field}'", 400) if unknown_filter_field
+
+            order_by, unknown_sort_field = parse_sort(model_class, req.query["sort"])
+            next res.error("UNKNOWN_FIELD", "Unknown sort field '#{unknown_sort_field}'", 400) if unknown_sort_field
 
             if filter_conditions.empty?
               records = model_class.all(limit: limit, offset: offset, order_by: order_by)
@@ -150,8 +185,7 @@ module Tina4
         # GET /api/{table}/{id} -- get single record
         Tina4::Router.add("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             if record
               res.json({ data: record.to_h })
             else
@@ -200,8 +234,7 @@ module Tina4
         # PUT /api/{table}/{id} -- update record
         put_route = Tina4::Router.add("PUT", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -236,8 +269,7 @@ module Tina4
         # DELETE /api/{table}/{id} -- delete record
         delete_route = Tina4::Router.add("DELETE", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -314,27 +346,51 @@ module Tina4
         auto_increment = single_pk && defs[single_pk.to_sym] && defs[single_pk.to_sym][:auto_increment]
         strip_pk = is_create ? !(single_pk && !auto_increment) : true
 
+        # ADR-0069: a body key is written only when it resolves to a DECLARED
+        # field, by attribute name or its mapped column - the SAME resolver the
+        # list route's filter/sort use. Anything else is dropped (writes drop,
+        # reads 400).
         data.each_with_object({}) do |(key, value), allowed|
-          key_s = key.to_s
-          next unless defs.key?(key_s.to_sym)
-          next if key_s == "is_deleted"
-          next if strip_pk && pk_fields.include?(key_s)
+          attribute = model_class.resolve_field(key)
+          next unless attribute
 
-          allowed[key] = value
+          attribute_name = attribute.to_s
+          next if attribute_name == "is_deleted"
+          next if strip_pk && pk_fields.include?(attribute_name)
+
+          allowed[attribute_name] = value
         end
       end
 
-      # Parse sort parameter: "-name,created_at" => "name DESC, created_at ASC"
-      def parse_sort(sort_str)
-        return nil if sort_str.nil? || sort_str.empty?
-        sort_str.split(",").map do |field|
-          field = field.strip
-          if field.start_with?("-")
-            "#{field[1..-1]} DESC"
-          else
-            "#{field} ASC"
-          end
-        end.join(", ")
+      # The row a URL {id} addresses, or nil. The id is bound, never
+      # interpolated; ORM.coerce_primary_key keeps a string natural key as-is
+      # and answers nil for a non-integer id on an integer key (-> 404).
+      def find_addressed_record(model_class, raw_id)
+        id = model_class.coerce_primary_key(raw_id)
+        id.nil? ? nil : model_class.find_by_id(id)
+      end
+
+      # Parse the sort parameter: "-name,created_at" => "name DESC, created_at ASC".
+      #
+      # ADR-0069: each part (empty parts skipped, a leading "-" means DESC) must
+      # resolve to a declared field; the ORDER BY is built ONLY from resolved
+      # columns plus ASC/DESC. Returns [order_by_or_nil, unknown_field_or_nil].
+      def parse_sort(model_class, sort_str)
+        return [nil, nil] if sort_str.nil? || sort_str.empty?
+
+        parts = []
+        sort_str.split(",").each do |part|
+          part = part.strip
+          next if part.empty?
+
+          descending = part.start_with?("-")
+          field = descending ? part[1..].strip : part
+          column = model_class.resolve_field_column(field)
+          return [nil, field] unless column
+
+          parts << "#{column} #{descending ? 'DESC' : 'ASC'}"
+        end
+        [parts.empty? ? nil : parts.join(", "), nil]
       end
     end
   end

data/lib/tina4/background.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # Periodic background task registry.
@@ -9,7 +15,7 @@ module Tina4
   #
   # Ruby has no asyncio event loop, so each task runs in its own dedicated OS
   # thread, started at registration time. Because the thread runs regardless of
-  # which web server (Puma/WEBrick) is in front, a Ruby background task is never
+  # which web server (the built-in server or Puma) is in front, a Ruby background task is never
   # a silent no-op under production — the thread IS the runtime (contrast the
   # Python ASGI / PHP-FPM silent-no-op the other frameworks had to fix). The GIL
   # keeps it cooperative-enough for the periodic work this is meant for (queue

data/lib/tina4/base64.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+
+module Tina4
+  # Base64 on core Array#pack / String#unpack1, so Tina4 needs no base64 gem.
+  #
+  # The base64 gem stopped being a default gem in Ruby 3.4, and a bundled gem an
+  # app does not declare is not on the load path under Bundler. The gem is itself
+  # a thin wrapper over pack("m"), so this module keeps its method names and its
+  # exact semantics (same bytes out, same ArgumentError on bad strict input) and
+  # the call sites read the same with a Tina4:: prefix.
+  module Base64
+    module_function
+
+    # RFC 2045 (MIME): a newline after every 60 encoded characters and at the end.
+    def encode64(binary)
+      [binary].pack("m")
+    end
+
+    # Lenient decode: characters outside the alphabet are skipped, never raised on.
+    def decode64(string)
+      string.unpack1("m")
+    end
+
+    # RFC 4648: no line feeds.
+    def strict_encode64(binary)
+      [binary].pack("m0")
+    end
+
+    # Raises ArgumentError on anything that is not canonical, padded base64.
+    def strict_decode64(string)
+      string.unpack1("m0")
+    end
+
+    # RFC 4648 URL-safe alphabet ("-" and "_"), padding optional.
+    def urlsafe_encode64(binary, padding: true)
+      encoded = strict_encode64(binary)
+      encoded.chomp!("==") or encoded.chomp!("=") unless padding
+      encoded.tr!("+/", "-_")
+      encoded
+    end
+
+    # Accepts padded or unpadded input; raises ArgumentError on invalid input.
+    def urlsafe_decode64(string)
+      if !string.end_with?("=") && string.length % 4 != 0
+        string = string.ljust((string.length + 3) & ~3, "=")
+        string.tr!("-_", "+/")
+      else
+        string = string.tr("-_", "+/")
+      end
+      strict_decode64(string)
+    end
+  end
+end

data/lib/tina4/cache.rb

@@ -1,3 +1,9 @@
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 module Tina4
   # In-memory TTL cache with tag-based invalidation.
   #

data/lib/tina4/cache_backends/base_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   module CacheBackends

data/lib/tina4/cache_backends/database_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require_relative "base_backend"

data/lib/tina4/cache_backends/file_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "fileutils"

data/lib/tina4/cache_backends/memcached_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "socket"

data/lib/tina4/cache_backends/memory_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "base_backend"
 

data/lib/tina4/cache_backends/mongo_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "uri"

data/lib/tina4/cache_backends/redis_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "socket"

data/lib/tina4/cache_backends/valkey_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "redis_backend"
 

data/lib/tina4/cache_backends.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "cache_backends/base_backend"
 require_relative "cache_backends/memory_backend"

data/lib/tina4/cli.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "optparse"
 require "fileutils"
@@ -8,6 +14,7 @@ require "tmpdir"    # Dir.mktmpdir — used by the ADR-0063 sandbox edit-hint sc
 require "stringio"  # StringIO — captures generator stdout during the sandbox run
 require "open3"     # Open3.capture2e — captures `ruby -c` output+status for `lint`
 require_relative "port_takeover"
+require_relative "env"       # Tina4::Env.is_truthy -- resolve_config runs before lib/tina4 loads
 
 module Tina4
   class CLI
@@ -676,7 +683,7 @@ module Tina4
         # invokes PHP. That mismatch is why Ruby could not be launched through
         # the shared launcher the other frameworks use.
         opts.on("--managed", "Running under the tina4 CLI supervisor") { options[:managed] = true }
-        opts.on("--production", "Use production server (Puma)") { options[:production] = true }
+        opts.on("--production", "Production mode: Puma if the app bundles it, else the built-in server") { options[:production] = true }
         opts.on("--no-browser", "Do not open browser on start") { options[:no_browser] = true }
         opts.on("--no-reload", "Disable file watcher / live-reload") { options[:no_reload] = true }
         opts.on("--no-kill", "Never take over the port from a stale dev server") { options[:no_kill] = true }
@@ -727,9 +734,9 @@ module Tina4
 
       is_debug = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
 
-      # Use Puma only when explicitly requested via --production flag
-      # WEBrick is used for development (supports dev toolbar/reload)
-      # Same production server, same shutdown contract as Tina4.run! - one
+      # Puma only with --production AND only when the app bundles it
+      # (ADR-0067); otherwise Tina4's built-in server, in development and
+      # production alike. Same production server, same shutdown contract as Tina4.run! - one
       # implementation, so the two entry points cannot drift again (the old
       # copy here claimed "we handle DB cleanup" and did no cleanup at all).
       # TINA4_DEFAULT_WEBSERVER=TRUE pins the built-in server even with
@@ -739,7 +746,6 @@ module Tina4
         return
       end
 
-      Tina4::Log.info("Development server: WEBrick")
       server = Tina4::WebServer.new(app, host: options[:host], port: options[:port])
       server.start
     end
@@ -3806,7 +3812,7 @@ module Tina4
         # loopback, not 0.0.0.0. Only the DEFAULT changes: production
         # (TINA4_DEBUG off) keeps 0.0.0.0, and a developer who WANTS network
         # exposure sets TINA4_HOST=0.0.0.0 to override deliberately.
-        Tina4.truthy?(ENV["TINA4_DEBUG"]) ? "127.0.0.1" : DEFAULT_HOST
+        Tina4::Env.is_truthy(ENV["TINA4_DEBUG"]) ? "127.0.0.1" : DEFAULT_HOST
       end
     end
 
@@ -3875,9 +3881,18 @@ module Tina4
 
       # Gemfile
       unless File.exist?(File.join(dir, "Gemfile"))
+        # Same Gemfile `tina4 init ruby` writes. The gem is published as
+        # "tina4ruby" ("tina4-ruby" does not exist, so bundle install failed),
+        # and sqlite3 is an app dependency (ADR-0067): tina4ruby loads it lazily
+        # for the default SQLite database but never declares it.
         File.write(File.join(dir, "Gemfile"), <<~RUBY)
           source "https://rubygems.org"
-          gem "tina4-ruby", "~> 3.0"
+
+          gem "tina4ruby", "~> 3.0"
+
+          # SQLite driver for the default database (TINA4_DATABASE_URL=sqlite:...).
+          # tina4ruby loads it lazily; it is an app dependency, like pg or mysql2.
+          gem "sqlite3"
         RUBY
       end