tina4ruby 3.13.99 → 3.13.101

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11d1350ed25f20cfc7c7ba9757417c0eb33e87292eb45876d3bed30119fefcca
-  data.tar.gz: 8bd0d33d8ae49492bd8784fb838339951ad92439bf96a615d71ffe2e488dfd7a
+  metadata.gz: 9102cf347865953d60e7d47b1ead3b87e25f139f1439a19e5f230ec31594c32a
+  data.tar.gz: 7a5323f6a9d26e41852269c63d76fac619a59b549e634aad6a56bdc887dcb780
 SHA512:
-  metadata.gz: e24bac573c4d4b58642fdc65071857c4a910dac229057f92c9eca2ba0936c1163a6e89bc79452c82f7d4601a4e64b0c10ce5c0af3e35384c16344491c6f61203
-  data.tar.gz: 0afe568dfd38eee2c0ce7c507b71b8c0110e11be10cce5197100244d30e56ac58e119b25a1e5757df8b26a9bb74172b4739d1e94ef029729e7b3e932e2847032
+  metadata.gz: b0d72050d8db6db2ca5a1c621c6212848ef094ab84a3718b32aa06d53912c74c0324973374b1dafc6dd43d64b52dd34cb574a806fe79f034ac8757c0400db1cb
+  data.tar.gz: b13a9d5139f751391a684e28858bc894268fbb511ca192615eb48181dda59784faddcebcbdf6ae74aefb08736a53e9e356d432bc0ec4f6b69b50132c75a6e3f3

data/CHANGELOG.md

@@ -6,6 +6,40 @@ 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.101
+
+### Breaking: metrics has one owner
+
+- Remove the framework `metrics` command and local quick census. Use the native `tina4 metrics` CLI.
+- Keep dev-admin metrics as a thin `/metrics/full` and `/metrics/file` JSON handoff to that CLI.
+
+### App-facing AI client
+
+- Add zero-dependency `Tina4::Ai.chat`, `Tina4::Ai.complete`, and `Tina4::Ai.embed`.
+- Support local/OpenAI-compatible, OpenAI, and Anthropic chat providers.
+- Normalize chat responses, stream ordered deltas, and preserve embedding cardinality.
+- Fail closed on missing hosted-provider keys, verify TLS, redact sensitive failures, and
+  distinguish bounded connection and total-request timeouts.
+- Retry only transient connection, HTTP 429, and HTTP 5xx failures, never a partial stream.
+
+## 3.13.100
+
+### Breaking: Frond instance extensions stay local
+
+Calling `add_filter`, `add_global`, or `add_test` on a Frond instance now changes
+that renderer only. Register on `Frond` itself when every later instance must
+inherit the extension.
+
+- Reject a second `{% extends %}` tag instead of replacing the first parent without warning.
+- Resolve multi-level inheritance without recursing through the same child template.
+- Preserve nested root blocks through a depth-aware final substitution pass.
+- Bound template, fragment, and expression caches, with TTL sweeps for stale entries.
+- Retry transient AI skill-download failures.
+- Activate the tina4-js skill for `tina4js` and `Tina4 JS` spellings as well as `tina4-js`.
+- Keep `Tina4::VERSION` and both AI-facing guide markers on one version.
+
+## 3.13.99
+
 ### Breaking: `request.params` is route-params-only, and `path_params` is renamed `params`
 
 Ruby had the worst version of the param-pollution bug: `params` used to merge the query

data/README.md

@@ -68,6 +68,18 @@ db = Tina4::Database.new("sqlite://app.db")
 
 **2,508 tests. Zero runtime dependencies. Full parity across Python, PHP, Ruby, and Node.js.**
 
+### AI Client
+
+```ruby
+reply = Tina4::Ai.chat([{ role: "user", content: "Summarise this text" }])
+text = Tina4::Ai.complete("Give me a title")
+vector = Tina4::Ai.embed("semantic search text")
+
+Tina4::Ai.chat([{ role: "user", content: "Stream this" }], stream: true).each { |delta| print delta }
+```
+
+Configure `TINA4_AI_PROVIDER` as `local`, `openai`, or `anthropic`. Hosted providers require `TINA4_AI_KEY`; local OpenAI-compatible endpoints do not.
+
 ---
 
 ## CLI Reference

