From 1c24f9149da8df8deb4a7a863016aa1458cecfcd Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 8 Sep 2026 03:16:57 -0400 Subject: [PATCH] Let a tool state its answer instead of printing it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The CLI said what it found by printing it: run() called ctx.ui.show() and handed back a ToolResult carrying only bookkeeping. By the time the boundary saw that result the contacts had gone down the pipe already rendered, and there was nothing left to offer a second format — which is exactly why --json reached two commands out of twenty and stopped, each one growing an `if ctx.json_output:` branch above the rendering that restated the whole answer in a dialect nobody else could reuse. exit_code has always worked the other way round: the tool states it, the boundary turns it into a process status, and no tool calls sys.exit. The answer now travels the same way. A tool states a Report; a renderer turns it into bytes; --json picks the renderer. ui/report.py holds the model — a Listing of records or a set of Facts, whose rows carry the typed value and whose columns carry both projections of it. ui/fields.py is the shared shapes, one constructor per concept, so every listing that mentions a node speaks the same five-key object by construction rather than by review. ui/renderers.py is the two faces: aligned text for a person, and the bare document for a program — an array for a listing, an object for a set of facts, no envelope, because the report a caller needs is still $?. Nothing is migrated yet: report defaults to None and every command renders exactly as it did. The script vocabulary the plain face will need lands alongside — ages, durations, locations, the arrow-drawn route, the comma-joined spec, pinned lanes for a live stream, and a wrap for the written pages — with the quoting still in place until its callers move off it. Also here, because the field library needs it: cli_time_format, the preference that says whether the command line prints ages or timestamps, with --absolute as its per-run override rather than a second switch beside it. Co-Authored-By: Claude Opus 5 (1M context) --- meshterm/cli.py | 66 +++++- meshterm/context.py | 15 +- meshterm/core/preferences.py | 17 ++ meshterm/tools/base.py | 16 ++ meshterm/ui/fields.py | 413 +++++++++++++++++++++++++++++++++++ meshterm/ui/renderers.py | 307 ++++++++++++++++++++++++++ meshterm/ui/report.py | 243 +++++++++++++++++++++ meshterm/ui/script.py | 339 +++++++++++++++++++++++++--- tests/test_report.py | 401 ++++++++++++++++++++++++++++++++++ 9 files changed, 1776 insertions(+), 41 deletions(-) create mode 100644 meshterm/ui/fields.py create mode 100644 meshterm/ui/renderers.py create mode 100644 meshterm/ui/report.py create mode 100644 tests/test_report.py diff --git a/meshterm/cli.py b/meshterm/cli.py index 977a2df..84ae571 100644 --- a/meshterm/cli.py +++ b/meshterm/cli.py @@ -31,7 +31,8 @@ from .persistence.repository import Repository from .platforms import Resolution, resolve, set_platform, without_emoji from .tools import all_tools from .tools.base import Tool, ToolResult -from .ui import script +from .ui import renderers, script +from .ui.renderers import OutputFormat from .ui.termfont import emoji_support from .ui.theme import make_console @@ -86,6 +87,9 @@ def main_callback( mock: bool = typer.Option(False, "--mock", help="Use the built-in simulator"), db_path: Path | None = typer.Option(None, "--db", help="SQLite database path"), json_output: bool = typer.Option(False, "--json", help="Machine-readable output"), + absolute: bool = typer.Option( + False, "--absolute", help="Print absolute timestamps instead of relative ages" + ), quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress console logging"), platform: str | None = typer.Option( None, @@ -104,7 +108,8 @@ def main_callback( tcp: Explicit network address ``host[:port]``, selecting the TCP transport. mock: Whether to use the simulator instead of real hardware. db_path: Override the database location. - json_output: Request machine-readable output from tools. + json_output: Print the answer as JSON instead of aligned text. + absolute: Print times as ISO-8601 instants rather than relative ages, for this run. quiet: Suppress console logging (file logging continues). platform: Explicit ``--platform`` override; see :func:`meshterm.platforms.resolve`. """ @@ -138,6 +143,12 @@ def main_callback( # Loaded before logging is configured, because how much goes in the file is one of # them — and handed to the context afterwards so the file is not read twice. prefs = Preferences.load(settings.config_dir / "preferences.yaml") + if absolute: + # An override of the preference rather than a second switch beside it: *how + # MeshTerm behaves* is a preference by this project's own rule, and a flag that + # bypassed the registry would be a behaviour a reader could not find. Set, never + # saved — it is a claim about this run. + prefs.set("cli_time_format", "absolute") configure_logging( # A scripted run's stdout carries its answer and nothing else, so log records go # to stderr instead of interleaving with the data a caller is parsing. @@ -173,7 +184,10 @@ def main_callback( ble_override=ble, tcp_override=tcp, ble_pin=ble_pin, - json_output=json_output, + output=OutputFormat.JSON if json_output else OutputFormat.PLAIN, + # Whether a tool may stop and ask, which is a different question from what its + # output looks like. A pipe on stdin means nobody is there to answer. + interactive=_stdin_is_a_person(), explicit_selection=( profile is not None or port is not None or ble is not None or tcp is not None ), @@ -182,6 +196,12 @@ def main_callback( ctx.call_on_close(app_ctx.repo.close) if ctx.invoked_subcommand is None: + if json_output: + # There is no document an interactive session can emit, and launching the + # full-screen menu for a caller that asked for JSON would hang whatever was + # waiting to parse it. + raise typer.BadParameter("--json needs a subcommand; the menu has no document") + from .ui.menu import run_menu # Before prompt_toolkit takes the screen: this can change the console's own font, @@ -480,9 +500,21 @@ def specimen_command() -> None: (rather than the plain one every other subcommand prints on — see :mod:`meshterm.ui.script`). This is not scripted output that happens to be pretty: the colour *is* the output. A monochrome specimen would test nothing. + + It is also the one command that *refuses* ``--json``, loudly and as a usage error. + There is no data behind a colour card, so a document of it would be either a lie or an + empty gesture — and a loud refusal is the same answer this project already gives for + the map, the dashboard and the live feed, which simply have no subcommand to refuse + from. """ from .ui.specimen import specimen_lines + assert _state is not None # set by the callback that always runs first + if _state.output is not OutputFormat.PLAIN: + raise typer.BadParameter( + "specimen has no machine-readable output — its output is the colour" + ) + console = make_console() for line in specimen_lines(): console.print(line) @@ -539,6 +571,23 @@ def run_tool_command(tool: Tool, params: dict) -> None: raise typer.Exit(result.exit_code) +def _stdin_is_a_person() -> bool: + """Whether something is there to answer a prompt. + + The test a tool actually wants before it stops and asks: a redirected or piped stdin + means nobody is watching, and a command that blocks there has hung rather than failed. + ``tx-optimize`` used to ask ``--json`` instead — a flag about output format, which + answers a different question and answered this one wrong in both directions. + + Returns: + ``True`` only where stdin is a terminal. + """ + try: + return bool(sys.stdin.isatty()) + except (AttributeError, ValueError): # pragma: no cover - stdin closed or replaced + return False + + def _reported(tool: Tool, problem: object, code: int) -> typer.Exit: """Log a failure, say so on stderr, and build the exit it should end on. @@ -587,12 +636,12 @@ async def _drive(coro, ctx: AppContext): # noqa: ANN201 - passes the awaited va async def _execute_and_render(tool: Tool, params: dict, ctx: AppContext) -> ToolResult: - """Run a tool and print any file it produced. + """Run a tool and render the answer it stated. - A tool's ``message`` is not printed here. It is the menu's closing line — "✓ applied - 3 changes", "✓ traced Alice" — and on the command line it restates what the output - above it already showed and what ``$?`` already says. Where a scripted run has a fact - to report that the listing does not carry, the tool prints that fact itself. + The one place a report becomes output. The tool says what happened as data and this + hands it to whichever renderer ``--json`` selected, exactly as ``exit_code`` is stated + here and turned into a process status by the caller — which is what lets a third format + be a new renderer rather than an edit to twenty tools. Args: tool: The tool to execute. @@ -603,6 +652,7 @@ async def _execute_and_render(tool: Tool, params: dict, ctx: AppContext) -> Tool The tool's :class:`ToolResult`. """ result = await tool.execute(ctx, params) + renderers.for_format(ctx.output, ctx.console).render(result.report) # A produced file is a fact, and its path is the whole of it: bare, one per line, so # `meshterm config backup out.toml` can be read by the thing that runs it. for artifact in result.artifacts: diff --git a/meshterm/context.py b/meshterm/context.py index 76383c0..0776316 100644 --- a/meshterm/context.py +++ b/meshterm/context.py @@ -30,6 +30,7 @@ from .core.settings_store import SettingsStore from .core.watch_store import WatchStore from .persistence.logging import get_logger from .persistence.repository import Repository +from .ui.renderers import OutputFormat if TYPE_CHECKING: from .services.advert_scheduler import AdvertScheduler @@ -91,7 +92,16 @@ class AppContext: interactive picker), selecting the TCP transport. Takes precedence over ``ble_override`` and ``port_override``. ble_pin: Optional BLE pairing PIN for the chosen Bluetooth device. - json_output: Whether tools should emit machine-readable output. + output: Which format a scripted run prints its answer in (see + :class:`~meshterm.ui.renderers.OutputFormat`). A tool never reads this to + decide *what* to say — it states its answer as a + :class:`~meshterm.ui.report.Report` and the CLI boundary picks the renderer — + and the two streaming commands read it only to open the right kind of stream. + interactive: Whether this run may stop and ask a person something. False for every + scripted run whose stdin is not a terminal, which is the question a tool + actually wants answered before it prompts. ``tx-optimize`` used to ask + ``--json`` instead, and a flag about *output format* cannot answer it: without + the flag, a scheduled run on a terminal would sit waiting for a password. selected_device: The discovered device chosen for this session, when known, so it can be remembered after a successful connection. explicit_selection: Whether ``--port``/``--ble``/``--profile`` was passed explicitly @@ -118,7 +128,8 @@ class AppContext: ble_override: str | None = None tcp_override: str | None = None ble_pin: str | None = None - json_output: bool = False + output: OutputFormat = OutputFormat.PLAIN + interactive: bool = True selected_device: DiscoveredDevice | None = None explicit_selection: bool = False _device: Device | None = field(default=None, init=False, repr=False) diff --git a/meshterm/core/preferences.py b/meshterm/core/preferences.py index cc71d79..4bfc1b2 100644 --- a/meshterm/core/preferences.py +++ b/meshterm/core/preferences.py @@ -109,6 +109,10 @@ class PrefSpec: return f"{self.help} (next launch)" if self.relaunch else self.help +#: The two languages the plain CLI can print a time in. Named for what the reader sees +#: rather than for the mechanism: an *age* is how long ago, a *timestamp* is when. +_CLI_TIME_CHOICES: dict[str, str] = {"relative": "ages", "absolute": "timestamps"} + #: The silence-rule choices, drawn from the Watchtower's own ring so the two never drift. _SILENCE_CHOICES: dict[int, str] = { **{h: f"{h} h" for h in SILENCE_CHOICES_H}, @@ -284,6 +288,19 @@ PREFERENCES: tuple[PrefSpec, ...] = ( maximum=5000, ), # --- Display ----------------------------------------------------------------- + PrefSpec( + key="cli_time_format", + label="Command-line times", + help="Whether the command line prints ages or timestamps", + group="Display", + value_type="enum", + # Relative, because a person at a prompt asking "heard recently?" should not have + # to subtract an ISO instant from `date` to find out. `--absolute` overrides this + # for one run, and the JSON face is UTC either way — it is read somewhere else and + # often later, where a relative age has nothing to be relative to. + default="relative", + choices=_CLI_TIME_CHOICES, + ), PrefSpec( key="fast_render", label="Fast redraw", diff --git a/meshterm/tools/base.py b/meshterm/tools/base.py index 24e0fef..c6f36cb 100644 --- a/meshterm/tools/base.py +++ b/meshterm/tools/base.py @@ -18,6 +18,7 @@ if TYPE_CHECKING: # avoid importing typer/context at module load for fast start import typer from ..context import AppContext + from ..ui.report import Report @dataclass(slots=True) @@ -36,12 +37,27 @@ class ToolResult: set to ``NO_RESULT`` by a tool that ran fine and found nothing to report, so a caller can tell an empty mesh from a full one without counting lines. A *failure* is raised, not returned, so this never carries one. + report: **The answer**, as data (see :mod:`meshterm.ui.report`). A scripted run + states it here and the CLI boundary hands it to a renderer, exactly as it + already does with ``exit_code`` — the tool says what happened, and something + else turns that into bytes or into a process status. It used to be printed + instead, which meant the answer was gone by the time anything could ask for it + in another format, which is why ``--json`` reached two commands and stopped. + + ``None`` for the menu path and for a feature with no scripted face at all (the + map, the dashboard), which keep working unchanged. + + Not folded into ``summary``: that is the *run log's* record of what this + invocation did, written to the ``runs`` table on every execution including a + menu run. Putting a five-hour ``monitor`` capture in SQLite would be the price + of one field fewer. """ summary: dict[str, Any] = field(default_factory=dict) message: str | None = None artifacts: list[str] = field(default_factory=list) exit_code: int = exitcodes.OK + report: Report | None = None class Tool(ABC): diff --git a/meshterm/ui/fields.py b/meshterm/ui/fields.py new file mode 100644 index 0000000..5479400 --- /dev/null +++ b/meshterm/ui/fields.py @@ -0,0 +1,413 @@ +"""The shared shapes a report is built out of — one constructor per concept. + +A node means the same thing in ``contacts``, ``monitor``, ``courier list``, ``trace`` and +``records``, and it should *look* the same in all five and parse the same in all five. The +way to guarantee that is not review, it is construction: every listing that mentions a +node asks this module for the column, so there is exactly one definition of what a node's +plain lanes are called and what its machine object holds. + +Each constructor returns one :class:`~meshterm.ui.report.Column`, which carries both +projections of one typed value. The typed value is what a row holds — a :class:`NodeRef`, +a :class:`Position`, a :class:`~datetime.datetime`, a bare float — never a formatted cell, +so the plain face can print ``+5.1`` and the machine face ``5.1`` without either one +parsing the other's output back. + +The interesting one is :func:`node`, and it is what earns the design: **one machine key +expands to as many plain columns as the surface has room for.** ``contacts`` spends four +(a name, a role, a hash, a key), ``monitor``'s live stream spends two, a trace's per-hop +table spends one — and all four documents carry the same five-key object, because the +lanes are a rendering choice and the shape is not. + +Two absences, kept apart on purpose. ``None`` is *we do not know*, and it reads as +:data:`~meshterm.ui.script.NONE` plain and ``null`` in JSON. A word standing in for an +absence is not the same thing: ``unknown`` in a ``TYPE`` column is a word a reader +understands, so the plain face keeps it, while the document writes ``null`` — because a +consumer already has one spelling for "there is nothing here" and a second one costs it a +special case. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from dataclasses import dataclass +from datetime import datetime +from typing import Any + +from . import script +from .report import Column, Lane, normalise + +# -- the shared value shapes ----------------------------------------------------------- + + +@dataclass(frozen=True, slots=True) +class NodeRef: + """A mesh participant's identity, and nothing else. + + The most repeated concept in either face. *Identity only*: when a node was heard, how + strong it came in, where it says it is — those belong to the **row**, because they + differ per surface and a node object that carried them would mean something different + in every one. + + Attributes: + name: The name the node advertises, or ``None`` where none was ever heard — + including where a surface substitutes a bare hash for one. + key: The full public key, lowercase hex, **never truncated**: a key cut short is + not something a caller can hand back to ``--to`` or ``--path``. ``None`` where + only a hash was ever heard. + hash: The short derived id, at the width the surrounding surface addressed the + node by — never ``key`` shortened by this module's own choosing. + type: The advertised role in the lexicon's words (``node``, ``repeater``, + ``room``, ``sensor``), or ``None`` where the advert never said. + is_self: Whether this is our own node. The plain face draws it like any other hop, + which is the point: "you already know who this is" is true of the person at + the prompt and false of whoever reads the file afterwards. The machine face + carries it as ``self``, because a parser has no way to work it out at all. + """ + + name: str | None = None + key: str | None = None + hash: str | None = None + type: str | None = None + is_self: bool = False + + +@dataclass(frozen=True, slots=True) +class Position: + """A shared location, in decimal degrees. + + Unrounded in the document, as stored: the plain face's five decimals are a column-width + concession and a consumer should not inherit one. + """ + + lat: float + lon: float + + +@dataclass(frozen=True, slots=True) +class ChannelRef: + """One channel slot's identity. The secret is deliberately not in it. + + A channel object travels through listings and send receipts, and a key that rode along + in all of them would be a key printed by commands nobody asked to print one. It + appears only where the caller explicitly asked (``channels share``), under its own + field, beside this. + + Attributes: + slot: The 0-based index every ``channels`` subcommand's ``INDEX`` takes. + name: The channel name. + public: Whether the key is derived from the name (a ``#`` channel or a firmware + default) rather than secret. + hash: The channel hash, lowercase hex. + """ + + slot: int + name: str + public: bool + hash: str | None = None + + +def node_json(ref: NodeRef | None) -> dict[str, Any] | None: + """One node as its machine object, or ``null`` where there is no node at all.""" + if ref is None: + return None + return { + "name": ref.name or None, + "key": (ref.key or None) and ref.key.lower(), + "hash": (ref.hash or None) and ref.hash.lower(), + "type": ref.type or None, + "self": ref.is_self, + } + + +def position_json(where: Position | None) -> dict[str, Any] | None: + """One position as its machine object, or ``null`` where none was ever shared. + + The whole object is ``null`` rather than a pair of ``null``s: a latitude without a + longitude is not half a location, it is no location. + """ + return None if where is None else {"lat": where.lat, "lon": where.lon} + + +def channel_json(channel: ChannelRef | None) -> dict[str, Any] | None: + """One channel as its machine object, or ``null`` for an empty slot.""" + if channel is None: + return None + return { + "slot": channel.slot, + "name": channel.name, + "public": channel.public, + "hash": (channel.hash or None) and channel.hash.lower(), + } + + +# -- the constructors ------------------------------------------------------------------ + +#: How each of a node's plain lanes reads its cell. A surface picks the ones it has room +#: for; the machine object is the same five keys either way. +_NODE_LANES = { + "name": lambda ref: script.name(ref.name if ref else None), + # The word, not a glyph: `▲` without its colour would need a legend and the CLI has no + # legends. `unknown` is a word a reader acts on; the document writes `null`. + "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, +} + + +def node(key: str = "node", *, lanes: Sequence[tuple[str, str]] = (("name", "NAME"),)) -> Column: + """One node: the shared five-key object, and whichever plain lanes fit. + + Args: + key: The machine key, and the key the row holds its :class:`NodeRef` at. + lanes: ``(part, header)`` pairs naming the plain columns to draw, in order. The + parts are ``name``, ``type``, ``hash`` and ``key``. A surface with one column + to spend draws the name; a per-hop table draws the hash, because that is what + joins it to the route line above it. + + Returns: + The column. + """ + return Column( + key=key, + lanes=tuple(Lane(header=header, render=_NODE_LANES[part]) for part, header in lanes), + json=node_json, + ) + + +def position(key: str = "position", header: str = "LOCATION") -> Column: + """A shared location: one plain column, one machine object. + + One column and not two. A coordinate pair is one fact to a reader, it is what goes + into a map's search box verbatim, and two columns of ``-`` for every node that has + never shared a position is worse than one. + """ + return Column( + key=key, + lanes=(Lane(header=header, render=_position_cell),), + json=position_json, + ) + + +def channel( + key: str = "channel", + *, + lanes: Sequence[tuple[str, str]] = (("name", "NAME"),), +) -> Column: + """One channel slot: the shared four-key object, and whichever plain lanes fit. + + Args: + key: The machine key. + lanes: ``(part, header)`` pairs; the parts are ``slot``, ``name``, ``type`` and + ``hash``. ``type`` is the plain face's word for the ``public`` boolean — + ``public``/``private`` reads where ``true``/``false`` would need the heading + to say which way round it runs. + """ + parts = { + "slot": lambda c: script.number(c.slot if c else None), + "name": lambda c: script.name(c.name if c else None), + "type": lambda c: ("public" if c.public else "private") if c else script.NONE, + "hash": lambda c: ((c.hash or "").lower() if c else "") or script.NONE, + } + return Column( + key=key, + lanes=tuple(Lane(header=header, render=parts[part]) for part, header in lanes), + json=channel_json, + ) + + +def when(key: str, header: str, *, absent: str = script.NONE) -> Column: + """A time the reader reads as an age: ``5m``, ``3h``, ``never``. + + The default form for every time in a listing, because "recently?" is the question the + reader typed the command to ask and an ISO instant makes them do arithmetic to answer + it. ``--absolute`` swaps the whole language back for a run; the document is UTC + regardless, since it is read somewhere else and often later. + + Args: + key: The machine key. It ends in ``_at`` by convention — a JSON key is a type hint + for a parser, and the suffix is the hint. + header: The plain heading. + absent: What an unknown time reads as plain. ``never`` where the row exists and + the event has not happened (a node not yet heard, a conversation with nothing + said in it); the default token where the row has no such time at all. + + Returns: + The column. + """ + return Column( + key=key, + lanes=(Lane(header=header, render=lambda v: _time(v, absent=absent), align="right"),), + ) + + +def instant(key: str, header: str) -> Column: + """A time that *is* the fact, printed absolutely whatever ``--absolute`` says. + + Three surfaces want this and each for the same reason — the instant is the answer, not + a way of saying how long ago something was. The device's own clock. An appointment set + with ``--at``, which is a wall-clock time the caller chose. And a live capture's own + ``TIME`` column, every row of which would otherwise read ``now``. + """ + return Column(key=key, lanes=(Lane(header=header, render=script.stamp),)) + + +def snr(key: str, header: str) -> Column: + """A signal-to-noise reading: ``+5.1`` plain, ``5.1`` in the document. + + The plain sign is a column convention — a lane of readings only reads as a ladder when + every one of them declares its direction. A number in JSON carries its own sign and a + leading ``+`` would make it a string. + """ + return Column( + key=key, + lanes=(Lane(header=header, render=lambda v: script.number(v, "+.1f"), align="right"),), + json=lambda v: None if v is None else round(float(v), 1), + ) + + +def integer(key: str, header: str) -> Column: + """A whole number, right-aligned so a column of them is comparable by eye.""" + return Column(key=key, lanes=(Lane(header=header, render=script.number, align="right"),)) + + +def decimal(key: str, header: str, spec: str = ".1f") -> Column: + """A measured number, formatted for the column and left unrounded in the document.""" + return Column( + key=key, + lanes=(Lane(header=header, render=lambda v: script.number(v, spec), align="right"),), + ) + + +def flag(key: str, header: str) -> Column: + """A boolean: ``yes``/``no`` for a reader, ``true``/``false`` for a parser. + + ``None`` is a third answer and stays one — ``acked`` on a channel message is not + ``false``, it is *there is no acknowledgement on a channel*, and the two are different + things to anyone counting delivery failures. + """ + return Column( + key=key, + lanes=(Lane(header=header, render=_flag_cell),), + ) + + +def word(key: str, header: str) -> Column: + """A member of a closed set — a state, a role, an outcome — as its own lowercase word. + + Both faces say the same word, so ``courier send``'s ``no ack`` reads the same in a + document as it does on the line the help lists it on. + """ + return Column(key=key, lanes=(Lane(header=header, render=lambda v: v or script.NONE),)) + + +def name(key: str, header: str) -> Column: + """A bare name that is not a node's — a channel label, a conversation, a device.""" + return Column(key=key, lanes=(Lane(header=header, render=script.name),)) + + +def free(key: str, header: str) -> Column: + """Free text a stranger filled in: escaped so it can never end its own record. + + Always the last lane in a listing, because it is the one field with no width. The + document carries it **raw and unshortened** — a JSON string holds a newline natively, + so the escaping is a plain-text necessity rather than something to inflict on a + consumer. + """ + return Column(key=key, lanes=(Lane(header=header, render=script.text),)) + + +def route(key: str = "route", header: str = "ROUTE") -> Column: + """A walked hop sequence: drawn with arrows plain, an array of nodes in the document. + + The row holds :class:`NodeRef` objects in propagation order, so the document's hops are + the same objects a listing's rows carry and a consumer's node handler is written once. + ``None`` where nothing came home — never ``[]``, which would claim a walk of no hops. + """ + return Column( + key=key, + lanes=( + Lane( + header=header, + render=lambda hops: ( + script.route([(h.name, h.hash) for h in hops]) if hops else script.NONE + ), + ), + ), + json=lambda hops: None if hops is None else [node_json(hop) for hop in hops], + ) + + +def spec(key: str = "path", header: str = "path") -> Column: + """A forced path exactly as the radio was given it: ``a1,d4,a1``, or absent. + + The one line on either face that round-trips into ``--path``, so it keeps its commas + and grows nothing. ``None`` means the device routed the walk itself: the plain face + says ``auto`` because a reader needs a word there, and the document says ``null`` + because ``auto`` is not a path spec and R3 already has a token for "there is no spec + here". + """ + return Column( + key=key, + lanes=(Lane(header=header, render=lambda v: v if v else "auto"),), + ) + + +def hexid(key: str, header: str) -> Column: + """A hash or a key on its own, lowercase, never truncated and never elided.""" + return Column( + key=key, + lanes=(Lane(header=header, render=lambda v: (v or "").lower() or script.NONE),), + json=lambda v: (v or None) and str(v).lower(), + ) + + +def note(key: str, header: str) -> Column: + """Prose for a reader, with no machine face at all. + + A preference's DESCRIPTION is the case: it explains a preference to somebody deciding + whether to change it, and there is nothing in it a program would branch on. Declaring + it as a column rather than smuggling it in keeps the listing's two faces stated in one + place. + """ + return Column(key=key, lanes=(Lane(header=header, render=script.text),), json=None) + + +def hidden(key: str) -> Column: + """A fact the document carries and the plain face has no room for. + + The mirror of :func:`note`. ``config show`` prints a setting's key and its value — + that is what a reader came for — while the document also says what type it is, what an + enum's number is called, and whether the value was withheld. + """ + return Column(key=key) + + +def _position_cell(where: Position | None) -> str: + """One position's cell: the pair, or the absent token.""" + return script.NONE if where is None else script.location(where.lat, where.lon) + + +def _flag_cell(value: bool | None) -> str: + """One boolean's cell, keeping ``None`` as an absence rather than a ``no``.""" + return script.NONE if value is None else ("yes" if value else "no") + + +def _time(value: Any, *, absent: str) -> str: + """Render a time in whichever language this run speaks (see :func:`when`).""" + if isinstance(value, datetime) or value is None: + return script.stamp(value) if _absolute() else script.age(value, absent=absent) + return normalise(value) # pragma: no cover - a row holding something else is a bug + + +def _absolute() -> bool: + """Whether this run prints absolute times. + + Read from the preference registry rather than a module flag, because *how MeshTerm + behaves* is a preference by this project's own rule — and ``--absolute`` is then + simply that preference overridden for one run (see + :func:`~meshterm.cli.main_callback`), rather than a second switch saying the same + thing in a place a reader cannot find. + """ + from ..core.preferences import current + + return str(current().cli_time_format) == "absolute" diff --git a/meshterm/ui/renderers.py b/meshterm/ui/renderers.py new file mode 100644 index 0000000..ceba83f --- /dev/null +++ b/meshterm/ui/renderers.py @@ -0,0 +1,307 @@ +"""The two faces of one answer: a renderer turns a report into bytes. + +A tool states its answer as a :mod:`~meshterm.ui.report`; this module is where that +becomes output, and the CLI boundary picks which one runs (see +:func:`~meshterm.cli.main_callback`). Nothing above here knows what a gutter or a comma is, +and nothing below here knows what a contact is. That separation is the whole point: a +third format later — YAML, CSV, whatever somebody needs — is a new class in this file and +not an edit to twenty tools. + +**Plain** (:class:`PlainRenderer`) is for a person at a prompt: aligned columns, ages, a +route drawn with arrows, and a ``sysctl -a`` block for a set of facts about one thing. It +is written in the vocabulary of :mod:`meshterm.ui.script`, which is where the reasons for +each of its rules live. + +**JSON** (:class:`JsonRenderer`) is for a program, often on another machine and often +later. It prints **the answer itself** — an array for a listing, an object for a set of +facts — compact, one line, UTF-8, no ASCII escaping, keys in the order the report declares +them. There is no wrapper: ``meshterm contacts --json | jq '.[].node.name'`` reads what it +looks like it reads, and the report a caller needs is still ``$?``, exactly as it is +without the flag. So a failure prints **nothing at all** on stdout — the ``meshterm: what +went wrong`` line stays on stderr where every utility puts it, and stdout holding a valid +document is then a reliable signal that the command worked. + +Two rules cover a report of more than one block, and between them they produce the +documents ``trace`` and ``tx-optimize`` are specified with. A **single-block** report *is* +its block's document. A **multi-block** report is one object: each :class:`Listing` under +its own key, and each :class:`Facts` merged in at the top level — a facts block is the set +of facts about the one thing the command answered, so it is the document rather than a +compartment inside it. +""" + +from __future__ import annotations + +import json +from collections.abc import Iterator, Mapping, Sequence +from contextlib import contextmanager +from enum import Enum +from typing import TYPE_CHECKING, Any + +from rich.console import Console +from rich.text import Text + +from . import script +from .report import BARE, SILENT, Block, Facts, Lane, Listing, Report + +if TYPE_CHECKING: # pragma: no cover - typing only + from ..context import AppContext + + +class OutputFormat(str, Enum): + """The formats a scripted run can print its answer in. + + An enum rather than the ``--json`` boolean it replaces, because the boolean was + already being asked questions it could not answer — ``tx-optimize`` read it as "may I + prompt?" — and because a third member here costs one renderer and no tool changes at + all. ``--json`` stays the documented spelling and is sugar for this. + """ + + PLAIN = "plain" + JSON = "json" + + +class Renderer: + """Turns a report into bytes. One subclass per format.""" + + def render(self, report: Report | None) -> None: + """Print a completed report, or nothing at all when there is none.""" + raise NotImplementedError + + @contextmanager + def stream(self, listing: Listing) -> Iterator[Any]: + """Open a live listing whose rows arrive one at a time. + + The narrow second seam, and it exists because a stream has no end to return from: + ``monitor`` and ``chat listen`` run until a window closes or somebody interrupts + them, so their answer cannot be a value handed back at the end. Two commands use + it. Nothing else should — a command that can build a whole report should, because + a report is the thing every format already knows how to read. + + Args: + listing: The shape of the records to come — its columns, its lane order, and + (for the plain face) the width each lane is pinned to. Its ``rows`` are + ignored; rows arrive through the yielded callable. + + Yields: + A callable taking one typed row mapping. + """ + raise NotImplementedError + + +class PlainRenderer(Renderer): + """The face a person reads: aligned text on the scripted console. + + Attributes: + console: The plain console (see :func:`meshterm.ui.script.console`). + """ + + def __init__(self, console: Console) -> None: + """Bind the renderer to the console its output goes to.""" + self.console = console + + def render(self, report: Report | None) -> None: + """Draw each block in order, one blank line between them.""" + for index, block in enumerate(report or ()): + drawn = self._block(block) + if drawn is None: + continue + if index: + self.console.print(script.blank()) + self.console.print(drawn) + + def _block(self, block: Block) -> Any: + """The renderable for one block, or ``None`` where it prints nothing.""" + if isinstance(block, Listing): + return self._listing(block) if block.rows else None + if isinstance(block, Facts): + return self._facts(block) + raise TypeError(f"unrenderable block: {block!r}") # pragma: no cover - closed set + + def _listing(self, block: Listing) -> Any: + """A listing as its header line and its padded records.""" + lanes = block.lanes() + table = script.columns( + *(lane.header for _, lane in lanes), + right=[lane.header for _, lane in lanes if lane.align == "right"], + ) + # `config show` is an array to a parser and a `sysctl -a` block to a reader, so it + # keeps the columns and drops the heading row. Same table either way — the padding, + # the no-wrap and the crop are what make a record splittable, and none of them is + # the header's doing. + table.show_header = block.headed + for row in block.rows: + table.add_row(*(lane.render(row.get(column.key)) for column, lane in lanes)) + return table + + def _facts(self, block: Facts) -> Any: + """A facts block as a key/value listing, one bare value, or nothing.""" + if block.shape == SILENT: + return None + if block.shape == BARE: + column = next(c for c in block.fields if c.key == block.bare) + # As a Text, not a markup string: this is a private key, a share URL or a + # remote node's own reply, and Rich would read a bracket in one as a style tag. + return Text(column.lanes[0].render(block.values.get(column.key))) + rows: list[tuple[str, str]] = [] + for column in block.fields: + value = block.values.get(column.key) + if block.omit_absent and (value is None or value == ""): + continue + for lane in column.lanes: + rows.append((lane.header, lane.render(value))) + return script.pairs(rows) + + @contextmanager + def stream(self, listing: Listing) -> Iterator[Any]: + """Print the header line, then one pinned-lane record per row as it arrives.""" + lanes = listing.lanes() + pinned = script.stream( + *((lane.header, _lane_width(lane)) for _, lane in lanes), + right=[lane.header for _, lane in lanes if lane.align == "right"], + ) + self.console.print(pinned.header, highlight=False) + + def row(record: Mapping[str, Any]) -> None: + cells = [lane.render(record.get(column.key)) for column, lane in lanes] + self.console.print(pinned.record(*cells), highlight=False) + + yield row + + +class JsonRenderer(Renderer): + """The face a program reads: one compact document, or one per streamed record. + + Attributes: + console: The plain console, used only for its stream — the document is written + through :func:`json.dumps` rather than by Rich, so nothing can pad, wrap, + highlight or otherwise adorn it. + """ + + def __init__(self, console: Console) -> None: + """Bind the renderer to the console its output goes to.""" + self.console = console + + def render(self, report: Report | None) -> None: + """Print the report as one document, or nothing when there is no report at all.""" + if report is None: + return + blocks = [block for block in report if not block.plain_only] + if not blocks: + return + self._write(self._document(blocks)) + + def _document(self, blocks: Sequence[Block]) -> Any: + """Fold the blocks into the one value this command answers with.""" + if len(blocks) == 1: + return self._value(blocks[0]) + document: dict[str, Any] = {} + for block in blocks: + if isinstance(block, Facts): + document.update(self._facts(block)) + else: + document[block.key] = self._value(block) + return document + + def _value(self, block: Block) -> Any: + """One block's document: an array for a listing, an object for a set of facts.""" + if isinstance(block, Listing): + return [self._row(block, row) for row in block.rows] + if isinstance(block, Facts): + return self._facts(block) + raise TypeError(f"unrenderable block: {block!r}") # pragma: no cover - closed set + + @staticmethod + def _row(block: Listing, row: Mapping[str, Any]) -> dict[str, Any]: + """One record, with every declared key present (``null`` where it is absent).""" + return { + column.key: column.json(row.get(column.key)) + for column in block.columns + if column.json is not None + } + + @staticmethod + def _facts(block: Facts) -> dict[str, Any]: + """One facts block as an object, keeping every declared key. + + ``omit_absent`` is a *plain* concession — ``info`` leaves out a reading the + firmware does not answer for, so a dash never claims the radio reported nothing. + A consumer cannot act on that distinction and pays a membership test on every + field for it, so the document keeps the key and writes ``null``. + """ + return { + column.key: column.json(block.values.get(column.key)) + for column in block.fields + if column.json is not None + } + + def _write(self, document: Any) -> None: + """Write one compact document and terminate it with a newline.""" + line = json.dumps( + document, + # A node name in Cyrillic is a node name, not a run of `\uXXXX`. The scripted + # console already reconfigures stdout to UTF-8 for exactly this class of + # character. + ensure_ascii=False, + # Compact and one line, so a stream and a one-shot answer are read the same + # way and `jq .` can re-indent for a person at no cost. Nothing can un-stream + # a document that was pretty-printed across four hundred lines. + separators=(",", ":"), + ) + self.console.file.write(line + "\n") + self.console.file.flush() + + @contextmanager + def stream(self, listing: Listing) -> Iterator[Any]: + """Print one document per record, flushed, as each arrives. + + Every line is the same shape, which is what makes the stream readable without a + discriminator: a consumer reads line by line and never has to ask which kind of + record it is holding. The closing per-node summary the plain face draws is marked + ``plain_only`` for that reason — it is derivable from the records above it, and a + second shape mid-stream would cost every reader a branch it otherwise never needs. + """ + + def row(record: Mapping[str, Any]) -> None: + self._write(self._row(listing, record)) + + yield row + + +def for_format(output: OutputFormat, console: Console) -> Renderer: + """The renderer for one output format. + + Args: + output: What the caller asked for. + console: The console to print on. + + Returns: + The renderer. + """ + return JsonRenderer(console) if output is OutputFormat.JSON else PlainRenderer(console) + + +@contextmanager +def stream(ctx: AppContext, listing: Listing) -> Iterator[Any]: + """Open a live listing on whichever renderer this run is using. + + Args: + ctx: The application context, for its output format and console. + listing: The stream's shape (see :meth:`Renderer.stream`). + + Yields: + A callable taking one typed row mapping. + """ + with for_format(ctx.output, ctx.console).stream(listing) as row: + yield row + + +def _lane_width(lane: Lane) -> int: + """How wide a streamed lane is pinned. + + A live capture cannot size its columns the way :func:`~meshterm.ui.script.columns` + does, because it has not seen the records yet. So each lane declares the width it is + pinned to, and a value wider than that overruns and pushes the rest of its row right + rather than being cut — which is why the one unbounded field goes last (see + :class:`meshterm.ui.script.Lanes`). + """ + return max(len(lane.header), lane.width) diff --git a/meshterm/ui/report.py b/meshterm/ui/report.py new file mode 100644 index 0000000..e06e639 --- /dev/null +++ b/meshterm/ui/report.py @@ -0,0 +1,243 @@ +"""What a tool answers with, stated as data before anything decides how it looks. + +A scripted run used to say its answer by *printing* it: ``Tool.run`` called +``ctx.ui.show()`` and returned a :class:`ToolResult` +carrying only bookkeeping. By the time the CLI boundary saw that result the contacts had +already gone down the pipe as a space-aligned table, and there was nothing left to hand a +second format. That is exactly why ``--json`` reached two commands out of twenty and +stopped: each one that wanted it grew an ``if ctx.json_output:`` branch *above* the +rendering, restating the whole answer in a second dialect nobody else could reuse. + +``exit_code`` already showed the shape that works — the tool states it, the boundary turns +it into a process status, and no tool has ever called :func:`sys.exit`. This module lets +the answer travel the same way: + + **A tool states its answer as data. A renderer turns data into bytes. The CLI + boundary picks the renderer** (see :mod:`meshterm.ui.renderers`). + +A report is a short sequence of blocks, and there are only two kinds because the plain +face proved only two are needed — a :class:`Listing` (records under a header line) and +:class:`Facts` (one thing described key by key). A :class:`Facts` block covers the +one-scalar answer too, through :data:`BARE`: ``config get`` prints its value alone +*because the caller named the key*, while the machine face still gets the object with the +key, the type and the label in it. Splitting that into a third block type would have +bought a second name for the same data. + +**A row holds the typed value.** ``6.0``, ``None``, a :class:`~datetime.datetime` — never +a formatted cell. Each :class:`Column` carries both projections instead: the plain +:class:`Lane` that turns the value into text, and the JSON function that normalises it. +One typed row, two projections, and a third format later is a third function rather than a +third row-builder. :mod:`meshterm.ui.fields` builds the columns for the concepts the whole +app shares — a node, a time, an SNR, a route — so every listing speaks the same shapes by +construction rather than by review. + +Nothing here renders. A block does not know what a gutter is, and a column does not know +whether anyone will ever ask it for JSON. +""" + +from __future__ import annotations + +from collections.abc import Callable, Mapping, Sequence +from dataclasses import dataclass, field +from datetime import datetime, timezone +from enum import Enum +from pathlib import Path +from typing import Any + +#: How a :class:`Facts` block reaches the *plain* face. The machine face is the same +#: object either way — this only chooses what a person at a prompt is shown. +PAIRS = "pairs" +#: One named field's value, alone, with no key in front of it. What ``config get`` prints: +#: the caller named the key, so repeating it back is one more thing to strip off. +BARE = "bare" +#: Nothing at all. An acknowledgement — ``config advert``, ``channels join`` — whose plain +#: report is its exit status. The machine face still gets a document, because "prints +#: nothing" is an answer a person can act on and a program cannot. +SILENT = "silent" + + +def _text(value: Any) -> str: + """The last-resort plain projection: the value as text, or the absent token.""" + from . import script + + return script.NONE if value is None else str(value) + + +def normalise(value: Any) -> Any: + """A typed value in its machine form: JSON-ready, and the same on every host. + + The one place the contract's cross-cutting value rules are applied, so a command + cannot forget one: + + * a **time** is UTC, RFC 3339, ``Z``-suffixed, to the second — always twenty + characters, so string comparison is time comparison. A local offset is a fact about + the machine that ran the command rather than about the event, and two hosts asking + the same radio the same question must produce the same document. A *naive* time is + one whose offset we do not actually know, which is not a fact, so it reads as absent + exactly as it does on the plain face. + * an **enum** is its value, not its Python name. + * a **path** is its text. + * everything else travels as it is, typed: ``9`` and not ``"9"``, ``false`` and not + ``"false"``, ``None`` and not the plain face's ``-``. + + Args: + value: The typed value from a report row. + + Returns: + The value in a form :mod:`json` can write. + """ + if isinstance(value, datetime): + if value.tzinfo is None: + return None + return value.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + if isinstance(value, Enum): + return normalise(value.value) + if isinstance(value, Path): + return str(value) + if isinstance(value, (list, tuple)): + return [normalise(item) for item in value] + return value + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Lane: + """One plain-text column, drawn from its :class:`Column`'s typed value. + + A lane is the *reader's* half of a column. Several may share one column where the + plain face spends more room on a concept than the machine face does — a node is one + JSON object and up to four plain columns (its name, its role, its hash, its key), + which is the whole reason a column owns a list of these rather than one header string. + + Attributes: + header: The uppercase heading, and the field a caller greps for. Renaming one + silently breaks a script, so it is as much a contract as the exit status. + render: Turns the column's typed value into this lane's cell. + align: ``"right"`` for a lane of magnitudes — a column of numbers or ages is only + comparable by eye once the digits line up. + width: The cells this lane is pinned to in a *live* listing, where the widths + cannot be measured because the records have not arrived yet. Ignored by an + ordinary listing, which sizes every lane to its widest value. + """ + + header: str + render: Callable[[Any], str] = _text + align: str = "left" + width: int = 0 + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Column: + """One concept in a report, with a projection for each face. + + Attributes: + key: The name this concept goes under: the JSON key, and the key a row's mapping + holds its typed value at. + lanes: The plain columns this concept draws — usually one. **Empty means the + concept has no plain face**, which is how ``config show`` carries a setting's + type and enum label into the document while printing the two fields a reader + wants. + json: The typed value's machine projection, or ``None`` where the concept has no + machine face — the mirror of an empty ``lanes``, and what a preference's + DESCRIPTION is: prose for whoever is choosing a value, carrying nothing a + program would branch on. Defaults to :func:`normalise`, which handles the + scalars; a shared shape (a node, a position) passes its own. + """ + + key: str + lanes: tuple[Lane, ...] = () + json: Callable[[Any], Any] | None = normalise + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Block: + """One part of an answer. + + Attributes: + key: The name this block goes under in a multi-block document. + plain_only: Whether this block is a rendering for a person that the machine face + has no use for. The one case is a stream's closing summary: ``monitor`` prints + a per-node aggregate under its live capture, and a consumer holding every + record of that capture can compute the same thing — where a second *shape* of + line in the middle of an otherwise homogeneous NDJSON stream costs every + reader a discriminator it would otherwise never need. + """ + + key: str + plain_only: bool = False + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Listing(Block): + """Records under a header line: a listing plain, an array of objects in JSON. + + Attributes: + columns: The concepts each record carries, in machine-face order. + rows: One mapping per record, keyed by ``Column.key`` and holding **typed** + values. + order: The lane headers in plain draw order. Empty means "as declared", which is + what most listings want; a listing states it where the two orders genuinely + differ — ``contacts`` puts HEARD and PKTS between a node's TYPE and its HASH, + and ``monitor`` puts the one unbounded field (a node's name) last so it can + never push a column. + headed: Whether the plain face draws the header line. ``config show`` is the one + listing that does not: it is an array of settings to a parser and a + ``sysctl -a`` block to a reader, and a header line over two columns whose keys + are the answer would be furniture. + """ + + columns: tuple[Column, ...] + rows: Sequence[Mapping[str, Any]] = () + order: tuple[str, ...] = () + headed: bool = True + + def __post_init__(self) -> None: + """Reject an ``order`` that does not name this listing's own lanes. + + A typo here draws a listing with a column missing and no complaint, which is the + one failure a header line cannot show. Cheaper to raise at construction. + """ + if not self.order: + return + known = {lane.header for column in self.columns for lane in column.lanes} + if set(self.order) != known or len(self.order) != len(known): + raise ValueError(f"{self.key}: order must name every lane exactly once") + + def lanes(self) -> list[tuple[Column, Lane]]: + """The plain columns in draw order, each with the column it reads from.""" + pairs = [(column, lane) for column in self.columns for lane in column.lanes] + if not self.order: + return pairs + by_header = {lane.header: (column, lane) for column, lane in pairs} + return [by_header[header] for header in self.order] + + +@dataclass(frozen=True, slots=True, kw_only=True) +class Facts(Block): + """One thing, described key by key: a ``sysctl -a`` block plain, an object in JSON. + + Attributes: + fields: The concepts, in the order both faces present them. + values: The typed value per ``Column.key``. + shape: :data:`PAIRS`, :data:`BARE` or :data:`SILENT` — what the *plain* face + prints. The machine face is the object either way. + bare: With :data:`BARE`, the one field whose value is printed alone. + omit_absent: Whether a field with no value is left out of the plain block + entirely. Only ``info`` wants this, and deliberately: its readings are + optional device queries, so a missing key says "this radio does not report + it" where a dash would claim it reported nothing. The machine face keeps every + declared key and writes ``null``, because "does not report" and "reported + nothing" are the same fact to a caller and a variable key set costs every + consumer a membership test on every field. + """ + + fields: tuple[Column, ...] + values: Mapping[str, Any] = field(default_factory=dict) + shape: str = PAIRS + bare: str = "" + omit_absent: bool = False + + +#: A tool's whole answer. Deliberately a bare sequence rather than a class of its own: +#: there is nothing a report *does*, and the two rules about how several blocks combine +#: belong to the renderer that combines them (see :mod:`meshterm.ui.renderers`). +Report = tuple[Block, ...] diff --git a/meshterm/ui/script.py b/meshterm/ui/script.py index 5ada9f1..7000f39 100644 --- a/meshterm/ui/script.py +++ b/meshterm/ui/script.py @@ -48,6 +48,7 @@ Nothing here is reachable from the menu, and nothing in the menu is reachable fr from __future__ import annotations from collections.abc import Iterable, Sequence +from dataclasses import dataclass from datetime import datetime from typing import Any @@ -71,6 +72,18 @@ GUTTER = 2 #: parser) learns it once. Never ``—``, ``n/a``, ``never``, or an empty cell. NONE = "-" +#: The separator between a route's hops, spaced — the same ``→`` the menu's path lines +#: draw with (:data:`meshterm.ui.pathline._ARROW`), and device-verified present in the +#: PicoCalc console font. It carries the direction the packet travelled, and it is what +#: makes the quoting unnecessary: a comma inside a node's name can no longer be read as a +#: hop boundary. +ARROW = " → " + +#: How wide a *written page* wraps. Not the terminal's width: the same paragraph must read +#: the same when it is piped, redirected, or shipped as the machine face's ``text`` field, +#: and 72 is the width every screen in this app is already held to. +PAGE_WIDTH = 72 + #: The characters with a readable escape of their own. Everything else that cannot travel #: in a record falls through to ``\xNN``/``\uNNNN`` below. @@ -160,9 +173,33 @@ def oneline(value: str | None) -> str: return NONE if value is None else _escaped(value) +def text(value: str | None) -> str: + r"""Free text as a field that can end a record without breaking it. + + For the field a listing puts last because it *is* the rest of the line — a message + body, a preference's description. "The rest of the line" and "anything at all" are not + compatible: a body holding a newline ended its record early and left the remainder + indented under the other columns, reading as a second record with an empty ``TIME``. + A body is also the field a stranger fills in, so that is not a hypothetical shape of + message. + + Args: + value: The free text. ``None`` gives :data:`NONE`. + + Returns: + The text with its line breaks and tabs escaped. + """ + return NONE if value is None else _escaped(value) + + def stamp(when: datetime | None) -> str: """Format a timestamp as local ISO-8601 to the second, or :data:`NONE`. + Kept for the times where the instant *is* the fact rather than a way of saying how + long ago something was: the device's own clock, an appointment set with ``--at``, a + live capture's per-row time (every row of which would otherwise read ``now``), and + every column under ``--absolute``. + Stored times are timezone-aware UTC; a naive one is a time whose offset we do not actually know, which is not a fact and so reads as absent — the same rule :func:`~meshterm.ui.widgets._age_seconds` applies to ages. @@ -178,6 +215,31 @@ def stamp(when: datetime | None) -> str: return when.astimezone().isoformat(timespec="seconds") +def age(when: datetime | None, *, absent: str = NONE) -> str: + """How long ago ``when`` was: ``now``, ``5m``, ``3h``, ``2d``, ``4w``. + + The default time form, and the reason is the premise change: a person at a prompt + reading ``2026-09-07T19:58:53-04:00`` is doing arithmetic to answer "recently?", which + is the question they typed the command to ask. Delegates to + :func:`~meshterm.ui.widgets._format_age` so the two faces cannot drift apart. + + Args: + when: The instant to age. A naive datetime has no offset we know, so it reads as + absent, exactly as :func:`stamp` treats it. + absent: What an unknown time reads as. A heard-age passes ``"never"`` — a node + that has never been heard is a fact, not a missing field — and everything else + takes the default token, which says this row has no such time at all. The same + distinction :func:`name` draws between ``-`` and an empty name, one axis over. + + Returns: + The age, or ``absent``. + """ + from .widgets import _age_seconds, _format_age + + seconds = _age_seconds(when) + return absent if seconds is None else _format_age(seconds) + + def number(value: Any, spec: str = "") -> str: """Format a number, or :data:`NONE` when it is absent. @@ -193,13 +255,146 @@ def number(value: Any, spec: str = "") -> str: return format(value, spec) if spec else str(value) +#: The units :func:`duration` counts in, largest first. +_UNITS: tuple[tuple[int, str], ...] = ((86400, "d"), (3600, "h"), (60, "m"), (1, "s")) + + +def duration(seconds: float | None) -> str: + """A span of seconds as something readable: ``93784`` → ``1d 2h``, ``360`` → ``6m``. + + Two units at most and always adjacent, so the magnitude arrives at a glance and the + precision never outruns what anyone would act on. Used only as a *gloss* beside the + raw figure (``uptime_s 93784 (1d 2h)``), never in place of it — the key says what + the number counts, and a caller reading the key must still find a number under it. + + Args: + seconds: The span. ``None`` reads as absent; the sign is dropped, since a caller + glossing a signed reading says which way in its own words. + + Returns: + The span in one or two units, or :data:`NONE`. + """ + if seconds is None: + return NONE + whole = int(abs(seconds)) + amounts: list[tuple[int, str]] = [] + for size, unit in _UNITS: + amounts.append((whole // size, unit)) + whole %= size + lead = next((i for i, (amount, _) in enumerate(amounts) if amount), len(amounts) - 1) + parts = [f"{amounts[lead][0]}{amounts[lead][1]}"] + if lead + 1 < len(amounts) and amounts[lead + 1][0]: + parts.append(f"{amounts[lead + 1][0]}{amounts[lead + 1][1]}") + return " ".join(parts) + + +def location(lat: float | None, lon: float | None) -> str: + """A shared position as one field: ``45.50190,-73.56740``, or :data:`NONE`. + + One column rather than two. A coordinate pair is one fact to a reader, it is what goes + into a map's search box verbatim, and two columns of ``-`` for every contact that has + never shared a position is worse than one. + + Args: + lat: Latitude in decimal degrees. + lon: Longitude in decimal degrees. + + Returns: + The pair to five decimals, or :data:`NONE` when either half is missing. + """ + if lat is None or lon is None: + return NONE + return f"{lat:.5f},{lon:.5f}" + + +def route(hops: Iterable[tuple[str | None, str | None]]) -> str: + """A walked hop sequence, drawn: ``Yagi-Repeater (a1) → Alice (d4) → Yagi (a1)``. + + A *route* is what a walk actually did, so it is a picture and not a spec — which is + why it takes :data:`ARROW` and not the comma ``--path`` accepts. Rendering it with + commas made it look pasteable, which it is not: the names are in it, and it is a + round trip nothing has. + + The hash rides on every hop and always. It is the join key to the per-hop table below + a trace, the token ``--path`` takes, and the disambiguator for two contacts sharing a + name. Dropping it "where the name is unique" would make one line's grammar depend on + another line's content. + + Our own node is a hop like any other — named and hashed. The menu draws it as ``★`` + because a reader never has to be told which node is theirs; here the line is as often + read out of a file by someone who was not at the prompt when it ran. + + Args: + hops: ``(label, hash)`` pairs in propagation order. A hop with both halves reads + ``Name (hash)``; a hop with one half is that half alone, never an empty + ``()`` — which is how the menu's :class:`~meshterm.ui.pathline.PathLine` + labels an unresolved hop too. + + Returns: + The joined route, or :data:`NONE` when there are no hops. + """ + parts: list[str] = [] + for label, value in hops: + if label and value: + parts.append(f"{_escaped(label)} ({value})") + else: + parts.append(_escaped(label) if label else (value or NONE)) + return ARROW.join(parts) if parts else NONE + + +def spec(hops: Iterable[str]) -> str: + """A forced path as the radio was given it: ``a1,d4,a1``. + + The other half of the split :func:`route` names. This is the *spec* — comma-separated + hashes, exactly what ``--path`` takes back — so it is the one line on either face that + round-trips, and it must never grow a name, an arrow or a space. + + Args: + hops: The hop hashes in propagation order. + + Returns: + The comma-joined spec, or :data:`NONE` when there are no hops. + """ + parts = [hop for hop in hops if hop] + return ",".join(parts) if parts else NONE + + +def path(hops: Iterable[tuple[str, str | None]]) -> str: + """Render a hop sequence as the CLI's path line. + + ``"Origin" (3d),"Relay" (f2),"Us" (a1)`` — each node's name quoted (:func:`quote`), + its hash in parentheses *outside* the quotes, hops separated by a bare comma. + + The hash is there because the CLI has no colour. On a screen a route's hops are told + apart by their key-derived hues, and matched to a route graph's one-byte labels the + same way; with the colour gone, the hash is what carries that identity. + + Our own node is a hop like any other — named and hashed, never the menu's ``★``. The + star says "you already know who this is", which is true of a reader and false of a + parser. + + The comma is the separator ``--path`` already takes, and the quoting is what keeps the + line splittable when a name contains one. + + Args: + hops: ``(label, hash)`` pairs in propagation order; a ``None`` hash prints the + name alone, for a node whose identity is genuinely unknown. + + Returns: + The joined path line, or :data:`NONE` when there are no hops. + """ + parts = [f"{quote(label)} ({value})" if value else quote(label) for label, value in hops] + return ",".join(parts) if parts else NONE + + def columns(*headers: str, right: Sequence[str] = ()) -> Table: """Build the scripted table: an uppercase header line, then padded records. The shape ``ps`` and ``df`` print — no box, no title, no edge padding, every column sized to its widest value and separated by :data:`GUTTER` spaces, nothing wrapped and nothing elided. Numeric lanes right-align, which is what makes a column of magnitudes - comparable by eye without changing what splitting it yields. + comparable by eye without changing what splitting it yields; an *age* lane aligns the + same way, so the ladder from ``now`` to ``4w`` reads down the column. Args: *headers: The column headings, already uppercase. @@ -240,8 +435,8 @@ def pairs(rows: Iterable[tuple[str, str]]) -> Table: """Build the scripted key/value listing: key then value, aligned, no header line. What a set of facts about one thing prints as (``meshterm info``, ``config show``, - ``preferences show``) — the ``sysctl -a`` shape. Keys are the ones the matching - ``get``/``set`` subcommand takes, so a line read out of ``show`` can be typed back in. + ``trace``) — the ``sysctl -a`` shape. Keys are the ones the matching ``get``/``set`` + subcommand takes, so a line read out of ``show`` can be typed back in. Args: rows: ``(key, value)`` pairs in display order. @@ -264,32 +459,97 @@ def pairs(rows: Iterable[tuple[str, str]]) -> Table: return table -def path(hops: Iterable[tuple[str, str | None]]) -> str: - """Render a hop sequence as the CLI's path line. +@dataclass(frozen=True, slots=True) +class Lanes: + """A fixed-width column layout for output whose widths arrive with the data. - ``"Origin" (3d),"Relay" (f2),"Us" (a1)`` — each node's name quoted (:func:`quote`), - its hash in parentheses *outside* the quotes, hops separated by a bare comma. + :func:`columns` sizes each lane to its widest value, which it can only do once it has + seen every record. A live capture has no "once": ``monitor`` prints a row the instant + a packet lands, and the row after it may be twice as wide. Those two streams used to + be gutter-joined with no alignment at all, which is why a name in one still carried + its quotes — nothing else said where the field ended. - The hash is there because the CLI has no colour. On a screen a route's hops are told - apart by their key-derived hues, and matched to a route graph's one-byte labels the - same way; with the colour gone, the hash is what carries that identity. + Pinning the lanes up front fixes it properly. A value wider than its lane **overruns + and pushes the rest of that row right** rather than being elided: one row out of many + is simply wider, and nothing lies about what it holds. Put the one unbounded field + (a node's name, a message body) last and it cannot push anything at all. - Our own node is a hop like any other — named and hashed, never the menu's ``★``. The - star says "you already know who this is", which is true of a reader and false of a - parser. + Attributes: + widths: ``(header, width)`` per lane, in order. + right: The headers whose cells right-align. + """ - The comma is the separator ``--path`` already takes, and the quoting is what keeps the - line splittable when a name contains one. + widths: tuple[tuple[str, int], ...] + right: frozenset[str] = frozenset() + + @property + def header(self) -> str: + """The one header line, printed before the first record.""" + return self.record(*(header for header, _ in self.widths)) + + def record(self, *cells: str) -> str: + """One record, padded into the lanes and joined by the gutter.""" + out: list[str] = [] + for (header, width), cell in zip(self.widths, cells, strict=True): + out.append(cell.rjust(width) if header in self.right else cell.ljust(width)) + return (" " * GUTTER).join(out).rstrip() + + +def stream(*widths: tuple[str, int], right: Sequence[str] = ()) -> Lanes: + """Build a fixed-lane layout for a live stream (see :class:`Lanes`). Args: - hops: ``(label, hash)`` pairs in propagation order; a ``None`` hash prints the - name alone, for a node whose identity is genuinely unknown. + *widths: ``(header, width)`` per lane, in order. + right: The headings whose values right-align. Returns: - The joined path line, or :data:`NONE` when there are no hops. + The layout, which prints its own header and formats each record. """ - parts = [f"{quote(label)} ({value})" if value else quote(label) for label, value in hops] - return ",".join(parts) if parts else NONE + return Lanes(widths=widths, right=frozenset(right)) + + +def wrap(body: str, width: int = PAGE_WIDTH) -> str: + """Fold a written page's paragraphs to ``width``, leaving its structure alone. + + The deliberate exception to "no wrapping", and the reason the rule exists says why: + wrapping splits a *record* and lands half its fields under the wrong headings. A + written page has no records and no headings — and left unwrapped, ``meshterm about`` + prints paragraphs six hundred cells long that no terminal can read. + + A line's own indent is kept and carried onto its continuations, so a bullet stays a + bullet and an indented block stays indented; a blank line stays blank; a line that is + already short is untouched. + + Args: + body: The page, as its plain renderer laid it out. + width: The cell width to fold to. + + Returns: + The page with every over-long line folded under its own indent. + """ + import textwrap + + out: list[str] = [] + for line in body.splitlines(): + stripped = line.lstrip() + if not stripped: + out.append("") + continue + indent = line[: len(line) - len(stripped)] + # A bullet's continuations hang under its text, not under its marker. + hanging = indent + (" " if stripped[:1] in "-*•" else "") + out.extend( + textwrap.wrap( + stripped, + width=max(width - len(indent), 20), + initial_indent=indent, + subsequent_indent=hanging, + break_long_words=False, + break_on_hyphens=False, + ) + or [indent + stripped] + ) + return "\n".join(out) # -- the console --------------------------------------------------------------------- @@ -385,9 +645,16 @@ def stderr_console() -> Console: """The console for everything that is *about* the run rather than part of its answer. stdout carries what the command was asked for and nothing else, so a progress bar, a - log line and an error message all go here instead — visible in a terminal, absent from - ``meshterm contacts > contacts.txt``. This one keeps its colour and its wrapping: a - terminal is the only thing that ever reads it. + log line, an acknowledgement and an error message all go here instead — visible in a + terminal, absent from ``meshterm contacts > contacts.txt``. This one keeps its colour, + because a terminal is usually the only thing that reads it. + + **Off a terminal it stops wrapping**, and that is the point of the width below. Rich + falls back to 80 cells when it cannot measure the destination, so ``2> errors.log`` + used to hard-wrap every message at 80 — and ``grep 'not already connected'`` then + found nothing, because the sentence it was looking for had been broken across three + lines by the logger. In a real terminal the width is left alone: a progress bar sized + to 16384 cells is not a progress bar. Returns: A themed :class:`~rich.console.Console` writing to ``sys.stderr``. @@ -396,7 +663,17 @@ def stderr_console() -> Console: from .theme import active_theme - return Console(file=sys.stderr, theme=active_theme(), markup=False, emoji=False) + try: + wraps = bool(sys.stderr.isatty()) + except (AttributeError, ValueError): # pragma: no cover - a closed or exotic stream + wraps = False + return Console( + file=sys.stderr, + theme=active_theme(), + markup=False, + emoji=False, + width=None if wraps else WIDTH, + ) # -- the safety net ------------------------------------------------------------------ @@ -405,15 +682,15 @@ def stderr_console() -> Console: def flatten(renderable: RenderableType) -> list[RenderableType]: """Strip framing from anything reaching the scripted console still wearing it. - Every CLI surface is *written* plain — the tools build their output through - :func:`columns`, :func:`pairs` and :func:`path`. This is the net under that, for a - renderable shared with the menu that still arrives boxed: a :class:`Panel` gives up - its border and title and yields its body, a :class:`Table` gives up its box, title and - expansion, and a :class:`Group` is flattened member by member. + Every CLI surface is *written* plain — a tool states its answer as a + :mod:`~meshterm.ui.report` and the plain renderer builds it through :func:`columns` + and :func:`pairs`. This is the net under that, for a renderable shared with the menu + that still arrives boxed: a :class:`Panel` gives up its border and title and yields + its body, a :class:`Table` gives up its box, title and expansion, and a :class:`Group` + is flattened member by member. It is deliberately not a *design*: a screen's table has the menu's columns, not the - CLI's, so passing it through here makes it printable, not right. Anything a script is - meant to read gets a plain renderer of its own. + CLI's, so passing it through here makes it printable, not right. Args: renderable: What a tool handed to :meth:`~meshterm.ui.surface.PlainUi.show`. diff --git a/tests/test_report.py b/tests/test_report.py new file mode 100644 index 0000000..b911949 --- /dev/null +++ b/tests/test_report.py @@ -0,0 +1,401 @@ +"""Tests for the seam between a tool's answer and its rendering. + +:mod:`meshterm.ui.report` is where a tool states what it found, :mod:`meshterm.ui.fields` +is where the shapes it states it in are defined once, and :mod:`meshterm.ui.renderers` is +where that becomes bytes. The claim the whole design rests on is that **one typed row +projects two ways** — so almost every test here builds one report and asserts both faces +of it, because a rule that holds in only one of them is exactly the drift this replaced. +""" + +from __future__ import annotations + +import io +import json +from datetime import datetime, timezone + +import pytest + +from meshterm.ui import fields, script +from meshterm.ui.renderers import JsonRenderer, OutputFormat, PlainRenderer, for_format +from meshterm.ui.report import BARE, SILENT, Column, Facts, Lane, Listing + +_WHEN = datetime(2026, 9, 7, 22, 22, 41, tzinfo=timezone.utc) + + +def _plain(*blocks) -> str: # noqa: ANN002 - blocks vary per test + """Render a report through the plain face and return what came out.""" + buffer = io.StringIO() + PlainRenderer(script.console(buffer)).render(blocks) + buffer.flush() + return buffer.getvalue() + + +def _json(*blocks): # noqa: ANN002, ANN202 - blocks vary per test + """Render a report through the machine face and return the parsed document.""" + buffer = io.StringIO() + JsonRenderer(script.console(buffer)).render(blocks) + lines = [line for line in buffer.getvalue().splitlines() if line] + assert len(lines) == 1, lines + return json.loads(lines[0]) + + +def _contacts(rows) -> Listing: # noqa: ANN001 - rows vary per test + """A listing in the shape ``contacts`` uses: a node, an age and a count.""" + return Listing( + key="contacts", + columns=( + fields.node( + "node", + lanes=(("name", "NAME"), ("type", "TYPE"), ("hash", "HASH"), ("key", "KEY")), + ), + fields.when("heard_at", "HEARD", absent="never"), + fields.integer("packets", "PKTS"), + ), + rows=rows, + order=("NAME", "TYPE", "HEARD", "PKTS", "HASH", "KEY"), + ) + + +_ALICE = { + "node": fields.NodeRef(name="Alice", key="d4" * 32, hash="d4", type="node"), + "heard_at": _WHEN, + "packets": 12, +} + + +# -- one row, two faces ---------------------------------------------------------------- + + +def test_one_typed_row_reaches_both_faces_without_either_parsing_the_other() -> None: + """The claim the seam exists for: a row holds the value, not somebody's rendering. + + The plain face writes ``+5.1`` because a column of readings only compares by eye once + every one declares its sign; the document writes ``5.1`` because a number carries its + own. Neither could be derived from the other without a parser, which is what the two + hand-written ``if ctx.json_output:`` branches were. + """ + block = Listing(key="hops", columns=(fields.snr("snr_db", "SNR_DB"),), rows=[{"snr_db": 5.14}]) + assert _plain(block).splitlines()[1].strip() == "+5.1" + assert _json(block) == [{"snr_db": 5.1}] + + +def test_a_node_is_one_object_however_many_columns_it_is_worth() -> None: + """One machine key, four plain lanes — the thing :func:`fields.node` earns. + + Every listing that mentions a node asks for the same column, so ``jq '.[].node.key'`` + reads the same on contacts, courier and monitor and a consumer's node handler is + written once. What differs is only how much room the surface has for it. + """ + header, record = _plain(_contacts([_ALICE])).splitlines() + assert header.split() == ["NAME", "TYPE", "HEARD", "PKTS", "HASH", "KEY"] + assert len(record.split()) == len(header.split()) + assert "Alice" in record and "d4" * 32 in record + assert _json(_contacts([_ALICE]))[0]["node"] == { + "name": "Alice", + "key": "d4" * 32, + "hash": "d4", + "type": "node", + "self": False, + } + + +def test_a_listing_may_draw_its_lanes_in_an_order_the_document_does_not_use() -> None: + """``contacts`` puts HEARD and PKTS between a node's TYPE and its HASH. + + The lane order is a reading decision — the fields a person scans first go left — and + the key order is the document's. Tying them together would have meant choosing which + face to make worse. + """ + header = _plain(_contacts([_ALICE])).splitlines()[0].split() + assert header.index("HEARD") < header.index("HASH") + assert list(_json(_contacts([_ALICE]))[0]) == ["node", "heard_at", "packets"] + + +def test_a_listing_refuses_an_order_that_does_not_name_its_own_lanes() -> None: + """A typo here draws a listing with a column missing and no complaint. + + That is the one failure a header line cannot show — the records still line up, under + the wrong headings — so it is caught where it is written instead. + """ + with pytest.raises(ValueError, match="every lane"): + Listing( + key="x", + columns=(fields.integer("a", "A"), fields.integer("b", "B")), + order=("A", "NOPE"), + ) + + +# -- absences -------------------------------------------------------------------------- + + +def test_the_two_faces_spell_absence_in_their_own_alphabets() -> None: + """``-`` is learned once by a reader; ``null`` is what a parser already has. + + Same fact, and neither face has to know the other's token — which is what stopped the + plain ``-`` from ever reaching a document as a string. + """ + empty = {"node": None, "heard_at": None, "packets": None} + record = _plain(_contacts([empty])).splitlines()[1] + assert record.split() == ["-", "unknown", "never", "-", "-", "-"] + assert _json(_contacts([empty]))[0] == {"node": None, "heard_at": None, "packets": None} + + +def test_a_word_standing_in_for_an_absence_stays_a_word_only_on_the_plain_face() -> None: + """``unknown`` is a word a reader acts on; a consumer already has ``null`` for it. + + Carrying both would give a program two spellings for one fact and a special case to + remember on every field. + """ + row = {"node": fields.NodeRef(hash="a1")} + block = Listing(key="n", columns=(fields.node("node", lanes=(("type", "TYPE"),)),), rows=[row]) + assert _plain(block).splitlines()[1].strip() == "unknown" + assert _json(block)[0]["node"]["type"] is None + + +def test_a_never_heard_node_is_a_fact_and_an_undated_row_is_an_absence() -> None: + """Two different things, and the age lane says which without a second column. + + A node that has never been heard *has* a heard-age; a row with no such time at all + does not. Flattening both onto ``-`` would have made "we have not heard from it" and + "this kind of row has no heard time" the same reading. + """ + assert script.age(None, absent="never") == "never" + assert script.age(None) == script.NONE + + +def test_info_leaves_out_a_reading_the_radio_does_not_answer_for_and_json_keeps_the_key() -> None: + """The one deliberate disagreement between the faces, and why it is deliberate. + + A missing plain key says "this radio does not report it", where a dash would claim it + reported nothing — a distinction a person can act on. A consumer cannot, and a + variable key set costs it a membership test on every field, so the document keeps the + key and writes ``null``. + """ + block = Facts( + key="info", + fields=(fields.word("model", "model"), fields.integer("uptime_s", "uptime_s")), + values={"model": None, "uptime_s": 42}, + omit_absent=True, + ) + assert _plain(block).split() == ["uptime_s", "42"] + assert _json(block) == {"model": None, "uptime_s": 42} + + +# -- facts, bare and silent ------------------------------------------------------------ + + +def test_a_get_prints_its_value_alone_and_still_documents_the_key() -> None: + """The caller named the key, so repeating it back is one more thing to strip off. + + ``$(meshterm config get name)`` needs no stripping — an argument entirely about shell + substitution, which a JSON consumer is not doing, so the document keeps the key, the + type and the label the bare form threw away. + """ + block = Facts( + key="setting", + fields=( + fields.word("key", "key"), + fields.word("value", "value"), + fields.hidden("type"), + ), + values={"key": "tx_power", "value": "20", "type": "int"}, + shape=BARE, + bare="value", + ) + assert _plain(block).strip() == "20" + assert _json(block) == {"key": "tx_power", "value": "20", "type": "int"} + + +def test_an_acknowledgement_prints_nothing_and_is_still_a_document() -> None: + """Printing nothing is an answer a person can act on and a program cannot. + + ``config advert`` says everything it has to say in its exit status, and that is the + right plain answer. A caller that needs to log *what was sent* has nowhere to read it, + which is what the document is for. + """ + block = Facts( + key="advert", + fields=(fields.flag("sent", "sent"), fields.flag("flood", "flood")), + values={"sent": True, "flood": False}, + shape=SILENT, + ) + assert _plain(block) == "" + assert _json(block) == {"sent": True, "flood": False} + + +# -- several blocks -------------------------------------------------------------------- + + +def test_a_single_block_report_is_its_block_and_nothing_around_it() -> None: + """``meshterm contacts --json | jq '.[].node.name'`` reads what it looks like. + + There is no envelope: the report a caller needs is ``$?``, exactly as it is without + the flag, so nothing has to be reached through to get at the answer. + """ + assert isinstance(_json(_contacts([_ALICE])), list) + + +def test_several_blocks_make_one_object_with_the_facts_at_its_top_level() -> None: + """A trace is a set of facts *and* a per-hop table, and the document says so. + + The facts block is the set of facts about the one thing the command answered, so it is + the document rather than a compartment inside it; a listing needs a name and takes its + own key. + """ + facts = Facts( + key="trace", fields=(fields.flag("success", "success"),), values={"success": True} + ) + edges = Listing(key="edges", columns=(fields.integer("index", "HOP"),), rows=[{"index": 0}]) + assert _json(facts, edges) == {"success": True, "edges": [{"index": 0}]} + assert _plain(facts, edges).splitlines() == ["success yes", "", "HOP", " 0"] + + +def test_a_block_drawn_only_for_a_person_never_reaches_the_document() -> None: + """``monitor``'s closing per-node summary is derivable from the records above it. + + Emitting it as a second *shape* of line mid-stream would cost every reader a + discriminator it otherwise never needs, so the plain face keeps the aggregate and the + stream stays homogeneous. + """ + facts = Facts( + key="window", fields=(fields.integer("packets", "packets"),), values={"packets": 2} + ) + summary = Listing( + key="heard", + columns=(fields.integer("packets", "PKTS"),), + rows=[{"packets": 2}], + plain_only=True, + ) + assert "PKTS" in _plain(facts, summary) + assert _json(facts, summary) == {"packets": 2} + + +# -- the document's own rules ---------------------------------------------------------- + + +def test_a_document_is_one_compact_line_that_never_escapes_a_name() -> None: + r"""A node name in Cyrillic is a node name, not a run of ``\\uXXXX``. + + One line, so a stream and a one-shot answer are read the same way and ``jq .`` can + re-indent for a person at no cost. Nothing can un-stream a document that was + pretty-printed across four hundred lines. + """ + buffer = io.StringIO() + row = {"node": fields.NodeRef(name="Наблюдатель", hash="c3")} + block = Listing(key="n", columns=(fields.node("node"),), rows=[row]) + JsonRenderer(script.console(buffer)).render((block,)) + out = buffer.getvalue() + assert out.endswith("\n") and out.count("\n") == 1 + assert "Наблюдатель" in out + assert ", " not in out and ": " not in out + + +def test_every_time_in_a_document_is_utc_to_the_second() -> None: + """Twenty characters, always, so string comparison is time comparison. + + A local offset is a fact about the machine that ran the command rather than about the + event, and two hosts asking the same radio the same question must produce the same + document. + """ + stamped = _json(_contacts([_ALICE]))[0]["heard_at"] + assert stamped == "2026-09-07T22:22:41Z" + assert len(stamped) == 20 + + +def test_a_time_whose_offset_we_do_not_know_is_absent_on_both_faces() -> None: + """A naive datetime is not a fact, and neither face may invent an offset for it.""" + naive = {"node": None, "heard_at": datetime(2026, 9, 7, 22, 22, 41), "packets": None} + assert "2026" not in _plain(_contacts([naive])) + assert _json(_contacts([naive]))[0]["heard_at"] is None + + +def test_a_concept_may_have_a_face_on_only_one_side() -> None: + """Both directions, and each has a real call site. + + A preference's DESCRIPTION is prose for whoever is choosing a value and carries + nothing a program would branch on; a setting's declared type is the reverse — a fact + the document wants and a reader dumping ``config show`` does not. + """ + block = Listing( + key="prefs", + columns=( + fields.word("key", "PREFERENCE"), + fields.note("help", "DESCRIPTION"), + fields.hidden("type"), + ), + rows=[{"key": "trace_cooldown_s", "help": "Wait this long", "type": "int"}], + ) + assert "Wait this long" in _plain(block) + assert _json(block) == [{"key": "trace_cooldown_s", "type": "int"}] + + +# -- streams --------------------------------------------------------------------------- + + +def _stream_listing() -> Listing: + """A live listing in the shape ``monitor`` uses: pinned lanes, the name last.""" + return Listing( + key="observations", + columns=( + fields.instant("observed_at", "TIME"), + fields.node("node", lanes=(("hash", "NODE"), ("name", "NAME"))), + ), + order=("TIME", "NODE", "NAME"), + ) + + +def test_a_stream_pins_its_lanes_because_the_widths_arrive_with_the_data() -> None: + """A live capture has no "once every record is in", which is when columns are sized. + + Both streams used to be gutter-joined with no alignment at all, which is why a name in + one still carried its quotes — nothing else said where the field ended. + """ + buffer = io.StringIO() + listing = _stream_listing() + with PlainRenderer(script.console(buffer)).stream(listing) as row: + row({"observed_at": _WHEN, "node": fields.NodeRef(name="Alice", hash="d4e5f6a7")}) + row({"observed_at": _WHEN, "node": fields.NodeRef(name="A Very Long Node Name", hash="c3")}) + header, first, second = buffer.getvalue().splitlines() + assert header.split() == ["TIME", "NODE", "NAME"] + assert first.index("d4e5f6a7") == second.index("c3") + + +def test_a_streamed_document_is_one_record_per_line_all_the_same_shape() -> None: + """A consumer reads line by line and never has to ask which kind of record it holds.""" + buffer = io.StringIO() + listing = _stream_listing() + with JsonRenderer(script.console(buffer)).stream(listing) as row: + row({"observed_at": _WHEN, "node": fields.NodeRef(hash="d4")}) + row({"observed_at": _WHEN, "node": fields.NodeRef(hash="a1")}) + documents = [json.loads(line) for line in buffer.getvalue().splitlines()] + assert [set(d) for d in documents] == [{"observed_at", "node"}] * 2 + assert [d["node"]["hash"] for d in documents] == ["d4", "a1"] + + +# -- the boundary ---------------------------------------------------------------------- + + +def test_the_format_picks_the_renderer_and_nothing_else_does() -> None: + """One choice, made once, at the one place that knows what the caller asked for.""" + console = script.console(io.StringIO()) + assert isinstance(for_format(OutputFormat.PLAIN, console), PlainRenderer) + assert isinstance(for_format(OutputFormat.JSON, console), JsonRenderer) + + +def test_a_tool_with_no_scripted_face_renders_nothing_at_all() -> None: + """The map and the dashboard state no report, and both renderers must be fine with it.""" + assert _plain() == "" + buffer = io.StringIO() + JsonRenderer(script.console(buffer)).render(None) + assert buffer.getvalue() == "" + + +def test_a_lane_and_a_column_are_separable_so_a_third_format_needs_neither() -> None: + """The point of the split, stated as a test: a format is a function of the typed row. + + A renderer that wanted CSV would read the same columns and the same rows and write its + own cells. Nothing about the report knows a gutter, a comma or a brace. + """ + column = Column(key="n", lanes=(Lane(header="N", render=lambda v: f"<{v}>"),)) + assert column.lanes[0].render(3) == "<3>" + assert column.json(3) == 3