dndkit 0.4.0__py3-none-any.whl

dndkit/storage/store.py

@@ -0,0 +1,278 @@
+"""The campaign store: one active campaign, saved as JSON, safe across threads
+and across processes sharing the data directory (``sharing``)."""
+
+import logging
+import threading
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from dndkit.errors import (
+    AlreadyExistsError,
+    GameError,
+    InvalidChangeError,
+    NoActiveCampaignError,
+    NotFoundError,
+)
+from dndkit.models import Campaign, GameState, now
+from dndkit.storage.catalog import CampaignEntry, modified_at, read_entry
+from dndkit.storage.confirmations import Confirmations
+from dndkit.storage.files import campaign_slug, read_json, same_slug, write_json_atomic
+from dndkit.storage.sharing import DiskLock, Stamp, stamp
+
+logger = logging.getLogger(__name__)
+
+SETTING_SUFFIXES = (".md", ".txt")
+MAX_SETTING_BYTES = 200_000
+
+
+class CampaignStore:
+    """Holds the active campaign and writes every change to disk.
+
+    FastMCP runs synchronous tools in a thread pool, and voice models often
+    call several tools at once, so every access goes through one lock.
+    *on_change* is called, from the changing thread, after every saved change
+    and every switch of campaign: the web pages wait on it. Another process
+    may share the data directory: changes take turns with it, and the active
+    campaign is read again when its file changed elsewhere.
+    """
+
+    def __init__(
+        self,
+        data_dir: Path,
+        confirmations: Confirmations | None = None,
+        on_change: Callable[[], None] | None = None,
+    ) -> None:
+        self.data_dir = data_dir
+        self.campaigns_dir = data_dir / "campaigns"
+        self.settings_dir = data_dir / "settings"
+        self.trash_dir = data_dir / "trash"
+        self.confirmations = confirmations or Confirmations()
+        self.campaigns_dir.mkdir(parents=True, exist_ok=True)
+        self.settings_dir.mkdir(parents=True, exist_ok=True)
+        self._on_change = on_change or (lambda: None)
+        self._lock = threading.RLock()
+        self._disk = DiskLock(data_dir)
+        self._current: Campaign | None = None
+        self._current_path: Path | None = None
+        self._stamp: Stamp | None = None  # the active file as we last read or wrote it
+        # When this server started: a roll call older than that was another session's.
+        self.opened_at = now()
+        self._open_most_recent()
+
+    @property
+    def current(self) -> Campaign | None:
+        """The active campaign, if any."""
+        with self._lock:
+            return self._current
+
+    @property
+    def current_file(self) -> Path | None:
+        """Where the active campaign is saved, if any."""
+        with self._lock:
+            return self._current_path
+
+    def list_campaigns(self) -> list[CampaignEntry]:
+        """A summary of every campaign file, most recently used first."""
+        with self._lock:
+            entries = [read_entry(path) for path in self.campaigns_dir.glob("*.json")]
+        return sorted(entries, key=lambda entry: entry.modified, reverse=True)
+
+    def create(
+        self,
+        name: str,
+        description: str,
+        dm_name: str | None = None,
+        setting: str | None = None,
+    ) -> Campaign:
+        """Create a campaign and make it active; an existing one is never replaced."""
+        slug = campaign_slug(name)
+        with self._lock, self._disk.held():
+            existing = self._file_for_slug(slug)
+            if existing is not None:
+                raise AlreadyExistsError(
+                    f"A campaign named '{read_entry(existing).name}' already exists. "
+                    "Open it with load_campaign or pick another name."
+                )
+            title = name.strip()
+            campaign = Campaign(
+                name=title,
+                description=description,
+                dm_name=dm_name,
+                setting=setting,
+                game_state=GameState(campaign_name=title),
+            )
+            path = self.campaigns_dir / f"{slug}.json"
+            self._write(campaign, path)
+            self._open(campaign, path)
+            logger.info("Created campaign %r in %s", title, path)
+        self._on_change()
+        return campaign
+
+    def load(self, name: str) -> Campaign:
+        """Open a campaign by name and make it active."""
+        with self._lock:
+            path = self._require_file(name)
+            campaign = self._read(path)
+            path.touch()  # the most recently opened campaign reopens at the next start
+            self._open(campaign, path)
+        self._on_change()
+        return campaign
+
+    def request_deletion(self, name: str) -> tuple[CampaignEntry, str]:
+        """What deleting *name* would remove, and the code that confirms it."""
+        with self._lock:
+            path = self._require_file(name)
+            return read_entry(path), self.confirmations.issue(str(path))
+
+    def delete(self, name: str, code: str) -> tuple[CampaignEntry, Path]:
+        """Move a campaign to the trash, given the code ``request_deletion`` issued.
+
+        Returns what was deleted and where its file went. Deleting the active
+        campaign leaves none active.
+        """
+        with self._lock, self._disk.held():
+            path = self._require_file(name)
+            if not self.confirmations.consume(str(path), code):
+                raise InvalidChangeError(
+                    "That confirmation code is wrong or expired, so nothing was deleted. "
+                    "Call delete_campaign without a code to get a new one."
+                )
+            entry = read_entry(path)
+            self.trash_dir.mkdir(parents=True, exist_ok=True)
+            target = self._trash_path(path.stem)
+            path.replace(target)
+            if self._current_path == path:
+                self._open(None, None)
+            logger.info("Moved campaign %r to %s", entry.name, target)
+        self._on_change()
+        return entry, target
+
+    def read_setting_file(self, file_name: str) -> str:
+        """Text of a .md/.txt file placed directly in the settings directory."""
+        folder = self.settings_dir.resolve()
+        candidate = (folder / file_name).resolve()
+        if candidate.parent != folder or candidate.suffix.lower() not in SETTING_SUFFIXES:
+            raise InvalidChangeError(
+                f"A setting file is a .md or .txt file directly inside {folder}."
+            )
+        if not candidate.is_file():
+            files = [p for p in folder.iterdir() if p.is_file()]
+            available = sorted(p.name for p in files if p.suffix.lower() in SETTING_SUFFIXES)
+            raise NotFoundError(
+                f"No setting file '{file_name}' in {folder}. "
+                f"Available: {', '.join(available) or 'none'}."
+            )
+        if candidate.stat().st_size > MAX_SETTING_BYTES:
+            raise InvalidChangeError(f"'{file_name}' is over {MAX_SETTING_BYTES} bytes.")
+        try:
+            return candidate.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise InvalidChangeError(f"'{file_name}' is not UTF-8: save it as UTF-8.") from exc
+
+    @contextmanager
+    def transaction(self) -> Iterator[Campaign]:
+        """The active campaign to change: saved on success, restored on any failure.
+
+        A tool that fails halfway leaves nothing behind, in memory or on disk,
+        so the model can retry without doubling an item or a hit.
+        """
+        with self._lock, self._disk.held():
+            self._catch_up()
+            campaign, path = self._require_current()
+            snapshot = campaign.model_copy(deep=True)
+            try:
+                yield campaign
+                campaign.updated_at = now()
+                self._write(campaign, path)
+                self._stamp = stamp(path)
+            except BaseException:
+                self._current = snapshot
+                raise
+        self._on_change()
+
+    @contextmanager
+    def reading(self) -> Iterator[Campaign]:
+        """The active campaign, to read while no tool changes it."""
+        with self._lock:
+            self._catch_up()
+            campaign, _ = self._require_current()
+            yield campaign
+
+    def close(self) -> None:
+        """Let go of the lock file."""
+        self._disk.close()
+
+    def _open(self, campaign: Campaign | None, path: Path | None) -> None:
+        self._current, self._current_path = campaign, path
+        self._stamp = stamp(path) if path else None
+
+    def _catch_up(self) -> None:
+        """Read the active campaign again if its file changed in another process."""
+        path = self._current_path
+        if path is None or stamp(path) == self._stamp:
+            return
+        if not path.exists():
+            logger.warning("Campaign file %s was removed by another program.", path)
+            self._open(None, None)
+        else:
+            logger.info("Campaign file %s changed in another program: read again.", path)
+            self._open(self._read(path), path)
+        self._on_change()
+
+    def _require_current(self) -> tuple[Campaign, Path]:
+        if self._current is None or self._current_path is None:
+            raise NoActiveCampaignError()
+        return self._current, self._current_path
+
+    def _require_file(self, name: str) -> Path:
+        path = self._file_for_slug(campaign_slug(name))
+        if path is None:
+            known = ", ".join(entry.name for entry in self.list_campaigns()) or "none yet"
+            raise NotFoundError(f"No campaign named '{name}'. Known campaigns: {known}.")
+        return path
+
+    def _trash_path(self, stem: str) -> Path:
+        stamp = now().strftime("%Y-%m-%d %H%M%S")
+        target = self.trash_dir / f"{stem} {stamp}.json"
+        number = 2
+        while target.exists():
+            target = self.trash_dir / f"{stem} {stamp} {number}.json"
+            number += 1
+        return target
+
+    def _file_for_slug(self, slug: str) -> Path | None:
+        for path in self.campaigns_dir.glob("*.json"):
+            if same_slug(path.stem, slug):
+                return path
+        return None
+
+    def _open_most_recent(self) -> None:
+        paths = sorted(self.campaigns_dir.glob("*.json"), key=modified_at, reverse=True)
+        for path in paths:
+            try:
+                self._open(self._read(path), path)
+            except GameError as exc:
+                logger.error("Skipping campaign file %s: %s", path, exc)
+                continue
+            logger.info("Opened campaign %r from %s", path.stem, path)
+            return
+        logger.info("No campaign to open in %s", self.campaigns_dir)
+
+    @staticmethod
+    def _read(path: Path) -> Campaign:
+        try:
+            return Campaign.model_validate(read_json(path))
+        # JSONDecodeError and ValidationError are ValueErrors; absurdly deep JSON recurses.
+        except (OSError, ValueError, RecursionError) as exc:
+            detail = str(exc)
+            if isinstance(exc, ValidationError):
+                first = exc.errors()[0]
+                detail = f"{'.'.join(map(str, first['loc']))}: {first['msg']}"
+            raise GameError(f"Campaign file {path.name} cannot be read: {detail}") from exc
+
+    @staticmethod
+    def _write(campaign: Campaign, path: Path) -> None:
+        write_json_atomic(path, campaign.model_dump(mode="json"))

