tina4ruby 3.11.35 → 3.11.36

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dfb1cf2a3f34468c680f80f120b935a59348b7bab428fa5ba8c738a2a9ddf85
-  data.tar.gz: 7ceb6e23bc01350d5de21c77fd4d7902a2a314933a5290a6db3dac272060865a
+  metadata.gz: 9615f251d5bed0d97024c8e061bdf34d26afb2677e5c6ec989005d45d3edc6c9
+  data.tar.gz: 7ef7b684a87906e932f3c929cfe57596f67bf81bf63cf35e79b8d343f2ab297a
 SHA512:
-  metadata.gz: f27c8ed10bc2c080ed765060989dafdc1c05c04bb255ac7a093cda62b692965e940b81d46f9b8f170ef0e3afd9cee44ee63d82eadc09410c34ef29338f1192ec
-  data.tar.gz: 694ef83820ce2021da6ae51013259590fd70374ac2170831d039af3cb9dfa3a30ab1bf7ff691c4c8bcdaadefdf7e5ca9901c30a8a537b69ade99c8aaa8cb1c12
+  metadata.gz: ecf726e25d06e8ecbed12874fa4f36edf20286ea10c2c9b6c973a2d9d430dd38933a95240b8d50dd4237b82e076b634527e0c28016aa6e94f6f71a7747d126f8
+  data.tar.gz: bc0603a6370d2dc27f26ad5cee86c00f233213d57dc904075f70c5befdf28ff81b78d0c25ffa25a42f34ae9cf48d0a33a322e1147d12bc05db1f125db245538f

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/database.rb

@@ -109,6 +109,15 @@ module Tina4
       @pool_size = pool  # 0 = single connection, N>0 = N pooled connections
       @connected = false
 
+      # Per-instance thread-local key for the transaction adapter pin.
+      # Without this pin, every Database method call rotates to a different
+      # pooled connection. Inside a transaction this silently breaks atomicity:
+      # start_transaction begins on adapter A, executes autocommit on B/C, and
+      # commit/rollback land on D — a no-op. start_transaction sets the pin,
+      # commit/rollback clear it. While pinned, current_driver returns the same
+      # driver for every call so the whole transaction runs on one connection.
+      @tx_pin_key = :"tina4_pinned_adapter_#{object_id}"
+
       # Query cache — off by default, opt-in via TINA4_DB_CACHE=true
       @cache_enabled = truthy?(ENV["TINA4_DB_CACHE"])
       @cache_ttl = (ENV["TINA4_DB_CACHE_TTL"] || "30").to_i
@@ -161,7 +170,14 @@ module Tina4
     end
 
     # Get the current driver — from pool (round-robin) or single connection.
+    #
+    # Inside a transaction, all calls must land on the SAME driver — otherwise
+    # start_transaction, execute, and commit each rotate to a different pooled
+    # connection and the transaction is meaningless. start_transaction pins
+    # the driver to the calling thread; commit/rollback release it.
     def current_driver
+      pinned = Thread.current[@tx_pin_key]
+      return pinned if pinned
       if @pool
         @pool.checkout
       else
@@ -355,27 +371,38 @@ module Tina4
 
     def transaction
       drv = current_driver
+      Thread.current[@tx_pin_key] = drv
       drv.begin_transaction
       yield self
       drv.commit
     rescue => e
-      drv.rollback
+      drv.rollback if drv
       raise e
+    ensure
+      Thread.current[@tx_pin_key] = nil
     end
 
     # Begin a transaction without a block — matches PHP/Python/Node API.
+    # Pins the driver to this thread for the whole transaction so executes
+    # and the final commit/rollback all run on the same connection.
     def start_transaction
-      current_driver.begin_transaction
+      drv = current_driver
+      Thread.current[@tx_pin_key] = drv
+      drv.begin_transaction
     end
 
-    # Commit the current transaction — matches PHP/Python/Node API.
+    # Commit the current transaction and release the driver pin.
     def commit
       current_driver.commit
+    ensure
+      Thread.current[@tx_pin_key] = nil
     end
 
-    # Roll back the current transaction — matches PHP/Python/Node API.
+    # Roll back the current transaction and release the driver pin.
     def rollback
       current_driver.rollback
+    ensure
+      Thread.current[@tx_pin_key] = nil
     end
 
     def tables

data/lib/tina4/dev_admin.rb

@@ -5,6 +5,8 @@ require "digest"
 require "tmpdir"
 require "net/http"
 require "uri"
+require "fileutils"
+require "shellwords"
 require_relative "metrics"
 
 module Tina4
@@ -314,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"]
@@ -405,7 +453,9 @@ module Tina4
           resolved = id ? error_tracker.resolve(id) : false
           json_response({ resolved: resolved, id: id })
         when ["POST", "/__dev/api/broken/clear"]
