The contacts command gives each node's place, and the node object has a place key

fields.node adds place (null when unknown) to its machine object, and the plain
face gets a PLACE column before KEY. The command reads stored places only.

Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
This commit is contained in:
Jean-Pierre MartineauandClaude Haiku 5.5 committed 2026-11-03 03:00:55 -05:00
1 parent c3174b6fbb
commit 9626d06a3f
8 files changed
+128 -29

No files matched your search

+1 -1
View File
@@ -691,7 +691,7 @@ the whole answer in a dialect nobody else could reuse.
the caller named the key) and the acknowledgement, through `shape=SILENT`.
- `ui/fields.py` — **the shared shapes, one constructor per concept**: `node`, `channel`,
`position`, `route`, `spec`, `when`, `instant`, `snr`, `flag`, `free`. A listing that
mentions a node asks for `fields.node`, so every document speaks the same five-key object
mentions a node asks for `fields.node`, so every document speaks the same six-key object
and every listing names its lanes the same way — by construction, not by review.
`fields.node` is the one that earns the design: **one machine key expands to as many
plain columns as the surface has room for**, four in `contacts` and one in a hop table.
+18 -17
View File
@@ -189,11 +189,11 @@ Numeric columns align to the right.
```console
$ meshterm contacts
NAME TYPE HEARD PKTS HASH LOCATION KEY
Observer-Bot node 7m - c3 45.48800,-73.58100 c3d4e5f600000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 7m - b2 45.47680,-73.59900 b2c3d4e500000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 7m - a1 45.50190,-73.56740 a1b2c3d400000000000000000000000000000000000000000000000000000000
Alice node 7m - d4 - d4e5f6a700000000000000000000000000000000000000000000000000000000
NAME TYPE HEARD PKTS HASH LOCATION PLACE KEY
Observer-Bot node 7m - c3 45.48800,-73.58100 - c3d4e5f600000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 7m - b2 45.47680,-73.59900 - b2c3d4e500000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 7m - a1 45.50190,-73.56740 - a1b2c3d400000000000000000000000000000000000000000000000000000000
Alice node 7m - d4 - - d4e5f6a700000000000000000000000000000000000000000000000000000000
```
Names are not in quotation marks. Quotation marks would give a script a delimiter, and
@@ -212,11 +212,11 @@ the second:
```console
$ meshterm --absolute contacts
NAME TYPE HEARD PKTS HASH LOCATION KEY
Observer-Bot companion 2026-09-08T04:30:50-04:00 - c3 45.48800,-73.58100 c3d4e5f600000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 2026-09-08T04:30:49-04:00 - b2 45.47680,-73.59900 b2c3d4e500000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 2026-09-08T04:30:49-04:00 - a1 45.50190,-73.56740 a1b2c3d400000000000000000000000000000000000000000000000000000000
Alice companion 2026-09-08T04:30:48-04:00 - d4 - d4e5f6a700000000000000000000000000000000000000000000000000000000
NAME TYPE HEARD PKTS HASH LOCATION PLACE KEY
Observer-Bot companion 2026-09-08T04:30:50-04:00 - c3 45.48800,-73.58100 - c3d4e5f600000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 2026-09-08T04:30:49-04:00 - b2 45.47680,-73.59900 - b2c3d4e500000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 2026-09-08T04:30:49-04:00 - a1 45.50190,-73.56740 - a1b2c3d400000000000000000000000000000000000000000000000000000000
Alice companion 2026-09-08T04:30:48-04:00 - d4 - - d4e5f6a700000000000000000000000000000000000000000000000000000000
```
The flag **overrides a preference**. It is not a second switch that works beside the
@@ -403,11 +403,11 @@ interactive session cannot emit a document.
This section defines each shape one time. The tables for each command below use the names
and do not repeat the definitions.
**`node`** is the identity of a mesh participant, and nothing else. All five keys are
**`node`** is the identity of a mesh participant, and nothing else. All six keys are
always present.
```json
{"name":"Yagi-Repeater","key":"a1b2c3d400000000000000000000000000000000000000000000000000000000","hash":"a1","type":"repeater","self":false}
{"name":"Yagi-Repeater","key":"a1b2c3d400000000000000000000000000000000000000000000000000000000","hash":"a1","type":"repeater","place":"Villeray, Montréal","self":false}
```
| Field | Type | Meaning |
@@ -416,6 +416,7 @@ always present.
| `key` | string \| null | The full public key, in lowercase hex, 64 characters. `null` when MeshTerm heard only a hash. |
| `hash` | string \| null | The short id that comes from the key. Its width is the width that the command used to address the node. It is never a `key` that is cut short. |
| `type` | string \| null | `"companion"` \| `"repeater"` \| `"room server"` \| `"sensor"` \| `null`. |
| `place` | string or null | The full label of the place of the node, the named area nearest its location (`Villeray, Montréal`). `null` when MeshTerm knows no place. The command reads the stored places only. |
| `self` | boolean | `true` for our node. This is what the star of the menu shows. The plain face deliberately does not show it. |
Reception facts belong to the **row** and not to the node. These facts are when MeshTerm
@@ -897,11 +898,11 @@ The contacts that your device knows.
```console
$ meshterm contacts --sort name
NAME TYPE HEARD PKTS HASH LOCATION KEY
Alice companion 7m - d4 - d4e5f6a700000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 7m - b2 45.47680,-73.59900 b2c3d4e500000000000000000000000000000000000000000000000000000000
Observer-Bot companion 7m - c3 45.48800,-73.58100 c3d4e5f600000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 7m - a1 45.50190,-73.56740 a1b2c3d400000000000000000000000000000000000000000000000000000000
NAME TYPE HEARD PKTS HASH LOCATION PLACE KEY
Alice companion 7m - d4 - - d4e5f6a700000000000000000000000000000000000000000000000000000000
Local-Repeater repeater 7m - b2 45.47680,-73.59900 - b2c3d4e500000000000000000000000000000000000000000000000000000000
Observer-Bot companion 7m - c3 45.48800,-73.58100 - c3d4e5f600000000000000000000000000000000000000000000000000000000
Yagi-Repeater repeater 7m - a1 45.50190,-73.56740 - a1b2c3d400000000000000000000000000000000000000000000000000000000
```
`TYPE` is the node's advertised role in words: `companion`, `repeater`, `room server`,
+28 -6
View File
@@ -8,6 +8,7 @@ The CLI prints only the contact list, because our node is not a contact.
from __future__ import annotations
from collections.abc import Callable
from typing import TYPE_CHECKING, Any
import typer
@@ -19,6 +20,7 @@ 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
@@ -90,7 +92,10 @@ class ContactsTool(Tool):
return ToolResult(summary={"contacts": len(contacts)})
sort = ContactsSort.from_name(sort_name)
listing = _listing(ordered_contacts(contacts, counts, sort), counts, prefix_bytes)
# The CLI reads the stored places only. It never starts the job that finds them.
listing = _listing(
ordered_contacts(contacts, counts, sort), counts, prefix_bytes, ctx.places.get
)
return ToolResult(
summary={"contacts": len(contacts)},
report=(listing,),
@@ -122,12 +127,18 @@ class ContactsTool(Tool):
run_tool_command(self, {"sort": sort})
def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int) -> Listing:
def _listing(
contacts: list[Contact],
counts: dict[str, int],
prefix_bytes: int,
place_of: Callable[[str], 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
@@ -140,6 +151,8 @@ def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int)
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 key, or ``None``. ``PLACE`` is the label of
that place, and it is ``null`` in the document when there is none.
Returns:
The listing.
@@ -151,6 +164,7 @@ def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int)
rows = []
for contact in contacts:
key = (contact.public_key or "").lower()
place = place_of(key or contact.key_prefix) if place_of else None
rows.append(
{
"node": fields.NodeRef(
@@ -158,6 +172,7 @@ def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int)
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 or None) if place else None,
),
"heard_at": contact.last_seen,
"packets": contact_packets(contact, counts),
@@ -171,14 +186,21 @@ def _listing(contacts: list[Contact], counts: dict[str, int], prefix_bytes: int)
columns=(
fields.node(
"node",
lanes=(("name", "NAME"), ("type", "TYPE"), ("hash", "HASH"), ("key", "KEY")),
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 four lanes of the node are not together. What the user looks for (who, what,
# how recently, how much) comes first, and the two long hex fields go to the right.
order=("NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "KEY"),
# 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"),
)
+10 -3
View File
@@ -63,6 +63,9 @@ class NodeRef:
its own choice.
type: The advertised role, in the words of the lexicon (``node``, ``repeater``,
``room``, ``sensor``). It is ``None`` if the advert did not give it.
place: The full label of the place of the node (``Villeray, Montréal``), the named
area nearest its location. It is ``None`` if MeshTerm knows no place. A listing
that has no use for it leaves it out, and the machine face then gives ``null``.
is_self: Whether this is our node. The plain face draws it like any other hop, on
purpose. "You already know who this is" is true for the person at the prompt.
It is not true for the person who reads the file afterwards. The machine face
@@ -73,6 +76,7 @@ class NodeRef:
key: str | None = None
hash: str | None = None
type: str | None = None
place: str | None = None
is_self: bool = False
@@ -146,6 +150,7 @@ def node_json(ref: NodeRef | None) -> dict[str, Any] | None:
"key": (ref.key or None) and ref.key.lower(),
"hash": (ref.hash or None) and ref.hash.lower(),
"type": ref.type or None,
"place": ref.place or None,
"self": ref.is_self,
}
@@ -174,7 +179,7 @@ def channel_json(channel: ChannelRef | None) -> dict[str, Any] | None:
# -- the constructors ------------------------------------------------------------------
#: How each plain lane of a node makes its cell. A listing selects the lanes that it has
#: room for. The machine object has the same five keys in each case.
#: room for. The machine object has the same six keys in each case.
_NODE_LANES = {
"name": lambda ref: script.name(ref.name if ref else None),
# The word, not a glyph. A `▲` with no colour needs a legend, and the CLI has no
@@ -182,17 +187,19 @@ _NODE_LANES = {
"type": lambda ref: ref.type if ref and ref.type else "unknown",
"hash": lambda ref: ((ref.hash or "").lower() if ref else "") or script.NONE,
"key": lambda ref: ((ref.key or "").lower() if ref else "") or script.NONE,
# The label as it is, with its comma and spaces. The plain face escapes the cell.
"place": lambda ref: script.name(ref.place if ref else None),
}
def node(key: str = "node", *, lanes: Sequence[tuple[str, str]] = (("name", "NAME"),)) -> Column:
"""One node: the shared object with five keys, and the plain lanes that fit.
"""One node: the shared object with six keys, and the plain lanes that fit.
Args:
key: The machine key. It is also the key at which the row holds its
:class:`NodeRef`.
lanes: ``(part, header)`` pairs that name the plain columns to draw, in order. The
parts are ``name``, ``type``, ``hash``, and ``key``. A listing that has one
parts are ``name``, ``type``, ``hash``, ``key``, and ``place``. A listing that has one
column to use draws the name. A table of hops draws the hash, because the hash
joins the table to the route line above it.
+11 -2
View File
@@ -52,7 +52,7 @@ _PATH_SPEC = re.compile(r"[0-9a-f]+(?:,[0-9a-f]+)*")
#: must find in each. Each command runs against only the mock companion or the database.
_LISTINGS: list[tuple[str, list[str], list[str]]] = [
# (command, arguments, headings or keys the output must carry)
("contacts", [], ["NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "KEY"]),
("contacts", [], ["NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "PLACE", "KEY"]),
("info", [], ["name", "public_key", "role"]),
("config", ["show"], ["name", "radio_freq", "tx_power"]),
("preferences", ["show"], ["PREFERENCE", "VALUE", "DEFAULT", "DESCRIPTION"]),
@@ -382,7 +382,16 @@ def test_contacts_names_every_node_bare_and_ages_every_time(run) -> None: # noq
user who wants them.
"""
header, *records = result_lines(run("contacts"))
assert header.split() == ["NAME", "TYPE", "HEARD", "PKTS", "HASH", "LOCATION", "KEY"]
assert header.split() == [
"NAME",
"TYPE",
"HEARD",
"PKTS",
"HASH",
"LOCATION",
"PLACE",
"KEY",
]
assert records, "the simulator always has contacts"
# Read the lane at the position of its heading. Do not count words, because a value can
# have a space (the `Lakeside BBS` of the simulator is a `room server`). The alignment,
+58
View File
@@ -242,3 +242,61 @@ def test_filter_matches_the_coarse_part_of_the_place() -> None:
_type(screen, "bob")
shown = "\n".join(_lines(screen, 200))
assert "Bob" in shown and "Alice" not in shown
# -- part 3: the CLI and the machine object -------------------------------------------
def _cli_contacts(place_of): # noqa: ANN001, ANN202 - a lookup function or None
from meshterm.tools.contacts import _listing
contacts = [
Contact(name="Alice", public_key=_ALICE, key_prefix=_ALICE[:12]),
Contact(name="Carl", public_key=_CARL, key_prefix=_CARL[:12]),
]
return _listing(contacts, {}, 1, place_of)
def _render(face, listing): # noqa: ANN001, ANN202 - the renderer class
import io
from meshterm.ui import script
buffer = io.StringIO()
face(script.console(buffer)).render((listing,))
return buffer.getvalue()
def test_node_object_has_a_place_key_that_is_null_when_unknown() -> None:
"""The machine object of a node has six keys. ``place`` is the label, or ``null``."""
import json
from meshterm.ui.renderers import JsonRenderer
docs = json.loads(_render(JsonRenderer, _cli_contacts(_places().get)))
alice, carl = (d["node"] for d in docs)
assert list(alice) == ["name", "key", "hash", "type", "place", "self"]
assert alice["place"] == "Villeray, Montréal"
assert carl["place"] is None
def test_contacts_without_a_lookup_gives_null_places() -> None:
"""A listing built with no place lookup still has the key, with ``null``."""
import json
from meshterm.ui.renderers import JsonRenderer
docs = json.loads(_render(JsonRenderer, _cli_contacts(None)))
assert [d["node"]["place"] for d in docs] == [None, None]
def test_plain_face_has_a_place_column_before_key() -> None:
"""The PLACE column sits just before KEY, shows the label, and uses ``-`` when unknown."""
from meshterm.ui.renderers import PlainRenderer
header, alice, carl = _render(PlainRenderer, _cli_contacts(_places().get)).splitlines()
labels = header.split()
assert labels.index("PLACE") == labels.index("KEY") - 1
assert "Villeray, Montréal" in alice
assert alice.index("Villeray") < alice.index(_ALICE)
assert carl.split()[-2] == "-" and carl.split()[-1] == _CARL
+1
View File
@@ -96,6 +96,7 @@ def test_a_node_is_one_object_however_many_columns_it_is_worth() -> None:
"key": "d4" * 32,
"hash": "d4",
"type": "node",
"place": None,
"self": False,
}
+1
View File
@@ -1443,6 +1443,7 @@ def test_chat_history_reads_a_room_by_author(cli) -> None: # noqa: ANN001
"key": None,
"hash": STRANGER_KEY,
"type": None,
"place": None,
"self": False,
}