ruby_llm-toolbox 0.1.0

data/lib/ruby_llm/toolbox/tools/git_blame.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Shows line-by-line authorship (commit, author, date) for a file in
+      # the repo at fs_root. Read-only.
+      class GitBlame < Base
+        include GitHelpers
+
+        description "Show git blame for a file in the repo at fs_root: which commit, author, and date " \
+                    "last touched each line. Optionally limit to a line range. Read-only."
+
+        param :path, type: "string",
+                     desc: "File to blame, relative to fs_root.",
+                     required: true
+        param :start_line, type: "integer",
+                          desc: "First line of the range to blame. Optional.",
+                          required: false
+        param :end_line, type: "integer",
+                        desc: "Last line of the range to blame. Optional.",
+                        required: false
+
+        def execute(path:, start_line: nil, end_line: nil)
+          rel = repo_relative(path)
+          return error("path must be provided", code: :bad_path) 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)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result.strip.empty? ? "no blame output (empty file?)" : result)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        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/ruby_llm/toolbox/tools/git_branch.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Lists the branches of the repo at fs_root, with the current branch
+      # marked and each branch's latest commit. Read-only; does not create,
+      # switch, or delete branches (git_checkout handles switching/creating).
+      class GitBranch < Base
+        include GitHelpers
+
+        description "List the branches of the repo at fs_root, with the current branch marked (*) and " \
+                    "each branch's tip commit. Set all true to include remote-tracking branches. Read-only."
+
+        param :all, type: "boolean",
+                    desc: "Include remote-tracking branches. Default false (local only).",
+                    required: false
+
+        def execute(all: false)
+          args = ["branch", "--no-color", "-vv"]
+          args << "-a" if all
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result.strip.empty? ? "no branches yet (no commits?)" : result)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_checkout.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Switches branches or creates a new branch in the repo at fs_root.
+      # The ref is validated (no leading dash, ref-safe characters only) so it
+      # can't smuggle git options.
+      class GitCheckout < Base
+        include GitHelpers
+        exec_tool!
+
+        description "Switch to a branch/commit in the repository at fs_root, or create a new branch " \
+                    "with create: true. Note this can change the working tree."
+
+        param :ref, type: "string",
+                    desc: "Branch, tag, or commit to switch to (or the new branch name when create is true).",
+                    required: true
+        param :create, type: "boolean",
+                      desc: "Create a new branch named ref before switching to it (git checkout -b). Default false.",
+                      required: false
+
+        def execute(ref:, create: false)
+          return error("invalid ref: #{ref.inspect}", code: :bad_ref) unless valid_ref?(ref)
+
+          args = ["checkout"]
+          args << "-b" if create
+          args << ref
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          # git prints checkout feedback to stderr on success.
+          truncate([out, err].map(&:strip).reject(&:empty?).join("\n"))
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_commit.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # EXEC. Commits staged changes in the repo at fs_root. The message is
+      # passed as a single argv element (-m), so it is never parsed by a shell.
+      class GitCommit < Base
+        include GitHelpers
+        exec_tool!
+
+        description "Commit staged changes in the repository at fs_root with a message. Set all to " \
+                    "also stage modified/deleted tracked files first (git commit -a). Does not push."
+
+        param :message, type: "string",
+                        desc: "Commit message.",
+                        required: true
+        param :all, type: "boolean",
+                    desc: "Stage modified/deleted tracked files before committing (git commit -a). Default false.",
+                    required: false
+
+        def execute(message:, all: false)
+          msg = message.to_s
+          return error("commit message must not be empty", code: :empty_message) if msg.strip.empty?
+
+          args = ["commit"]
+          args << "-a" if all
+          args += ["-m", msg]
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          if result.is_a?(Hash)
+            combined = "#{out}\n#{err}"
+            return error("nothing to commit (stage changes first)", code: :nothing_to_commit) if combined.match?(/nothing to commit/i)
+
+            return result
+          end
+
+          truncate(out.strip)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_diff.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Shows a unified diff of the repo at fs_root. Read-only.
+      #
+      # External diff drivers and textconv filters are disabled so a malicious
+      # repo can't turn a diff into command execution.
+      class GitDiff < Base
+        include GitHelpers
+
+        description "Show a unified git diff for the repository at fs_root. By default shows unstaged " \
+                    "changes; set staged to show what's staged. Optionally scope to a path or diff " \
+                    "against a ref. Read-only."
+
+        param :staged, type: "boolean",
+                      desc: "Show staged changes (git diff --cached) instead of unstaged. Default false.",
+                      required: false
+        param :path, type: "string",
+                     desc: "Limit the diff to this path, relative to fs_root. Optional.",
+                     required: false
+        param :ref, type: "string",
+                    desc: "Diff against this commit/branch/tag instead of the index. Optional.",
+                    required: false
+
+        def execute(staged: false, path: nil, ref: nil)
+          return error("invalid ref: #{ref.inspect}", code: :bad_ref) if ref && !valid_ref?(ref)
+
+          rel = repo_relative(path)
+          args = ["diff", "--no-ext-diff", "--no-textconv", "--stat", "--patch"]
+          args << "--cached" if staged
+          args << ref if ref
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result.strip.empty? ? "no changes" : result)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_grep.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Searches the repo's tracked files with `git grep` and returns
+      # matching lines with file:line prefixes. Read-only. Faster and cleaner
+      # than grep_files in a git repo because it only looks at tracked content
+      # and skips binary files.
+      class GitGrep < Base
+        include GitHelpers
+
+        description "Search the tracked files of the repo at fs_root for a pattern using git grep, " \
+                    "returning file:line: matches. Optionally restrict to a path, ignore case, or treat " \
+                    "the pattern as a fixed string instead of a regex."
+
+        param :pattern, type: "string",
+                        desc: "The pattern to search for (a basic regex unless fixed is true).",
+                        required: true
+        param :path, type: "string",
+                     desc: "Restrict the search to this file or directory, relative to fs_root. Optional.",
+                     required: false
+        param :ignore_case, type: "boolean",
+                           desc: "Case-insensitive search. Default false.",
+                           required: false
+        param :fixed, type: "boolean",
+                      desc: "Treat the pattern as a literal string rather than a regex. Default false.",
+                      required: false
+
+        def execute(pattern:, path: nil, ignore_case: false, fixed: false)
+          pat = pattern.to_s
+          return error("pattern must not be empty", code: :empty_pattern) if pat.empty?
+
+          rel = repo_relative(path)
+          args = ["grep", "-n", "-I", "--no-color"]
+          args << "-i" if ignore_case
+          args << "-F" if fixed
+          args += ["-e", pat] # -e guards against a pattern that begins with "-"
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args)
+          interpret(out, err, status)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        # git grep exits 1 (with no error output) when there are simply no
+        # matches — that's a normal result, not a tool failure.
+        def interpret(out, err, status)
+          return error("timed out after #{config.command_timeout}s", code: :timeout) if status == :timeout
+
+          case status.exitstatus
+          when 0 then truncate(out)
+          when 1 then err.to_s.strip.empty? ? "no matches" : error(err.strip, code: :git_error)
+          else error(err.to_s.strip.empty? ? out.to_s.strip : err.strip, code: :git_error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_helpers.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "ruby_llm/toolbox/process_runner"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # Shared behavior for the git tools. Mixed into each so they all run git
+      # the same hardened way.
+      #
+      # Hardening matters here because git executes commands configured *by the
+      # repository* in several places, which turns "read-only" commands into RCE
+      # when operating on an untrusted checkout:
+      #   - core.fsmonitor runs a command during `git status`
+      #   - diff.external / textconv run commands during `git diff`
+      # The read tools are on by default, so the runner neutralizes those
+      # (`-c core.fsmonitor=`, and diff adds --no-ext-diff --no-textconv). The
+      # pager and credential prompts are also disabled so nothing can hang.
+      module GitHelpers
+        GIT_ENV = { "GIT_PAGER" => "cat", "GIT_TERMINAL_PROMPT" => "0" }.freeze
+        # A ref/branch the model supplies: no leading dash (option injection),
+        # and only the characters git refs legitimately use.
+        REF_RE = %r{\A[A-Za-z0-9][\w./\-]*\z}
+
+        def run_git(*args, stdin: nil)
+          argv = ["git", "-c", "core.fsmonitor=", "-C", config.fs_root, "--no-pager", *args]
+          ProcessRunner.capture(argv, env: git_env, stdin: stdin, timeout: config.command_timeout, unsetenv_others: true)
+        end
+
+        # Maps a finished git run onto the toolbox return contract.
+        def git_result(out, err, status)
+          return error("git timed out after #{config.command_timeout}s", code: :timeout) if status == :timeout
+          return out if status.exitstatus&.zero?
+
+          message = (err.empty? ? out : err).strip
+          code = message.match?(/not a git repository/i) ? :not_a_repo : :git_error
+          error("git failed: #{message}", code: code)
+        end
+
+        def valid_ref?(ref)
+          ref.to_s.match?(REF_RE)
+        end
+
+        # Resolve a path param to a repo-relative path, rejecting jail escapes.
+        # Returns nil for a blank path. Raises PathJail::Jailbreak on escape.
+        def repo_relative(path)
+          return nil if path.nil? || path.to_s.empty?
+
+          jail = Safety::PathJail.new(config.fs_root)
+          real = jail.resolve(path)
+          Pathname.new(real).relative_path_from(Pathname.new(jail.root)).to_s
+        end
+
+        private
+
+        def git_env
+          env = config.env_passthrough.each_with_object({}) do |key, acc|
+            value = ENV[key]
+            acc[key] = value unless value.nil?
+          end
+          env.merge(GIT_ENV)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_log.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Shows recent commit history for the repo at fs_root. Read-only.
+      class GitLog < Base
+        include GitHelpers
+
+        description "Show recent git commit history for the repository at fs_root (hash, date, " \
+                    "author, subject). Optionally limit the count or scope to a path. Read-only."
+
+        DEFAULT_COUNT = 20
+        MAX_COUNT     = 200
+        FORMAT        = "%h %ad %an: %s"
+
+        param :count, type: "integer",
+                      desc: "Number of commits to show (default 20, max 200).",
+                      required: false
+        param :path, type: "string",
+                     desc: "Limit history to commits touching this path, relative to fs_root. Optional.",
+                     required: false
+
+        def execute(count: DEFAULT_COUNT, path: nil)
+          n = count.to_i
+          n = DEFAULT_COUNT if n <= 0
+          n = MAX_COUNT if n > MAX_COUNT
+
+          rel  = repo_relative(path)
+          args = ["log", "--max-count=#{n}", "--date=short", "--pretty=format:#{FORMAT}"]
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result.strip.empty? ? "no commits" : result)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_show.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Shows a commit (message + diff) or the contents of a file at a
+      # given ref. Read-only. External diff drivers and textconv are disabled.
+      class GitShow < Base
+        include GitHelpers
+
+        description "Show a git object in the repo at fs_root. With no path, shows the commit at ref " \
+                    "(message and diff). With a path, shows that file's contents as of ref. Defaults " \
+                    "to HEAD. Read-only."
+
+        param :ref, type: "string",
+                    desc: "Commit/branch/tag to show. Default HEAD.",
+                    required: false
+        param :path, type: "string",
+                     desc: "If given, show this file's contents at ref instead of the commit. Optional.",
+                     required: false
+
+        def execute(ref: "HEAD", path: nil)
+          ref = ref.to_s.strip
+          ref = "HEAD" if ref.empty?
+          return error("invalid ref: #{ref.inspect}", code: :bad_ref) unless valid_ref?(ref)
+
+          rel = repo_relative(path)
+          args = if rel
+                   ["show", "#{ref}:#{rel}"]
+                 else
+                   ["show", "--no-ext-diff", "--no-textconv", "--stat", "--patch", ref]
+                 end
+
+          out, err, status = run_git(*args)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/git_status.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/tools/git_helpers"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Shows the working-tree status of the repo at fs_root (branch plus
+      # staged/unstaged/untracked changes). Read-only; requires git on the host.
+      class GitStatus < Base
+        include GitHelpers
+
+        description "Show the git working-tree status of the repository at fs_root: current branch " \
+                    "and staged, unstaged, and untracked changes. Read-only."
+
+        def execute
+          out, err, status = run_git("status", "--short", "--branch")
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          truncate(result.strip.empty? ? "working tree clean" : result)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/toolbox/tools/glob.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "ruby_llm/toolbox/base"
+require "ruby_llm/toolbox/safety/path_jail"
+
+module RubyLLM
+  module Toolbox
+    module Tools
+      # SAFE. Finds files matching a glob pattern within fs_root and returns
+      # their paths relative to the glob base. Each hit is re-checked through
+      # the path jail so a symlinked match that points outside the root is
+      # dropped.
+      class Glob < Base
+        description "Find files matching a glob pattern within fs_root (e.g. '**/*.rb', " \
+                    "'app/models/*.rb'). Returns matching paths, sorted. Results are capped " \
+                    "and token-budgeted."
+
+        param :pattern, type: "string",
+                        desc: "Glob pattern such as '**/*.rb', evaluated relative to base.",
+                        required: true
+        param :base, type: "string",
+                     desc: "Directory to glob from, relative to fs_root. Defaults to fs_root.",
+                     required: false
+
+        MAX_RESULTS = 1_000
+
+        def execute(pattern:, base: ".")
+          return error("pattern must be provided", code: :bad_pattern) if pattern.to_s.empty?
+          return error("pattern may not contain '..'", code: :bad_pattern) if pattern.include?("..")
+
+          jail = Safety::PathJail.new(config.fs_root)
+          root = jail.resolve(base)
+          return error("not a directory: #{base}", code: :not_a_directory) unless File.directory?(root)
+
+          base_pn = Pathname.new(root)
+          results = Dir.glob(File.join(root, pattern), File::FNM_PATHNAME).sort.filter_map do |match|
+            in_jail?(jail, 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" }
+          truncate(body)
+        rescue Safety::PathJail::Jailbreak => e
+          error(e.message, code: :path_denied)
+        end
+
+        private
+
+        def in_jail?(jail, match)
+          jail.resolve(match)
+          File.exist?(match)
+        rescue Safety::PathJail::Jailbreak
+          false
+        end
+      end
+    end
+  end
+end