Files
MeshTerm/meshterm/tools/base.py
T
Jean-Pierre MartineauandClaude Opus 5 da05dd402f Give the CLI its own voice, meant for a pipe rather than an eye
The CLI had grown the menu's manners -- colour, boxes, section headings,
glyph columns, a closing check mark -- and every one of them is in the way
of the thing it is actually for. It now prints like a standard Unix
utility: plain text, no escape sequences at all, no frames, one record per
line, and nothing wrapped, so a long line runs off the right instead of
folding its fields onto a second one.

meshterm/ui/script.py is the whole vocabulary. Listings are an uppercase
header and space-aligned records; key/value blocks are sysctl's shape, and
a `get` prints the bare value alone. Names are quoted wherever they share a
line, because a name can hold a space or a comma and a bare one is not a
field. A route reads "Origin" (3d),"Relay" (f2),"Us" (a1) -- the hash
outside the quotes, our own node a hop like any other rather than a star,
since the hash is what carries the identity that colour carries on screen.
Times are absolute local ISO-8601 and "-" is the one token for absent.

The return value is now half the report: 0 ok, 1 failure, 2 usage, 3 no
device, 4 the device was reached and the operation failed, 5 nothing to
report. That last one is the point -- a command that ran fine and found
nothing prints nothing and says so in $?, so a script never has to count
output lines to tell an empty mesh from a full one. Errors and progress
moved to stderr, and an expected failure no longer arrives as a traceback.

Two things lose their scripted face rather than get a degraded one. The map
is a picture whose nodes are told apart by colour: monochrome it would be
unreadable, coloured it could not be piped anywhere useful, and the nodes
themselves are still in `contacts`. The QR codes are a second rendering of
a link the output already prints.

ui.ack joins ui.note to draw the line the change needed: a note is output,
an acknowledgement is reassurance a person wants and a script must filter
out, so the menu prints it and the CLI drops it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-08 00:52:48 -04:00

261 lines
10 KiB
Python

