shared_tools 0.4.2 → 0.6.0

data/lib/shared_tools/tools/bash_tool.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "../process_runner"
+require_relative "../command_guard"
+
+module SharedTools
+  module Tools
+    # Runs ONE allowlisted executable with arguments.
+    #
+    # Deliberately NOT a shell: there are no pipes, redirects, globs,
+    # quoting, or variable expansion. The program goes in `command`; each
+    # argument is a separate element of `args` and is passed verbatim as
+    # argv. This is the safe primitive that the OS-command-injection class of
+    # bug cannot touch, because no shell ever parses the input.
+    #
+    # Requires user authorization (see SharedTools.execute?) AND the
+    # executable being on allowed_commands (empty by default — nothing is
+    # allowed until the caller configures it).
+    #
+    # @example
+    #   tool = SharedTools::Tools::BashTool.new(allowed_commands: ["ls", "cat"])
+    #   tool.execute(command: "ls", args: ["-la"])
+    class BashTool < ::RubyLLM::Tool
+      DEFAULT_TIMEOUT = 30
+
+      def self.name = 'bash'
+
+      description "Run a single ALLOWLISTED executable with arguments. " \
+                  "No shell is involved: no pipes, redirects, globs, or variable expansion. " \
+                  "Put the program name in `command` and each argument as its own element of `args`."
+
+      parameters do
+        string :command, description: "Executable name (must be on the allowlist). No path, no shell characters."
+        array  :args,    of: :string, description: "Arguments passed verbatim to the program, one per element. Optional.", required: false
+      end
+
+      # @param allowed_commands [Array<String>] executables permitted to run. Empty by default (nothing allowed).
+      # @param logger [Logger] optional logger
+      def initialize(allowed_commands: [], logger: nil)
+        @allowed_commands = allowed_commands
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param command [String]
+      # @param args [Array<String>, nil]
+      #
+      # @return [String, Hash]
+      def execute(command:, args: nil)
+        @logger.info("#{self.class.name}#execute command=#{command.inspect} args=#{args.inspect}")
+
+        exe = SharedTools::CommandGuard.new(@allowed_commands).check!(command)
+        argv = sanitize_args(args)
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: ([exe] + argv).join(" "))
+        unless allowed
+          @logger.warn("User declined to run #{([exe] + argv).join(' ')}")
+          return { error: "User declined to run the command" }
+        end
+
+        out, err, status = SharedTools::ProcessRunner.capture(
+          [exe, *argv],
+          env: clean_env,
+          timeout: DEFAULT_TIMEOUT,
+          unsetenv_others: true
+        )
+        format_result(exe, argv, out, err, status)
+      rescue SharedTools::CommandGuard::Blocked => e
+        @logger.error("#{self.class.name} command denied: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def sanitize_args(args)
+        nul = 0.chr
+        Array(args).map do |arg|
+          str = arg.to_s
+          raise SharedTools::CommandGuard::Blocked, "argument contains a NUL byte" if str.include?(nul)
+
+          str
+        end
+      end
+
+      def clean_env
+        {}
+      end
+
+      def format_result(exe, argv, out, err, status)
+        body = +"argv: #{([exe] + argv).inspect}\n"
+        body << if status == :timeout
+                  "result: timed out after #{DEFAULT_TIMEOUT}s (killed)\n"
+                else
+                  "exit: #{status.exitstatus}\n"
+                end
+        body << "\n--- stdout ---\n#{out}" unless out.empty?
+        body << "\n--- stderr ---\n#{err}" unless err.empty?
+        body
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/click_tool.rb

@@ -15,7 +15,7 @@ module SharedTools
 
         description "A browser automation tool for clicking any clickable element."
 
-        params do
+        parameters do
           string :selector, description: <<~TEXT.strip
             A CSS selector to locate or interact with an element on the page:
 

data/lib/shared_tools/tools/browser/inspect_tool.rb

@@ -17,7 +17,7 @@ module SharedTools
 
         description "A browser automation tool for finding UI elements by their text content."
 
-        params do
+        parameters do
           string :text_content, description: "Search for elements containing this text"
           string :selector, description: "Optional CSS selector to further filter results", required: false
           integer :context_size, description: "Number of parent elements to include for context", required: false

data/lib/shared_tools/tools/browser/page_inspect_tool.rb

@@ -17,7 +17,7 @@ module SharedTools
 
         description "A browser automation tool for viewing the full HTML of the current page."
 
-        params do
+        parameters do
           boolean :summarize, description: "If true, returns a summary instead of full HTML", required: false
         end
 

data/lib/shared_tools/tools/browser/page_screenshot_tool.rb

@@ -11,7 +11,7 @@ module SharedTools
 
         description "Take a screenshot of the current browser page and save it to a file."
 
-        params do
+        parameters do
           string :path, required: false,
                         description: "File path to save the screenshot (e.g. 'screenshot.png'). " \
                                      "Defaults to a timestamped name in the current directory."

data/lib/shared_tools/tools/browser/selector_inspect_tool.rb

@@ -17,7 +17,7 @@ module SharedTools
 
         description "A browser automation tool for finding and inspecting elements by CSS selector."
 
-        params do
+        parameters do
           string :selector, description: "CSS selector to target specific elements"
           integer :context_size, description: "Number of parent elements to include for context", required: false
         end

data/lib/shared_tools/tools/browser/text_field_area_set_tool.rb

@@ -12,7 +12,7 @@ module SharedTools
 
         description "A browser automation tool for clicking a specific link."
 
-        params do
+        parameters do
           string :selector, description: "The ID / name of the text field / area to interact with."
           string :text, description: "The text to set."
         end

data/lib/shared_tools/tools/browser/visit_tool.rb

@@ -12,7 +12,7 @@ module SharedTools
 
         description "A browser automation tool for navigating to a specific URL."
 
-        params do
+        parameters do
           string :url, description: "A URL (e.g. https://news.ycombinator.com)."
         end
 

data/lib/shared_tools/tools/browser_tool.rb

@@ -86,7 +86,7 @@ module SharedTools
           {"action": "#{Action::SCREENSHOT}"}
       TEXT
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           The browser action to perform. Options:
           * `#{Action::VISIT}`: Navigate to a website

data/lib/shared_tools/tools/bundle_tool.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "toolchain_helpers"
+
+module SharedTools
+  module Tools
+    # Runs Bundler operations in a project. The mutating sibling of the
+    # read-only GemTool. install/update/add reach the network and change the
+    # project's gems, so this requires user authorization (see
+    # SharedTools.execute?).
+    #
+    # @example
+    #   tool = SharedTools::Tools::BundleTool.new(root: "./my-project")
+    #   tool.execute(action: "install")
+    #   tool.execute(action: "add", gem: "rack")
+    class BundleTool < ::RubyLLM::Tool
+      include ToolchainHelpers
+
+      ACTIONS = %w[install update outdated check lock add].freeze
+      NAME_RE = /\A[A-Za-z0-9_.-]+\z/
+      DEFAULT_TIMEOUT = 180
+
+      def self.name = 'bundle'
+
+      description "Run Bundler in a project. Actions: install, update, outdated, check, lock, add. " \
+                  "For 'add' provide a gem name; for 'update' a gem name is optional (omit to update " \
+                  "all). Requires a Gemfile."
+
+      parameters do
+        string :action, description: "One of: install, update, outdated, check, lock, add."
+        string :gem,    description: "Gem name — required for 'add', optional for 'update'.", required: false
+      end
+
+      # @param root [String] optional, defaults to the current directory
+      # @param logger [Logger] optional logger
+      def initialize(root: nil, logger: nil)
+        @root = root || Dir.pwd
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param action [String]
+      # @param gem [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(action:, gem: nil)
+        @logger.info("#{self.class.name}#execute action=#{action} gem=#{gem.inspect}")
+
+        act = action.to_s.strip.downcase
+        return { error: "unknown action: #{act} (use #{ACTIONS.join(', ')})" } unless ACTIONS.include?(act)
+        return { error: "a Gemfile is required (none at #{@root})" } unless gemfile?
+
+        args = build_args(act, gem)
+        return args if args.is_a?(Hash) # validation error
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: args.join(" "))
+        unless allowed
+          @logger.warn("User declined to run #{args.join(' ')}")
+          return { error: "User declined to run #{args.join(' ')}" }
+        end
+
+        out, err, status = run_in_project(args, use_bundle: false, timeout: DEFAULT_TIMEOUT)
+        toolchain_output(out, err, status,
+                         pass_label: "bundle #{act}: ok",
+                         fail_label: "bundle #{act}: failed",
+                         timeout: DEFAULT_TIMEOUT)
+      rescue CommandMissing
+        @logger.error("#{self.class.name}: bundler is not available")
+        { error: "bundler is not available (gem install bundler)" }
+      end
+
+      private
+
+      def build_args(act, gem_name)
+        case act
+        when "add"
+          name = gem_name.to_s.strip
+          return { error: "'add' requires a valid gem name" } unless name.match?(NAME_RE)
+
+          ["bundle", "add", name]
+        when "update"
+          name = gem_name.to_s.strip
+          if name.empty?
+            ["bundle", "update"]
+          else
+            return { error: "invalid gem name: #{name.inspect}" } unless name.match?(NAME_RE)
+
+            ["bundle", "update", name]
+          end
+        else
+          ["bundle", act]
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/calculator_tool.rb

