tina4ruby 3.13.100 → 3.13.101

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 850c8661fec2f0bb0ffeaf0c5d7644a6625b59878f5b053aeba49a4fa48cbde7
-  data.tar.gz: df0cbd73ccc67d39ac6f2900d8d2e6a9875925fbf85dfd092bdf1579e4748f38
+  metadata.gz: 9102cf347865953d60e7d47b1ead3b87e25f139f1439a19e5f230ec31594c32a
+  data.tar.gz: 7a5323f6a9d26e41852269c63d76fac619a59b549e634aad6a56bdc887dcb780
 SHA512:
-  metadata.gz: 39994977bdc2437b6abbfdeb88b0f3727e43cb46a4c189aae216e37202bdcd2e34505e396c60b083df3712c9bab1ac160f8f410b629e00a686dd9e9b48a4589b
-  data.tar.gz: b4948b71e5ecad37aa7923bc96091d88e243d0f3599e4a3440e94cc38a8452be2d8bb993459487590ef905752424b441376d78983597b94f4ac7059426780eae
+  metadata.gz: b0d72050d8db6db2ca5a1c621c6212848ef094ab84a3718b32aa06d53912c74c0324973374b1dafc6dd43d64b52dd34cb574a806fe79f034ac8757c0400db1cb
+  data.tar.gz: b13a9d5139f751391a684e28858bc894268fbb511ca192615eb48181dda59784faddcebcbdf6ae74aefb08736a53e9e356d432bc0ec4f6b69b50132c75a6e3f3

data/CHANGELOG.md

@@ -6,6 +6,22 @@ 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

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.

data/lib/tina4/metrics.rb

@@ -1,426 +1,117 @@
 # frozen_string_literal: true
 
-# Tina4 Code Metrics — the native engine (ADR-0002) plus an instant file census.
-#
-# Two-tier analysis:
-#   1. Quick metrics (instant): LOC, file counts, class/function counts
-#   2. Full analysis (on-demand, cached): cyclomatic complexity, maintainability
-#      index, coupling, Halstead metrics, offenders
-#
-# Zero dependencies. The census is pure Ruby; the analysis is `tina4 metrics --json`.
-
 require 'json'
-require 'digest'
+require 'open3'
 require 'pathname'
 
 module Tina4
-  # The native metrics engine could not produce a payload.
-  #
-  # Raised instead of falling back to a second implementation: two engines is
-  # exactly the condition that made the four frameworks' numbers incomparable.
   class MetricsEngineError < StandardError; end
 
+  # Thin dev-admin adapter for the native `tina4 metrics` engine (ADR-0054).
   module Metrics
