Phase 4: mail & calendar — reads + guarded writes (#23, #24)

Add read tools (get_mail, read_mail, get_calendar) and guarded write tools
(send_mail, set_mail_read, respond_calendar_event). Writes resolve an
explicit character, return a dry-run preview unless confirm=true, and only
execute when writes are enabled. Add EsiClient put/delete.

Closes #23, #24. 112 tests, coverage 90%.

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

tests/test_comms.py

@@ -0,0 +1,77 @@
+"""Mail/calendar read tools and guarded write actions."""
+
+import asyncio
+
+import httpx
+import pytest
+
+from conftest import route
+from familiar import auth, comms, writes
+from familiar.server import mcp
+
+CHARS = [{"character_id": 99, "character_name": "Alpha", "scopes": []}]
+
+
+@pytest.fixture
+def fake_auth(monkeypatch):
+    monkeypatch.setattr(auth, "list_characters", lambda: list(CHARS))
+
+    async def get_auth(cid, **kw):
+        return f"token-{cid}", cid
+
+    monkeypatch.setattr(auth, "get_auth", get_auth)
+    monkeypatch.setattr(auth, "resolve_character", lambda i: 99)
+    return CHARS
+
+
+@pytest.fixture
+def writes_on(tmp_path, monkeypatch):
+    monkeypatch.setenv("FAMILIAR_DATA_DIR", str(tmp_path))
+    monkeypatch.setenv("FAMILIAR_ENABLE_WRITES", "true")
+
+
+def test_get_mail_read(mock_esi, fake_auth):
+    mock_esi(lambda r: route(r, {"/mail/": [{"mail_id": 1, "subject": "hi"}]}))
+    res = asyncio.run(comms.get_mail())
+    assert res["characters"][0]["count"] == 1
+
+
+def test_send_mail_dry_run_does_not_post(mock_esi, fake_auth):
+    posted = []
+    mock_esi(lambda r: (posted.append(r), httpx.Response(201, json=1))[1])
+    res = asyncio.run(comms.send_mail(99, [{"recipient_id": 1}], "s", "b"))
+    assert res["dry_run"] is True
+    assert not posted
+
+
+def test_send_mail_disabled_raises(mock_esi, fake_auth, tmp_path, monkeypatch):
+    monkeypatch.setenv("FAMILIAR_DATA_DIR", str(tmp_path))
+    monkeypatch.delenv("FAMILIAR_ENABLE_WRITES", raising=False)
+    mock_esi(lambda r: httpx.Response(201, json=1))
+    with pytest.raises(writes.WriteDisabled):
+        asyncio.run(comms.send_mail(99, [{"recipient_id": 1}], "s", "b", confirm=True))
+
+
+def test_send_mail_executes_when_enabled(mock_esi, fake_auth, writes_on):
+    mock_esi(lambda r: httpx.Response(201, json=987654))
+    res = asyncio.run(comms.send_mail(99, [{"recipient_id": 1}], "s", "b", confirm=True))
+    assert res["executed"] is True
+    assert res["result"] == 987654
+
+
+def test_respond_calendar_validates_response(mock_esi, fake_auth, writes_on):
+    mock_esi(lambda r: httpx.Response(204, content=b""))
+    res = asyncio.run(comms.respond_calendar_event(99, 5, "banana", confirm=True))
+    assert res["action"] == "respond_calendar_event"
+    assert res["executed"] is True
+
+
+def test_comms_tools_registered():
+    tools = {t.name for t in asyncio.run(mcp.list_tools())}
+    assert {
+        "get_mail",
+        "send_mail",
+        "set_mail_read",
+        "get_calendar",
+        "respond_calendar_event",
+    } <= tools