@@ -1,12 +1,22 @@
 # calculator_tool.rb - Safe mathematical calculator
 require 'ruby_llm/tool'
-require 'dentaku'
+
+DENTAKU_AVAILABLE = begin
+  require 'dentaku'
+  true
+rescue LoadError, Gem::LoadError
+  false
+end
 
 module SharedTools
   module Tools
     class CalculatorTool < RubyLLM::Tool
       def self.name = 'calculator'
 
+      def available?
+        DENTAKU_AVAILABLE
+      end
+
       description <<~'DESCRIPTION'
         Perform advanced mathematical calculations with comprehensive error handling and validation.
         This tool supports basic arithmetic operations, parentheses, and common mathematical functions.
@@ -34,7 +44,7 @@ module SharedTools
           puts "Result: #{result[:result]}" # 3.3333
       DESCRIPTION
 
-      params do
+      parameters do
         string :expression, description: <<~DESC.strip
           Mathematical expression to evaluate using standard arithmetic operators and parentheses.
           Supported operations include: addition (+), subtraction (-), multiplication (*),

data/lib/shared_tools/tools/clipboard_tool.rb

@@ -25,7 +25,7 @@ module SharedTools
         - 'clear' — Empty the clipboard
       DESC
 
-      params do
+      parameters do
         string :action, description: "Action to perform: 'read', 'write', or 'clear'"
         string :text, required: false, description: "Text to write. Required only for the 'write' action."
       end

