Files
MeshTerm/meshterm/ui/contacts_screen.py
T
Jean-Pierre MartineauandClaude Fable 5 0add80a821 Footers: one verb per Enter, settled in the standard
Five words had grown for one key — select, pick, open, choose, commit —
so CLAUDE.md now fixes the Enter verb by action (open pushes a screen,
select picks a value or action row, set commits a value picker) and the
outliers come along: the purge and discipline pickers say select, the
record card's action rows say select, "Esc keep current" and the three
"type filter"s were typos against existing rules (housekeeping H-008).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-29 23:13:55 -04:00

325 lines
14 KiB
Python

"""The interactive Contacts screen: the device's contacts in the shared sortable contact list.
The Time Machine picker's presentation pointed at the companion's contact table: the same
aligned ``NAME · HEARD · PKTS · KEY`` lanes, our own node pinned first, the same Ctrl+arrow
sort (now including the key column) and type-to-filter — one contact list app-wide, whatever
the data source (see :mod:`~meshterm.ui.contactlist`). Enter opens the highlighted node's
full-screen Node detail page (:mod:`~meshterm.ui.node_detail_screen`) — its identity, a
location preview, the observed routes to it, and the ways in (trace, map, time machine) —
and backing out of that page returns to the list right where it stood. The one-shot CLI
(``meshterm contacts --sort …``) still renders the static
:func:`~meshterm.ui.widgets.contacts_table`; only the menu gets the live list.
Below the contacts sits one maintenance action — **Purge stale contacts** — that sweeps out
the contacts a device has accumulated but no longer hears. It offers an age ladder (a week up
to a year, plus a *never heard* bucket), each rung showing a live count of how many contacts
it would remove, so the impact is visible before anything is chosen; the pick is then gated
behind a typed ``delete`` confirm. A purge deletes the contacts from the device's table and
forgets them from the cross-session store (see :mod:`~meshterm.core.contact_store`) so a
firmware-less bridge doesn't merge them back — but only the *contact* is dropped: each node's
reception history and overheard traffic in MeshTerm are untouched. Our own node, pinned above
the list, is never a purge candidate (it isn't in the device's contact table).
"""
from __future__ import annotations
from typing import TYPE_CHECKING
from rich.text import Text
from .contactlist import ContactListScreen, ContactRow
from .menus import back_rows, menu_rows
from .tui import Choice, Separator
from .tui.screen import CANCEL
from .widgets import ContactsSort, _age_seconds, _contact_pkts
if TYPE_CHECKING:
from ..context import AppContext
from ..core.models import Contact
#: A stable identity for the own-node row (its lane data has no key to stand on when no
#: device answered) — Enter on it opens our own node's detail page.
YOU = ("you",)
#: The contact-list tail sentinels (distinct from any :class:`~meshterm.core.models.Contact`
#: and from :data:`YOU`): the purge action row and the bare ``Back`` exit row.
_PURGE = ("purge",)
_BACK = ("back",)
#: A day in seconds, for the purge age ladder.
_DAY = 86400
#: The age rungs the purge picker offers, ``(label, min_age_seconds)``. A contact qualifies
#: for a rung when its last-heard age is *at least* that long; a never-heard contact — one
#: with no advert time at all — is excluded here and swept only by the separate never-heard
#: bucket, so an age rung never quietly deletes a freshly-added contact that hasn't had time
#: to advert yet.
PURGE_RUNGS: tuple[tuple[str, int], ...] = (
("Older than 1 week", 7 * _DAY),
("Older than 1 month", 30 * _DAY),
("Older than 3 months", 90 * _DAY),
("Older than 6 months", 180 * _DAY),
("Older than 1 year", 365 * _DAY),
)
#: The picker value for the never-heard bucket (contacts with no advert time at all).
_NEVER = "__never__"
def stale_past(contacts: "list[Contact]", min_age_seconds: float) -> "list[Contact]":
"""Contacts last heard at least ``min_age_seconds`` ago.
Never-heard contacts (no last-heard time) are *excluded* — they have their own bucket
(see :func:`never_heard`), so an age rung sweeps only contacts that were once heard and
have since gone quiet, never a contact that has simply not adverted yet.
"""
out: list["Contact"] = []
for contact in contacts:
secs = _age_seconds(contact.last_seen)
if secs is not None and secs >= min_age_seconds:
out.append(contact)
return out
def never_heard(contacts: "list[Contact]") -> "list[Contact]":
"""Contacts with no advert time at all — ones we have never heard broadcasting."""
return [c for c in contacts if _age_seconds(c.last_seen) is None]
def _count_desc(n: int) -> str:
"""The count shown against a purge rung: ``no contacts`` / ``1 contact`` / ``n contacts``."""
if n == 0:
return "no contacts"
return f"{n} contact{'' if n == 1 else 's'}"
class ContactsScreen(ContactListScreen):
"""A full-screen, Ctrl+arrow-sortable list of this node and its known contacts.
Enter resolves the highlighted row — our own node (:data:`YOU`) or a
:class:`~meshterm.core.models.Contact` — for :func:`open_contacts` to open in the
Node detail page; the shared list handles the sort, filter, and navigation.
"""
def __init__(
self,
self_name: str,
self_key: str,
contacts: "list[Contact]",
prefix_bytes: int,
counts: dict[str, int],
sort: ContactsSort,
) -> None:
"""Create the contacts screen over already-fetched contact data.
Args:
self_name: This node's advertised name.
self_key: This node's full public key (hex); blank renders a muted ``?``.
contacts: Known contacts to list under our own node.
prefix_bytes: Path-hash width in bytes to highlight in every key.
counts: Overheard-packet counts keyed by lowercased 12-hex node id; a contact
with no entry shows a faint ``—``.
sort: The initial sort; mutated in place by the Ctrl+arrows. Its ring should
span :data:`~meshterm.ui.contactlist.SORT_COLUMNS` so the hash sort is
reachable.
"""
rows = [ContactRow(value=YOU, name=self_name, key=self_key, you=True)]
for c in contacts:
rows.append(
ContactRow(
# The contact itself is the row's identity, so Enter hands the whole
# record straight to the detail page — no re-lookup by name/key.
value=c,
name=c.name,
key=c.public_key,
node_type=c.node_type,
last_seen=c.last_seen,
count=_contact_pkts(c, counts),
)
)
# The maintenance action closes the list, past every contact whatever the sort: a
# blank spacer, the err-tinted purge row (a `…` — it opens further prompts), then the
# standard exit group. Offered only when there are contacts to purge.
tail: list = []
if contacts:
tail = [
Separator(" "),
Choice(
title=Text.assemble(("🗑 ", "err"), "Purge stale contacts…"),
value=_PURGE,
),
*back_rows(_BACK),
]
super().__init__(
f"Contacts · {len(contacts)} known",
rows=rows,
prefix_bytes=prefix_bytes,
sort=sort,
tail=tail,
)
async def open_contacts(
ctx: "AppContext",
self_name: str,
self_key: str,
contacts: "list[Contact]",
prefix_bytes: int,
counts: dict[str, int],
sort: ContactsSort,
) -> None:
"""Open the interactive contacts list; Enter opens Node detail, Esc leaves.
Runs the show/open/reshow loop: the sortable list, then whichever node's detail page
Enter commits (or the purge flow the tail action opens), then the list again (same sort,
the highlight kept on its row) — until Esc, or the ``Back`` row, backs out of the list
itself. A purge that removes anything re-reads the device and rebuilds the list so the
swept contacts are gone from it.
Args:
ctx: Shared application context (must be in the interactive menu).
self_name: This node's advertised name.
self_key: This node's full public key (hex).
contacts: Known contacts to list under our own node.
prefix_bytes: Path-hash width in bytes to highlight in every key.
counts: Overheard-packet counts keyed by lowercased 12-hex node id.
sort: The initial sort (column + direction) over the shared list's ring — mutated
in place, so a re-sort survives visiting a detail page and coming back.
Raises:
RuntimeError: If called outside the interactive menu (no full-screen session).
"""
from .node_detail_screen import open_node_detail
from .surface import TuiUi
if not isinstance(ctx.ui, TuiUi): # pragma: no cover - guarded by the menu-only caller
raise RuntimeError("the interactive contacts list is only available in the menu")
session = ctx.ui.session
# One screen for the whole visit: re-running it keeps the highlight (and any sort or
# filter) on the row the user just opened a detail for, rather than snapping to the top.
screen = ContactsScreen(self_name, self_key, contacts, prefix_bytes, counts, sort)
while True:
chosen = await session.run_screen(screen)
if chosen is CANCEL or chosen is None or chosen == _BACK:
return
if chosen == _PURGE:
# The purge picker and its confirm float over the list, so re-push it as the
# backdrop while they run (run_screen just popped it). A purge that removed
# anything invalidates the contacts cache, so re-read and rebuild the list.
session.push(screen)
try:
removed = await _purge_stale(ctx, self_key)
finally:
session.pop(screen)
if removed:
contacts = await ctx.devstate.contacts()
screen = ContactsScreen(
self_name, self_key, contacts, prefix_bytes, counts, sort
)
continue
# The own-node sentinel opens our own node's page; any other value is a Contact.
await open_node_detail(ctx, None if chosen == YOU else chosen)
async def _purge_stale(ctx: "AppContext", self_key: str) -> int:
"""Pick an age threshold, confirm, and remove every contact past it. Returns the count removed.
Shows the age ladder (each rung carrying a live count of the contacts it would sweep,
plus a never-heard bucket), gates the pick behind a typed ``delete`` confirm, then deletes
each victim from the device's contact table and forgets it from the cross-session store so
a forgetful bridge doesn't merge it back. Only the *contact* is dropped — each node's
reception history in MeshTerm stays. Runs over the pushed contacts list as its backdrop.
Args:
ctx: Shared application context (interactive menu).
self_key: The device's own public key (hex) — how the contact store scopes this
device's remembered contacts.
Returns:
How many contacts were removed (``0`` if cancelled or nothing matched).
"""
from .surface import TuiUi
assert isinstance(ctx.ui, TuiUi) # guaranteed by open_contacts
session = ctx.ui.session
# Read fresh so the counts match the device right now (own node is never in this list, so
# a purge can't touch it).
contacts = await ctx.devstate.contacts()
rungs = [(label, secs, stale_past(contacts, secs)) for label, secs in PURGE_RUNGS]
never = never_heard(contacts)
rows = [(label, _count_desc(len(victims)), secs) for label, secs, victims in rungs]
rows.append(("Never heard", _count_desc(len(never)), _NEVER))
from .tui import SelectScreen
items = menu_rows(rows)
items.extend(back_rows(None))
picked = await session.run_screen(
SelectScreen(
f"Purge stale contacts — {len(contacts)} known",
items,
prompt="Remove contacts you haven't heard from in the chosen span.",
footer_hint="↑↓ move · Enter select · Esc back",
filterable=False,
wrap=False,
)
)
if picked is CANCEL or picked is None:
return 0
if picked == _NEVER:
victims = never
warning = (
f"This deletes {_count_desc(len(victims))} you've never heard an advert from, "
"removing them from this device's contact list."
)
else:
span = next(label for label, secs in PURGE_RUNGS if secs == picked).lower()
victims = stale_past(contacts, int(picked))
warning = (
f"This deletes {_count_desc(len(victims))} {span}, removing them from this "
"device's contact list. Their reception history in MeshTerm is kept."
)
if not victims:
ctx.ui.note("[muted]no contacts that stale — nothing to purge[/muted]")
return 0
if not await ctx.ui.typed_confirm(warning, "delete", title="Purge stale contacts"):
return 0
device = await ctx.device()
dev_pub = (self_key or "").lower().removeprefix("0x")
store = ctx.contact_store
removed = 0
failed = 0
# A companion-local command per contact (no LoRa transmission), so a straight sequential
# sweep — not paced radio traffic — under a busy overlay for the slower links.
async with ctx.ui.busy_overlay(
f"Purging {_count_desc(len(victims))}…", title="Purge stale contacts"
):
for contact in victims:
try:
await device.remove_contact(contact)
except Exception as exc: # noqa: BLE001 - one bad removal shouldn't abort the sweep
failed += 1
ctx.log.debug("contacts: purge failed for %s: %s", contact.name, exc)
continue
if store is not None and dev_pub and contact.public_key:
store.forget(dev_pub, contact.public_key)
removed += 1
# Drop the cached contact list so the rebuilt screen (and the dashboard) re-read the
# device without the swept contacts.
ctx.devstate.invalidate_contacts()
if removed and not failed:
ctx.ui.note(f"[ok]✓[/ok] purged {_count_desc(removed)}")
elif removed:
ctx.ui.note(
f"[warn]purged {_count_desc(removed)}; {failed} could not be removed[/warn]"
)
else:
ctx.ui.note("[err]no contacts could be removed[/err]")
return removed