From b3f06af8a425f530d25205fd64db48c87ed7c14b Mon Sep 17 00:00:00 2001 From: Latte Date: Sat, 27 Jun 2026 20:14:57 +0200 Subject: [PATCH] =?UTF-8?q?Phase=204:=20contacts=20&=20fittings=20?= =?UTF-8?q?=E2=80=94=20reads=20+=20guarded=20writes=20(#25,=20#26)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Contacts: read character/corp/alliance contacts; guarded add/remove of character contacts. Fittings: read saved fits; guarded create/delete. EsiClient.delete now takes params. All writes go through write-safety. Closes #25, #26. 120 tests, coverage 89%. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/familiar/contacts.py | 106 ++++++++++++++++++++++++++++++++ src/familiar/esi.py | 6 +- src/familiar/fittings.py | 71 +++++++++++++++++++++ src/familiar/server.py | 6 ++ tests/test_contacts_fittings.py | 97 +++++++++++++++++++++++++++++ 5 files changed, 284 insertions(+), 2 deletions(-) create mode 100644 src/familiar/contacts.py create mode 100644 src/familiar/fittings.py create mode 100644 tests/test_contacts_fittings.py diff --git a/src/familiar/contacts.py b/src/familiar/contacts.py new file mode 100644 index 0000000..9773736 --- /dev/null +++ b/src/familiar/contacts.py @@ -0,0 +1,106 @@ +"""Contacts: read (character, corp, alliance) plus guarded character writes.""" + +from __future__ import annotations + +from typing import Any + +from fastmcp import FastMCP + +from . import auth, writes +from .charutil import corporation_id, run_per_character, run_per_corp, summarize +from .esi import client + + +async def get_contacts(character: str | int | None = None, limit: int = 50) -> dict[str, Any]: + """Personal contacts for one character or all.""" + + async def fetch(token: str, cid: int) -> dict[str, Any]: + contacts = await client().get_all_pages(f"/characters/{cid}/contacts/", token=token) + return summarize(contacts, limit) + + return await run_per_character(character, fetch) + + +async def get_corp_contacts(character: str | int | None = None, limit: int = 50) -> dict[str, Any]: + """Corp contacts (needs a corp role) for one character's corp or all.""" + + async def fetch(token: str, corp_id: int, cid: int) -> dict[str, Any]: + contacts = await client().get_all_pages(f"/corporations/{corp_id}/contacts/", token=token) + return summarize(contacts, limit) + + return await run_per_corp(character, fetch) + + +async def get_alliance_contacts( + character: str | int | None = None, limit: int = 50 +) -> dict[str, Any]: + """Alliance contacts, resolved via each character's corp's alliance.""" + + async def fetch(token: str, cid: int) -> dict[str, Any]: + corp_id = await corporation_id(cid) + corp = await client().get(f"/corporations/{corp_id}/") + alliance_id = corp.get("alliance_id") + if not alliance_id: + return {"alliance_id": None, "count": 0, "sample": []} + contacts = await client().get_all_pages(f"/alliances/{alliance_id}/contacts/", token=token) + return {"alliance_id": alliance_id, **summarize(contacts, limit)} + + return await run_per_character(character, fetch) + + +async def add_contacts( + character: str | int, + contact_ids: list[int], + standing: float = 0.0, + confirm: bool = False, +) -> dict[str, Any]: + """Add personal contacts with a standing. WRITE — guarded by write-safety.""" + cid = auth.resolve_character(character) + + async def execute() -> Any: + token, _ = await auth.get_auth(cid) + return await client().post( + f"/characters/{cid}/contacts/", + json=contact_ids, + params={"standing": standing}, + token=token, + ) + + return await writes.guard( + "add_contacts", + {"character_id": cid, "contact_ids": contact_ids, "standing": standing}, + confirm, + execute, + ) + + +async def remove_contacts( + character: str | int, contact_ids: list[int], confirm: bool = False +) -> dict[str, Any]: + """Remove personal contacts. WRITE — guarded by write-safety.""" + cid = auth.resolve_character(character) + + async def execute() -> Any: + token, _ = await auth.get_auth(cid) + return await client().delete( + f"/characters/{cid}/contacts/", params={"contact_ids": contact_ids}, token=token + ) + + return await writes.guard( + "remove_contacts", {"character_id": cid, "contact_ids": contact_ids}, confirm, execute + ) + + +TOOLS = [ + get_contacts, + get_corp_contacts, + get_alliance_contacts, + add_contacts, + remove_contacts, +] + + +def register(mcp: FastMCP) -> None: + """Register the contacts tools onto the given server.""" + for fn in TOOLS: + mcp.tool(fn) diff --git a/src/familiar/esi.py b/src/familiar/esi.py index 63f99ec..e9f6a7c 100644 --- a/src/familiar/esi.py +++ b/src/familiar/esi.py @@ -72,8 +72,10 @@ class EsiClient: ) -> Any: return await self._request("PUT", path, params=params, json=json, token=token) - async def delete(self, path: str, token: str | None = None) -> Any: - return await self._request("DELETE", path, token=token) + async def delete( + self, path: str, params: dict[str, Any] | None = None, token: str | None = None + ) -> Any: + return await self._request("DELETE", path, params=params, token=token) async def get_all_pages( self, path: str, params: dict[str, Any] | None = None, token: str | None = None diff --git a/src/familiar/fittings.py b/src/familiar/fittings.py new file mode 100644 index 0000000..1230bb1 --- /dev/null +++ b/src/familiar/fittings.py @@ -0,0 +1,71 @@ +"""Ship fittings: read plus guarded create/delete writes.""" + +from __future__ import annotations + +from typing import Any + +from fastmcp import FastMCP + +from . import auth, writes +from .charutil import run_per_character, summarize +from .esi import client + + +async def get_fittings(character: str | int | None = None, limit: int = 50) -> dict[str, Any]: + """Saved ship fittings for one character or all.""" + + async def fetch(token: str, cid: int) -> dict[str, Any]: + fits = await client().get(f"/characters/{cid}/fittings/", token=token) or [] + return summarize(fits, limit) + + return await run_per_character(character, fetch) + + +async def create_fitting( + character: str | int, fitting: dict[str, Any], confirm: bool = False +) -> dict[str, Any]: + """Save a new fitting. WRITE — guarded by write-safety. + + ``fitting`` is an ESI fitting object: ``name``, ``description``, + ``ship_type_id``, and ``items`` (list of ``{type_id, flag, quantity}``). + """ + cid = auth.resolve_character(character) + + async def execute() -> Any: + token, _ = await auth.get_auth(cid) + return await client().post(f"/characters/{cid}/fittings/", json=fitting, token=token) + + return await writes.guard( + "create_fitting", + { + "character_id": cid, + "name": fitting.get("name"), + "ship_type_id": fitting.get("ship_type_id"), + }, + confirm, + execute, + ) + + +async def delete_fitting( + character: str | int, fitting_id: int, confirm: bool = False +) -> dict[str, Any]: + """Delete a saved fitting. WRITE — guarded by write-safety.""" + cid = auth.resolve_character(character) + + async def execute() -> Any: + token, _ = await auth.get_auth(cid) + return await client().delete(f"/characters/{cid}/fittings/{fitting_id}/", token=token) + + return await writes.guard( + "delete_fitting", {"character_id": cid, "fitting_id": fitting_id}, confirm, execute + ) + + +TOOLS = [get_fittings, create_fitting, delete_fitting] + + +def register(mcp: FastMCP) -> None: + """Register the fittings tools onto the given server.""" + for fn in TOOLS: + mcp.tool(fn) diff --git a/src/familiar/server.py b/src/familiar/server.py index ab6788b..e5082e2 100644 --- a/src/familiar/server.py +++ b/src/familiar/server.py @@ -15,8 +15,10 @@ from . import ( __version__, account, comms, + contacts, corp, corp_economy, + fittings, industry, killmails, market, @@ -87,3 +89,7 @@ misc.register(mcp) # Phase 4: mail & calendar (read + guarded writes). comms.register(mcp) + +# Phase 4: contacts & fittings (read + guarded writes). +contacts.register(mcp) +fittings.register(mcp) diff --git a/tests/test_contacts_fittings.py b/tests/test_contacts_fittings.py new file mode 100644 index 0000000..105ce18 --- /dev/null +++ b/tests/test_contacts_fittings.py @@ -0,0 +1,97 @@ +"""Contacts and fittings: reads + guarded writes.""" + +import asyncio + +import httpx +import pytest + +from conftest import route +from familiar import auth, contacts, fittings, 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_contacts(mock_esi, fake_auth): + mock_esi(lambda r: route(r, {"/contacts/": [{"contact_id": 1, "standing": 5.0}]})) + res = asyncio.run(contacts.get_contacts()) + assert res["characters"][0]["count"] == 1 + + +def test_alliance_contacts(mock_esi, fake_auth): + fixtures = { + "/characters/99/": {"corporation_id": 2000}, + "/corporations/2000/": {"alliance_id": 3000}, + "/alliances/": [{"contact_id": 7}], + } + mock_esi(lambda r: route(r, fixtures)) + res = asyncio.run(contacts.get_alliance_contacts()) + assert res["characters"][0]["alliance_id"] == 3000 + assert res["characters"][0]["count"] == 1 + + +def test_add_contacts_dry_run(mock_esi, fake_auth): + posted = [] + mock_esi(lambda r: (posted.append(r), httpx.Response(200, json=[1]))[1]) + res = asyncio.run(contacts.add_contacts(99, [1, 2], standing=5.0)) + assert res["dry_run"] is True + assert not posted + + +def test_remove_contacts_executes(mock_esi, fake_auth, writes_on): + mock_esi(lambda r: httpx.Response(204, content=b"")) + res = asyncio.run(contacts.remove_contacts(99, [1], confirm=True)) + assert res["executed"] is True + + +def test_get_fittings(mock_esi, fake_auth): + mock_esi(lambda r: route(r, {"/fittings/": [{"fitting_id": 1, "name": "PvP Rifter"}]})) + res = asyncio.run(fittings.get_fittings()) + assert res["characters"][0]["count"] == 1 + + +def test_create_fitting_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={"fitting_id": 5})) + with pytest.raises(writes.WriteDisabled): + asyncio.run(fittings.create_fitting(99, {"name": "x"}, confirm=True)) + + +def test_create_fitting_executes(mock_esi, fake_auth, writes_on): + mock_esi(lambda r: httpx.Response(201, json={"fitting_id": 5})) + res = asyncio.run(fittings.create_fitting(99, {"name": "x", "ship_type_id": 587}, confirm=True)) + assert res["executed"] is True + assert res["result"]["fitting_id"] == 5 + + +def test_contacts_fittings_registered(): + tools = {t.name for t in asyncio.run(mcp.list_tools())} + assert { + "get_contacts", + "get_corp_contacts", + "get_alliance_contacts", + "add_contacts", + "remove_contacts", + "get_fittings", + "create_fitting", + "delete_fitting", + } <= tools