shared_tools 0.4.2 → 0.6.0

data/lib/shared_tools/tools/git_tool.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # A tool for interacting with a git repository: status, diff, log, show,
+    # blame, branch, grep, add, commit, and checkout. Mutating actions (add,
+    # commit, checkout) require user authorization (see SharedTools.execute?).
+    #
+    # @example
+    #   git = SharedTools::Tools::GitTool.new
+    #   git.execute(action: SharedTools::Tools::GitTool::Action::STATUS)
+    #   git.execute(action: SharedTools::Tools::GitTool::Action::LOG, count: 5)
+    #   git.execute(action: SharedTools::Tools::GitTool::Action::COMMIT, message: "Fix the thing")
+    class GitTool < ::RubyLLM::Tool
+      def self.name = 'git_tool'
+
+      description <<~TEXT
+        A tool for interacting with a git repository. Read-only actions (status, diff, log, show,
+        blame, branch, grep) require no authorization. Mutating actions (add, commit, checkout)
+        require user authorization.
+      TEXT
+
+      module Action
+        STATUS   = "status"
+        DIFF     = "diff"
+        LOG      = "log"
+        SHOW     = "show"
+        BLAME    = "blame"
+        BRANCH   = "branch"
+        GREP     = "grep"
+        ADD      = "add"
+        COMMIT   = "commit"
+        CHECKOUT = "checkout"
+      end
+
+      ACTIONS = [
+        Action::STATUS,
+        Action::DIFF,
+        Action::LOG,
+        Action::SHOW,
+        Action::BLAME,
+        Action::BRANCH,
+        Action::GREP,
+        Action::ADD,
+        Action::COMMIT,
+        Action::CHECKOUT,
+      ].freeze
+
+      parameters do
+        string  :action,      description: "The git operation to perform. One of: #{ACTIONS.join(', ')}"
+        boolean :staged,      description: "For `#{Action::DIFF}`: show staged changes instead of unstaged.", required: false
+        string  :path,        description: "A file or directory path, relative to the repo root. Used by #{Action::DIFF}, #{Action::LOG}, #{Action::SHOW}, #{Action::BLAME}, #{Action::GREP}.", required: false
+        string  :ref,         description: "A commit/branch/tag. Used by #{Action::DIFF}, #{Action::SHOW}, #{Action::CHECKOUT}.", required: false
+        integer :count,       description: "For `#{Action::LOG}`: number of commits to show.", required: false
+        integer :start_line,  description: "For `#{Action::BLAME}`: first line of the range.", required: false
+        integer :end_line,    description: "For `#{Action::BLAME}`: last line of the range.", required: false
+        boolean :all,         description: "For `#{Action::BRANCH}`: include remote-tracking branches. For `#{Action::ADD}`: stage all changes. For `#{Action::COMMIT}`: stage tracked files first.", required: false
+        string  :pattern,     description: "For `#{Action::GREP}`: the pattern to search for.", required: false
+        boolean :ignore_case, description: "For `#{Action::GREP}`: case-insensitive search.", required: false
+        boolean :fixed,       description: "For `#{Action::GREP}`: treat pattern as a literal string.", required: false
+        array   :paths,       of: :string, description: "For `#{Action::ADD}`: paths to stage.", required: false
+        string  :message,     description: "For `#{Action::COMMIT}`: the commit message.", required: false
+        boolean :create,      description: "For `#{Action::CHECKOUT}`: create ref as a new branch.", required: false
+      end
+
+      # @param repo_root [String] optional, defaults to the current directory
+      # @param logger [Logger] optional logger
+      def initialize(repo_root: nil, logger: nil)
+        @repo_root = repo_root || Dir.pwd
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @return [String, Hash]
+      def execute(action:, **opts)
+        @logger.info("GitTool#execute action=#{action}")
+
+        case action.to_s.downcase
+        when Action::STATUS   then status_tool.execute
+        when Action::DIFF     then diff_tool.execute(staged: opts[:staged] || false, path: opts[:path], ref: opts[:ref])
+        when Action::LOG      then log_tool.execute(count: opts[:count] || Git::LogTool::DEFAULT_COUNT, path: opts[:path])
+        when Action::SHOW     then show_tool.execute(ref: opts[:ref] || "HEAD", path: opts[:path])
+        when Action::BLAME    then require_param!(:path, opts[:path]) && blame_tool.execute(path: opts[:path], start_line: opts[:start_line], end_line: opts[:end_line])
+        when Action::BRANCH   then branch_tool.execute(all: opts[:all] || false)
+        when Action::GREP     then require_param!(:pattern, opts[:pattern]) && grep_tool.execute(pattern: opts[:pattern], path: opts[:path], ignore_case: opts[:ignore_case] || false, fixed: opts[:fixed] || false)
+        when Action::ADD      then add_tool.execute(paths: opts[:paths], all: opts[:all] || false)
+        when Action::COMMIT   then require_param!(:message, opts[:message]) && commit_tool.execute(message: opts[:message], all: opts[:all] || false)
+        when Action::CHECKOUT then require_param!(:ref, opts[:ref]) && checkout_tool.execute(ref: opts[:ref], create: opts[:create] || false)
+        else
+          { error: "Unsupported action: #{action}. Supported actions are: #{ACTIONS.join(', ')}" }
+        end
+      rescue StandardError => e
+        @logger.error("GitTool execution failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      # @raise [ArgumentError]
+      def require_param!(name, value)
+        raise ArgumentError, "#{name} param is required for this action" if value.nil?
+
+        true
+      end
+
+      def status_tool
+        @status_tool ||= Git::StatusTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def diff_tool
+        @diff_tool ||= Git::DiffTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def log_tool
+        @log_tool ||= Git::LogTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def show_tool
+        @show_tool ||= Git::ShowTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def blame_tool
+        @blame_tool ||= Git::BlameTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def branch_tool
+        @branch_tool ||= Git::BranchTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def grep_tool
+        @grep_tool ||= Git::GrepTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def add_tool
+        @add_tool ||= Git::AddTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def commit_tool
+        @commit_tool ||= Git::CommitTool.new(repo_root: @repo_root, logger: @logger)
+      end
+
+      def checkout_tool
+        @checkout_tool ||= Git::CheckoutTool.new(repo_root: @repo_root, logger: @logger)
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/glob_tool.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Finds files matching a glob pattern within a directory and returns
+    # their paths relative to the glob base, sorted. Each hit is re-checked
+    # against the base so a symlinked match that points outside it is
+    # dropped. Read-only, in-process — no authorization prompt required.
+    #
+    # @example
+    #   tool = SharedTools::Tools::GlobTool.new
+    #   tool.execute(pattern: "**/*.rb")
+    #   tool.execute(pattern: "*.rb", base: "app/models")
+    class GlobTool < ::RubyLLM::Tool
+      MAX_RESULTS = 1_000
+
+      def self.name = 'glob'
+
+      description "Find files matching a glob pattern within a directory (e.g. '**/*.rb', " \
+                  "'app/models/*.rb'). Returns matching paths, sorted, relative to base."
+
+      parameters do
+        string :pattern, description: "Glob pattern such as '**/*.rb', evaluated relative to base."
+        string :base,    description: "Directory to glob from. Defaults to the current directory.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param pattern [String]
+      # @param base [String]
+      #
+      # @return [String, Hash]
+      def execute(pattern:, base: ".")
+        @logger.info("#{self.class.name}#execute pattern=#{pattern.inspect} base=#{base.inspect}")
+
+        return { error: "pattern must be provided" } if pattern.to_s.empty?
+        return { error: "pattern may not contain '..'" } if pattern.include?("..")
+
+        return { error: "not a directory: #{base}" } unless File.directory?(File.expand_path(base))
+
+        root = File.realpath(File.expand_path(base))
+
+        base_pn = Pathname.new(root)
+        results = Dir.glob(File.join(root, pattern), File::FNM_PATHNAME).sort.filter_map do |match|
+          in_base?(root, match) ? Pathname.new(match).relative_path_from(base_pn).to_s : nil
+        end
+
+        capped = results.first(MAX_RESULTS)
+        body = +"#{results.size} match#{results.size == 1 ? '' : 'es'}"
+        body << " (showing first #{MAX_RESULTS})" if results.size > MAX_RESULTS
+        body << " for #{pattern}:\n"
+        capped.each { |rel| body << rel << "\n" }
+        body
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def in_base?(root, match)
+        real = File.realpath(match)
+        (real == root || real.start_with?(root + File::SEPARATOR)) && File.exist?(match)
+      rescue Errno::ENOENT
+        false
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/http_helpers.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "../../shared_tools"
+require_relative "../url_guard"
+
+module SharedTools
+  module Tools
+    # Shared guarded-HTTP behavior for WebFetchTool, HttpRequestTool, and
+    # DownloadFileTool. Every request URL and every redirect hop passes
+    # through UrlGuard, and the socket is pinned to the vetted IP so a second
+    # DNS lookup can't redirect to an internal address. SSRF protection is
+    # always on — there is no bypass.
+    module HttpHelpers
+      HTTP_TIMEOUT = 10
+      MAX_REDIRECTS = 5
+      MAX_FETCH_BYTES = 5 * 1024 * 1024
+      USER_AGENT = "SharedTools/#{SharedTools::VERSION} (+https://github.com/madbomber/shared_tools)"
+
+      Response = Struct.new(:status, :headers, :body, :final_url, keyword_init: true)
+
+      class FetchError < StandardError; end
+
+      def url_guard
+        SharedTools::UrlGuard.new(allowlist: @web_allowlist || [], denylist: @web_denylist || [])
+      end
+
+      # GET with redirect following and a body-size cap. Each hop is
+      # re-guarded and re-pinned.
+      def guarded_get(url)
+        checker = url_guard
+        current = url
+        seen = 0
+
+        loop do
+          resolution = checker.resolve!(current)
+          response, body = perform(resolution.uri, "GET", nil, nil, resolution.address)
+
+          if redirect?(response)
+            location = response["location"]
+            raise FetchError, "redirect with no Location header (status #{response.code})" unless location
+            raise FetchError, "too many redirects (max #{MAX_REDIRECTS})" if seen >= MAX_REDIRECTS
+
+            seen += 1
+            current = URI.join(resolution.uri.to_s, location).to_s
+            next
+          end
+
+          return Response.new(status: response.code.to_i, headers: response.to_hash,
+                              body: body, final_url: resolution.uri.to_s)
+        end
+      rescue SharedTools::UrlGuard::Blocked
+        raise
+      rescue StandardError => e
+        raise FetchError, e.message
+      end
+
+      # A single request with an explicit method/headers/body (no redirect
+      # following). Used by HttpRequestTool.
+      def guarded_request(method, url, headers: {}, body: nil)
+        resolution = url_guard.resolve!(url)
+        response, raw = perform(resolution.uri, method.to_s.upcase, headers, body, resolution.address)
+        Response.new(status: response.code.to_i, headers: response.to_hash, body: raw, final_url: resolution.uri.to_s)
+      rescue SharedTools::UrlGuard::Blocked
+        raise
+      rescue StandardError => e
+        raise FetchError, e.message
+      end
+
+      private
+
+      def redirect?(response)
+        response.is_a?(Net::HTTPRedirection)
+      end
+
+      def perform(uri, method, headers, body, pin)
+        request = build_request(uri, method, headers, body)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.ipaddr = pin if pin # pin to the vetted address (closes DNS rebinding)
+        http.open_timeout = HTTP_TIMEOUT
+        http.read_timeout = HTTP_TIMEOUT
+
+        captured = +""
+        response = http.start do |conn|
+          conn.request(request) do |res|
+            unless res.is_a?(Net::HTTPRedirection)
+              res.read_body do |chunk|
+                captured << chunk
+                break if captured.bytesize >= MAX_FETCH_BYTES
+              end
+            end
+            res
+          end
+        end
+
+        [response, captured]
+      end
+
+      def build_request(uri, method, headers, body)
+        klass = begin
+          Net::HTTP.const_get(method.capitalize)
+        rescue NameError
+          nil
+        end
+        raise FetchError, "unsupported HTTP method: #{method}" unless klass && klass <= Net::HTTPRequest
+
+        request = klass.new(uri)
+        request["User-Agent"] = USER_AGENT
+        request["Accept"] ||= "*/*"
+        Array(headers).each { |k, v| request[k.to_s] = v.to_s } if headers
+        request.body = body.to_s if body && !body.to_s.empty?
+        request
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/http_request_tool.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "http_helpers"
+
+module SharedTools
+  module Tools
+    # A general HTTP client, UrlGuard-protected. Read methods (GET/HEAD) work
+    # by default; mutating methods (POST/PUT/PATCH/DELETE) require user
+    # authorization (see SharedTools.execute?), so the safe default can't
+    # change remote state. Returns status, key headers, and the body.
+    #
+    # @example
+    #   tool = SharedTools::Tools::HttpRequestTool.new
+    #   tool.execute(url: "https://api.example.com/status")
+    #   tool.execute(url: "https://api.example.com/items", method: "POST", body: '{"name":"x"}')
+    class HttpRequestTool < ::RubyLLM::Tool
+      include HttpHelpers
+
+      READ_METHODS = %w[GET HEAD].freeze
+      MUTATING_METHODS = %w[POST PUT PATCH DELETE].freeze
+      SHOWN_HEADERS = %w[content-type content-length location etag last-modified].freeze
+
+      def self.name = 'http_request'
+
+      description "Make an HTTP request to an http/https URL and return the status, headers, and " \
+                  "body. GET and HEAD are available by default; POST/PUT/PATCH/DELETE require user " \
+                  "authorization. Cannot reach private, loopback, or cloud-metadata addresses."
+
+      parameters do
+        string :url,     description: "The http/https URL to request."
+        string :method,  description: "HTTP method: GET (default), HEAD, POST, PUT, PATCH, DELETE.", required: false
+        object :headers, description: "Optional request headers as a JSON object of name/value strings.", required: false do
+          additional_properties true
+        end
+        string :body,    description: "Optional request body (for POST/PUT/PATCH).", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param url [String]
+      # @param method [String]
+      # @param headers [Hash, nil]
+      # @param body [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(url:, method: "GET", headers: nil, body: nil)
+        @logger.info("#{self.class.name}#execute url=#{url.inspect} method=#{method}")
+
+        verb = method.to_s.strip.upcase
+        verb = "GET" if verb.empty?
+        return { error: "unsupported method: #{verb}" } unless (READ_METHODS + MUTATING_METHODS).include?(verb)
+
+        if MUTATING_METHODS.include?(verb)
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "#{verb} #{url}")
+          unless allowed
+            @logger.warn("User declined #{verb} #{url}")
+            return { error: "User declined the request" }
+          end
+        end
+
+        response = guarded_request(verb, url, headers: headers, body: body)
+        return { error: "HTTP #{response.status} from #{response.final_url}" } if response.status >= 400
+
+        format_response(verb, response)
+      rescue SharedTools::UrlGuard::Blocked => e
+        @logger.error("#{self.class.name} url blocked: #{e.message}")
+        { error: e.message }
+      rescue HttpHelpers::FetchError => e
+        @logger.error("#{self.class.name} request failed: #{e.message}")
+        { error: "request failed: #{e.message}" }
+      end
+
+      private
+
+      def format_response(verb, response)
+        lines = ["#{verb} #{response.final_url} -> #{response.status}"]
+        SHOWN_HEADERS.each do |name|
+          value = Array(response.headers[name]).first
+          lines << "#{name}: #{value}" if value
+        end
+        body = response.body.to_s.scrub
+        lines << "\n--- body ---\n#{body}" unless body.empty?
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/json_query_tool.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Parses JSON (from a file or an inline string) and either pretty-prints
+    # it or extracts a value with a dot/bracket path. In-process, read-only.
+    #
+    # Path syntax: dot-separated keys, [n] for array indices, and [] to map a
+    # field across an array. Examples:
+    #   users[0].name        users[].email        config.server.port
+    #
+    # @example
+    #   tool = SharedTools::Tools::JsonQueryTool.new
+    #   tool.execute(path: "./config.json", query: "servers[0].host")
+    #   tool.execute(json: '{"a":{"b":1}}', query: "a.b")
+    class JsonQueryTool < ::RubyLLM::Tool
+      MAX_BYTES = 5 * 1024 * 1024
+
+      def self.name = 'json_query'
+
+      description "Query JSON with a path expression, or pretty-print it. Provide either a file " \
+                  "path or an inline json string. Path syntax: keys separated by dots, [n] for " \
+                  "array index, [] to map over an array (e.g. users[].name)."
+
+      parameters do
+        string :path,  description: "JSON file to read. Provide this or json.", required: false
+        string :json,  description: "Inline JSON string. Provide this or path.", required: false
+        string :query, description: "Path expression to extract, e.g. 'users[0].name'. Omit to pretty-print. Optional.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String, nil]
+      # @param json [String, nil]
+      # @param query [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, json: nil, query: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} query=#{query.inspect}")
+
+        source = load_source(path, json)
+        return source if source.is_a?(Hash) # error
+
+        data = JSON.parse(source)
+        result = query.to_s.strip.empty? ? data : SharedTools::DataPath.query(data, query)
+        JSON.pretty_generate(result)
+      rescue JSON::ParserError => e
+        @logger.error("#{self.class.name} invalid JSON: #{e.message}")
+        { error: "invalid JSON: #{e.message}" }
+      rescue SharedTools::DataPath::Error => e
+        @logger.error("#{self.class.name} bad query: #{e.message}")
+        { error: e.message }
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def load_source(path, json)
+        if path && !path.to_s.empty?
+          return { error: "file not found: #{path}" } unless File.exist?(path)
+          return { error: "not a file: #{path}" } unless File.file?(path)
+          return { error: "file too large (> #{MAX_BYTES} bytes)" } if File.size(path) > MAX_BYTES
+
+          File.read(path).scrub
+        elsif json && !json.to_s.empty?
+          json.to_s
+        else
+          { error: "provide either path or json" }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/lint_tool.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "toolchain_helpers"
+
+module SharedTools
+  module Tools
+    # Runs RuboCop or Standard over a project. Offenses are a normal result,
+    # not a tool error. With autocorrect, the linter rewrites files in place,
+    # so this requires user authorization (see SharedTools.execute?) even
+    # without autocorrect, since it executes an external command.
+    #
+    # @example
+    #   tool = SharedTools::Tools::LintTool.new(root: "./my-project")
+    #   tool.execute
+    #   tool.execute(path: "lib/foo.rb", autocorrect: true)
+    class LintTool < ::RubyLLM::Tool
+      include ToolchainHelpers
+
+      LINTERS = %w[rubocop standard].freeze
+      DEFAULT_TIMEOUT = 120
+
+      def self.name = 'lint'
+
+      description "Lint a project with RuboCop or Standard. Auto-detects (Standard if .standard.yml " \
+                  "is present, else RuboCop) or set linter explicitly. Optionally scope to a path and " \
+                  "apply safe autocorrections. Uses `bundle exec` when a Gemfile exists."
+
+      parameters do
+        string  :path,        description: "Limit linting to this path, relative to root. Optional.", required: false
+        string  :linter,      description: "Force the linter: rubocop or standard. Default: auto-detect.", required: false
+        boolean :autocorrect, description: "Apply safe autocorrections, rewriting files in place. Default false.", required: false
+      end
+
+      # @param root [String] optional, defaults to the current directory
+      # @param logger [Logger] optional logger
+      def initialize(root: nil, logger: nil)
+        @root = root || Dir.pwd
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String, nil]
+      # @param linter [String, nil]
+      # @param autocorrect [Boolean]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, linter: nil, autocorrect: false)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} linter=#{linter.inspect} autocorrect=#{autocorrect}")
+
+        tool = (linter || detect_linter).to_s
+        return { error: "unknown linter: #{tool} (use #{LINTERS.join(', ')})" } unless LINTERS.include?(tool)
+
+        rel = jail_relative(path)
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Lint#{autocorrect ? ' with autocorrect' : ''}: #{tool}#{rel ? " #{rel}" : ''}")
+        unless allowed
+          @logger.warn("User declined to lint")
+          return { error: "User declined to lint" }
+        end
+
+        out, err, status = run_in_project(build_args(tool, rel, autocorrect), use_bundle: true, timeout: DEFAULT_TIMEOUT)
+        toolchain_output(out, err, status,
+                         pass_label: "LINT CLEAN",
+                         fail_label: autocorrect ? "LINT: offenses found (autocorrected where possible)" : "LINT: offenses found",
+                         timeout: DEFAULT_TIMEOUT)
+      rescue SecurityError => e
+        @logger.error("#{self.class.name} path denied: #{e.message}")
+        { error: e.message }
+      rescue CommandMissing => e
+        @logger.error("#{self.class.name}: #{e.message} is not available")
+        { error: "#{e.message} is not available (is it in the bundle / installed?)" }
+      end
+
+      private
+
+      def detect_linter
+        File.exist?(File.join(@root, ".standard.yml")) ? "standard" : "rubocop"
+      end
+
+      def build_args(tool, rel, autocorrect)
+        if tool == "standard"
+          args = ["standardrb"]
+          args << "--fix" if autocorrect
+        else
+          args = ["rubocop", "--no-color"]
+          args << "--autocorrect" if autocorrect
+        end
+        args << rel if rel
+        args
+      end
+    end
+  end
+end