tina4ruby 3.13.37 → 3.13.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b75f9ed6546e671904c26e7dc9bb1f29fc83a62a63a7488d05540e12c535f32f
-  data.tar.gz: f33418ea68192ed529eb2f0b7953e2762ca5eface4c8b4b368b8a93c57344981
+  metadata.gz: 62dc42240a6abd35572f17207f42c631ebf2c36cc73b94adad4b163b3a2924a5
+  data.tar.gz: e9ea35e0aad4bee25bc42f7ee7a37973144265ed538b5e6127e5a546278a62cf
 SHA512:
-  metadata.gz: 413ecc40fcc877a0ea0cfbdca95ef5a3b5da3b3f24035787a9619ecc385e4735e5532eea10c34cbe316727f4544865adea62fcf0233804019815c52f699674fd
-  data.tar.gz: 84c7bd505379a49527cb75eead709eb8155225a90406ee5691afdfc53127129e013b5c3ede53c7cb35df44dcbdeb3467fdaa91adf6881f159ffe3912476ec65e
+  metadata.gz: 58cf9b41857e5905b5eeda37a6881f812aad230a12533051d4510724222453f344ae1a0e05120e915a69450a05788dad7468eb1b99925e44a5bd8a625dca4c59
+  data.tar.gz: 8ff5447f091aafe2ff0a06c7e23a8f7838190545ec96f99bc2329753ee0a9ed0714cc1a7293d127805efe504552293fbb6f08e3fa7651e8423998cc8939869f5

data/README.md

@@ -2,7 +2,7 @@
   <img src="https://tina4.com/logo.svg" alt="Tina4" width="200">
 </p>
 <h1 align="center">Tina4 Ruby</h1>
-<h3 align="center">TINA4 — The Intelligent Native Application 4ramework</h3>
+<h3 align="center">TINA4: The Intelligent Native Application 4ramework</h3>
 <p align="center"><em>Simple. Fast. Human. &nbsp;|&nbsp; Built for AI. Built for you.</em></p>
 <p align="center">55 built-in features. Zero runtime dependencies. One require, everything works.</p>
 <p align="center">
