tina4ruby 3.13.132 → 3.13.134

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf58fba1e80ebbfcdeccfdf5ecab50bf0ce08754d834eaffe29e9e7e37ff4363
-  data.tar.gz: f59a4a709438114acd05275ee4220e032ebe539b3d27547b377de492f2583038
+  metadata.gz: 1d0d4c7801e0766f00041e3d004a0318d7bd4e22d9b4a4d102d05516b89ebba1
+  data.tar.gz: 837234011a9a76e4d0733d8a05936bdb08a5bcb8681638679064b51d84dc2392
 SHA512:
-  metadata.gz: 3b4c3b693f8686a0119ed679627ab646439c4e7e4b75649e55e70e5207556582b06bd3413fe4560cbc60183f6f66f6732f4fe11e4c87b7358b2b7327976f5841
-  data.tar.gz: 93b12a0719367dc9c8e4f1a95339d43ae170ea14e4ea52c347d9419044ad508ff894c08ba11a1c930920365a779ca5e0ab95a7e442a8fe60383d35d5fdeac045
+  metadata.gz: bfd2d4b058f1366920dd46b66f1d59f504f1b30cc649b71ecc7f5d8f8d15a385eaa19b5de9078768c0f935aba9a3115e8e10efe72806cfa53be5aca73f5c2caf
+  data.tar.gz: 178596fd8db63262bc35aeb25ae13e11c609b3f50a85bc06d91ce12063b9739973f80ce5783ec5a330d115b3b07e9389718f2316d8c53590b47867ad777b193d

data/CHANGELOG.md

