Files
MeshTerm/meshterm/tools/contacts.py
T
Jean-Pierre MartineauandClaude Opus 5.5 d08513aa69 contacts --sort takes place and hash; the Archived list gets the PLACE column
The CLI sorts on the same ring as the Contacts screen (name, heard, packets,
place, hash). The ring moved to ui/widgets.py so the CLI loads no TUI code, and
ordered_contacts sorts by place (no place last) and by key.

The Archived list reads NAME · ARCHIVED · PLACE · KEY, sorts by place, cuts no
value and pans with ←→, like the Contacts list. The place fill and its live
refresh moved from ContactsScreen into ContactListScreen, so any list that
declares the PLACE lane gets them from places=.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 17:28:01 -05:00

238 lines
9.7 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""The ``contacts`` tool: list the contacts that this node knows.
The menu opens the Contacts screen, which you can sort and which starts with our node.
The CLI prints only the contact list, because our node is not a contact.
``meshterm info`` reports our node, with much more detail than a row can hold.
"""
from __future__ import annotations
from collections.abc import Callable
from typing import TYPE_CHECKING, Any
import typer
from ..context import AppContext
from ..core import exitcodes
from ..core.models import NODE_TYPE_LABELS
from .base import Tool, ToolResult, register
if TYPE_CHECKING: # pragma: no cover - typing only
from ..core.models import Contact
from ..core.places import Place
from ..ui.report import Listing
@register
class ContactsTool(Tool):
"""List this node and its known contacts, each with its hash."""
name = "contacts"
title = "Contacts"
icon = "👥"
help = "Known contacts — last heard, packets, type"
category = "Message"
order = 40 # the address book from which the three tools above select a recipient
async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
"""Query the device and render the contact list.
Args:
ctx: The shared application context.
params: Not used.
Returns:
A :class:`ToolResult` with a summary of the number of known contacts.
"""
from ..ui.surface import TuiUi
from ..ui.widgets import (
CONTACTS_SORT_COLUMNS,
CONTACTS_SORT_OPENS_ASCENDING,
ContactsSort,
ordered_contacts,
)
# Read through the session cache. On a busy node, the contacts table is a slow
# round trip. If MeshTerm reads it again (and the self info) at each visit to the
# menu, that is a main cause of slow navigation. The cache keeps them for the session
# and reads the contacts again in the background (refer to
# :class:`~meshterm.services.device_state.DeviceState`).
info = await ctx.devstate.self_info()
contacts = await ctx.devstate.contacts()
# The hash (the first part of a key, which a forced path uses as the address) is
# ``mode + 1`` bytes wide. Light it in each key. The mode is an optional read. Thus
# if the firmware does not report it, light nothing.
try:
mode = await ctx.devstate.path_hash_mode()
except Exception: # noqa: BLE001 - an optional read. If it is absent, nothing is lit.
mode = None
prefix_bytes = (mode + 1) if isinstance(mode, int) and 0 <= mode <= 3 else 0
# The counts of overheard packets from the background monitor, keyed by node hash.
# A contact that we never overheard passively has no entry.
counts = {n.node: n.count for n in ctx.repo.heard_nodes() if n.node}
self_name = str(info.get("name") or "this node")
self_key = str(info.get("public_key") or "")
# The list opens with the most recently heard node first. The list must answer "who
# is out there now", and an order with the newest first answers that immediately.
# A list from A to Z does not. Then the Ctrl+arrows sort the list again (and
# ``--sort`` sets the order of the CLI).
sort_name = str(params.get("sort") or "heard")
# The two faces use the same ring: the five columns of the Contacts list (also the
# place and the hash).
sort = ContactsSort.from_name(
sort_name, CONTACTS_SORT_COLUMNS, CONTACTS_SORT_OPENS_ASCENDING
)
# In the menu, give the list to the interactive screen, so that the Ctrl+arrows sort
# it again while it is open. On the scripted CLI, print the plain listing one time,
# in the requested order.
if isinstance(ctx.ui, TuiUi):
from ..ui.contacts_screen import open_contacts
await open_contacts(ctx, self_name, self_key, contacts, prefix_bytes, counts, sort)
return ToolResult(summary={"contacts": len(contacts)})
# The CLI reads the stored places only. It never starts the job that finds them.
places = getattr(ctx, "places", None)
place_of = _place_lookup(places.get) if places is not None else None
listing = _listing(
ordered_contacts(
contacts,
counts,
sort,
(lambda c: _place_label(place_of(c))) if place_of else None,
),
counts,
prefix_bytes,
place_of,
)
return ToolResult(
summary={"contacts": len(contacts)},
report=(listing,),
exit_code=exitcodes.OK if contacts else exitcodes.NO_RESULT,
)
def register_cli(self, app: typer.Typer) -> None:
"""Register the ``contacts`` subcommand.
Args:
app: The Typer application.
"""
from ..cli import run_tool_command
from ..ui.widgets import CONTACTS_SORT_COLUMNS, ContactsSort
@app.command(name=self.name, help=self.help)
def _contacts(
sort: str = typer.Option(
"heard",
"--sort",
"-s",
help="Order contacts by: heard, name, packets, place, hash",
),
) -> None:
# For an unknown name, `ContactsSort.from_name` uses the first column. This is
# on purpose, so that a saved preference from an older build cannot block the
# list of the menu. On the command line, the same silence hides a typing error:
# the caller asked for one order and got another, and nothing said so.
if sort not in ContactsSort.names(CONTACTS_SORT_COLUMNS):
choices = ", ".join(ContactsSort.names(CONTACTS_SORT_COLUMNS))
raise typer.BadParameter(f"--sort must be one of: {choices} (got {sort!r})")
run_tool_command(self, {"sort": sort})
def _place_lookup(get: Callable[[str], Place | None]) -> Callable[[Contact], Place | None]:
"""Give the stored place of a contact, from a lookup by key (or key prefix)."""
def place_of(contact: Contact) -> Place | None:
return get((contact.public_key or contact.key_prefix).lower())
return place_of
def _place_label(place: Place | None) -> str | None:
"""The full label of a place (``Villeray, Montréal``), or ``None`` for no place."""
return (place.label or None) if place else None
def _listing(
contacts: list[Contact],
counts: dict[str, int],
prefix_bytes: int,
place_of: Callable[[Contact], Place | None] | None = None,
) -> Listing:
"""The contact list, stated one time for the two faces.
``TYPE`` is the advertised role of the node, in words. The menu draws a coloured glyph
there, but a monochrome ``▲`` must have a legend, and the CLI has no legends.
``HEARD`` is a relative age, because the user opens this listing to ask "recently?".
``PLACE`` is the named area nearest the location of the node. It is just before ``KEY``.
``HASH`` is the token that ``--path`` and ``--to`` accept. Before, the user had to cut
it out of ``KEY`` by hand. ``LOCATION`` is a fact that the model always had, but no
column had space for it. ``KEY`` stays full and last. Thus it goes off the right side
with no harm and is never cut: a caller cannot give a truncated key back to a command.
Args:
contacts: The contacts, already in the requested order.
counts: The counts of overheard packets, keyed by node id (from the passive
monitor).
prefix_bytes: The path hash width of the device. Because of it, ``HASH`` is the
token by which a forced path addresses this node, not a random part of the
key.
place_of: Gives the stored place of a contact, or ``None``. ``PLACE`` is the label
of that place, and it is ``null`` in the document when there is none.
Returns:
The listing.
"""
from ..ui import fields
from ..ui.report import Listing
from ..ui.widgets import contact_packets
rows = []
for contact in contacts:
key = (contact.public_key or "").lower()
place = place_of(contact) if place_of else None
rows.append(
{
"node": fields.NodeRef(
name=contact.name,
key=key or None,
hash=(key or contact.key_prefix.lower())[: prefix_bytes * 2] or None,
type=NODE_TYPE_LABELS.get(contact.node_type),
place=_place_label(place),
),
"heard_at": contact.last_seen,
"packets": contact_packets(contact, counts),
"position": (
fields.Position(contact.lat, contact.lon) if contact.has_location else None
),
}
)
return Listing(
key="contacts",
columns=(
fields.node(
"node",
lanes=(
("name", "NAME"),
("type", "TYPE"),
("hash", "HASH"),
("place", "PLACE"),
("key", "KEY"),
),
),
fields.when("heard_at", "HEARD", absent="never"),
fields.integer("packets", "PKTS"),
fields.position(),
),
rows=rows,
# The five lanes of the node are not together. What the user looks for (who, what,
# how recently, how much) comes first, and the long fields go to the right. PLACE is
# just before KEY, the same as in the menu.
order=("NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "PLACE", "KEY"),
)