shared_tools 0.4.4 → 0.6.0

data/lib/shared_tools/tools/disk/file_write_tool.rb

@@ -13,7 +13,7 @@ module SharedTools
 
         description "Writes the contents of a file."
 
-        params do
+        parameters do
           string :path, description: "a path for the file (e.g. `./main.rb`)"
           string :text, description: "the text to write to the file (e.g. `puts 'Hello World'`)"
         end

data/lib/shared_tools/tools/disk_tool.rb

@@ -44,7 +44,7 @@ module SharedTools
         Action::FILE_REPLACE,
       ].freeze
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           Options:
           * `#{Action::DIRECTORY_CREATE}`: creates a directory at a specific `path`

data/lib/shared_tools/tools/dns_tool.rb

@@ -40,7 +40,7 @@ module SharedTools
         - 'whois'       — Query the WHOIS database for a domain name or IP address
       DESC
 
-      params do
+      parameters do
         string :action, description: <<~DESC.strip
           The DNS or network operation to perform. One of:
           - 'a'           — Look up IPv4 A records for a hostname. Returns the IPv4 addresses

data/lib/shared_tools/tools/doc/docx_reader_tool.rb

@@ -20,7 +20,7 @@ module SharedTools
 
         description "Read the text content of a Microsoft Word (.docx) document."
 
-        params do
+        parameters do
           string :doc_path, description: "Path to the .docx file."
 
           string :paragraph_range, description: <<~DESC.strip, required: false

data/lib/shared_tools/tools/doc/pdf_reader_tool.rb

@@ -18,7 +18,7 @@ module SharedTools
 
         description "Read the text of any set of pages from a PDF document."
 
-        params do
+        parameters do
           string :page_numbers, description: 'Comma-separated page numbers (first page: 1). (e.g. "12, 14, 15")'
           string :doc_path, description: "Path to the PDF document."
         end

data/lib/shared_tools/tools/doc/spreadsheet_reader_tool.rb

@@ -27,7 +27,7 @@ module SharedTools
 
         SUPPORTED_FORMATS = %w[.csv .xlsx .ods .xlsm].freeze
 
-        params do
+        parameters do
           string :doc_path, description: <<~DESC.strip
             Path to the spreadsheet file. Supported formats:
             - .csv  — Comma-separated values (plain text, no gem beyond roo required)

data/lib/shared_tools/tools/doc/text_reader_tool.rb

@@ -13,7 +13,7 @@ module SharedTools
 
         description "Read the full contents of a plain text file."
 
-        params do
+        parameters do
           string :doc_path, description: "Path to the text file to read."
         end
 

data/lib/shared_tools/tools/doc_tool.rb

@@ -85,7 +85,7 @@ module SharedTools
           {"action": "#{Action::SPREADSHEET_READ}", "doc_path": "./report.xlsx", "row_range": "2-50", "headers": false}
       TEXT
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           The document action to perform. Options:
           * `#{Action::TEXT_READ}`: Read a plain text file

data/lib/shared_tools/tools/docker/compose_run_tool.rb

@@ -13,7 +13,7 @@ module SharedTools
 
         description "Runs a command via Docker with arguments on the project (e.g. `rspec spec/main_spec.rb`)."
 
-        params do
+        parameters do
           string :service, description: "The service to run the command on (e.g. `app`).", required: false
           string :command, description: "The command to run (e.g. `rspec`)."
           array :args, of: :string, description: "The arguments for the command.", required: false

