shared_tools 0.4.4 → 0.7.0

data/lib/shared_tools/tools/git/helpers.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+module SharedTools
+  module Tools
+    module Git
+      # Shared behavior for the git tools: running git the same hardened way,
+      # and mapping its output onto the shared_tools { error: } contract.
+      #
+      # Hardening matters because git executes commands configured *by the
+      # repository* in several places, which turns "read-only" commands into
+      # arbitrary code execution when operating on an untrusted checkout:
+      #   - core.fsmonitor runs a command during `git status`
+      #   - diff.external / textconv run commands during `git diff`
+      # core.fsmonitor is disabled via `-c`, and the diff/show tools pass
+      # --no-ext-diff --no-textconv. The pager and credential prompts are
+      # also disabled so a call can never hang waiting on a TTY.
+      module Helpers
+        GIT_ENV = { "GIT_PAGER" => "cat", "GIT_TERMINAL_PROMPT" => "0" }.freeze
+        # A ref/branch the model supplies: no leading dash (option injection),
+        # and only the characters git refs legitimately use.
+        REF_RE = %r{\A[A-Za-z0-9][\w./\-]*\z}
+
+        # @param args [Array<String>]
+        # @param repo_root [String]
+        # @return [Array(String, String, Process::Status)] stdout, stderr, status
+        def run_git(*args, repo_root:)
+          Open3.capture3(GIT_ENV, "git", "-c", "core.fsmonitor=", "-C", repo_root.to_s, "--no-pager", *args)
+        end
+
+        # Maps a finished git run onto the shared_tools return contract.
+        #
+        # @return [String, Hash] stdout on success, or an { error:, code: } hash
+        def git_result(out, err, status)
+          return out if status.success?
+
+          message = (err.to_s.empty? ? out.to_s : err.to_s).strip
+          code = message.match?(/not a git repository/i) ? :not_a_repo : :git_error
+          { error: message.empty? ? "git failed with exit code #{status.exitstatus}" : "git failed: #{message}", code: code }
+        end
+
+        # @param ref [String]
+        # @return [Boolean]
+        def valid_ref?(ref)
+          ref.to_s.match?(REF_RE)
+        end
+
+        # Resolve a path param to a repo-relative path, rejecting jail escapes.
+        # Returns nil for a blank path.
+        #
+        # @param path [String, nil]
+        # @param repo_root [String]
+        #
+        # @raise [SecurityError] if the path escapes repo_root
+        # @return [String, nil]
+        def repo_relative(path, repo_root:)
+          return nil if path.nil? || path.to_s.strip.empty?
+
+          root = Pathname.new(File.expand_path(repo_root))
+          resolved = (root + path).cleanpath
+          raise SecurityError, "path escapes repo_root: #{path}" unless resolved.ascend.any? { |ancestor| ancestor == root }
+
+          resolved.relative_path_from(root).to_s
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/log_tool.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows recent commit history for the repo at repo_root.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::LogTool.new
+      #   tool.execute(count: 10)
+      class LogTool < ::RubyLLM::Tool
+        include Helpers
+
+        DEFAULT_COUNT = 20
+        MAX_COUNT     = 200
+        FORMAT        = "%h %ad %an: %s"
+
+        def self.tool_name = 'git_log'
+
+        description "Show recent git commit history for the repository (hash, date, author, " \
+                    "subject). Optionally limit the count or scope to a path. Read-only."
+
+        parameters do
+          integer :count, description: "Number of commits to show (default #{DEFAULT_COUNT}, max #{MAX_COUNT}).", required: false
+          string  :path,  description: "Limit history to commits touching this path, relative to the repo root. Optional.", 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
+
+        # @param count [Integer]
+        # @param path [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(count: DEFAULT_COUNT, path: nil)
+          @logger.info("#{self.class.name}#execute count=#{count} path=#{path.inspect}")
+
+          n = count.to_i
+          n = DEFAULT_COUNT if n <= 0
+          n = MAX_COUNT if n > MAX_COUNT
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = ["log", "--max-count=#{n}", "--date=short", "--pretty=format:#{FORMAT}"]
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          if result.is_a?(Hash)
+            return "no commits" if result[:error].to_s.match?(/does not have any commits yet|bad default revision/i)
+
+            return result
+          end
+
+          result.strip.empty? ? "no commits" : result
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/show_tool.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows a commit (message + diff) or the contents of a file
+      # at a given ref. External diff drivers and textconv are disabled.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::ShowTool.new
+      #   tool.execute
+      #   tool.execute(ref: "HEAD~1", path: "lib/foo.rb")
+      class ShowTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_show'
+
+        description "Show a git object in the repository. With no path, shows the commit at ref " \
+                    "(message and diff). With a path, shows that file's contents as of ref. Defaults " \
+                    "to HEAD. Read-only."
+
+        parameters do
+          string :ref,  description: "Commit/branch/tag to show. Default HEAD.", required: false
+          string :path, description: "If given, show this file's contents at ref instead of the commit. Optional.", 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
+
+        # @param ref [String]
+        # @param path [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(ref: "HEAD", path: nil)
+          @logger.info("#{self.class.name}#execute ref=#{ref.inspect} path=#{path.inspect}")
+
+          ref = ref.to_s.strip
+          ref = "HEAD" if ref.empty?
+          return { error: "invalid ref: #{ref.inspect}" } unless valid_ref?(ref)
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = if rel
+                   ["show", "#{ref}:#{rel}"]
+                 else
+                   ["show", "--no-ext-diff", "--no-textconv", "--stat", "--patch", ref]
+                 end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          git_result(out, err, status)
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/status_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows the working-tree status of the repo at repo_root
+      # (current branch plus staged/unstaged/untracked changes).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::StatusTool.new
+      #   tool.execute
+      class StatusTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_status'
+
+        description "Show the git working-tree status of the repository: current branch and " \
+                    "staged, unstaged, and untracked changes. Read-only."
+
+        # @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
+          @logger.info("#{self.class.name}#execute repo_root=#{@repo_root}")
+
+          out, err, status = run_git("status", "--short", "--branch", repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          changes = result.each_line.reject { |line| line.start_with?("##") }
+          changes.empty? ? "working tree clean" : result
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Collection loader for all git tools
+# Usage: require 'shared_tools/tools/git'
+
+require 'shared_tools'
+
+require_relative 'git/helpers'
+require_relative 'git/status_tool'
+require_relative 'git/diff_tool'
+require_relative 'git/log_tool'
+require_relative 'git/show_tool'
+require_relative 'git/blame_tool'
+require_relative 'git/branch_tool'
+require_relative 'git/grep_tool'
+require_relative 'git/add_tool'
+require_relative 'git/commit_tool'
+require_relative 'git/checkout_tool'

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.tool_name = 'git'
+
+      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.tool_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