shared_tools 0.4.4 → 0.7.0

data/lib/shared_tools/tools/diff_tool.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Compares two blocks of text and returns a readable line diff. In-process,
+    # read-only — no filesystem or git access. For diffing files already on
+    # disk, see Git::DiffTool.
+    #
+    # @example
+    #   tool = SharedTools::Tools::DiffTool.new
+    #   tool.execute(old: "a\nb\n", new: "a\nc\n")
+    class DiffTool < ::RubyLLM::Tool
+      def self.tool_name = 'diff'
+
+      description "Compare two blocks of text and return a readable line-by-line diff " \
+                  "(removed lines prefixed -, added lines prefixed +). In-process."
+
+      parameters do
+        string :old,       description: "The original text."
+        string :new,       description: "The changed text."
+        string :old_label, description: "Label for the original side. Default 'old'.", required: false
+        string :new_label, description: "Label for the changed side. Default 'new'.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param old [String]
+      # @param new [String]
+      # @param old_label [String]
+      # @param new_label [String]
+      #
+      # @return [String]
+      def execute(old:, new:, old_label: "old", new_label: "new")
+        @logger.info("#{self.class.name}#execute old_label=#{old_label} new_label=#{new_label}")
+
+        SharedTools::TextDiff.unified(old.to_s, new.to_s, old_label: old_label.to_s, new_label: new_label.to_s)
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+    end
+  end
+end

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::DirectoryCreateTool.new(root: "./project")
       #   tool.execute(path: "./foo/bar")
       class DirectoryCreateTool < ::RubyLLM::Tool
-        def self.name = 'disk_directory_create'
+        def self.tool_name = 'disk_directory_create'
 
         description "Creates a directory."
 
-        params do
+        parameters do
           string :path, description: "a path to the directory (e.g. `./foo/bar`)"
         end
 

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::DirectoryDeleteTool.new(root: "./project")
       #   tool.execute(path: "./foo/bar")
       class DirectoryDeleteTool < ::RubyLLM::Tool
-        def self.name = 'disk_directory_delete'
+        def self.tool_name = 'disk_directory_delete'
 
         description "Deletes a directory."
 
-        params do
+        parameters do
           string :path, description: "a path to the directory (e.g. `./foo/bar`)"
         end
 

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::SummaryTool.new(root: "./project")
       #   tool.execute
       class DirectoryListTool < ::RubyLLM::Tool
-        def self.name = 'disk_directory_list'
+        def self.tool_name = 'disk_directory_list'
 
         description "Summarizes the contents (files and directories) of a directory."
 
-        params do
+        parameters do
           string :path, description: "a path to the directory (e.g. `./foo/bar`)", required: false
         end
 

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::DirectoryMoveTool.new(root: "./project")
       #   tool.execute(path: "./foo", destination: "./bar")
       class DirectoryMoveTool < ::RubyLLM::Tool
-        def self.name = 'disk_directory_move'
+        def self.tool_name = 'disk_directory_move'
 
         description "Moves a directory from one location to another."
 
-        params do
+        parameters do
           string :path, description: "a path (e.g. `./old`)"
           string :destination, description: "a path (e.g. `./new`)"
         end

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::FileCreateTool.new(root: "./project")
       #   tool.execute(path: "./README.md")
       class FileCreateTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_create'
+        def self.tool_name = 'disk_file_create'
 
         description "Creates a file."
 
-        params do
+        parameters do
           string :path, description: "a path to the file (e.g. `./README.md`)"
         end
 

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::FileDeleteTool.new(root: "./project")
       #   tool.execute(path: "./README.md")
       class FileDeleteTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_delete'
+        def self.tool_name = 'disk_file_delete'
 
         description "Deletes a file."
 
-        params do
+        parameters do
           string :path, description: "a path to the file (e.g. `./README.md`)"
         end
 

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

@@ -12,11 +12,11 @@ module SharedTools
       #     destination: "./README.md",
       #   )
       class FileMoveTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_move'
+        def self.tool_name = 'disk_file_move'
 
         description "Moves a file."
 
-        params do
+        parameters do
           string :path, description: "a path (e.g. `./old.rb`)"
           string :destination, description: "a path (e.g. `./new.rb`)"
         end

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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Disk::FileReadTool.new
       #   tool.execute(path: "./README.md") # => "..."
       class FileReadTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_read'
+        def self.tool_name = 'disk_file_read'
 
         description "Reads the contents of a file."
 
-        params do
+        parameters do
           string :path, description: "a path (e.g. `./main.rb`)"
         end
 

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

@@ -13,11 +13,11 @@ module SharedTools
       #     path: "README.md"
       #   )
       class FileReplaceTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_replace'
+        def self.tool_name = 'disk_file_replace'
 
         description "Replaces a specific string in a file (old_text => new_text)."
 
-        params do
+        parameters do
           string :old_text, description: "the old text (e.g. `puts 'ABC'`)"
           string :new_text, description: "the new text (e.g. `puts 'DEF'`)"
           string :path, description: "a path (e.g. `./main.rb`)"

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

@@ -9,11 +9,11 @@ module SharedTools
       #    tool = SharedTools::Tools::Disk::FileWriteTool.new(root: "./project")
       #    tool.execute(path: "./README.md", text: "Hello World")
       class FileWriteTool < ::RubyLLM::Tool