data/lib/shared_tools/tools/download_file_tool.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require_relative "../../shared_tools"
+require_relative "http_helpers"
+
+module SharedTools
+  module Tools
+    # Downloads a URL to a file within root. The request goes through
+    # UrlGuard (so it can't be pointed at internal/loopback/metadata
+    # addresses), follows redirects safely, and is capped at
+    # HttpHelpers::MAX_FETCH_BYTES. The destination path is confined to
+    # root. Mutating — requires user authorization (see
+    # SharedTools.execute?).
+    #
+    # @example
+    #   tool = SharedTools::Tools::DownloadFileTool.new(root: "./downloads")
+    #   tool.execute(url: "https://example.com/file.zip", path: "file.zip")
+    class DownloadFileTool < ::RubyLLM::Tool
+      include HttpHelpers
+
+      def self.name = 'download_file'
+
+      description "Download an http/https URL to a file within root. SSRF-protected and " \
+                  "size-capped. Use for fetching an asset or release to disk (web_fetch returns text " \
+                  "instead). Overwrites an existing file."
+
+      parameters do
+        string :url,  description: "The http/https URL to download."
+        string :path, description: "Destination path, relative to root."
+      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 url [String]
+      # @param path [String]
+      #
+      # @return [String, Hash]
+      def execute(url:, path:)
+        @logger.info("#{self.class.name}#execute url=#{url.inspect} path=#{path.inspect}")
+
+        real = resolve!(path)
+        return { error: "path is a directory: #{path}" } if File.directory?(real)
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Download #{url} to #{path}")
+        unless allowed
+          @logger.warn("User declined to download #{url}")
+          return { error: "User declined to download the file" }
+        end
+
+        response = guarded_get(url)
+        return { error: "server returned HTTP #{response.status} for #{response.final_url}" } if response.status >= 400
+
+        body = response.body.to_s
+        FileUtils.mkdir_p(File.dirname(real))
+        File.binwrite(real, body)
+
+        "Downloaded #{body.bytesize} bytes from #{response.final_url} to #{path}"
+      rescue SecurityError => e
+        @logger.error("#{self.class.name} path denied: #{e.message}")
+        { error: e.message }
+      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} download failed: #{e.message}")
+        { error: "download failed: #{e.message}" }
+      end
+
+      private
+
+      def resolve!(path)
+        root = Pathname.new(File.expand_path(@root))
+        resolved = (root + path).cleanpath
+        raise SecurityError, "path escapes root: #{path}" unless resolved.ascend.any? { |ancestor| ancestor == root }
+
+        resolved.to_s
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/enabler.rb

@@ -24,8 +24,8 @@ module Tools
     description <<~DESCRIPTION
       Enables a tool based on the request.
     DESCRIPTION
-    param :tool, desc: 'Tool name to enable'
-    # param :params, desc: 'JSON formatted parameters'
+    parameter :tool, description: 'Tool name to enable'
+    # parameter :params, description: 'JSON formatted parameters', required: false
 
     def initialize(agent)
       @agent = agent

data/lib/shared_tools/tools/error_handling_tool.rb

@@ -52,7 +52,7 @@ module SharedTools
           )
       DESCRIPTION
 
-      params do
+      parameters do
         string :operation, description: <<~DESC.strip
           The operation to perform. Options:
           - 'validate': Validate data structure and content

data/lib/shared_tools/tools/eval/python_eval_tool.rb

@@ -21,7 +21,7 @@ module SharedTools
                       NOTE: Requires python3 to be available in the system PATH.
                     DESCRIPTION
 
-        params do
+        parameters do
           string :code, description: "The Python code to execute"
         end
 

data/lib/shared_tools/tools/eval/ruby_eval_tool.rb

@@ -20,7 +20,7 @@ module SharedTools
                       WARNING: This tool executes arbitrary Ruby code. Use with caution.
                     DESCRIPTION
 
-        params do
+        parameters do
           string :code, description: "The Ruby code to execute"
         end
 

data/lib/shared_tools/tools/eval/shell_eval_tool.rb

@@ -17,7 +17,7 @@ module SharedTools
 
         description "Execute a shell command safely and return the result."
 
-        params do
+        parameters do
           string :command, description: "The shell command to execute"
           string :workdir, description: "Working directory for the command (default: current directory)", required: false
         end

data/lib/shared_tools/tools/eval_tool.rb

@@ -58,7 +58,7 @@ module SharedTools
           {"action": "#{Action::SHELL}", "command": "uname -a"}
       TEXT
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           The evaluation action to perform. Options:
           * `#{Action::RUBY}`: Execute Ruby code

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.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.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.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.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.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