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>
238 lines
9.7 KiB
Python
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"),
|
|
)
|