feat: add --path flag to filter diff to a specific file or directory

[anpryl]

Summary

Adds several features for AI agent integration workflows:

1. --path flag — filters diff view to a specific file or directory
2. --file flag — opens any file for annotation without requiring a VCS repository
3. --stdout escape fix — prevents garbage in captured export output

Also fixes #203

Use Case: AI Agent Integration

tuicr's README describes the core workflow: "Let the agent loose, review the changes like a PR, drop comments where needed, and export everything as structured feedback." These features extend tuicr for document-driven review workflows.

The Problem

When using tuicr as part of an automated review workflow (e.g., an AI coding agent writes a design document, then opens tuicr for the user to annotate):

1. --path problem: Without it, tuicr shows every changed file in the working tree — the user has to manually navigate to the relevant file
2. --file problem: The document may not be committed (or even tracked by git). Currently tuicr requires a VCS repository, so reviewing an arbitrary file means staging it first and cleaning up after
3. --stdout problem: Keyboard enhancement probe writes escape sequences to stdout before the /dev/tty redirect is established, leaking binary garbage into captured output

The Solution

# Review a file without needing git/hg/jj at all
tuicr --file plans/design.md --stdout

# Review only a specific file within a git diff
tuicr --path plans/design.md --stdout

# Review only files in a directory
tuicr --path src/components/

Real-World Workflow

This is used in a "review-plan" skill for Claude Code:

1. Agent writes a design document to plans/feature-x.md
2. Agent launches tuicr --file plans/feature-x.md --stdout in a tmux popup
3. User reviews the document, leaves comments using tuicr's annotation features
4. User exits with :wq — comments are exported to stdout
5. Agent reads the structured feedback and revises the document

No git add needed. No VCS repo needed. Just a file and tuicr.

Details

--file flag (src/vcs/file.rs, src/vcs/traits.rs, src/app.rs, src/main.rs, src/theme/mod.rs)

• FileBackend (src/vcs/file.rs): New VcsBackend implementation that reads a file and presents it as a synthetic "all lines added" diff with syntax highlighting — no git, hg, or jj required
• VcsType::File (src/vcs/traits.rs): New variant for the file-only backend
• CLI parsing (src/theme/mod.rs): Adds file_path: Option<String> to CliArgs, parses --file <PATH> and --file=<PATH> forms
• Mutual exclusivity (src/main.rs): --file cannot be combined with --path, -r, or -w
• App integration (src/app.rs): New code path in App::new that uses FileBackend, hides file list panel, and focuses on the diff view

--path flag (src/theme/mod.rs, src/app.rs, src/main.rs)

• CLI parsing (src/theme/mod.rs): Adds path_filter: Option<String> to CliArgs, parses -p/--path <PATH> and --path=<PATH> forms with validation
• Filtering (src/app.rs): New filter_by_path() method filters DiffFiles by exact filename match or directory prefix. Applied consistently across all diff retrieval paths
• Auto-hide file list (src/app.rs): When path filter matches exactly one file, show_file_list is set to false and focus moves to the diff panel
• Implicit --working-tree (src/main.rs): --path implies --working-tree unless -r is explicitly provided
• 8 unit tests for CLI parsing edge cases

--stdout escape fix (src/main.rs)

• Skip supports_keyboard_enhancement() probe when --stdout is active — keyboard enhancement is a minor UX improvement that doesn't affect core functionality

Compatibility

• No breaking changes to existing CLI behavior
• All new flags are opt-in; without them, tuicr behaves exactly as before
• The --stdout fix only changes behavior when --stdout is already in use
• All existing tests pass

Testing

# --file: review any file without a VCS repo
tuicr --file README.md
tuicr --file /tmp/notes.md --stdout

# --path: scope to a specific file in a git diff
echo "test" >> README.md && tuicr -p README.md

# --path: directory filter
tuicr -p src/

# --stdout: clean output
tuicr --file README.md --stdout

# mutual exclusivity: should error
tuicr --file foo.md --path bar.md
tuicr --file foo.md -w

[agavra]

Very cool feature, thanks @anpryl - I tested it locally and confirmed it works. This also fixes #203, since you're the second reporter of this I think it's acceptable to disable advanced keyboard shortcuts in this situation.

[agavra]

Ah @anpryl I realized late this was a draft PR, I converted it back. LMK when you're ready to merge and I will merge it.

[anpryl]

@agavra It is ready for review!