@@ -18,7 +18,7 @@
 ## Quick Start
 
 ```bash
-# With the Tina4 CLI (recommended — enables SCSS + live reload)
+# With the Tina4 CLI (recommended, enables SCSS + live reload)
 cargo install tina4    # or grab a binary from https://github.com/tina4stack/tina4/releases
 tina4 init ruby ./my-app
 cd my-app && tina4 serve
@@ -56,12 +56,12 @@ db = Tina4::Database.new("sqlite://app.db")
 | Category | Features |
 |----------|----------|
 | **Core HTTP** (7) | Router with path params (`{id:int}`, `{p:path}`), Server, Request/Response, Middleware pipeline, Static file serving, CORS |
-| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird — unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
+| **Database** (6) | SQLite, PostgreSQL, MySQL, MSSQL, Firebird: unified adapter, connection pooling, query cache, transactions, race-safe ID generation, SQL dialect translation |
 | **ORM** (7) | Active Record with typed fields, relationships (`has_one`/`has_many`/`belongs_to`), soft delete, QueryBuilder + MongoDB support, Auto-CRUD generator, migrations with rollback |
 | **Auth & Security** (5) | JWT (HS256/RS256), password hashing (PBKDF2-SHA256), API key validation, rate limiting, CSRF form tokens |
 | **Templating** (3) | Frond engine (Twig/Jinja2-compatible, pre-compiled 2.8× faster), SCSS auto-compilation, built-in CSS (~24 KB) |
 | **API & Integration** (5) | HTTP client (zero-dep), GraphQL with ORM auto-schema + GraphiQL IDE, WSDL/SOAP with auto WSDL, WebSocket (RFC 6455) + Redis backplane, MCP server (24 dev tools) |
-| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters — service runner — event system (on/emit/once/off) |
+| **Background** (3) | Job queue (File/RabbitMQ/Kafka/MongoDB) with priority, delay, retry, dead letters; service runner; event system (on/emit/once/off) |
 | **Data & Storage** (4) | Session (File/Redis/Valkey/MongoDB/DB), response cache (LRU, TTL), seeder + 50+ fake data generators, messenger (SMTP/IMAP) |
 | **Developer Tools** (7) | Dev dashboard (11 tabs), dev toolbar, error overlay (Catppuccin Mocha), dev mailbox, hot reload + CSS hot-reload, code metrics (complexity, coupling, maintainability), AI context installer (7 tools) |
 | **Utilities** (7) | DI container (transient + singleton), HtmlElement builder, inline testing (`@tests` decorator), i18n (6 languages), Swagger/OpenAPI auto-generation, CLI scaffolding (`generate model/route/migration/middleware`), structured logging |
@@ -84,14 +84,14 @@ tina4ruby generate model <name>
 
 ## Performance
 
-Benchmarked with `wrk` — 5,000 requests, 50 concurrent, median of 3 runs:
+Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 
 | Framework | JSON req/s | Deps | Features |
 |-----------|-----------|------|----------|
 | **Tina4 Ruby** | **10,243** | 0 | 55 |
 | Sinatra | 9,548 | 5+ | ~4 |
 
-Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4** — with zero runtime dependencies.
+Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4**, with zero runtime dependencies.
 
 **Across all 4 Tina4 implementations:**
 
@@ -105,7 +105,7 @@ Tina4 Ruby outperforms Sinatra while delivering **55 features vs ~4** — with z
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages — same architecture, same conventions, same 55 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, same 55 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

data/lib/tina4/api.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 require "net/http"
+require "openssl"
 require "uri"
 require "json"
 require "base64"
 
 module Tina4
+  # Statuses that warrant an automatic retry when max_retries > 0: rate-limit
+  # (429) plus the transient server-side 5xx family. 4xx client errors (401,
+  # 404, …) are NOT retried — a repeat won't succeed. Parity with the Python
+  # master's _RETRY_STATUSES.
+  API_RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
   class API
     attr_reader :base_url, :headers
 
@@ -18,9 +25,16 @@ module Tina4
     #     api = Tina4::API.new("https://self-signed.local", verify_ssl: false)
     #
     # Bearer wins over basic-auth when both are passed.
+    #
+    # 3.13.39: +max_retries / +retry_backoff enable opt-in automatic retry with
+    # exponential backoff (default max_retries: 0 = off, non-breaking) on a
+    # transport error (APIResponse#status == 0) or a retryable status
+    # (429/5xx). A retried non-idempotent request (POST/PUT/PATCH/DELETE) may be
+    # re-sent — retries are opt-in for exactly that reason. Parity with the
+    # Python master.
     def initialize(base_url, headers: {}, timeout: 30,
                    bearer_token: nil, username: nil, password: nil,
-                   verify_ssl: nil)
+                   verify_ssl: nil, max_retries: 0, retry_backoff: 0.5)
       @base_url = base_url.chomp("/")
       @headers = {
         "Content-Type" => "application/json",
@@ -28,6 +42,8 @@ module Tina4
       }.merge(headers)
       @timeout = timeout
       @verify_ssl = verify_ssl
+      @max_retries = [0, max_retries.to_i].max
+      @retry_backoff = retry_backoff.to_f
 
       # Bearer wins over basic-auth when both passed
       if bearer_token
@@ -142,9 +158,35 @@ module Tina4
       end
     end
 
+    # Execute the request with opt-in retry/backoff. Returns an APIResponse.
+    #
+    # With @max_retries > 0, a transport error (APIResponse#status == 0, the
+    # existing error sentinel) or a retryable status (429/5xx) is retried up to
+    # @max_retries times with exponential backoff (@retry_backoff seconds base,
+    # doubling each attempt); any other outcome (2xx, 3xx, other 4xx) returns at
+    # once. Parity with the Python master's _request.
     def execute(uri, request)
+      attempts = @max_retries + 1
+      response = nil
+      (0...attempts).each do |attempt|
+        response = attempt_request(uri, request)
+        code = response.status
+        retryable = code.zero? || API_RETRY_STATUSES.include?(code)
+        return response if !retryable || attempt == attempts - 1
+
+        sleep(@retry_backoff * (2**attempt))
+      end
+      response
+    end
+
+    # A single HTTP attempt. Returns the standardized APIResponse.
+    def attempt_request(uri, request)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = uri.scheme == "https"
+      # 3.13.39: honour verify_ssl: false (the dead-since-3.13.1 kwarg). Only
+      # disable verification when EXPLICITLY false — nil/true keep the secure
+      # default (OpenSSL::SSL::VERIFY_PEER).
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE if @verify_ssl == false
       http.open_timeout = @timeout
       http.read_timeout = @timeout
 

data/lib/tina4/auth.rb

@@ -3,11 +3,20 @@ require "openssl"
 require "base64"
 require "json"
 require "fileutils"
+require "securerandom"
 
 module Tina4
   module Auth
     KEYS_DIR = ".keys"
 
+    # Single source of truth for the blank-secret warning, emitted identically
+    # from both the CI/prod boot path (ensure_dev_secret) and the lazy
+    # per-call resolver (hmac_secret). Actionable: names exactly what to set.
+    BLANK_SECRET_WARNING =
+      "Auth: TINA4_SECRET is not set — JWT signing is insecure. Set TINA4_SECRET " \
+      "to a random value (e.g. `openssl rand -hex 32`) in your environment or " \
+      ".env before serving traffic."
+
     class << self
       def setup(root_dir = Dir.pwd)
         @keys_dir = File.join(root_dir, KEYS_DIR)
@@ -15,6 +24,54 @@ module Tina4
         ensure_keys
       end
 
+      # Boot-time bootstrap (run once after env load, before auth is used).
+      #
+      # Mirrors the Python master's tina4_python.auth.ensure_dev_secret:
+      #   - If TINA4_SECRET is already set → no-op (returns nil).
+      #   - Else if NOT dev, OR CI, OR production → emit the actionable
+      #     blank-secret warning and return nil. NEVER generates or persists a
+      #     secret in CI or production. (Hard security constraint.)
+      #   - Else (dev, not CI, not prod, blank secret) → mint a 32-byte
+      #     (64 hex char) random secret, set it in the process env immediately,
+      #     then APPEND it to <root_dir>/.env.local (gitignored, created if
+      #     missing). On ANY write failure keep the in-memory secret and warn —
+      #     never raise (boot must not crash).
+      #
+      # `root_dir` exists only so tests can target a temp dir without chdir;
+      # production callers pass nothing (defaults to Dir.pwd).
+      #
+      # Returns the generated secret (String) when it mints one, else nil.
+      def ensure_dev_secret(root_dir = Dir.pwd)
+        existing = ENV["TINA4_SECRET"]
+        return nil if existing && !existing.empty?
+
+        unless dev? && !ci? && !production?
+          warn_blank_secret
+          return nil
+        end
+
+        new_secret = SecureRandom.hex(32) # 32 bytes -> 64 hex chars
+        ENV["TINA4_SECRET"] = new_secret  # available for this run immediately
+
+        begin
+          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")
+          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.
+          log_warning("Auth: generated a development secret but could not write .env.local (#{e.message}); using it for this run only")
+        end
+
+        new_secret
+      end
+
       # ── HS256 helpers (stdlib only, no gem) ──────────────────────
 
       # Returns true when SECRET env var is set and no RSA keys exist in .keys/
@@ -28,8 +85,13 @@ module Tina4
           File.exist?(File.join(@keys_dir, "public.pem")))
       end
 
+      # Lazy per-call secret resolver. When the secret is blank, emit the
+      # actionable blank-secret warning (the same text the CI/prod bootstrap
+      # path uses) before returning. Parity with Python's _resolve_secret.
       def hmac_secret
-        ENV["TINA4_SECRET"]
+        secret = ENV["TINA4_SECRET"]
+        warn_blank_secret if secret.nil? || secret.empty?
+        secret
       end
 
       # Base64url-encode without padding (JWT spec)
@@ -196,9 +258,12 @@ module Tina4
 
         token = Regexp.last_match(1)
 
-        # API_KEY bypass — matches tina4_python behavior
-        api_key = ENV["TINA4_API_KEY"]
-        if api_key && !api_key.empty? && token == api_key
+        # API_KEY bypass — timing-safe comparison via validate_api_key
+        # (OpenSSL.fixed_length_secure_compare). Parity with Python's
+        # authenticate_request (validate_api_key), PHP (hash_equals) and
+        # Node (timingSafeEqual). Never use a plain `==` here — that leaks the
+        # key length/prefix through comparison timing.
+        if validate_api_key(token)
           return { "api_key" => true }
         end
 
@@ -235,9 +300,12 @@ module Tina4
 
           token = Regexp.last_match(1)
 
-          # API_KEY bypass — matches tina4_python behavior
-          api_key = ENV["TINA4_API_KEY"]
-          if api_key && !api_key.empty? && token == api_key
+          # API_KEY bypass — timing-safe comparison via validate_api_key
+          # (OpenSSL.fixed_length_secure_compare). Parity with Python's
+          # authenticate_request (validate_api_key), PHP (hash_equals) and
+          # Node (timingSafeEqual). Never use a plain `==` here — that leaks the
+          # key length/prefix through comparison timing.
+          if validate_api_key(token)
             env["tina4.auth"] = { "api_key" => true }
             return true
           end
@@ -271,6 +339,49 @@ module Tina4
 
       private
 
+      # ── Dev-secret bootstrap helpers (parity with Python master) ──
+
+      # Dev when the framework debug flag is truthy (TINA4_DEBUG).
+      def dev?
+        Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
+      end
+
+      # CI when the de-facto CI env var is truthy.
+      def ci?
+        Tina4::Env.is_truthy(ENV["CI"])
+      end
+
+      # Production when TINA4_ENV (default "development") is "production".
+      def production?
+        (ENV["TINA4_ENV"] || "development").to_s.strip.downcase == "production"
+      end
+
+      # Emit the single actionable blank-secret warning. Same text from the
+      # CI/prod bootstrap path and the lazy per-call resolver.
+      def warn_blank_secret
+        log_warning(BLANK_SECRET_WARNING)
+      end
+
+      def log_info(message)
+        if defined?(Tina4::Log)
+          Tina4::Log.info(message)
+        else
+          warn(message)
+        end
+      rescue StandardError
+        warn(message)
+      end
+
+      def log_warning(message)
+        if defined?(Tina4::Log)
+          Tina4::Log.warning(message)
+        else
+          warn(message)
+        end
+      rescue StandardError
+        warn(message)
+      end
+
       def ensure_keys
         @keys_dir ||= File.join(Dir.pwd, KEYS_DIR)
         FileUtils.mkdir_p(@keys_dir)

data/lib/tina4/cli.rb

@@ -5,7 +5,7 @@ require "fileutils"
 
 module Tina4
   class CLI
-    COMMANDS = %w[init start migrate migrate:status migrate:rollback seed seed:create test version routes console generate ai help].freeze
+    COMMANDS = %w[init start migrate migrate:status migrate:rollback seed seed:create test version routes console generate ai metrics help].freeze
 
     # ── Field type mapping ──────────────────────────────────────────────
     FIELD_TYPE_MAP = {
@@ -43,6 +43,7 @@ module Tina4
       when "console"    then cmd_console
       when "generate"   then cmd_generate(argv)
       when "ai"         then cmd_ai(argv)
+      when "metrics"    then cmd_metrics(argv)
       when "help", "-h", "--help" then cmd_help
       else
         puts "Unknown command: #{command}"
@@ -85,7 +86,7 @@ module Tina4
     # Parse --key value and --flag from args. Returns [flags_hash, positional_array]
     def parse_flags(args)
       # Boolean-only flags that never take a value argument
-      boolean_flags = %w[no-browser no-reload production managed all clear dev]
+      boolean_flags = %w[no-browser no-reload production managed all clear dev json]
 
       flags = {}
       positional = []
@@ -286,6 +287,10 @@ module Tina4
             status_icon = r[:status] == "success" ? "OK" : "FAIL"
             puts "  [#{status_icon}] #{r[:name]}"
           end
+          # FAIL-FAST: a failed migration must give CI a non-zero exit (parity
+          # with the Python master). Only the startup auto-migration hook
+          # swallows failures; the explicit CLI does not.
+          exit 1 if results.any? { |r| r[:status] == "failed" }
         end
       end
     end
@@ -488,6 +493,100 @@ module Tina4
       end
     end
 
+    # ── metrics ───────────────────────────────────────────────────────────
+
+    # Report top code-quality offenders (complexity, size, maintainability,
+    # tests). Mirrors the Python-master `tina4python metrics` command.
+    #
+    #   tina4ruby metrics                       # human report, scans src/ (or framework)
+    #   tina4ruby metrics --top 10              # only the worst 10
+    #   tina4ruby metrics --path lib            # scan a specific directory
+    #   tina4ruby metrics --json                # machine-readable for CI
+    #   tina4ruby metrics --fail-on warn        # exit 1 if any warn/error offender
+    #   tina4ruby metrics --fail-on error       # exit 1 only on error-severity
+    def cmd_metrics(argv)
+      require "json"
+      require "set"
+      require_relative "metrics"
+
+      flags, _positional = parse_flags(argv)
+
+      top = (flags["top"].to_s =~ /\A\d+\z/) ? flags["top"].to_i : 20
+      as_json = flags.key?("json")
+      path = flags["path"].is_a?(String) ? flags["path"] : "src"
+      fail_on = flags["fail-on"].is_a?(String) ? flags["fail-on"] : nil
+
+      unless [nil, "warn", "error"].include?(fail_on)
+        puts "  invalid --fail-on '#{fail_on}' (use warn or error)"
+        exit 2
+      end
+
+      result = Tina4::Metrics.offenders(path, top)
+      summary = result["summary"]
+      found = result["offenders"]
+
+      if summary.key?("error")
+        puts "  metrics error: #{summary['error']}"
+        exit 2
+      end
+
+      # Decide exit code from the FULL offender set, not just the printed top-N.
+      # full_analysis is cached, so this reuses the same analysis.
+      all_offenders = Tina4::Metrics.offenders(path, [summary["total_offenders"], 1].max)["offenders"]
+      severities = all_offenders.map { |o| o["severity"] }.to_set
+      exit_code = 0
+      if fail_on == "warn" && !(severities & %w[warn error]).empty?
+        exit_code = 1
+      elsif fail_on == "error" && severities.include?("error")
+        exit_code = 1
+      end
+
+      if as_json
+        puts JSON.pretty_generate({ "summary" => summary, "offenders" => found })
+        exit exit_code
+      end
+
+      # ── Human report ──────────────────────────────────────────────────
+      use_color = $stdout.tty?
+      colorize = lambda do |text, code|
+        use_color ? "\e[#{code}m#{text}\e[0m" : text
+      end
+      sev_color = { "error" => "31", "warn" => "33", "info" => "2" } # red / yellow / dim
+
+      puts
+      puts "  Tina4 Metrics — #{summary['scan_mode']} scan (#{summary['scan_root']})"
+      puts "  files: #{summary['files_analyzed']}   " \
+           "functions: #{summary['total_functions']}   " \
+           "avg complexity: #{summary['avg_complexity']}   " \
+           "avg maintainability: #{summary['avg_maintainability']}"
+      showing = found.empty? ? "" : " (showing top #{found.length})"
+      puts "  offenders: #{summary['total_offenders']} total#{showing}"
+      puts
+
+      if found.empty?
+        puts "  " + colorize.call("✓ no offenders — clean", "32")
+        puts
+        exit exit_code
+      end
+
+      # Compute column widths so the table lines up.
+      locs = found.map { |o| "#{o['file']}:#{o['line']}" }
+      loc_w = [("FILE:LINE".length)].concat(locs.map(&:length)).max
+      kind_w = [("KIND".length)].concat(found.map { |o| o["kind"].length }).max
+
+      header = format("  %3s  %-8s  %-#{kind_w}s  %-#{loc_w}s  DETAIL", "#", "SEVERITY", "KIND", "FILE:LINE")
+      puts colorize.call(header, "1")
+      puts "  " + ("-" * (header.length - 2))
+      found.each_with_index do |o, i|
+        sev = o["severity"]
+        sev_cell = colorize.call(format("%-8s", sev), sev_color[sev])
+        puts format("  %3d  %s  %-#{kind_w}s  %-#{loc_w}s  %s",
+                    i + 1, sev_cell, o["kind"], locs[i], o["detail"])
+      end
+      puts
+      exit exit_code
+    end
+
     # ── generate ────────────────────────────────────────────────────────
 
     def cmd_generate(argv)
@@ -1225,6 +1324,7 @@ module Tina4
           routes             List all registered routes
           console            Start an interactive console
           ai                 Detect AI tools and install context files
+          metrics            Rank top code-quality offenders
           help               Show this help message
 
         Generators:
@@ -1238,6 +1338,13 @@ module Tina4
           generate view <Name> [--fields "..."]   List + detail templates for viewing records
           generate auth                           Login/register/logout routes + User model + templates
 
+        Metrics:
+          metrics [--top N] [--json] [--fail-on warn|error] [--path DIR]
+            --top N        Show only the worst N offenders (default: 20)
+            --json         Print machine-readable JSON ({summary, offenders}) for CI
+            --fail-on      Exit 1 if any offender at/above this severity (warn|error)
+            --path DIR     Scan DIR (default: src/, auto-resolves to the framework)
+
         Field types: string, int, float, bool, text, datetime, blob
         Table names: singular by default (Product -> product)
 
@@ -1346,6 +1453,7 @@ module Tina4
       unless File.exist?(File.join(dir, ".gitignore"))
         File.write(File.join(dir, ".gitignore"), <<~TEXT)
           .env
+          .env.local
           .keys/
           logs/
           sessions/