tina4ruby 3.13.81 → 3.13.82

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c97745aeda99520ca771efcba237145e03897174113229656c05f12f1b3cc07
-  data.tar.gz: 64e21ce431b7c697cc9b392f810d0b5072d6245d38e2c60d962a57a9c473e174
+  metadata.gz: 3c8f9a8a50b4bb94a8b19b81774ce30e7a9d64fca932c2eb6a49016dc0352171
+  data.tar.gz: 90066d82b0085d019c3118fe57d225eb78206fe44f55c235dd3e7d67d8451382
 SHA512:
-  metadata.gz: 6327789d45d5e1d44a6f6641be57580c69587fa3f935b07d8c5511b0754b4cc307cd0746299a0e4c57f67dcbf982afc58e331c160a06b75445568b75034a0b76
-  data.tar.gz: f4235dd14f3fe8f6aee9ef35705761bb0191694b3942f6d7858e6eabdf883c8421b2b5674515d87bd4054d65c32423ab759123e7c699b629d2abd43d99d822d9
+  metadata.gz: 042b4dbfa4faf371dde9eb25e3e4406170c46086c29f1ff67afecad0fb61c482605f4f912469251b8640545142eeb295dd7eb1797081137575d941ebccf3f9be
+  data.tar.gz: e5e303934c51d2fc83692817eef9f26382d5bbd5c1b735f6a0b3bcd65a13a7a902574b070cd86a1b60cf0e17a34788444507c5b8cd62c9d8a60aea626abff80f

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+Tina4 keeps ONE version across all four frameworks (Python, PHP, Ruby, Node.js), so a version
+number means the same thing everywhere.
+
+**The authoritative release notes for every shipped version live in the documentation:**
+https://tina4.com/ruby/36-releases
+
+This file is deliberately NOT a copy of those notes. Duplicating them is exactly how a
+changelog rots into claiming a version that was never cut, so this file records only
+UNRELEASED work. When a version ships, its notes go to the release notes above.
+
+## Unreleased
+
+### Added
+
+- **MQTT 3.1.1 client** (`Tina4::Mqtt` / `Tina4::MqttMessage`), zero-dependency (stdlib `socket` +
+  lazily-required `openssl`), verified against a real broker with no mocks. publish/subscribe/consume,
+  QoS 0/1, retained, Last Will, per-client TLS, QoS 2 refused loudly. Ruby ships all 97 shared
+  features plus its native ERB engine, for **98 built-in features**.
+
+### Changed
+
+- Internal: the SQL dialect-translation file is renamed
+  `lib/tina4/sql_translation.rb` -> `lib/tina4/sql_translator.rb`, so the filename matches the
+  `Tina4::SQLTranslator` class it defines (and the sibling frameworks). The class name, its
+  methods and its behaviour are unchanged, and `require "tina4"` is unaffected - this is a
+  filename alignment, not an API change. Only code that bypassed the gem's own entry point with
+  a direct `require "tina4/sql_translation"` needs to update the path.
+
+## Earlier history (pre-3.x)
+
+Kept for reference only. The versions below are from the 0.x line, long before the unified
+3.x versioning; everything from 3.x onward is in the release notes linked above.
+
 ## [0.4.0] - 2026-03-18
 
 ### Added
@@ -14,7 +47,7 @@
 - Recursive descent GraphQL parser (queries, mutations, fragments, variables, aliases)
 - Depth-first AST executor with resolver pattern
 - GraphQL schema with programmatic type registration
-- ORM auto-schema generation (`schema.from_orm(User)`) — auto-creates CRUD queries/mutations
+- ORM auto-schema generation (`schema.from_orm(User)`) - auto-creates CRUD queries/mutations
 - GraphiQL UI served at GET /graphql
 - Route integration via `gql.register_route("/graphql")`
 - Full GraphQL type system (scalars, objects, lists, non-null, input objects)
@@ -23,7 +56,7 @@
 
 ### Added
 - Default auth protection for POST/PUT/PATCH/DELETE routes (matching tina4_python behavior)
