feat(core): Add FileSystemHandler with atomic writes (Issue #6)

[raifdmueller]

Summary

Implements the File System Handler component (Issue #6) with atomic read/write operations as specified in ADR-004.

Implementation Details

ADR-004 Backup-and-Replace Strategy

1. Create backup of original file (.bak)
2. Write changes to temporary file (.tmp)
3. Atomically rename temp file to replace original
4. Delete backup on success
5. On error: restore from backup, cleanup temp files

API

class FileSystemHandler:
    def read_file(self, path: Path | str) -> str
    def read_lines(self, path: Path | str, start: int, end: int) -> list[str]
    def write_file(self, path: Path | str, content: str) -> None
    def update_section(self, path: Path | str, start_line: int, end_line: int, new_content: str) -> None

Features

• Custom exceptions: FileReadError, FileWriteError
• UTF-8 encoding with proper error handling
• 1-based line numbers for line operations
• Path and str input support
• Debug logging for operations

Test Coverage (35 tests)

• Read operations: success, UTF-8, empty files, not found, permission denied, encoding errors
• Line range: single line, range, validation, out of bounds
• Atomic write: success, new file creation, no .bak/.tmp files remain, error recovery
• Section updates: middle, first line, last line, expand, shrink
• Edge cases: files without trailing newline, path as string

Self Code Review

• ADR-004 compliance verified
• Error handling with exception chaining
• Cleanup on all error paths
• Thread safety documented (not safe, external locking needed)
• All 35 tests pass
• Linting passes

Closes #6

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR implements the File System Handler component (Issue #6) with atomic read/write operations following the ADR-004 backup-and-replace strategy. The implementation provides UTF-8 file operations with comprehensive error handling and atomic writes to prevent file corruption.

Changes:

• Added FileSystemHandler class with read_file(), read_lines(), write_file(), and update_section() methods
• Implemented custom exceptions FileReadError and FileWriteError for clear error reporting
• Created comprehensive test suite with 35 tests covering success paths, error scenarios, and edge cases

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
src/mcp_server/file_handler.py	Implements FileSystemHandler with atomic write operations per ADR-004, including backup-and-replace strategy, UTF-8 encoding support, and line-based section updates
tests/test_file_system_handler.py	Comprehensive test suite with 35 tests covering read operations, atomic writes, section updates, error handling, and edge cases like files without trailing newlines

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.