tina4ruby 3.11.17 → 3.11.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5bc93541bae10ff3eeaf0ab13618b899d3ea3ace7ae346c7e6c0fc77bf54cfb
-  data.tar.gz: 71bbbf40e7411a7955d675f3a479dddea6f93c17b7b8cc4b91459d738cefc70d
+  metadata.gz: 913dfbf6820b99da3ff8f0b5a845fb23239736ccc1db30eb958d664fba6abe9f
+  data.tar.gz: c7c39ce01253b8dc60edc30550b004914ac9c4742ee2efabfdedab44dfe984f7
 SHA512:
-  metadata.gz: 3b67f60cfd3f12f05d711151892963c935c5297dfd7533649e216cbff8ae1c9a1b383172191524594db2a1ef8a3bd529d58a3913fda910162d42b9e925aaf52a
-  data.tar.gz: d32f9309802ab0a5051eb330e39df3e43ec7612eb0b03715390871ee1c6413858c5e0a065dd486b1450578e5b3f93fd0a78e97feb6ff1d3e20b9591d587a0cb9
+  metadata.gz: c926a2b39b248a45112e3f323174049ccdb0955c07ce3491a9346c837776cca37707ce54ecca21320ad71599b8d537a78eedadf4e675cd8c2b71dcfa6415ca39
+  data.tar.gz: caf6b606d28154e7ed8ded6e2519cc4a45f10a9034644f15f82625eace4e2747dbc27d845dadf0f0881a1c180c38a465428976a7be6d7b1c52b4239f637fd793