-- API_KEY bypass in bearer auth — if `ENV["API_KEY"]` matches the bearer token, access is granted
+- API_KEY bypass in bearer auth - if `ENV["API_KEY"]` matches the bearer token, access is granted
 - `auth: false` option to make write routes public (equivalent to tina4_python's `@noauth()`)
 - `default_secure_auth` cached auth handler for performance
 - `resolve_auth` helper for flexible auth resolution

data/README.md

@@ -4,11 +4,11 @@
 <h1 align="center">Tina4 Ruby</h1>
 <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">98 built-in features. Zero runtime dependencies. One require, everything works.</p>
 <p align="center">
   <a href="https://rubygems.org/gems/tina4ruby"><img src="https://img.shields.io/gem/v/tina4ruby?color=7b1fa2&label=RubyGems" alt="RubyGems"></a>
   <img src="https://img.shields.io/badge/tests-2%2C508%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/features-55-blue" alt="Features">
+  <img src="https://img.shields.io/badge/features-98-blue" alt="Features">
   <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero Deps">
   <a href="https://tina4.com"><img src="https://img.shields.io/badge/docs-tina4.com-7b1fa2" alt="Docs"></a>
 </p>
@@ -91,7 +91,7 @@ Benchmarked with `wrk`: 5,000 requests, 50 concurrent, median of 3 runs:
 | **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 **98 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 zero
 
 ## 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 97 features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

data/lib/tina4/background.rb

@@ -36,15 +36,34 @@ module Tina4
       end
 
       # Stop and join every running task. Called on graceful shutdown.
+      #
+      # Each stop_task deregisters its own descriptor, so there is no blanket
+      # `tasks.clear` here: clearing would ALSO drop a task registered while
+      # this loop was running — leaving its thread alive but invisible in the
+      # registry, which is the worse of the two failure modes.
       def stop_all(timeout: 2.0)
         snapshot = mutex.synchronize { tasks.dup }
         snapshot.each { |task| stop_task(task, timeout: timeout) }
-        mutex.synchronize { tasks.clear }
       end
 
-      # Stop a single task. Used by tests that register, fire, then stop.
+      # Stop a single task and DEREGISTER it. Used by tests that register, fire,
+      # then stop, and by any subsystem that owns a task for part of its life
+      # (e.g. Mqtt::Client#stop_keepalive).
+      #
+      # The descriptor is removed from `tasks` so the registry never reports a
+      # stopped task as registered — leaving it in place made `tasks` grow for
+      # the life of the process on every start/stop cycle and made introspection
+      # lie about what is actually running.
+      #
+      # Idempotent: a second call on the same descriptor removes nothing, finds
+      # no thread and returns safely.
       def stop_task(task, timeout: 2.0)
         task[:running] = false
+        # Identity, not equality: `tasks.delete(task)` uses `==`, which would
+        # take out any OTHER descriptor that happens to hold an equal Hash
+        # (same callback, same interval). Only this exact descriptor goes.
+        mutex.synchronize { tasks.delete_if { |registered| registered.equal?(task) } }
+
         thread = task[:thread]
         return unless thread
 

data/lib/tina4/cli.rb

@@ -75,6 +75,58 @@ module Tina4
       "help"             => { handler: :cmd_help,                                                          summary: "Show this help message" },
     }.freeze
 
