diff --git a/meshterm/tools/trace.py b/meshterm/tools/trace.py index cc43a68..cb21469 100644 --- a/meshterm/tools/trace.py +++ b/meshterm/tools/trace.py @@ -5,7 +5,9 @@ purely a UX notion — and the menu splits the feature along exactly that line: * **Trace target** (``trace``): *can I reach this node?* Pick a target from a recency-ordered list; the live screen composes/explores symmetric routes that turn - at the target and come home over the mirrored hops. + at the target and come home over the mirrored hops. The list stays pushed underneath + for the whole visit, so Esc from a walk lands back on the row that launched it — + freshly re-sorted by what was just traced — and the next node is one Enter away. * **Trace path** (``trace-path``): *how far can a route I build carry?* No target and no picker — the whole walk is composed hop by hop and only has to end within our own earshot. Traces record under the ``(path)`` sentinel, keeping composed walks @@ -25,7 +27,7 @@ stored history reads the same no matter where it came from. from __future__ import annotations from datetime import datetime -from typing import Any, Optional +from typing import TYPE_CHECKING, Any, Optional import typer from rich.text import Text @@ -36,6 +38,9 @@ from ..services import trace_runner from ..ui.widgets import stats_panel from .base import Tool, ToolResult, register +if TYPE_CHECKING: # pragma: no cover - typing only + from ..ui.contactlist import ContactListScreen, ContactRow + #: The characters a stored trace target must consist of to be treated as a hex key #: prefix when folding it back to a contact name in the target picker. _HEX_DIGITS = frozenset("0123456789abcdef") @@ -53,18 +58,20 @@ class TraceTool(Tool): order = 30 # see a node above, walk to it here async def prompt_params(self, ctx: AppContext) -> Optional[dict[str, Any]]: - """Pick the first target for the live screen. + """Nothing to gather here — the target picker lives inside :meth:`run`. + + The picker has to *stay pushed* while the live screen it opens runs: that is what + makes Esc out of a trace one pop back onto the row it was launched from. A prompt + gathered here would have to resolve — and pop — before the tool runs, so the picker + moved into :meth:`_run_live` along with the loop that owns it. Args: ctx: Shared application context. Returns: - ``{"live": True, "target": name}``, or ``None`` if the user backed out. + ``{"live": True}`` — the menu's marker for the interactive path. """ - target = await self._pick_target(ctx) - if target is None: - return None - return {"live": True, "target": target} + return {"live": True} async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult: """Run — without the outer run row on the live path. @@ -89,35 +96,87 @@ class TraceTool(Tool): Args: ctx: Shared application context. - params: ``live`` + ``target`` from the menu picker; or ``target`` (str), - optional ``path``, and the injected ``_run_id`` from the CLI. + params: ``live`` from the menu (the target is picked on the screen); or + ``target`` (str), optional ``path``, and the injected ``_run_id`` + from the CLI. Returns: A :class:`ToolResult` with the trace's outcome. """ if params.get("live"): - return await self._run_live(ctx, str(params["target"])) + return await self._run_live(ctx) return await self._run_cli(ctx, params) # -- interactive (menu) ------------------------------------------------------- - async def _run_live(self, ctx: AppContext, target: str) -> ToolResult: - """Open the live screen for one target; backing out drops to the main menu. + async def _run_live(self, ctx: AppContext) -> ToolResult: + """Loop the target picker and the live screen until the picker itself is left. + + The picker **stays pushed** for the whole visit (the app's hub idiom), so the live + trace screen nests *above* it: Esc out of a trace is one pop, landing back on the + row it was launched from with the cursor, the sort and any typed filter intact, and + Esc from the picker is the second pop, out to the menu. The picker used to be a + one-shot prompt that resolved and popped before the screen opened, which left the + trace screen sitting directly on the menu — so a single Esc skipped the picker + entirely and there was no way back to the list except reopening the tool. + + Every returning trace ages the row it walked, and the list is *sorted* by that + column, so the lanes are re-read and swapped in place afterwards: the node just + traced rises to the top of the ``TRACED`` sort with the highlight riding it. The + ages come from stored history alone, so coming back costs no device round-trip. Args: ctx: Shared application context. - target: The target to open. Returns: - A :class:`ToolResult` counting the traces run. + A :class:`ToolResult` counting the screens opened and the traces run. """ from ..ui.trace_screen import open_trace + from ..ui.tui.screen import CANCEL - traces = await open_trace(ctx, target) - return ToolResult(summary={"sessions": 1, "traces": traces}) + built = await self._build_picker(ctx) + if built is None: + # Nothing to list (or no full-screen session): the free-text prompt is a + # one-shot, with no list underneath to come back to. + target = await self._prompt_target(ctx) + if target is None: + return ToolResult(summary={}) + return ToolResult( + summary={"sessions": 1, "traces": await open_trace(ctx, target)} + ) - async def _pick_target(self, ctx: AppContext) -> Optional[str]: - """Pick a trace target from the shared sortable contact list. + picker, contacts = built + sessions = 0 + traces = 0 + async with ctx.ui.session.stay(picker) as visit: + while True: + chosen = await visit.result() + if chosen is CANCEL or chosen is None: # Esc — the pop out to the menu + return ToolResult(summary={"sessions": sessions, "traces": traces}) + traces += await open_trace(ctx, chosen.name) + sessions += 1 + picker.update_rows(self._picker_rows(ctx, contacts)) + + async def _prompt_target(self, ctx: AppContext) -> Optional[str]: + """Ask for a target by hand — the way in when there is no list to pick from. + + Reached with no known contacts at all (an empty list would be nothing to pick from) + and on any surface without a full-screen session. It is also the only way to trace a + bare key prefix for a node the device doesn't carry as a contact. + + Args: + ctx: Shared application context. + + Returns: + The typed target, or ``None`` if it was left blank or cancelled. + """ + entered = await ctx.ui.text("Target node (name or key prefix):") + return entered.strip() if entered else None + + async def _build_picker( + self, ctx: AppContext + ) -> Optional[tuple[ContactListScreen, list[Contact]]]: + """Build the trace-target picker, or ``None`` when there is no list to draw. The same ``NAME · TRACED · HEARD · PKTS · KEY`` lanes, Ctrl+arrow sort ring, and type-to-filter the Contacts screen and the courier recipient draw — but with every @@ -125,27 +184,24 @@ class TraceTool(Tool): just as for a companion) and an extra ``TRACED`` lane: how long ago each node was last traced. The list opens sorted by ``TRACED`` descending, so the most recently traced node leads and never-traced ones gather at the bottom. Enter commits the - highlighted node's name as the target. - - With no known contacts at all the list would be empty, so a free-text prompt takes - over instead — also the only way to trace a bare key prefix for a node the device - doesn't carry as a contact. + highlighted node as the target. Args: ctx: Shared application context. Returns: - The chosen target name, or ``None`` if cancelled. + The screen paired with the contacts it lists (kept so the lanes can be + re-read after a trace), or ``None`` when there is nothing to list — see + :meth:`_prompt_target`. """ from ..ui.contactlist import ( TRACE_SORT_COLUMNS, TRACE_SORT_OPENS_ASCENDING, ContactListScreen, - ContactRow, ) from ..ui.surface import TuiUi from ..ui.timemachine_screen import _routing_prefix_bytes - from ..ui.widgets import ContactsSort, _contact_pkts + from ..ui.widgets import ContactsSort # Through the session cache: this picker runs on every Trace open, and the contacts # table is a slow round-trip on a busy node — re-reading it here (in front of the @@ -153,15 +209,42 @@ class TraceTool(Tool): # :class:`~meshterm.services.device_state.DeviceState`. contacts = await ctx.devstate.contacts() if not contacts or not isinstance(ctx.ui, TuiUi): - # No contacts to list (or no full-screen session): a free-text prompt is the - # only way in — and the only way to trace a bare key prefix off-list. - entered = await ctx.ui.text("Target node (name or key prefix):") - return entered.strip() if entered else None + return None + + picker = ContactListScreen( + "Trace target — pick a target", + rows=self._picker_rows(ctx, contacts), + prefix_bytes=await _routing_prefix_bytes(ctx), + sort=ContactsSort.from_name( + "traced", TRACE_SORT_COLUMNS, TRACE_SORT_OPENS_ASCENDING + ), + footer_hint="↑↓ move · ^←→↑↓ sort · type to filter · Enter select · Esc back", + show_traced=True, + ) + return picker, contacts + + @staticmethod + def _picker_rows(ctx: AppContext, contacts: list[Contact]) -> list[ContactRow]: + """The picker's lane data for ``contacts``, read fresh from stored history. + + Both the ``TRACED`` ages and the packet counts come from the repository, so this is + cheap enough to redo every time a trace hands the picker back — which is what keeps + the lane the list is *sorted* by honest about the walk that just happened. + + Args: + ctx: Shared application context. + contacts: The device's contacts, as listed. + + Returns: + One :class:`~meshterm.ui.contactlist.ContactRow` per contact, in the order + given (the screen sorts them). + """ + from ..ui.contactlist import ContactRow + from ..ui.widgets import _contact_pkts traced = _last_traced_by_name(contacts, ctx.repo.target_last_traced()) counts = {n.node: n.count for n in ctx.repo.heard_nodes() if n.node} - prefix_bytes = await _routing_prefix_bytes(ctx) - rows = [ + return [ ContactRow( value=c, name=c.name, @@ -173,18 +256,6 @@ class TraceTool(Tool): ) for c in contacts ] - picker = ContactListScreen( - "Trace target — pick a target", - rows=rows, - prefix_bytes=prefix_bytes, - sort=ContactsSort.from_name( - "traced", TRACE_SORT_COLUMNS, TRACE_SORT_OPENS_ASCENDING - ), - footer_hint="↑↓ move · ^←→↑↓ sort · type to filter · Enter select · Esc back", - show_traced=True, - ) - chosen = await ctx.ui.session.run_screen(picker) - return chosen.name if isinstance(chosen, Contact) else None # -- scripted (CLI) ------------------------------------------------------------- diff --git a/meshterm/ui/contactlist.py b/meshterm/ui/contactlist.py index ad9c1e1..0c53b23 100644 --- a/meshterm/ui/contactlist.py +++ b/meshterm/ui/contactlist.py @@ -461,6 +461,26 @@ class ContactListScreen(SelectScreen): items.extend(self._tail) return items + def update_rows(self, rows: list[ContactRow]) -> None: + """Swap the contact lanes in place, keeping the reader's place. + + The :meth:`~meshterm.ui.tui.select.SelectScreen.replace_items` counterpart for a + list whose *lanes* are data: the Trace-target picker's ``TRACED`` column ages the + moment a trace it launched comes back, and the list is sorted by that column. The + rows are recomposed and re-sorted, and the highlight lands back on the same contact + wherever the new order put it — so the node just traced rises to the top with the + cursor riding it. The typed filter and the sort ride along untouched. + + Use it for a lane that changed; a contact that is *gone* is the rebuild case (see + :func:`~meshterm.ui.contacts_screen.open_contacts`), because the row the list was + holding a place in no longer exists. + + Args: + rows: Every contact's lane data, as :meth:`__init__` takes it. + """ + self._contact_rows = rows + self._rebuild() + def _rebuild(self) -> None: """Recompose the rows for the current sort/width, keeping the highlight on its contact.""" current = self._current_choice() diff --git a/tests/test_navigation.py b/tests/test_navigation.py index 036ed0f..bdbae5a 100644 --- a/tests/test_navigation.py +++ b/tests/test_navigation.py @@ -29,6 +29,11 @@ from meshterm.ui.tui.session import _CTRL_LETTER_CHORDS, _KEY_ACTIONS, TuiSessio POP_ALL_KEY = "\x17" # ^W QUIT_KEY = "\x11" # ^Q +#: The two keys the picker/live-screen flow is driven by, spelled out so no raw +#: control byte has to sit in the source. +ESC = "\x1b" +ENTER = "\r" + def _session(inp) -> TuiSession: """A headless session driven by a pipe, rendering nowhere.""" @@ -119,6 +124,66 @@ async def test_a_visited_screen_is_armed_from_the_moment_it_is_pushed() -> None: await asyncio.wait_for(session.run(main()), timeout=5) +async def test_the_trace_target_picker_stays_pushed_under_the_live_screen(monkeypatch) -> None: + """Esc out of a trace is one pop, back onto the picker — not a drop to the menu. + + The picker used to be a one-shot prompt gathered in ``prompt_params``: it resolved and + popped *before* the live screen opened, so the trace screen sat straight on the menu and + a single Esc skipped the list it was launched from. Now the tool keeps the picker for the + whole visit and the live screen nests above it. + """ + from meshterm.core.models import Contact + from meshterm.tools.trace import TraceTool + from meshterm.ui.surface import TuiUi + + contacts = [ + Contact(name="YUL-Poly", public_key="a1" + "0" * 62, key_prefix="a1"), + Contact(name="YUL-Cartierville", public_key="3d" + "0" * 62, key_prefix="3d"), + ] + + class _Repo: + def target_last_traced(self): + return {} + + def heard_nodes(self): + return [] + + class _Devstate: + async def contacts(self): + return list(contacts) + + class _Ctx: + repo = _Repo() + devstate = _Devstate() + is_connected = False # keeps the best-effort path-hash read off the radio + settings = type("S", (), {"connect_on_start": False})() + + ctx = _Ctx() + depths: list[int] = [] + + with create_pipe_input() as inp: + session = _session(inp) + ctx.ui = TuiUi(session) + + async def fake_open_trace(_ctx, target: str, *, initial_spec: str = "") -> int: + """Stand in for the live screen: note the stack under it, then Esc out of it.""" + depths.append(len(session._stack)) + inp.send_text(ESC) # the Esc that used to land on the main menu + return 2 + + monkeypatch.setattr("meshterm.ui.trace_screen.open_trace", fake_open_trace) + + async def main() -> None: + inp.send_text(ENTER) # Enter on the leading row commits it as the target + result = await TraceTool()._run_live(ctx) + assert result.summary == {"sessions": 1, "traces": 2} + + await asyncio.wait_for(session.run(main()), timeout=5) + + assert depths == [1], "the picker is still on the stack while the trace screen runs" + assert session._stack == [], "and the visit pops it on the way out" + + # --- refreshing a visited list's rows ---------------------------------------- @@ -163,6 +228,54 @@ def test_replace_items_clamps_to_the_position_when_the_row_is_gone() -> None: assert screen._current_choice() is None +def test_update_rows_resorts_the_lanes_and_keeps_the_highlight_on_its_contact() -> None: + """The Trace picker's TRACED lane ages under the reader without moving them. + + The list is sorted by the very column a returning trace changes, so the node just + walked jumps to the top — and the cursor has to ride it there, or the reader would be + put back on whatever row inherited their position. + """ + from datetime import datetime, timedelta, timezone + + from meshterm.ui.contactlist import ( + TRACE_SORT_COLUMNS, + TRACE_SORT_OPENS_ASCENDING, + ContactListScreen, + ContactRow, + ) + from meshterm.ui.widgets import ContactsSort + + now = datetime.now(timezone.utc) + rows = [ + ContactRow(value="alpha", name="alpha", last_traced=now - timedelta(hours=2)), + ContactRow(value="beta", name="beta", last_traced=None), # never traced + ] + screen = ContactListScreen( + "Trace target — pick a target", + rows=rows, + prefix_bytes=1, + sort=ContactsSort.from_name( + "traced", TRACE_SORT_COLUMNS, TRACE_SORT_OPENS_ASCENDING + ), + show_traced=True, + ) + screen.handle("text", "bet") # find-as-you-type down to the never-traced node + assert screen._current_choice().value == "beta" + + # beta is traced: it now leads the TRACED sort, where alpha was. + screen.update_rows( + [ + ContactRow(value="alpha", name="alpha", last_traced=now - timedelta(hours=2)), + ContactRow(value="beta", name="beta", last_traced=now), + ] + ) + assert screen._filter == "bet", "the typed filter survives the swap" + assert screen._current_choice().value == "beta", "the highlight followed its contact" + for _ in range(3): # ⌫ back out of the filter: the whole, re-sorted list is there + screen.handle("backspace") + assert [c.value for c in screen._choices()] == ["beta", "alpha"] + + # --- ^W, the pop-all ---------------------------------------------------------