tina4ruby 3.11.18 → 3.11.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aa9ce02d7a7c924ae48d78b5ed1485261b85cde643ab13501040ea5bc7145da
-  data.tar.gz: f97407bec1e490e48714ae6d00ee78ad211b74e50ec0f94325d92f3dbf935e43
+  metadata.gz: 913dfbf6820b99da3ff8f0b5a845fb23239736ccc1db30eb958d664fba6abe9f
+  data.tar.gz: c7c39ce01253b8dc60edc30550b004914ac9c4742ee2efabfdedab44dfe984f7
 SHA512:
-  metadata.gz: c2bfb361e4de75738221dbdfb8f7a070cf224b71d02c389b0bc62171dd6566dea13d8fb0677f119ef331295d234fb1269d4a5a6573d026302d1c9d6c1b75a8e4
-  data.tar.gz: ac914458d86220ae3788f9a7da1a3cd427d4b0901139b53f57e007f93103bb5d82ded233b449dcebad4ae8145624ca971e9d056d36ae103f808b66c5a67689b3
+  metadata.gz: c926a2b39b248a45112e3f323174049ccdb0955c07ce3491a9346c837776cca37707ce54ecca21320ad71599b8d537a78eedadf4e675cd8c2b71dcfa6415ca39
+  data.tar.gz: caf6b606d28154e7ed8ded6e2519cc4a45f10a9034644f15f82625eace4e2747dbc27d845dadf0f0881a1c180c38a465428976a7be6d7b1c52b4239f637fd793

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