+    # ── Delegation to the `tina4` client ────────────────────────────────
+    #
+    # `doctor`, `setup` and `deploy` are owned by the Rust `tina4` client, not by
+    # any framework. `doctor` probes ALL FOUR runtimes plus package managers,
+    # ports and global AI-skills currency; `setup` installs language runtimes
+    # (Homebrew / Chocolatey, with UAC elevation on Windows) and scaffolds a
+    # project from nothing; `deploy` writes deployment boilerplate baked into the
+    # client binary. Cloning any of them into four languages would duplicate
+    # hundreds of lines per language for zero new capability — and four copies
+    # would immediately drift.
+    #
+    # So the framework CLI DELEGATES: it resolves `tina4` on PATH, runs it with
+    # the same argv, and exits with the client's exit code. All four frameworks
+    # reach the SAME implementation, which is a stronger parity guarantee than
+    # four ports.
+    #
+    # Delegation is ALLOW-LISTED, never blind. The client forwards ITS unknown
+    # commands to the framework CLI, so a framework that forwarded its unknowns
+    # back would ping-pong an unknown command between two processes forever. This
+    # closed set contains only commands the client dispatches natively, so no loop
+    # is possible by construction, and a real typo still gets "Unknown command".
+    #
+    # There are no handlers here: #run runs `tina4 <name> <args...>` and exits
+    # with its code. Keep this set closed and identical in all four frameworks.
+    # Summaries are the client's own wording, verbatim. Ruby mirror of the Python
+    # master's DELEGATED / _delegate_to_client.
+
+    DELEGATED = {
+      "doctor" => { summary: "Check installed languages and tools" },
+      "setup"  => { summary: "Guided, menu-driven setup: install everything + scaffold a ready-to-run project" },
+      "deploy" => { usage: "<docker|systemd|nginx|cpanel> [--force]", args: ["target"],
+                    summary: "Generate deployment scaffolding (Dockerfile, systemd unit, nginx block, cPanel)" },
+    }.freeze
+
+    CLIENT_BINARY = "tina4"
+
+    # Internal process marker (same class as the client's own
+    # TINA4_SETUP_ELEVATED): set on the child so a client that resolves back to a
+    # framework CLI is caught instead of spawning forever. NOT user configuration
+    # — deliberately absent from the CLI's known_vars().
+    DELEGATION_GUARD_ENV = "TINA4_CLI_DELEGATED"
+
+    # 127 is the conventional "command not found" and covers both ways the client
+    # can be unreachable (absent from PATH, or the loop guard tripping).
+    EXIT_CLIENT_UNAVAILABLE = 127
+    EXIT_UNKNOWN_COMMAND = 1
+
+    CLIENT_INSTALL_HINT = <<~HINT.freeze
+      Install it:  curl -fsSL https://tina4.com/install.sh | sh
+      Windows:     irm https://tina4.com/install.ps1 | iex
+    HINT
+
     # ── Field type mapping ──────────────────────────────────────────────
     FIELD_TYPE_MAP = {
       "string"   => { orm: "string_field",  sql: "VARCHAR(255)", default: "''" },
@@ -105,15 +157,68 @@ module Tina4
       spec = COMMANDS[command]
       if spec
         send(spec[:handler], argv)
+      elsif DELEGATED.key?(command)
+        exit delegate_to_client(command, argv)
       else
+        # A genuinely unknown command is an ERROR: exit non-zero so a typo in a
+        # script or CI step fails loudly instead of reporting success.
         puts "Unknown command: #{command}"
         cmd_help
-        exit 1
+        exit EXIT_UNKNOWN_COMMAND
       end
     end
 
     private
 
+    # Absolute path of the `tina4` client on PATH, or nil if it isn't there.
+    #
+    # Scans PATH directly rather than shelling out to which/where — one less
+    # process and it behaves the same on every platform.
+    def find_client
+      windows = RUBY_PLATFORM =~ /mswin|mingw|cygwin/
+      names = windows ? %W[#{CLIENT_BINARY}.exe #{CLIENT_BINARY}.cmd #{CLIENT_BINARY}.bat] : [CLIENT_BINARY]
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        next if dir.empty?
+
+        names.each do |name|
+          candidate = File.join(dir, name)
+          return candidate if File.file?(candidate) && (windows || File.executable?(candidate))
+        end
+      end
+      nil
+    end
+
+    # Run `tina4 <command> <args...>`, returning the client's exit code.
+    #
+    # Returns EXIT_CLIENT_UNAVAILABLE (127) with an actionable message when the
+    # client is not on PATH, or when the re-entry guard shows the resolved `tina4`
+    # came back to a framework CLI (a delegation loop).
+    def delegate_to_client(command, args)
+      if ENV[DELEGATION_GUARD_ENV] == command
+        warn "  Refusing to delegate '#{command}' again — the 'tina4' on your PATH"
+        warn "  resolved back to a framework CLI instead of the tina4 client."
+        warn ""
+        warn "  Check which 'tina4' comes first on your PATH and put the client first."
+        return EXIT_CLIENT_UNAVAILABLE
+      end
+
+      client = find_client
+      if client.nil?
+        warn "  '#{command}' is provided by the tina4 client, which is not on your PATH."
+        warn ""
+        CLIENT_INSTALL_HINT.each_line { |line| warn "  #{line.chomp}" }
+        warn ""
+        warn "  Then run:    #{CLIENT_BINARY} #{command}"
+        return EXIT_CLIENT_UNAVAILABLE
+      end
+
+      # Array form => no shell, so no quoting/injection surface. stdio is
+      # inherited, so the client's interactive prompts (setup) and colour output
+      # work exactly as if it had been invoked directly.
+      system({ DELEGATION_GUARD_ENV => command }, client, command, *args)
+      $?&.exitstatus || EXIT_CLIENT_UNAVAILABLE
+    end
+
     # ── Helpers ──────────────────────────────────────────────────────────
 
     # CamelCase -> snake_case: ProductCategory -> product_category
@@ -2083,13 +2188,12 @@ module Tina4
       content = <<~RUBY
         # #{name} request validator.
         #
-        # Tina4::Validator is NOT part of the default `require "tina4"` surface
-        # (unlike Queue / Events / ServiceRunner), so require it explicitly here.
-        # NOT auto-loaded — require this file from the route that validates:
+        # Tina4::Validator comes with `require "tina4"` — no extra require needed.
+        # This FILE is not auto-discovered though (only src/routes/ and src/orm/
+        # are), so require it from the route that validates:
         #     require_relative "../validators/#{snake}"
         #     v = validate_#{snake}(request.body)
         #     next response.json({ error: v.errors.first[:message] }, 400) unless v.is_valid?
-        require "tina4/validator"
 
         def validate_#{snake}(data)
           validator = Tina4::Validator.new(data)
@@ -2756,20 +2860,23 @@ module Tina4
 
     # Print the human-readable command reference.
     #
-    # Generated from the COMMANDS and GENERATORS registries — the SAME single
-    # source of truth that drives dispatch (#run / #cmd_generate) and the
+    # Generated from the COMMANDS, DELEGATED and GENERATORS registries — the SAME
+    # single source of truth that drives dispatch (#run / #cmd_generate) and the
     # `commands --json` manifest — so the help text can never drift from what
     # the CLI actually does.
     def cmd_help(_argv = nil)
       command_rows = COMMANDS.map do |name, spec|
         ["#{name} #{spec[:usage]}".rstrip, spec[:summary]]
       end
+      delegated_rows = DELEGATED.map do |name, spec|
+        ["#{name} #{spec[:usage]}".rstrip, spec[:summary]]
+      end
       generator_rows = GENERATORS.map do |name, spec|
         ["generate #{name} #{spec[:usage]}".rstrip, spec[:summary]]
       end
       # Align summaries in a column; a left cell longer than the cap overflows
       # cleanly (2-space gap) rather than pushing every other summary out.
-      pad = [46, (command_rows + generator_rows).map { |left, _| left.length }.max].min
+      pad = [46, (command_rows + delegated_rows + generator_rows).map { |left, _| left.length }.max].min
 
       row = lambda do |left, summary|
         gap = left.length <= pad ? pad : left.length
@@ -2778,6 +2885,10 @@ module Tina4
 
       lines = ["Tina4 Ruby CLI", "", "Usage: tina4ruby COMMAND [options]", "", "Commands:"]
       lines += command_rows.map { |left, summary| row.call(left, summary) }
+      lines += ["", "Delegated to the #{CLIENT_BINARY} client (same behaviour in every framework):"]
+      lines += delegated_rows.map { |left, summary| row.call(left, summary) }
+      lines += ["  (these run the #{CLIENT_BINARY} client — install: " \
+                "curl -fsSL https://tina4.com/install.sh | sh)"]
       lines += ["", "Generators:"]
       lines += generator_rows.map { |left, summary| row.call(left, summary) }
       lines += [
@@ -2809,14 +2920,19 @@ module Tina4
 
     # Build the machine-readable manifest of the CLI's command surface.
     #
-    # Pure data: reads the COMMANDS registry and the framework version — no
-    # bootstrap, no database, no migrations, no app imports. This is exactly
-    # what `commands --json` serializes and what the tina4 client consumes to
-    # discover which commands this framework supports.
+    # Pure data: reads the COMMANDS and DELEGATED registries and the framework
+    # version — no bootstrap, no database, no migrations, no app imports. This is
+    # exactly what `commands --json` serializes and what the tina4 client consumes
+    # to discover which commands this framework supports.
+    #
+    # Commands handed to the `tina4` client carry "delegated" => true, so the
+    # manifest describes the WHOLE surface the CLI accepts while still saying who
+    # implements each one. The client needs no change: its help renderer already
+    # drops manifest names that clash with its own natives.
     #
     # Shape:
     #   { "framework" => "ruby", "version" => "<x.y.z>",
-    #     "commands" => [ { "name", "summary", "args"?, "subcommands"? }, ... ] }
+    #     "commands" => [ { "name", "summary", "args"?, "subcommands"?, "delegated"? }, ... ] }
     def commands_manifest
       require_relative "version"
       commands = COMMANDS.map do |name, spec|
@@ -2825,6 +2941,11 @@ module Tina4
         entry["subcommands"] = spec[:subcommands].dup if spec[:subcommands]
         entry
       end
+      commands += DELEGATED.map do |name, spec|
+        entry = { "name" => name, "summary" => spec[:summary], "delegated" => true }
+        entry["args"] = spec[:args].dup if spec[:args]
+        entry
+      end
       { "framework" => "ruby", "version" => Tina4::VERSION, "commands" => commands }
     end
 
@@ -2851,7 +2972,8 @@ module Tina4
       puts "\nTina4 #{manifest['framework']} - #{manifest['version']}\n\n"
       width = manifest["commands"].map { |command| command["name"].length }.max
       manifest["commands"].each do |command|
-        puts "  #{command['name'].ljust(width)}  #{command['summary']}"
+        marker = command["delegated"] ? " (#{CLIENT_BINARY} client)" : ""
+        puts "  #{command['name'].ljust(width)}  #{command['summary']}#{marker}"
         if command["subcommands"]
           puts "  #{''.ljust(width)}    #{command['subcommands'].join(', ')}"
         end
@@ -3052,6 +3174,11 @@ module Tina4
             {% block content %}{% endblock %}
             <script src="/js/tina4.min.js"></script>
             <script src="/js/frond.min.js"></script>
+            <!-- tina4-js reactive frontend (signals, components, router).
+                 Served from the framework's bundled public dir, same as
+                 tina4-python/example/src/templates/base.twig:47-48 and
+                 tina4-php/example/src/templates/base.twig:47-48. -->
+            <script src="/js/tina4js.min.js"></script>
             {% block scripts %}{% endblock %}
           </body>
           </html>