fix: don't take a screenshot at import time (breaks headless imports)

recorder.py computed monitor dimensions via utils.take_screenshot() at
module scope, so `import openadapt_capture` crashed in any headless
environment whose display reported a zero-size region. This took down
`openadapt version` and `openadapt doctor` (found via the new CLI smoke
tests in OpenAdaptAI/OpenAdapt). Move the computation into the video-
setup function that is its only consumer.

Adds tests/test_headless_import.py: a deterministic AST guard that no
package module calls a display API (take_screenshot/get_monitor_dims/
grab) at import scope. A subprocess import test is unreliable (only
reproduces on a genuinely headless display); this fails regardless of
environment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: abrichr

openadapt_capture/recorder.py

@@ -45,9 +45,8 @@
     soundfile = None
     websockets = None
 
-def set_browser_mode(
-    mode: str, websocket: "websockets.sync.server.ServerConnection"
-) -> None:
+
+def set_browser_mode(mode: str, websocket: "websockets.sync.server.ServerConnection") -> None:
     """Send a message to the browser extension to set the mode."""
     logger.info(f"{type(websocket)=}")
     VALID_MODES = ("idle", "record", "replay")
@@ -142,9 +141,6 @@ def __bool__(self):
 stop_sequence_detected = False
 ws_server_instance = None
 
-# TODO XXX replace with utils.get_monitor_dims() once fixed
-monitor_width, monitor_height = utils.take_screenshot().size
-
 
 def collect_stats(performance_snapshots: list[tracemalloc.Snapshot]) -> None:
     """Collects and appends performance snapshots using tracemalloc.
@@ -533,7 +529,9 @@ def write_events(
 
 
 def video_pre_callback(
-    db: crud.SaSession, recording: Recording, video_dir: str = None,
+    db: crud.SaSession,
+    recording: Recording,
+    video_dir: str = None,
 ) -> dict[str, Any]:
     """Function to call before main loop.
 