-          error_tracker.clear_resolved
+          # "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({ connections: [], count: 0 })
@@ -494,6 +544,66 @@ module Tina4
         when ["GET", "/__dev/api/metrics/file"]
           file_path = (query_param(env, "path") || "").to_s
           json_response(Tina4::Metrics.file_detail(file_path))
+        when ["GET", "/__dev/api/thoughts"]
+          json_response(thoughts_payload)
+        when ["POST", "/__dev/api/supervise/create"]
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor("/supervise/create", method: "POST", body: body))
+        when ["GET", "/__dev/api/supervise/sessions"]
+          json_response(proxy_supervisor("/supervise/sessions", method: "GET", query: env["QUERY_STRING"]))
+        when ["GET", "/__dev/api/supervise/diff"]
+          json_response(proxy_supervisor("/supervise/diff", method: "GET", query: env["QUERY_STRING"]))
+        when ["POST", "/__dev/api/supervise/commit"]
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor("/supervise/commit", method: "POST", body: body))
+        when ["POST", "/__dev/api/supervise/cancel"]
+          body = read_json_body(env) || {}
+          json_response(proxy_supervisor("/supervise/cancel", method: "POST", body: body))
+        when ["POST", "/__dev/api/execute"]
+          body = read_json_body(env) || {}
+          execute_proxy(body)
+        when ["GET", "/__dev/api/files"]
+          json_response(files_list(env))
+        when ["GET", "/__dev/api/file"]
+          json_response(file_read_payload(query_param(env, "path")))
+        when ["GET", "/__dev/api/file/raw"]
+          file_raw_response(query_param(env, "path"))
+        when ["POST", "/__dev/api/file/save"]
+          body = read_json_body(env) || {}
+          json_response(file_save(body))
+        when ["POST", "/__dev/api/file/rename"]
+          body = read_json_body(env) || {}
+          json_response(file_rename(body))
+        when ["POST", "/__dev/api/file/delete"]
+          body = read_json_body(env) || {}
+          json_response(file_delete(body))
+        when ["GET", "/__dev/api/deps/search"]
+          json_response(deps_search(query_param(env, "q") || query_param(env, "query") || ""))
+        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)
+        when ["GET", "/__dev/api/mcp/tools"]
+          json_response(mcp_tools_list)
+        when ["POST", "/__dev/api/mcp/call"]
+          body = read_json_body(env) || {}
+          json_response(mcp_tool_call(body))
+        when ["GET", "/__dev/api/scaffold"]
+          json_response(scaffold_templates)
+        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
@@ -930,6 +1040,358 @@ module Tina4
 
         { deployed: name, files: copied }
       end
