shared_tools 0.4.2 → 0.6.0

data/lib/shared_tools/tools/replace_in_files_tool.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+
+module SharedTools
+  module Tools
+    # Find-and-replace across the files in root that match a glob. Literal
+    # by default; set regex: true for a pattern (with backreferences in the
+    # replacement). Binary files and ignored directories are skipped, the
+    # pattern runs under a ReDoS timeout, and every path is confined to
+    # root. Use dry_run: true to preview the impact without writing.
+    # Mutating — requires user authorization (see SharedTools.execute?).
+    #
+    # @example
+    #   tool = SharedTools::Tools::ReplaceInFilesTool.new(root: "./my-project")
+    #   tool.execute(pattern: "FooBar", replacement: "BazQux", glob: "**/*.rb")
+    #   tool.execute(pattern: "v(\\d+)\\.(\\d+)", replacement: 'v\1.\2-beta', regex: true, dry_run: true)
+    class ReplaceInFilesTool < ::RubyLLM::Tool
+      MAX_BYTES = 5 * 1024 * 1024
+      MAX_LISTED = 100
+      REGEX_TIMEOUT = 2
+      IGNORED_DIRS = %w[.git .hg .svn node_modules .bundle tmp].freeze
+
+      def self.name = 'replace_in_files'
+
+      description "Replace occurrences of a pattern with a replacement across files in root " \
+                  "matching a glob (default '**/*'). Literal by default; set regex true to use a " \
+                  "regular expression (replacement may use \\1 backreferences). Set dry_run true to " \
+                  "preview without writing. Skips binary files and ignored directories."
+
+      parameters do
+        string  :pattern,     description: "Text (or regex if regex=true) to find."
+        string  :replacement, description: "Replacement text. With regex=true, \\1 etc. refer to capture groups.", required: false
+        string  :glob,        description: "Glob of files to search, relative to root. Default '**/*'.", required: false
+        boolean :regex,       description: "Treat pattern as a regular expression. Default false (literal).", required: false
+        boolean :ignore_case, description: "Case-insensitive matching. Default false.", required: false
+        boolean :dry_run,     description: "Report what would change without writing. 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 pattern [String]
+      # @param replacement [String]
+      # @param glob [String]
+      # @param regex [Boolean]
+      # @param ignore_case [Boolean]
+      # @param dry_run [Boolean]
+      #
+      # @return [String, Hash]
+      def execute(pattern:, replacement: "", glob: "**/*", regex: false, ignore_case: false, dry_run: false)
+        @logger.info("#{self.class.name}#execute pattern=#{pattern.inspect} glob=#{glob.inspect} regex=#{regex} dry_run=#{dry_run}")
+
+        return { error: "pattern must not be empty" } if pattern.to_s.empty?
+
+        matcher = build_matcher(pattern, regex, ignore_case)
+        root = File.realpath(@root)
+
+        candidates = candidate_files(glob, root)
+        preview = candidates.filter_map do |abs, rel|
+          content = File.read(abs)
+          next unless text?(content)
+
+          count, = substitute(content, matcher, replacement.to_s, regex)
+          [abs, rel, count] unless count.zero?
+        end
+
+        return format_summary([], 0, dry_run) if preview.empty?
+
+        unless dry_run
+          allowed = SharedTools.execute?(tool: self.class.to_s, stuff: "Replace #{preview.sum { |_, _, c| c }} occurrence(s) across #{preview.size} file(s)")
+          unless allowed
+            @logger.warn("User declined to replace in files")
+            return { error: "User declined to replace in files" }
+          end
+        end
+
+        changed = []
+        total = 0
+        preview.each do |abs, rel, _count|
+          content = File.read(abs)
+          count, updated = substitute(content, matcher, replacement.to_s, regex)
+          next if count.zero?
+
+          total += count
+          changed << [rel, count]
+          File.write(abs, updated) unless dry_run
+        end
+
+        format_summary(changed, total, dry_run)
+      rescue Regexp::TimeoutError
+        @logger.error("#{self.class.name}: regex timed out")
+        { error: "pattern timed out (possible ReDoS); narrow the pattern" }
+      rescue RegexpError => e
+        @logger.error("#{self.class.name}: invalid regex: #{e.message}")
+        { error: "invalid regular expression: #{e.message}" }
+      end
+
+      private
+
+      def build_matcher(pattern, regex, ignore_case)
+        flags = ignore_case ? Regexp::IGNORECASE : 0
+        src = regex ? pattern.to_s : Regexp.escape(pattern.to_s)
+        Regexp.new(src, flags, timeout: REGEX_TIMEOUT)
+      end
+
+      def candidate_files(glob, root)
+        Dir.glob(File.join(root, glob)).filter_map do |abs|
+          next unless File.file?(abs)
+
+          real = begin
+            File.realpath(abs)
+          rescue StandardError
+            next
+          end
+          next unless real == root || real.start_with?(root + File::SEPARATOR)
+
+          rel = real.delete_prefix(root + File::SEPARATOR)
+          next if ignored?(rel)
+          next if File.size(real) > MAX_BYTES
+
+          [real, rel]
+        end
+      end
+
+      def ignored?(rel)
+        parts = rel.split(File::SEPARATOR)
+        IGNORED_DIRS.any? { |dir| parts.include?(dir) }
+      end
+
+      def text?(content)
+        nul = 0.chr
+        content.valid_encoding? && !content.include?(nul)
+      end
+
+      def substitute(content, matcher, replacement, regex)
+        if regex
+          count = content.scan(matcher).size
+          return [0, content] if count.zero?
+
+          [count, content.gsub(matcher, replacement)]
+        else
+          count = 0
+          updated = content.gsub(matcher) { count += 1; replacement }
+          return [0, content] if count.zero?
+
+          [count, updated]
+        end
+      end
+
+      def format_summary(changed, total, dry_run)
+        verb = dry_run ? "Would replace" : "Replaced"
+        return "#{verb} 0 occurrences (no matching files changed)." if changed.empty?
+
+        header = "#{verb} #{total} occurrence#{total == 1 ? '' : 's'} across #{changed.size} file#{changed.size == 1 ? '' : 's'}#{dry_run ? ' (dry run)' : ''}:"
+        lines = changed.first(MAX_LISTED).map { |rel, n| "  #{rel} (#{n})" }
+        lines << "  ... and #{changed.size - MAX_LISTED} more" if changed.size > MAX_LISTED
+        ([header] + lines).join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/run_tests_tool.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+require_relative "toolchain_helpers"
+
+module SharedTools
+  module Tools
+    # Runs a Ruby project's test suite (RSpec or Minitest) from root and
+    # returns the output with a pass/fail headline. A failing suite is a
+    # normal result (the caller needs to see it), not a tool error. Requires
+    # user authorization (see SharedTools.execute?) since it executes an
+    # external command.
+    #
+    # @example
+    #   tool = SharedTools::Tools::RunTestsTool.new(root: "./my-project")
+    #   tool.execute
+    #   tool.execute(path: "spec/models/user_spec.rb")
+    class RunTestsTool < ::RubyLLM::Tool
+      include ToolchainHelpers
+
+      FRAMEWORKS = %w[rspec minitest].freeze
+      DEFAULT_TIMEOUT = 180
+
+      def self.name = 'run_tests'
+
+      description "Run a Ruby project's test suite from root and report results. Auto-detects RSpec " \
+                  "(spec/ or .rspec) or Minitest (test/ via rake), or set framework explicitly. " \
+                  "Optionally scope to a path. Uses `bundle exec` when a Gemfile exists."
+
+      parameters do
+        string :path,      description: "Limit the run to this spec/test file or directory, relative to root. Optional.", required: false
+        string :framework, description: "Force the framework: rspec or minitest. Default: auto-detect.", 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, nil]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, framework: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} framework=#{framework.inspect}")
+
+        fw = (framework || detect_framework).to_s
+        return { error: "could not detect a test framework (no spec/ or test/); set framework" } 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 = fw == "rspec" ? run_rspec(rel) : run_minitest(rel)
+        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 in the bundle / installed?)" }
+      end
+
+      private
+
+      def detect_framework
+        return "rspec" if File.directory?(File.join(@root, "spec")) || File.exist?(File.join(@root, ".rspec"))
+        return "minitest" if File.directory?(File.join(@root, "test"))
+
+        ""
+      end
+
+      def run_rspec(rel)
+        args = ["rspec"]
+        args << rel if rel
+        run_in_project(args, use_bundle: true, timeout: DEFAULT_TIMEOUT)
+      end
+
+      def run_minitest(rel)
+        args = ["rake", "test"]
+        args << "TEST=#{rel}" if rel
+        run_in_project(args, use_bundle: true, timeout: DEFAULT_TIMEOUT)
+      end
+
+      # Pull the framework's summary line into the headline when present.
+      def summarize(out, err, label)
+        text = "#{out}\n#{err}"
+        if (m = text.match(/(\d+) examples?, (\d+) failures?(?:, (\d+) errors?)?/))
+          "#{label} (#{m[0]})"
+        elsif (m = text.match(/(\d+) runs?, \d+ assertions?, (\d+) failures?, (\d+) errors?/))
+          "#{label} (#{m[0]})"
+        else
+          label
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/search_codebase_tool.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "find"
+require "pathname"
+
+module SharedTools
+  module Tools
+    # Search file contents for a regular expression under a directory and
+    # return "path:line: text" hits. Pure Ruby (no `rg`/`grep` dependency).
+    # Read-only — no authorization prompt required.
+    #
+    # The pattern comes from an LLM, so two abuse vectors are guarded against:
+    #   - ReDoS: the regex is compiled with a per-match timeout, so
+    #     catastrophic backtracking can't hang the process.
+    #   - Runaway scans: results are capped at max_results (default 50, max
+    #     500), and the walk skips binary files, symlinks, oversized files,
+    #     and common noise directories (.git, node_modules, tmp, ...).
+    #
+    # @example
+    #   tool = SharedTools::Tools::SearchCodebaseTool.new
+    #   tool.execute(pattern: "def execute")
+    #   tool.execute(pattern: "RubyLLM", glob: "*.rb", max_results: 20)
+    #   tool.execute(pattern: "TODO", context: 2) # 2 lines of context around each match
+    class SearchCodebaseTool < ::RubyLLM::Tool
+      MAX_RESULTS_CAP = 500
+      DEFAULT_MAX_RESULTS = 50
+      MAX_FILE_BYTES = 5 * 1024 * 1024
+      MAX_CONTEXT = 50
+      REGEX_TIMEOUT = 2
+      IGNORED_DIRS = %w[.git .hg .svn node_modules .bundle tmp].freeze
+
+      def self.name = 'search_codebase'
+
+      description "Search file contents for a regular expression under a directory. Returns " \
+                  "'path:line: text' for each match, or context blocks when context/before/after " \
+                  "is set. Optionally restrict to files whose name matches a glob, and/or match " \
+                  "case-insensitively. Results are capped, ReDoS-guarded, and require no external " \
+                  "search binary."
+
+      parameters do
+        string  :pattern,     description: "Regular expression to search for."
+        string  :path,        description: "Directory to search in (default: current directory)", required: false
+        string  :glob,        description: "Only search files whose basename matches this glob, e.g. '*.rb'. Optional.", required: false
+        boolean :ignore_case, description: "Case-insensitive match. Default false.", required: false
+        integer :context,     description: "Lines of context to show before AND after each match (like grep -C). Optional.", required: false
+        integer :before,      description: "Lines of context before each match (like grep -B). Overrides context. Optional.", required: false
+        integer :after,       description: "Lines of context after each match (like grep -A). Overrides context. Optional.", required: false
+        integer :max_results, description: "Maximum number of matches to return (default #{DEFAULT_MAX_RESULTS}, max #{MAX_RESULTS_CAP}).", required: false
+      end
+
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      def execute(pattern:, path: ".", glob: nil, ignore_case: false, context: nil, before: nil, after: nil, max_results: DEFAULT_MAX_RESULTS)
+        @logger.info("SearchCodebaseTool#execute pattern=#{pattern.inspect} path=#{path} glob=#{glob.inspect}")
+
+        return { error: "Search pattern cannot be empty" } if pattern.to_s.strip.empty?
+
+        search_path = File.expand_path(path)
+        return { error: "Path not found: #{path}" } unless File.exist?(search_path)
+        return { error: "Not a directory: #{path}" } unless File.directory?(search_path)
+
+        regex = build_regex(pattern, ignore_case)
+        max = [[max_results.to_i, 1].max, MAX_RESULTS_CAP].min
+        ctx_before = clamp_context(before.nil? ? context : before)
+        ctx_after  = clamp_context(after.nil? ? context : after)
+
+        matches, truncated =
+          if ctx_before.zero? && ctx_after.zero?
+            gather(search_path, regex, glob, max)
+          else
+            gather_with_context(search_path, regex, glob, ctx_before, ctx_after, max)
+          end
+
+        { matches: matches, count: matches.size, truncated: truncated, tool: "ruby" }
+      rescue Regexp::TimeoutError
+        @logger.error("SearchCodebaseTool regex timed out: #{pattern.inspect}")
+        { error: "regex timed out (possible catastrophic backtracking); simplify the pattern" }
+      rescue RegexpError => e
+        @logger.error("SearchCodebaseTool invalid regex: #{e.message}")
+        { error: "invalid regex: #{e.message}" }
+      rescue => e
+        @logger.error("SearchCodebaseTool error: #{e.message}")
+        { error: e.message }
+      end
+
+      private
+
+      def build_regex(pattern, ignore_case)
+        options = ignore_case ? Regexp::IGNORECASE : 0
+        Regexp.new(pattern.to_s, options, timeout: REGEX_TIMEOUT)
+      end
+
+      def clamp_context(value)
+        n = value.to_i
+        return 0 if n <= 0
+
+        [n, MAX_CONTEXT].min
+      end
+
+      def gather(root, regex, glob, max)
+        base = Pathname.new(root)
+        matches = []
+        truncated = false
+
+        catch(:done) do
+          walk(root, glob) do |file|
+            scan(file, regex) do |lineno, text|
+              rel = Pathname.new(file).relative_path_from(base).to_s
+              matches << "#{rel}:#{lineno}: #{text.strip}"
+              if matches.size >= max
+                truncated = true
+                throw :done
+              end
+            end
+          end
+        end
+
+        [matches, truncated]
+      end
+
+      # Like gather, but expands each match with before/after context lines,
+      # merges overlapping/adjacent ranges per file, and returns formatted
+      # blocks. Match lines use "path:line: text"; context lines use
+      # "path-line- text".
+      def gather_with_context(root, regex, glob, ctx_before, ctx_after, max)
+        base = Pathname.new(root)
+        blocks = []
+        total = 0
+        truncated = false
+
+        catch(:done) do
+          walk(root, glob) do |file|
+            next if binary?(file)
+
+            lines = read_lines(file)
+            next if lines.nil?
+
+            match_idxs = []
+            lines.each_with_index { |line, i| match_idxs << i if regex.match?(line) }
+            next if match_idxs.empty?
+
+            taken = match_idxs.first(max - total)
+            truncated = true if taken.size < match_idxs.size
+            match_set = {}
+            taken.each { |i| match_set[i] = true }
+
+            rel = Pathname.new(file).relative_path_from(base).to_s
+            ranges = taken.map { |i| [[i - ctx_before, 0].max, [i + ctx_after, lines.size - 1].min] }
+            merge_ranges(ranges).each do |lo, hi|
+              block = (lo..hi).map do |i|
+                sep = match_set[i] ? ":" : "-"
+                "#{rel}#{sep}#{i + 1}#{sep} #{lines[i].to_s.strip}"
+              end
+              blocks << block.join("\n")
+            end
+
+            total += taken.size
+            throw :done if total >= max
+          end
+        end
+
+        [blocks, truncated]
+      end
+
+      def read_lines(file)
+        File.readlines(file).map(&:scrub)
+      rescue ArgumentError, SystemCallError
+        nil
+      end
+
+      def merge_ranges(ranges)
+        merged = []
+        ranges.sort_by(&:first).each do |lo, hi|
+          if !merged.empty? && lo <= merged.last[1] + 1
+            merged.last[1] = [merged.last[1], hi].max
+          else
+            merged << [lo, hi]
+          end
+        end
+        merged
+      end
+
+      def walk(root, glob)
+        Find.find(root) do |entry|
+          basename = File.basename(entry)
+
+          if File.directory?(entry)
+            Find.prune if IGNORED_DIRS.include?(basename)
+            next
+          end
+
+          next if File.symlink?(entry)
+          next if glob && !File.fnmatch?(glob, basename, File::FNM_PATHNAME)
+          next unless File.file?(entry)
+          next if File.size(entry) > MAX_FILE_BYTES
+
+          yield entry
+        end
+      end
+
+      def scan(file, regex)
+        return if binary?(file)
+
+        File.foreach(file).with_index(1) do |line, lineno|
+          safe = line.scrub
+          yield(lineno, safe) if regex.match?(safe)
+        end
+      rescue ArgumentError
+        # Unreadable as text (encoding) — skip the file rather than fail.
+        nil
+      end
+
+      def binary?(file)
+        File.binread(file, 1024).to_s.include?("".b)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/secure_tool_template.rb

