diff --git a/CLAUDE.md b/CLAUDE.md index cf6d79f..1f6afd5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. diff --git a/docs/cli/README.md b/docs/cli/README.md index 2a4cf1d..d3675ba 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -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`, diff --git a/meshterm/tools/contacts.py b/meshterm/tools/contacts.py index 9a54c8f..7771d94 100644 --- a/meshterm/tools/contacts.py +++ b/meshterm/tools/contacts.py @@ -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"), ) diff --git a/meshterm/ui/fields.py b/meshterm/ui/fields.py index e0a86ee..a5f4541 100644 --- a/meshterm/ui/fields.py +++ b/meshterm/ui/fields.py @@ -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. diff --git a/tests/test_cli_contract.py b/tests/test_cli_contract.py index 98689eb..d8e7d20 100644 --- a/tests/test_cli_contract.py +++ b/tests/test_cli_contract.py @@ -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, diff --git a/tests/test_contact_places.py b/tests/test_contact_places.py index 2bb29b6..4b9ecd7 100644 --- a/tests/test_contact_places.py +++ b/tests/test_contact_places.py @@ -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 diff --git a/tests/test_report.py b/tests/test_report.py index cf759ea..9c35a14 100644 --- a/tests/test_report.py +++ b/tests/test_report.py @@ -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, } diff --git a/tests/test_rooms.py b/tests/test_rooms.py index f400cc8..3b8389b 100644 --- a/tests/test_rooms.py +++ b/tests/test_rooms.py @@ -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, }