dndkit/text.py

@@ -0,0 +1,13 @@
+"""How two spellings of one name compare, for every layer (storage included)."""
+
+import unicodedata
+
+
+def normalize(name: str) -> str:
+    """Casefolded, accent-free, single-spaced: "Élodie " and "elodie" are one name.
+
+    A voice transcript rarely spells a name the way it was typed.
+    """
+    decomposed = unicodedata.normalize("NFKD", name)
+    bare = "".join(c for c in decomposed if not unicodedata.combining(c))
+    return " ".join(bare.casefold().split())

dndkit/tools/__init__.py

@@ -0,0 +1,47 @@
+"""MCP tools: thin adapters from tool calls to the game logic.
+
+Each module lists its tools in ``TOOLS``; ``ALL_TOOLS`` is what the server
+registers.
+"""
+
+from collections.abc import Callable
+
+from dndkit.tools import (
+    battle,
+    bestiary,
+    campaign,
+    characters,
+    combat,
+    journal,
+    locations,
+    npcs,
+    play,
+    players,
+    progression,
+    quests,
+    resources,
+    screen,
+    spells,
+    utility,
+)
+
+ALL_TOOLS: list[Callable[..., str]] = [
+    *campaign.TOOLS,
+    *characters.TOOLS,
+    *resources.TOOLS,
+    *spells.TOOLS,
+    *progression.TOOLS,
+    *npcs.TOOLS,
+    *locations.TOOLS,
+    *quests.TOOLS,
+    *play.TOOLS,
+    *players.TOOLS,
+    *combat.TOOLS,
+    *battle.TOOLS,
+    *bestiary.TOOLS,
+    *journal.TOOLS,
+    *utility.TOOLS,
+    *screen.TOOLS,
+]
+
+__all__ = ["ALL_TOOLS"]