@@ -6,6 +6,103 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.134
+
+Feature 140 Web Push is now available with provider-neutral subscription delivery,
+native result envelopes, fail-closed configuration, and the documented runtime
+configuration. Developer skills now include the Web Push API and configuration
+reference for all supported language stacks.
+
+## 3.13.133
+
+Maintainability pass, no behavior changes. Swagger.generate decomposed into cohesive
+helpers (Python 64->6, PHP 83->6, Node 52->2 cyclomatic; Ruby already lean) with the
+OpenAPI document byte-for-byte identical. Ruby dev-admin handle_request split from a
+138-branch dispatcher into per-concern methods (CC 138->11); routes, responses, and
+the localhost/auth gate unchanged. Full notes: https://tina4.com/python/36-releases
+
+## 3.13.132
+
+ORM reads return a ModelCollection carrying the query total (ADR-0064): where,
+select, find (filter form), all, and with_trashed hand back the page of models AND
+the total for the filter, so you paginate without a second query. get_total_records()
+/ to_paginate() (Python, Ruby); getTotalRecords() / toPaginate() (PHP, Node). The
+total reuses the count the query already ran - zero extra queries. Python's
+where(..., with_count=True) tuple is removed; PHP's return type changes from a bare
+array to an array-compatible ModelCollection object (toArray() escape hatch). Also:
+the dev server binds dual-stack loopback so localhost works on Windows; the dev-admin
+agent chat surface is removed and the dashboard no longer self-reloads; Firebird DDL
+no longer reads a row count and Firebird adapters close cleanly on GC (Python); the
+Valkey session handler subclasses Redis and shared fetch/execute/Frond loops are
+hoisted (behaviour unchanged). Full notes: https://tina4.com/python/36-releases
+
+## 3.13.131
+
+AI skills for a global team: plain English, short replies, effort matched to the
+task, ask-before-guess, and a grounding fallback for tools without the coder server.
+
+## 3.13.130
+
+AI skills discipline pass: objective on ideas (disagree when a design is weak),
+claim only what was verified, and chat instead of narrate.
+
+## 3.13.129
+
+tina4 generate model stops silently pluralising a reserved-word table. It prints a
+note and offers --table-name, so a downstream route or query does not fail with no
+clue the table was renamed.
+
+## 3.13.128
+
+tina4 lint: one command runs the project linter (ruff, phpcs, rubocop, or eslint),
+installs it as a dev dependency on demand, and falls back to a zero-dependency syntax
+baseline with --no-install.
+
+## 3.13.127
+
+A bare TRUE or FALSE now reaches SQL Server and Firebird as 1/0 in every framework.
+Node, PHP and Ruby had skipped the boolean translation on SQL Server, and Ruby on
+Firebird too.
+
+## 3.13.126
+
+The fake-data seeder reads the column name: a products.name column fills with product
+names, not person names.
+
+## 3.13.125
+
+Scaffolded migrations apply on every engine. tina4 generate migration wrote
+SQLite-only DDL (TEXT, REAL, CREATE TABLE IF NOT EXISTS); the generators now emit
+engine-correct types so a migration runs on Firebird and the rest.
+
+## 3.13.124
+
+The database session backend works on Firebird in all four frameworks, with a
+session-engine test in each so the gap cannot reopen.
+
+## 3.13.123
+
+tina4 generate queue <topic> returns the generate_v1_1 envelope: edit_hints[] naming
+the handler line to fill and next[] naming what to run after.
+
+## 3.13.122
+
+The default Content-Security-Policy (default-src 'self') no longer fails silently:
+when an app relies on something the policy blocks, the framework surfaces it instead
+of leaving a blank page.
+
+## 3.13.121
+
+Every migration surface speaks the ADR-0063 generate_v1_1 envelope - the CLI
+migrate:create, the MCP migration_create, and the rest, not just tina4 generate
+migration. Adds a pre-tag release guard.
+
+## 3.13.120
+
+Scaffolding envelope v1.1 (ADR-0063): every tina4 generate verb reports what to edit
+next and what to do after, not just where files went. Introduces the tina4-architect
+skill.
+
 ## 3.13.119
 
 Skill repair by @MichaelC8E (#44, merged as c1b8c43d5) plus a

data/README.md

@@ -102,7 +102,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 **98 features vs ~4**, with zero runtime dependencies.
+Tina4 Ruby outperforms Sinatra while delivering **140 cataloged features vs ~4**, with zero runtime dependencies.
 
 **Across all 4 Tina4 implementations:**
 
@@ -116,7 +116,7 @@ Tina4 Ruby outperforms Sinatra while delivering **98 features vs ~4**, with zero
 
 ## Cross-Framework Parity
 
-Tina4 ships identical features across four languages: same architecture, same conventions, same 98 features:
+Tina4 ships identical features across four languages: same architecture, same conventions, the same 140 cataloged features:
 
 | | Python | PHP | Ruby | Node.js |
 |---|--------|-----|------|---------|

data/lib/tina4/dev_admin.rb

@@ -395,6 +395,34 @@ module Tina4
         denial = dev_mutation_denial(env)
         return denial if denial
 
+        # Exact [method, path] dispatch, split by concern. Every route is an
+        # exact pair (no overlaps), so the groups form a partition: the first
+        # group that matches answers, and a group returns nil when it holds no
+        # matching route. Behaviour is identical to the former single 138-branch
+        # case — the only handler that legitimately returns nil is an MCP route
+        # with the capability disabled (with_mcp_gate), for which the original
+        # case also fell through to nil (RackApp then 404s it).
+        dispatch_dashboard(method, path, env) ||
+          dispatch_inspectors(method, path, env) ||
+          dispatch_mailbox(method, path, env) ||
+          dispatch_queue(method, path, env) ||
+          dispatch_data(method, path, env) ||
+          dispatch_config(method, path, env) ||
+          dispatch_files(method, path, env) ||
+          dispatch_mcp(method, path, env)
+      end
+
+
+      private
+
+      # ── /__dev request dispatch (split from a single 138-CC case) ──────
+      # Each dispatch_* owns one concern's exact [method, path] routes and
+      # returns a Rack triple, or nil when it holds no matching route. Branch
+      # bodies are the former case's, moved verbatim.
+
+      # Dashboard shell, injected-toolbar assets, the reload trigger and the
+      # core status / routes / system panels.
+      def dispatch_dashboard(method, path, env)
         case [method, path]
         when ["GET", "/__dev"], ["GET", "/__dev/"]
           serve_dashboard
@@ -413,54 +441,24 @@ module Tina4
         when ["GET", "/__dev/api/mtime"]
           json_response({ mtime: @reload_mtime || 0, file: @reload_file || "" })
         when ["POST", "/__dev/api/reload"]
-          body = read_json_body(env) || {}
-          @reload_mtime = Time.now.to_i
-          @reload_file = body["file"] || ""
-          reload_type = body["type"] || "reload"
-          Tina4::Log.info("External reload trigger: #{reload_type}#{@reload_file.empty? ? '' : " (#{@reload_file})"}")
-          # Re-discover so files dropped into src/routes/ register without
-          # a server restart. Idempotent — already-loaded files are skipped,
-          # changed files are re-loaded (mtime-tracked).
-          begin
-            Tina4::Router.rescan_routes!
-          rescue StandardError => e
-            Tina4::Log.error("Re-discover on reload failed: #{e.message}")
-          end
-          # Keep the code Context index LIVE on the same reload trigger: reindex
-          # just the changed file (UPSERT) so the dev-MCP code_search reflects
-          # the edit immediately. Only touches an already-built index
-          # (existing_context never creates one); guarded so a context failure
-          # never breaks the reload.
-          begin
-            unless @reload_file.to_s.empty?
-              ctx = Tina4::Context.existing_context
-              ctx&.reindex_file(@reload_file)
-            end
-          rescue StandardError => e
-            Tina4::Log.error("Context reindex on reload failed: #{e.message}")
-          end
-          # WebSocket-primary reload: push an instant message to every browser
-          # connected on /__dev_reload. The toolbar client (and the dev-admin
-          # dashboard) act on this immediately — the mtime poll above is only a
-          # fallback for when the socket is down. CSS changes swap stylesheets;
-          # everything else triggers a full page reload. We normalise the wire
-          # `type` to "css"/"reload" (the clients only react to css/reload/change)
-          # but still echo the caller's original type in the HTTP response.
-          # Wrapped so a broadcast failure — or zero connected clients — never
-          # 500s the reload endpoint.
-          begin
-            ws_type = reload_type == "css" ? "css" : "reload"
-            Tina4::DevReload.broadcast(
-              JSON.generate({ type: ws_type, file: @reload_file, mtime: @reload_mtime })
-            )
-          rescue StandardError => e
-            Tina4::Log.error("Dev-reload WebSocket broadcast failed: #{e.message}")
-          end
-          json_response({ ok: true, type: reload_type })
+          handle_reload(env)
         when ["GET", "/__dev/api/status"]
           json_response(status_payload)
         when ["GET", "/__dev/api/routes"]
           json_response(routes_payload)
+        when ["GET", "/__dev/api/system"]
+          json_response(system_payload)
+        when ["GET", "/__dev/api/version-check"]
+          json_response(version_check_payload)
+        when ["GET", "/__dev/api/git/status"]
+          json_response(git_status_payload)
+        end
+      end
+
+      # Observability panels: message log, request inspector and live
+      # WebSocket connections. (Mailbox + error tracker live in dispatch_mailbox.)
+      def dispatch_inspectors(method, path, env)
+        case [method, path]
         when ["GET", "/__dev/api/messages"]
           category = query_param(env, "category")
           messages = message_log.get(category: category)
@@ -471,68 +469,31 @@ module Tina4
           category = body["category"] if body
           message_log.clear(category: category)
           json_response({ cleared: true })
+        when ["GET", "/__dev/api/messages/search"]
+          keyword = query_param(env, "q") || query_param(env, "keyword") || ""
+          all_messages = message_log.get
+          filtered = keyword.empty? ? all_messages : all_messages.select { |m| m[:message].to_s.downcase.include?(keyword.downcase) }
+          json_response({ messages: filtered, count: filtered.size, keyword: keyword })
         when ["GET", "/__dev/api/requests"]
           limit = (query_param(env, "limit") || 50).to_i
           json_response({ requests: request_inspector.get(limit: limit), stats: request_inspector.stats })
         when ["POST", "/__dev/api/requests/clear"]
           request_inspector.clear
           json_response({ cleared: true })
-        when ["GET", "/__dev/api/system"]
-          json_response(system_payload)
-        when ["GET", "/__dev/api/queue/topics"]
-          json_response({ topics: queue_topics })
-        when ["GET", "/__dev/api/queue/dead-letters"]
-          topic = query_param(env, "topic") || "default"
-          jobs = begin
-            queue_dead_letters(topic)
-          rescue StandardError
-            []
-          end
-          json_response({ jobs: jobs, count: jobs.size, topic: topic })
-        when ["GET", "/__dev/api/queue"]
-          topic = query_param(env, "topic") || "default"
-          stats = { pending: 0, completed: 0, failed: 0, reserved: 0 }
-          jobs = []
-          begin
-            if defined?(Tina4::Queue)
-              queue = Tina4::Queue.new(backend: :file, topic: topic)
-              # Queue#size is keyword-only (def size(status:)). Calling it
-              # positionally raises ArgumentError, which the rescue below
-              # swallows — silently zeroing every stat. Use keyword form.
-              stats = {
-                pending: queue.size(status: "pending"),
-                completed: queue.size(status: "completed"),
-                failed: queue.size(status: "failed"),
-                reserved: queue.size(status: "reserved"),
-              }
-              jobs = queue_jobs(topic, query_param(env, "status"))
-            end
-          rescue StandardError
-            # fall through to empty stats
-          end
-          json_response({ jobs: jobs, stats: stats })
-        when ["GET", "/__dev/api/mailbox"]
-          messages = mailbox.inbox
-          json_response({ messages: messages, count: messages.size, unread: mailbox.unread_count })
-        when ["GET", "/__dev/api/broken"]
-          errors   = error_tracker.get(include_resolved: true)
-          h        = error_tracker.health
-          json_response({ errors: errors, count: errors.size, health: h })
-        when ["POST", "/__dev/api/broken/resolve"]
-          body = read_json_body(env)
-          id   = body && body["id"]
-          resolved = id ? error_tracker.resolve(id) : false
-          json_response({ resolved: resolved, id: id })
-        when ["POST", "/__dev/api/broken/clear"]
-          # "Clear All" button — flush every tracked error, not only the
-          # ones individually marked resolved. Matches PHP/Python.
-          error_tracker.clear_all
-          json_response({ cleared: true })
         when ["GET", "/__dev/api/websockets"]
           json_response(websockets_payload)
         when ["POST", "/__dev/api/websockets/disconnect"]
           body = read_json_body(env) || {}
           json_response(websockets_disconnect(body))
+        end
+      end
+
+      # Dev mailbox (email capture) and the error tracker panel.
+      def dispatch_mailbox(method, path, env)
+        case [method, path]
+        when ["GET", "/__dev/api/mailbox"]
+          messages = mailbox.inbox
+          json_response({ messages: messages, count: messages.size, unread: mailbox.unread_count })
         when ["GET", "/__dev/api/mailbox/read"]
           message_id = query_param(env, "id")
           message = mailbox.read(message_id)
@@ -550,11 +511,39 @@ module Tina4
         when ["POST", "/__dev/api/mailbox/clear"]
           mailbox.clear
           json_response({ cleared: true })
-        when ["GET", "/__dev/api/messages/search"]
-          keyword = query_param(env, "q") || query_param(env, "keyword") || ""
-          all_messages = message_log.get
-          filtered = keyword.empty? ? all_messages : all_messages.select { |m| m[:message].to_s.downcase.include?(keyword.downcase) }
-          json_response({ messages: filtered, count: filtered.size, keyword: keyword })
+        when ["GET", "/__dev/api/broken"]
+          errors   = error_tracker.get(include_resolved: true)
+          h        = error_tracker.health
+          json_response({ errors: errors, count: errors.size, health: h })
+        when ["POST", "/__dev/api/broken/resolve"]
+          body = read_json_body(env)
+          id   = body && body["id"]
+          resolved = id ? error_tracker.resolve(id) : false
+          json_response({ resolved: resolved, id: id })
+        when ["POST", "/__dev/api/broken/clear"]
+          # "Clear All" button — flush every tracked error, not only the
+          # ones individually marked resolved. Matches PHP/Python.
+          error_tracker.clear_all
+          json_response({ cleared: true })
+        end
+      end
+
+      # Queue panel: topic list, dead letters, per-topic overview and the
+      # retry / purge / replay mutations.
+      def dispatch_queue(method, path, env)
+        case [method, path]
+        when ["GET", "/__dev/api/queue/topics"]
+          json_response({ topics: queue_topics })
+        when ["GET", "/__dev/api/queue/dead-letters"]
+          topic = query_param(env, "topic") || "default"
+          jobs = begin
+            queue_dead_letters(topic)
+          rescue StandardError
+            []
+          end
+          json_response({ jobs: jobs, count: jobs.size, topic: topic })
+        when ["GET", "/__dev/api/queue"]
+          queue_overview(env)
         when ["POST", "/__dev/api/queue/retry"]
           body = read_json_body(env) || {}
           json_response(queue_retry(body))
@@ -564,18 +553,18 @@ module Tina4
         when ["POST", "/__dev/api/queue/replay"]
           body = read_json_body(env) || {}
           json_response(queue_replay(body))
+        end
+      end
+
+      # Data + tooling: table browser, seeding, the run-chips (migrate / test /
+      # seed), the SQL console, table list, the gallery and the metrics panels.
+      def dispatch_data(method, path, env)
+        case [method, path]
         when ["GET", "/__dev/api/table"]
           table_name = query_param(env, "name")
           json_response(table_detail_payload(table_name))
         when ["POST", "/__dev/api/seed"]
-          body = read_json_body(env)
-          table_name = (body && body["table"]) || ""
-          count = (body && body["count"]) || 10
-          seed = body && body["seed"]
-          seed = (Integer(seed) rescue nil) unless seed.nil?
-          clear = body && (body["clear"] == true || body["clear"].to_s == "true")
-          strict = body && (body["strict"] == true || body["strict"].to_s == "true")
-          json_response(seed_table_data(table_name, count.to_i, seed: seed, clear: clear, strict: strict))
+          handle_seed(env)
         when ["POST", "/__dev/api/tool"]
           body = read_json_body(env)
           tool = (body && body["tool"]) || ""
@@ -590,6 +579,28 @@ module Tina4
           json_response(run_tests_payload)
         when ["POST", "/__dev/api/seed/run"]
           json_response(run_seeds_payload)
+        when ["POST", "/__dev/api/query"]
+          body = read_json_body(env)
+          sql = (body && (body["query"] || body["sql"])) || ""
+          json_response(run_query(sql))
+        when ["GET", "/__dev/api/tables"]
+          json_response(tables_payload)
+        when ["GET", "/__dev/api/gallery"]
+          json_response(gallery_list)
+        when ["POST", "/__dev/api/gallery/deploy"]
+          body = read_json_body(env)
+          name = (body && body["name"]) || ""
+          json_response(gallery_deploy(name))
+        when ["GET", "/__dev/api/metrics/full"]
+          metrics_full_response
+        when ["GET", "/__dev/api/metrics/file"]
+          metrics_file_response(env)
+        end
+      end
+
+      # Grounding token panel and the database-connection editor.
+      def dispatch_config(method, path, env)
+        case [method, path]
         # Grounding panel — configure the tina4-coder MCP token used for
         # live-docs grounding. Self-contained (.env read/write); no proxy.
         when ["GET", "/__dev/api/grounding/status"]
@@ -605,40 +616,13 @@ module Tina4
         when ["POST", "/__dev/api/connections/save"]
           body = read_json_body(env)
           handle_connections_save(body)
-        when ["POST", "/__dev/api/query"]
-          body = read_json_body(env)
-          sql = (body && (body["query"] || body["sql"])) || ""
-          json_response(run_query(sql))
-        when ["GET", "/__dev/api/tables"]
-          json_response(tables_payload)
-        when ["GET", "/__dev/api/gallery"]
-          json_response(gallery_list)
-        when ["POST", "/__dev/api/gallery/deploy"]
-          body = read_json_body(env)
-          name = (body && body["name"]) || ""
-          json_response(gallery_deploy(name))
-        when ["GET", "/__dev/api/version-check"]
-          json_response(version_check_payload)
-        when ["GET", "/__dev/api/metrics/full"]
-          # No fallback (ADR-0002). A missing or stale CLI is a 503 naming the
-          # install command, never zeros that read as a healthy codebase.
-          begin
-            json_response(Tina4::Metrics.full_analysis)
-          rescue Tina4::MetricsEngineError => e
-            json_response({ "error" => e.message }, 503)
-          end
-        when ["GET", "/__dev/api/metrics/file"]
-          file_path = (query_param(env, "path") || "").to_s
-          begin
-            json_response(Tina4::Metrics.file_detail(file_path))
-          rescue Tina4::MetricsEngineError => e
-            # A bad path is the caller's mistake (404); anything else is the
-            # engine being unavailable (503).
-            bad_path = e.message.include?("no such file") ||
-                       e.message.include?("not a file") ||
-                       e.message.include?("needs a path")
-            json_response({ "error" => e.message }, bad_path ? 404 : 503)
-          end
+        end
+      end
+
+      # File browser + editor (read / raw / save / rename / delete) and the
+      # dependency search / install surface.
+      def dispatch_files(method, path, env)
+        case [method, path]
         when ["GET", "/__dev/api/files"]
           json_response(files_list(env))
         when ["GET", "/__dev/api/file"]
@@ -662,8 +646,13 @@ module Tina4
         when ["POST", "/__dev/api/deps/install"]
           body = read_json_body(env) || {}
           json_response(deps_install(body))
-        when ["GET", "/__dev/api/git/status"]
-          json_response(git_status_payload)
+        end
+      end
+
+      # The MCP surfaces (REST shim + JSON-RPC + SSE), scaffolding, and the
+      # live-docs (Live API RAG) + GraphQL-schema endpoints.
+      def dispatch_mcp(method, path, env)
+        case [method, path]
         # All four MCP surfaces (REST shim + JSON-RPC + SSE) go through
         # with_mcp_gate: capability (Tina4.mcp_enabled?) decides whether MCP
         # runs at all (off → route behaves as unmounted, nil → RackApp 404,
@@ -705,23 +694,133 @@ module Tina4
         when ["GET", "/__dev/api/docs/.well-known.json"]
           json_response(docs_well_known_payload)
         when ["GET", "/__dev/api/graphql/schema"]
-          begin
-            gql = Tina4::GraphQL.new
-            # Auto-discover and register all ORM subclasses
-            ObjectSpace.each_object(Class).select { |c| c < Tina4::ORM }.each do |model_class|
-              gql.from_orm(model_class.new)
-            end
-            json_response({ schema: gql.introspect, sdl: gql.schema_sdl })
-          rescue => e
-            json_response({ error: e.message }, 400)
-          end
-        else
-          nil
+          graphql_schema_response
         end
       end
 
+      # POST /__dev/api/reload — external reload trigger. Bumps the mtime
+      # counter, re-discovers routes, keeps the live docs index fresh, and
+      # broadcasts a WebSocket reload to connected browsers.
+      def handle_reload(env)
+        body = read_json_body(env) || {}
+        @reload_mtime = Time.now.to_i
+        @reload_file = body["file"] || ""
+        reload_type = body["type"] || "reload"
+        Tina4::Log.info("External reload trigger: #{reload_type}#{@reload_file.empty? ? '' : " (#{@reload_file})"}")
+        # Re-discover so files dropped into src/routes/ register without
+        # a server restart. Idempotent — already-loaded files are skipped,
+        # changed files are re-loaded (mtime-tracked).
+        begin
+          Tina4::Router.rescan_routes!
+        rescue StandardError => e
+          Tina4::Log.error("Re-discover on reload failed: #{e.message}")
+        end
+        # Keep the code Context index LIVE on the same reload trigger: reindex
+        # just the changed file (UPSERT) so the dev-MCP code_search reflects
+        # the edit immediately. Only touches an already-built index
+        # (existing_context never creates one); guarded so a context failure
+        # never breaks the reload.
+        begin
+          unless @reload_file.to_s.empty?
+            ctx = Tina4::Context.existing_context
+            ctx&.reindex_file(@reload_file)
+          end
+        rescue StandardError => e
+          Tina4::Log.error("Context reindex on reload failed: #{e.message}")
+        end
+        # WebSocket-primary reload: push an instant message to every browser
+        # connected on /__dev_reload. The toolbar client (and the dev-admin
+        # dashboard) act on this immediately — the mtime poll above is only a
+        # fallback for when the socket is down. CSS changes swap stylesheets;
+        # everything else triggers a full page reload. We normalise the wire
+        # `type` to "css"/"reload" (the clients only react to css/reload/change)
+        # but still echo the caller's original type in the HTTP response.
+        # Wrapped so a broadcast failure — or zero connected clients — never
+        # 500s the reload endpoint.
+        begin
+          ws_type = reload_type == "css" ? "css" : "reload"
+          Tina4::DevReload.broadcast(
+            JSON.generate({ type: ws_type, file: @reload_file, mtime: @reload_mtime })
+          )
+        rescue StandardError => e
+          Tina4::Log.error("Dev-reload WebSocket broadcast failed: #{e.message}")
+        end
+        json_response({ ok: true, type: reload_type })
+      end
 
-      private
+      # GET /__dev/api/queue — per-topic stats + job list. Queue#size is
+      # keyword-only; the rescue swallows a backend error into empty stats.
+      def queue_overview(env)
+        topic = query_param(env, "topic") || "default"
+        stats = { pending: 0, completed: 0, failed: 0, reserved: 0 }
+        jobs = []
+        begin
+          if defined?(Tina4::Queue)
+            queue = Tina4::Queue.new(backend: :file, topic: topic)
+            # Queue#size is keyword-only (def size(status:)). Calling it
+            # positionally raises ArgumentError, which the rescue below
+            # swallows — silently zeroing every stat. Use keyword form.
+            stats = {
+              pending: queue.size(status: "pending"),
+              completed: queue.size(status: "completed"),
+              failed: queue.size(status: "failed"),
+              reserved: queue.size(status: "reserved"),
+            }
+            jobs = queue_jobs(topic, query_param(env, "status"))
+          end
+        rescue StandardError
+          # fall through to empty stats
+        end
+        json_response({ jobs: jobs, stats: stats })
+      end
+
+      # POST /__dev/api/seed — seed fake rows into a table via the shared
+      # resilient seed_table helper.
+      def handle_seed(env)
+        body = read_json_body(env)
+        table_name = (body && body["table"]) || ""
+        count = (body && body["count"]) || 10
+        seed = body && body["seed"]
+        seed = (Integer(seed) rescue nil) unless seed.nil?
+        clear = body && (body["clear"] == true || body["clear"].to_s == "true")
+        strict = body && (body["strict"] == true || body["strict"].to_s == "true")
+        json_response(seed_table_data(table_name, count.to_i, seed: seed, clear: clear, strict: strict))
+      end
+
+      # GET /__dev/api/metrics/full — native metrics (ADR-0002). No fallback:
+      # a missing/stale CLI is a 503 naming the install command, never zeros
+      # that read as a healthy codebase.
+      def metrics_full_response
+        json_response(Tina4::Metrics.full_analysis)
+      rescue Tina4::MetricsEngineError => e
+        json_response({ "error" => e.message }, 503)
+      end
+
+      # GET /__dev/api/metrics/file — metrics for one file. A bad path is the
+      # caller's mistake (404); anything else is the engine being unavailable
+      # (503).
+      def metrics_file_response(env)
+        file_path = (query_param(env, "path") || "").to_s
+        json_response(Tina4::Metrics.file_detail(file_path))
+      rescue Tina4::MetricsEngineError => e
+        bad_path = e.message.include?("no such file") ||
+                   e.message.include?("not a file") ||
+                   e.message.include?("needs a path")
+        json_response({ "error" => e.message }, bad_path ? 404 : 503)
+      end
+
+      # GET /__dev/api/graphql/schema — introspect every ORM subclass into a
+      # GraphQL schema + SDL.
+      def graphql_schema_response
+        gql = Tina4::GraphQL.new
+        # Auto-discover and register all ORM subclasses
+        ObjectSpace.each_object(Class).select { |c| c < Tina4::ORM }.each do |model_class|
+          gql.from_orm(model_class.new)
+        end
+        json_response({ schema: gql.introspect, sdl: gql.schema_sdl })
+      rescue => e
+        json_response({ error: e.message }, 400)
+      end
 
       def query_param(env, key)
         qs = env["QUERY_STRING"] || ""

data/lib/tina4/push.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+require "net/http"
+require "uri"
+
+module Tina4
+  class PushError < StandardError; end
+
+  # Provider-neutral Web Push sender using Ruby's stdlib OpenSSL and Net::HTTP.
+  # Web Push remains optional at use time; a Ruby build without OpenSSL fails
+  # loudly when the feature is selected rather than silently sending plaintext.
+  class Push
+    RECORD_SIZE = 4096
+    MAX_PAYLOAD = RECORD_SIZE - 17
+
+    def self.generate_vapid_keys
+      require_openssl
+      key = OpenSSL::PKey::EC.generate("prime256v1")
+      {
+        "publicKey" => b64(key.public_key.to_bn.to_s(2)),
+        "privateKey" => b64(key.private_key.to_s(2))
+      }
+    end
+
+    def initialize(subject: nil, public_key: nil, private_key: nil, ttl: 60, urgency: nil)
+      @subject = (subject || ENV.fetch("TINA4_VAPID_SUBJECT", "")).strip
+      @public_key = (public_key || ENV.fetch("TINA4_VAPID_PUBLIC", "")).strip
+      @private_key = (private_key || ENV.fetch("TINA4_VAPID_PRIVATE", "")).strip
+      @ttl = ttl
+      @urgency = urgency
+      if %w[0 false off no].include?(ENV.fetch("TINA4_WEB_PUSH", "").strip.downcase)
+        raise PushError, "Web Push is disabled by TINA4_WEB_PUSH"
+      end
+      configuration if [@subject, @public_key, @private_key].any? { |value| !value.empty? }
+    end
+
+    def send(subscription, payload)
+      endpoint, uri = endpoint_for(subscription)
+      subject, public_key, private_key = configuration
+      public, private = vapid_keys(public_key, private_key)
+      deliver(endpoint, uri, subject, public_key, private, public, encrypt(payload_bytes(payload), subscription))
+    rescue URI::InvalidURIError => e
+      raise PushError, "Push subscription endpoint must be a valid URL: #{e.message}"
+    rescue Net::HTTPError, SocketError, SystemCallError => e
+      raise PushError, "Web Push request failed: #{e.message}"
+    end
+
+    private
+
+    def endpoint_for(subscription)
+      endpoint = subscription.is_a?(Hash) ? (subscription["endpoint"] || subscription[:endpoint]) : nil
+      raise PushError, "A Web Push subscription with an endpoint is required" unless endpoint.is_a?(String) && !endpoint.empty?
+      uri = URI.parse(endpoint)
+      raise PushError, "Push subscription endpoint must use HTTP or HTTPS" unless %w[http https].include?(uri.scheme) && uri.host
+      [endpoint, uri]
+    end
+
+    def vapid_keys(public_key, private_key)
+      public = decode(public_key, "TINA4_VAPID_PUBLIC")
+      private = decode(private_key, "TINA4_VAPID_PRIVATE")
+      raise PushError, "TINA4_VAPID_PUBLIC must be a 65-byte P-256 public key" unless public.bytesize == 65 && public.getbyte(0) == 4
+      raise PushError, "TINA4_VAPID_PRIVATE must be a 32-byte P-256 private key" unless private.bytesize == 32
+      begin
+        derived = private_key_from_raw(private, public).public_key.to_bn.to_s(2)
+      rescue OpenSSL::PKey::PKeyError => e
+        raise PushError, "TINA4_VAPID_PRIVATE is not a valid P-256 private key: #{e.message}"
+      end
+      raise PushError, "TINA4_VAPID_PUBLIC does not match TINA4_VAPID_PRIVATE" unless derived == public
+      [public, private]
+    end
+
+    def deliver(endpoint, uri, subject, public_key, private, public, body)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "vapid t=#{vapid_token(uri, subject, private, public)}, k=#{public_key}"
+      request["Content-Encoding"] = "aes128gcm"
+      request["Content-Type"] = "application/octet-stream"
+      request["TTL"] = @ttl.to_i.to_s
+      request["Urgency"] = @urgency if @urgency && !@urgency.empty?
+      request.body = body
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      response = http.start { |client| client.request(request) }
+      status = response.code.to_i
+      { "ok" => status < 400, "status" => status, "dead" => [404, 410].include?(status), "retryable" => [408, 429].include?(status) || status >= 500, "endpoint" => endpoint, "response" => response.body.to_s }
+    end
+
+    def configuration
+      missing = []
+      missing << "TINA4_VAPID_SUBJECT" if @subject.empty?
+      missing << "TINA4_VAPID_PUBLIC" if @public_key.empty?
+      missing << "TINA4_VAPID_PRIVATE" if @private_key.empty?
+      raise PushError, "Web Push is configured but missing: #{missing.join(', ')}" unless missing.empty?
+      self.class.send(:require_openssl)
+      [@subject, @public_key, @private_key]
+    end
+
+    def self.require_openssl
+      return if defined?(OpenSSL::PKey::EC)
+
+      raise PushError, "Web Push requires Ruby's OpenSSL stdlib capability; rebuild Ruby with OpenSSL support"
+    end
+
+    def self.b64(value)
+      Base64.urlsafe_encode64(value, padding: false)
+    end
+
+    def decode(value, name)
+      raise PushError, "#{name} must be a non-empty base64url string" unless value.is_a?(String) && value.match?(/\A[A-Za-z0-9_-]+\z/)
+
+      Base64.urlsafe_decode64(value)
+    rescue ArgumentError => e
+      raise PushError, "#{name} must be base64url encoded: #{e.message}"
+    end
+
+    def payload_bytes(payload)
+      return payload.b if payload.is_a?(String)
+      JSON.generate(payload)
+    rescue JSON::GeneratorError => e
+      raise PushError, "Push payload is not JSON serializable: #{e.message}"
+    end
+
+    def private_key_from_raw(private, public)
+      body = OpenSSL::ASN1::Sequence.new([
+        OpenSSL::ASN1::Integer.new(1),
+        OpenSSL::ASN1::OctetString.new(private),
+        OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::ObjectId.new("prime256v1")], 0, :CONTEXT_SPECIFIC),
+        OpenSSL::ASN1::ASN1Data.new([OpenSSL::ASN1::BitString.new(public)], 1, :CONTEXT_SPECIFIC)
+      ])
+      OpenSSL::PKey.read(body.to_der)
+    end
+
+    def public_key_from_raw(public)
+      algorithm = OpenSSL::ASN1::Sequence.new([OpenSSL::ASN1::ObjectId.new("id-ecPublicKey"), OpenSSL::ASN1::ObjectId.new("prime256v1")])
+      OpenSSL::PKey.read(OpenSSL::ASN1::Sequence.new([algorithm, OpenSSL::ASN1::BitString.new(public)]).to_der)
+    end
+
+    def encrypt(payload, subscription)
+      raise PushError, "Push payload is too large; maximum is #{MAX_PAYLOAD} bytes" if payload.bytesize > MAX_PAYLOAD
+      keys = subscription.is_a?(Hash) ? (subscription["keys"] || subscription[:keys] || {}) : {}
+      p256dh = keys["p256dh"] || keys[:p256dh]
+      auth = keys["auth"] || keys[:auth]
+      client = decode(p256dh.to_s, "subscription.keys.p256dh")
+      auth_secret = decode(auth.to_s, "subscription.keys.auth")
+      raise PushError, "subscription.keys.p256dh must be a 65-byte P-256 public key" unless client.bytesize == 65 && client.getbyte(0) == 4
+      raise PushError, "subscription.keys.auth must be a 16-byte authentication secret" unless auth_secret.bytesize == 16
+
+      ephemeral = OpenSSL::PKey::EC.generate("prime256v1")
+      server = ephemeral.public_key.to_bn.to_s(2)
+      shared = ephemeral.derive(public_key_from_raw(client))
+      ikm = hkdf(hmac(auth_secret, shared), "WebPush: info\0" + client + server, 32)
+      salt = OpenSSL::Random.random_bytes(16)
+      prk = hmac(salt, ikm)
+      cek = hkdf(prk, "Content-Encoding: aes128gcm\0", 16)
+      nonce = hkdf(prk, "Content-Encoding: nonce\0", 12)
+      cipher = OpenSSL::Cipher.new("aes-128-gcm")
+      cipher.encrypt
+      cipher.key = cek
+      cipher.iv = nonce
+      ciphertext = cipher.update(payload + "\x02") + cipher.final
+      tag = cipher.auth_tag
+      salt + [RECORD_SIZE].pack("N") + [server.bytesize].pack("C") + server + ciphertext + tag
+    end
+
+    def hmac(key, value)
+      OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, key, value)
+    end
+
+    def hkdf(prk, info, length)
+      output = +""
+      previous = +""
+      counter = 1
+      while output.bytesize < length
+        previous = hmac(prk, previous + info + [counter].pack("C"))
+        output << previous
+        counter += 1
+        raise PushError, "HKDF output is too large" if counter > 255
+      end
+      output.byteslice(0, length)
+    end
+
+    def vapid_token(uri, subject, private, public)
+      aud = "#{uri.scheme}://#{uri.host}#{uri.port && ![80, 443].include?(uri.port) ? ":#{uri.port}" : ""}"
+      header = self.class.send(:b64, JSON.generate({ typ: "JWT", alg: "ES256" }))
+      claims = self.class.send(:b64, JSON.generate({ aud: aud, exp: Time.now.to_i + 43_200, sub: subject }))
+      input = "#{header}.#{claims}"
+      signature = private_key_from_raw(private, public).sign(OpenSSL::Digest::SHA256.new, input)
+      asn = OpenSSL::ASN1.decode(signature)
+      raw = [asn.value[0].value.to_s(2), asn.value[1].value.to_s(2)].map { |value| value.rjust(32, "\0") }.join
+      "#{input}.#{self.class.send(:b64, raw)}"
+    end
+  end
+end

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -169,6 +169,8 @@ module Tina4
   autoload :MqttError,           File.expand_path("tina4/mqtt", __dir__)
   autoload :MqttTimeoutError,    File.expand_path("tina4/mqtt", __dir__)
   autoload :MqttMessage,         File.expand_path("tina4/mqtt_message", __dir__)
+  autoload :Push,                File.expand_path("tina4/push", __dir__)
+  autoload :PushError,           File.expand_path("tina4/push", __dir__)
   autoload :Testing,             File.expand_path("tina4/testing", __dir__)
   # Queue / Messenger / DocStore were the last three optional subsystems still
   # loaded eagerly, so every `require "tina4"` paid for a queue backend, an

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.132
+  version: 3.13.134
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -405,6 +405,7 @@ files:
 - lib/tina4/public/js/tina4js.min.js
 - lib/tina4/public/swagger/index.html
 - lib/tina4/public/swagger/oauth2-redirect.html
+- lib/tina4/push.rb
 - lib/tina4/query_builder.rb
 - lib/tina4/queue.rb
 - lib/tina4/queue_backends/kafka_backend.rb