"""The runner: how the CLI is called in process, decoded, and mapped to a code. Most of this drives a recording stand-in (:class:`mcp_fake.FakeCli`), because the subject is what this layer decides -- the argv list and the mapping. Three tests drive the **real** entry point, against a control socket that does not exist: that is the honest way to prove the dispatch, the capture and the exit-code mapping against the CLI's actual parser without standing a daemon up. """ from __future__ import annotations import contextlib import os import signal import mcp_fake import pytest from hhstreamd.protocol import ExitCode from hhstream_mcp import invoke, media @pytest.fixture(autouse=True) def _isolated(monkeypatch, tmp_path): mcp_fake.isolate(monkeypatch, tmp_path) # ── the call ─────────────────────────────────────────────────────────────── def test_the_argv_reaches_the_entry_point_unchanged(): fake = mcp_fake.FakeCli(stdout="hello\n") outcome = invoke.Runner(fake).run(["session", "list", "--json"]) assert outcome.ok assert outcome.stdout == "hello\n" assert fake.argv == ["session", "list", "--json"] assert outcome.argv == ["session", "list", "--json"] def test_a_metacharacter_is_one_argument_and_never_a_statement(): """There is no shell between a tool and the CLI, and no string either.""" fake = mcp_fake.FakeCli() nasty = "; rm -rf / #" invoke.Runner(fake).run(["session", "keyboard", "type", "--", "s1", nasty]) assert fake.argv == ["session", "keyboard", "type", "--", "s1", nasty] def test_what_the_cli_prints_is_captured_and_not_leaked_to_the_transport(capsys): """A print on stdout here would be a parse error at the client.""" fake = mcp_fake.FakeCli(stdout="on stdout\n", stderr="on stderr\n") outcome = invoke.Runner(fake).run(["status"]) assert outcome.stdout == "on stdout\n" assert outcome.stderr == "on stderr\n" escaped = capsys.readouterr() assert escaped.out == "" assert escaped.err == "" def test_sys_exit_is_the_exit_code_a_process_would_have_had(): """argparse refuses with `sys.exit(2)`; handlers exit on a missing tool.""" fake = mcp_fake.FakeCli(raises=SystemExit(2)) assert invoke.Runner(fake).run(["session"]).returncode == int(ExitCode.USAGE) # `sys.exit("message")` is status 1 in a real process, and the message is # the exit code object rather than something printed. fake = mcp_fake.FakeCli(raises=SystemExit("hhstream: grim is not on PATH")) assert invoke.Runner(fake).run(["shot"]).returncode == invoke.GENERIC_FAILURE fake = mcp_fake.FakeCli(raises=SystemExit(None)) assert invoke.Runner(fake).run(["status"]).returncode == 0 def test_an_uncaught_exception_becomes_exit_one_with_its_traceback(): """What a CLI process would have done, rather than a transport error.""" fake = mcp_fake.FakeCli(raises=RuntimeError("boom")) outcome = invoke.Runner(fake).run(["session", "list", "--json"]) assert outcome.returncode == invoke.GENERIC_FAILURE assert "RuntimeError: boom" in outcome.stderr assert "Traceback" in outcome.stderr def test_a_keyboard_interrupt_is_not_swallowed_as_a_tool_result(): """BaseException is caught on purpose; the code still says "failed".""" fake = mcp_fake.FakeCli(raises=KeyboardInterrupt()) outcome = invoke.Runner(fake).run(["session", "list"]) assert outcome.returncode == invoke.GENERIC_FAILURE def test_a_call_runs_with_the_serialising_lock_held(): """The CLI prints to a process-global stdout, so one call at a time. Asserted from inside the call rather than by racing two threads and hoping their output interleaves: a race that passes by luck is not a test. The private name is the point -- what is being asserted is that this specific lock is held while a handler runs. """ def probing(argv): free = invoke._ONE_AT_A_TIME.acquire(blocking=False) if free: invoke._ONE_AT_A_TIME.release() print("free" if free else "held", end="") return 0 assert invoke.Runner(probing).run(["status"]).stdout == "held" # ── decoding ─────────────────────────────────────────────────────────────── def test_the_protocol_object_is_read_from_stdout_on_success(): fields = {"ok": True, "id": "s-1", "session": {"state": "running"}} fake = mcp_fake.FakeCli(stdout=mcp_fake.reply(**fields)) assert invoke.Runner(fake).run(["session", "status", "--json"]).payload() == fields def test_the_protocol_object_is_read_from_stderr_on_failure(): """The CLI's own split: an error goes to stderr whatever the output mode.""" fields = {"ok": False, "error": "no_lease", "reason": "no pointer lease for s-1"} fake = mcp_fake.FakeCli( stderr=mcp_fake.reply(**fields), exit_code=int(ExitCode.NO_LEASE) ) outcome = invoke.Runner(fake).run(["session", "pointer", "click", "--json"]) assert not outcome.ok assert outcome.payload() == fields def test_an_object_printed_under_a_bare_line_is_still_found(): """`session start` prints the id beside its object; parsing must survive it.""" fake = mcp_fake.FakeCli(stdout='s-1\n{\n "ok": true,\n "id": "s-1"\n}\n') assert invoke.Runner(fake).run(["session", "start"]).payload() == { "ok": True, "id": "s-1", } def test_no_json_at_all_is_none_rather_than_an_invention(): fake = mcp_fake.FakeCli(stdout="services:\n hyprland-headless.service active\n") assert invoke.Runner(fake).run(["status"]).payload() is None def test_a_json_array_is_not_mistaken_for_the_protocol_object(): assert invoke.first_json_object("[1, 2, 3]") is None assert invoke.first_json_object('[{"a": 1}]') == {"a": 1} # ── the real entry point, with nothing listening ─────────────────────────── def test_the_real_cli_refuses_a_bad_flag_with_the_frozen_usage_code(): """argparse's own refusal, through the CLI's own parser, mapped to exit 2.""" outcome = invoke.Runner().run( ["session", "pointer", "click", "--json", "--button=nonsense", "--", "s-1"] ) assert outcome.returncode == int(ExitCode.USAGE) assert "invalid choice" in outcome.stderr # And nothing escaped onto the real stdout: argparse prints usage there for # --help and to stderr for an error, and both are captured. assert outcome.stdout == "" def test_the_real_cli_reports_an_unreachable_broker_as_the_frozen_code(): """No socket, no daemon, no fake: the mapping end to end.""" outcome = invoke.Runner().run(["session", "list", "--json"]) assert outcome.returncode == int(ExitCode.DAEMON_UNREACHABLE) payload = outcome.payload() assert payload is not None assert payload["error"] == "daemon_unreachable" def test_the_real_cli_refuses_a_gesture_with_no_lease_without_a_broker(): """Exit 9 is produced by the CLI before the socket is touched at all.""" outcome = invoke.Runner().run( ["session", "pointer", "click", "--json", "--", "s-1"] ) assert outcome.returncode == int(ExitCode.NO_LEASE) assert (outcome.payload() or {}).get("error") == "no_lease" def test_an_unreachable_frame_socket_earns_the_hint_the_sg_re_exec_replaces(): """The one capability lost by calling the CLI in process, said out loud.""" outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"]) assert "cannot read" in outcome.stderr assert "sg hhstream" in outcome.stderr def test_the_hint_is_absent_when_the_socket_is_readable(tmp_path, monkeypatch): readable = tmp_path / "stream.sock" readable.write_bytes(b"") monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(readable)) outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=1)).run(["shot"]) assert "sg hhstream" not in outcome.stderr def test_a_session_verb_never_earns_the_frame_socket_hint(): """It has nothing to do with the control socket, so it must not be offered.""" outcome = invoke.Runner(mcp_fake.FakeCli(exit_code=int(ExitCode.BUSY))).run( ["session", "pointer", "acquire", "--json", "--", "s-1"] ) assert "sg hhstream" not in outcome.stderr # ── the exit-code table ──────────────────────────────────────────────────── @pytest.mark.parametrize( "code", [ ExitCode.USAGE, ExitCode.NO_SUCH_SESSION, ExitCode.BAD_STATE, ExitCode.DAEMON_UNREACHABLE, ExitCode.POLICY, ExitCode.TIMEOUT, ExitCode.BUSY, ExitCode.NO_LEASE, ExitCode.COMPOSITOR, ], ) def test_every_frozen_exit_code_has_a_remedy_naming_itself(code): """A new code in the frozen table must not fall through to a generic line.""" text = invoke.remedy_for(int(code)) assert text.startswith(f"exit {int(code)} ({code.name})") assert int(code) in invoke.REMEDY def test_the_lease_codes_say_the_two_different_things_an_agent_must_do(): """8 and 9 are the pair that must never read alike (CONTRACT-sessions.md §4).""" busy = invoke.remedy_for(int(ExitCode.BUSY)) none_held = invoke.remedy_for(int(ExitCode.NO_LEASE)) assert "pointer_state" in busy and "wait" in busy assert "pointer_acquire" in none_held # "acquire one" must not be the advice for BUSY: that is the one confusion # the two codes exist to prevent. assert "pointer_acquire" not in busy def test_an_unclassified_code_is_still_a_failure_and_says_so(): text = invoke.remedy_for(42) assert "exit 42 (UNCLASSIFIED)" in text assert "do not assume anything happened" in text def test_generic_failure_is_its_own_case(): """Exit 1 is the frame verbs', and is not in the broker's frozen table.""" assert invoke.GENERIC_FAILURE not in [int(code) for code in ExitCode] assert "grim" in invoke.remedy_for(invoke.GENERIC_FAILURE) # ── launch, for `run` ────────────────────────────────────────────────────── def test_launch_leaves_the_application_running_in_its_own_session(wayland): """`run` launches and forgets, and a killed server must not take it along.""" spawned = invoke.Runner().launch(["sleep", "30"], settle=0.3) try: assert not spawned.exited assert spawned.pid > 0 os.kill(spawned.pid, 0) # Its own session, so a client that kills this server's process group # does not kill the desktop with it. assert os.getsid(spawned.pid) == spawned.pid assert os.getsid(spawned.pid) != os.getsid(0) finally: with contextlib.suppress(ProcessLookupError): os.kill(spawned.pid, signal.SIGTERM) def test_launch_reports_an_application_that_died_inside_the_window(wayland): spawned = invoke.Runner().launch(["false"], settle=5.0) assert spawned.exited assert spawned.pid > 0 def test_launch_hands_back_what_a_failing_application_said(wayland): spawned = invoke.Runner().launch( ["sh", "-c", "echo 'cannot open display' >&2; exit 3"], settle=5.0 ) assert spawned.exited assert "cannot open display" in spawned.stderr def test_launch_refuses_a_command_that_is_not_on_path_rather_than_forking(wayland): spawned = invoke.Runner().launch(["definitely-not-a-program-here"], settle=5.0) assert spawned.exited assert spawned.pid == 0 assert "no executable" in spawned.stderr def test_launch_passes_on_the_cli_s_own_refusal_when_there_is_no_compositor(tmp_path, monkeypatch): """`env_for_session` exits with the message; it is handed on verbatim.""" monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(tmp_path / "empty" / "stream.sock")) (tmp_path / "empty").mkdir() spawned = invoke.Runner().launch(["true"], settle=1.0) assert spawned.exited assert spawned.pid == 0 assert "no wayland socket" in spawned.stderr assert "is the compositor up?" in spawned.stderr @pytest.fixture def wayland(workdir, monkeypatch): """A runtime directory with something `env_for_session` accepts in it. A real AF_UNIX socket, because that function checks `is_socket()` -- an empty file would make it refuse for a reason these tests are not about. The suite's `workdir` fixture and not `tmp_path`, because an AF_UNIX address is capped near 108 bytes and pytest's own paths are longer than that. """ import socket listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) listener.bind(str(workdir / "wayland-0")) monkeypatch.setenv("HHSTREAM_FRAME_SOCKET", str(workdir / "stream.sock")) yield workdir listener.close() # ── artefact readers ─────────────────────────────────────────────────────── def test_a_png_is_sniffed_by_its_header_not_its_extension(): image = media.sniff(mcp_fake.png(width=13, height=7)) assert image is not None assert (image.media_type, image.width, image.height) == ("image/png", 13, 7) def test_a_jpeg_under_a_png_filename_is_still_a_jpeg(): """The publisher serves `image/jpeg` on the deployment machine.""" image = media.sniff(mcp_fake.jpeg(width=6, height=3)) assert image is not None assert (image.media_type, image.width, image.height) == ("image/jpeg", 6, 3) def test_an_unrecognised_format_is_none_rather_than_a_guess(): assert media.sniff(b"GIF89a\x00\x00") is None assert media.sniff(b"") is None def test_the_measured_record_rate_is_read_off_the_cli_s_own_line(): found = media.recording("/tmp/out.mp4 (57 frames in 6.02s -> 9 fps)\n") assert found is not None assert (found.path, found.frames, found.seconds, found.fps) == ("/tmp/out.mp4", 57, 6.02, 9) def test_a_record_line_in_an_unexpected_shape_is_not_half_parsed(): assert media.recording("/tmp/out.mp4\n") is None assert media.recording("") is None def test_temp_name_is_unique_per_process_and_under_a_named_directory(): first = invoke.temp_name("recording", ".mp4") assert "hhstream-mcp" in first assert first.endswith(".mp4") assert str(os.getpid()) in first