dndkit/tools/apps.py

@@ -0,0 +1,47 @@
+"""MCP Apps: which tools open a widget, and the page each widget loads.
+
+A tool whose ``_meta.ui.resourceUri`` names a ``ui://`` resource opens that
+page in clients that support MCP Apps (roomkit-ui shows it in the chat);
+other clients ignore the metadata. roomkit-ui hands a page only the tool's
+text result, so each page reads its data from ``get_screen_data`` instead.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from fastmcp import FastMCP
+
+from dndkit import ui
+
+DICE_APP = "ui://dndkit/dice.html"
+COMBAT_APP = "ui://dndkit/combat.html"
+PARTY_APP = "ui://dndkit/party.html"
+CHARACTER_APP = "ui://dndkit/character.html"
+SEATING_APP = "ui://dndkit/seating.html"
+
+_PAGES = {
+    DICE_APP: ("dice", "Dice tray: the latest roll, rolling."),
+    COMBAT_APP: ("combat", "Combat tracker: initiative, hit points, conditions, live."),
+    PARTY_APP: ("party", "Party board: hit points, conditions, location and quests, live."),
+    CHARACTER_APP: ("character", "Character sheet, live."),
+    SEATING_APP: ("seating", "The table: who plays which character tonight, live."),
+}
+
+
+def app_meta(uri: str) -> dict[str, Any]:
+    """Tool metadata that opens the page at *uri*."""
+    return {"ui": {"resourceUri": uri}}
+
+
+def register_apps(server: FastMCP) -> None:
+    """Serve every page as a ``ui://`` resource (MIME text/html;profile=mcp-app)."""
+    for uri, (name, description) in _PAGES.items():
+        server.resource(uri, name=f"{name}-app", description=description)(_loader(name))
+
+
+def _loader(name: str) -> Callable[[], str]:
+    def load() -> str:
+        return ui.page(name)
+
+    load.__name__ = f"{name}_app"
+    return load

