refactor: extract warn helper to consolidate stderr warning messages

Three modules (_agent, _keypress) independently formatted warning
messages to stderr with inconsistent methods (print(file=stderr) vs
stderr.write()) and manually repeated the "ralphify: warning:" prefix.
Extract a shared warn() helper in _output.py so the prefix, output
method, and formatting are defined once. Also removes the now-unused
sys import from _agent.py.

Co-authored-by: Ralphify <noreply@ralphify.co>

Author: 2 people

src/ralphify/_agent.py

@@ -20,7 +20,6 @@
 import queue as _queue
 import signal
 import subprocess
-import sys
 import threading
 import time
 from collections.abc import Callable
@@ -36,6 +35,7 @@
     SUBPROCESS_TEXT_KWARGS,
     ProcessResult,
     collect_output,
+    warn,
 )
 
 # ── Callback type aliases ──────────────────────────────────────────────
@@ -152,11 +152,7 @@ def _ensure_process_dead(proc: subprocess.Popen[Any]) -> None:
     try:
         proc.wait(timeout=_PROCESS_WAIT_TIMEOUT)
     except subprocess.TimeoutExpired:
-        print(
-            "ralphify: warning: agent process did not exit within"
-            f" {_PROCESS_WAIT_TIMEOUT}s after kill",
-            file=sys.stderr,
-        )
+        warn(f"agent process did not exit within {_PROCESS_WAIT_TIMEOUT}s after kill")
 
 
 def _close_pipes(proc: subprocess.Popen[Any]) -> None:
@@ -573,10 +569,9 @@ def _drain_readers(
         if thread is not None:
             thread.join(timeout=timeout)
             if thread.is_alive():
-                print(
-                    f"ralphify: warning: reader thread {thread.name!r} did not"
-                    f" exit within {timeout}s — log output may be incomplete",
-                    file=sys.stderr,
+                warn(
+                    f"reader thread {thread.name!r} did not exit within"
+                    f" {timeout}s — log output may be incomplete"
                 )
 
 

src/ralphify/_keypress.py

@@ -33,6 +33,8 @@
 from collections.abc import Callable
 from types import FrameType
 
+from ralphify._output import warn
+
 
 _POLL_INTERVAL = 0.1  # seconds between stop-flag checks (POSIX select)
 _WIN_POLL_INTERVAL = 0.05  # seconds between kbhit() checks on Windows
@@ -123,8 +125,8 @@ def stop(self) -> None:
                 # posix loop will still restore the terminal on process
                 # exit, so the user's shell will not be wedged.
                 try:
-                    sys.stderr.write(
-                        f"ralphify: keypress listener did not exit within {_THREAD_JOIN_TIMEOUT}s\n"
+                    warn(
+                        f"keypress listener did not exit within {_THREAD_JOIN_TIMEOUT}s"
                     )
                 except Exception:
                     pass

src/ralphify/_output.py

@@ -78,6 +78,15 @@ def collect_output(
     return "".join(parts)
 
 
+def warn(message: str) -> None:
+    """Print a warning message to stderr with the ``ralphify:`` prefix.
+
+    Used by low-level modules (agent, keypress) for operational warnings
+    that should be visible even when Rich console rendering is not active.
+    """
+    print(f"ralphify: warning: {message}", file=sys.stderr)
+
+
 _SECONDS_PER_MINUTE = 60
 _MINUTES_PER_HOUR = 60