-    # ── Cache ───────────────────────────────────────────────────
-    @full_cache_hash = ""
-    @full_cache_data = nil
-    @full_cache_time = 0
-    CACHE_TTL = 60
-
-    # Stores the resolved scan root so file_detail can locate framework files.
-    @last_scan_root = ""
-
-    # ── Root Resolution ──────────────────────────────────────────
-
-    # Pick the right directory to scan.
-    #
-    # If the root dir has Ruby files, scan the user's project code.
-    # Otherwise, scan the framework itself — so the bubble chart is never empty.
-    def self._resolve_root(root = 'src')
-      root_path = Pathname.new(root)
-      if root_path.directory? && !Dir.glob(root_path.join('**', '*.rb')).empty?
-        @last_scan_root = File.expand_path(root)
-        return root
-      end
-      # Fallback: scan the framework package itself
-      fw_dir = File.dirname(__FILE__)
-      @last_scan_root = fw_dir
-      fw_dir
-    end
-
-    def self.last_scan_root
-      @last_scan_root
-    end
-
-    # Return [directory to scan, scan_mode] for any metrics producer.
-    #
-    # The CLI engine is language-agnostic and cannot know which directory holds a
-    # framework package, so root resolution and the "framework" label stay here,
-    # shared by the census and the engine adapter so the two never disagree about
-    # what was measured.
-    def self.resolve_scan_target(root = 'src')
-      resolved = _resolve_root(root)
-      framework_dir = File.dirname(__FILE__)
-      resolved_real = File.expand_path(resolved)
-      scanning_framework = resolved_real == framework_dir || resolved_real.start_with?(framework_dir)
-      [resolved, scanning_framework ? 'framework' : 'project']
-    end
-
-    # ── Quick Metrics ───────────────────────────────────────────
-
-    def self.quick_metrics(root = 'src')
-      # Check if the requested directory exists before falling back
-      root_path = Pathname.new(root)
-      return { "error" => "Directory not found: #{root}" } unless root_path.directory?
-
-      root = _resolve_root(root)
-      root_path = Pathname.new(root)
-
-      rb_files = Dir.glob(root_path.join('**', '*.rb'))
-      twig_files = Dir.glob(root_path.join('**', '*.twig')) + Dir.glob(root_path.join('**', '*.erb'))
-
-      migrations_path = Pathname.new('migrations')
-      sql_files = if migrations_path.directory?
-                    Dir.glob(migrations_path.join('**', '*.sql')) + Dir.glob(migrations_path.join('**', '*.rb'))
-                  else
-                    []
-                  end
-
-      scss_files = Dir.glob(root_path.join('**', '*.scss')) + Dir.glob(root_path.join('**', '*.css'))
-
-      total_loc = 0
-      total_blank = 0
-      total_comment = 0
-      total_classes = 0
-      total_functions = 0
-      file_details = []
-
-      rb_files.each do |f|
-        source = begin
-          File.read(f, encoding: 'utf-8')
-        rescue StandardError
-          next
-        end
-
-        lines = source.lines.map(&:chomp)
-        loc = 0
-        blank = 0
-        comment = 0
-        in_heredoc = false
-        heredoc_id = nil
-        in_block_comment = false
-
-        lines.each do |line|
-          stripped = line.strip
-
-          if stripped.empty?
-            blank += 1
-            next
-          end
-
-          # =begin/=end block comments
-          if in_block_comment
-            comment += 1
-            in_block_comment = false if stripped.start_with?('=end')
-            next
-          end
-
-          if stripped.start_with?('=begin')
-            comment += 1
-            in_block_comment = true
-            next
-          end
-
-          # Heredoc tracking (simplified)
-          if in_heredoc
-            if stripped == heredoc_id
-              in_heredoc = false
-            end
-            loc += 1
-            next
-          end
-
-          if stripped.match?(/<<[~-]?['"]?(\w+)['"]?/)
-            m = stripped.match(/<<[~-]?['"]?(\w+)['"]?/)
-            heredoc_id = m[1]
-            in_heredoc = true unless stripped.include?(heredoc_id + stripped[-1].to_s)
-            loc += 1
-            next
-          end
-
-          if stripped.start_with?('#')
-            comment += 1
-            next
-          end
-
-          loc += 1
-        end
-
-        # Count classes and methods via simple pattern matching
-        classes = lines.count { |l| l.strip.match?(/\A(class|module)\s+/) }
-        functions = lines.count { |l| l.strip.match?(/\Adef\s+/) }
-
-        total_loc += loc
-        total_blank += blank
-        total_comment += comment
-        total_classes += classes
-        total_functions += functions
-
-        rel_path = begin
-          Pathname.new(f).relative_path_from(root_path).to_s
-        rescue ArgumentError
-          f
-        end
-
-        file_details << {
-          "path" => rel_path,
-          "loc" => loc,
-          "blank" => blank,
-          "comment" => comment,
-          "classes" => classes,
-          "functions" => functions
-        }
-      end
-
-      file_details.sort_by! { |d| -d["loc"] }
-
-      # Route and ORM counts
-      route_count = 0
-      orm_count = 0
-      begin
-        if defined?(Tina4::Router) && Tina4::Router.respond_to?(:routes)
-          route_count = Tina4::Router.routes.length
-        elsif defined?(Tina4::Router) && Tina4::Router.instance_variable_defined?(:@routes)
-          route_count = Tina4::Router.instance_variable_get(:@routes).length
-        end
-      rescue StandardError
-        # ignore
-      end
-
-      begin
-        if defined?(Tina4::ORM)
-          orm_count = ObjectSpace.each_object(Class).count { |c| c < Tina4::ORM }
-        end
-      rescue StandardError
-        # ignore
-      end
-
-      breakdown = {
-        "ruby" => rb_files.length,
-        "templates" => twig_files.length,
-        "migrations" => sql_files.length,
-        "stylesheets" => scss_files.length
-      }
-
-      {
-        "file_count" => rb_files.length,
-        "total_loc" => total_loc,
-        "total_blank" => total_blank,
-        "total_comment" => total_comment,
-        "lloc" => total_loc,
-        "classes" => total_classes,
-        "functions" => total_functions,
-        "route_count" => route_count,
-        "orm_count" => orm_count,
-        "template_count" => twig_files.length,
-        "migration_count" => sql_files.length,
-        "avg_file_size" => rb_files.empty? ? 0 : (total_loc.to_f / rb_files.length).round(1),
-        "largest_files" => file_details.first(10),
-        "breakdown" => breakdown
-      }
-    end
-
-    # ── Full Analysis (Ripper-based) ────────────────────────────
-    # ── The native engine (ADR-0002) ─────────────────────────────
-    #
-    # The Ripper-based analyzer that used to live below here is gone. Everything
-    # except the instant file census now comes from `tina4 metrics --json`, so a
-    # number measured in Ruby is comparable with the same number measured in
-    # Python, PHP or Node. There is deliberately NO fallback: a second engine is
-    # exactly the condition that made the four frameworks' numbers incomparable.
-
-    TIMEOUT_SECONDS = 60
-
-    INSTALL_HINT = <<~HINT.strip
-      the tina4 CLI provides the metrics engine (ADR-0002). Install it with
-        curl -fsSL https://tina4.com/install.sh | sh
-      or see https://tina4.com/cli
-    HINT
-
-    # Fields the dashboard renders. Checking for the DATA is honest where checking
-    # a version string is not: a user may run any CLI build, and the payload is
-    # what tells us what that build can actually do.
+    INSTALL_HINT = 'update the native tina4 CLI: https://tina4.com/cli'
     SUMMARY_KEYS = %w[files_analyzed total_functions avg_complexity avg_maintainability].freeze
     FILE_KEYS = %w[path loc avg_complexity maintainability has_tests].freeze
     FUNCTION_KEYS = %w[name file line complexity loc].freeze
 
-    # Absolute path to the tina4 CLI binary, or nil when it is not installed.
-    #
-    # Skips shebang scripts. The engine is a COMPILED Rust binary, but `bundle
-    # exec` prepends RubyGems' bin directory to PATH, and a gem executable named
-    # `tina4` sits there as a Ruby shim. Taking the first PATH hit found that
-    # shim and running it died with "can't find executable tina4 for gem" -- so
-    # every metrics call failed under the ordinary `bundle exec` workflow. The
-    # same guard also steps over rbenv/asdf shims and any gem squatting the name.
-    def self.engine_path
-      ENV['PATH'].to_s.split(File::PATH_SEPARATOR).each do |dir|
-        next if dir.empty?
+    def self.resolve_target(root = 'src')
+      source = Pathname.new(root)
+      resolved, mode = if source.directory? && !Dir.glob(source.join('**/*.rb').to_s).empty?
+                         [source.expand_path, 'project']
+                       else
+                         [Pathname.new(__dir__).expand_path, 'framework']
+                       end
+      @last_scan_root = resolved.to_s
+      [resolved.to_s, mode]
+    end
 
+    def self.engine_path
+      ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |directory|
         %w[tina4 tina4.exe].each do |name|
-          candidate = File.join(dir, name)
+          candidate = File.join(directory, name)
           next unless File.file?(candidate) && File.executable?(candidate)
-          next if _shebang_script?(candidate)
+          next if File.binread(candidate, 2) == '#!'
 
           return candidate
+        rescue StandardError
+          next
         end
       end
       nil
     end
 
-    # True when the file begins with `#!` -- a script, never the native engine.
-    def self._shebang_script?(path)
-      File.binread(path, 2) == '#!'
-    rescue StandardError
-      false
-    end
-
-    # Run `tina4 metrics --json` over path and return the raw payload.
-    #
-    # Raises MetricsEngineError naming the actual cause: a caller that cannot get
-    # metrics needs to know whether the binary is missing, the run failed, or the
-    # output was unreadable.
-    def self._run_engine(path)
+    def self.run_engine(path)
       binary = engine_path
-      raise MetricsEngineError, "tina4 not found on PATH - #{INSTALL_HINT}" if binary.nil?
-
-      stdout = nil
-      status = nil
-      stderr = nil
-      begin
-        require 'open3'
-        stdout, stderr, status = Open3.capture3(
-          binary, 'metrics', '--path', path.to_s, '--json'
-        )
-        # capture3 tags the output with the LOCALE's encoding, so under a
-        # minimal locale (LANG=C / LANG unset, common on CI runners and in slim
-        # containers) the engine's UTF-8 JSON arrives labelled US-ASCII and the
-        # first String#strip raises Encoding::CompatibilityError. The bytes were
-        # always UTF-8; only the label was wrong.
-        stdout = stdout.to_s.dup.force_encoding(Encoding::UTF_8)
-        stderr = stderr.to_s.dup.force_encoding(Encoding::UTF_8)
-      rescue StandardError => e
-        raise MetricsEngineError, "could not run #{binary}: #{e.message}"
-      end
+      raise MetricsEngineError, "tina4 not found on PATH - #{INSTALL_HINT}" unless binary
 
+      stdout, stderr, status = Open3.capture3(binary, 'metrics', '--path', path.to_s, '--json')
       unless status.success?
-        detail = (stderr.to_s.strip.empty? ? stdout.to_s : stderr.to_s).strip.lines.first
-        first = detail ? detail.strip : "exit code #{status.exitstatus}"
-        raise MetricsEngineError, "tina4 metrics failed on #{path}: #{first}"
+        detail = (stderr.empty? ? stdout : stderr).strip.lines.first || "exit code #{status.exitstatus}"
+        raise MetricsEngineError, "tina4 metrics failed on #{path}: #{detail.strip}"
       end
-
-      raise MetricsEngineError, "tina4 metrics produced no output for #{path}" if stdout.to_s.strip.empty?
-
-      begin
-        payload = JSON.parse(stdout)
-      rescue JSON::ParserError => e
-        raise MetricsEngineError, "tina4 metrics returned unreadable JSON: #{e.message}"
-      end
-
+      payload = JSON.parse(stdout)
       raise MetricsEngineError, 'tina4 metrics returned a non-object payload' unless payload.is_a?(Hash)
 
       payload
+    rescue JSON::ParserError => error
+      raise MetricsEngineError, "tina4 metrics returned unreadable JSON: #{error.message}"
+    rescue SystemCallError => error
+      raise MetricsEngineError, "could not run #{binary}: #{error.message}"
     end
 
-    # Pull a key out of the payload or raise naming what the engine is missing.
-    def self._require(payload, key, kind)
+    def self.require_array(payload, key)
       value = payload[key]
-      unless value.is_a?(kind)
-        raise MetricsEngineError,
-              "engine payload has no usable '#{key}' - the installed tina4 CLI predates " \
-              "a field the dashboard renders. Update it: #{INSTALL_HINT}"
-      end
-      value
+      return value if value.is_a?(Array)
+
+      raise MetricsEngineError, "engine payload has no usable '#{key}' - #{INSTALL_HINT}"
     end
 
-    # Full code analysis from the native engine, shaped for the dashboard.
     def self.full_analysis(root = 'src')
-      resolved, scan_mode = resolve_scan_target(root)
-      payload = _run_engine(resolved)
-
-      summary = _require(payload, 'summary', Hash)
-      file_metrics = _require(payload, 'file_metrics', Array)
-      functions = _require(payload, 'most_complex_functions', Array)
-
-      missing = SUMMARY_KEYS.reject { |k| summary.key?(k) }
-      unless missing.empty?
-        raise MetricsEngineError,
-              "engine summary is missing #{missing.join(', ')} - update the CLI: #{INSTALL_HINT}"
-      end
-      unless file_metrics.empty?
-        absent = FILE_KEYS.reject { |k| file_metrics.first.key?(k) }
-        raise MetricsEngineError, "engine file_metrics is missing #{absent.join(', ')}" unless absent.empty?
+      resolved, scan_mode = resolve_target(root)
+      payload = run_engine(resolved)
+      summary = payload['summary']
+      raise MetricsEngineError, "engine payload has no usable 'summary' - #{INSTALL_HINT}" unless summary.is_a?(Hash)
+
+      files = require_array(payload, 'file_metrics')
+      functions = require_array(payload, 'most_complex_functions')
+      missing = SUMMARY_KEYS.reject { |key| summary.key?(key) }
+      raise MetricsEngineError, "engine summary is missing #{missing.join(', ')}" unless missing.empty?
+      unless files.empty?
+        missing = FILE_KEYS.reject { |key| files.first.key?(key) }
+        raise MetricsEngineError, "engine file_metrics is missing #{missing.join(', ')}" unless missing.empty?
       end
       unless functions.empty?
-        absent = FUNCTION_KEYS.reject { |k| functions.first.key?(k) }
-        raise MetricsEngineError, "engine function metrics are missing #{absent.join(', ')}" unless absent.empty?
+        missing = FUNCTION_KEYS.reject { |key| functions.first.key?(key) }
+        raise MetricsEngineError, "engine function metrics are missing #{missing.join(', ')}" unless missing.empty?
       end
 
-      result = SUMMARY_KEYS.each_with_object({}) { |k, h| h[k] = summary[k] }
-      result['file_metrics'] = file_metrics
-      # Display cap only. offenders reads the engine's own uncapped list, so a
-      # 16th over-threshold function is never hidden from the gate.
-      result['most_complex_functions'] = functions.first(15)
-      result['dependency_graph'] = payload['dependency_graph'] || {}
-      # The framework owns these two: the engine always reports "project" because
-      # it cannot know which directory is a framework package.
-      result['scan_mode'] = scan_mode
-      result['scan_root'] = File.expand_path(resolved)
-      result['engine'] = 'tina4-cli'
-      result
+      SUMMARY_KEYS.to_h { |key| [key, summary[key]] }.merge(
+        'file_metrics' => files,
+        'most_complex_functions' => functions.first(15),
+        'dependency_graph' => payload['dependency_graph'] || {},
+        'scan_mode' => scan_mode,
+        'scan_root' => resolved,
+        'engine' => 'tina4-cli'
+      )
     end
 
-    # Top code-health offenders from the native engine.
-    #
-    # The engine ranks and severity-tags them, and its own --fail-on gate reads
-    # the same list, so the CLI and the dashboard can never disagree about what
-    # counts as an offender.
-    def self.offenders(root = 'src', top = 20)
-      resolved, scan_mode = resolve_scan_target(root)
-      payload = _run_engine(resolved)
-
-      found = _require(payload, 'offenders', Array)
-      summary = _require(payload, 'summary', Hash).dup
-      summary['scan_mode'] = scan_mode
-      summary['scan_root'] = File.expand_path(resolved)
-      summary['engine'] = 'tina4-cli'
-      summary['total_offenders'] ||= found.length
-      { 'offenders' => found.first(top), 'summary' => summary }
-    end
-
-    # Per-file metrics from the native engine.
-    #
-    # The engine accepts a single file for --path, so one code path serves both
-    # the whole-tree scan and one file.
     def self.file_detail(file_path)
-      raise MetricsEngineError, 'file_detail needs a path' if file_path.nil? || file_path.to_s.empty?
+      raise MetricsEngineError, 'file_detail needs a path' if file_path.to_s.empty?
 
       target = Pathname.new(file_path.to_s)
-      unless target.exist?
-        # Try it relative to whatever the census last resolved, so the dashboard
-        # can pass a path taken straight out of file_metrics.
-        unless @last_scan_root.to_s.empty?
-          candidate = Pathname.new(@last_scan_root).join(file_path.to_s)
-          target = candidate if candidate.exist?
-        end
-      end
+      target = Pathname.new(@last_scan_root).join(file_path.to_s) if !target.exist? && @last_scan_root
       raise MetricsEngineError, "no such file: #{file_path}" unless target.exist?
       raise MetricsEngineError, "not a file: #{file_path}" if target.directory?
 
-      payload = _run_engine(target.to_s)
-      file_metrics = _require(payload, 'file_metrics', Array)
-      raise MetricsEngineError, "engine reported no metrics for #{file_path}" if file_metrics.empty?
+      payload = run_engine(target.to_s)
+      files = require_array(payload, 'file_metrics')
+      raise MetricsEngineError, "engine reported no metrics for #{file_path}" if files.empty?
 
-      file_metrics.first.dup.merge('engine' => 'tina4-cli')
+      files.first.merge(
+        'function_count' => files.first.fetch('functions', 0),
+        'functions' => require_array(payload, 'most_complex_functions'),
+        'engine' => 'tina4-cli'
+      )
     end
   end
 end

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -42,6 +42,7 @@ require_relative "tina4/dev_admin"
 require_relative "tina4/feedback"
 require_relative "tina4/dev_mailbox"
 require_relative "tina4/ai"
+require_relative "tina4/ai_client"
 require_relative "tina4/cache"
 require_relative "tina4/sql_translator"
 require_relative "tina4/cache_backends"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.100
+  version: 3.13.101
 platform: ruby
 authors:
 - Tina4 Team
@@ -321,6 +321,7 @@ files:
 - exe/tina4ruby
 - lib/tina4.rb
 - lib/tina4/ai.rb
+- lib/tina4/ai_client.rb
 - lib/tina4/api.rb
 - lib/tina4/auth.rb
 - lib/tina4/auto_crud.rb