data/lib/tina4/ai_client.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Tina4
+  class AiError < StandardError; end
+  class AiConfigError < AiError; end
+  class AiTimeoutError < AiError; end
+  class AiParseError < AiError; end
+
+  class AiHTTPError < AiError
+    attr_reader :status
+
+    def initialize(message, status = nil)
+      super(message)
+      @status = status
+    end
+  end
+
+  ChatResponse = Struct.new(:text, :model, :usage, :finish_reason, :raw, keyword_init: true)
+
+  # Zero-dependency app-facing AI client (ADR-0053).
+  class Ai
+    PROVIDERS = %w[local openai anthropic].freeze
+
+    class << self
+      def chat(messages, model: nil, temperature: nil, max_tokens: nil, stream: false, timeout: nil, provider: nil)
+        validate_messages(messages)
+        config = resolve_config("chat", model, timeout, provider)
+        body = chat_body(config, messages, temperature, max_tokens, stream)
+        return stream_request(config, headers(config), body) if stream
+
+        normalize_chat(config[:provider], request_json(config, headers(config), body))
+      end
+
+      def complete(prompt, **options)
+        raise AiConfigError, "AI prompt must be a string" unless prompt.is_a?(String)
+
+        options.delete(:stream)
+        chat([{ role: "user", content: prompt }], **options, stream: false).text
+      end
+
+      def embed(text_or_texts, model: nil, timeout: nil, provider: nil)
+        single = text_or_texts.is_a?(String)
+        valid_batch = text_or_texts.is_a?(Array) && !text_or_texts.empty? && text_or_texts.all? { |item| item.is_a?(String) }
+        raise AiConfigError, "AI embedding input must be a string or a non-empty list of strings" unless single || valid_batch
+
+        config = resolve_config("embed", model, timeout, provider)
+        raise AiConfigError, "Anthropic does not provide the embedding endpoint in this contract" if config[:provider] == "anthropic"
+
+        raw = request_json(config, headers(config), { model: config[:model], input: text_or_texts })
+        begin
+          data = raw.fetch("data").sort_by { |item| item.fetch("index", 0) }
+          vectors = data.map { |item| item.fetch("embedding") }
+          expected = single ? 1 : text_or_texts.length
+          valid = vectors.length == expected && vectors.all? do |vector|
+            vector.is_a?(Array) && !vector.empty? && vector.all? { |value| value.is_a?(Numeric) }
+          end
+          raise KeyError unless valid
+        rescue KeyError, TypeError
+          raise AiParseError, "AI provider returned a malformed embedding response"
+        end
+        single ? vectors.first : vectors
+      end
+
+      private
+
+      def validate_messages(messages)
+        valid = messages.is_a?(Array) && !messages.empty? && messages.all? do |message|
+          message.is_a?(Hash) && %w[system user assistant].include?((message[:role] || message["role"]).to_s) &&
+            (message.key?(:content) ? message[:content] : message["content"]).is_a?(String)
+        end
+        raise AiConfigError, "AI messages must contain supported roles and string content" unless valid
+      end
+
+      def number(name, default, minimum)
+        value = Float(ENV.fetch(name, default.to_s))
+        raise AiConfigError, "#{name} must be at least #{minimum}" if value < minimum
+
+        value
+      rescue ArgumentError, TypeError
+        raise AiConfigError, "#{name} must be numeric"
+      end
+
+      def resolve_config(capability, model, timeout, provider)
+        selected = (provider || ENV["TINA4_AI_PROVIDER"] || "local").strip.downcase
+        raise AiConfigError, "TINA4_AI_PROVIDER must be local, openai, or anthropic" unless PROVIDERS.include?(selected)
+
+        key = ENV["TINA4_AI_KEY"]
+        if %w[openai anthropic].include?(selected) && (key.nil? || key.empty?)
+          raise AiConfigError, "TINA4_AI_KEY is required for the #{selected} provider"
+        end
+        defaults = {
+          "local" => ["http://localhost:11437", "llama3.2"],
+          "openai" => ["https://api.openai.com/v1", "gpt-4o-mini"],
+          "anthropic" => ["https://api.anthropic.com/v1", "claude-3-5-haiku-latest"]
+        }
+        value = capability == "embed" && ENV["TINA4_EMBED_URL"] ? ENV["TINA4_EMBED_URL"] : (ENV["TINA4_AI_URL"] || defaults[selected][0])
+        total = timeout.nil? ? number("TINA4_AI_TIMEOUT", 60, 0.001) : Float(timeout)
+        raise AiConfigError, "AI timeout must be greater than zero" unless total.positive?
+
+        chosen_model = (model || ENV["TINA4_AI_MODEL"] || defaults[selected][1]).to_s.strip
+        raise AiConfigError, "AI model must be a non-empty string" if chosen_model.empty?
+
+        {
+          provider: selected,
+          url: endpoint(value, capability, selected),
+          model: chosen_model,
+          key: key,
+          total_timeout: total,
+          connect_timeout: number("TINA4_AI_CONNECT_TIMEOUT", 10, 0.001),
+          max_retries: number("TINA4_AI_MAX_RETRIES", 2, 0).to_i
+        }
+      rescue ArgumentError, TypeError
+        raise AiConfigError, "AI timeout must be numeric"
+      end
+
+      def endpoint(value, capability, provider)
+        uri = URI.parse(value)
+        raise AiConfigError, "AI URL must be an http or https URL" unless %w[http https].include?(uri.scheme) && uri.host
+
+        path = uri.path.to_s.sub(%r{/+$}, "")
+        if ["", "/v1", "/api"].include?(path)
+          suffix = provider == "anthropic" ? "/messages" : (capability == "embed" ? "/embeddings" : "/chat/completions")
+          uri.path = (path.empty? ? "/v1" : path) + suffix
+        end
+        uri.to_s
+      rescue URI::InvalidURIError
+        raise AiConfigError, "AI URL must be an http or https URL"
+      end
+
+      def headers(config)
+        result = { "Content-Type" => "application/json", "Accept" => "application/json" }
+        if config[:provider] == "openai"
+          result["Authorization"] = "Bearer #{config[:key]}"
+        elsif config[:provider] == "anthropic"
+          result["x-api-key"] = config[:key]
+          result["anthropic-version"] = "2023-06-01"
+        end
+        result
+      end
+
+      def chat_body(config, messages, temperature, max_tokens, stream)
+        normalized = messages.map { |message| { role: (message[:role] || message["role"]).to_s, content: message.key?(:content) ? message[:content] : message["content"] } }
+        body = { model: config[:model], messages: normalized, stream: stream }
+        body[:temperature] = temperature unless temperature.nil?
+        body[:max_tokens] = max_tokens unless max_tokens.nil?
+        if config[:provider] == "anthropic"
+          system = normalized.select { |message| message[:role] == "system" }.map { |message| message[:content] }
+          body[:messages] = normalized.reject { |message| message[:role] == "system" }
+          body[:max_tokens] = max_tokens || 1024
+          body[:system] = system.join("\n\n") unless system.empty?
+        end
+        body
+      end
+
+      def http_request(config, deadline, request_headers, body)
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        raise AiTimeoutError, "AI total request timeout expired" unless remaining.positive?
+
+        uri = URI.parse(config[:url])
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.open_timeout = [config[:connect_timeout], remaining].min
+        http.read_timeout = remaining
+        http.write_timeout = remaining if http.respond_to?(:write_timeout=)
+        request = Net::HTTP::Post.new(uri.request_uri, request_headers)
+        request.body = JSON.generate(body)
+        [http, request]
+      end
+
+      def request_json(config, request_headers, body)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config[:total_timeout]
+        (config[:max_retries] + 1).times do |attempt|
+          begin
+            http, request = http_request(config, deadline, request_headers, body)
+            response = http.request(request)
+            raise AiTimeoutError, "AI total request timeout expired" if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+            status = response.code.to_i
+            unless status.between?(200, 299)
+              if (status == 429 || status >= 500) && attempt < config[:max_retries]
+                retry_delay(response, deadline)
+                next
+              end
+              raise AiHTTPError.new("AI provider returned HTTP #{status}", status)
+            end
+            parsed = JSON.parse(response.body)
+            raise AiParseError, "AI provider returned a non-object JSON response" unless parsed.is_a?(Hash)
+
+            return parsed
+          rescue Net::OpenTimeout
+            raise AiTimeoutError, "AI connection timeout expired" if attempt >= config[:max_retries]
+          rescue Net::ReadTimeout, Timeout::Error
+            raise AiTimeoutError, "AI total request timeout expired" if attempt >= config[:max_retries]
+          rescue AiHTTPError => e
+            raise if e.status || attempt >= config[:max_retries]
+          rescue SocketError, EOFError, IOError, SystemCallError => e
+            raise AiHTTPError, "AI transport failed (#{e.class.name})" if attempt >= config[:max_retries]
+          rescue JSON::ParserError
+            raise AiParseError, "AI provider returned malformed JSON"
+          end
+        end
+        raise AiHTTPError, "AI request failed"
+      end
+
+      def retry_delay(response, deadline)
+        requested = Float(response["retry-after"] || 0.1) rescue 0.1
+        delay = [requested.positive? ? requested : 0, deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)].min
+        sleep(delay) if delay.positive?
+      end
+
+      def normalize_chat(provider, raw)
+        if provider == "anthropic"
+          parts = raw.fetch("content").select { |item| item.fetch("type", "text") == "text" }.map { |item| item.fetch("text") }
+          raise KeyError if parts.empty?
+          prompt = raw.fetch("usage", {}).fetch("input_tokens", 0).to_i
+          completion = raw.fetch("usage", {}).fetch("output_tokens", 0).to_i
+          return ChatResponse.new(text: parts.join, model: raw.fetch("model", "").to_s,
+                                  usage: { prompt_tokens: prompt, completion_tokens: completion, total_tokens: prompt + completion },
+                                  finish_reason: raw["stop_reason"], raw: raw)
+        end
+        choice = raw.fetch("choices").fetch(0)
+        text = choice.fetch("message").fetch("content")
+        raise TypeError unless text.is_a?(String)
+        usage = raw.fetch("usage", {})
+        ChatResponse.new(text: text, model: raw.fetch("model", "").to_s,
+                         usage: { prompt_tokens: usage.fetch("prompt_tokens", 0).to_i,
+                                  completion_tokens: usage.fetch("completion_tokens", 0).to_i,
+                                  total_tokens: usage.fetch("total_tokens", 0).to_i },
+                         finish_reason: choice["finish_reason"], raw: raw)
+      rescue KeyError, IndexError, TypeError
+        raise AiParseError, "AI provider returned a malformed chat response"
+      end
+
+      def stream_delta(provider, data)
+        return [true, nil] if data == "[DONE]"
+
+        event = JSON.parse(data)
+        text = if provider == "anthropic"
+                 event["type"] == "content_block_delta" ? event.dig("delta", "text") : nil
+               else
+                 event.dig("choices", 0, "delta", "content")
+               end
+        raise AiParseError, "AI provider returned malformed stream data" unless text.nil? || text.is_a?(String)
+
+        [false, text]
+      rescue JSON::ParserError
+        raise AiParseError, "AI provider returned malformed stream data"
+      end
+
+      def each_stream_data(response, deadline)
+        buffer = +""
+        response.read_body do |chunk|
+          raise AiTimeoutError, "AI total request timeout expired" if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+          buffer << chunk
+          while (index = buffer.index("\n"))
+            line = buffer.slice!(0..index).strip
+            yield line.delete_prefix("data:").strip if line.start_with?("data:")
+          end
+        end
+      end
+
+      def stream_request(config, request_headers, body)
+        Enumerator.new do |yielder|
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + config[:total_timeout]
+          yielded = false
+          (config[:max_retries] + 1).times do |attempt|
+            begin
+              http, request = http_request(config, deadline, request_headers.merge("Accept" => "text/event-stream"), body)
+              retry_response = false
+              completed = false
+              http.request(request) do |response|
+                status = response.code.to_i
+                unless status.between?(200, 299)
+                  response.read_body { |_chunk| nil }
+                  if (status == 429 || status >= 500) && attempt < config[:max_retries]
+                    retry_delay(response, deadline)
+                    retry_response = true
+                    next
+                  end
+                  raise AiHTTPError.new("AI provider returned HTTP #{status}", status)
+                end
+                each_stream_data(response, deadline) do |data|
+                  completed, text = stream_delta(config[:provider], data)
+                  break if completed
+                  next if text.nil?
+                  yielded = true
+                  yielder << text
+                end
+              end
+              next if retry_response
+              raise AiParseError, "AI provider stream ended before [DONE]" unless completed
+              break
+            rescue Net::OpenTimeout
+              raise AiTimeoutError, "AI connection timeout expired" if yielded || attempt >= config[:max_retries]
+            rescue Net::ReadTimeout, Timeout::Error
+              raise AiTimeoutError, "AI total request timeout expired" if yielded || attempt >= config[:max_retries]
+            rescue SocketError, EOFError, IOError, SystemCallError => e
+              raise AiHTTPError, "AI transport failed (#{e.class.name})" if yielded || attempt >= config[:max_retries]
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tina4/cli.rb

