pikuri-workspace 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7cd37f2cda8958c1a0098160a71b6a0a3e375cd6f8169c298909950a8c6fdb87
+  data.tar.gz: fb99c3d2b8dcb886f5f5e93bb6562bf2e87b8bad0d44cdf71da2ece883ef3270
+SHA512:
+  metadata.gz: 4a79642151199e5e4ceeefda2130c270de29015350fa5a128d54d1a692fac9e37949363db2f4222d635d7619e09409140d6bad41c7cc841f1b9f1cde58762fc0
+  data.tar.gz: eb45fe6977711e452f399f58a9e4f0d80450e62008c1af32fc6c0d9fe04d7b3c63b8149c685f296dbed1de3e9f9cd883dea13714e23baa87681abeb28eb02f05

data/README.md

@@ -0,0 +1,50 @@
+# pikuri-workspace
+
+Filesystem tools + Workspace/Confirmer seams for the
+[pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant toolkit.
+
+Self-contained "operate on a directory tree" toolkit:
+- `Pikuri::Tool::Workspace` — abstract base + bundled
+  `Workspace::Cwd` that scopes filesystem access to a chosen root,
+  rejecting `..`-escapes and symlinks that resolve outside the root.
+- `Pikuri::Tool::Confirmer` — abstract base + `AUTO_APPROVE` /
+  `TERMINAL` for user-state mutations.
+- Five file tools: `Pikuri::Tool::Read`, `Pikuri::Tool::Write`,
+  `Pikuri::Tool::Edit`, `Pikuri::Tool::Grep`, `Pikuri::Tool::Glob`.
+
+No shell execution — `Pikuri::Tool::Bash` ships in
+[`pikuri-code`](../pikuri-code/README.md) on top of these.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'pikuri-workspace'
+```
+
+## Usage
+
+```ruby
+require 'pikuri-core'
+require 'pikuri-workspace'
+
+workspace = Pikuri::Tool::Workspace::Cwd.new(root: Dir.pwd)
+confirmer = Pikuri::Tool::Confirmer::TERMINAL
+
+agent = Pikuri::Agent.new(
+  transport: ...,
+  system_prompt: ...,
+) do |c|
+  c.add_tool Pikuri::Tool::Read.new(workspace: workspace)
+  c.add_tool Pikuri::Tool::Grep.new(workspace: workspace)
+  c.add_tool Pikuri::Tool::Glob.new(workspace: workspace)
+  c.add_tool Pikuri::Tool::Edit.new(workspace: workspace)
+  c.add_tool Pikuri::Tool::Write.new(workspace: workspace, confirmer: confirmer)
+  c.add_listener ...
+end
+```
+
+`Workspace::Cwd` is the "look-but-don't-leak" guard around filesystem
+access. Read tools route through `#resolve_for_read(path)`; mutating
+tools route through `#resolve_for_write(path)` + the Confirmer's
+`#confirm?(prompt:)`.

data/lib/pikuri/tool/confirmer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # Port for asking the user to confirm a potentially destructive tool
+    # operation — currently {Tool::Bash} (every command) and
+    # {Tool::Write} (overwrite of an existing file with non-identical
+    # content). Subclass and implement {#confirm?}.
+    #
+    # == Why a Boolean return
+    #
+    # v1 returns +true+ or +false+. Two paths-not-taken worth recording
+    # so a future reader knows the design space was considered:
+    #
+    # 1. Richer return (+:once+ / +:always+ / +:reject+) — rejected
+    #    because it creates decision fatigue, and the long-term answer
+    #    is to make confirmations rare rather than smart (sandboxing,
+    #    agentic destructiveness analysis).
+    # 2. Agentic destructive-or-not classifier — deferred to v2.
+    #
+    # The intended escape from confirmation prompts today is sandboxing
+    # (docker / dev-container) plus the +--yolo+ flag on +bin/pikuri-code+
+    # (which wires {AUTO_APPROVE} instead of {TERMINAL}).
+    #
+    # == Seam discipline
+    #
+    # Tools that need confirmation take a {Confirmer} via constructor and
+    # invoke {#confirm?} with a fully-composed prompt String. Tools do
+    # *not* call +gets+ / +puts+ directly — same lesson as listeners,
+    # keep IO at the seam so a future TUI / web client can plug a
+    # different implementation in without touching tool code.
+    class Confirmer
+      # @param prompt [String] human-readable question composed by the
+      #   calling tool. The confirmer renders it and parses the answer;
+      #   it does NOT compose its own prompt content. Caller owns the
+      #   closing punctuation and any "(y/n)" cue.
+      # @return [Boolean] +true+ iff approved
+      # @raise [NotImplementedError] in the abstract base
+      def confirm?(prompt:)
+        raise NotImplementedError, "#{self.class}#confirm? must be implemented"
+      end
+
+      # Stdin/stdout implementation: prints +prompt+ on its own line (a
+      # leading +puts+ guarantees separation from any streamed output
+      # the +Terminal+ listener may have produced just above), reads one
+      # line from +$stdin+, parses it strictly:
+      #
+      # * +"y"+ / +"yes"+ (case-insensitive, stripped) → +true+
+      # * +"n"+ / +"no"+ → +false+
+      # * EOF / Ctrl+D (+gets+ returns +nil+) → +false+, deliberate abort
+      # * anything else (blank, typo, +"maybe"+) → re-prompt with a short
+      #   "Please answer y or n: " line and loop
+      #
+      # No retry cap; EOF eventually breaks adversarial input.
+      class Terminal < Confirmer
+        # @param prompt [String]
+        # @return [Boolean]
+        def confirm?(prompt:)
+          puts
+          puts prompt
+          $stdout.flush
+          loop do
+            line = $stdin.gets
+            return false if line.nil?
+
+            answer = line.strip.downcase
+            return true  if answer == 'y' || answer == 'yes'
+            return false if answer == 'n' || answer == 'no'
+
+            print 'Please answer y or n: '
+            $stdout.flush
+          end
+        end
+      end
+
+      # Approves everything. Used by +bin/pikuri-code --yolo+ (docker /
+      # dev-container mode) and by tool specs that don't want to
+      # coordinate stdin. The name +AUTO_APPROVE+ matches the public
+      # constant {AUTO_APPROVE}.
+      class AutoApprove < Confirmer
+        # @param prompt [String] ignored
+        # @return [true]
+        def confirm?(prompt:)
+          true
+        end
+      end
+
+      # Shared singleton instance of {Terminal}. Stateless; reusable
+      # across tools and sub-agents.
+      TERMINAL = Terminal.new
+
+      # Shared singleton instance of {AutoApprove}.
+      AUTO_APPROVE = AutoApprove.new
+    end
+  end
+end

data/lib/pikuri/tool/edit.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +edit+ tool — exact-string replacement on an existing file.
+    # Instantiating +Tool::Edit.new(workspace: ws)+ produces a tool whose
+    # {Tool#to_ruby_llm_tool} wiring is identical to any bundled tool's.
+    # Same shape as {Tool::Read} (workspace captured by +execute+; no
+    # confirmer needed).
+    #
+    # == Why no confirmer
+    #
+    # The +old_string+ argument is itself an implicit read-check: the
+    # model can't write a correct +old_string+ without having seen the
+    # file (via {Tool::Read} or out-of-band), so the blast radius of any
+    # Edit is bounded by the model's actual knowledge of file state.
+    # That makes Edit safe to execute without prompting — by contrast,
+    # {Tool::Write} requires a confirmer because a hallucinated 500-line
+    # +content+ could clobber unread bytes.
+    #
+    # == Matching is strict (no fuzz cascade)
+    #
+    # +old_string+ must match the file byte-for-byte. v1 ships *no*
+    # fallback replacer (no whitespace-normalized, line-trimmed, block-
+    # anchor, etc.). Predictability beats fuzz: when an Edit fails, the
+    # model re-reads with {Tool::Read} and retries — clear failure mode,
+    # no compounding-heuristic risk. opencode runs a 9-replacer cascade
+    # under the hood despite its own description saying "must match
+    # exactly"; pi stays strict. We match pi.
+    #
+    # == Line endings get normalized
+    #
+    # The one structural exception to "strict bytes": files with CRLF
+    # line endings get matched in LF space, and the original line ending
+    # is restored on write. Reason: {Tool::Read} renders content via
+    # +each_line+ + +chomp+, which strips +\r\n+ to +\n+ in what the
+    # model sees. A pure strict byte-match would then never succeed on
+    # CRLF files because the model can only ever supply LF. opencode and
+    # pi both do this normalization for the same reason.
+    #
+    # Algorithm:
+    #
+    # 1. Detect whether the file contains +\r\n+ anywhere (treat as CRLF).
+    # 2. Normalize content, +old_string+, and +new_string+ to LF.
+    # 3. Match + replace in LF space.
+    # 4. If the file was CRLF, convert +\n+ → +\r\n+ on the way back out.
+    #
+    # Caveat: a mixed-line-ending file is treated as CRLF, which means
+    # any pre-existing bare-LF lines get converted on write. Rare in
+    # practice; acceptable for v1.
+    #
+    # == Refusals
+    #
+    # All returned as +"Error: ..."+ observations the LLM can react to:
+    #
+    # * Empty +old_string+ → "use the write tool" (keeps Edit/Write roles
+    #   non-overlapping).
+    # * +old_string+ == +new_string+ → no-op error.
+    # * +old_string+ not found in file → "must match exactly" error
+    #   pointing at the read tool.
+    # * +old_string+ found multiple times without +replace_all+ →
+    #   multi-match error suggesting more context or +replace_all+.
+    # * File missing / is a directory / is binary → respective error.
+    # * Workspace boundary violation / EACCES → standard rescue path.
+    class Edit < Tool
+      # Description shown to the LLM. Follows the opencode-shape (summary
+      # + +Usage:+ bullets) prescribed by the project's tool-description
+      # convention. Per-parameter constraints live in the parameter
+      # descriptions.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        Edit a file by exact-string replacement.
+
+        Usage:
+        - Use for partial changes to an existing file; for full rewrites or new files use `write` instead.
+        - `old_string` must match the file byte-for-byte (whitespace and indentation count); re-read the file with `read` if uncertain.
+        - `old_string` and `new_string` must differ.
+        - If `old_string` matches multiple times the call fails — add surrounding context to make the match unique, or set `replace_all: true`.
+        - Cannot create files (rejects empty `old_string` and missing files).
+        - Binary files are refused.
+        - CRLF files are matched in LF space; the original line endings are preserved on write.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution;
+      #   all reads/writes route through +workspace.resolve_for_write+
+      #   (Edit modifies, so it uses the write-set even though it doesn't
+      #   create files).
+      # @return [Edit]
+      def initialize(workspace:)
+        super(
+          name: 'edit',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :path,
+                              'Path to the file to edit. Relative paths ' \
+                              'resolve against the workspace root, e.g. ' \
+                              '"lib/foo.rb".'
+            p.required_string :old_string,
+                              'Exact text to find in the file. Must match ' \
+                              'byte-for-byte (whitespace counts); must be ' \
+                              'unique unless replace_all is true. Example: ' \
+                              '"def foo\n  bar\nend".'
+            p.required_string :new_string,
+                              'Replacement text. Must differ from ' \
+                              'old_string. Example: "def foo\n  baz\nend".'
+            p.optional_boolean :replace_all,
+                               'Replace every occurrence of old_string ' \
+                               'instead of failing on multiple matches. ' \
+                               'Defaults to false, e.g. true.'
+          },
+          execute: ->(path:, old_string:, new_string:, replace_all: false) {
+            Edit.edit(workspace: workspace, path: path,
+                      old_string: old_string, new_string: new_string,
+                      replace_all: replace_all)
+          }
+        )
+      end
+
+      # Resolve +path+ against +workspace+, run the precondition checks
+      # (non-empty / non-identical / file exists / not directory / not
+      # binary), match +old_string+ in line-ending-normalized form, and
+      # write the result back preserving the file's original line endings.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param path [String] raw path as supplied by the LLM
+      # @param old_string [String] text to find
+      # @param new_string [String] text to substitute in
+      # @param replace_all [Boolean] when true, every occurrence is
+      #   replaced; when false (default) multiple matches are an error
+      # @return [String] tool observation
+      def self.edit(workspace:, path:, old_string:, new_string:, replace_all:)
+        return 'Error: old_string is empty; use the write tool to create or overwrite a file.' if old_string.empty?
+        return 'Error: old_string and new_string are identical — this edit is a no-op.' if old_string == new_string
+
+        resolved = workspace.resolve_for_write(path)
+        return "Error: file not found: #{path}" unless resolved.exist?
+        return "Error: #{path} is a directory" if resolved.directory?
+
+        raw = resolved.binread
+        sample = raw.byteslice(0, Tool::Read::BINARY_SAMPLE_BYTES)
+        return "Error: cannot edit binary file: #{path}" if Tool::Read.binary?(sample)
+
+        crlf    = raw.include?("\r\n")
+        content = crlf ? raw.gsub("\r\n", "\n") : raw
+        needle  = normalize_lf(old_string)
+        patch   = normalize_lf(new_string)
+
+        occurrences = content.scan(needle).size
+        if occurrences.zero?
+          return "Error: old_string not found in #{path}. It must match the file " \
+                 'exactly, including whitespace and indentation; re-read with the ' \
+                 'read tool if uncertain.'
+        end
+        if occurrences > 1 && !replace_all
+          return "Error: old_string matches #{occurrences} times in #{path}. " \
+                 'Provide more surrounding context to make the match unique, ' \
+                 'or set replace_all=true to replace all occurrences.'
+        end
+
+        replaced = replace_all ? occurrences : 1
+        new_content =
+          if replace_all
+            # Block form bypasses gsub's \1 / \& interpolation on the
+            # replacement String — we want literal substitution.
+            content.gsub(needle) { patch }
+          else
+            idx = content.index(needle)
+            content.byteslice(0, idx) + patch + content.byteslice(idx + needle.bytesize, content.bytesize - idx - needle.bytesize)
+          end
+
+        final = crlf ? new_content.gsub("\n", "\r\n") : new_content
+        resolved.write(final)
+
+        "Edited #{path}: replaced #{replaced} occurrence#{replaced == 1 ? '' : 's'}."
+      rescue Tool::Workspace::Error => e
+        "Error: #{e.message}"
+      rescue Errno::EACCES => e
+        "Error: cannot edit #{path}: #{e.message}"
+      end
+
+      # Force a String to BINARY encoding and collapse +\r\n+ → +\n+ so
+      # all matching/replacement happens in LF space with byte-stable
+      # comparisons. Applied to the file content, +old_string+, and
+      # +new_string+ alike — symmetric normalization keeps the byte-match
+      # semantics consistent across all three inputs.
+      #
+      # @param str [String]
+      # @return [String] BINARY-encoded, CRLF-collapsed copy
+      def self.normalize_lf(str)
+        str.b.gsub("\r\n", "\n")
+      end
+      private_class_method :normalize_lf
+    end
+  end
+end