"""The tool plugin contract and registry.
A *tool* is one menu option / CLI subcommand. Subclass :class:`Tool`, decorate it with
:func:`register`, and implement :meth:`Tool.run`. The same registry drives both the
interactive menu and the Typer CLI, and :meth:`Tool.execute` wraps every invocation in a
logged ``runs`` row, so new tools get persistence and logging for free.
"""
from __future__ import annotations
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any
from ..core import exitcodes
if TYPE_CHECKING: # avoid importing typer/context at module load for fast startup
import typer
from ..context import AppContext
@dataclass(slots=True)
class ToolResult:
"""The outcome of a tool execution.
Attributes:
summary: JSON-serializable summary persisted to the run record.
message: Optional human-readable closing message. The *menu's* closing line — a
scripted run does not print it (see
:func:`~meshterm.cli._execute_and_render`), because on the command line it
restates the output above it and the exit status below it.
artifacts: Paths to any files produced (e.g. generated visualizations).
exit_code: The status a scripted run should exit with — see
:mod:`meshterm.core.exitcodes`. Left at ``OK`` by everything that worked;
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.
"""
summary: dict[str, Any] = field(default_factory=dict)
message: str | None = None
artifacts: list[str] = field(default_factory=list)
exit_code: int = exitcodes.OK
class Tool(ABC):
"""Base class for all MeshTerm features.
Class Attributes:
name: CLI identifier (kebab-case), unique across tools.
title: Display name shown as the interactive menu item and on the tool's result
window. Capitalized, and kept identical to the screen the item opens so the
menu never promises one name and delivers another. Falls back to ``name``.
help: One-line description shown in the menu and ``--help`` (no trailing period).
icon: Emoji drawn before the title in the interactive menu (and only there — the
result window keeps the plain title). Single-codepoint, emoji-presentation
glyphs only, so the two-cell width holds across terminals (see
:mod:`meshterm.ui.tui.emoji_width`).
category: Grouping label used to organize the interactive menu.
order: Sort key within a category (lower sorts first).
menu_visible: Whether the tool appears in the interactive menu. Set ``False`` for
CLI-only tools (e.g. startup-time diagnostics with no place in a connected
session); such tools still register a CLI subcommand as usual.
popup: Whether the menu stays pushed while this tool runs, so the tool's prompts
and result float over it as modal popups (the quit-dialog pattern) instead of
replacing the screen. For quick dialog-sized tools; a tool that pushes its
own full screen keeps the default.
"""
name: str = ""
title: str = ""
help: str = ""
icon: str = ""
category: str = "General"
order: int = 100
menu_visible: bool = True
popup: bool = False
@abstractmethod
async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
"""Execute the tool's work.
Args:
ctx: Shared application context (console, device, repository, ...).
params: Validated parameters for this invocation.
Returns:
A :class:`ToolResult` describing the outcome.
"""
async def prompt_params(self, ctx: AppContext) -> dict[str, Any]:
"""Interactively gather parameters for the menu.
The default implementation requires no parameters. Tools override this to ask
the user via ``questionary``.
Args:
ctx: Shared application context.
Returns:
A parameter dict compatible with :meth:`run`.
"""
return {}
def register_cli(self, app: typer.Typer) -> None:
"""Register this tool as a Typer subcommand.
The default registers a no-argument command. Tools with parameters override this
to declare typed options, then delegate to :meth:`execute`.
Args:
app: The Typer application to add the command to.
"""
from ..cli import run_tool_command
@app.command(name=self.name, help=self.help)
def _command() -> None:
run_tool_command(self, {})
async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
"""Run the tool wrapped in run-logging and error capture.
Opens a ``runs`` row before execution and closes it with the final status and
summary afterward, regardless of success.
Args:
ctx: Shared application context.
params: Parameters for this invocation.
Returns:
The :class:`ToolResult` from :meth:`run`.
Raises:
Exception: Re-raises any error from :meth:`run` after recording it.
"""
import typer
from ..core.connection import DeviceCommandError, is_connection_lost
from ..core.device_config import DeviceConfigError
from ..core.preferences import PreferenceError
from ..core.selection import DeviceSelectionError
run_id = ctx.repo.start_run(self.name, params, ctx.profile_name)
ctx.log.debug("run %s start: tool=%s params=%s", run_id, self.name, params)
try:
result = await self.run(ctx, {**params, "_run_id": run_id})
except (
DeviceSelectionError,
DeviceConfigError,
DeviceCommandError,
PreferenceError,
# A tool rejecting one of its own arguments (an unresolvable `--to`) raises
# what the parser would have. It is a usage error, not a fault.
typer.BadParameter,
typer.Abort,
typer.Exit,
) as exc:
# Expected user-facing condition (no/ambiguous device, a bad config or
# preference value, a bad argument, or a transient command failure): record it
# but don't dump a traceback; callers print the message cleanly.
ctx.repo.finish_run(run_id, "error", {"error": str(exc)})
ctx.log.debug("run %s aborted: %s", run_id, exc)
raise
except Exception as exc: # noqa: BLE001 - we record then re-raise
ctx.repo.finish_run(run_id, "error", {"error": str(exc)})
if is_connection_lost(exc):
# The radio was unplugged or powered off mid-command. Every layer above
# already knows how to say that in one line; a stack of serial internals
# describes how the driver found out, which is not the same question.
ctx.log.warning("run %s lost the device connection: %s", run_id, exc)
else:
ctx.log.exception("run %s failed: %s", run_id, exc)
raise
ctx.repo.finish_run(run_id, "ok", result.summary)
ctx.log.debug("run %s ok", run_id)
return result
_REGISTRY: dict[str, Tool] = {}
#: Explicit menu ordering for tool categories. The menu asks "What would you like to
#: do?", so its sections answer that: each names a *doing*, not a subject, and holds
#: everything that shares it. Message leads (the everyday features, plus the book you
#: pick a recipient from), then Watch (what the mesh is doing, what it did, what to be
#: told about), Explore (where the nodes are, how they reach each other, and the boards
#: that score the walking), then the two scopes a setting can belong to — This node, the
#: radio in your hand, and Other nodes, someone else's over the mesh.
#:
#: This app closes the list as the third and last *scope*, after the radio in your hand and
#: someone else's over the mesh: the program in front of you. It holds the one thing that
#: changes how MeshTerm behaves (Preferences) and the four pages that say what MeshTerm is
#: — questions none of the doings above can hold, and which nothing on the mesh can answer.
#: It sits last because a reader who has run out of things to do is who goes looking for it.
#: Categories not listed here sort last, alphabetically, so a new category still appears.
_CATEGORY_ORDER = [
"Message",
"Watch",
"Explore",
"This node",
"Other nodes",
"This app",
]
def _category_rank(category: str) -> int:
"""Return a category's sort rank (its position in ``_CATEGORY_ORDER``, else last)."""
try:
return _CATEGORY_ORDER.index(category)
except ValueError:
return len(_CATEGORY_ORDER)
def register(cls: type[Tool]) -> type[Tool]:
"""Class decorator that instantiates a tool and adds it to the registry.
Args:
cls: The :class:`Tool` subclass to register.
Returns:
The unchanged class (so the decorator is transparent).
Raises:
ValueError: If the tool has no ``name`` or the name is already registered.
"""
instance = cls()
if not instance.name:
raise ValueError(f"{cls.__name__} must define a non-empty 'name'.")
if instance.name in _REGISTRY:
raise ValueError(f"Duplicate tool name: {instance.name!r}")
_REGISTRY[instance.name] = instance
return cls
def all_tools() -> list[Tool]:
"""Return all registered tools sorted by category rank, then order, then name.
Categories are ordered by :data:`_CATEGORY_ORDER` (Mesh first), so the first-class
Chat and Channels tools lead the menu; within a category, ``order`` then ``name`` break
ties.
Returns:
The registered tool instances in stable menu order.
"""
return sorted(
_REGISTRY.values(),
key=lambda t: (_category_rank(t.category), t.category, t.order, t.name),
)
def get_tool(name: str) -> Tool | None:
"""Look up a registered tool by name.
Args:
name: The tool's ``name``.
Returns:
The tool instance, or ``None`` if not registered.
"""
return _REGISTRY.get(name)