feat(radio): configure file logging + settable log location (quill-radio #5) (#1130)

The standalone app never configured file logging, so everything radio debug mode
raised to DEBUG had nowhere to land. Fix and make it settable:

- apps/radio.main() now calls configure_logging (to RadioHistory.log_dir or the
  default <data_dir>/logs) before the app comes up, keeps the QueueListener,
  hands it to the frame, and stops it on exit.
- RadioHistory.log_dir persists the choice; Preferences (Ctrl+,) gains a
  "Log folder" field that relocates the live log via the new
  logging_config.relocate_log() and persists -- a bad path is a no-op that
  leaves logging working.

Closes the observable-radio work (quill-radio #5): verbose debug mode, ffmpeg
stderr capture, discovery/engine/finalization logging, and settable temp/log
locations all now land in one readable quill.log.

Tests: relocate moves new records + tolerates a bad path; configure writes the
log; log_dir round-trips. apps/radio.py rebaselined 1081 -> 1115 with reason.

Co-authored-by: Jeff Bishop <jeff@community-access.org>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Improved
 
+- **Quill Radio now writes a log, and you can choose where (quill-radio #5).** The standalone app never configured file logging, so debug mode had nowhere to write; it now writes `quill.log` from launch (to `<data>/logs` by default), and **Preferences (Ctrl+,)** gains a **Log folder** field to point it wherever you like -- changing it moves the live log immediately, and a bad path is ignored rather than breaking logging. This completes the observable-radio work: verbose debug mode, ffmpeg stderr capture, discovery/engine/finalization logging, and settable temp/log locations all now land in one readable log.
+
 - **More radio debug logging: playback-engine selection and recording finalization (quill-radio #5).** With radio debug mode on, `quill.log` now also records which playback backend was chosen for a station and why (preference + whether mpv is present), and how each recording ended and where its finished file landed. Internal cleanup rode along: the pure ffmpeg/ffprobe command and filename builders moved out of `recording.py` into a new `recording_commands` module (no behavior change; the recorder module dropped back under its size budget).
 
 - **Radio stream discovery now leaves a debug trail (quill-radio #5).** With radio debug mode on, Find Streams from a Website logs each scanned page and the candidate links it kept (with the reason for each, including the iHeart/TuneIn portal-page follow), and the Triton/StreamTheWorld resolver logs which callsign resolved to how many playable streams -- so a "why didn't this station's stream show up?" question has an answer in `quill.log`. Every logged URL is redacted first. (More per-module coverage -- engine selection, reconnects, recording finalization -- follows with the recording-module decomposition.)

quill/apps/radio.py

@@ -839,6 +839,12 @@ def _open_preferences(self) -> None:
                     _NOW_PLAYING_HELP,
                     history.now_playing_template,
                 ),
+                PreferenceText(
+                    "&Log folder:",
+                    "Where quill.log is written; leave blank for the default. "
+                    "Changing it moves the log immediately.",
+                    history.log_dir,
+                ),
             ],
             actions=[
                 PreferenceAction(
@@ -880,6 +886,19 @@ def _open_preferences(self) -> None:
             self._radio_controller.set_output_device(chosen_device)
         new_template = text_values[0].strip()
         history.now_playing_template = new_template or _DEFAULT_NOW_PLAYING_TEMPLATE
+        new_log_dir = text_values[1].strip()
+        if new_log_dir != history.log_dir:
+            history.log_dir = new_log_dir
+            # Relocate the live log so new records land in the chosen folder now
+            # (quill-radio #5), not just next launch.
+            listener = getattr(self, "_log_listener", None)
+            if listener is not None:
+                from pathlib import Path
+
+                from quill.stability.logging_config import relocate_log
+
+                target = Path(new_log_dir) if new_log_dir else app_data_dir() / "logs"
+                relocate_log(listener, target)
         radio_history.save_history(app_data_dir(), history)
         menu_bar = self.frame.GetMenuBar()
         if menu_bar is not None:
@@ -1070,10 +1089,25 @@ def _on_radio_app_close(self, event: wx.CloseEvent) -> None:
 
 def main() -> int:
     safe_mode = bool(os.environ.get("QUILL_SAFE_MODE"))
+    # Configure file logging before the app comes up so startup records -- and
+    # everything radio debug mode raises to DEBUG -- land in quill.log
+    # (quill-radio #5). The folder is the log-location preference, or the
+    # default <data_dir>/logs.
+    from pathlib import Path
+
+    from quill.core.paths import app_data_dir
+    from quill.core.radio import history as radio_history
+    from quill.stability.logging_config import configure_logging
+
+    history = radio_history.load_history(app_data_dir())
+    log_dir = Path(history.log_dir) if history.log_dir else app_data_dir() / "logs"
+    log_listener = configure_logging(log_dir)
     app = wx.App()
     frame = RadioAppFrame(safe_mode=safe_mode)
+    frame._log_listener = log_listener
     frame.frame.Show()
     app.MainLoop()
+    log_listener.stop()
     return 0
 
 

quill/core/radio/history.py

@@ -1,45 +1,81 @@
-"""Queue-backed logging configuration used during early startup.
-
-Implements: ROADMAP STAB-1 (the rotating-file ``quill.log`` and the
-queue listener that drains log records off the UI thread so a
-flooded log channel never blocks the wx main thread). The handler
-list installed here is what :mod:`quill.stability.crash_report` reads
-when the user saves a diagnostic bundle.
-"""
-
-from __future__ import annotations
-
-import logging
-import logging.handlers
-import queue
-from pathlib import Path
-
-
-def configure_logging(log_dir: Path) -> logging.handlers.QueueListener:
-    log_dir.mkdir(parents=True, exist_ok=True)
-
-    log_queue: queue.Queue[logging.LogRecord] = queue.Queue(maxsize=10_000)
-    queue_handler = logging.handlers.QueueHandler(log_queue)
-
-    root = logging.getLogger()
-    root.setLevel(logging.INFO)
-    root.handlers.clear()
-    root.addHandler(queue_handler)
-
-    file_handler = logging.handlers.RotatingFileHandler(
-        log_dir / "quill.log",
-        maxBytes=5_000_000,
-        backupCount=5,
-        encoding="utf-8",
-    )
-    file_handler.setFormatter(
-        logging.Formatter("%(asctime)s %(levelname)s %(threadName)s %(name)s: %(message)s")
-    )
-
-    listener = logging.handlers.QueueListener(
-        log_queue,
-        file_handler,
-        respect_handler_level=True,
-    )
-    listener.start()
-    return listener
+"""Queue-backed logging configuration used during early startup.
+
+Implements: ROADMAP STAB-1 (the rotating-file ``quill.log`` and the
+queue listener that drains log records off the UI thread so a
+flooded log channel never blocks the wx main thread). The handler
+list installed here is what :mod:`quill.stability.crash_report` reads
+when the user saves a diagnostic bundle.
+"""
+
+from __future__ import annotations
+
+import logging
+import logging.handlers
+import queue
+from pathlib import Path
+
+
+def configure_logging(log_dir: Path) -> logging.handlers.QueueListener:
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    log_queue: queue.Queue[logging.LogRecord] = queue.Queue(maxsize=10_000)
+    queue_handler = logging.handlers.QueueHandler(log_queue)
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    root.handlers.clear()
+    root.addHandler(queue_handler)
+
+    file_handler = logging.handlers.RotatingFileHandler(
+        log_dir / "quill.log",
+        maxBytes=5_000_000,
+        backupCount=5,
+        encoding="utf-8",
+    )
+    file_handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s %(threadName)s %(name)s: %(message)s")
+    )
+
+    listener = logging.handlers.QueueListener(
+        log_queue,
+        file_handler,
+        respect_handler_level=True,
+    )
+    listener.start()
+    return listener
+
+
+def relocate_log(listener: logging.handlers.QueueListener, log_dir: Path) -> None:
+    """Move the active ``quill.log`` to *log_dir* at runtime (quill-radio #5).
+
+    Swaps the listener's rotating-file handler for one writing into *log_dir*,
+    so a user who changes the log-folder preference sees new records land there
+    without a restart. The old handler is closed. A no-op (leaving the current
+    handler in place) if the new directory can't be created, so a bad path
+    never leaves logging broken.
+    """
+    try:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        new_handler = logging.handlers.RotatingFileHandler(
+            log_dir / "quill.log",
+            maxBytes=5_000_000,
+            backupCount=5,
+            encoding="utf-8",
+        )
+    except OSError:
+        logging.getLogger(__name__).warning(
+            "Could not relocate the log to %s; keeping the current location.", log_dir
+        )
+        return
+    new_handler.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s %(threadName)s %(name)s: %(message)s")
+    )
+    old_handlers = list(listener.handlers)
+    listener.stop()
+    listener.handlers = (new_handler,)
+    listener.start()
+    for handler in old_handlers:
+        try:
+            handler.close()
+        except OSError:
+            pass

quill/stability/logging_config.py

@@ -350,7 +350,8 @@
   "_rebaseline_2026_06_27_prompt_store_consolidation": "quill/__main__.py 638->640 and quill/core/prompt_library.py 364->393 (+29) for the one-prompt-store-truth migration (AI Library Phase 2/3, docs/planning/ai-menu-redesign-plan.md). __main__.py: the two-line guarded startup call (import + consolidate_prompts_quietly()) alongside the existing consolidate_provider_keys_quietly() hook; the migration logic itself lives in the new wx-free quill/core/prompt_migration.py so it adds no growth to either store. prompt_library.py: the new upsert_external() method, which inserts/replaces a user prompt by explicit id (refusing built-ins) so import and the store migration are idempotent and reversible. Same accepted startup-hook / additive-method rebaseline pattern. Budgets re-baselined to current size.",
   "_rebaseline_2026_06_27_main_resync_merge": "Merge of origin/main (0.8.0 line: Python 3.13 runtime, upgrade hardening, legacy-import + startup-maintenance, winrt OCR, bundled Kokoro) into 2.0-dev. Seven modules touched independently on both branches now hold the union of both sides' additions, so the max-of-both budget no longer fits: __main__.py 640->651 (both startup hooks: apply_pending_legacy_import + run_pending_startup_maintenance from main, consolidate_provider_keys/prompts from 2.0-dev), keymap.py 682->683, settings.py 1226->1231, ai_hub_dialog.py 924->927, assistant_panel.py 943->947, main_frame.py 26172->26218, main_frame_statusbar.py 956->967. These are merge combinations of pre-approved per-branch growth, not new feature work; CQ-1 decomposition remains the path down for the large UI modules. Budgets re-baselined to current size.",
   "budgets": {
-    "quill/apps/radio.py": 1081,
+    "quill/apps/radio.py": 1115,
+    "_rebaseline_2026_07_18_radio_log_location": "apps/radio.py 1081 -> 1115 (+34): quill-radio #5, the settable log location -- the standalone previously configured no file logging at all, so debug mode had nowhere to write. main() now calls configure_logging (to RadioHistory.log_dir or the default <data_dir>/logs) before the app comes up, keeps the QueueListener, hands it to the frame, and stops it on exit; Preferences (Ctrl+,) gains a 'Log folder' text field that relocates the live log via the new logging_config.relocate_log and persists. log_dir lives in core/radio/history.py; relocate_log in stability/logging_config.py (both under cap).",
     "_rebaseline_2026_07_17_radio_missed_recording_report": "apps/radio.py 1051 -> 1081 (+30): quill-radio #4, the startup missed-recording report. _report_missed_recordings (scheduled via wx.CallAfter at launch) reads RadioHistory.last_seen, asks the wx-free recording_schedule.missed_occurrences/describe_missed which enabled schedules fired while the app was closed, announces a one-line summary, and re-stamps last_seen; the exit path also stamps last_seen=now so the next launch's window is the closed gap. The occurrence math + the spoken-summary formatter live in core/radio/recording_schedule.py (under cap); last_seen lives in core/radio/history.py.",
     "_rebaseline_2026_07_17_radio_debug_mode_pref": "apps/radio.py 1038 -> 1051 (+13): quill-radio #5, the Preferences (Ctrl+,) 'Verbose logging (debug mode)' checkbox -- one PreferenceCheckbox spec, its addition to the checkbox-values unpack, and the immediate set_radio_debug(history.debug_mode) apply-on-change block so it takes effect this session. The debug_mode field lives in core/radio/history.py and the logging switch itself is the under-cap core/radio/radio_logging.set_radio_debug.",
     "_rebaseline_2026_07_17_low_vision_tree_contrast": "apps/radio.py 1033 -> 1038 (+5): quill-radio #3, low-vision legibility. The main-page favorites TreeCtrl now calls the shared apply_readable_tree_colours() (in favorites_manager_dialog.py) to pin it to the theme-resolved system window/text colours so it is never near-invisible on a mismatched default. Not dark mode -- no hard-coded colours, no toggle.",

quill/tools/module_size_budgets.json

@@ -58,6 +58,13 @@ def test_check_updates_on_startup_round_trips(tmp_path: Path) -> None:
     assert loaded.last_update_check == "2026-07-16T00:00:00"
 
 
+def test_log_dir_round_trips_and_defaults_empty(tmp_path: Path) -> None:
+    # quill-radio #5: the settable log-folder preference.
+    assert load_history(tmp_path).log_dir == ""
+    save_history(tmp_path, RadioHistory(log_dir="D:/radio-logs"))
+    assert load_history(tmp_path).log_dir == "D:/radio-logs"
+
+
 def test_last_seen_round_trips_and_defaults_empty(tmp_path: Path) -> None:
     # quill-radio #4: the "last running" stamp for the missed-recording report.
     assert load_history(tmp_path).last_seen == ""

tests/unit/core/test_radio_history.py

@@ -0,0 +1,61 @@
+"""Tests for the queue-backed logging configuration (STAB-1) and the
+runtime log relocation used by Quill Radio's log-folder preference (#5)."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from quill.stability.logging_config import configure_logging, relocate_log
+
+
+def _drain_and_close(listener: logging.handlers.QueueListener) -> None:
+    """Stop the listener and close its handlers so the file is released."""
+    listener.stop()
+    for handler in listener.handlers:
+        handler.close()
+    logging.getLogger().handlers.clear()
+
+
+def test_configure_logging_writes_quill_log(tmp_path: Path) -> None:
+    listener = configure_logging(tmp_path)
+    try:
+        logging.getLogger("quill.core.radio.test").warning("hello-configure")
+        listener.stop()  # flush the queue to the file
+        listener.start()
+        assert (tmp_path / "quill.log").exists()
+        assert "hello-configure" in (tmp_path / "quill.log").read_text(encoding="utf-8")
+    finally:
+        _drain_and_close(listener)
+
+
+def test_relocate_log_moves_new_records_to_the_new_dir(tmp_path: Path) -> None:
+    first = tmp_path / "first"
+    second = tmp_path / "second"
+    listener = configure_logging(first)
+    try:
+        logging.getLogger("quill.core.radio.test").warning("in-first")
+        relocate_log(listener, second)
+        logging.getLogger("quill.core.radio.test").warning("in-second")
+        listener.stop()
+        listener.start()
+        assert (second / "quill.log").exists()
+        assert "in-second" in (second / "quill.log").read_text(encoding="utf-8")
+    finally:
+        _drain_and_close(listener)
+
+
+def test_relocate_log_bad_path_keeps_current_handler(tmp_path: Path) -> None:
+    listener = configure_logging(tmp_path)
+    try:
+        # A path whose parent is a file cannot be made a directory; relocation
+        # must be a no-op that leaves logging working, not raise.
+        blocker = tmp_path / "blocker"
+        blocker.write_text("x", encoding="utf-8")
+        relocate_log(listener, blocker / "sub")
+        logging.getLogger("quill.core.radio.test").warning("still-logging")
+        listener.stop()
+        listener.start()
+        assert "still-logging" in (tmp_path / "quill.log").read_text(encoding="utf-8")
+    finally:
+        _drain_and_close(listener)

tests/unit/stability/test_logging_config.py

@@ -38,6 +38,7 @@ def _frame(*, playing: RadioStation | None = None) -> Any:
         compressor_enabled=True,
         now_playing_template="{title}[ by {artist}]",
         debug_mode=False,
+        log_dir="",
     )
     frame._radio_favorites = RadioFavoritesStore()
     frame._radio_controller = SimpleNamespace(