Skip to content

interactive-diffs.md

Latest commit

 

History

History
53 lines (44 loc) · 3.6 KB

interactive-diffs.md

File metadata and controls

53 lines (44 loc) · 3.6 KB
title Interactive diffs
description Design for reviewing and accepting agent-proposed file changes in the TUI.
product drover-code
audience platform-operator
doc_type how-to
topics
agent-jobs
surface repo-docs

Interactive Diffs Design Document

1. Overview

The Interactive Diffs feature allows users to review and selectively apply agent-proposed file edits at a hunk-by-hunk level before they are written to disk. This functionality mirrors industry best practices for safe, auditable autonomous coding agents and integrates deeply with Drover Code's TUI.

2. Core Components

2.1 Unified Diff Parser (internal/tui/diff/parser.go)

  • Responsibility: Parses unified diffs generated by the fs.PreviewEdit function.
  • Implementation: Processes standard patch format headers (@@ -start,length +start,length @@) and correctly parses contextual lines, deletions (-), and additions (+).
  • Data Model: Extracted Hunks contain OldStart, OldLines, RawLines, and independent Accepted and Rejected toggles.

2.2 Terminal UI Model (internal/tui/diff/model.go)

  • Responsibility: Displays the interactive diff review prompt.
  • Keybindings:
    • j/k or Up/Down arrow keys to navigate hunks.
    • Space or t to toggle hunk selection (Accept/Reject).
    • A to accept all, R to reject all, C to clear selections.
    • Enter to confirm and apply the selected hunks.
    • q or Esc to cancel the interactive diff session.
  • Integration: The diffModel intercepts key events inside the main TUI loop when m.showingDiff == true, deferring regular TUI logic until the user commits to a decision.

2.3 Safe Patch Applier (internal/tui/diff/applier.go)

  • Responsibility: Safely mutates the file on disk by strictly applying the Accepted hunks.
  • Safety Mechanism: Reverses hunk application (from bottom to top) to ensure line-numbering mutations do not offset prior hunks. Context lines are verified and selectively managed without relying on an external unified diff utility that could overwrite or squash the user's intent.
  • Atomicity: Follows toolutil.WriteAtomic principles by writing to a temporary file before renaming it to the final destination, avoiding partial file corruption if an interrupt occurs.

2.4 Agent Loop Orchestration (internal/agent/loop.go)

  • Responsibility: Bypasses tool execution when the interactive diff has manually applied the changes.
  • Workflow:
    1. The LLM invokes edit_file.
    2. The TUI detects the permission request for edit_file, intercepts the request, and previews the file using fs.PreviewEdit().
    3. The DiffModel is presented.
    4. Upon Enter, the TUI writes to disk and returns the new tools.AppliedManually decision.
    5. The execution engine recognizes tools.AppliedManually and directly injects a success ToolResultBlock into the prompt buffer, skipping the actual edit_file execution.

3. Testing and Validation

  • Unit Testing: Verified via internal/tui/diff/diff_test.go, which specifically tests the parser for accurate line counts and the Patch Applier for executing simulated diff patches on isolated files.
  • Fuzz/End-To-End Testing: The main test harnesses ensure the compilation integrity of the new interactive UI integrations across all terminal architectures without crashing.

4. Security & Governance

This module strictly acts within the established layer-6 Governance policies. Agents still cannot bypass file execution without TUI rendering. In automated (headless) workflows, tools.AppliedManually is skipped entirely, forcing adherence to standard policy engine rules.