shared_tools 0.4.4 → 0.7.0

data/lib/shared_tools/tools/gem_tool.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require_relative "../../shared_tools"
+
+module SharedTools
+  module Tools
+    # Read-only RubyGems.org metadata lookup. The host is fixed and all user
+    # input is URL-encoded into the path/query (and gem names are validated),
+    # so there is no arbitrary-URL / SSRF surface here.
+    #
+    # @example
+    #   tool = SharedTools::Tools::GemTool.new
+    #   tool.execute(name: "ruby_llm")
+    #   tool.execute(name: "ruby_llm", action: "version")
+    #   tool.execute(name: "sqlite3", action: "search")
+    class GemTool < ::RubyLLM::Tool
+      class NotFound < StandardError; end
+      class HttpError < StandardError; end
+
+      HTTP_TIMEOUT = 10
+      USER_AGENT = "SharedTools/#{SharedTools::VERSION} (+https://github.com/madbomber/shared_tools)"
+      ACTIONS = %w[info version dependencies search].freeze
+      NAME_RE = /\A[A-Za-z0-9_.-]+\z/
+      HOST = "https://rubygems.org"
+
+      def self.tool_name = 'gem'
+
+      description "Look up RubyGems.org metadata for a gem (read-only). Actions: info (summary), " \
+                  "version (latest version), dependencies (runtime deps), search (find gems by " \
+                  "query). For 'search', pass the query as name."
+
+      parameters do
+        string :name,   description: "Gem name, or — for action 'search' — the search query."
+        string :action, description: "One of: info, version, dependencies, search. Default info.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param name [String]
+      # @param action [String]
+      #
+      # @return [String, Hash]
+      def execute(name:, action: "info")
+        @logger.info("#{self.class.name}#execute name=#{name.inspect} action=#{action.inspect}")
+
+        act = normalize_action(action)
+        return { error: "unknown action: #{act} (use #{ACTIONS.join(', ')})" } unless ACTIONS.include?(act)
+        return search(name) if act == "search"
+
+        gem = name.to_s.strip
+        return { error: "invalid gem name: #{gem.inspect}" } unless gem.match?(NAME_RE)
+
+        case act
+        when "version"      then version(gem)
+        when "dependencies" then dependencies(gem)
+        else                     info(gem)
+        end
+      rescue NotFound
+        @logger.error("#{self.class.name}: gem not found: #{name}")
+        { error: "gem not found: #{name}" }
+      rescue HttpError => e
+        @logger.error("#{self.class.name}: rubygems.org request failed: #{e.message}")
+        { error: "rubygems.org request failed: #{e.message}" }
+      end
+
+      private
+
+      def normalize_action(action)
+        a = action.to_s.strip.downcase
+        a.empty? ? "info" : a
+      end
+
+      def info(gem)
+        data = get_json("#{HOST}/api/v1/gems/#{enc(gem)}.json")
+        lines = ["#{data['name']} #{data['version']}"]
+        lines << data["info"].to_s.strip unless data["info"].to_s.strip.empty?
+        lines << "homepage: #{data['homepage_uri']}" if data["homepage_uri"]
+        lines << "licenses: #{Array(data['licenses']).join(', ')}" if data["licenses"]
+        lines << "downloads: #{data['downloads']}" if data["downloads"]
+        runtime = data.dig("dependencies", "runtime") || []
+        unless runtime.empty?
+          lines << "runtime deps: #{runtime.map { |d| "#{d['name']} #{d['requirements']}" }.join('; ')}"
+        end
+        lines.join("\n")
+      end
+
+      def version(gem)
+        data = get_json("#{HOST}/api/v1/versions/#{enc(gem)}/latest.json")
+        v = data["version"]
+        return { error: "gem not found: #{gem}" } if v.nil? || v == "unknown"
+
+        "#{gem} #{v}"
+      end
+
+      def dependencies(gem)
+        data = get_json("#{HOST}/api/v1/gems/#{enc(gem)}.json")
+        runtime = data.dig("dependencies", "runtime") || []
+        dev = data.dig("dependencies", "development") || []
+        return "#{gem} #{data['version']} has no runtime dependencies" if runtime.empty?
+
+        body = +"#{gem} #{data['version']} runtime dependencies:\n"
+        runtime.each { |d| body << "  #{d['name']} #{d['requirements']}\n" }
+        body << "(+#{dev.size} development deps)" unless dev.empty?
+        body
+      end
+
+      def search(query)
+        q = query.to_s.strip
+        return { error: "empty search query" } if q.empty?
+
+        results = get_json("#{HOST}/api/v1/search.json?query=#{enc(q)}")
+        return "no gems found for #{q.inspect}" unless results.is_a?(Array) && results.any?
+
+        body = +"#{results.size} result#{results.size == 1 ? '' : 's'} for #{q.inspect}:\n"
+        results.first(20).each do |g|
+          summary = g["info"].to_s.split("\n").first
+          body << "  #{g['name']} #{g['version']} — #{summary}\n"
+        end
+        body
+      end
+
+      def enc(str)
+        URI.encode_www_form_component(str)
+      end
+
+      # Seam for tests. Performs a GET and parses JSON, mapping transport and
+      # not-found conditions onto the tool's error classes.
+      def get_json(url)
+        uri = URI.parse(url)
+        req = Net::HTTP::Get.new(uri)
+        req["User-Agent"] = USER_AGENT
+        req["Accept"] = "application/json"
+
+        res = Net::HTTP.start(uri.host, uri.port,
+                              use_ssl: uri.scheme == "https",
+                              open_timeout: HTTP_TIMEOUT,
+                              read_timeout: HTTP_TIMEOUT) { |http| http.request(req) }
+
+        case res
+        when Net::HTTPSuccess  then JSON.parse(res.body)
+        when Net::HTTPNotFound then raise NotFound
+        else raise HttpError, "HTTP #{res.code}"
+        end
+      rescue JSON::ParserError => e
+        raise HttpError, "invalid JSON (#{e.message})"
+      rescue SocketError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise HttpError, e.message
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Mutating. Stages changes in the repo at repo_root. Requires user
+      # authorization (see SharedTools.execute?).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::AddTool.new
+      #   tool.execute(paths: ["lib/foo.rb"])
+      #   tool.execute(all: true)
+      class AddTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_add'
+
+        description "Stage changes in the repository. Pass specific paths, or set all to stage " \
+                    "every change (git add -A)."
+
+        parameters do
+          array   :paths, of: :string, description: "Paths to stage, relative to the repo root.", required: false
+          boolean :all,   description: "Stage all changes (git add -A) instead of specific paths. Default false.", 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 paths [Array<String>, nil]
+        # @param all [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(paths: nil, all: false)
+          @logger.info("#{self.class.name}#execute paths=#{paths.inspect} all=#{all}")
+
+          rels = Array(paths).filter_map { |p| repo_relative(p, repo_root: @repo_root) }
+
+          if all
+            args = ["add", "-A"]
+          elsif rels.empty?
+            return { error: "provide paths or set all: true" }
+          else
+            args = ["add", "--", *rels]
+          end
+
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: args.join(" "))
+          unless allowed
+            @logger.warn("User declined to stage changes")
+            return { error: "User declined to stage changes" }
+          end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          all ? "Staged all changes" : "Staged: #{rels.join(', ')}"
+        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/blame_tool.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows line-by-line authorship (commit, author, date) for a
+      # file in the repo at repo_root.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::BlameTool.new
+      #   tool.execute(path: "lib/foo.rb", start_line: 10, end_line: 20)
+      class BlameTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_blame'
+
+        description "Show git blame for a file in the repository: which commit, author, and date " \
+                    "last touched each line. Optionally limit to a line range. Read-only."
+
+        parameters do
+          string  :path,        description: "File to blame, relative to the repo root."
+          integer :start_line,  description: "First line of the range to blame. Optional.", required: false
+          integer :end_line,    description: "Last line of the range to blame. 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 path [String]
+        # @param start_line [Integer, nil]
+        # @param end_line [Integer, nil]
+        #
+        # @return [String, Hash]
+        def execute(path:, start_line: nil, end_line: nil)
+          @logger.info("#{self.class.name}#execute path=#{path.inspect} start_line=#{start_line.inspect} end_line=#{end_line.inspect}")
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          return { error: "path must be provided" } if rel.nil?
+
+          args = ["blame", "--date=short"]
+          if (range = line_range(start_line, end_line))
+            args += ["-L", range]
+          end
+          args += ["--", rel]
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          result.strip.empty? ? "no blame output (empty file?)" : 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
+
+        private
+
+        def line_range(start_line, end_line)
+          return nil if start_line.nil? && end_line.nil?
+
+          first = [start_line.to_i, 1].max
+          last  = end_line.nil? ? "" : [end_line.to_i, first].max
+          "#{first},#{last}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Lists the branches of the repo at repo_root, with the
+      # current branch marked and each branch's latest commit. Does not
+      # create, switch, or delete branches (see Git::CheckoutTool).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::BranchTool.new
+      #   tool.execute(all: true)
+      class BranchTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_branch'
+
+        description "List the branches of the repository, with the current branch marked (*) and " \
+                    "each branch's tip commit. Set all true to include remote-tracking branches. Read-only."
+
+        parameters do
+          boolean :all, description: "Include remote-tracking branches. Default false (local only).", 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 all [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(all: false)
+          @logger.info("#{self.class.name}#execute all=#{all}")
+
+          args = ["branch", "--no-color", "-vv"]
+          args << "-a" if all
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          result.strip.empty? ? "no branches yet (no commits?)" : 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/checkout_tool.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Mutating. Switches branches or creates a new branch in the repo at
+      # repo_root; can change the working tree. The ref is validated (no
+      # leading dash, ref-safe characters only) so it can't smuggle git
+      # options. Requires user authorization (see SharedTools.execute?).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::CheckoutTool.new
+      #   tool.execute(ref: "main")
+      #   tool.execute(ref: "feature/x", create: true)
+      class CheckoutTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_checkout'
+
+        description "Switch to a branch/commit in the repository, or create a new branch with " \
+                    "create: true. Note this can change the working tree."
+
+        parameters do
+          string  :ref,    description: "Branch, tag, or commit to switch to (or the new branch name when create is true)."
+          boolean :create, description: "Create a new branch named ref before switching to it (git checkout -b). Default false.", 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 create [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(ref:, create: false)
+          @logger.info("#{self.class.name}#execute ref=#{ref.inspect} create=#{create}")
+
+          return { error: "invalid ref: #{ref.inspect}" } unless valid_ref?(ref)
+
+          args = ["checkout"]
+          args << "-b" if create
+          args << ref
+
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: args.join(" "))
+          unless allowed
+            @logger.warn("User declined to checkout #{ref}")
+            return { error: "User declined to checkout #{ref}" }
+          end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          # git prints checkout feedback to stderr on success.
+          [out, err].map(&:strip).reject(&:empty?).join("\n")
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Mutating. Commits staged changes in the repo at repo_root with a
+      # message. The message is passed as a single argv element (-m), so it
+      # is never parsed by a shell. Requires user authorization (see
+      # SharedTools.execute?). Does not push.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::CommitTool.new
+      #   tool.execute(message: "Fix the thing")
+      class CommitTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_commit'
+
+        description "Commit staged changes in the repository with a message. Set all to also " \
+                    "stage modified/deleted tracked files first (git commit -a). Does not push."
+
+        parameters do
+          string  :message, description: "Commit message."
+          boolean :all,     description: "Stage modified/deleted tracked files before committing (git commit -a). Default false.", 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 message [String]
+        # @param all [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(message:, all: false)
+          @logger.info("#{self.class.name}#execute all=#{all}")
+
+          msg = message.to_s
+          return { error: "commit message must not be empty" } if msg.strip.empty?
+
+          args = ["commit"]
+          args << "-a" if all
+          args += ["-m", msg]
+
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "git commit#{all ? ' -a' : ''} -m #{msg.inspect}")
+          unless allowed
+            @logger.warn("User declined to commit")
+            return { error: "User declined to commit" }
+          end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          if result.is_a?(Hash)
+            combined = "#{out}\n#{err}"
+            return { error: "nothing to commit (stage changes first)" } if combined.match?(/nothing to commit/i)
+
+            return result
+          end
+
+          out.strip
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows a unified diff of the repo at repo_root. External
+      # diff drivers and textconv filters are disabled so a malicious repo
+      # can't turn a diff into command execution.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::DiffTool.new
+      #   tool.execute
+      #   tool.execute(staged: true, path: "lib/foo.rb")
+      class DiffTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_diff'
+
+        description "Show a unified git diff for the repository. By default shows unstaged " \
+                    "changes; set staged to show what's staged. Optionally scope to a path or diff " \
+                    "against a ref. Read-only."
+
+        parameters do
+          boolean :staged, description: "Show staged changes (git diff --cached) instead of unstaged. Default false.", required: false
+          string  :path,   description: "Limit the diff to this path, relative to the repo root. Optional.", required: false
+          string  :ref,    description: "Diff against this commit/branch/tag instead of the index. 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 staged [Boolean]
+        # @param path [String, nil]
+        # @param ref [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(staged: false, path: nil, ref: nil)
+          @logger.info("#{self.class.name}#execute staged=#{staged} path=#{path.inspect} ref=#{ref.inspect}")
+
+          return { error: "invalid ref: #{ref.inspect}" } if ref && !valid_ref?(ref)
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = ["diff", "--no-ext-diff", "--no-textconv", "--stat", "--patch"]
+          args << "--cached" if staged
+          args << ref if ref
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          result.strip.empty? ? "no changes" : 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/grep_tool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Searches the repo's tracked files with `git grep` and
+      # returns matching lines with file:line prefixes. Faster and cleaner
+      # than a filesystem grep in a git repo because it only looks at
+      # tracked content and skips binary files.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::GrepTool.new
+      #   tool.execute(pattern: "def execute")
+      class GrepTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.tool_name = 'git_grep'
+
+        description "Search the tracked files of the repository for a pattern using git grep, " \
+                    "returning file:line: matches. Optionally restrict to a path, ignore case, or treat " \
+                    "the pattern as a fixed string instead of a regex."
+
+        parameters do
+          string  :pattern,     description: "The pattern to search for (a basic regex unless fixed is true)."
+          string  :path,        description: "Restrict the search to this file or directory, relative to the repo root. Optional.", required: false
+          boolean :ignore_case, description: "Case-insensitive search. Default false.", required: false
+          boolean :fixed,       description: "Treat the pattern as a literal string rather than a regex. Default false.", 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 pattern [String]
+        # @param path [String, nil]
+        # @param ignore_case [Boolean]
+        # @param fixed [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(pattern:, path: nil, ignore_case: false, fixed: false)
+          @logger.info("#{self.class.name}#execute pattern=#{pattern.inspect} path=#{path.inspect}")
+
+          pat = pattern.to_s
+          return { error: "pattern must not be empty" } if pat.empty?
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = ["grep", "-n", "-I", "--no-color"]
+          args << "-i" if ignore_case
+          args << "-F" if fixed
+          args += ["-e", pat] # -e guards against a pattern that begins with "-"
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          interpret(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
+
+        private
+
+        # git grep exits 1 (with no error output) when there are simply no
+        # matches — that's a normal result, not a tool failure.
+        def interpret(out, err, status)
+          case status.exitstatus
+          when 0 then out
+          when 1 then err.to_s.strip.empty? ? "no matches" : { error: err.strip }
+          else { error: err.to_s.strip.empty? ? out.to_s.strip : err.strip }
+          end
+        end
+      end
+    end
+  end
+end