@@ -546,8 +544,10 @@ def video_pre_callback(
         dict[str, Any]: The updated state.
     """
     video_file_path = video.get_video_file_path(recording.timestamp, video_dir)
-    video_container, video_stream, video_start_timestamp = (
-        video.initialize_video_writer(video_file_path, monitor_width, monitor_height)
+    # TODO XXX replace with utils.get_monitor_dims() once fixed
+    monitor_width, monitor_height = utils.take_screenshot().size
+    video_container, video_stream, video_start_timestamp = video.initialize_video_writer(
+        video_file_path, monitor_width, monitor_height
     )
     crud.update_video_start_time(db, recording, video_start_timestamp)
     return {
@@ -643,9 +643,7 @@ def write_video_event(
     }
 
 
-def trigger_action_event(
-    event_q: queue.Queue, action_event_args: dict[str, Any]
-) -> None:
+def trigger_action_event(event_q: queue.Queue, action_event_args: dict[str, Any]) -> None:
     """Triggers an action event and adds it to the event queue.
 
     Args:
@@ -778,9 +776,7 @@ def handle_key(
         "char",
         "vk",
     ]
-    attrs = {
-        f"key_{attr_name}": getattr(key, attr_name, None) for attr_name in attr_names
-    }
+    attrs = {f"key_{attr_name}": getattr(key, attr_name, None) for attr_name in attr_names}
     logger.debug(f"{attrs=}")
     canonical_attrs = {
         f"canonical_key_{attr_name}": getattr(canonical_key, attr_name, None)
@@ -1216,9 +1212,7 @@ def audio_callback(
         audio_frames.append(indata.copy())
 
     # open InputStream and start recording while ActionEvents are recorded
-    audio_stream = sounddevice.InputStream(
-        callback=audio_callback, samplerate=16000, channels=1
-    )
+    audio_stream = sounddevice.InputStream(callback=audio_callback, samplerate=16000, channels=1)
     logger.info("Audio recording started.")
     start_timestamp = utils.get_timestamp()
     audio_stream.start()
@@ -1239,6 +1233,7 @@ def audio_callback(
     # Convert audio to text using OpenAI's Whisper
     logger.info("Transcribing audio...")
     import whisper
+
     model = whisper.load_model("base")
     result_info = model.transcribe(converted_audio, word_timestamps=True, fp16=False)
     logger.info(f"The narrated text is: {result_info['text']}")
@@ -1251,21 +1246,15 @@ def audio_callback(
             word_list = result_info["segments"][0]["words"]
 
     # compress and convert to bytes to save to database
-    logger.info(
-        "Size of uncompressed audio data: {} bytes".format(converted_audio.nbytes)
-    )
+    logger.info("Size of uncompressed audio data: {} bytes".format(converted_audio.nbytes))
     # Create an in-memory file-like object
     file_obj = io.BytesIO()
     # Write the audio data using lossless compression
-    soundfile.write(
-        file_obj, converted_audio, int(audio_stream.samplerate), format="FLAC"
-    )
+    soundfile.write(file_obj, converted_audio, int(audio_stream.samplerate), format="FLAC")
     # Get the compressed audio data as bytes
     compressed_audio_bytes = file_obj.getvalue()
 
-    logger.info(
-        "Size of compressed audio data: {} bytes".format(len(compressed_audio_bytes))
-    )
+    logger.info("Size of compressed audio data: {} bytes".format(len(compressed_audio_bytes)))
 
     file_obj.close()
 
@@ -1462,9 +1451,7 @@ def record(
                 event_q,
                 terminate_processing,
                 recording,
-                task_started_events.setdefault(
-                    "window_event_reader", threading.Event()
-                ),
+                task_started_events.setdefault("window_event_reader", threading.Event()),
             ),
         )
         window_event_reader.start()
@@ -1477,9 +1464,7 @@ def record(
                 event_q,
                 terminate_processing,
                 recording,
-                task_started_events.setdefault(
-                    "browser_event_reader", threading.Event()
-                ),
+                task_started_events.setdefault("browser_event_reader", threading.Event()),
             ),
         )
         browser_event_reader.start()
@@ -1567,9 +1552,7 @@ def record(
             recording,
             db_path,
             terminate_processing,
-            task_started_events.setdefault(
-                "screen_event_writer", multiprocessing.Event()
-            ),
+            task_started_events.setdefault("screen_event_writer", multiprocessing.Event()),
         ),
     )
     screen_event_writer.start()
@@ -1587,9 +1570,7 @@ def record(
                 recording,
                 db_path,
                 terminate_processing,
-                task_started_events.setdefault(
-                    "browser_event_writer", multiprocessing.Event()
-                ),
+                task_started_events.setdefault("browser_event_writer", multiprocessing.Event()),
             ),
         )
         browser_event_writer.start()
@@ -1606,9 +1587,7 @@ def record(
             recording,
             db_path,
             terminate_processing,
-            task_started_events.setdefault(
-                "action_event_writer", multiprocessing.Event()
-            ),
+            task_started_events.setdefault("action_event_writer", multiprocessing.Event()),
         ),
     )
     action_event_writer.start()
@@ -1626,9 +1605,7 @@ def record(
                 recording,
                 db_path,
                 terminate_processing,
-                task_started_events.setdefault(
-                    "window_event_writer", multiprocessing.Event()
-                ),
+                task_started_events.setdefault("window_event_writer", multiprocessing.Event()),
             ),
         )
         window_event_writer.start()
@@ -1661,9 +1638,7 @@ def record(
                 recording,
                 db_path,
                 terminate_processing,
-                task_started_events.setdefault(
-                    "audio_event_writer", multiprocessing.Event()
-                ),
+                task_started_events.setdefault("audio_event_writer", multiprocessing.Event()),
             ),
         )
         audio_recorder.start()
@@ -1677,9 +1652,7 @@ def record(
             recording,
             db_path,
             terminate_perf_event,
-            task_started_events.setdefault(
-                "perf_stats_writer", multiprocessing.Event()
-            ),
+            task_started_events.setdefault("perf_stats_writer", multiprocessing.Event()),
         ),
     )
     perf_stats_writer.start()
