From 1c267378ef72db3f7fae28b8baae0df7cc185619 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Sun, 12 Jul 2026 03:30:19 -0400 Subject: [PATCH] Relative ages speak grammar: "(now)", never "now ago" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit format_ago in widgets.py is now the one prose form for relative ages — bare "now"/"never", "5m ago" otherwise — and every row that stitched _format_age plus a hard-coded " ago" suffix (packet viewer heard row, Time Machine record/first-heard lines, Courier finished rows, channel detail summary) goes through it, killing "now ago" everywhere at once. The channel summary drops its one-off "just now" special case for the same app-wide wording. Also: the Device actions description no longer claims an advert action — that lives in its own main-menu entry. Co-Authored-By: Claude Opus 4.8 --- meshterm/tools/device_actions.py | 16 +++++++--------- meshterm/ui/channels.py | 5 ++--- meshterm/ui/courier_screen.py | 11 +++++++++-- meshterm/ui/packet_viewer.py | 4 ++-- meshterm/ui/timemachine_screen.py | 5 +++-- meshterm/ui/widgets.py | 13 +++++++++++++ tests/test_channels.py | 3 ++- tests/test_packet_viewer.py | 8 ++++++++ tests/test_widgets.py | 28 ++++++++++++++++++++++++++++ 9 files changed, 74 insertions(+), 19 deletions(-) create mode 100644 tests/test_widgets.py diff --git a/meshterm/tools/device_actions.py b/meshterm/tools/device_actions.py index c012a53..052478d 100644 --- a/meshterm/tools/device_actions.py +++ b/meshterm/tools/device_actions.py @@ -1,17 +1,15 @@ """The ``device-actions`` tool: immediate operations on the companion device itself. Opens the Device actions screen (see :func:`meshterm.ui.config_editor.device_actions`) — -adverts, backup/restore, the identity key, reboot, and factory reset. Where the sibling -``config`` tool *stages* value changes for review, everything here acts on the box the -moment it is confirmed, so the two concerns get their own menu entries and screens. +clock sync, backup/restore, the identity key, reboot, and factory reset. Where the +sibling ``config`` tool *stages* value changes for review, everything here acts on the +box the moment it is confirmed, so the two concerns get their own menu entries and +screens. Sending an advert is not here: that everyday operation lives in its own +main-menu entry (the sibling ``advert`` tool — see :mod:`meshterm.tools.advert`). Menu-only: every action already has a first-class scripted equivalent under the ``config`` CLI group (``config backup``, ``config restore``, ``config reboot``, ...), so no duplicate subcommand is registered here. - -The advert action is additionally promoted to its own main-menu entry (the sibling -``advert`` tool — see :mod:`meshterm.tools.advert`): it is the everyday operation in this -bucket, so it earns a top-level row while remaining available here with the rest. """ from __future__ import annotations @@ -26,12 +24,12 @@ from .base import Tool, ToolResult, register @register class DeviceActionsTool(Tool): - """Run immediate device operations: advert, backup, identity key, reboot, reset.""" + """Run immediate device operations: clock, backup, identity key, reboot, reset.""" name = "device-actions" title = "Device actions" icon = "🔨" - help = "Act on the device itself — advert, backup, identity key, reboot, reset" + help = "Act on the device itself — clock, backup, identity key, reboot, reset" category = "Device management" order = 9 diff --git a/meshterm/ui/channels.py b/meshterm/ui/channels.py index 8ab49a6..9b9e106 100644 --- a/meshterm/ui/channels.py +++ b/meshterm/ui/channels.py @@ -56,7 +56,7 @@ from ..persistence.repository import ACTIVITY_BUCKETS from .braillechart import activity_sparkline from .qr import qr_text from .tui import CANCEL, Choice, SelectScreen, Separator -from .widgets import _age_seconds, _format_age, channel_glyph +from .widgets import _age_seconds, _format_age, channel_glyph, format_ago if TYPE_CHECKING: from ..context import AppContext @@ -481,8 +481,7 @@ def _detail_summary(ctx: "AppContext", slot: ChannelSlot, stats: _LiveStats) -> if unread: parts.append(f"{unread} unread") if st.last_at is not None: - age = _format_age(_age_seconds(st.last_at)) - parts.append("last message just now" if age == "now" else f"last message {age} ago") + parts.append(f"last message {format_ago(_age_seconds(st.last_at))}") return " · ".join(parts) diff --git a/meshterm/ui/courier_screen.py b/meshterm/ui/courier_screen.py index 923ce15..de749bd 100644 --- a/meshterm/ui/courier_screen.py +++ b/meshterm/ui/courier_screen.py @@ -25,7 +25,14 @@ from ..core.courier_store import DELIVERED, GAVE_UP, QUEUED, QueuedMessage from ..core.models import Contact, utcnow from .tui import Choice, Separator from .watchtower_screen import contact_watch_key -from .widgets import _DEFAULT_GLYPH, _NODE_GLYPHS, _age_seconds, _format_age, _recency_style +from .widgets import ( + _DEFAULT_GLYPH, + _NODE_GLYPHS, + _age_seconds, + _format_age, + _recency_style, + format_ago, +) if TYPE_CHECKING: from ..context import AppContext @@ -199,7 +206,7 @@ def _done_row(message: QueuedMessage) -> Text: when = message.finished or message.created verb = "delivered" if message.status == DELIVERED else "gave up" row.append( - f" · {verb} {_format_age(_age_seconds(when))} ago" + f" · {verb} {format_ago(_age_seconds(when))}" f" · {message.attempts} attempt{'s' if message.attempts != 1 else ''}", style="muted", ) diff --git a/meshterm/ui/packet_viewer.py b/meshterm/ui/packet_viewer.py index 9d725c3..4b9312b 100644 --- a/meshterm/ui/packet_viewer.py +++ b/meshterm/ui/packet_viewer.py @@ -38,7 +38,7 @@ from .theme import name_style, snr_style from .trace_screen import snr_bar from .tui.render import render_lines from .tui.screen import Screen -from .widgets import _age_seconds, _format_age, highlighted_hash +from .widgets import _age_seconds, format_ago, highlighted_hash #: Friendly gloss for a raw packet's parsed payload class (mirrors the meshcore #: library's own ``PAYLOAD_TYPENAMES``), shown on a ``packet`` entry's "class" row. @@ -387,7 +387,7 @@ class PacketViewer(Screen): secs = _age_seconds(entry.when) heard = Text(entry.when.astimezone().strftime("%b %d %H:%M:%S")) - heard.append(f" ({_format_age(secs)} ago)", style="muted") + heard.append(f" ({format_ago(secs)})", style="muted") rows.append(("heard", heard)) if entry.node or entry.name: diff --git a/meshterm/ui/timemachine_screen.py b/meshterm/ui/timemachine_screen.py index 19c0b58..c5a2911 100644 --- a/meshterm/ui/timemachine_screen.py +++ b/meshterm/ui/timemachine_screen.py @@ -40,6 +40,7 @@ from .widgets import ( _age_seconds, _format_age, _recency_style, + format_ago, highlighted_hash, ) @@ -284,7 +285,7 @@ def _node_sections( first, last = observations[0].observed_at, observations[-1].observed_at line = Text("heard ", style="muted") line.append(f"first {_when_label(first)} · last {_when_label(last)}") - line.append(f" ({_format_age(_age_seconds(last))} ago)", style="muted") + line.append(f" ({format_ago(_age_seconds(last))})", style="muted") out.append(line) snrs = [p[1] for p in snr_pairs] if snrs: @@ -585,7 +586,7 @@ def _mesh_sections( line.append_text(highlighted_hash(node, prefix_bytes, width=_PICK_HASH_W)) line.append(" ") line.append(_when_label(first)) - line.append(f" ({_format_age(secs)} ago)", style="muted") + line.append(f" ({format_ago(secs)})", style="muted") out.append(line) all_days = ctx.repo.daily_activity() diff --git a/meshterm/ui/widgets.py b/meshterm/ui/widgets.py index 94288c0..f7e7eb3 100644 --- a/meshterm/ui/widgets.py +++ b/meshterm/ui/widgets.py @@ -503,6 +503,19 @@ def _format_age(secs: Optional[float]) -> str: return f"{int(secs // 604800)}w" +def format_ago(secs: Optional[float]) -> str: + """The relative-age *phrase* — ``now``, ``5m ago``, ``never`` — for running prose. + + The canonical grammar for every "heard … (…)" and "delivered …" row: a fresh + sighting reads as bare ``now`` and an unknown one as bare ``never`` (neither takes + the suffix — "now ago" is nonsense), while any measured age reads ``5m ago``. + Callers embedding an age in a sentence or parenthetical use this; + :func:`_format_age` stays the bare column form for aligned age lanes. + """ + age = _format_age(secs) + return age if age in ("now", "never") else f"{age} ago" + + def _recency_style(secs: Optional[float]) -> str: """The heat-map name colour for a contact last heard ``secs`` ago (hotter = more recent). diff --git a/tests/test_channels.py b/tests/test_channels.py index 39123cf..6c8dfb7 100644 --- a/tests/test_channels.py +++ b/tests/test_channels.py @@ -554,7 +554,8 @@ async def test_detail_summary_reads_slot_totals_and_unread(ctx: AppContext) -> N ) ctx.chat._unread[slot.conversation.key] = 1 summary = _detail_summary(ctx, slot, _LiveStats(ctx)) - assert summary == "Slot 3 · 1 message · 1 unread · last message just now" + # A fresh age reads as bare "now" (the app-wide format_ago grammar — never "now ago"). + assert summary == "Slot 3 · 1 message · 1 unread · last message now" # -- the tool against the simulator ------------------------------------------- diff --git a/tests/test_packet_viewer.py b/tests/test_packet_viewer.py index 26d43f8..472dd90 100644 --- a/tests/test_packet_viewer.py +++ b/tests/test_packet_viewer.py @@ -89,6 +89,14 @@ def test_packet_viewer_reaches_packets_that_arrive_after_open() -> None: assert "1/2" in viewer.title +def test_packet_viewer_heard_row_says_now_not_now_ago() -> None: + """A just-heard packet's heard row reads "(now)" — the format_ago grammar.""" + entry = PacketEntry(when=utcnow(), kind="advert", node="aa") + body = _plain(_viewer(entry).render_body(80)) + assert "(now)" in body + assert "now ago" not in body + + def test_packet_viewer_without_a_source_stays_a_snapshot() -> None: """With no live source the viewer is frozen on its opening list (unchanged behaviour).""" entry = PacketEntry(when=utcnow(), kind="advert", node="aa") diff --git a/tests/test_widgets.py b/tests/test_widgets.py new file mode 100644 index 0000000..2852aae --- /dev/null +++ b/tests/test_widgets.py @@ -0,0 +1,28 @@ +"""Shared-widget helper tests: the canonical formatting primitives every screen leans on. + +Most widgets are exercised through their host screens' tests; what lives here are the +pure text helpers whose exact output *is* the app-wide convention — get these right once +and every caller inherits it. +""" + +from __future__ import annotations + +from meshterm.ui.widgets import _format_age, format_ago + + +def test_format_age_is_the_bare_column_form() -> None: + """The lane form stays suffix-free at every magnitude, for aligned age columns.""" + assert _format_age(None) == "never" + assert _format_age(5) == "now" + assert _format_age(90) == "1m" + assert _format_age(7200) == "2h" + assert _format_age(180000) == "2d" + assert _format_age(1300000) == "2w" + + +def test_format_ago_speaks_grammatical_prose() -> None: + """The prose form says "5m ago" but bare "now"/"never" — never "now ago".""" + assert format_ago(5) == "now" + assert format_ago(None) == "never" + assert format_ago(90) == "1m ago" + assert format_ago(7200) == "2h ago"