meshcorectl 0.1.0__py3-none-any.whl

meshcorectl/__init__.py

@@ -0,0 +1,3 @@
+"""meshcorectl: a kubectl-style CLI for MeshCore companion radios."""
+
+__version__ = "0.1.0"

meshcorectl/__main__.py

@@ -0,0 +1,6 @@
+"""Allows `python -m meshcorectl` to behave like the `meshcorectl` console script."""
+
+from meshcorectl.cli import main
+
+if __name__ == "__main__":  # pragma: no cover - identical to cli.py's own entry-point guard
+    main()

meshcorectl/cli.py

@@ -0,0 +1,243 @@
+"""The root Click group: global flags, logging setup, and `CliState`.
+
+Every command module receives `CliState` via `@click.pass_obj` and uses
+`state.resolve_context()` / `state.connect()` to reach a device — command
+code never touches `ContextStore` or `connect.connect()` directly, which is
+what keeps `tests/commands/*` fast: inject a fake `MeshCoreConnection`
+instead of calling `state.connect()`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import sys
+from collections.abc import AsyncIterator, Callable, Coroutine
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypeVar
+
+import click
+
+from . import __version__, resource_specs  # noqa: F401 - import registers resource specs
+from .commands.advert import advert_command
+from .commands.completion import completion_command
+from .commands.config_cmd import config_group
+from .commands.create import create_group
+from .commands.delete import delete_group
+from .commands.describe import describe_group
+from .commands.exec_ import exec_command
+from .commands.get import get_group
+from .commands.login import login_command, logout_command
+from .commands.logs import logs_command
+from .commands.reboot import reboot_command
+from .commands.scan import scan_command
+from .commands.send import send_group
+from .commands.set_ import set_group
+from .commands.top import top_group
+from .commands.trace import trace_command
+from .commands.version import version_command
+from .connect import ConnectError, MeshCoreConnection, connect
+from .context_store import Context, ContextStore
+from .mesh_data import MeshDataError
+from .output import OutputFormat
+
+DEFAULT_TIMEOUT = 10.0
+
+_T = TypeVar("_T")
+
+
+@dataclass
+class CliState:
+    """Resolved global options + the context store, threaded through every command."""
+
+    store: ContextStore
+    context_override: str | None
+    output: OutputFormat
+    timeout_override: float | None
+    verbosity: int
+
+    def resolve_context(self) -> Context:
+        """The `Context` a command should use: `--context` override, else
+        the store's `current-context`.
+
+        Raises `click.ClickException` (not a raw store exception) since
+        this is always called from inside a command and the message is
+        meant to reach the user as-is.
+        """
+        name = self.context_override
+        if name is None:
+            cfg = self.store.load()
+            name = cfg.current_context
+        if name is None:
+            raise click.ClickException(
+                "no context specified: pass --context NAME or run "
+                "'meshcorectl config use-context NAME' "
+                "(see 'meshcorectl config set-context --help' to create one)"
+            )
+        try:
+            return self.store.get_context(name)
+        except Exception as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    def effective_timeout(self, context: Context) -> float:
+        """Precedence: `--timeout` flag > the context's own timeout > the
+        config file's `defaults.timeout` > `DEFAULT_TIMEOUT`."""
+        if self.timeout_override is not None:
+            return self.timeout_override
+        if context.timeout is not None:
+            return context.timeout
+        configured = self.store.load().defaults.get("timeout")
+        return float(configured) if configured is not None else DEFAULT_TIMEOUT
+
+    async def connect(self) -> MeshCoreConnection:
+        """Resolve the current context and open a live connection to it."""
+        context = self.resolve_context()
+        return await connect(
+            context.connection,
+            timeout=self.effective_timeout(context),
+            debug=self.verbosity >= 2,
+        )
+
+    def run_async(self, coro: Coroutine[Any, Any, _T]) -> _T:
+        """Convenience for commands: `state.run_async(state.connect())`."""
+        return asyncio.run(coro)
+
+    @asynccontextmanager
+    async def connected(self) -> AsyncIterator[MeshCoreConnection]:
+        """`async with state.connected() as conn:` -- connect, yield, always
+        disconnect, even if the command body raises."""
+        connection = await self.connect()
+        try:
+            yield connection
+        finally:
+            await connection.disconnect()
+
+    def run_command(self, coro: Coroutine[Any, Any, _T]) -> _T:
+        """Run `coro` (typically built around `async with state.connected()`),
+        translating connection/device failures into the one
+        `click.ClickException` every command surfaces -- never a raw
+        traceback from `connect.ConnectError`/`mesh_data.MeshDataError`."""
+        try:
+            return self.run_async(coro)
+        except (ConnectError, MeshDataError) as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    def call(self, fn: Callable[[MeshCoreConnection], Coroutine[Any, Any, _T]]) -> _T:
+        """The one-liner most read/write commands use: connect, call
+        `fn(connection)`, disconnect, translate errors -- e.g.
+        `state.call(fetch_contacts)`, or `state.call(lambda conn:
+        fetch_telemetry(conn, contact))` for a call needing extra args."""
+
+        async def run() -> _T:
+            async with self.connected() as connection:
+                return await fn(connection)
+
+        return self.run_command(run())
+
+
+def _configure_logging(verbosity: int) -> None:
+    level = logging.WARNING
+    if verbosity == 1:
+        level = logging.INFO
+    elif verbosity >= 2:
+        level = logging.DEBUG
+    logging.basicConfig(level=level, format="%(levelname)s:%(name)s:%(message)s", force=True)
+
+
+@click.group(name="meshcorectl")
+@click.option(
+    "--context",
+    "context_override",
+    default=None,
+    metavar="NAME",
+    help="Connection context to use (overrides the current context).",
+)
+@click.option(
+    "-o",
+    "--output",
+    "output_str",
+    type=click.Choice([f.value for f in OutputFormat]),
+    default=OutputFormat.TABLE.value,
+    show_default=True,
+    help="Output format.",
+)
+@click.option(
+    "--timeout",
+    "timeout_override",
+    type=float,
+    default=None,
+    metavar="SECONDS",
+    help="Per-command timeout (overrides the context/config default).",
+)
+@click.option(
+    "-v",
+    "--verbose",
+    "verbosity",
+    count=True,
+    help=(
+        "Increase logging verbosity (-v for info, -vv for debug). Login "
+        "passwords, device PINs, and message text are kept out of the "
+        "debug log."
+    ),
+)
+@click.option(
+    "--config",
+    "config_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    metavar="PATH",
+    help="Path to the meshcorectl config file (default: ~/.config/meshcorectl/config.yaml).",
+)
+@click.version_option(version=__version__, prog_name="meshcorectl")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    context_override: str | None,
+    output_str: str,
+    timeout_override: float | None,
+    verbosity: int,
+    config_path: Path | None,
+) -> None:
+    """meshcorectl: a kubectl-style CLI for MeshCore companion radios."""
+    _configure_logging(verbosity)
+    ctx.obj = CliState(
+        store=ContextStore(config_path),
+        context_override=context_override,
+        output=OutputFormat(output_str),
+        timeout_override=timeout_override,
+        verbosity=verbosity,
+    )
+
+
+cli.add_command(config_group)
+cli.add_command(get_group)
+cli.add_command(describe_group)
+cli.add_command(create_group)
+cli.add_command(delete_group)
+cli.add_command(send_group)
+cli.add_command(exec_command)
+cli.add_command(login_command)
+cli.add_command(logout_command)
+cli.add_command(top_group)
+cli.add_command(logs_command)
+cli.add_command(trace_command)
+cli.add_command(advert_command)
+cli.add_command(reboot_command)
+cli.add_command(set_group)
+cli.add_command(scan_command)
+cli.add_command(version_command)
+cli.add_command(completion_command)
+
+
+def main() -> None:
+    try:
+        cli(prog_name="meshcorectl")
+    except KeyboardInterrupt:
+        click.echo("aborted", err=True)
+        sys.exit(130)
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised via the console-script entry point
+    main()

