shared_tools 0.4.2 → 0.6.0

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.

data/lib/shared_tools/tools/parse_ruby_tool.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "pathname"
+require_relative "../../shared_tools"
+require_relative "../ruby_outline"
+
+module SharedTools
+  module Tools
+    # Produces a structural outline of a Ruby file (classes, modules,
+    # methods, constants) with line numbers, or finds where a name is
+    # defined. In-process via Ripper/Prism — it parses, never executes, the
+    # code. Read-only.
+    #
+    # @example
+    #   tool = SharedTools::Tools::ParseRubyTool.new
+    #   tool.execute(path: "./lib/foo.rb")
+    #   tool.execute(path: "./lib/foo.rb", query: "initialize")
+    #   tool.execute(path: "./lib/foo.rb", kind: "method")
+    class ParseRubyTool < ::RubyLLM::Tool
+      KINDS = %w[class module method constant].freeze
+      MAX_BYTES = 5 * 1024 * 1024
+
+      def self.name = 'parse_ruby'
+
+      description "Outline a Ruby file's structure (classes, modules, methods, constants with line " \
+                  "numbers), or locate definitions. Give a query to find definitions whose name " \
+                  "matches, and/or a kind to filter. Parses in-process; does not run the code."
+
+      parameters do
+        string :path,  description: "Ruby file to outline."
+        string :query, description: "Only show definitions whose (qualified) name matches this, case-insensitive. Optional.", required: false
+        string :kind,  description: "Filter to a kind: class, module, method, or constant. Optional.", required: false
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param path [String]
+      # @param query [String, nil]
+      # @param kind [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(path:, query: nil, kind: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} query=#{query.inspect} kind=#{kind.inspect}")
+
+        k = kind.to_s.strip.downcase
+        k = nil if k.empty?
+        return { error: "unknown kind: #{k} (use #{KINDS.join(', ')})" } if k && !KINDS.include?(k)
+
+        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
+
+        entries = SharedTools::RubyOutline.extract(File.read(path).scrub)
+        return "no definitions found in #{path}" if entries.empty?
+
+        render(entries, path, query, k)
+      rescue SharedTools::RubyOutline::ParseError => e
+        @logger.error("#{self.class.name}: #{e.message} in #{path}")
+        { error: "#{e.message} in #{path}" }
+      rescue => e
+        @logger.error("#{self.class.name} failed: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def render(entries, path, query, kind)
+        if query || kind
+          flat_list(entries, path, query, kind)
+        else
+          "Outline of #{path}:\n#{tree(entries)}"
+        end
+      end
+
+      def tree(entries)
+        entries.map { |e| "#{'  ' * e.depth}#{label(e)} (L#{e.line})" }.join("\n")
+      end
+
+      def flat_list(entries, path, query, kind)
+        pairs = qualify(entries)
+        pairs = pairs.select { |e, _| e.kind.to_s == kind } if kind
+        if query
+          q = query.downcase
+          pairs = pairs.select { |e, qn| qn.downcase.include?(q) || e.name.downcase.include?(q) }
+        end
+        return "no matching definitions in #{path}" if pairs.empty?
+
+        desc = ["definitions", ("matching #{query.inspect}" if query), ("of kind #{kind}" if kind)].compact.join(" ")
+        header = "#{pairs.size} #{desc} in #{path}:"
+        "#{header}\n#{pairs.map { |e, qn| "#{qn} (L#{e.line}) [#{e.kind}]" }.join("\n")}"
+      end
+
+      # Pair each entry with its fully-qualified name using the depth stack.
+      def qualify(entries)
+        namespace = []
+        entries.map do |entry|
+          namespace = namespace.first(entry.depth)
+          ns = namespace.compact
+          qualified =
+            case entry.kind
+            when :class, :module, :singleton_class
+              full = (ns + [entry.name]).join("::")
+              namespace[entry.depth] = entry.name
+              full
+            when :method
+              ns.empty? ? entry.name : "#{ns.join('::')}##{entry.name}"
+            else # constant
+              ns.empty? ? entry.name : "#{ns.join('::')}::#{entry.name}"
+            end
+          [entry, qualified]
+        end
+      end
+
+      def label(entry)
+        case entry.kind
+        when :class, :singleton_class then "class #{entry.name}"
+        when :module then "module #{entry.name}"
+        when :method then "def #{entry.name}"
+        else entry.name
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/process_kill_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "../process_registry"
+
+module SharedTools
+  module Tools
+    # Stops a background process: SIGTERM to its process group, escalating
+    # to SIGKILL if it doesn't exit, then returns any final output. Always
+    # available, with no authorization prompt, so a runaway process can
+    # always be stopped. Removes the process from the registry.
+    #
+    # @example
+    #   tool = SharedTools::Tools::ProcessKillTool.new
+    #   tool.execute(id: "proc_1")
+    class ProcessKillTool < ::RubyLLM::Tool
+      def self.name = 'process_kill'
+
+      description "Stop a background process (started with process_start) and return any final " \
+                  "output. Terminates the whole process group, escalating to SIGKILL if needed."
+
+      parameters do
+        string :id, description: "The process id to kill (e.g. 'proc_1')."
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param id [String]
+      #
+      # @return [String, Hash]
+      def execute(id:)
+        @logger.info("#{self.class.name}#execute id=#{id.inspect}")
+
+        proc = SharedTools::ProcessRegistry.get(id)
+        return { error: "no such process: #{id}" } unless proc
+
+        was_running = proc.running?
+        proc.kill
+        final = proc.read_new
+        SharedTools::ProcessRegistry.delete(id)
+
+        body = +"#{id} #{was_running ? 'terminated' : 'was already exited'}"
+        body << " (exit #{proc.exit_code})" if proc.exit_code
+        unless final[:out].empty? && final[:err].empty?
+          body << "\n--- final stdout ---\n#{final[:out]}" unless final[:out].empty?
+          body << "\n--- final stderr ---\n#{final[:err]}" unless final[:err].empty?
+        end
+        body
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/process_list_tool.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "../process_registry"
+
+module SharedTools
+  module Tools
+    # Lists the background processes started this run (with ProcessStartTool):
+    # id, status, pid, age, and command — so a caller can rediscover ids and
+    # see what's still running. Read-only.
+    #
+    # @example
+    #   tool = SharedTools::Tools::ProcessListTool.new
+    #   tool.execute
+    class ProcessListTool < ::RubyLLM::Tool
+      def self.name = 'process_list'
+
+      description "List background processes (started with process_start): id, status, pid, age, and " \
+                  "command. Read-only."
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @return [String]
+      def execute
+        @logger.info("#{self.class.name}#execute")
+
+        procs = SharedTools::ProcessRegistry.all
+        return "no background processes" if procs.empty?
+
+        lines = procs.map do |proc|
+          status = proc.status == :exited ? "exited(#{proc.exit_code})" : "running"
+          "#{proc.id}  #{status.ljust(12)}  pid=#{proc.pid}  age=#{proc.age.round}s  #{proc.name}  #{proc.argv.inspect}"
+        end
+        (["#{procs.size} process#{procs.size == 1 ? '' : 'es'}:"] + lines).join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/process_output_tool.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "../process_registry"
+
+module SharedTools
+  module Tools
+    # Returns the output a background process has produced since the last
+    # read, plus its current status (running, or exited with a code). Reads
+    # are incremental, so polling in a loop streams the process's output
+    # without repeats. Read-only.
+    #
+    # @example
+    #   tool = SharedTools::Tools::ProcessOutputTool.new
+    #   tool.execute(id: "proc_1")
+    class ProcessOutputTool < ::RubyLLM::Tool
+      def self.name = 'process_output'
+
+      description "Read new stdout/stderr from a background process (started with process_start) " \
+                  "since the last read, along with its status and exit code if it has finished. Poll " \
+                  "this to follow a process's output."
+
+      parameters do
+        string :id, description: "The process id returned by process_start (e.g. 'proc_1')."
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param id [String]
+      #
+      # @return [String, Hash]
+      def execute(id:)
+        @logger.info("#{self.class.name}#execute id=#{id.inspect}")
+
+        proc = SharedTools::ProcessRegistry.get(id)
+        return { error: "no such process: #{id}" } unless proc
+
+        data = proc.read_new
+        format_output(proc, data)
+      end
+
+      private
+
+      def format_output(proc, data)
+        body = +"#{proc.id} (#{proc.name}): #{proc.status}"
+        body << " (exit #{proc.exit_code})" if proc.status == :exited && proc.exit_code
+        body << "\n"
+
+        if data[:out].empty? && data[:err].empty?
+          body << "(no new output)"
+          return body
+        end
+
+        unless data[:out].empty?
+          body << "\n--- stdout#{data[:out_dropped] ? ' (earlier output dropped)' : ''} ---\n"
+          body << data[:out]
+        end
+        unless data[:err].empty?
+          body << "\n--- stderr#{data[:err_dropped] ? ' (earlier output dropped)' : ''} ---\n"
+          body << data[:err]
+        end
+        body
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/python_tests_tool.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "toolchain_helpers"
+
+module SharedTools
+  module Tools
+    # Runs a Python project's tests (pytest or unittest) from root and
+    # returns the output with a pass/fail headline. A failing suite is a
+    # normal result, not a tool error. Runs in the project environment, so a
+    # virtualenv/installed deps resolve as they would in a shell. Requires
+    # user authorization (see SharedTools.execute?) since it executes an
+    # external command.
+    #
+    # @example
+    #   tool = SharedTools::Tools::PythonTestsTool.new(root: "./my-project")
+    #   tool.execute
+    #   tool.execute(path: "tests/test_models.py", framework: "unittest")
+    class PythonTestsTool < ::RubyLLM::Tool
+      include ToolchainHelpers
+
+      FRAMEWORKS = %w[pytest unittest].freeze
+      DEFAULT_TIMEOUT = 180
+
+      def self.name = 'python_tests'
+
+      description "Run a Python project's test suite from root and report results. Uses pytest by " \
+                  "default, or unittest (python -m unittest discover) when framework is unittest. " \
+                  "Optionally scope to a path."
+
+      parameters do
+        string :path,      description: "Limit the run to this test file or directory, relative to root. Optional.", required: false
+        string :framework, description: "pytest (default) or unittest.", 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 framework [String]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, framework: "pytest")
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} framework=#{framework}")
+
+        fw = framework.to_s.strip.downcase
+        fw = "pytest" if fw.empty?
+        return { error: "unknown framework: #{fw} (use #{FRAMEWORKS.join(', ')})" } unless FRAMEWORKS.include?(fw)
+
+        rel = jail_relative(path)
+
+        allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Run #{fw} tests#{rel ? " (#{rel})" : ''}")
+        unless allowed
+          @logger.warn("User declined to run tests")
+          return { error: "User declined to run tests" }
+        end
+
+        out, err, status = run_in_project(args_for(fw, rel), use_bundle: false, timeout: DEFAULT_TIMEOUT)
+        toolchain_output(out, err, status,
+                         pass_label: summarize(out, err, "TESTS PASSED"),
+                         fail_label: summarize(out, err, "TESTS FAILED"),
+                         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 installed in the project env?)" }
+      end
+
+      private
+
+      def args_for(framework, rel)
+        if framework == "unittest"
+          args = ["python3", "-m", "unittest", "discover"]
+          args += ["-s", rel] if rel
+        else
+          args = ["pytest"]
+          args << rel if rel
+        end
+        args
+      end
+
+      # Surface pytest's or unittest's summary in the headline.
+      def summarize(out, err, label)
+        text = "#{out}\n#{err}"
+        counts = %w[passed failed error skipped].filter_map do |word|
+          m = text.match(/(\d+) #{word}/)
+          "#{m[1]} #{word}" if m
+        end
+        return "#{label} (#{counts.join(', ')})" unless counts.empty?
+
+        if (m = text.match(/Ran (\d+) tests?.*?(OK|FAILED)/m))
+          return "#{label} (ran #{m[1]}, #{m[2]})"
+        end
+
+        label
+      end
+    end
+  end
+end