data/lib/tina4/background.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Tina4
+  # Periodic background task registry.
+  #
+  # Matches Python's `tina4_python.core.server.background(fn, interval)` and
+  # PHP's `$app->background($callback, $interval)` — a callback that runs
+  # periodically alongside the server lifecycle.
+  #
+  # Ruby has no asyncio event loop, so each task runs in its own thread.
+  # The GIL keeps it cooperative-enough for the periodic work this is meant
+  # for (queue draining, health checks, simulators). Errors in the callback
+  # are caught and logged so they don't kill the thread.
+  module Background
+    class << self
+      # Register a periodic callback.
+      #
+      # @param callback [#call, nil] Object responding to `call` with no args.
+      # @param interval [Float] Seconds between invocations (default 1.0).
+      # @param block    [Proc]   Optional block (used if callback is nil).
+      # @return [Hash] The registered task descriptor.
+      def register(callback = nil, interval: 1.0, &block)
+        cb = callback || block
+        raise ArgumentError, "background requires a callback or block" if cb.nil?
+        raise ArgumentError, "callback must respond to :call" unless cb.respond_to?(:call)
+
+        task = { callback: cb, interval: interval.to_f, thread: nil, running: false }
+        mutex.synchronize { tasks << task }
+        start_task(task)
+        task
+      end
+
+      # All registered task descriptors. Tests use this for introspection.
+      def tasks
+        @tasks ||= []
+      end
+
+      # Stop and join every running task. Called on graceful shutdown.
+      def stop_all(timeout: 2.0)
+        snapshot = mutex.synchronize { tasks.dup }
+        snapshot.each { |task| stop_task(task, timeout: timeout) }
+        mutex.synchronize { tasks.clear }
+      end
+
+      # Stop a single task. Used by tests that register, fire, then stop.
+      def stop_task(task, timeout: 2.0)
+        task[:running] = false
+        thread = task[:thread]
+        return unless thread
+
+        thread.join(timeout) || thread.kill
+        task[:thread] = nil
+      end
+
+      private
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def start_task(task)
+        task[:running] = true
+        task[:thread] = Thread.new do
+          while task[:running]
+            sleep task[:interval]
+            break unless task[:running]
+
+            begin
+              task[:callback].call
+            rescue => e
+              # Never let a callback error kill the thread — next interval still fires.
+              if defined?(Tina4::Log) && Tina4::Log.respond_to?(:error)
+                Tina4::Log.error("background task error: #{e.class}: #{e.message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tina4/dev_admin.rb

@@ -316,9 +316,55 @@ module Tina4
         Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
       end
 
+      # Write `.tina4/mcp.json` so MCP-aware tools (Claude Code, Cursor) can
+      # auto-discover this project's live docs server. Idempotent — no-op if
+      # the file already matches the desired contents. Also appends `.tina4/`
+      # to the project's `.gitignore` if a git repo is present.
+      def auto_discover_mcp!(project_root: Dir.pwd)
+        return if @_mcp_auto_discovered
+        @_mcp_auto_discovered = true
+        return unless enabled?
+
+        port = ENV["TINA4_PORT"] || ENV["PORT"] || "7147"
+        url  = "http://localhost:#{port}/__dev/api/mcp"
+        target_dir = File.join(project_root, ".tina4")
+        target = File.join(target_dir, "mcp.json")
+        payload = {
+          "mcpServers" => {
+            "tina4-live-docs" => {
+              "url" => url,
+              "description" => "Live API docs for this Tina4 project (framework + user code)",
+            },
+          },
+        }
+        begin
+          FileUtils.mkdir_p(target_dir)
+          existing = if File.file?(target)
+                       (JSON.parse(File.read(target)) rescue {})
+                     else
+                       {}
+                     end
+          if existing != payload
+            File.write(target, JSON.pretty_generate(payload))
+          end
+
+          gitignore = File.join(project_root, ".gitignore")
+          if File.directory?(File.join(project_root, ".git"))
+            current = File.file?(gitignore) ? File.read(gitignore) : ""
+            unless current.lines.map(&:strip).include?(".tina4/") || current.lines.map(&:strip).include?(".tina4")
+              prefix = (!current.empty? && !current.end_with?("\n")) ? "\n" : ""
+              File.write(gitignore, "#{current}#{prefix}.tina4/\n")
+            end
+          end
+        rescue StandardError => e
+          Tina4::Log.warning("auto_discover_mcp! failed: #{e.message}") if defined?(Tina4::Log)
+        end
+      end
+
       # Handle a /__dev request; returns [status, headers, body] or nil if not a dev path
       def handle_request(env)
         return nil unless enabled?
+        auto_discover_mcp!
 
         path = env["PATH_INFO"] || "/"
         method = env["REQUEST_METHOD"]
@@ -548,6 +594,16 @@ module Tina4
         when ["POST", "/__dev/api/scaffold/run"]
           body = read_json_body(env) || {}
           json_response(scaffold_run(body))
+        when ["GET", "/__dev/api/docs/search"]
+          json_response(docs_search_payload(env))
+        when ["GET", "/__dev/api/docs/class"]
+          json_response(docs_class_payload(query_param(env, "name")))
+        when ["GET", "/__dev/api/docs/method"]
+          json_response(docs_method_payload(query_param(env, "class"), query_param(env, "name")))
+        when ["GET", "/__dev/api/docs/index"]
+          json_response(docs_index_payload(query_param(env, "source")))
+        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
@@ -1286,6 +1342,56 @@ module Tina4
           { ok: false, error: "unknown kind: #{kind}" }
         end
       end
+
+      # ── Live Docs (Live API RAG) ─────────────────────────────────
+
+      def docs_search_payload(env)
+        q = (query_param(env, "q") || "").to_s
+        k = (query_param(env, "k") || "5").to_i
+        source = (query_param(env, "source") || "all").to_s
+        include_private = %w[1 true yes].include?((query_param(env, "include_private") || "").to_s.downcase)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        results = Tina4::Docs.cached(Dir.pwd).search(
+          q, k: k, source: source, include_private: include_private
+        )
+        took_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000.0).round(2)
+        { ok: true, query: q, results: results, took_ms: took_ms }
+      end
+
+      def docs_class_payload(name)
+        spec = Tina4::Docs.cached(Dir.pwd).class_spec(name.to_s)
+        return { ok: false, error: "class not found: #{name}" } if spec.nil?
+        { ok: true, class: spec }
+      end
+
+      def docs_method_payload(class_fqn, name)
+        spec = Tina4::Docs.cached(Dir.pwd).method_spec(class_fqn.to_s, name.to_s)
+        return { ok: false, error: "method not found: #{class_fqn}##{name}" } if spec.nil?
+        { ok: true, method: spec }
+      end
+
+      def docs_index_payload(source)
+        idx = Tina4::Docs.cached(Dir.pwd).index
+        idx = idx.select { |e| e[:source] == source } if source && %w[framework user vendor].include?(source.to_s)
+        { ok: true, count: idx.size, entries: idx }
+      end
+
+      def docs_well_known_payload
+        {
+          ok: true,
+          service: "tina4-live-docs",
+          version: Tina4::VERSION,
+          framework: "tina4-ruby",
+          endpoints: {
+            search: "/__dev/api/docs/search?q=<query>&k=<int>&source=<framework|user|all>&include_private=<bool>",
+            class:  "/__dev/api/docs/class?name=<fqn>",
+            method: "/__dev/api/docs/method?class=<fqn>&name=<method>",
+            index:  "/__dev/api/docs/index?source=<framework|user|all>",
+          },
+          mcp: { url: "/__dev/api/mcp", tools: %w[api_search api_class api_method] },
+          spec: "https://tina4.com — Live API RAG plan/v3/22-LIVE-API-RAG.md",
+        }
+      end
     end
   end
 end