---
phase: 01-ripgrep-integration
plan: 1
type: execute
wave: 1
depends_on: []
files_modified:
  - "src/fs_mcp/server.py"
  - "src/fs_mcp/tools.py"
  - "tests/test_tools.py"
autonomous: false

must_haves:
  truths:
    - "Server checks for ripgrep on startup."
    - "Server logs a warning if ripgrep is missing."
    - "Server provides platform-specific install instructions if ripgrep is missing."
    - "Agent can call a `grep_content` tool."
    - "`grep_content` returns bounded results with file paths, line numbers, and context."
    - "`grep_content` handles 'no matches' and 'timeout' scenarios gracefully."
  artifacts:
    - path: "src/fs_mcp/utils.py"
      provides: "Ripgrep availability check and platform-specific install instructions."
    - path: "src/fs_mcp/tools.py"
      provides: "The `grep_content` tool."
    - path: "tests/test_tools.py"
      provides: "Unit tests for the `grep_content` tool."
  key_links:
    - from: "src/fs_mcp/server.py"
      to: "src/fs_mcp/utils.py"
      via: "calling the ripgrep check on startup"
    - from: "src/fs_mcp/tools.py"
      to: "subprocess.run"
      via: "executing the 'rg' command"
---

<objective>
Implement Ripgrep dependency check and the core `grep_content` tool.

Purpose: To provide a robust content search capability for the agent, with graceful degradation if the `ripgrep` dependency is not met.
Output: A new `grep_content` tool, and a server that checks for `ripgrep` on startup.
</objective>

<execution_context>
@~/.config/opencode/get-shit-done/workflows/execute-plan.md
@~/.config/opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/01-ripgrep-integration/01-DISCOVERY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Implement Ripgrep Availability Check</name>
  <files>
    - "src/fs_mcp/utils.py"
    - "src/fs_mcp/server.py"
  </files>
  <action>
  1.  Create a new file `src/fs_mcp/utils.py`.
  2.  In `utils.py`, create a function `check_ripgrep()` that:
      -   Uses `shutil.which('rg')` to check if `ripgrep` is installed.
      -   If not found, it uses `platform.system()` and `distro.id()` to determine the OS and provide the correct install command (brew, choco, apt, dnf).
      -   Returns a tuple of `(is_installed: bool, message: str)`. The message should contain the installation instructions if `is_installed` is `False`.
  3.  In `src/fs_mcp/server.py`, at startup:
      -   Call `check_ripgrep()`.
      -   If `ripgrep` is not installed, log a warning to the console with the installation instructions.
      -   Set a global flag or a state in the server application context to indicate that the `grep_content` tool should be disabled.
  </action>
  <verify>
  - Run the server without `ripgrep` installed. Verify that a warning is logged with the correct installation instructions for your platform.
  - Install `ripgrep` and run the server again. Verify that no warning is logged.
  </verify>
  <done>
  The server correctly detects the presence of `ripgrep` and provides platform-specific installation instructions if it's missing.
  </done>
</task>

<task type="auto">
  <name>Task 2: Implement the `grep_content` tool</name>
  <files>
    - "src/fs_mcp/tools.py"
    - "tests/test_tools.py"
  </files>
  <action>
  1. In `src/fs_mcp/tools.py`, create a new tool function `grep_content(pattern: str, search_path: str = '.', case_insensitive: bool = False, context_lines: int = 2)`.
  2. If the `ripgrep` availability flag (from Task 1) is `False`, the tool should immediately return a helpful error message with installation instructions.
  3. The tool will execute `ripgrep` using `subprocess.run`. Construct the `rg` command with the following arguments:
      - `--json` for structured output.
      - `--max-count=100` to bound the results.
      - `--ignore-case` if `case_insensitive` is `True`.
      - `--context={context_lines}` for context lines.
      - The `pattern` and `search_path`.
  4. The command should have a timeout of 10 seconds.
  5. The `search_path` should be validated to be within the allowed directories.
  6. Parse the JSON output from `ripgrep`. Handle the case where there are no matches (ripgrep exits with code 1).
  7. Format the results into a clear, readable string for the agent, including file paths, line numbers, and the matched text with context.
  8. In `tests/test_tools.py`, add unit tests for the `grep_content` tool, covering success cases, no-matches cases, and timeout cases.
  </action>
  <verify>
  - `pytest tests/test_tools.py` should pass.
  - Manually call the `grep_content` tool and verify that it returns the expected output for a known pattern in the codebase.
  - Test the error handling for no matches and timeouts.
  </verify>
  <done>
  The `grep_content` tool is implemented, tested, and ready for use by the agent.
  </done>
</task>

<task type="checkpoint:human-verify" gate="blocking">
  <name>Task 3: Verify Ripgrep Integration</name>
  <what-built>
  The `ripgrep` dependency check on server startup and the new `grep_content` tool.
  </what-built>
  <how-to-verify>
  1.  Ensure `ripgrep` is NOT installed on your system.
  2.  Start the server. Verify you see a warning message with the correct installation instructions for your OS.
  3.  Attempt to use the `grep_content` tool (e.g., via a test script or an API call). Verify it returns the error message about `ripgrep` not being installed.
  4.  Install `ripgrep` using the instructions provided.
  5.  Restart the server. Verify there is no warning message.
  6.  Use the `grep_content` tool to search for a pattern you know exists in the codebase.
  7.  Verify that you get back the expected results, including file paths, line numbers, and context.
  8.  Try a search that you know will have no matches and verify you get the "No matches found" message.
  </how-to-verify>
  <resume-signal>Type "approved" or describe issues</resume-signal>
</task>

</tasks>

<verification>
- The server starts and checks for `ripgrep`.
- The `grep_content` tool is available and functional if `ripgrep` is installed.
- The `grep_content` tool is gracefully disabled and provides helpful instructions if `ripgrep` is not installed.
</verification>

<success_criteria>
- All requirements for Phase 1 as outlined in `ROADMAP.md` are met.
- The `grep_content` tool is functional and robust.
- The server's startup process correctly handles the `ripgrep` dependency.
</success_criteria>

<output>
After completion, create `.planning/phases/01-ripgrep-integration/01-01-SUMMARY.md`
</output>