@@ -1715,9 +1688,7 @@ def record(
         started_tasks = sum(event.is_set() for event in task_started_events.values())
         if started_tasks >= expected_starts:
             break
-        waiting_for = [
-            task for task, event in task_started_events.items() if not event.is_set()
-        ]
+        waiting_for = [task for task, event in task_started_events.items() if not event.is_set()]
         logger.info(f"Waiting for tasks to start: {waiting_for}")
         logger.info(f"Started tasks: {started_tasks}/{expected_starts}")
         time.sleep(1)  # Sleep to reduce busy waiting
@@ -1780,7 +1751,9 @@ def join_tasks(task_names: list[str]) -> None:
     if config.PLOT_PERFORMANCE:
         session = get_session_for_path(db_path)
         plotting.plot_performance(
-            session, recording, save_dir=capture_dir,
+            session,
+            recording,
+            save_dir=capture_dir,
         )
 
     logger.info(f"Saved {recording_timestamp=}")
@@ -1824,6 +1797,7 @@ def join_tasks(task_names: list[str]) -> None:
     _profile_path = os.path.join(capture_dir, "profiling.json")
     try:
         import json as _json
+
         with open(_profile_path, "w") as _f:
             _json.dump(_profile_data, _f, indent=2)
         logger.info(f"Profiling saved to {_profile_path}")
@@ -1838,13 +1812,17 @@ def join_tasks(task_names: list[str]) -> None:
             print(f"  {k}: {v} events ({rate:.1f}/s)")
         if _screen_timing:
             st = _profile_data["screen_timing"]
-            print(f"  screenshot: avg={st['screenshot_avg_ms']}ms "
-                  f"max={st['screenshot_max_ms']}ms "
-                  f"min={st['screenshot_min_ms']}ms")
-        print(f"Config: WINDOW_DATA={config.RECORD_WINDOW_DATA} "
-              f"VIDEO={config.RECORD_VIDEO} "
-              f"PLOT_PERF={config.PLOT_PERFORMANCE} "
-              f"FPS={config.SCREEN_CAPTURE_FPS}")
+            print(
+                f"  screenshot: avg={st['screenshot_avg_ms']}ms "
+                f"max={st['screenshot_max_ms']}ms "
+                f"min={st['screenshot_min_ms']}ms"
+            )
+        print(
+            f"Config: WINDOW_DATA={config.RECORD_WINDOW_DATA} "
+            f"VIDEO={config.RECORD_VIDEO} "
+            f"PLOT_PERF={config.PLOT_PERFORMANCE} "
+            f"FPS={config.SCREEN_CAPTURE_FPS}"
+        )
         print("=========================\n")
 
         # Auto-send profiling via wormhole if requested
@@ -1977,7 +1955,8 @@ def _run_record(self) -> None:
     def __enter__(self) -> "Recorder":
         # Start status drain thread
         self._status_thread = threading.Thread(
-            target=self._drain_status_pipe, daemon=True,
+            target=self._drain_status_pipe,
+            daemon=True,
         )
         self._status_thread.start()
 

tests/test_headless_import.py

@@ -0,0 +1,58 @@
+"""Importing openadapt_capture must not call display APIs at module scope.
+
+recorder.py used to compute monitor dimensions via a screenshot at
+module scope (`monitor_width, monitor_height = utils.take_screenshot()
+.size`), so `import openadapt_capture` crashed in any headless
+environment whose display reported a zero-size region, taking down
+`openadapt version`/`doctor` with it.
+
+A subprocess import test is unreliable here (it only reproduces on a
+genuinely headless display), so this guards the invariant statically:
+no module-level call to a display/screenshot API in any package module.
+Importing a library should be cheap and side-effect free.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parent.parent / "openadapt_capture"
+
+# Calls that touch the screen/display and must not run at import time.
+FORBIDDEN_AT_MODULE_SCOPE = {"take_screenshot", "get_monitor_dims", "grab"}
+
+
+def _module_level_calls(tree: ast.Module):
+    """Yield Call nodes that execute at import (module body, not inside
+    a function or class definition)."""
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        for sub in ast.walk(node):
+            if isinstance(sub, ast.Call):
+                yield sub
+
+
+def _called_name(call: ast.Call) -> str | None:
+    func = call.func
+    if isinstance(func, ast.Name):
+        return func.id
+    if isinstance(func, ast.Attribute):
+        return func.attr
+    return None
+
+
+def test_no_display_calls_at_module_scope():
+    problems = []
+    for path in PACKAGE_ROOT.rglob("*.py"):
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        for call in _module_level_calls(tree):
+            name = _called_name(call)
+            if name in FORBIDDEN_AT_MODULE_SCOPE:
+                problems.append(f"{path}:{call.lineno}: module-level {name}()")
+    assert not problems, (
+        "Display/screenshot calls at import time break headless imports "
+        "(CI, servers, containers). Move them inside the function that "
+        "uses them:\n  " + "\n  ".join(problems)
+    )