shared_tools 0.4.2 → 0.6.0

data/lib/shared_tools/tools/git/branch_tool.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Lists the branches of the repo at repo_root, with the
+      # current branch marked and each branch's latest commit. Does not
+      # create, switch, or delete branches (see Git::CheckoutTool).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::BranchTool.new
+      #   tool.execute(all: true)
+      class BranchTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_branch'
+
+        description "List the branches of the repository, with the current branch marked (*) and " \
+                    "each branch's tip commit. Set all true to include remote-tracking branches. Read-only."
+
+        parameters do
+          boolean :all, description: "Include remote-tracking branches. Default false (local only).", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param all [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(all: false)
+          @logger.info("#{self.class.name}#execute all=#{all}")
+
+          args = ["branch", "--no-color", "-vv"]
+          args << "-a" if all
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          result.strip.empty? ? "no branches yet (no commits?)" : result
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/checkout_tool.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Mutating. Switches branches or creates a new branch in the repo at
+      # repo_root; can change the working tree. The ref is validated (no
+      # leading dash, ref-safe characters only) so it can't smuggle git
+      # options. Requires user authorization (see SharedTools.execute?).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::CheckoutTool.new
+      #   tool.execute(ref: "main")
+      #   tool.execute(ref: "feature/x", create: true)
+      class CheckoutTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_checkout'
+
+        description "Switch to a branch/commit in the repository, or create a new branch with " \
+                    "create: true. Note this can change the working tree."
+
+        parameters do
+          string  :ref,    description: "Branch, tag, or commit to switch to (or the new branch name when create is true)."
+          boolean :create, description: "Create a new branch named ref before switching to it (git checkout -b). Default false.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param ref [String]
+        # @param create [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(ref:, create: false)
+          @logger.info("#{self.class.name}#execute ref=#{ref.inspect} create=#{create}")
+
+          return { error: "invalid ref: #{ref.inspect}" } unless valid_ref?(ref)
+
+          args = ["checkout"]
+          args << "-b" if create
+          args << ref
+
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: args.join(" "))
+          unless allowed
+            @logger.warn("User declined to checkout #{ref}")
+            return { error: "User declined to checkout #{ref}" }
+          end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          # git prints checkout feedback to stderr on success.
+          [out, err].map(&:strip).reject(&:empty?).join("\n")
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/commit_tool.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Mutating. Commits staged changes in the repo at repo_root with a
+      # message. The message is passed as a single argv element (-m), so it
+      # is never parsed by a shell. Requires user authorization (see
+      # SharedTools.execute?). Does not push.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::CommitTool.new
+      #   tool.execute(message: "Fix the thing")
+      class CommitTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_commit'
+
+        description "Commit staged changes in the repository with a message. Set all to also " \
+                    "stage modified/deleted tracked files first (git commit -a). Does not push."
+
+        parameters do
+          string  :message, description: "Commit message."
+          boolean :all,     description: "Stage modified/deleted tracked files before committing (git commit -a). Default false.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param message [String]
+        # @param all [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(message:, all: false)
+          @logger.info("#{self.class.name}#execute all=#{all}")
+
+          msg = message.to_s
+          return { error: "commit message must not be empty" } if msg.strip.empty?
+
+          args = ["commit"]
+          args << "-a" if all
+          args += ["-m", msg]
+
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "git commit#{all ? ' -a' : ''} -m #{msg.inspect}")
+          unless allowed
+            @logger.warn("User declined to commit")
+            return { error: "User declined to commit" }
+          end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          if result.is_a?(Hash)
+            combined = "#{out}\n#{err}"
+            return { error: "nothing to commit (stage changes first)" } if combined.match?(/nothing to commit/i)
+
+            return result
+          end
+
+          out.strip
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/diff_tool.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows a unified diff of the repo at repo_root. External
+      # diff drivers and textconv filters are disabled so a malicious repo
+      # can't turn a diff into command execution.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::DiffTool.new
+      #   tool.execute
+      #   tool.execute(staged: true, path: "lib/foo.rb")
+      class DiffTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_diff'
+
+        description "Show a unified git diff for the repository. By default shows unstaged " \
+                    "changes; set staged to show what's staged. Optionally scope to a path or diff " \
+                    "against a ref. Read-only."
+
+        parameters do
+          boolean :staged, description: "Show staged changes (git diff --cached) instead of unstaged. Default false.", required: false
+          string  :path,   description: "Limit the diff to this path, relative to the repo root. Optional.", required: false
+          string  :ref,    description: "Diff against this commit/branch/tag instead of the index. Optional.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param staged [Boolean]
+        # @param path [String, nil]
+        # @param ref [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(staged: false, path: nil, ref: nil)
+          @logger.info("#{self.class.name}#execute staged=#{staged} path=#{path.inspect} ref=#{ref.inspect}")
+
+          return { error: "invalid ref: #{ref.inspect}" } if ref && !valid_ref?(ref)
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          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, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          result.strip.empty? ? "no changes" : result
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/grep_tool.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Searches the repo's tracked files with `git grep` and
+      # returns matching lines with file:line prefixes. Faster and cleaner
+      # than a filesystem grep in a git repo because it only looks at
+      # tracked content and skips binary files.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::GrepTool.new
+      #   tool.execute(pattern: "def execute")
+      class GrepTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_grep'
+
+        description "Search the tracked files of the repository 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."
+
+        parameters do
+          string  :pattern,     description: "The pattern to search for (a basic regex unless fixed is true)."
+          string  :path,        description: "Restrict the search to this file or directory, relative to the repo root. Optional.", required: false
+          boolean :ignore_case, description: "Case-insensitive search. Default false.", required: false
+          boolean :fixed,       description: "Treat the pattern as a literal string rather than a regex. Default false.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param pattern [String]
+        # @param path [String, nil]
+        # @param ignore_case [Boolean]
+        # @param fixed [Boolean]
+        #
+        # @return [String, Hash]
+        def execute(pattern:, path: nil, ignore_case: false, fixed: false)
+          @logger.info("#{self.class.name}#execute pattern=#{pattern.inspect} path=#{path.inspect}")
+
+          pat = pattern.to_s
+          return { error: "pattern must not be empty" } if pat.empty?
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          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, repo_root: @repo_root)
+          interpret(out, err, status)
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        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)
+          case status.exitstatus
+          when 0 then out
+          when 1 then err.to_s.strip.empty? ? "no matches" : { error: err.strip }
+          else { error: err.to_s.strip.empty? ? out.to_s.strip : err.strip }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/helpers.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "open3"
+require "pathname"
+
+module SharedTools
+  module Tools
+    module Git
+      # Shared behavior for the git tools: running git the same hardened way,
+      # and mapping its output onto the shared_tools { error: } contract.
+      #
+      # Hardening matters because git executes commands configured *by the
+      # repository* in several places, which turns "read-only" commands into
+      # arbitrary code execution when operating on an untrusted checkout:
+      #   - core.fsmonitor runs a command during `git status`
+      #   - diff.external / textconv run commands during `git diff`
+      # core.fsmonitor is disabled via `-c`, and the diff/show tools pass
+      # --no-ext-diff --no-textconv. The pager and credential prompts are
+      # also disabled so a call can never hang waiting on a TTY.
+      module Helpers
+        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}
+
+        # @param args [Array<String>]
+        # @param repo_root [String]
+        # @return [Array(String, String, Process::Status)] stdout, stderr, status
+        def run_git(*args, repo_root:)
+          Open3.capture3(GIT_ENV, "git", "-c", "core.fsmonitor=", "-C", repo_root.to_s, "--no-pager", *args)
+        end
+
+        # Maps a finished git run onto the shared_tools return contract.
+        #
+        # @return [String, Hash] stdout on success, or an { error:, code: } hash
+        def git_result(out, err, status)
+          return out if status.success?
+
+          message = (err.to_s.empty? ? out.to_s : err.to_s).strip
+          code = message.match?(/not a git repository/i) ? :not_a_repo : :git_error
+          { error: message.empty? ? "git failed with exit code #{status.exitstatus}" : "git failed: #{message}", code: code }
+        end
+
+        # @param ref [String]
+        # @return [Boolean]
+        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.
+        #
+        # @param path [String, nil]
+        # @param repo_root [String]
+        #
+        # @raise [SecurityError] if the path escapes repo_root
+        # @return [String, nil]
+        def repo_relative(path, repo_root:)
+          return nil if path.nil? || path.to_s.strip.empty?
+
+          root = Pathname.new(File.expand_path(repo_root))
+          resolved = (root + path).cleanpath
+          raise SecurityError, "path escapes repo_root: #{path}" unless resolved.ascend.any? { |ancestor| ancestor == root }
+
+          resolved.relative_path_from(root).to_s
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/log_tool.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows recent commit history for the repo at repo_root.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::LogTool.new
+      #   tool.execute(count: 10)
+      class LogTool < ::RubyLLM::Tool
+        include Helpers
+
+        DEFAULT_COUNT = 20
+        MAX_COUNT     = 200
+        FORMAT        = "%h %ad %an: %s"
+
+        def self.name = 'git_log'
+
+        description "Show recent git commit history for the repository (hash, date, author, " \
+                    "subject). Optionally limit the count or scope to a path. Read-only."
+
+        parameters do
+          integer :count, description: "Number of commits to show (default #{DEFAULT_COUNT}, max #{MAX_COUNT}).", required: false
+          string  :path,  description: "Limit history to commits touching this path, relative to the repo root. Optional.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param count [Integer]
+        # @param path [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(count: DEFAULT_COUNT, path: nil)
+          @logger.info("#{self.class.name}#execute count=#{count} path=#{path.inspect}")
+
+          n = count.to_i
+          n = DEFAULT_COUNT if n <= 0
+          n = MAX_COUNT if n > MAX_COUNT
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = ["log", "--max-count=#{n}", "--date=short", "--pretty=format:#{FORMAT}"]
+          args += ["--", rel] if rel
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          result = git_result(out, err, status)
+          if result.is_a?(Hash)
+            return "no commits" if result[:error].to_s.match?(/does not have any commits yet|bad default revision/i)
+
+            return result
+          end
+
+          result.strip.empty? ? "no commits" : result
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/show_tool.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows a commit (message + diff) or the contents of a file
+      # at a given ref. External diff drivers and textconv are disabled.
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::ShowTool.new
+      #   tool.execute
+      #   tool.execute(ref: "HEAD~1", path: "lib/foo.rb")
+      class ShowTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_show'
+
+        description "Show a git object in the repository. 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."
+
+        parameters do
+          string :ref,  description: "Commit/branch/tag to show. Default HEAD.", required: false
+          string :path, description: "If given, show this file's contents at ref instead of the commit. Optional.", required: false
+        end
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @param ref [String]
+        # @param path [String, nil]
+        #
+        # @return [String, Hash]
+        def execute(ref: "HEAD", path: nil)
+          @logger.info("#{self.class.name}#execute ref=#{ref.inspect} path=#{path.inspect}")
+
+          ref = ref.to_s.strip
+          ref = "HEAD" if ref.empty?
+          return { error: "invalid ref: #{ref.inspect}" } unless valid_ref?(ref)
+
+          rel = repo_relative(path, repo_root: @repo_root)
+          args = if rel
+                   ["show", "#{ref}:#{rel}"]
+                 else
+                   ["show", "--no-ext-diff", "--no-textconv", "--stat", "--patch", ref]
+                 end
+
+          out, err, status = run_git(*args, repo_root: @repo_root)
+          git_result(out, err, status)
+        rescue SecurityError => e
+          @logger.error("#{self.class.name} path denied: #{e.message}")
+          { error: e.message }
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git/status_tool.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module SharedTools
+  module Tools
+    module Git
+      # Read-only. Shows the working-tree status of the repo at repo_root
+      # (current branch plus staged/unstaged/untracked changes).
+      #
+      # @example
+      #   tool = SharedTools::Tools::Git::StatusTool.new
+      #   tool.execute
+      class StatusTool < ::RubyLLM::Tool
+        include Helpers
+
+        def self.name = 'git_status'
+
+        description "Show the git working-tree status of the repository: current branch and " \
+                    "staged, unstaged, and untracked changes. Read-only."
+
+        # @param repo_root [String] optional, defaults to the current directory
+        # @param logger [Logger] optional logger
+        def initialize(repo_root: nil, logger: nil)
+          @repo_root = repo_root || Dir.pwd
+          @logger = logger || RubyLLM.logger
+        end
+
+        # @return [String, Hash]
+        def execute
+          @logger.info("#{self.class.name}#execute repo_root=#{@repo_root}")
+
+          out, err, status = run_git("status", "--short", "--branch", repo_root: @repo_root)
+          result = git_result(out, err, status)
+          return result if result.is_a?(Hash)
+
+          changes = result.each_line.reject { |line| line.start_with?("##") }
+          changes.empty? ? "working tree clean" : result
+        rescue => e
+          @logger.error("#{self.class.name} failed: #{e.message}")
+          { error: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/git.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Collection loader for all git tools
+# Usage: require 'shared_tools/tools/git'
+
+require 'shared_tools'
+
+require_relative 'git/helpers'
+require_relative 'git/status_tool'
+require_relative 'git/diff_tool'
+require_relative 'git/log_tool'
+require_relative 'git/show_tool'
+require_relative 'git/blame_tool'
+require_relative 'git/branch_tool'
+require_relative 'git/grep_tool'
+require_relative 'git/add_tool'
+require_relative 'git/commit_tool'
+require_relative 'git/checkout_tool'