meshcorectl/commands/__init__.py

@@ -0,0 +1 @@
+"""Click command groups, one module per verb."""

meshcorectl/commands/advert.py

@@ -0,0 +1,33 @@
+"""`meshcorectl advert` -- send an advertisement packet."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import send_advert
+from ..output import output_option, render_result, resolve_output
+
+
+@click.command(name="advert")
+@click.option(
+    "--flood", is_flag=True, help="Flood the advert instead of sending a normal (zero-hop) one."
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be sent without sending it.")
+@output_option
+@click.pass_obj
+def advert_command(state: Any, flood: bool, dry_run: bool, output_override: str | None) -> None:
+    """Send an advertisement packet announcing this device."""
+    if dry_run:
+        click.echo(f"would send{' a flood' if flood else ''} advert (dry run)")
+        return
+
+    async def run(connection: MeshCoreConnection) -> None:
+        await send_advert(connection, flood=flood)
+
+    state.call(run)
+    text = "advert sent" + (" (flood)" if flood else "")
+    fmt = resolve_output(state.output, output_override)
+    click.echo(render_result({"sent": True, "flood": flood}, fmt, text))

meshcorectl/commands/completion.py

@@ -0,0 +1,40 @@
+"""`meshcorectl completion` -- print a shell completion script.
+
+Exposes Click's built-in completion support as a discoverable subcommand
+(like `kubectl completion`/`gh completion`) instead of requiring the
+`_MESHCORECTL_COMPLETE=bash_source` env-var convention.
+"""
+
+from __future__ import annotations
+
+import click
+from click.shell_completion import get_completion_class
+
+SHELLS = ("bash", "zsh", "fish")
+
+
+@click.command(name="completion")
+@click.argument("shell", type=click.Choice(SHELLS))
+@click.pass_context
+def completion_command(ctx: click.Context, shell: str) -> None:
+    """Print a shell completion script for SHELL.
+
+    \b
+    Load it for the current session:
+      bash:  source <(meshcorectl completion bash)
+      zsh:   source <(meshcorectl completion zsh)
+      fish:  meshcorectl completion fish | source
+
+    \b
+    Or install it permanently, e.g. for bash:
+      meshcorectl completion bash > ~/.local/share/bash-completion/completions/meshcorectl
+    """
+    completion_class = get_completion_class(shell)
+    if completion_class is None:  # pragma: no cover - click.Choice already restricts `shell`
+        raise click.ClickException(f"unsupported shell {shell!r}")
+
+    root = ctx.find_root()
+    prog_name = root.info_name or "meshcorectl"
+    complete_var = f"_{prog_name.upper().replace('-', '_')}_COMPLETE"
+    complete = completion_class(root.command, {}, prog_name, complete_var)
+    click.echo(complete.source())

meshcorectl/commands/config_cmd.py

@@ -0,0 +1,186 @@
+"""`meshcorectl config` — manage named connection contexts.
+
+Deliberately mirrors `kubectl config`: `get-contexts`, `current-context`,
+`use-context`, `set-context`, `delete-context`, `view`.
+"""
+
+from __future__ import annotations
+
+import json
+
+import click
+import yaml
+
+from ..context_store import ConnectionSpec, ContextNotFoundError
+from ..output import OutputFormat, output_option, resolve_output
+from ..output.table import format_table
+
+
+@click.group(name="config")
+def config_group() -> None:
+    """Manage connection contexts (BLE/serial/TCP device profiles)."""
+
+
+@config_group.command("get-contexts")
+@click.pass_obj
+def get_contexts(state) -> None:
+    """List all configured contexts."""
+    cfg = state.store.load()
+    if not cfg.contexts:
+        click.echo(
+            "No contexts defined. Create one with 'meshcorectl config set-context'.", err=True
+        )
+        return
+    rows = [
+        {
+            "current": "*" if name == cfg.current_context else "",
+            "name": name,
+            "connection": context.connection.summary(),
+            "timeout": context.timeout if context.timeout is not None else "",
+        }
+        for name, context in sorted(cfg.contexts.items())
+    ]
+    click.echo(
+        format_table(
+            rows,
+            [
+                ("CURRENT", "current"),
+                ("NAME", "name"),
+                ("CONNECTION", "connection"),
+                ("TIMEOUT", "timeout"),
+            ],
+        )
+    )
+
+
+@config_group.command("current-context")
+@click.pass_obj
+def current_context(state) -> None:
+    """Print the name of the current context."""
+    cfg = state.store.load()
+    if not cfg.current_context:
+        raise click.ClickException("current-context is not set")
+    click.echo(cfg.current_context)
+
+
+@config_group.command("use-context")
+@click.argument("name")
+@click.pass_obj
+def use_context(state, name: str) -> None:
+    """Set the current context to NAME."""
+    try:
+        state.store.use_context(name)
+    except ContextNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f'switched to context "{name}"')
+
+
+@config_group.command("set-context")
+@click.argument("name")
+@click.option(
+    "--ble-address", default=None, metavar="ADDR", help="BLE MAC address (or UUID on macOS)."
+)
+@click.option(
+    "--ble-name",
+    "ble_name_filter",
+    default=None,
+    metavar="SUBSTRING",
+    help="Match a substring of the device's advertised BLE name, when the address isn't known.",
+)
+@click.option(
+    "--serial-port", default=None, metavar="PATH", help="Serial device, e.g. /dev/ttyUSB0."
+)
+@click.option("--serial-baudrate", default=115200, show_default=True, type=int)
+@click.option(
+    "--tcp-host", default=None, metavar="HOST", help="Hostname/IP of a TCP-exposed radio."
+)
+@click.option("--tcp-port", default=5000, show_default=True, type=int)
+@click.option(
+    "--timeout",
+    "context_timeout",
+    type=float,
+    default=None,
+    metavar="SECONDS",
+    help="Default per-command timeout for this context.",
+)
+@click.option(
+    "--current/--no-current",
+    "set_current",
+    default=False,
+    help="Also make this the current context (the first context you create always becomes "
+    "current).",
+)
+@click.pass_obj
+def set_context(
+    state,
+    name: str,
+    ble_address: str | None,
+    ble_name_filter: str | None,
+    serial_port: str | None,
+    serial_baudrate: int,
+    tcp_host: str | None,
+    tcp_port: int,
+    context_timeout: float | None,
+    set_current: bool,
+) -> None:
+    """Create or update a connection context named NAME."""
+    kinds_given = {
+        "ble": ble_address is not None or ble_name_filter is not None,
+        "serial": serial_port is not None,
+        "tcp": tcp_host is not None,
+    }
+    selected = [kind for kind, given in kinds_given.items() if given]
+    if len(selected) > 1:
+        raise click.ClickException(
+            f"conflicting connection flags for: {', '.join(selected)} "
+            "(a context can only use one of --ble-*, --serial-*, or --tcp-*)"
+        )
+    if not selected:
+        raise click.ClickException(
+            "no connection specified: pass --ble-address/--ble-name, --serial-port, or --tcp-host"
+        )
+
+    kind = selected[0]
+    if kind == "ble":
+        connection = ConnectionSpec(kind="ble", address=ble_address, name_filter=ble_name_filter)
+    elif kind == "serial":
+        connection = ConnectionSpec(kind="serial", port=serial_port, baudrate=serial_baudrate)
+    else:
+        connection = ConnectionSpec(kind="tcp", host=tcp_host, tcp_port=tcp_port)
+
+    state.store.set_context(
+        name, connection=connection, timeout=context_timeout, set_current=set_current
+    )
+    now_current = set_current or state.store.load().current_context == name
+    click.echo(f'context "{name}" set.' + (" (current)" if now_current else ""))
+
+
+@config_group.command("delete-context")
+@click.argument("name")
+@click.pass_obj
+def delete_context(state, name: str) -> None:
+    """Delete context NAME."""
+    try:
+        was_current = state.store.delete_context(name)
+    except ContextNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(f'context "{name}" deleted.')
+    if was_current:
+        click.echo(
+            "note: that was the current context; set a new one with "
+            "'meshcorectl config use-context'.",
+            err=True,
+        )
+
+
+@config_group.command("view")
+@output_option
+@click.pass_obj
+def view(state, output_override: str | None) -> None:
+    """Print the full contents of the config file."""
+    cfg = state.store.load()
+    fmt = resolve_output(state.output, output_override)
+    if fmt is OutputFormat.JSON:
+        click.echo(json.dumps(cfg.to_dict(), indent=2))
+    else:
+        click.echo(yaml.safe_dump(cfg.to_dict(), sort_keys=False), nl=False)

meshcorectl/commands/create.py

@@ -0,0 +1,65 @@
+"""`meshcorectl create` -- import a contact card, or define a channel."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import create_channel, import_contact
+from ..output import output_option, render, render_result, resolve_output
+
+
+@click.group(name="create")
+def create_group() -> None:
+    """Create a resource: import a contact, or define a channel."""
+
+
+@create_group.command("contact")
+@click.option("--uri", required=True, metavar="URI", help="A meshcore:// contact card URI.")
+@click.option("--dry-run", is_flag=True, help="Show what would be imported without doing it.")
+@output_option
+@click.pass_obj
+def create_contact(state: Any, uri: str, dry_run: bool, output_override: str | None) -> None:
+    """Import a contact from its meshcore:// card URI."""
+    if dry_run:
+        click.echo(f"would import contact from {uri} (dry run)")
+        return
+    state.call(lambda conn: import_contact(conn, uri))
+    result = {"imported": True, "uri": uri}
+    fmt = resolve_output(state.output, output_override)
+    click.echo(render_result(result, fmt, f"contact imported from {uri}"))
+
+
+@create_group.command("channel")
+@click.argument("index", type=int)
+@click.argument("name")
+@click.argument("key", required=False, metavar="[KEY]")
+@click.option("--dry-run", is_flag=True, help="Show what would be created without doing it.")
+@output_option
+@click.pass_obj
+def create_channel_command(
+    state: Any, index: int, name: str, key: str | None, dry_run: bool, output_override: str | None
+) -> None:
+    """Define channel INDEX with NAME and optional 32-hex-char KEY.
+
+    When KEY is omitted: a '#'-prefixed NAME is the public-channel convention,
+    so the device derives the same secret from NAME itself -- anyone who knows
+    the name can compute it and join. For any other NAME, meshcorectl generates
+    a random secret for you (a name-derived secret would make a "private"
+    channel just as guessable as a public one).
+    """
+    generating = key is None and not name.startswith("#")
+    if dry_run:
+        suffix = " (auto-generating a random secret)" if generating else ""
+        click.echo(f"would create channel {index} named {name!r}{suffix} (dry run)")
+        return
+
+    async def run(connection: MeshCoreConnection) -> dict[str, Any]:
+        return await create_channel(connection, index, name, key)
+
+    channel = state.call(run)
+    if generating:
+        click.echo(f"Generated channel secret: {channel['secret']}", err=True)
+    click.echo(render(channel, resolve_output(state.output, output_override), kind="channel"))

