tina4ruby 3.12.10 → 3.13.0

data/lib/tina4/router.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "json"
+
 module Tina4
   class Route
     attr_reader :method, :path, :handler, :auth_handler, :swagger_meta,
@@ -312,6 +315,25 @@ module Tina4
         add("ANY", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
       end
 
+      # Register an explicit HEAD route. By default the framework auto-handles
+      # HEAD by falling back to the GET route and stripping the body
+      # (RFC 9110 §9.3.2). Use this only when you need a HEAD handler that
+      # does something different from GET — e.g. cheaper existence-check
+      # logic, custom validator headers without the cost of building the body.
+      # The framework still strips the response body for you on the way out.
+      def head(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("HEAD", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
+      # Register an explicit OPTIONS route. By default the framework auto-
+      # handles OPTIONS by building an Allow header from every method
+      # registered for the path and returning 204 (RFC 9110 §9.3.7). Use
+      # this to take over that behaviour — e.g. to return a richer OPTIONS
+      # payload describing the resource.
+      def options(path, middleware: [], swagger_meta: {}, template: nil, &block)
+        add("OPTIONS", path, block, middleware: middleware, swagger_meta: swagger_meta, template: template)
+      end
+
       def find_route(method, path)
         normalized_method = method.upcase
         # Normalize path once (not per-route)
@@ -325,9 +347,59 @@ module Tina4
           params = route.match_path(normalized_path)
           return [route, params] if params
         end
+
+        # RFC 9110 §9.3.2: HEAD is identical to GET except for the absence
+        # of a response body. If no explicit HEAD route matched, fall back
+        # to the GET route — the dispatcher strips the body on the way out
+        # so the handler doesn't need to know HEAD even happened.
+        if normalized_method == "HEAD"
+          (method_index["GET"] || []).each do |route|
+            params = route.match_path(normalized_path)
+            return [route, params] if params
+          end
+        end
+
         nil
       end
 
+      # Return the list of HTTP methods registered for ``path``, in the order
+      # GET / POST / PUT / PATCH / DELETE / HEAD / OPTIONS. Used by the
+      # dispatcher to build the ``Allow:`` header on 405 / OPTIONS responses
+      # (RFC 9110 §10.2.1, §9.3.7).
+      #
+      # If GET is registered for the path, HEAD is appended implicitly
+      # (HEAD auto-fallback). OPTIONS is appended whenever the path has any
+      # registered method (the framework auto-handles OPTIONS).
+      def methods_allowed_for_path(path)
+        normalized_path = path.gsub("\\", "/")
+        normalized_path = "/#{normalized_path}" unless normalized_path.start_with?("/")
+        normalized_path = normalized_path.chomp("/") unless normalized_path == "/"
+
+        method_order = %w[GET POST PUT PATCH DELETE HEAD OPTIONS]
+        seen = []
+        any_matched = false
+
+        method_index.each do |m, routes_for_method|
+          next if routes_for_method.empty?
+          matched = routes_for_method.any? { |r| r.match_path(normalized_path) }
+          next unless matched
+          if m == "ANY"
+            any_matched = true
+          elsif method_order.include?(m)
+            seen << m unless seen.include?(m)
+          end
+        end
+
+        seen = method_order.dup if any_matched
+
+        if !seen.empty?
+          seen << "HEAD" if seen.include?("GET") && !seen.include?("HEAD")
+          seen << "OPTIONS" unless seen.include?("OPTIONS")
+        end
+
+        method_order.select { |m| seen.include?(m) }
+      end
+
       # When TINA4_TRAILING_SLASH_REDIRECT is truthy, the rack app uses this
       # to detect whether the *original* (un-stripped) path differed from the
       # canonical form so it can issue a 301 redirect. Default false — silent
@@ -369,17 +441,79 @@ module Tina4
         GroupContext.new(prefix, auth_handler, middleware).instance_eval(&block)
       end
 
-      # Load route files from a directory (file-based route discovery)
+      # Load route files from a directory (file-based route discovery).
+      #
+      # Idempotent: files already loaded by a previous call are skipped, so
+      # calling load_routes repeatedly (e.g. on /__dev/api/reload) only
+      # picks up NEW files. Records the directory so #rescan_routes! can
+      # re-run without re-passing it.
       def load_routes(directory)
         return unless Dir.exist?(directory)
-        Dir.glob(File.join(directory, "**/*.rb")).sort.each do |file|
+
+        @loaded_route_files ||= {}
+        @last_routes_dir = directory
+
+        files = Dir.glob(File.join(directory, "**/*.rb")).sort
+        total = files.length
+        files.each do |file|
+          next if @loaded_route_files[file]
           begin
             load file
+            @loaded_route_files[file] = true
             Tina4::Log.debug("Route loaded: #{file}")
-          rescue => e
+          rescue ScriptError, StandardError => e
+            # ScriptError catches SyntaxError, which is NOT a StandardError —
+            # a bare `rescue => e` would let a syntax-broken route file crash
+            # the whole discovery pass.
             Tina4::Log.error("Failed to load route #{file}: #{e.message}")
+            record_broken_route_import(file, e)
           end
         end
+
+        # Zero-routes warning — src/routes/ has .rb files but the router
+        # is still empty. Almost certainly the user forgot Tina4::Router.get.
+        if total > 0 && routes.empty?
+          Tina4::Log.warning(
+            "Auto-discover found #{total} .rb file(s) in #{directory} but no routes registered. " \
+            "Each route file must call Tina4::Router.get / .post / etc."
+          )
+        end
+      end
+
+      # Re-run the most recent load_routes — called by /__dev/api/reload so
+      # files dropped into src/routes/ after server boot get picked up
+      # without a restart. No-op if load_routes has never been called.
+      def rescan_routes!
+        return [] if @last_routes_dir.nil? || @last_routes_dir.empty?
+        before = routes.length
+        load_routes(@last_routes_dir)
+        added = routes.length - before
+        Tina4::Log.info("Re-discovered #{added} new route(s) on reload") if added.positive?
+        added
+      end
+
+      # Test-only helper — reset the loaded-files state so tests can scan
+      # the same directory multiple times with different file contents.
+      def reset_route_discovery!
+        @loaded_route_files = {}
+        @last_routes_dir = nil
+      end
+
+      # Write a .broken sentinel so /health and the dev dashboard surface
+      # auto-discover failures instead of swallowing them into a log line.
+      def record_broken_route_import(file, error)
+        broken_dir = File.join(Dir.pwd, "data", ".broken")
+        FileUtils.mkdir_p(broken_dir) unless Dir.exist?(broken_dir)
+        slug = file.gsub(%r{[/\\]}, "_")
+        payload = JSON.generate(
+          type: "auto_discover_failure",
+          file: file,
+          error: "#{error.class}: #{error.message}"
+        )
+        File.write(File.join(broken_dir, "discover_#{slug}.broken"), payload)
+      rescue StandardError
+        # If the .broken write itself fails, the original error is already
+        # in the log — nothing more to do.
       end
     end
 

data/lib/tina4/test.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# Tina4 — The Intelligent Native Application 4ramework
+# Copyright 2007 - current Tina4
+# License: MIT https://opensource.org/licenses/MIT
+
+module Tina4
+  # Tina4 xUnit-style test base class — class-based test suites with HTTP
+  # helpers and positional assertions. Zero external dependencies.
+  #
+  # Documentation chapter 18 has long described:
+  #
+  #     class UserApiTest < Tina4::Test
+  #       def test_health
+  #         resp = get("/health")
+  #         assert_equal_value(resp.status, 200)
+  #       end
+  #     end
+  #
+  # Until 3.13.0 this class did not exist — examples crashed with
+  # "uninitialized constant Tina4::Test". Ruby parity of the
+  # Python `tina4_python.test.Test` and PHP `Tina4\Test` classes.
+  #
+  # The class has a built-in runner (no Minitest/RSpec required):
+  #
+  #     results = Tina4::Test.run_all          # discovers all subclasses
+  #     # => { passed: 12, failed: 0, errors: 0, details: [...] }
+  #
+  # Or run a single suite class:
+  #
+  #     UserApiTest.run!
+  #
+  # HTTP helpers (get/post/put/patch/delete) delegate to TestClient.
+  # Positional assertions match the Python (actual, expected, message)
+  # shape used throughout the cross-framework docs.
+  class Test
+    # Class-level registry so run_all can discover every subclass without
+    # filesystem scanning.
+    @subclasses = []
+
+    class << self
+      attr_reader :subclasses
+
+      def inherited(subclass)
+        super
+        Test.subclasses << subclass
+      end
+
+      # Run every test method (`test_*`) on the calling subclass. Returns
+      # a hash with passed/failed/errors counts and per-test details.
+      def run!
+        instance_methods(false).grep(/\Atest_/).sort.each_with_object(
+          { passed: 0, failed: 0, errors: 0, details: [] }
+        ) do |method, results|
+          suite = new
+          begin
+            suite.send(:set_up)
+            suite.send(method)
+            suite.send(:tear_down)
+            results[:passed] += 1
+            results[:details] << { suite: name, test: method, status: "passed" }
+          rescue AssertionError => e
+            results[:failed] += 1
+            results[:details] << { suite: name, test: method, status: "failed", message: e.message }
+          rescue StandardError => e
+            results[:errors] += 1
+            results[:details] << { suite: name, test: method, status: "error", message: "#{e.class}: #{e.message}" }
+          end
+        end
+      end
+
+      # Discover and run every Tina4::Test subclass.
+      def run_all(quiet: false)
+        results = { passed: 0, failed: 0, errors: 0, details: [] }
+        Test.subclasses.each do |klass|
+          out = klass.run!
+          results[:passed] += out[:passed]
+          results[:failed] += out[:failed]
+          results[:errors] += out[:errors]
+          results[:details].concat(out[:details])
+        end
+        unless quiet
+          puts "Tina4 Test results: #{results[:passed]} passed, #{results[:failed]} failed, #{results[:errors]} errors"
+        end
+        results
+      end
+    end
+
+    # ── Lifecycle hooks ──────────────────────────────────────────────
+    # snake_case Tina4 idiom; override in subclasses.
+
+    def set_up
+    end
+
+    def tear_down
+    end
+
+    # ── HTTP test client (lazy) ───────────────────────────────────────
+
+    def test_client
+      @test_client ||= Tina4::TestClient.new
+    end
+
+    def get(path, headers: nil)
+      test_client.get(path, headers: headers)
+    end
+
+    def post(path, json: nil, body: nil, headers: nil)
+      test_client.post(path, json: json, body: body, headers: headers)
+    end
+
+    def put(path, json: nil, body: nil, headers: nil)
+      test_client.put(path, json: json, body: body, headers: headers)
+    end
+
+    def patch(path, json: nil, body: nil, headers: nil)
+      test_client.patch(path, json: json, body: body, headers: headers)
+    end
+
+    def delete(path, headers: nil)
+      test_client.delete(path, headers: headers)
+    end
+
+    # ── Positional assertions — (actual, expected, message) shape ─────
+
+    def assert_equal_value(actual, expected, message = nil)
+      return if actual == expected
+
+      raise AssertionError, message || "Expected #{expected.inspect}, got #{actual.inspect}"
+    end
+
+    def assert_not_equal_value(actual, expected, message = nil)
+      return unless actual == expected
+
+      raise AssertionError, message || "Expected #{actual.inspect} != #{expected.inspect}, but they are equal"
+    end
+
+    def assert_true(value, message = nil)
+      return if value
+
+      raise AssertionError, message || "Expected truthy, got #{value.inspect}"
+    end
+
+    def assert_false(value, message = nil)
+      return unless value
+
+      raise AssertionError, message || "Expected falsy, got #{value.inspect}"
+    end
+
+    def assert_nil_value(value, message = nil)
+      return if value.nil?
+
+      raise AssertionError, message || "Expected nil, got #{value.inspect}"
+    end
+
+    def assert_not_nil_value(value, message = nil)
+      return unless value.nil?
+
+      raise AssertionError, message || "Expected non-nil, got nil"
+    end
+
+    def assert_raises(expected_class, message = nil)
+      raise ArgumentError, "Block required" unless block_given?
+
+      begin
+        yield
+      rescue StandardError => e
+        return if e.is_a?(expected_class)
+
+        raise AssertionError,
+              message || "Expected #{expected_class}, got #{e.class}: #{e.message}"
+      end
+      raise AssertionError, message || "Expected #{expected_class} to be raised, but nothing was"
+    end
+  end
+
+  # AssertionError raised by Tina4::Test assertion helpers on failure.
+  class AssertionError < StandardError; end
+end

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -44,6 +44,7 @@ require_relative "tina4/events"
 require_relative "tina4/plan"
 require_relative "tina4/project_index"
 require_relative "tina4/dev_admin"
+require_relative "tina4/feedback"
 require_relative "tina4/messenger"
 require_relative "tina4/dev_mailbox"
 require_relative "tina4/ai"
@@ -53,6 +54,7 @@ require_relative "tina4/response_cache"
 require_relative "tina4/html_element"
 require_relative "tina4/error_overlay"
 require_relative "tina4/test_client"
+require_relative "tina4/test"
 require_relative "tina4/docs"
 require_relative "tina4/mcp"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.12.10
+  version: 3.13.0
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-14 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -306,6 +306,7 @@ files:
 - lib/tina4/env.rb
 - lib/tina4/error_overlay.rb
 - lib/tina4/events.rb
+- lib/tina4/feedback.rb
 - lib/tina4/field_types.rb
 - lib/tina4/frond.rb
 - lib/tina4/gallery/auth/meta.json
@@ -337,6 +338,7 @@ files:
 - lib/tina4/orm.rb
 - lib/tina4/plan.rb
 - lib/tina4/project_index.rb
+- lib/tina4/public/__feedback/widget.js
 - lib/tina4/public/css/tina4.css
 - lib/tina4/public/css/tina4.min.css
 - lib/tina4/public/favicon.ico
@@ -400,6 +402,7 @@ files:
 - lib/tina4/templates/errors/502.twig
 - lib/tina4/templates/errors/503.twig
 - lib/tina4/templates/errors/base.twig
+- lib/tina4/test.rb
 - lib/tina4/test_client.rb
 - lib/tina4/testing.rb
 - lib/tina4/validator.rb