-        def self.name = 'disk_file_write'
+        def self.tool_name = 'disk_file_write'
 
         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

@@ -13,7 +13,7 @@ module SharedTools
     #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_READ, path: "./demo.rb")
     #   disk.execute(action: SharedTools::Tools::DiskTool::Action::FILE_DELETE, path: "./demo.rb")
     class DiskTool < ::RubyLLM::Tool
-      def self.name = 'disk_tool' 
+      def self.tool_name = 'disk'
       description <<~TEXT
         A tool for interacting with a system. It is able to list, create, delete, move and modify directories and files.
       TEXT
@@ -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

@@ -20,7 +20,7 @@ module SharedTools
     #   tool.execute(action: 'whois',       host: 'github.com')
     #   tool.execute(action: 'whois',       host: '8.8.8.8')
     class DnsTool < ::RubyLLM::Tool
-      def self.name = 'dns_tool'
+      def self.tool_name = 'dns'
 
       description <<~DESC
         Perform DNS lookups, reverse lookups, record queries, external IP detection,
@@ -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

@@ -16,11 +16,11 @@ module SharedTools
       #   tool.execute(doc_path: "./report.docx")
       #   tool.execute(doc_path: "./report.docx", paragraph_range: "1-10")
       class DocxReaderTool < ::RubyLLM::Tool
-        def self.name = 'doc_docx_read'
+        def self.tool_name = 'doc_docx_read'
 
         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

@@ -14,11 +14,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Doc::PdfReaderTool.new
       #   tool.execute(doc_path: "./document.pdf", page_numbers: "1, 5, 10")
       class PdfReaderTool < ::RubyLLM::Tool
-        def self.name = 'doc_pdf_read'
+        def self.tool_name = 'doc_pdf_read'
 
         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

@@ -21,13 +21,13 @@ module SharedTools
       # @example Read a row range from a worksheet
       #   tool.execute(doc_path: "./report.xlsx", sheet: "Summary", row_range: "2-50")
       class SpreadsheetReaderTool < ::RubyLLM::Tool
-        def self.name = 'doc_spreadsheet_read'
+        def self.tool_name = 'doc_spreadsheet_read'
 
         description "Read tabular data from spreadsheet files (CSV, XLSX, ODS, and other formats)."
 
         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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Doc::TextReaderTool.new
       #   tool.execute(doc_path: "./guide.txt")
       class TextReaderTool < ::RubyLLM::Tool
-        def self.name = 'doc_text_read'
+        def self.tool_name = 'doc_text_read'
 
         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

@@ -6,7 +6,7 @@ module SharedTools
   module Tools
     # A tool for reading and processing documents
     class DocTool < ::RubyLLM::Tool
-      def self.name = 'doc_tool'
+      def self.tool_name = 'doc'
 
       module Action
         PDF_READ         = "pdf_read"
@@ -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

@@ -9,11 +9,11 @@ module SharedTools
       #   tool = SharedTools::Tools::Docker::ComposeRunTool.new
       #   tool.execute(service: "app", command: "rspec", args: ["spec/main_spec.rb"])
       class ComposeRunTool < ::RubyLLM::Tool
-        def self.name = 'docker_compose_run'
+        def self.tool_name = 'docker_compose_run'
 
         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.tool_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

@@ -22,7 +22,7 @@ module SharedTools
     class ResourceNotFoundError < StandardError; end
 
     class ErrorHandlingTool < RubyLLM::Tool
-      def self.name = 'error_handling_tool'
+      def self.tool_name = 'error_handling'
 
       description <<~'DESCRIPTION'
         Reference tool demonstrating comprehensive error handling patterns and resilience strategies
@@ -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

@@ -8,7 +8,7 @@ module SharedTools
       #   tool = SharedTools::Tools::Eval::PythonEvalTool.new
       #   tool.execute(code: "print('Hello'); result = 2 + 2")
       class PythonEvalTool < ::RubyLLM::Tool
-        def self.name = 'eval_python'
+        def self.tool_name = 'eval_python'
 
         description <<~DESCRIPTION
                       Execute Python source code safely and return the result.
@@ -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

@@ -9,7 +9,7 @@ module SharedTools
       #   tool = SharedTools::Tools::Eval::RubyEvalTool.new
       #   tool.execute(code: "puts 'Hello'; 2 + 2")
       class RubyEvalTool < ::RubyLLM::Tool
-        def self.name = 'eval_ruby'
+        def self.tool_name = 'eval_ruby'
 
         description <<~DESCRIPTION
                       Execute Ruby source code safely and return the result.
@@ -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

@@ -13,11 +13,11 @@ module SharedTools
         STDOUT_MAX = 5000
         STDERR_MAX = 2000
 
-        def self.name = 'eval_shell'
+        def self.tool_name = 'eval_shell'
 
         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

@@ -6,7 +6,7 @@ module SharedTools
   module Tools
     # A tool for evaluating code in different programming languages
     class EvalTool < ::RubyLLM::Tool
-      def self.name = 'eval_tool'
+      def self.tool_name = 'eval'
 
       module Action
         RUBY = "ruby"
@@ -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