+
+      # ── New dev-admin surface area (parity with Python/PHP) ────
+
+      def supervisor_base
+        base = ENV["TINA4_SUPERVISOR_URL"].to_s.strip
+        return base unless base.empty?
+        port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i + 2000
+        "http://127.0.0.1:#{port}"
+      end
+
+      def thoughts_payload
+        base = supervisor_base
+        begin
+          uri = URI.parse("#{base}/thoughts")
+          req = Net::HTTP::Get.new(uri)
+          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 5) { |h| h.request(req) }
+          return JSON.parse(resp.body) if resp.is_a?(Net::HTTPSuccess)
+          { thoughts: [], error: "Supervisor returned #{resp.code}" }
+        rescue StandardError => e
+          { thoughts: [], error: e.message }
+        end
+      end
+
+      def proxy_supervisor(path, method: "GET", body: nil, query: nil)
+        base = supervisor_base
+        url = "#{base}#{path}"
+        url += "?#{query}" if query && !query.empty?
+        begin
+          uri = URI.parse(url)
+          req = case method.upcase
+                when "POST"
+                  r = Net::HTTP::Post.new(uri)
+                  r["Content-Type"] = "application/json"
+                  r.body = JSON.generate(body || {})
+                  r
+                else
+                  Net::HTTP::Get.new(uri)
+                end
+          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 30) { |h| h.request(req) }
+          begin
+            JSON.parse(resp.body)
+          rescue JSON::ParserError
+            { body: resp.body, status: resp.code.to_i }
+          end
+        rescue StandardError => e
+          { error: e.message, supervisor: base }
+        end
+      end
+
+      def execute_proxy(body)
+        # Proxy POST /execute to the supervisor at framework_port + 2000.
+        # Pass through the response stream as-is (SSE or JSON).
+        base = supervisor_base
+        begin
+          uri = URI.parse("#{base}/execute")
+          req = Net::HTTP::Post.new(uri)
+          req["Content-Type"] = "application/json"
+          req["Accept"] = "text/event-stream"
+          req.body = JSON.generate(body || {})
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.open_timeout = 2
+          http.read_timeout = 300
+          resp = http.request(req)
+          ct = resp["content-type"] || "application/json; charset=utf-8"
+          [resp.code.to_i, { "content-type" => ct }, [resp.body.to_s]]
+        rescue StandardError => e
+          body_str = JSON.generate({ error: e.message, supervisor: base })
+          [502, { "content-type" => "application/json; charset=utf-8" }, [body_str]]
+        end
+      end
+
+      def safe_project_path(rel_path)
+        root = File.expand_path(Dir.pwd)
+        resolved = File.expand_path(rel_path.to_s, root)
+        raise ArgumentError, "path escapes project directory" unless resolved.start_with?(root)
+        resolved
+      end
+
+      def files_list(env)
+        rel = query_param(env, "path") || "."
+        begin
+          target = safe_project_path(rel)
+          return { error: "Not found" } unless File.exist?(target)
+          return { error: "Not a directory" } unless File.directory?(target)
+          entries = Dir.children(target).sort.map do |name|
+            full = File.join(target, name)
+            {
+              name: name,
+              type: File.directory?(full) ? "dir" : "file",
+              size: File.file?(full) ? File.size(full) : 0
+            }
+          end
+          { path: rel, entries: entries, count: entries.size }
+        rescue => e
+          { error: e.message }
+        end
+      end
+
+      def file_read_payload(rel)
+        return { error: "path required" } if rel.nil? || rel.empty?
+        begin
+          target = safe_project_path(rel)
+          return { error: "Not found" } unless File.exist?(target)
+          return { error: "Not a file" } unless File.file?(target)
+          content = File.read(target, encoding: "utf-8", invalid: :replace, undef: :replace)
+          { path: rel, content: content, bytes: File.size(target) }
+        rescue => e
+          { error: e.message }
+        end
+      end
+
+      def file_raw_response(rel)
+        return json_response({ error: "path required" }) if rel.nil? || rel.empty?
+        begin
+          target = safe_project_path(rel)
+          return json_response({ error: "Not found" }) unless File.file?(target)
+          content = File.binread(target)
+          ct = case File.extname(target).downcase
+               when ".css" then "text/css"
+               when ".js"  then "application/javascript"
+               when ".json" then "application/json"
+               when ".html", ".htm" then "text/html"
+               when ".png" then "image/png"
+               when ".jpg", ".jpeg" then "image/jpeg"
+               when ".gif" then "image/gif"
+               when ".svg" then "image/svg+xml"
+               else "text/plain; charset=utf-8"
+               end
+          [200, { "content-type" => ct }, [content]]
+        rescue => e
+          json_response({ error: e.message })
+        end
+      end
+
+      def file_save(body)
+        rel     = body["path"].to_s
+        content = body["content"].to_s
+        return { error: "path required" } if rel.empty?
+        begin
+          target = safe_project_path(rel)
+          existed = File.exist?(target)
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, content, encoding: "utf-8")
+          Tina4::Plan.record_action(existed ? "patched" : "created", rel) if defined?(Tina4::Plan)
+          { saved: rel, bytes: content.bytesize }
+        rescue => e
+          { error: e.message }
+        end
+      end
+
+      def file_rename(body)
+        from = body["from"].to_s
+        to   = body["to"].to_s
+        return { error: "from/to required" } if from.empty? || to.empty?
+        begin
+          src = safe_project_path(from)
+          dst = safe_project_path(to)
+          return { error: "Source not found" } unless File.exist?(src)
+          FileUtils.mkdir_p(File.dirname(dst))
+          File.rename(src, dst)
+          { renamed: { from: from, to: to } }
+        rescue => e
+          { error: e.message }
+        end
+      end
+
+      def file_delete(body)
+        rel = body["path"].to_s
+        return { error: "path required" } if rel.empty?
+        begin
+          target = safe_project_path(rel)
+          return { error: "Not found" } unless File.exist?(target)
+          if File.directory?(target)
+            FileUtils.rm_rf(target)
+          else
+            File.delete(target)
+          end
+          { deleted: rel }
+        rescue => e
+          { error: e.message }
+        end
+      end
+
+      def deps_search(query)
+        return { results: [], count: 0, error: "query required" } if query.to_s.strip.empty?
+        begin
+          uri = URI.parse("https://rubygems.org/api/v1/search.json?query=#{URI.encode_www_form_component(query)}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 5
+          http.read_timeout = 8
+          resp = http.request(Net::HTTP::Get.new(uri))
+          if resp.is_a?(Net::HTTPSuccess)
+            gems = JSON.parse(resp.body)
+            results = gems.first(20).map do |g|
+              { name: g["name"], version: g["version"], info: g["info"].to_s[0, 200] }
+            end
+            { results: results, count: results.size }
+          else
+            { results: [], count: 0, error: "rubygems returned #{resp.code}" }
+          end
+        rescue => e
+          { results: [], count: 0, error: e.message }
+        end
+      end
+
+      def deps_install(body)
+        name = body["name"].to_s.strip
+        return { ok: false, error: "name required" } if name.empty?
+        # Append to Gemfile if not present — do NOT actually bundle install.
+        gemfile = File.join(Dir.pwd, "Gemfile")
+        return { ok: false, error: "No Gemfile at project root" } unless File.exist?(gemfile)
+        content = File.read(gemfile)
+        if content.include?("gem \"#{name}\"") || content.include?("gem '#{name}'")
+          return { ok: true, gem: name, note: "already in Gemfile" }
+        end
+        File.open(gemfile, "a") { |f| f.write("\ngem \"#{name}\"\n") }
+        { ok: true, gem: name, note: "added to Gemfile; run `bundle install`" }
+      end
+
+      def git_status_payload
+        begin
+          inside = `cd #{Shellwords.escape(Dir.pwd)} && git rev-parse --is-inside-work-tree 2>/dev/null`.strip
+          return { error: "Not a git repository" } if inside != "true"
+          branch = `cd #{Shellwords.escape(Dir.pwd)} && git branch --show-current 2>/dev/null`.strip
+          status = `cd #{Shellwords.escape(Dir.pwd)} && git status --porcelain 2>/dev/null`.strip.split("\n").reject(&:empty?)
+          recent = `cd #{Shellwords.escape(Dir.pwd)} && git log --oneline -5 2>/dev/null`.strip.split("\n").reject(&:empty?)
+          { branch: branch, status: status, recent_commits: recent }
+        rescue => e
+          { error: "git unavailable: #{e.message}" }
+        end
+      end
+
+      def mcp_tools_list
+        return { tools: [], count: 0 } unless defined?(Tina4::McpServer)
+        server = Tina4._default_mcp_server
+        list = server.tools.values.map do |t|
+          { name: t["name"], description: t["description"], schema: t["inputSchema"] }
+        end
+        { tools: list, count: list.size }
+      end
+
+      def mcp_tool_call(body)
+        tool_name = body["name"].to_s
+        args      = body["arguments"] || {}
+        return { error: "tool name required" } if tool_name.empty?
+        return { error: "MCP not loaded" } unless defined?(Tina4::McpServer)
+        server = Tina4._default_mcp_server
+        payload = JSON.generate({
+          "jsonrpc" => "2.0",
+          "id"      => 1,
+          "method"  => "tools/call",
+          "params"  => { "name" => tool_name, "arguments" => args }
+        })
+        raw = server.handle_message(payload)
+        return {} if raw.nil? || raw.empty?
+        JSON.parse(raw)
+      end
+
+      def scaffold_templates
+        # Expose built-in scaffold targets for the dev-admin UI.
+        { templates: [
+          { id: "route",      label: "Route file",           target: "src/routes" },
+          { id: "model",      label: "ORM model",            target: "src/orm" },
+          { id: "migration",  label: "SQL migration",        target: "migrations" },
+          { id: "middleware", label: "Middleware class",     target: "src/app" }
+        ] }
+      end
+
+      def scaffold_run(body)
+        kind = body["kind"].to_s
+        name = body["name"].to_s.strip
+        return { ok: false, error: "kind + name required" } if kind.empty? || name.empty?
+        project = Dir.pwd
+        case kind
+        when "route"
+          target = File.join(project, "src", "routes", "#{name}.rb")
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, "# #{name} routes\nTina4::Router.get(\"/api/#{name}\") do |req, res|\n  res.call({ hello: \"#{name}\" })\nend\n") unless File.exist?(target)
+          { ok: true, created: target.sub("#{project}/", "") }
+        when "model"
+          target = File.join(project, "src", "orm", "#{name}.rb")
+          FileUtils.mkdir_p(File.dirname(target))
+          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
+          File.write(target, "class #{cls} < Tina4::ORM\n  integer_field :id, primary_key: true, auto_increment: true\n  string_field :name\nend\n") unless File.exist?(target)
+          { ok: true, created: target.sub("#{project}/", "") }
+        when "migration"
+          ts = Time.now.strftime("%Y%m%d%H%M%S")
+          target = File.join(project, "migrations", "#{ts}_#{name}.sql")
+          FileUtils.mkdir_p(File.dirname(target))
+          File.write(target, "-- migration: #{name}\n")
+          { ok: true, created: target.sub("#{project}/", "") }
+        when "middleware"
+          target = File.join(project, "src", "app", "#{name}.rb")
+          FileUtils.mkdir_p(File.dirname(target))
+          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
+          File.write(target, "class #{cls}\n  def self.before_check(req, res); [req, res]; end\nend\n") unless File.exist?(target)
+          { ok: true, created: target.sub("#{project}/", "") }
+        else
+          { 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