# Copyright (c) 2026 Krzysztof Rudnicki. MIT licence. """Adding somebody to the roster of an album that already has one. The tagger could only ever write ``people.json`` from empty: the setup form appeared when there were no people, ``Album.setup`` overwrote the file whole, and the keys were handed out by position -- ``p{len + 1}``. Together those mean the obvious thing (edit the list to insert somebody) renumbers everyone after them, and every ``tags.json`` entry then points at the wrong person, silently, with no error at any layer. So in practice a roster was written once and never touched, and a new face meant hand-editing JSON. This module is the append-only path instead. Keys come from the highest number in use, never the count -- the same rule ``pack_custom.next_key`` follows, and for the same reason: deleting ``p3`` by hand must not let a later add reuse the key and inherit its photos. Two checks before anything is written, and they are different in kind: * **Against the album**, by writing the file and then calling ``pack_load.load`` on it. That is the whole of pack_load's validation -- trigger shape, no digits, uniqueness after folding, across people and combos and custom labels -- rather than a second copy of it here that could drift. A failure rolls the file back to the bytes it had. * **Against the bot's own commands**, from ``aliases.json``. ``load`` cannot see those: a person triggered by ``!losuj`` is a perfectly valid pack that quietly shadows ``!random`` at run time. This is the same collision ``pack_add`` refuses a custom label for. """ from __future__ import annotations import json from pathlib import Path from typing import TYPE_CHECKING, Any, Final from signal_bot.folding import fold from signal_bot.groups import ConfigError from signal_bot.pack import PEOPLE_FILE from signal_bot.pack_load import load from signal_bot.pack_store import write_json if TYPE_CHECKING: from collections.abc import Sequence ALIAS_FILE: Final = Path(__file__).with_name("aliases.json") # The person-key shape, mirroring pack_custom.KEY_PATTERN for custom tags. KEY_PREFIX: Final = "p" def reserved() -> frozenset[str]: """Every folded word that is already one of the bot's own commands.""" document = json.loads(ALIAS_FILE.read_text(encoding="utf-8")) return frozenset( fold(trigger) for name, triggers in document.items() if not name.startswith("_") for trigger in triggers ) def next_key(people: Sequence[dict[str, Any]]) -> str: """The key a new person would take, without taking it. One past the highest number in use rather than the count, so a roster somebody has edited by hand cannot make an add reuse a retired key. """ used = [ int(key.removeprefix(KEY_PREFIX)) for person in people if isinstance(key := person.get("key"), str) and key.startswith(KEY_PREFIX) and key.removeprefix(KEY_PREFIX).isdigit() ] return f"{KEY_PREFIX}{max(used, default=0) + 1}" def normalise(triggers: Sequence[str]) -> list[str]: """Trigger spellings as they are stored: "!"-prefixed, blanks dropped. People type "alfa" as often as "!alfa" and the difference is not one worth an error message. """ cleaned = [] for raw in triggers: word = raw.strip() if word: cleaned.append(word if word.startswith("!") else f"!{word}") return cleaned def add_person(directory: Path, triggers: Sequence[str]) -> str: """Append one person to the roster and prove the album still loads. Args: directory: The album directory. triggers: What somebody types to get this person's photos. Returns: The key the new person was given. Raises: ConfigError: The triggers are empty, collide with one of the bot's own commands, or leave the album in a state that does not load. The manifest is unchanged in every one of those cases. """ wanted = normalise(triggers) if not wanted: msg = "a person needs at least one trigger" raise ConfigError(msg) taken = reserved() & {fold(trigger) for trigger in wanted} if taken: msg = f"already a command: {sorted(taken)}" raise ConfigError(msg) path = directory / PEOPLE_FILE document = _document(path) people = list(document.get("people", [])) key = next_key(people) document["people"] = [*people, {"key": key, "triggers": wanted}] return _commit(directory, path, document, key) def merge(document: dict[str, Any], people: Sequence[dict[str, Any]]) -> list[dict[str, Any]]: """The roster with ``people`` folded in, existing keys left where they are. Used by the setup form, which used to replace the file wholesale. Anyone already present keeps their key and gains any new triggers; anyone new is appended with a fresh key. """ merged = [dict(person) for person in document.get("people", [])] by_key = {person.get("key"): person for person in merged} for person in people: existing = by_key.get(person.get("key")) if existing is None: fresh = dict(person) fresh["key"] = next_key(merged) merged.append(fresh) by_key[fresh["key"]] = fresh continue seen = set(existing.get("triggers", [])) existing["triggers"] = [ *existing.get("triggers", []), *(t for t in person.get("triggers", []) if t not in seen), ] return merged def _commit(directory: Path, path: Path, document: dict[str, Any], key: str) -> str: """Write the roster, or put back exactly what was there and re-raise.""" previous = path.read_bytes() if path.exists() else None write_json(path, document) try: load(directory) except ConfigError: if previous is None: path.unlink(missing_ok=True) else: path.write_bytes(previous) raise return key def _document(path: Path) -> dict[str, Any]: """The roster as it stands. Strict, unlike the ledger's reader: this file *is* the album's manifest, and appending to a document that failed to parse would write a roster that silently dropped everyone already in it. Raises: ConfigError: The file is not a JSON object. """ if not path.exists(): return {} try: document = json.loads(path.read_text(encoding="utf-8")) except json.JSONDecodeError as error: msg = f"{path.name} is not valid JSON: {error}" raise ConfigError(msg) from error if not isinstance(document, dict): msg = f"{path.name} is not an object" raise ConfigError(msg) return document