meshcorectl/commands/delete.py

@@ -0,0 +1,100 @@
+"""`meshcorectl delete` -- remove a contact (by name or -l selector), or
+clear a channel slot.
+
+No `pending-contacts` subcommand: "pending" contacts are client-side
+bookkeeping accumulated over a session (see `get.py`'s `pending-contacts`,
+which watches for a window instead of reading a cache, for the same
+reason). A one-shot connection never accumulates anything across
+invocations, so there's nothing for `delete pending-contacts` to clear.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import (
+    AmbiguousMatchError,
+    delete_channel,
+    fetch_channels,
+    fetch_contacts,
+    find_channel,
+    find_contact,
+)
+from ..mesh_data import remove_contact as remove_contact_data
+from ..selectors import SelectorError, filter_contacts
+
+
+@click.group(name="delete")
+def delete_group() -> None:
+    """Delete a contact, or clear a channel slot."""
+
+
+@delete_group.command("contact")
+@click.argument("name", required=False, metavar="NAME")
+@click.option(
+    "-l",
+    "--selector",
+    "selector_text",
+    default=None,
+    metavar="SELECTOR",
+    help="Delete every contact matching this filter instead of one by name, e.g. 't=client,u>30d'.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be deleted without deleting it.")
+@click.pass_obj
+def delete_contact(state: Any, name: str | None, selector_text: str | None, dry_run: bool) -> None:
+    """Delete one contact by NAME, or every contact matching -l/--selector."""
+    if (name is None) == (selector_text is None):
+        raise click.ClickException("pass exactly one of NAME or -l/--selector")
+
+    async def run(connection: MeshCoreConnection) -> None:
+        contacts = await fetch_contacts(connection)
+        if name is not None:
+            try:
+                contact = find_contact(contacts, name)
+            except AmbiguousMatchError as exc:
+                raise click.ClickException(str(exc)) from exc
+            if contact is None:
+                raise click.ClickException(f"no contact matching {name!r}")
+            targets = [contact]
+        else:
+            try:
+                targets = filter_contacts(contacts, selector_text)
+            except SelectorError as exc:
+                raise click.ClickException(str(exc)) from exc
+            if not targets:
+                click.echo("No contacts matched.", err=True)
+                return
+
+        for target in targets:
+            if dry_run:
+                click.echo(f"contact {target['name']!r} would be deleted (dry run)")
+                continue
+            await remove_contact_data(connection, target)
+            click.echo(f"contact {target['name']!r} deleted")
+
+    state.call(run)
+
+
+@delete_group.command("channel")
+@click.argument("index_or_name", metavar="INDEX_OR_NAME")
+@click.option("--dry-run", is_flag=True, help="Show what would be deleted without deleting it.")
+@click.pass_obj
+def delete_channel_command(state: Any, index_or_name: str, dry_run: bool) -> None:
+    """Clear channel INDEX_OR_NAME (there's no true delete: the name and
+    secret are cleared instead)."""
+
+    async def run(connection: MeshCoreConnection) -> None:
+        channels = await fetch_channels(connection)
+        channel = find_channel(channels, index_or_name)
+        if channel is None:
+            raise click.ClickException(f"no channel matching {index_or_name!r}")
+        if dry_run:
+            click.echo(f"channel {channel['name']!r} would be cleared (dry run)")
+            return
+        await delete_channel(connection, channel["index"])
+        click.echo(f"channel {channel['name']!r} cleared")
+
+    state.call(run)