data/lib/pikuri/tool/glob.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Tool
+    # The +glob+ tool — list files matching a glob pattern via
+    # +rg --files+, sorted by modification time (newest first).
+    # Instantiating +Tool::Glob.new(workspace: ws)+ produces a tool
+    # whose {Tool#to_ruby_llm_tool} wiring is identical to any bundled
+    # tool's. Same shape as {Tool::Grep} (workspace captured by the
+    # +execute+ closure, no confirmer — read-only).
+    #
+    # == Why a separate tool from Grep
+    #
+    # The unique capability is *mtime-descending sort* — "what's been
+    # touched recently" is a common navigation move and Grep can't
+    # express it. The rest (filter by name, default to listing all
+    # matching files) is theoretically reachable through Grep with
+    # +pattern="."+, but Glob avoids that hack and keeps Read / Grep /
+    # Glob as three clean roles: read one file, search content, list
+    # files by name.
+    #
+    # == ripgrep dependency
+    #
+    # Hard dependency: {.check_binaries!} runs in +initialize+ and
+    # raises if +rg+ isn't on +PATH+. Each tool owns its own probe so
+    # construction order doesn't matter — Glob doesn't lean on Grep's
+    # check.
+    #
+    # == Argv & filter pipeline
+    #
+    #   rg --files --color=never --hidden --glob '!.git/*' \
+    #      -- <relative-path-or-dot>
+    #   # …then filter the result list in Ruby with File.fnmatch?
+    #
+    # Why not pass the user pattern as +--glob+ to rg? Because rg's
+    # +--glob+ documentation says *"This always overrides any other
+    # ignore logic"* — so +--glob '**/*.rb'+ would re-include
+    # +.gitignore+'d Ruby files, breaking our gitignore-respect
+    # promise. We let rg produce the full gitignore-respecting file
+    # list and filter to the user's pattern in Ruby with
+    # +File.fnmatch?(pattern, p, FNM_PATHNAME | FNM_EXTGLOB |
+    # FNM_DOTMATCH)+. The three flags together cover the common rg
+    # glob cases: +**+ recursion (+FNM_PATHNAME+), +{a,b}+ alternation
+    # (+FNM_EXTGLOB+), and dotfile inclusion (+FNM_DOTMATCH+, matching
+    # rg's +--hidden+ behavior). The +.git/+ exclusion stays on the rg
+    # side so its contents never even reach the Ruby filter.
+    #
+    # * +--hidden+ → search dotfiles (still respects +.gitignore+).
+    # * No +--sort+ flag: we re-sort by mtime in Ruby on the way out.
+    # * Output paths come back as +./...+ when the search path is +.+;
+    #   the leading +./+ is stripped post-rg so the model sees clean
+    #   workspace-relative paths.
+    #
+    # == Sort
+    #
+    # mtime-descending in Ruby after rg returns, with path-ascending
+    # as a tiebreaker for files with equal mtimes (the common case in
+    # fresh checkouts). Cost: one +stat+ per result. Broad patterns
+    # can make this expensive, but in practice rg's +.gitignore+ filter
+    # keeps result sets bounded; if real friction shows up later we can
+    # cap pre-sort.
+    #
+    # == Truncation
+    #
+    # Total output head-truncated to {MAX_BYTES} *after* mtime sort, so
+    # the kept rows are the newest. Matches {Tool::Grep}'s budget and
+    # head-bias.
+    #
+    # == Exit codes
+    #
+    # * +0+ → at least one file; format with footer.
+    # * +1+ → no files; return +"No files match pattern '...'"+.
+    # * +2+ → rg error (bad path, bad glob); return
+    #   +"Error: ripgrep: ..."+.
+    #
+    # == Refusals
+    #
+    # All returned as +"Error: ..."+ observations:
+    #
+    # * Empty +pattern+ → fast reject.
+    # * +path+ is a regular file → fast reject pointing at the +read+
+    #   tool.
+    # * +path+ not found → +"Error: path not found: <path>"+.
+    # * +path+ outside the workspace → caught from
+    #   {Tool::Workspace::Error}.
+    class Glob < Tool
+      # @return [Integer] hard byte cap on combined rg output. Same
+      #   value as {Tool::Grep::MAX_BYTES} so the two file-touching
+      #   tools share a budget shape. Re-declared here rather than
+      #   referenced cross-file because Zeitwerk's eager-load order
+      #   isn't guaranteed between siblings.
+      MAX_BYTES = 50 * 1024
+
+      # @return [String] human-readable form of {MAX_BYTES} for the
+      #   truncation marker.
+      MAX_BYTES_LABEL = "#{MAX_BYTES / 1024} KB"
+
+      # Description shown to the LLM. opencode-shape (summary +
+      # +Usage:+ bullets). Per-parameter constraints live in parameter
+      # descriptions.
+      #
+      # @return [String]
+      DESCRIPTION = <<~DESC
+        List files matching a glob pattern, sorted by modification time (newest first).
+
+        Usage:
+        - `.gitignore` is respected; for unfiltered listing use bash `rg --no-ignore --files -g <pattern>`.
+        - Glob syntax: `**` matches any number of directories, `*` matches any filename chars (not `/`), `{a,b}` is alternation.
+        - Default search root is the workspace root; pass `path` to narrow to a subdirectory.
+        - Use `glob` to find files by name; use `grep` to find files by content.
+        - Output is sorted by mtime descending — recently-touched files come first, so broad patterns still surface relevant files near the top.
+        - Output is truncated to #{MAX_BYTES_LABEL}; refine the pattern or narrow `path` if the response ends in a truncation marker.
+      DESC
+
+      # @param workspace [Tool::Workspace] captured for path resolution
+      #   and as +chdir+ for rg. All path arguments route through
+      #   +workspace.resolve_for_read+.
+      # @raise [RuntimeError] if +rg+ isn't on +PATH+; fail-loud at
+      #   construction rather than the first tool call.
+      # @return [Glob]
+      def initialize(workspace:)
+        Glob.send(:check_binaries!)
+        super(
+          name: 'glob',
+          description: DESCRIPTION,
+          parameters: Parameters.build { |p|
+            p.required_string :pattern,
+                              'Glob pattern (** matches any number of ' \
+                              'directories; {a,b} alternation), e.g. ' \
+                              '"**/*.rb" or "lib/**/*_spec.rb".'
+            p.optional_string :path,
+                              'Directory to search in. Relative paths resolve ' \
+                              'against the workspace root. Defaults to the ' \
+                              'workspace root, e.g. "lib/" or "spec/".'
+          },
+          execute: lambda { |pattern:, path: nil|
+            Glob.search(workspace: workspace, pattern: pattern, path: path)
+          }
+        )
+      end
+
+      # Validate inputs, resolve the path against the workspace, spawn
+      # rg, mtime-sort, head-truncate, render. Returns either the
+      # formatted listing, a "no files match" message, or
+      # +"Error: ..."+.
+      #
+      # @param workspace [Tool::Workspace]
+      # @param pattern [String]
+      # @param path [String, nil]
+      # @return [String]
+      def self.search(workspace:, pattern:, path:)
+        return 'Error: empty pattern.' if pattern.empty?
+
+        search_target = '.'
+        if path
+          resolved = workspace.resolve_for_read(path)
+          return "Error: path not found: #{path}" unless resolved.exist?
+          if resolved.file?
+            return "Error: #{path} is a file, not a directory; use the read tool to view it."
+          end
+
+          rel = resolved.relative_path_from(workspace.cwd).to_s
+          search_target = rel
+        end
+
+        argv = build_argv(path: search_target)
+        result = Pikuri::Subprocess.spawn(*argv, chdir: workspace.cwd.to_s).wait
+        exit_code = result.status.exitstatus
+
+        case exit_code
+        when 0
+          format_output(result.output, workspace: workspace,
+                        pattern: pattern, path: path)
+        when 1
+          no_match_message(pattern: pattern, path: path)
+        else
+          stderr = result.output.strip
+          stderr = "exited #{exit_code}" if stderr.empty?
+          "Error: ripgrep: #{stderr}"
+        end
+      rescue Tool::Workspace::Error => e
+        "Error: #{e.message}"
+      end
+
+      # @return [Integer] flags for {File.fnmatch?}: +FNM_PATHNAME+ for
+      #   +**+ recursion + path-aware +/+ matching, +FNM_EXTGLOB+ for
+      #   +{a,b}+ alternation, +FNM_DOTMATCH+ to match dotfiles (rg
+      #   does this when +--hidden+ is set).
+      FNMATCH_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB | File::FNM_DOTMATCH
+
+      # Build the +rg+ argv. User pattern is NOT passed to rg — see
+      # the class header for why (rg's +--glob+ overrides
+      # +.gitignore+).
+      #
+      # @return [Array<String>]
+      def self.build_argv(path:)
+        [
+          'rg',
+          '--files',
+          '--color=never',
+          '--hidden',
+          '--glob', '!.git/*',
+          '--', path
+        ]
+      end
+      private_class_method :build_argv
+
+      # Strip the +./+ prefix rg adds when invoked with +.+ as the
+      # search path, filter to the user pattern with +fnmatch+,
+      # mtime-sort descending (path ascending as tiebreaker),
+      # head-truncate at {MAX_BYTES}, append a footer summarizing the
+      # count.
+      #
+      # @return [String]
+      def self.format_output(raw, workspace:, pattern:, path:)
+        all_paths = raw.split("\n").reject(&:empty?).map { |p| p.sub(%r{\A\./}, '') }
+        paths = all_paths.select { |p| File.fnmatch?(pattern, p, FNMATCH_FLAGS) }
+        return no_match_message(pattern: pattern, path: path) if paths.empty?
+
+        sorted = mtime_sort(paths, workspace.cwd)
+        joined = sorted.join("\n") + "\n"
+        content, truncation_marker = head_truncate(joined)
+        stripped = content.chomp
+        count = stripped.split("\n").size
+
+        footer = "Found #{pluralize(count, 'file', 'files')}."
+        [stripped, '', footer + truncation_marker].join("\n")
+      end
+      private_class_method :format_output
+
+      # mtime descending; path ascending for stable order on ties.
+      #
+      # @return [Array<String>]
+      def self.mtime_sort(paths, cwd)
+        paths
+          .map { |p| [p, mtime_of(cwd + p)] }
+          .sort_by { |(p, m)| [-m, p] }
+          .map(&:first)
+      end
+      private_class_method :mtime_sort
+
+      # @return [Float] epoch-seconds mtime; 0 for paths we can't stat
+      #   (race between rg listing and our stat, deleted symlinks,
+      #   etc.). The fallback puts unstattable entries at the bottom.
+      def self.mtime_of(absolute)
+        File.mtime(absolute).to_f
+      rescue Errno::ENOENT
+        0.0
+      end
+      private_class_method :mtime_of
+
+      # Head-truncate +raw+ to {MAX_BYTES}, cutting at the last newline
+      # boundary so the final row is never partial. Returns the
+      # truncated content and a marker String (empty if no truncation).
+      #
+      # @return [Array(String, String)]
+      def self.head_truncate(raw)
+        total = raw.bytesize
+        return [raw, ''] if total <= MAX_BYTES
+
+        head = raw.byteslice(0, MAX_BYTES)
+        last_nl = head.rindex("\n")
+        head = head.byteslice(0, last_nl) if last_nl
+        omitted = total - head.bytesize
+        marker = "\n\n... [#{omitted} bytes omitted; total was #{total} bytes; " \
+                 'refine pattern or path] ...'
+        [head, marker]
+      end
+      private_class_method :head_truncate
+
+      # @return [String]
+      def self.no_match_message(pattern:, path:)
+        base = "No files match pattern '#{pattern}'"
+        base += " in #{path}" if path
+        "#{base}."
+      end
+      private_class_method :no_match_message
+
+      # @return [String] +"1 file"+ / +"2 files"+
+      def self.pluralize(n, sing, plural)
+        "#{n} #{n == 1 ? sing : plural}"
+      end
+      private_class_method :pluralize
+
+      # Verify +rg+ is reachable on +PATH+. Routed through
+      # {Pikuri::Subprocess.spawn} to honor the subprocess seam. rg
+      # missing surfaces as +Errno::ENOENT+; an installed rg returns
+      # exit 0 from +--version+.
+      #
+      # @return [void]
+      # @raise [RuntimeError] if rg is missing
+      def self.check_binaries!
+        result = Pikuri::Subprocess.spawn('rg', '--version', chdir: '/').wait
+        return if result.status.success?
+
+        raise install_hint
+      rescue Errno::ENOENT
+        raise install_hint
+      end
+      private_class_method :check_binaries!
+
+      # @return [String]
+      def self.install_hint
+        "Tool::Glob requires 'rg' (ripgrep) on PATH; install via your " \
+          "distro's package manager (e.g. 'apt install ripgrep')."
+      end
+      private_class_method :install_hint
+    end
+  end
+end