@@ -71,7 +71,6 @@ module Tina4
       "console"          => { handler: :cmd_console,                                                       summary: "Start an interactive console" },
       "generate"         => { handler: :cmd_generate,         usage: "<what> <name> [options]", subcommands: GENERATORS.keys, summary: "Generate scaffolding (see Generators below)" },
       "ai"               => { handler: :cmd_ai,               usage: "[--all]",                            summary: "Detect AI tools and install context files" },
-      "metrics"          => { handler: :cmd_metrics,          usage: "[--top N] [--json] [--fail-on warn|error] [--path DIR]", summary: "Rank top code-quality offenders" },
       "commands"         => { handler: :cmd_commands,         usage: "[--json]",                           summary: "List available commands (add --json for machine form)" },
       "help"             => { handler: :cmd_help,                                                          summary: "Show this help message" },
     }.freeze
@@ -1060,104 +1059,6 @@ 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
-
-      # ONE engine run. Ask for every offender and slice for display: the gate
-      # must read the FULL set, not the printed top-N, and the old second call
-      # re-ran the whole analysis (its "full_analysis is cached" comment stopped
-      # being true when the in-process analyzer and its cache were deleted).
-      # An Integer, not Float::INFINITY -- Array#first demands an Integer.
-      every_offender = 2**31
-      begin
-        result = Tina4::Metrics.offenders(path, every_offender)
-      rescue Tina4::MetricsEngineError => e
-        warn "  metrics error: #{e.message}"
-        exit 2
-      end
-      summary = result["summary"]
-      all_offenders = result["offenders"]
-      found = all_offenders.first(top)
-
-      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)
@@ -2939,13 +2840,6 @@ module Tina4
         "shaped ones emit working code. Writes are secure by default; use --public",
         "to open them.",
         "",
-        "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)",
         "",

data/lib/tina4/dev_admin.rb

@@ -632,8 +632,6 @@ module Tina4
           json_response(gallery_deploy(name))
         when ["GET", "/__dev/api/version-check"]
           json_response(version_check_payload)
-        when ["GET", "/__dev/api/metrics"]
-          json_response(Tina4::Metrics.quick_metrics)
         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.