Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

tests/hermes_cli/test_update_receipt.py

@@ -0,0 +1,402 @@
+"""Tests for hermes_cli.update_receipt — Phase 1 of the fleet-update plan (#91277).
+
+Covers:
+- receipt lifecycle (begin → record → finalize → read back)
+- skip recording with reasons
+- gateway restart phase recording (success + phase-error shapes)
+- receipt pruning
+- fleet version classification (current / stale / unknown)
+- gateway_state.json code-identity stamping (gateway/status.py side)
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+import hermes_cli.update_receipt as ur
+
+
+@pytest.fixture()
+def receipt_home(tmp_path, monkeypatch):
+    """Isolated HERMES_HOME for receipt writes."""
+    home = tmp_path / ".hermes"
+    home.mkdir()
+    monkeypatch.setattr(
+        "hermes_cli.config.get_hermes_home", lambda: home, raising=False
+    )
+    # ensure no receipt bleeds between tests
+    ur._current = None
+    yield home
+    ur._current = None
+
+
+def _finalize(outcome="success", fleet=None):
+    return ur.finalize_update_receipt(outcome, fleet=fleet)
+
+
+class TestReceiptLifecycle:
+    def test_begin_record_finalize_roundtrip(self, receipt_home):
+        ur.begin_update_receipt()
+        ur.record_step("pre_update_backup", True, "snapshot=abc123")
+        ur.record_skip("gateway_restart", "no gateways running")
+        ur.record_gateway_restart(
+            restarted_services=["hermes-gateway"],
+            relaunched_profiles=["work"],
+            killed_pids=[123],
+            failed_units=[],
+            incomplete=False,
+        )
+        path = _finalize("success", fleet=[{"profile": "default", "state": "current"}])
+        assert path is not None and path.is_file()
+
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        assert payload["schema"] == 1
+        assert payload["outcome"] == "success"
+        assert payload["finished_at"] is not None
+        assert payload["steps"][0]["name"] == "pre_update_backup"
+        assert payload["steps"][0]["ok"] is True
+        assert payload["skips"][0]["reason"] == "no gateways running"
+        gr = payload["gateway_restart"]
+        assert gr["restarted_services"] == ["hermes-gateway"]
+        assert gr["relaunched_profiles"] == ["work"]
+        assert gr["killed_pids"] == [123]
+        assert gr["incomplete"] is False
+        assert payload["fleet"][0]["profile"] == "default"
+
+    def test_fresh_recovery_result_reaches_persisted_receipt(self, receipt_home):
+        recovery = {
+            "requested": ["coder", "default", "ops"],
+            "verified": ["default"],
+            "relaunch_attempted": ["ops"],
+            "failed": ["coder"],
+            "skipped": [
+                {
+                    "profile": "desk",
+                    "kind": "serve",
+                    "supervisor": "desktop",
+                    "reason": "desktop app owns and respawns this serve backend",
+                }
+            ],
+        }
+
+        ur.begin_update_receipt()
+        ur.record_gateway_restart(
+            restarted_services=[],
+            incomplete=True,
+            phase_error="boom: module vanished mid-pull",
+            fresh_recovery=recovery,
+        )
+        path = _finalize("partial")
+
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        persisted = payload["gateway_restart"]["fresh_recovery"]
+        assert {key: persisted[key] for key in recovery} == recovery
+        # Serve coverage is always persisted, even when the pass had nothing
+        # to report, so a reader can tell "no serve runtime" from "the field
+        # predates #92145".
+        assert persisted["serve_units"] == {"verified": [], "failed": []}
+        assert persisted["stale_runtimes"] == []
+        # The conservative vocabulary is the persisted contract: no bucket may
+        # rebrand an unverified relaunch as supervisor-backed success.
+        assert "succeeded" not in persisted
+
+    def test_latest_pointer_written_and_readable(self, receipt_home):
+        ur.begin_update_receipt()
+        ur.record_step("git_pull", True)
+        _finalize("partial")
+        latest = ur.read_latest_receipt()
+        assert latest is not None
+        assert latest["outcome"] == "partial"
+
+    def test_phase_error_shape(self, receipt_home):
+        ur.begin_update_receipt()
+        ur.record_gateway_restart(
+            restarted_services=[],
+            incomplete=True,
+            phase_error="boom: module vanished mid-pull",
+        )
+        path = _finalize("partial")
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        gr = payload["gateway_restart"]
+        assert gr["incomplete"] is True
+        assert "boom" in gr["phase_error"]
+
+    def test_record_without_begin_is_noop(self, receipt_home):
+        # No begin — nothing should raise, nothing should be written.
+        ur.record_step("orphan", True)
+        ur.record_skip("orphan", "no receipt")
+        ur.record_gateway_restart(restarted_services=[])
+        assert _finalize("success") is None
+
+    def test_finalize_clears_current(self, receipt_home):
+        ur.begin_update_receipt()
+        assert ur._current is not None
+        _finalize("success")
+        assert ur._current is None
+
+    def test_pruning_keeps_recent(self, receipt_home, monkeypatch):
+        monkeypatch.setattr(ur, "_RECEIPT_KEEP", 3)
+        directory = receipt_home / "logs" / "update_receipts"
+        directory.mkdir(parents=True)
+        for i in range(6):
+            p = directory / f"update_2026010{i}_000000_1.json"
+            p.write_text("{}", encoding="utf-8")
+            os.utime(p, (1000 + i, 1000 + i))
+        ur._prune_old_receipts(directory)
+        remaining = sorted(p.name for p in directory.glob("update_*.json"))
+        assert len(remaining) == 3
+        # newest three survive
+        assert remaining == [
+            "update_20260103_000000_1.json",
+            "update_20260104_000000_1.json",
+            "update_20260105_000000_1.json",
+        ]
+
+    def test_read_latest_receipt_missing(self, receipt_home):
+        assert ur.read_latest_receipt() is None
+
+
+class TestCommandBoundaryFinalization:
+    """Receipt lifetime is owned by the update-command boundary (#91283 review).
+
+    Early sys.exit paths (concurrent-instance preflight exit-2, venv-holder
+    refusal, fetch failure) predate the inner finalize sites; the boundary
+    safety net must persist the receipt exactly once with the stop reason,
+    while inner-finalized runs are untouched.
+    """
+
+    def test_pending_receipt_persisted_on_exit_2_refusal(self, receipt_home):
+        ur.begin_update_receipt()
+        ur.record_step("windows_preflight", False, "another hermes.exe running")
+        path = ur.finalize_pending_update_receipt(2, "sys.exit(2)")
+        assert path is not None and path.is_file()
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        assert payload["outcome"] == "refused"
+        assert payload["exit_code"] == 2
+        assert payload["stop_reason"] == "sys.exit(2)"
+        assert payload["finished_at"] is not None
+        assert ur._current is None
+
+    def test_pending_receipt_persisted_on_exit_1_failure(self, receipt_home):
+        ur.begin_update_receipt()
+        path = ur.finalize_pending_update_receipt(1, "sys.exit(1)")
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        assert payload["outcome"] == "failed"
+        assert payload["exit_code"] == 1
+
+    def test_noop_when_inner_path_already_finalized(self, receipt_home):
+        """Exactly-once: boundary call after an inner finalize writes nothing."""
+        ur.begin_update_receipt()
+        first = ur.finalize_update_receipt("success")
+        assert first is not None
+        second = ur.finalize_pending_update_receipt(0, "boundary")
+        assert second is None
+        directory = receipt_home / "logs" / "update_receipts"
+        assert len(list(directory.glob("update_*.json"))) == 1
+
+    def test_noop_when_never_begun(self, receipt_home):
+        assert ur.finalize_pending_update_receipt(2, "sys.exit(2)") is None
+        assert ur.read_latest_receipt() is None
+
+    def test_cmd_update_boundary_finalizes_on_early_exit(
+        self, receipt_home, monkeypatch
+    ):
+        """End-to-end through the real cmd_update wrapper: an impl that begins
+        a receipt then sys.exit(2)s (the concurrent-instance shape) must leave
+        a finalized 'refused' receipt, preserve the exit code, and clear the
+        singleton."""
+        from types import SimpleNamespace
+
+        from hermes_cli import main as hermes_main
+
+        def _fake_impl(args, gateway_mode):
+            ur.begin_update_receipt()
+            ur.record_step("windows_preflight", False, "hermes.exe holds venv")
+            sys.exit(2)
+
+        monkeypatch.setattr(hermes_main, "_cmd_update_impl", _fake_impl)
+        monkeypatch.setattr(
+            hermes_main, "detect_install_method", lambda *a, **k: "git", raising=False
+        )
+        monkeypatch.setattr(
+            hermes_main,
+            "_install_hangup_protection",
+            lambda gateway_mode: None,
+            raising=False,
+        )
+        monkeypatch.setattr(
+            hermes_main, "_finalize_update_output", lambda state: None, raising=False
+        )
+
+        class _FakeLock:
+            holder = None
+
+            def acquire(self):
+                return True
+
+            def release(self):
+                pass
+
+        import hermes_cli.update_lock as update_lock_mod
+
+        monkeypatch.setattr(update_lock_mod, "UpdateLock", _FakeLock)
+
+        args = SimpleNamespace(
+            check=False, gateway=False, branch=None, yes=False,
+            force=False, force_venv=False,
+        )
+        with pytest.raises(SystemExit) as exc_info:
+            hermes_main.cmd_update(args)
+
+        assert exc_info.value.code == 2  # exit code preserved
+        latest = ur.read_latest_receipt()
+        assert latest is not None
+        assert latest["outcome"] == "refused"
+        assert latest["exit_code"] == 2
+        assert latest["stop_reason"] == "sys.exit(2)"
+        assert latest["steps"][0]["name"] == "windows_preflight"
+        assert ur._current is None
+        # exactly-once: exactly one receipt file
+        directory = receipt_home / "logs" / "update_receipts"
+        assert len(list(directory.glob("update_*.json"))) == 1
+
+
+class TestFleetClassification:
+    def _fleet_with(self, monkeypatch, tmp_path, record, expected_sha="a" * 40):
+        """Run collect_fleet_versions against one fake default profile."""
+        home = tmp_path / "fleet_home"
+        home.mkdir()
+        (home / "gateway_state.json").write_text(
+            json.dumps(record), encoding="utf-8"
+        )
+        monkeypatch.setattr(
+            "hermes_cli.build_info.get_code_identity",
+            lambda refresh=False: {"sha": expected_sha, "short_sha": expected_sha[:8],
+                                   "version": "1.0", "source": "git"},
+        )
+        monkeypatch.setattr(
+            "hermes_cli.profiles._get_default_hermes_home", lambda: home
+        )
+        monkeypatch.setattr(
+            "hermes_cli.profiles._get_profiles_root",
+            lambda: tmp_path / "nonexistent_profiles_root",
+        )
+        monkeypatch.setattr("gateway.status._pid_exists", lambda pid: True)
+        return ur.collect_fleet_versions()
+
+    def test_current_gateway(self, monkeypatch, tmp_path):
+        sha = "a" * 40
+        fleet = self._fleet_with(
+            monkeypatch, tmp_path,
+            {"pid": 4242, "code_sha": sha, "code_version": "1.0"},
+            expected_sha=sha,
+        )
+        assert len(fleet) == 1
+        assert fleet[0]["state"] == "current"
+        assert fleet[0]["pid"] == 4242
+
+    def test_stale_gateway(self, monkeypatch, tmp_path):
+        fleet = self._fleet_with(
+            monkeypatch, tmp_path,
+            {"pid": 4242, "code_sha": "b" * 40, "code_version": "0.9"},
+            expected_sha="a" * 40,
+        )
+        assert fleet[0]["state"] == "stale"
+
+    def test_unstamped_gateway_is_unknown(self, monkeypatch, tmp_path):
+        # Pre-feature gateway: no code_sha in its runtime status.
+        fleet = self._fleet_with(
+            monkeypatch, tmp_path, {"pid": 4242}, expected_sha="a" * 40
+        )
+        assert fleet[0]["state"] == "unknown"
+
+    def test_dead_pid_excluded(self, monkeypatch, tmp_path):
+        home = tmp_path / "fleet_home2"
+        home.mkdir()
+        (home / "gateway_state.json").write_text(
+            json.dumps({"pid": 999999, "code_sha": "a" * 40}), encoding="utf-8"
+        )
+        monkeypatch.setattr(
+            "hermes_cli.profiles._get_default_hermes_home", lambda: home
+        )
+        monkeypatch.setattr(
+            "hermes_cli.profiles._get_profiles_root",
+            lambda: tmp_path / "nope",
+        )
+        monkeypatch.setattr("gateway.status._pid_exists", lambda pid: False)
+        assert ur.collect_fleet_versions() == []
+
+    def test_matrix_returns_true_only_on_stale(self, capsys):
+        assert ur.print_fleet_version_matrix([]) is False
+        ok = ur.print_fleet_version_matrix(
+            [{"profile": "default", "pid": 1, "code_sha": "a" * 40, "state": "current"}]
+        )
+        assert ok is False
+        stale = ur.print_fleet_version_matrix(
+            [
+                {"profile": "default", "pid": 1, "code_sha": "a" * 40, "state": "current"},
+                {"profile": "work", "pid": 2, "code_sha": "b" * 40, "state": "stale"},
+            ]
+        )
+        assert stale is True
+        out = capsys.readouterr().out
+        assert "STALE" in out
+        assert "hermes -p <profile> gateway restart" in out
+
+    def test_unknown_does_not_fail_update(self, capsys):
+        ok = ur.print_fleet_version_matrix(
+            [{"profile": "default", "pid": 1, "code_sha": None, "state": "unknown"}]
+        )
+        assert ok is False
+        assert "version unknown" in capsys.readouterr().out
+
+
+class TestGatewayStatusStamping:
+    def test_runtime_status_record_carries_code_identity(self, monkeypatch):
+        import gateway.status as gs
+
+        monkeypatch.setattr(
+            "hermes_cli.build_info.get_code_identity",
+            lambda refresh=False: {"sha": "c" * 40, "short_sha": "c" * 8,
+                                   "version": "2.0", "source": "git"},
+        )
+        record = gs._build_runtime_status_record()
+        assert record["code_sha"] == "c" * 40
+        assert record["code_version"] == "2.0"
+
+    def test_code_identity_failure_degrades_to_absent(self, monkeypatch):
+        import gateway.status as gs
+
+        def _boom(refresh=False):
+            raise RuntimeError("no build info")
+
+        monkeypatch.setattr("hermes_cli.build_info.get_code_identity", _boom)
+        record = gs._build_runtime_status_record()
+        # Must not raise, and must not stamp bogus values.
+        assert "code_sha" not in record
+        assert record["gateway_state"] == "starting"
+
+
+class TestCodeIdentity:
+    def test_get_code_identity_shape(self):
+        from hermes_cli.build_info import get_code_identity
+
+        identity = get_code_identity(refresh=True)
+        assert set(identity) == {"sha", "short_sha", "version", "source"}
+        # Running from a git checkout in CI/dev: sha resolves via git.
+        if identity["sha"]:
+            assert identity["short_sha"] == identity["sha"][:8]
+            assert identity["source"] in ("git", "build-file")
+
+    def test_get_code_identity_cached(self):
+        from hermes_cli.build_info import get_code_identity
+
+        first = get_code_identity(refresh=True)
+        second = get_code_identity()
+        assert first == second
+        # returned dicts are copies, not the shared cache
+        second["sha"] = "mutated"
+        assert get_code_identity()["sha"] == first["sha"]