feat(controller-peers-env-fallback): read XCE_CONTROLLER_PEERS ahead of XCEADMIN_CONTROLLER in every --controller option (task 4.2)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/xceadmin/tests/test_cli.py

@@ -12,6 +12,7 @@ import ssl
 import socket
 import threading
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 import yaml
@@ -597,6 +598,7 @@ def test_format_sched_admin_error_plain_when_not_recording() -> None:
 
 
 def test_scheduler_record_start_success_prints_formatted_result(monkeypatch) -> None:
+    monkeypatch.delenv("XCE_CONTROLLER_PEERS", raising=False)
     captured = {}
 
     def _fake_record_start(controller, filename):
@@ -650,6 +652,7 @@ def test_scheduler_record_start_passes_filename_and_controller_arguments(monkeyp
 
 
 def test_controller_option_falls_back_to_xceadmin_controller_env_var(monkeypatch) -> None:
+    monkeypatch.delenv("XCE_CONTROLLER_PEERS", raising=False)
     captured = {}
 
     def _fake_record_status(controller):
@@ -668,6 +671,7 @@ def test_controller_option_falls_back_to_xceadmin_controller_env_var(monkeypatch
 
 
 def test_controller_flag_overrides_xceadmin_controller_env_var(monkeypatch) -> None:
+    monkeypatch.delenv("XCE_CONTROLLER_PEERS", raising=False)
     captured = {}
 
     def _fake_record_status(controller):
@@ -687,6 +691,126 @@ def test_controller_flag_overrides_xceadmin_controller_env_var(monkeypatch) -> N
     assert captured["controller"] == "127.0.0.1:9999"
 
 
+# ---------------------------------------------------------------------------
+# --controller precedence with $XCE_CONTROLLER_PEERS (controller-peers-env-
+# fallback Requirement 2.1, 2.4-2.7, 4.3): explicit --controller >
+# $XCE_CONTROLLER_PEERS > $XCEADMIN_CONTROLLER > _DEFAULT_CONTROLLER, for
+# every command that takes --controller. Each case sets or deletes BOTH
+# variables itself, so ambient environment state cannot leak in.
+# ---------------------------------------------------------------------------
+
+_RECORD_RESULT = RecordResult(recording=False, file="", event_count=0, started_at=0)
+
+
+def _patch_controller_command(monkeypatch, command: str, tmp_path: Path) -> tuple[list[str], dict]:
+    """Patch the backend function behind ``command`` so it records the
+    controller value it was given; return the CLI args that invoke it."""
+    captured: dict = {}
+
+    def _record(controller, *_rest):
+        captured["controller"] = controller
+        return _RECORD_RESULT
+
+    if command == "config push":
+
+        def _fake_push_config(cluster_bin_path, controller):
+            captured["controller"] = controller
+            return SimpleNamespace(version_tag=1, acked_count=1, error="")
+
+        monkeypatch.setattr(cli_module, "push_config", _fake_push_config)
+        bin_path = tmp_path / "cluster.bin"
+        bin_path.write_bytes(b"unused -- push_config() is monkeypatched here")
+        return ["config", "push", str(bin_path)], captured
+
+    name = command.split()[-1]
+    monkeypatch.setattr(cli_module, f"record_{name}", _record)
+    return ["scheduler", "record", name], captured
+
+
+_CONTROLLER_COMMANDS = [
+    "config push",
+    "scheduler record start",
+    "scheduler record stop",
+    "scheduler record status",
+]
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_option_uses_xce_controller_peers_alone(monkeypatch, tmp_path, command) -> None:
+    monkeypatch.delenv("XCEADMIN_CONTROLLER", raising=False)
+    monkeypatch.setenv("XCE_CONTROLLER_PEERS", "ctrl-1=localhost:9921,ctrl-2=localhost:9922")
+    args, captured = _patch_controller_command(monkeypatch, command, tmp_path)
+
+    result = CliRunner().invoke(cli, args)
+
+    assert result.exit_code == 0, result.output
+    assert captured["controller"] == "ctrl-1=localhost:9921,ctrl-2=localhost:9922"
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_option_prefers_xce_controller_peers_over_legacy(monkeypatch, tmp_path, command) -> None:
+    monkeypatch.setenv("XCE_CONTROLLER_PEERS", "localhost:9921")
+    monkeypatch.setenv("XCEADMIN_CONTROLLER", "localhost:9901")
+    args, captured = _patch_controller_command(monkeypatch, command, tmp_path)
+
+    result = CliRunner().invoke(cli, args)
+
+    assert result.exit_code == 0, result.output
+    assert captured["controller"] == "localhost:9921"
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_option_empty_xce_controller_peers_falls_through_to_legacy(
+    monkeypatch, tmp_path, command
+) -> None:
+    monkeypatch.setenv("XCE_CONTROLLER_PEERS", "")
+    monkeypatch.setenv("XCEADMIN_CONTROLLER", "localhost:9901")
+    args, captured = _patch_controller_command(monkeypatch, command, tmp_path)
+
+    result = CliRunner().invoke(cli, args)
+
+    assert result.exit_code == 0, result.output
+    assert captured["controller"] == "localhost:9901"
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_flag_overrides_both_env_vars(monkeypatch, tmp_path, command) -> None:
+    monkeypatch.setenv("XCE_CONTROLLER_PEERS", "localhost:9921")
+    monkeypatch.setenv("XCEADMIN_CONTROLLER", "localhost:9901")
+    args, captured = _patch_controller_command(monkeypatch, command, tmp_path)
+
+    result = CliRunner().invoke(cli, [*args, "--controller", "127.0.0.1:9999"])
+
+    assert result.exit_code == 0, result.output
+    assert captured["controller"] == "127.0.0.1:9999"
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_option_uses_default_when_neither_env_var_set(monkeypatch, tmp_path, command) -> None:
+    monkeypatch.delenv("XCE_CONTROLLER_PEERS", raising=False)
+    monkeypatch.delenv("XCEADMIN_CONTROLLER", raising=False)
+    args, captured = _patch_controller_command(monkeypatch, command, tmp_path)
+
+    result = CliRunner().invoke(cli, args)
+
+    assert result.exit_code == 0, result.output
+    assert captured["controller"] == cli_module._DEFAULT_CONTROLLER
+
+
+@pytest.mark.parametrize("command", _CONTROLLER_COMMANDS)
+def test_controller_option_help_names_both_env_vars_in_order(command) -> None:
+    result = CliRunner().invoke(cli, [*command.split(), "--help"])
+
+    assert result.exit_code == 0, result.output
+    help_text = " ".join(result.output.split())
+    assert "$XCE_CONTROLLER_PEERS" in help_text
+    assert "$XCEADMIN_CONTROLLER" in help_text
+    assert help_text.index("$XCE_CONTROLLER_PEERS") < help_text.index("$XCEADMIN_CONTROLLER")
+    assert "name=host:port" in help_text
+    assert "['XCE" not in result.output
+    assert "$[" not in result.output
+
+
 def test_scheduler_record_stop_success_prints_formatted_result(monkeypatch) -> None:
     def _fake_record_stop(controller):
         return RecordResult(recording=False, file="final.replay", event_count=14273, started_at=1000)
@@ -778,6 +902,7 @@ def test_scheduler_record_status_connection_timeout_exits_nonzero_not_raw_traceb
 
 
 def test_scheduler_record_start_connection_refused_exits_nonzero_not_raw_traceback(monkeypatch) -> None:
+    monkeypatch.delenv("XCE_CONTROLLER_PEERS", raising=False)
     def _fake_record_start(controller, filename):
         raise ConnectionRefusedError("refused")