@@ -28,7 +28,7 @@ module SharedTools
         sensitive systems, handle user data, or perform privileged operations.
       DESCRIPTION
 
-      params do
+      parameters do
         string :user_input, description: <<~DESC.strip
           User-provided input string that will be processed with comprehensive security validation.
           The input undergoes multiple security checks:

data/lib/shared_tools/tools/system_info_tool.rb

@@ -26,7 +26,7 @@ module SharedTools
         - 'all'     (default) — All of the above combined
       DESC
 
-      params do
+      parameters do
         string :category, required: false, description: <<~DESC.strip
           Info category. Options: 'os', 'cpu', 'memory', 'disk', 'network', 'ruby', 'all' (default).
         DESC

data/lib/shared_tools/tools/todo_write_tool.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "../../shared_tools"
+
+module SharedTools
+  module Tools
+    # Tracks a task list for multi-step work. Each call replaces the whole
+    # list (the standard agent pattern) and renders it back. State lives on
+    # the tool instance, so it persists across calls within a single chat
+    # session (when one instance is registered with the chat). Read-only in
+    # the sense that it never touches the filesystem or network — no
+    # authorization prompt required.
+    #
+    # @example
+    #   tool = SharedTools::Tools::TodoWriteTool.new
+    #   tool.execute(todos: [
+    #     { content: "Write the tool", status: "completed" },
+    #     { content: "Write the tests", status: "in_progress" }
+    #   ])
+    class TodoWriteTool < ::RubyLLM::Tool
+      STATUSES = %w[pending in_progress completed].freeze
+      MARKS = { "pending" => "[ ]", "in_progress" => "[~]", "completed" => "[x]" }.freeze
+
+      def self.name = 'todo_write'
+
+      description "Maintain a task list for multi-step work. Pass the full list of todos; each call " \
+                  "replaces the previous list. Each todo has a content string and a status of " \
+                  "pending, in_progress, or completed."
+
+      parameters do
+        array :todos, description: "The full task list, replacing the previous one." do
+          object do
+            string :content, description: "The task description."
+            string :status,  description: "One of: pending, in_progress, completed."
+          end
+        end
+      end
+
+      # @param logger [Logger] optional logger
+      def initialize(logger: nil)
+        @todos = []
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param todos [Array<Hash>]
+      #
+      # @return [String, Hash]
+      def execute(todos:)
+        @logger.info("#{self.class.name}#execute todos=#{Array(todos).size}")
+
+        return { error: "todos must be an array" } unless todos.is_a?(Array)
+
+        normalized = todos.map { |todo| normalize(todo) }
+        invalid = normalized.find { |todo| !STATUSES.include?(todo[:status]) }
+        return { error: "invalid status: #{invalid[:status].inspect} (use #{STATUSES.join(', ')})" } if invalid
+
+        @todos = normalized
+        render
+      end
+
+      private
+
+      def normalize(todo)
+        hash = todo.is_a?(Hash) ? todo : {}
+        {
+          content: (hash["content"] || hash[:content]).to_s,
+          status: (hash["status"] || hash[:status] || "pending").to_s.strip.downcase
+        }
+      end
+
+      def render
+        return "Task list is empty." if @todos.empty?
+
+        done = @todos.count { |todo| todo[:status] == "completed" }
+        lines = ["Tasks (#{done}/#{@todos.size} complete):"]
+        @todos.each { |todo| lines << "#{MARKS[todo[:status]]} #{todo[:content]}" }
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/toml_query_tool.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # Parses TOML (from a file or an inline string) and either pretty-prints
+    # it (as JSON, for readability) or extracts a value with a dot/bracket
+    # path. In-process, read-only, no external gem dependency — handy for
+    # Cargo.toml, pyproject.toml, and similar config.
+    #
+    # Path syntax matches JsonQueryTool / YamlQueryTool: dependencies.serde.version,
+    # products[0].name, products[].name
+    #
+    # @example
+    #   tool = SharedTools::Tools::TomlQueryTool.new
+    #   tool.execute(path: "./Cargo.toml", query: "dependencies.serde.version")
+    class TomlQueryTool < ::RubyLLM::Tool
+      MAX_BYTES = 5 * 1024 * 1024
+
+      def self.name = 'toml_query'
+
+      description "Query TOML with a path expression, or pretty-print it. Provide either a file " \
+                  "path or an inline toml string. Path syntax: keys separated by dots, [n] for " \
+                  "array index, [] to map over an array (e.g. products[].name)."
+
+      parameters do
+        string :path,  description: "TOML file to read. Provide this or toml.", required: false
+        string :toml,  description: "Inline TOML string. Provide this or path.", required: false
+        string :query, description: "Path expression to extract, e.g. 'dependencies.serde.version'. 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 toml [String, nil]
+      # @param query [String, nil]
+      #
+      # @return [String, Hash]
+      def execute(path: nil, toml: nil, query: nil)
+        @logger.info("#{self.class.name}#execute path=#{path.inspect} query=#{query.inspect}")
+
+        source = load_source(path, toml)
+        return source if source.is_a?(Hash) # error
+
+        data = SharedTools::TomlParser.parse(source)
+        result = query.to_s.strip.empty? ? data : SharedTools::DataPath.query(data, query)
+        JSON.pretty_generate(result)
+      rescue SharedTools::TomlParser::ParseError => e
+        @logger.error("#{self.class.name} invalid TOML: #{e.message}")
+        { error: "invalid TOML: #{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, toml)
+        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 toml && !toml.to_s.empty?
+          toml.to_s
+        else
+          { error: "provide either path or toml" }
+        end
+      end
+    end
+  end
+end