dndkit/tools/battle.py

@@ -0,0 +1,117 @@
+"""Battle map tools: lay out the map, put combatants on it, move them by the rules."""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastmcp.dependencies import Depends
+from fastmcp.tools import tool
+from pydantic import Field
+
+from dndkit.game import areas, battlefield, combat, movement, sight
+from dndkit.game.areas import Aim, Shape
+from dndkit.game.movement import Order
+from dndkit.models import Placement
+from dndkit.models.battle import MAX_SQUARES
+from dndkit.storage import CampaignStore
+from dndkit.tools import render_combat, render_map
+from dndkit.tools.apps import COMBAT_APP, app_meta
+from dndkit.tools.deps import READ_ONLY, get_store
+
+Squares = Annotated[list[str] | None, Field(description='Squares: "C3", or "C1:C6" for a block')]
+Creature = Annotated[str | None, Field(description="A combatant")]
+
+
+@tool(meta=app_meta(COMBAT_APP))
+def set_battlefield(
+    width: Annotated[int, Field(ge=1, le=MAX_SQUARES, description="Squares across, 5 ft each")],
+    height: Annotated[int, Field(ge=1, le=MAX_SQUARES, description="Squares down")],
+    walls: Squares = None,
+    difficult: Squares = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Lay out the battle map (A1 top left). Whoever has no square goes to an edge:
+    the party left, foes right."""
+    with store.transaction() as campaign:
+        state = campaign.game_state
+        battlefield.lay_out(state, width, height, walls or [], difficult or [])
+        battlefield.place_the_rest(state)
+        return render_map.battle_map(campaign)
+
+
+@tool
+def place_tokens(
+    tokens: Annotated[list[Placement], Field(min_length=1, description="Who and where")],
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Put combatants on squares (big ones by their top-left square), or hide them from
+    the players (an ambush) and reveal them. remove_combatant takes one off."""
+    with store.transaction() as campaign:
+        state = campaign.game_state
+        for token in tokens:
+            combatant = combat.find(state, token.who)
+            if token.ally is not None:
+                combatant.ally = token.ally
+            if token.hidden is not None:
+                combatant.hidden = token.hidden
+            if token.at is not None:
+                combatant.position = None
+                battlefield.place(state, combatant, token.at)
+        if state.battlefield is None:
+            return render_combat.initiative(campaign)
+        return render_map.battle_map(campaign)
+
+
+@tool
+def move_token(
+    who: Annotated[str, Field(min_length=1, description="The combatant moving")],
+    to: Annotated[str | None, Field(description="Square, e.g. D7")] = None,
+    toward: Creature = None,
+    away_from: Creature = None,
+    feet: Annotated[int | None, Field(ge=5, description="At most this far")] = None,
+    dash: Annotated[bool, Field(description="Dash: double movement this turn")] = False,
+    disengage: Annotated[bool, Field(description="Disengage: no opportunity attacks")] = False,
+    forced: Annotated[bool, Field(description="Pushed, pulled or teleported")] = False,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Move by the 5e rules; says the cost, movement left, opportunity attacks and who is
+    in reach. Refuses impossible moves; toward stops within reach."""
+    order = Order(to=to, toward=toward, away_from=away_from, feet=feet)
+    with store.transaction() as campaign:
+        done = movement.move(campaign, who, order, dash=dash, disengage=disengage, forced=forced)
+        return render_map.move(campaign, done)
+
+
+@tool
+def area_of_effect(
+    shape: Annotated[Shape, Field(description="sphere also for cylinders")],
+    feet: Annotated[int, Field(ge=5, description="Radius, cube side, or cone/line length")],
+    at: Annotated[str | None, Field(description="Centre: square or creature")] = None,
+    source: Annotated[str | None, Field(description="Caster of a cone, line or cube")] = None,
+    toward: Annotated[str | None, Field(description="Square or creature aimed at")] = None,
+    width: Annotated[int, Field(ge=5, description="Line width")] = 5,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Who an area of effect catches; walls stop it. Shown until the next turn."""
+    aim = Aim(shape=shape, feet=feet, at=at, source=source, toward=toward, width=width)
+    with store.transaction() as campaign:
+        return render_map.area(areas.resolve(campaign.game_state, aim))
+
+
+@tool(annotations=READ_ONLY)
+def check_target(
+    attacker: Annotated[str, Field(min_length=1, description="Who attacks")],
+    target: Annotated[str, Field(min_length=1, description="Who is attacked")],
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Before an attack on the map: distance, reach, cover, and what gives disadvantage."""
+    with store.reading() as campaign:
+        return render_map.sightline(sight.look(campaign, attacker, target))
+
+
+TOOLS: list[Callable[..., str]] = [
+    set_battlefield,
+    place_tokens,
+    move_token,
+    area_of_effect,
+    check_target,
+]

dndkit/tools/bestiary.py

@@ -0,0 +1,121 @@
+"""Bestiary and encounter tools."""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastmcp.dependencies import Depends
+from fastmcp.tools import tool
+from pydantic import Field
+
+from dndkit.game import battlefield as battlefields
+from dndkit.game import bestiary, combatants
+from dndkit.models import EncounterGroup, Layout, Size
+from dndkit.storage import CampaignStore
+from dndkit.tools import render_combat
+from dndkit.tools.deps import READ_ONLY, get_store, provided
+
+Text = Annotated[str | None, Field(description="Free text")]
+
+
+@tool
+def save_monster(
+    name: Annotated[str, Field(min_length=1, description="Monster name, e.g. Goblin")],
+    armor_class: Annotated[int | None, Field(ge=0, description="AC")] = None,
+    hit_points: Annotated[int | None, Field(ge=1, description="Average HP")] = None,
+    challenge_rating: Annotated[str | None, Field(description="CR, e.g. 1/4 or 3")] = None,
+    xp: Annotated[int | None, Field(ge=0, description="XP; derived from CR if omitted")] = None,
+    initiative_bonus: Annotated[int | None, Field(description="Dexterity modifier")] = None,
+    speed: Annotated[str | None, Field(description="e.g. 30 ft., fly 60 ft.")] = None,
+    size: Annotated[Size | None, Field(description="Size")] = None,
+    actions: Annotated[str | None, Field(description="Attacks and abilities")] = None,
+    notes: Text = None,
+    boss: Annotated[bool | None, Field(description="The fight's boss")] = None,
+    legendary_actions: Annotated[int | None, Field(ge=0, le=5, description="Per round")] = None,
+    legendary_resistances: Annotated[int | None, Field(ge=0, le=5, description="Per day")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Save or update a monster stat block; combatants named after it get its stats.
+    A book monster (goblin, orc) takes its book numbers. For one you invent, a challenge
+    rating alone sets AC, HP and attacks (DMG table, sturdy at low CR). A boss gets 3
+    legendary actions and resistances unless told."""
+    fields = provided(
+        armor_class=armor_class,
+        hit_points=hit_points,
+        challenge_rating=challenge_rating,
+        xp=xp,
+        initiative_bonus=initiative_bonus,
+        speed=speed,
+        size=size,
+        actions=actions,
+        notes=notes,
+        boss=boss,
+        legendary_actions=legendary_actions,
+        legendary_resistances=legendary_resistances,
+    )
+    with store.transaction() as campaign:
+        monster, created = bestiary.save_monster(campaign, name, fields)
+        caught_up = combatants.refresh(campaign)  # a monster already fighting takes it
+    saved = f"{'Saved' if created else 'Updated'} {render_combat.monster(monster)}"
+    estimated = created and challenge_rating and (armor_class is None or hit_points is None)
+    return "\n".join([saved, *([ESTIMATED] if estimated else []), *caught_up])
+
+
+ESTIMATED = (
+    "AC and HP come from the challenge rating (DMG table). A book monster has its own: "
+    "save them with save_monster if it is one."
+)
+
+
+@tool(annotations=READ_ONLY)
+def get_monsters(
+    name: Annotated[str | None, Field(description="One monster; omit to list all")] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """A monster's stat block, or the whole bestiary."""
+    with store.reading() as campaign:
+        if name:
+            return render_combat.monster(bestiary.find_monster(campaign, name))
+        monsters = sorted(campaign.monsters.values(), key=lambda m: m.name)
+        if not monsters:
+            return "The bestiary is empty; add monsters with save_monster."
+        return "\n".join(render_combat.monster(m).splitlines()[0] for m in monsters)
+
+
+@tool
+def plan_encounter(
+    name: Annotated[str, Field(min_length=1, description="Encounter name")],
+    monsters: Annotated[
+        list[EncounterGroup] | None, Field(description="Bestiary monsters and how many")
+    ] = None,
+    description: Text = None,
+    location: Annotated[str | None, Field(description="Where it happens")] = None,
+    notes: Text = None,
+    battlefield: Annotated[
+        Layout | None, Field(description="Its battle map; monsters may then have squares")
+    ] = None,
+    store: CampaignStore = Depends(get_store),
+) -> str:
+    """Prepare (or change) a fight and rate its difficulty for the party.
+    Run it later with start_combat(encounter=...), which lays out its map."""
+    fields = provided(description=description, location=location, notes=notes)
+    if battlefield is not None:
+        fields["battlefield"] = battlefields.build(
+            battlefield.width, battlefield.height, battlefield.walls, battlefield.difficult
+        )
+    with store.transaction() as campaign:
+        encounter, created = bestiary.plan_encounter(campaign, name, monsters, fields)
+        text = render_combat.encounter(campaign, encounter)
+    return f"{'Planned' if created else 'Updated'} {text}"
+
+
+@tool(annotations=READ_ONLY)
+def list_encounters(store: CampaignStore = Depends(get_store)) -> str:
+    """Planned encounters with their monsters, status and difficulty."""
+    with store.reading() as campaign:
+        encounters = list(campaign.encounters.values())
+        if not encounters:
+            return "No encounter planned."
+        return "\n".join(f"- {render_combat.encounter(campaign, e)}" for e in encounters)
+
+
+TOOLS: list[Callable[..., str]] = [save_monster, get_monsters, plan_encounter, list_encounters]