data/lib/shared_tools/tools/composite_analysis_tool.rb

@@ -17,7 +17,7 @@ module SharedTools
         from initial data loading through final insights. Handles CSV, JSON, and text data formats.
       DESCRIPTION
 
-      params do
+      parameters do
         string :data_source, description: <<~DESC.strip, required: false
           Primary data source to analyze. Can be either a local file path or a web URL.
           For files: Use relative or absolute paths to CSV, JSON, XML, or text files.

data/lib/shared_tools/tools/computer_tool.rb

@@ -70,7 +70,7 @@ module SharedTools
         ScrollDirection::RIGHT,
       ].freeze
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           Options:
           * `#{Action::KEY}`: Press a single key / combination of keys on the keyboard:

data/lib/shared_tools/tools/cron_tool.rb

@@ -33,7 +33,7 @@ module SharedTools
                            'every weekday', 'first day of every month at midnight'
       DESC
 
-      params do
+      parameters do
         string  :action,      description: "Action: 'parse', 'validate', 'next_times', 'generate'"
         string  :expression,  required: false, description: "5-field cron expression. Required for parse, validate, next_times."
         integer :count,       required: false, description: "Number of next execution times. Default: 5."

data/lib/shared_tools/tools/csv_read_tool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'csv'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Reads a CSV file and returns its rows in a compact, readable form.
+    # Read-only.
+    #
+    # @example
+    #   tool = SharedTools::Tools::CsvReadTool.new
+    #   tool.execute(path: "./sales.csv")
+    #   tool.execute(path: "./sales.csv", headers: false, limit: 10)
+    class CsvReadTool < ::RubyLLM::Tool
+      MAX_BYTES = 10 * 1024 * 1024
+      DEFAULT_LIMIT = 100
+
+      def self.name = 'csv_read'
+
+      description "Read a CSV file and return its rows. By default the first row is treated as a " \
+                  "header. Use limit to cap the number of data rows returned."
+
+      parameters do
+        string  :path,    description: "CSV file to read."
+        boolean :headers, description: "Treat the first row as column headers. Default true.", required: false
+        integer :limit,   description: "Maximum number of data rows to return (default #{DEFAULT_LIMIT}).", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String]
+      # @param headers [Boolean]
+      # @param limit [Integer]
+      #
+      # @return [String, Hash]
+      def execute(path:, headers: true, limit: DEFAULT_LIMIT)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} headers=#{headers} limit=#{limit}")
+
+        return { error: "file not found: #{path}" } unless File.exist?(path)
+        return { error: "not a file: #{path}" } unless File.file?(path)
+        return { error: "file too large (> #{MAX_BYTES} bytes)" } if File.size(path) > MAX_BYTES
+
+        rows = CSV.read(path)
+        return "empty CSV" if rows.empty?
+
+        max = limit.to_i
+        max = DEFAULT_LIMIT if max <= 0
+        render(rows, headers, max)
+      rescue CSV::MalformedCSVError => e
+        @logger.error("#{self.class.name} malformed CSV: #{e.message}")
+        { error: "malformed CSV: #{e.message}" }
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def render(rows, headers, max)
+        header = headers ? rows.first : nil
+        data = headers ? rows[1..] : rows
+        shown = data.first(max)
+
+        lines = []
+        lines << "columns: #{header.join(' | ')}" if header
+        lines << "#{data.size} row#{data.size == 1 ? '' : 's'}#{data.size > max ? " (showing #{max})" : ''}"
+        shown.each_with_index do |row, i|
+          lines << if header
+                     "#{i + 1}. " + header.zip(row).map { |k, v| "#{k}=#{v}" }.join(", ")
+                   else
+                     "#{i + 1}. " + row.join(" | ")
+                   end
+        end
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/csv_write_tool.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'csv'
+require 'fileutils'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Writes rows to a CSV file. Optional header row. Missing parent
+    # directories are created. Overwrites an existing file. Mutating —
+    # requires user authorization (see SharedTools.execute?).
+    #
+    # @example
+    #   tool = SharedTools::Tools::CsvWriteTool.new
+    #   tool.execute(path: "./out.csv", headers: ["name", "age"], rows: [["Alice", 30]])
+    class CsvWriteTool < ::RubyLLM::Tool
+      def self.name = 'csv_write'
+
+      description "Write rows to a CSV file. Provide rows as an array of arrays (each inner array " \
+                  "is a row of cell values, written as strings), with an optional headers array " \
+                  "written as the first line. Overwrites an existing file."
+
+      parameters do
+        string :path, description: "Destination CSV path."
+        array  :rows, description: "Array of rows; each row is an array of cell values (as strings)." do
+          array of: :string
+        end
+        array :headers, of: :string, description: "Optional column header row, written first.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String]
+      # @param rows [Array<Array>]
+      # @param headers [Array<String>, nil]
+      #
+      # @return [String, Hash]
+      def execute(path:, rows:, headers: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} rows=#{Array(rows).size}")
+
+        return { error: "rows must be an array of arrays" } unless rows.is_a?(Array)
+        return { error: "path is a directory: #{path}" } if File.directory?(path)
+
+        all = []
+        all << Array(headers) if headers && !Array(headers).empty?
+        rows.each { |row| all << Array(row) }
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Write #{rows.size} row(s) to #{path}")
+        unless allowed
+          @logger.warn("User declined to write CSV to #{path}")
+          return { error: "User declined to write the CSV file" }
+        end
+
+        FileUtils.mkdir_p(File.dirname(path))
+        CSV.open(path, "w") { |csv| all.each { |row| csv << row } }
+
+        "Wrote #{rows.size} row#{rows.size == 1 ? '' : 's'} to #{path}"
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/current_date_time_tool.rb

@@ -24,7 +24,7 @@ module SharedTools
         - 'iso8601' — iso8601, iso8601_utc, unix_timestamp
       DESC
 
-      params do
+      parameters do
         string :format, required: false, description: <<~DESC.strip
           Output format. Options: 'full' (default), 'date', 'time', 'iso8601'.
         DESC

data/lib/shared_tools/tools/data_science_kit.rb

@@ -17,7 +17,7 @@ module SharedTools
         recommendations and statistical significance testing where applicable.
       DESCRIPTION
 
-      params do
+      parameters do
         string :analysis_type, description: <<~DESC.strip, required: true
           Type of data science analysis to perform:
           - 'statistical_summary': Descriptive statistics, distributions, outlier detection

data/lib/shared_tools/tools/database_query_tool.rb

@@ -1,12 +1,22 @@
 # database_query_tool.rb - Safe database query execution
 require 'ruby_llm/tool'
-require 'sequel'
+
+SEQUEL_AVAILABLE = begin
+  require 'sequel'
+  true
+rescue LoadError, Gem::LoadError
+  false
+end
 
 module SharedTools
   module Tools
     class DatabaseQueryTool < RubyLLM::Tool
       def self.name = 'database_query'
 
+      def available?
+        SEQUEL_AVAILABLE
+      end
+
       description <<~'DESCRIPTION'
         Execute safe, read-only database queries with automatic connection management and security controls.
         This tool is designed for secure data retrieval operations only, restricting access to SELECT statements
@@ -31,7 +41,7 @@ module SharedTools
           puts "Found #{result[:row_count]} users"
       DESCRIPTION
 
-      params do
+      parameters do
         string :query, description: <<~DESC.strip
           SQL SELECT query to execute against the database. Only SELECT statements are permitted
           for security reasons - INSERT, UPDATE, DELETE, and DDL statements will be rejected.

data/lib/shared_tools/tools/database_tool.rb

@@ -57,7 +57,7 @@ module SharedTools
             ]
       TEXT
 
-      params do
+      parameters do
         array :statements, of: :string, description: "A list of SQL statements to run sequentially (e.g. ['SELECT * FROM users', 'INSERT INTO ...'])"
       end
 

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

@@ -13,7 +13,7 @@ module SharedTools
 
         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

@@ -13,7 +13,7 @@ module SharedTools
 
         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

@@ -13,7 +13,7 @@ module SharedTools
 
         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

@@ -13,7 +13,7 @@ module SharedTools
 
         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

@@ -13,7 +13,7 @@ module SharedTools
 
         description "Creates a file."
 
-        params do
+        parameters do
           string :path, description: "a path to the file (e.g. `./README.md`)"
         end