shared_tools 0.4.4 → 0.6.0

data/lib/shared_tools/tools/glob_tool.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Finds files matching a glob pattern within a directory and returns
+    # their paths relative to the glob base, sorted. Each hit is re-checked
+    # against the base so a symlinked match that points outside it is
+    # dropped. Read-only, in-process — no authorization prompt required.
+    #
+    # @example
+    #   tool = SharedTools::Tools::GlobTool.new
+    #   tool.execute(pattern: "**/*.rb")
+    #   tool.execute(pattern: "*.rb", base: "app/models")
+    class GlobTool < ::RubyLLM::Tool
+      MAX_RESULTS = 1_000
+
+      def self.name = 'glob'
+
+      description "Find files matching a glob pattern within a directory (e.g. '**/*.rb', " \
+                  "'app/models/*.rb'). Returns matching paths, sorted, relative to base."
+
+      parameters do
+        string :pattern, description: "Glob pattern such as '**/*.rb', evaluated relative to base."
+        string :base,    description: "Directory to glob from. Defaults to the current directory.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param pattern [String]
+      # @param base [String]
+      #
+      # @return [String, Hash]
+      def execute(pattern:, base: ".")
+        @logger.info("#{self.class.name}#execute pattern=#{pattern.inspect} base=#{base.inspect}")
+
+        return { error: "pattern must be provided" } if pattern.to_s.empty?
+        return { error: "pattern may not contain '..'" } if pattern.include?("..")
+
+        return { error: "not a directory: #{base}" } unless File.directory?(File.expand_path(base))
+
+        root = File.realpath(File.expand_path(base))
+
+        base_pn = Pathname.new(root)
+        results = Dir.glob(File.join(root, pattern), File::FNM_PATHNAME).sort.filter_map do |match|
+          in_base?(root, match) ? Pathname.new(match).relative_path_from(base_pn).to_s : nil
+        end
+
+        capped = results.first(MAX_RESULTS)
+        body = +"#{results.size} match#{results.size == 1 ? '' : 'es'}"
+        body << " (showing first #{MAX_RESULTS})" if results.size > MAX_RESULTS
+        body << " for #{pattern}:\n"
+        capped.each { |rel| body << rel << "\n" }
+        body
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def in_base?(root, match)
+        real = File.realpath(match)
+        (real == root || real.start_with?(root + File::SEPARATOR)) && File.exist?(match)
+      rescue Errno::ENOENT
+        false
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/http_helpers.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require_relative "../../shared_tools"
+require_relative "../url_guard"
+
+module SharedTools
+  module Tools
+    # Shared guarded-HTTP behavior for WebFetchTool, HttpRequestTool, and
+    # DownloadFileTool. Every request URL and every redirect hop passes
+    # through UrlGuard, and the socket is pinned to the vetted IP so a second
+    # DNS lookup can't redirect to an internal address. SSRF protection is
+    # always on — there is no bypass.
+    module HttpHelpers
+      HTTP_TIMEOUT = 10
+      MAX_REDIRECTS = 5
+      MAX_FETCH_BYTES = 5 * 1024 * 1024
+      USER_AGENT = "SharedTools/#{SharedTools::VERSION} (+https://github.com/madbomber/shared_tools)"
+
+      Response = Struct.new(:status, :headers, :body, :final_url, keyword_init: true)
+
+      class FetchError < StandardError; end
+
+      def url_guard
+        SharedTools::UrlGuard.new(allowlist: @web_allowlist || [], denylist: @web_denylist || [])
+      end
+
+      # GET with redirect following and a body-size cap. Each hop is
+      # re-guarded and re-pinned.
+      def guarded_get(url)
+        checker = url_guard
+        current = url
+        seen = 0
+
+        loop do
+          resolution = checker.resolve!(current)
+          response, body = perform(resolution.uri, "GET", nil, nil, resolution.address)
+
+          if redirect?(response)
+            location = response["location"]
+            raise FetchError, "redirect with no Location header (status #{response.code})" unless location
+            raise FetchError, "too many redirects (max #{MAX_REDIRECTS})" if seen >= MAX_REDIRECTS
+
+            seen += 1
+            current = URI.join(resolution.uri.to_s, location).to_s
+            next
+          end
+
+          return Response.new(status: response.code.to_i, headers: response.to_hash,
+                              body: body, final_url: resolution.uri.to_s)
+        end
+      rescue SharedTools::UrlGuard::Blocked
+        raise
+      rescue StandardError => e
+        raise FetchError, e.message
+      end
+
+      # A single request with an explicit method/headers/body (no redirect
+      # following). Used by HttpRequestTool.
+      def guarded_request(method, url, headers: {}, body: nil)
+        resolution = url_guard.resolve!(url)
+        response, raw = perform(resolution.uri, method.to_s.upcase, headers, body, resolution.address)
+        Response.new(status: response.code.to_i, headers: response.to_hash, body: raw, final_url: resolution.uri.to_s)
+      rescue SharedTools::UrlGuard::Blocked
+        raise
+      rescue StandardError => e
+        raise FetchError, e.message
+      end
+
+      private
+
+      def redirect?(response)
+        response.is_a?(Net::HTTPRedirection)
+      end
+
+      def perform(uri, method, headers, body, pin)
+        request = build_request(uri, method, headers, body)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.ipaddr = pin if pin # pin to the vetted address (closes DNS rebinding)
+        http.open_timeout = HTTP_TIMEOUT
+        http.read_timeout = HTTP_TIMEOUT
+
+        captured = +""
+        response = http.start do |conn|
+          conn.request(request) do |res|
+            unless res.is_a?(Net::HTTPRedirection)
+              res.read_body do |chunk|
+                captured << chunk
+                break if captured.bytesize >= MAX_FETCH_BYTES
+              end
+            end
+            res
+          end
+        end
+
+        [response, captured]
+      end
+
+      def build_request(uri, method, headers, body)
+        klass = begin
+          Net::HTTP.const_get(method.capitalize)
+        rescue NameError
+          nil
+        end
+        raise FetchError, "unsupported HTTP method: #{method}" unless klass && klass <= Net::HTTPRequest
+
+        request = klass.new(uri)
+        request["User-Agent"] = USER_AGENT
+        request["Accept"] ||= "*/*"
+        Array(headers).each { |k, v| request[k.to_s] = v.to_s } if headers
+        request.body = body.to_s if body && !body.to_s.empty?
+        request
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/http_request_tool.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "http_helpers"
+
+module SharedTools
+  module Tools
+    # A general HTTP client, UrlGuard-protected. Read methods (GET/HEAD) work
+    # by default; mutating methods (POST/PUT/PATCH/DELETE) require user
+    # authorization (see SharedTools.execute?), so the safe default can't
+    # change remote state. Returns status, key headers, and the body.
+    #
+    # @example
+    #   tool = SharedTools::Tools::HttpRequestTool.new
+    #   tool.execute(url: "https://api.example.com/status")
+    #   tool.execute(url: "https://api.example.com/items", method: "POST", body: '{"name":"x"}')
+    class HttpRequestTool < ::RubyLLM::Tool
+      include HttpHelpers
+
+      READ_METHODS = %w[GET HEAD].freeze
+      MUTATING_METHODS = %w[POST PUT PATCH DELETE].freeze
+      SHOWN_HEADERS = %w[content-type content-length location etag last-modified].freeze
+
+      def self.name = 'http_request'
+
+      description "Make an HTTP request to an http/https URL and return the status, headers, and " \
+                  "body. GET and HEAD are available by default; POST/PUT/PATCH/DELETE require user " \
+                  "authorization. Cannot reach private, loopback, or cloud-metadata addresses."
+
+      parameters do
+        string :url,     description: "The http/https URL to request."
+        string :method,  description: "HTTP method: GET (default), HEAD, POST, PUT, PATCH, DELETE.", required: false
+        object :headers, description: "Optional request headers as a JSON object of name/value strings.", required: false do
+          additional_properties true
+        end
+        string :body,    description: "Optional request body (for POST/PUT/PATCH).", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param url [String]
+      # @param method [String]
+      # @param headers [Hash, nil]
+      # @param body [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(url:, method: "GET", headers: nil, body: nil)
+        @logger.info("#{self.class.name}#execute url=#{url.inspect} method=#{method}")
+
+        verb = method.to_s.strip.upcase
+        verb = "GET" if verb.empty?
+        return { error: "unsupported method: #{verb}" } unless (READ_METHODS + MUTATING_METHODS).include?(verb)
+
+        if MUTATING_METHODS.include?(verb)
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "#{verb} #{url}")
+          unless allowed
+            @logger.warn("User declined #{verb} #{url}")
+            return { error: "User declined the request" }
+          end
+        end
+
+        response = guarded_request(verb, url, headers: headers, body: body)
+        return { error: "HTTP #{response.status} from #{response.final_url}" } if response.status >= 400
+
+        format_response(verb, response)
+      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} request failed: #{e.message}")
+        { error: "request failed: #{e.message}" }
+      end
+
+      private
+
+      def format_response(verb, response)
+        lines = ["#{verb} #{response.final_url} -> #{response.status}"]
+        SHOWN_HEADERS.each do |name|
+          value = Array(response.headers[name]).first
+          lines << "#{name}: #{value}" if value
+        end
+        body = response.body.to_s.scrub
+        lines << "\n--- body ---\n#{body}" unless body.empty?
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/json_query_tool.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Parses JSON (from a file or an inline string) and either pretty-prints
+    # it or extracts a value with a dot/bracket path. In-process, read-only.
+    #
+    # Path syntax: dot-separated keys, [n] for array indices, and [] to map a
+    # field across an array. Examples:
+    #   users[0].name        users[].email        config.server.port
+    #
+    # @example
+    #   tool = SharedTools::Tools::JsonQueryTool.new
+    #   tool.execute(path: "./config.json", query: "servers[0].host")
+    #   tool.execute(json: '{"a":{"b":1}}', query: "a.b")
+    class JsonQueryTool < ::RubyLLM::Tool
+      MAX_BYTES = 5 * 1024 * 1024
+
+      def self.name = 'json_query'
+
+      description "Query JSON with a path expression, or pretty-print it. Provide either a file " \
+                  "path or an inline json string. Path syntax: keys separated by dots, [n] for " \
+                  "array index, [] to map over an array (e.g. users[].name)."
+
+      parameters do
+        string :path,  description: "JSON file to read. Provide this or json.", required: false
+        string :json,  description: "Inline JSON string. Provide this or path.", required: false
+        string :query, description: "Path expression to extract, e.g. 'users[0].name'. Omit to pretty-print. Optional.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String, nil]
+      # @param json [String, nil]
+      # @param query [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, json: nil, query: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} query=#{query.inspect}")
+
+        source = load_source(path, json)
+        return source if source.is_a?(Hash) # error
+
+        data = JSON.parse(source)
+        result = query.to_s.strip.empty? ? data : SharedTools::DataPath.query(data, query)
+        JSON.pretty_generate(result)
+      rescue JSON::ParserError => e
+        @logger.error("#{self.class.name} invalid JSON: #{e.message}")
+        { error: "invalid JSON: #{e.message}" }
+      rescue SharedTools::DataPath::Error => e
+        @logger.error("#{self.class.name} bad query: #{e.message}")
+        { error: e.message }
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def load_source(path, json)
+        if path && !path.to_s.empty?
+          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
+
+          File.read(path).scrub
+        elsif json && !json.to_s.empty?
+          json.to_s
+        else
+          { error: "provide either path or json" }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/lint_tool.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "toolchain_helpers"
+
+module SharedTools
+  module Tools
+    # Runs RuboCop or Standard over a project. Offenses are a normal result,
+    # not a tool error. With autocorrect, the linter rewrites files in place,
+    # so this requires user authorization (see SharedTools.execute?) even
+    # without autocorrect, since it executes an external command.
+    #
+    # @example
+    #   tool = SharedTools::Tools::LintTool.new(root: "./my-project")
+    #   tool.execute
+    #   tool.execute(path: "lib/foo.rb", autocorrect: true)
+    class LintTool < ::RubyLLM::Tool
+      include ToolchainHelpers
+
+      LINTERS = %w[rubocop standard].freeze
+      DEFAULT_TIMEOUT = 120
+
+      def self.name = 'lint'
+
+      description "Lint a project with RuboCop or Standard. Auto-detects (Standard if .standard.yml " \
+                  "is present, else RuboCop) or set linter explicitly. Optionally scope to a path and " \
+                  "apply safe autocorrections. Uses `bundle exec` when a Gemfile exists."
+
+      parameters do
+        string  :path,        description: "Limit linting to this path, relative to root. Optional.", required: false
+        string  :linter,      description: "Force the linter: rubocop or standard. Default: auto-detect.", required: false
+        boolean :autocorrect, description: "Apply safe autocorrections, rewriting files in place. Default false.", 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 path [String, nil]
+      # @param linter [String, nil]
+      # @param autocorrect [Boolean]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, linter: nil, autocorrect: false)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} linter=#{linter.inspect} autocorrect=#{autocorrect}")
+
+        tool = (linter || detect_linter).to_s
+        return { error: "unknown linter: #{tool} (use #{LINTERS.join(', ')})" } unless LINTERS.include?(tool)
+
+        rel = jail_relative(path)
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Lint#{autocorrect ? ' with autocorrect' : ''}: #{tool}#{rel ? " #{rel}" : ''}")
+        unless allowed
+          @logger.warn("User declined to lint")
+          return { error: "User declined to lint" }
+        end
+
+        out, err, status = run_in_project(build_args(tool, rel, autocorrect), use_bundle: true, timeout: DEFAULT_TIMEOUT)
+        toolchain_output(out, err, status,
+                         pass_label: "LINT CLEAN",
+                         fail_label: autocorrect ? "LINT: offenses found (autocorrected where possible)" : "LINT: offenses found",
+                         timeout: DEFAULT_TIMEOUT)
+      rescue SecurityError => e
+        @logger.error("#{self.class.name} path denied: #{e.message}")
+        { error: e.message }
+      rescue CommandMissing => e
+        @logger.error("#{self.class.name}: #{e.message} is not available")
+        { error: "#{e.message} is not available (is it in the bundle / installed?)" }
+      end
+
+      private
+
+      def detect_linter
+        File.exist?(File.join(@root, ".standard.yml")) ? "standard" : "rubocop"
+      end
+
+      def build_args(tool, rel, autocorrect)
+        if tool == "standard"
+          args = ["standardrb"]
+          args << "--fix" if autocorrect
+        else
+          args = ["rubocop", "--no-color"]
+          args << "--autocorrect" if autocorrect
+        end
+        args << rel if rel
+        args
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/multi_edit_tool.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Applies several string replacements to one file in a single, atomic
+    # operation. Edits are applied in order (a later edit sees the result of
+    # earlier ones); each edit's old_string must match exactly once unless
+    # replace_all is set. If any edit can't be applied, nothing is written and
+    # the failing edit is reported — so the file is never left half-edited.
+    # Mutating — requires user authorization (see SharedTools.execute?).
+    #
+    # @example
+    #   tool = SharedTools::Tools::MultiEditTool.new
+    #   tool.execute(path: "./lib/foo.rb", edits: [
+    #     { old_string: "def bar", new_string: "def baz" },
+    #     { old_string: "BAR", new_string: "BAZ", replace_all: true }
+    #   ])
+    class MultiEditTool < ::RubyLLM::Tool
+      class BadEdit < StandardError; end
+
+      MAX_BYTES = 10 * 1024 * 1024
+
+      def self.name = 'multi_edit'
+
+      description "Apply multiple find/replace edits to a single file atomically. Provide edits as " \
+                  "an array of objects with old_string, new_string, and optional replace_all. Edits " \
+                  "run in order; if any fails to apply cleanly, no changes are written."
+
+      parameters do
+        string :path, description: "File to edit, relative to root."
+        array  :edits, description: "Array of edits, applied in order." do
+          object do
+            string  :old_string,  description: "Exact text to replace. Include surrounding lines so it's unique."
+            string  :new_string,  description: "Replacement text."
+            boolean :replace_all, description: "Replace every occurrence instead of requiring a unique match. Default false.", required: false
+          end
+        end
+      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 path [String]
+      # @param edits [Array<Hash>]
+      #
+      # @return [String, Hash]
+      def execute(path:, edits:)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} edits=#{Array(edits).size}")
+
+        return { error: "edits must be a non-empty array" } unless edits.is_a?(Array) && !edits.empty?
+
+        real = resolve!(path)
+        return { error: "not a file: #{path}" } unless File.file?(real)
+        return { error: "file too large (> #{MAX_BYTES} bytes)" } if File.size(real) > MAX_BYTES
+
+        original = File.read(real).scrub
+        content = original
+        total = 0
+
+        edits.each_with_index do |edit, i|
+          content, n = apply_edit(content, edit, i + 1, path)
+          total += n
+        end
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Apply #{edits.size} edit(s) to #{path}")
+        unless allowed
+          @logger.warn("User declined to edit #{path}")
+          return { error: "User declined to edit #{path}" }
+        end
+
+        File.write(real, content)
+        "Applied #{edits.size} edit#{edits.size == 1 ? '' : 's'} to #{path} " \
+          "(#{total} replacement#{total == 1 ? '' : 's'}, #{original.bytesize} -> #{content.bytesize} bytes)"
+      rescue SecurityError => e
+        @logger.error("#{self.class.name} path denied: #{e.message}")
+        { error: e.message }
+      rescue BadEdit => e
+        @logger.error("#{self.class.name} bad edit: #{e.message}")
+        { error: e.message }
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def apply_edit(content, edit, index, path)
+        edit = normalize_edit(edit)
+        old_s = edit["old_string"].to_s
+        new_s = edit["new_string"].to_s
+        replace_all = [true, "true"].include?(edit["replace_all"])
+
+        raise BadEdit, "edit #{index}: old_string must not be empty" if old_s.empty?
+        raise BadEdit, "edit #{index}: old_string and new_string are identical" if old_s == new_s
+
+        if replace_all
+          count = 0
+          updated = content.gsub(old_s) { count += 1; new_s }
+          raise BadEdit, "edit #{index}: old_string not found in #{path}" if count.zero?
+
+          [updated, count]
+        else
+          count = content.scan(Regexp.new(Regexp.escape(old_s))).size
+          raise BadEdit, "edit #{index}: old_string not found in #{path}" if count.zero?
+          if count > 1
+            raise BadEdit, "edit #{index}: old_string is ambiguous (#{count} matches in #{path}); " \
+                           "add surrounding context or set replace_all"
+          end
+
+          [content.sub(old_s) { new_s }, 1]
+        end
+      end
+
+      def normalize_edit(edit)
+        edit.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+
+      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/notification_tool.rb

@@ -26,7 +26,7 @@ module SharedTools
         On Linux uses notify-send, zenity (or terminal fallback), and espeak-ng/espeak.
       DESC
 
-      params do
+      parameters do
         string :action, description: <<~TEXT.strip
           The notification action to perform:
           * `notify` — Non-blocking desktop banner notification.