oh-my-opencode-slim/src/tools/grep/codemap.md

src/tools/grep/

The folder implements the grep tool that powers ripgrep/grep-based searches for the OpenCode ecosystem. It exposes shared helpers for resolving/running the CLI, parsing output, downloading a bundled ripgrep when missing, and wiring the tool definition that the plugin host uses.

Responsibility

Serve as the authoritative implementation of the fast content-search tool. It discovers which binary to run (rg vs fallback grep), enforces safety defaults (timeouts, max files/size/depth), parses the child-process output, formats readable responses, and exposes the ready-to-use tool definition consumed by the CLI/plugin layer.

Design

The module is structured around a few focused responsibilities: constants.ts holds the configuration (safety flags, defaults) and a cached resolveGrepCli/resolveGrepCliWithAutoInstall that looks for bundled/system binaries before installing ripgrep from downloader.ts (platform aware fetch + extract). cli.ts encapsulates backend-agnostic argument builders (buildRgArgs/buildGrepArgs), output parsers, and the top-level runRg/runRgCount functions that spawn the tool via Bun, apply timeouts, and convert stdout/stderr into typed results. tools.ts wraps runRg with formatGrepResult (which groups matches by file) into a @opencode-ai/plugin/tool definition. index.ts re-exports the key APIs so other systems can import the grep functionality without knowing internal layout.

Flow

1. Callers pass GrepOptions to runRg (or runRgCount); the CLI module first resolves the best backend via resolveGrepCli, which itself may probe bundled paths, the system rg, a cached install under ~/.cache/oh-my-opencode-slim/bin, or finally grep. 2. buildArgs chooses rg versus grep flag sets, adds safety arguments, globs, excludes, and finally the search pattern and paths. 3. Bun spawns the selected executable with the assembled arguments and a timeout promise; stdout is read, truncated if necessary, and converted into GrepMatch objects via parseOutput/parseCountOutput. 4. The parsed matches are returned as a GrepResult, which tools.ts later formats (formatGrepResult) with grouped file sections before presenting to the user.

Integration

constants.ts imports downloader.ts to provide a self-installing ripgrep bundle when the preferred CLI is missing. runRg/runRgCount are the primary exports consumed elsewhere via src/tools/grep/index.ts, which also re-exports the resolver helpers and downloader entry points for reuse. This folder feeds the plugin registry in tools.ts so that the grep tool appears in the OpenCode tool suite, and other modules (e.g., higher-level CLI handlers) can orchestrate searches without dealing with binaries or parsing. The downloader taps ../../utils for extractZip, and all exports are typed through types.ts so other callers can rely on GrepResult/CountResult contracts.