From b76a93808f07e7ed097d34e9e047d00122d3e277 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Tue, 8 Sep 2026 05:03:17 -0400 Subject: [PATCH] Three more arguments that were reported as the radio's fault MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `4` promises a caller that the node answered and a retry is worth trying. An unknown admin node, an unknown courier contact and an `--at` that is not a clock time are all decided before a word goes over the air, so a caller retrying on `4` would retransmit nothing, forever. `tx-optimize` had already answered the identical question the identical way for a missing password; these had not caught up. A refused admin login stays `4`. The node was reached and answered no, the password may simply have changed, and that is exactly the case a retry exists for — the line is whether anything was transmitted, not whether the command worked. The manual documented the old behaviour and called the inconsistency out; it now documents the rule instead. Co-Authored-By: Claude Opus 5 (1M context) --- docs/cli.md | 10 ++++++---- meshterm/tools/courier.py | 9 +++++---- meshterm/tools/repeater_admin.py | 8 ++++++-- tests/test_cli_contract.py | 32 ++++++++++++++++++++++++++++++++ 4 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index d5cd4af..ec460b7 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1186,8 +1186,9 @@ of `delivered`, `no ack`, `gave up`, `unknown contact`, `busy`, `gone` — kept spaces and all, so the two faces say the same word. `list` returns `5` on an empty outbox; `cancel` and `clear` return `5` when there was -nothing to act on. A contact the device does not know is a **device error** (`4`), not a -usage one. +nothing to act on. A contact the device does not know, a contact with no key to address, +and an `--at` that is not a clock time are all **usage errors** (`2`): the argument is +wrong, nothing was queued, and nothing went out over the air. --- @@ -1365,8 +1366,9 @@ landed), but there is nothing to report, so it returns `5`. Logging in happens automatically from the remembered password; run the interactive flow once to store one, or pass `--password`. A refused login clears the saved password and -fails with `4`. **An absent password also fails with `4` here**, where `tx-optimize` calls -the same condition a usage error — worth knowing if you branch on the status. +fails with `4` — the node answered, and answered no. An **absent** password, and a node +name no contact matches, are usage errors (`2`): nothing was transmitted in either case, +which is the line `3` and `4` are drawn on. **`--json`:** diff --git a/meshterm/tools/courier.py b/meshterm/tools/courier.py index b07bddc..4320253 100644 --- a/meshterm/tools/courier.py +++ b/meshterm/tools/courier.py @@ -23,7 +23,6 @@ import typer from ..context import AppContext from ..core import exitcodes -from ..core.connection import DeviceCommandError from .base import Tool, ToolResult, register if TYPE_CHECKING: # pragma: no cover - typing only @@ -102,17 +101,19 @@ class CourierTool(Tool): name = str(params["contact"]) needle = name.casefold() contact = next((c for c in contacts if c.name.casefold() == needle), None) + # The named contact, not the radio: nothing is queued and nothing is sent, so + # these are bad arguments (2) rather than device failures (4). if contact is None: - raise DeviceCommandError(f"unknown contact: {name!r}") + raise typer.BadParameter(f"unknown contact: {name!r}") key = contact_watch_key(contact) if key is None: - raise DeviceCommandError(f"{name!r} has no usable key to address") + raise typer.BadParameter(f"{name!r} has no usable key to address") not_before = None if params.get("at"): not_before = parse_clock(str(params["at"])) if not_before is None: - raise DeviceCommandError( + raise typer.BadParameter( f"--at wants a clock time like 07:00, not {params['at']!r}" ) message = ctx.courier_store.queue( diff --git a/meshterm/tools/repeater_admin.py b/meshterm/tools/repeater_admin.py index 8b9299e..53c1b56 100644 --- a/meshterm/tools/repeater_admin.py +++ b/meshterm/tools/repeater_admin.py @@ -71,12 +71,16 @@ class RepeaterAdminTool(Tool): contacts = await device.get_contacts() name = str(params["node"]) node = next((c for c in contacts if c.name == name), None) + # Both of these are the *argument* being wrong, and nothing has gone out over + # the air when either fires — so they are usage errors (2), not device failures + # (4), whose promise to a caller is that a retry is worth trying. `tx-optimize` + # already answered the identical question this way for the identical condition. if node is None: - raise DeviceCommandError(f"unknown contact: {name!r}") + raise typer.BadParameter(f"unknown contact: {name!r}") password = params.get("password") or ctx.admin_store.get(node) if not password: - raise DeviceCommandError( + raise typer.BadParameter( f"no admin password for {name!r}; pass --password or run the " "interactive flow once to store it." ) diff --git a/tests/test_cli_contract.py b/tests/test_cli_contract.py index a065eee..b430e62 100644 --- a/tests/test_cli_contract.py +++ b/tests/test_cli_contract.py @@ -556,6 +556,38 @@ def test_a_port_that_will_not_open_is_no_device_not_a_device_failure(run) -> Non assert "lost" not in result.stderr +@pytest.mark.parametrize( + "args", + [ + ("repeater-admin", "Nobody", "get", "name"), + ("courier", "queue", "Nobody", "hi"), + ("courier", "queue", "Alice", "hi", "--at", "25:99"), + ], + ids=["unknown-admin-node", "unknown-courier-contact", "bad-at-time"], +) +def test_a_bad_argument_is_never_reported_as_a_device_failure(run, args) -> None: # noqa: ANN001 + """``4`` promises a caller that the radio answered and a retry is worth trying. + + Each of these is the *argument* being wrong, decided before a word goes over the air — + so a caller that retried on ``4`` would retransmit nothing, forever. ``tx-optimize`` + already answered the identical question the identical way for a missing password; + these three were the ones that had not caught up. + """ + result = run(*args) + assert result.exit_code == exitcodes.USAGE, result.output + assert result.stdout == "" + + +def test_a_node_that_answers_no_is_still_a_device_failure(run) -> None: # noqa: ANN001 + """The other side of the line: the radio was reached, so a retry is a real option. + + A refused admin login is not a bad argument — the password may simply have changed — + and reclassifying the arguments above must not drag this one along with them. + """ + result = run("repeater-admin", "Yagi-Repeater", "get", "name", "--password", "wrongpw") + assert result.exit_code == exitcodes.DEVICE, result.output + + def test_an_empty_result_writes_nothing_to_stdout_at_all(run) -> None: # noqa: ANN001 """Not a "no channels configured" line: the status carries it, so the pipe stays clean.""" result = run("channels", "list")