feat: implement encoding conversion to UTF-8 (F-001)

Re-saves the current document as UTF-8 when convertEncodingButton is
clicked; emits encoding_detected, file_saved, and error_occurred signals.
No-op when already UTF-8 or no document is loaded.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: chrisdpurcell

src/viewmodels/main_viewmodel.py

@@ -163,3 +163,38 @@ def replace_all(
         self.content_updated.emit(new_content)
         noun = "occurrence" if count == 1 else "occurrences"
         self.status_changed.emit(f"Replaced {count} {noun}")
+
+    @Slot(str)
+    def convert_to_utf8(self, current_text: str) -> None:
+        """Re-save the current document in UTF-8 encoding.
+
+        Args:
+            current_text: Live editor text from the View. Used as the content
+                to save (preserves unsaved edits).
+
+        No-op when no document is loaded or the file is already UTF-8.
+        Encoding comparison normalises dashes so 'utf-8' and 'utf8' both match.
+        """
+        if self._current_document is None:
+            self.status_changed.emit("No document loaded")
+            return
+        # Normalise: strip dashes and lowercase so 'UTF-8', 'utf-8', 'utf8' all match.
+        current_encoding = self._current_document.encoding.lower().replace("-", "")
+        if current_encoding in ("utf8",):
+            self.status_changed.emit("File is already UTF-8")
+            return
+        doc = TextDocument(
+            filepath=self._current_document.filepath,
+            content=current_text,
+            encoding="utf-8",
+        )
+        try:
+            self._file_service.save_file(doc)
+            self._current_document = doc
+            self.encoding_detected.emit("utf-8")
+            self.file_saved.emit(doc.filepath)
+            self.status_changed.emit(f"Converted to UTF-8: {doc.filepath}")
+        except (ValueError, PermissionError, OSError) as e:
+            msg = f"Cannot convert file: {e}"
+            logger.error(msg)
+            self.error_occurred.emit(msg)

src/views/main_window.py

@@ -208,9 +208,9 @@ def _connect_signals(self) -> None:
         self._replace_button.clicked.connect(self._on_replace_clicked)
         self._replace_all_button.clicked.connect(self._on_replace_all_clicked)
 
-        # Encoding convert is stubbed for v1
+        # Encoding conversion: pass live editor text so unsaved edits are preserved
         self._convert_button.clicked.connect(
-            lambda: self.ui.statusBar().showMessage("Encoding conversion — coming soon")
+            lambda: self._viewmodel.convert_to_utf8(self._plain_text_edit.toPlainText())
         )
 
         # Menu actions

tests/integration/test_main_window.py

@@ -405,3 +405,13 @@ def test_f3_triggers_find_next(self, window, qtbot):
         assert window._plain_text_edit.textCursor().selectedText() == "hello"
         pos_after_second = window._plain_text_edit.textCursor().position()
         assert pos_after_second > pos_after_first
+
+
+class TestConvertEncodingHandler:
+    def test_convert_button_calls_viewmodel(self, window, qtbot):
+        """Clicking the Convert button must call viewmodel.convert_to_utf8."""
+        from unittest.mock import patch
+        window._plain_text_edit.setPlainText("hello")
+        with patch.object(window._viewmodel, "convert_to_utf8") as mock_convert:
+            window._convert_button.click()
+        mock_convert.assert_called_once_with("hello")

tests/unit/test_main_viewmodel.py

@@ -148,3 +148,65 @@ def test_replace_all_uses_current_text_when_provided(self, vm, qtbot):
         with qtbot.waitSignal(vm.content_updated, timeout=1000) as blocker:
             vm.replace_all("hello", "goodbye", current_text="hello hello")
         assert blocker.args[0] == "goodbye goodbye"
+
+
+class TestConvertToUtf8:
+    def test_saves_file_with_utf8_encoding(self, vm, mock_file_svc, qtbot):
+        """convert_to_utf8 must call save_file with encoding='utf-8'."""
+        from src.models.text_document import TextDocument
+        mock_file_svc.open_file.return_value = TextDocument(
+            filepath="/tmp/latin.txt", content="caf\u00e9", encoding="ISO-8859-1"
+        )
+        vm.load_file("/tmp/latin.txt")
+        vm.convert_to_utf8("café")
+        saved_doc = mock_file_svc.save_file.call_args[0][0]
+        assert saved_doc.encoding == "utf-8"
+        assert saved_doc.content == "café"
+
+    def test_emits_encoding_detected_utf8(self, vm, mock_file_svc, qtbot):
+        """convert_to_utf8 must emit encoding_detected('utf-8')."""
+        from src.models.text_document import TextDocument
+        mock_file_svc.open_file.return_value = TextDocument(
+            filepath="/tmp/latin.txt", content="caf\u00e9", encoding="ISO-8859-1"
+        )
+        vm.load_file("/tmp/latin.txt")
+        with qtbot.waitSignal(vm.encoding_detected, timeout=1000) as blocker:
+            vm.convert_to_utf8("café")
+        assert blocker.args[0] == "utf-8"
+
+    def test_emits_file_saved(self, vm, mock_file_svc, qtbot):
+        """convert_to_utf8 must emit file_saved after a successful save."""
+        from src.models.text_document import TextDocument
+        mock_file_svc.open_file.return_value = TextDocument(
+            filepath="/tmp/latin.txt", content="caf\u00e9", encoding="ISO-8859-1"
+        )
+        vm.load_file("/tmp/latin.txt")
+        with qtbot.waitSignal(vm.file_saved, timeout=1000) as blocker:
+            vm.convert_to_utf8("café")
+        assert blocker.args[0] == "/tmp/latin.txt"
+
+    def test_no_op_when_already_utf8(self, vm, mock_file_svc, qtbot):
+        """convert_to_utf8 must not save when encoding is already utf-8."""
+        from src.models.text_document import TextDocument
+        mock_file_svc.open_file.return_value = TextDocument(
+            filepath="/tmp/utf8.txt", content="hello", encoding="utf-8"
+        )
+        vm.load_file("/tmp/utf8.txt")
+        vm.convert_to_utf8("hello")
+        mock_file_svc.save_file.assert_not_called()
+
+    def test_no_op_when_no_document(self, vm, qtbot):
+        """convert_to_utf8 with no loaded document must be silent."""
+        vm.convert_to_utf8("some text")  # must not raise
+
+    def test_emits_error_on_save_failure(self, vm, mock_file_svc, qtbot):
+        """convert_to_utf8 must emit error_occurred when save_file raises."""
+        from src.models.text_document import TextDocument
+        mock_file_svc.open_file.return_value = TextDocument(
+            filepath="/tmp/latin.txt", content="caf\u00e9", encoding="ISO-8859-1"
+        )
+        vm.load_file("/tmp/latin.txt")
+        mock_file_svc.save_file.side_effect = PermissionError("read-only")
+        with qtbot.waitSignal(vm.error_occurred, timeout=1000) as blocker:
+            vm.convert_to_utf8("café")
+        assert "Cannot convert" in blocker.args[0]