meshcorectl 0.1.0__py3-none-any.whl

meshcorectl/commands/describe.py

@@ -0,0 +1,86 @@
+"""`meshcorectl describe` -- verbose, human-only detail views.
+
+Mirrors a deliberate `kubectl describe` quirk: unlike `get`, `describe`
+ignores `-o`/`--output` entirely and always prints the same labeled,
+multi-line text -- there's no JSON/YAML "describe" shape, only a human one.
+For machine-readable output use `get ... -o json`/`-o yaml` instead.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+import click
+
+from ..mesh_data import AmbiguousMatchError, fetch_contacts, fetch_device, find_contact
+
+
+@click.group(name="describe")
+def describe_group() -> None:
+    """Show a detailed, human-readable view of one resource."""
+
+
+@describe_group.command("device")
+@click.pass_obj
+def describe_device(state: Any) -> None:
+    """Describe the connected device."""
+    device = state.call(fetch_device)
+    click.echo(_describe_device_text(device))
+
+
+@describe_group.command("contact")
+@click.argument("name")
+@click.pass_obj
+def describe_contact(state: Any, name: str) -> None:
+    """Describe one contact by name or public-key prefix."""
+    contacts = state.call(fetch_contacts)
+    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}")
+    click.echo(_describe_contact_text(contact))
+
+
+def _dash(value: Any) -> str:
+    return "-" if value is None or value == "" else str(value)
+
+
+def _format_epoch(epoch: Any) -> str:
+    if not epoch:
+        return "-"
+    return datetime.datetime.fromtimestamp(epoch).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _describe_device_text(device: dict[str, Any]) -> str:
+    lines = [
+        f"Name:          {_dash(device.get('name'))}",
+        f"Model:         {_dash(device.get('model'))}",
+        f"Firmware:      {_dash(device.get('ver'))} (protocol {_dash(device.get('fw ver'))})",
+        f"Build:         {_dash(device.get('fw_build'))}",
+        f"Public Key:    {_dash(device.get('public_key'))}",
+        "Radio:         "
+        f"{_dash(device.get('radio_freq'))}MHz  bw={_dash(device.get('radio_bw'))}  "
+        f"sf={_dash(device.get('radio_sf'))}  cr={_dash(device.get('radio_cr'))}",
+        f"Location:      {_dash(device.get('adv_lat'))}, {_dash(device.get('adv_lon'))}",
+        f"Max Contacts:  {_dash(device.get('max_contacts'))}",
+        f"Max Channels:  {_dash(device.get('max_channels'))}",
+        f"Repeater Mode: {'yes' if device.get('repeat') else 'no'}",
+    ]
+    return "\n".join(lines)
+
+
+def _describe_contact_text(contact: dict[str, Any]) -> str:
+    lines = [
+        f"Name:         {_dash(contact.get('name'))}",
+        f"Type:         {_dash(contact.get('type'))}",
+        f"Public Key:   {_dash(contact.get('public_key'))}",
+        f"Path:         {_dash(contact.get('path'))}",
+        f"Last Advert:  {_format_epoch(contact.get('last_advert'))}",
+        f"Last Update:  {_format_epoch(contact.get('lastmod'))}",
+        f"Flags:        {_dash(contact.get('flags'))}",
+        f"Location:     {_dash(contact.get('adv_lat'))}, {_dash(contact.get('adv_lon'))}",
+    ]
+    return "\n".join(lines)

meshcorectl/commands/exec_.py

@@ -0,0 +1,107 @@
+"""`meshcorectl exec` -- run a raw console command on a repeater/room and
+print its reply, the mesh analogue of `kubectl exec pod -- cmd`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import AmbiguousMatchError, fetch_contacts, find_contact
+from ..mesh_data import run_repeater_command as run_repeater_command_data
+from ..selectors import SelectorError, filter_contacts
+
+DEFAULT_REPLY_TIMEOUT = 8.0
+
+
+@click.command(name="exec", context_settings={"ignore_unknown_options": True})
+@click.argument("args", nargs=-1, type=click.UNPROCESSED, metavar="[REPEATER] -- CMD...")
+@click.option(
+    "-l",
+    "--selector",
+    "selector_text",
+    default=None,
+    metavar="SELECTOR",
+    help="Run on every contact matching this filter instead of one by name.",
+)
+@click.option(
+    "--timeout",
+    "reply_timeout",
+    type=float,
+    default=DEFAULT_REPLY_TIMEOUT,
+    show_default=True,
+    metavar="SECONDS",
+    help="How long to wait for the reply.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would run without running it.")
+@click.pass_obj
+def exec_command(
+    state: Any,
+    args: tuple[str, ...],
+    selector_text: str | None,
+    reply_timeout: float,
+    dry_run: bool,
+) -> None:
+    """Run a raw console command on REPEATER (or every -l/--selector match).
+
+    \b
+    Usage: meshcorectl exec REPEATER -- CMD...
+
+    REPEATER and CMD are split out of a single catch-all argument (rather
+    than two separate Click arguments) on purpose: Click fills fixed
+    positionals in declaration order regardless of `required=False`, so an
+    optional REPEATER ahead of a variadic CMD would silently steal CMD's
+    first word whenever -l/--selector was used instead. `--` is stripped by
+    Click itself wherever it appears, so it doesn't show up in `args`.
+    """
+    tokens = list(args)
+    if selector_text is None:
+        if not tokens:
+            raise click.ClickException("pass exactly one of REPEATER or -l/--selector")
+        name: str | None = tokens[0]
+        command_tokens = tokens[1:]
+    else:
+        name = None
+        command_tokens = tokens
+
+    if not command_tokens:
+        raise click.ClickException("no command given (usage: exec REPEATER -- CMD...)")
+    command_text = " ".join(command_tokens)
+
+    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
+
+        multiple = len(targets) > 1
+        for target in targets:
+            if dry_run:
+                click.echo(f"would run on {target['name']!r}: {command_text!r} (dry run)")
+                continue
+            reply = await run_repeater_command_data(
+                connection, target, command_text, timeout=reply_timeout
+            )
+            if reply is None:
+                click.echo(f"{target['name']}: (no reply within {reply_timeout}s)", err=True)
+            elif multiple:
+                click.echo(f"{target['name']}: {reply}")
+            else:
+                click.echo(reply)
+
+    state.call(run)

meshcorectl/commands/get.py

@@ -0,0 +1,183 @@
+"""`meshcorectl get` -- read resources: device, contacts, channels,
+pending-contacts, path, time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import click
+from meshcore import EventType
+
+from ..mesh_data import (
+    AmbiguousMatchError,
+    collect_events,
+    fetch_channels,
+    fetch_contacts,
+    fetch_device,
+    fetch_time,
+    find_channel,
+    find_contact,
+    normalize_contact,
+)
+from ..output import output_option, render, resolve_output
+from ..selectors import SelectorError, filter_contacts
+
+
+@click.group(name="get")
+def get_group() -> None:
+    """Get one or more resources (device, contacts, channels, ...)."""
+
+
+@get_group.command("device")
+@output_option
+@click.pass_obj
+def get_device(state: Any, output_override: str | None) -> None:
+    """Show the connected device's advertised info and firmware/protocol query."""
+    device = state.call(fetch_device)
+    click.echo(render(device, resolve_output(state.output, output_override), kind="device"))
+
+
+@get_group.command("contacts")
+@click.option(
+    "-l",
+    "--selector",
+    "selector_text",
+    default=None,
+    metavar="SELECTOR",
+    help="Only list contacts matching this filter, e.g. 't=repeater,u<2d'.",
+)
+@output_option
+@click.pass_obj
+def get_contacts(state: Any, selector_text: str | None, output_override: str | None) -> None:
+    """List every contact (client/repeater/room/sensor) known to the device."""
+    contacts = state.call(fetch_contacts)
+    if selector_text is not None:
+        # `is not None`, not truthy: an explicitly empty `-l ""` (e.g. an
+        # unset shell variable expanding to nothing) must be rejected by
+        # filter_contacts as an invalid selector, not silently treated the
+        # same as "-l wasn't passed at all" and match everything.
+        try:
+            contacts = filter_contacts(contacts, selector_text)
+        except SelectorError as exc:
+            raise click.ClickException(str(exc)) from exc
+    if not contacts:
+        click.echo("No contacts.", err=True)
+        return
+    click.echo(render(contacts, resolve_output(state.output, output_override), kind="contact"))
+
+
+@get_group.command("contact")
+@click.argument("name")
+@output_option
+@click.pass_obj
+def get_contact(state: Any, name: str, output_override: str | None) -> None:
+    """Show one contact by name or public-key prefix."""
+    contacts = state.call(fetch_contacts)
+    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}")
+    click.echo(render(contact, resolve_output(state.output, output_override), kind="contact"))
+
+
+@get_group.command("channels")
+@click.option(
+    "-A",
+    "--all",
+    "show_all",
+    is_flag=True,
+    default=False,
+    help="Include empty (unconfigured) channel slots.",
+)
+@output_option
+@click.pass_obj
+def get_channels(state: Any, show_all: bool, output_override: str | None) -> None:
+    """List every configured channel.
+
+    A device reserves a fixed number of channel slots (commonly 40) whether
+    or not they're in use; empty slots are hidden by default -- same as
+    `send channel`/`delete channel`, which never treat one as a valid
+    target. Pass --all to include them too, in every output format.
+    """
+    channels = state.call(fetch_channels)
+    if not show_all:
+        channels = [c for c in channels if c["name"]]
+    if not channels:
+        hint = "No channels configured."
+        if not show_all:
+            hint += " (pass --all to include empty slots)"
+        click.echo(hint, err=True)
+        return
+    click.echo(render(channels, resolve_output(state.output, output_override), kind="channel"))
+
+
+@get_group.command("channel")
+@click.argument("index_or_name")
+@output_option
+@click.pass_obj
+def get_channel(state: Any, index_or_name: str, output_override: str | None) -> None:
+    """Show one channel by index or name."""
+    channels = state.call(fetch_channels)
+    channel = find_channel(channels, index_or_name)
+    if channel is None:
+        raise click.ClickException(f"no channel matching {index_or_name!r}")
+    click.echo(render(channel, resolve_output(state.output, output_override), kind="channel"))
+
+
+@get_group.command("pending-contacts")
+@output_option
+@click.pass_obj
+def get_pending_contacts(state: Any, output_override: str | None) -> None:
+    """Watch for adverts from not-yet-added contacts, for one timeout window.
+
+    Unlike a long-lived session, a one-shot connection has no pre-existing
+    cache of pending adverts to show: this actively listens for the
+    current --timeout (or the context/config default) and reports whatever
+    arrives in that window. Re-run (or pass a longer --timeout) to catch
+    more.
+    """
+
+    async def watch(connection: Any) -> list[dict[str, Any]]:
+        context = state.resolve_context()
+        duration = state.effective_timeout(context)
+        return await collect_events(
+            connection, EventType.NEW_CONTACT, duration, sleep=asyncio.sleep
+        )
+
+    pending = state.call(watch)
+    contacts = [normalize_contact(c) for c in pending]
+    if not contacts:
+        click.echo("No pending contacts seen in this window.", err=True)
+        return
+    fmt = resolve_output(state.output, output_override)
+    click.echo(render(contacts, fmt, kind="pending-contact"))
+
+
+@get_group.command("path")
+@click.argument("name")
+@output_option
+@click.pass_obj
+def get_path(state: Any, name: str, output_override: str | None) -> None:
+    """Show the routing path to a contact (flood, direct, or a hop list)."""
+    contacts = state.call(fetch_contacts)
+    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}")
+    result = {"name": contact["name"], "path": contact["path"]}
+    click.echo(render(result, resolve_output(state.output, output_override), kind="path"))
+
+
+@get_group.command("time")
+@output_option
+@click.pass_obj
+def get_time(state: Any, output_override: str | None) -> None:
+    """Show the device's current clock."""
+    result = state.call(fetch_time)
+    click.echo(render(result, resolve_output(state.output, output_override), kind="time"))

meshcorectl/commands/login.py

@@ -0,0 +1,115 @@
+"""`meshcorectl login`/`logout` -- authenticate to a repeater/room server."""
+
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import AmbiguousMatchError, fetch_contacts, find_contact
+from ..mesh_data import login as login_data
+from ..mesh_data import logout as logout_data
+from ..selectors import SelectorError, filter_contacts
+
+
+def _resolve_password(password: str | None, password_stdin: bool) -> str:
+    """Assumes the `--password`/`--password-stdin` mutual exclusion was
+    already validated by the caller (see `login_command`) -- checked
+    early, before connecting, not buried in here."""
+    if password_stdin:
+        return sys.stdin.readline().rstrip("\n")
+    if password is not None:
+        return password
+    return click.prompt("Password", hide_input=True)
+
+
+@click.command(name="login")
+@click.argument("name", required=False, metavar="REPEATER")
+@click.option(
+    "-l",
+    "--selector",
+    "selector_text",
+    default=None,
+    metavar="SELECTOR",
+    help="Log into every contact matching this filter instead of one by name.",
+)
+@click.option(
+    "--password",
+    default=None,
+    help="Password (prefer --password-stdin, or the secure prompt, over shell history).",
+)
+@click.option("--password-stdin", is_flag=True, help="Read the password from stdin.")
+@click.option("--dry-run", is_flag=True, help="Show what would run without logging in.")
+@click.pass_obj
+def login_command(
+    state: Any,
+    name: str | None,
+    selector_text: str | None,
+    password: str | None,
+    password_stdin: bool,
+    dry_run: bool,
+) -> None:
+    """Log into REPEATER (or room), or every -l/--selector match."""
+    if (name is None) == (selector_text is None):
+        raise click.ClickException("pass exactly one of REPEATER or -l/--selector")
+    if password is not None and password_stdin:
+        raise click.ClickException("pass only one of --password or --password-stdin")
+
+    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
+
+        if dry_run:
+            for target in targets:
+                click.echo(f"would log into {target['name']!r} (dry run)")
+            return
+
+        secret = _resolve_password(password, password_stdin)
+        context = state.resolve_context()
+        timeout = state.effective_timeout(context)
+        for target in targets:
+            success = await login_data(connection, target, secret, timeout=timeout)
+            click.echo(f"{target['name']!r}: {'login ok' if success else 'login failed'}")
+
+    state.call(run)
+
+
+@click.command(name="logout")
+@click.argument("name", metavar="REPEATER")
+@click.option("--dry-run", is_flag=True, help="Show what would run without logging out.")
+@click.pass_obj
+def logout_command(state: Any, name: str, dry_run: bool) -> None:
+    """Log out of REPEATER (or room)."""
+
+    async def run(connection: MeshCoreConnection) -> None:
+        contacts = await fetch_contacts(connection)
+        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}")
+        if dry_run:
+            click.echo(f"would log out of {contact['name']!r} (dry run)")
+            return
+        await logout_data(connection, contact)
+        click.echo(f"{contact['name']!r}: logged out")
+
+    state.call(run)

meshcorectl/commands/logs.py

@@ -0,0 +1,130 @@
+"""`meshcorectl logs` -- messages received by the device, the mesh analogue
+of `kubectl logs`.
+
+Like `kubectl logs`, this prints plain lines, not a table: a stream of
+messages arriving over time isn't a resource list `get` would show, it's a
+log. `-o json`/`-o yaml` still switch the line format for scripting, one
+record per line, same as `-o json`'s effect on `kubectl logs --timestamps`
+type output in other tools.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any
+
+import click
+import yaml
+from meshcore import EventType
+
+from ..connect import MeshCoreConnection
+from ..durations import parse_duration
+from ..mesh_data import drain_messages, fetch_channels, fetch_contacts, normalize_message
+from ..output import OutputFormat, output_option, resolve_output
+
+
+async def wait_until_interrupted() -> None:
+    """Blocks until the process is interrupted (Ctrl-C), which `main()`
+    already translates into a clean exit. Its own module-level function
+    (rather than an inline `await asyncio.Event().wait()`) so tests can
+    monkeypatch it to return immediately instead of hanging."""
+    await asyncio.Event().wait()
+
+
+def format_message_line(message: dict[str, Any], fmt: OutputFormat) -> str:
+    if fmt is OutputFormat.JSON:
+        return json.dumps(message)
+    if fmt is OutputFormat.YAML:
+        return yaml.safe_dump(message, sort_keys=False).rstrip("\n")
+    return f"{message['name']}: {message['text']}"
+
+
+@click.command(name="logs")
+@click.option(
+    "-f",
+    "--follow",
+    is_flag=True,
+    help="Keep the connection open and print new messages as they arrive.",
+)
+@click.option(
+    "--since",
+    "since_text",
+    default=None,
+    metavar="DURATION",
+    help="Only show already-queued messages newer than this, e.g. 30m, 2h.",
+)
+@click.option(
+    "--rx",
+    "raw_rx",
+    is_flag=True,
+    help="Follow the raw rx-log packet stream instead of messages (requires --follow).",
+)
+@output_option
+@click.pass_obj
+def logs_command(
+    state: Any,
+    follow: bool,
+    since_text: str | None,
+    raw_rx: bool,
+    output_override: str | None,
+) -> None:
+    """Show messages received by the device."""
+    if raw_rx and not follow:
+        raise click.ClickException("--rx has no effect without --follow")
+
+    since_seconds: float | None = None
+    if since_text is not None:
+        try:
+            since_seconds = parse_duration(since_text)
+        except ValueError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    fmt = resolve_output(state.output, output_override)
+
+    async def run(connection: MeshCoreConnection) -> None:
+        if raw_rx:
+            connection.subscribe(
+                EventType.RX_LOG_DATA,
+                lambda event: click.echo(json.dumps(event.payload, default=str)),
+            )
+            await wait_until_interrupted()
+            return
+
+        contacts = await fetch_contacts(connection)
+        channels = await fetch_channels(connection)
+        cutoff = time.time() - since_seconds if since_seconds is not None else None
+
+        def show(raw: dict[str, Any]) -> None:
+            timestamp = raw.get("sender_timestamp")
+            if cutoff is not None and timestamp is not None and timestamp < cutoff:
+                return
+            message = normalize_message(raw, contacts=contacts, channels=channels)
+            click.echo(format_message_line(message, fmt))
+
+        for raw in await drain_messages(connection):
+            show(raw)
+
+        if follow:
+            # CONTACT_MSG_RECV/CHANNEL_MSG_RECV are not passively pushed:
+            # they only fire as a side effect of an explicit
+            # commands.get_msg() call, normally triggered by a
+            # MESSAGES_WAITING notification. So subscribe to
+            # MESSAGES_WAITING and drain again (via the same
+            # drain_messages() used for the initial batch) whenever it fires.
+            fetch_task: asyncio.Task[None] | None = None
+
+            async def drain_new_messages() -> None:
+                for raw in await drain_messages(connection):
+                    show(raw)
+
+            def handle_messages_waiting(_event: Any) -> None:
+                nonlocal fetch_task
+                if fetch_task is None or fetch_task.done():
+                    fetch_task = asyncio.create_task(drain_new_messages())
+
+            connection.subscribe(EventType.MESSAGES_WAITING, handle_messages_waiting)
+            await wait_until_interrupted()
+
+    state.call(run)

meshcorectl/commands/reboot.py

@@ -0,0 +1,40 @@
+"""`meshcorectl reboot` -- reboot the connected device.
+
+No interactive y/n prompt: `--yes` is a required flag instead, the same
+pattern as `terraform apply -auto-approve`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from ..connect import MeshCoreConnection
+from ..mesh_data import reboot_device
+from ..output import output_option, render_result, resolve_output
+
+
+@click.command(name="reboot")
+@click.option(
+    "--yes",
+    is_flag=True,
+    help="Confirm the reboot; required, since there is no interactive prompt.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would happen without rebooting.")
+@output_option
+@click.pass_obj
+def reboot_command(state: Any, yes: bool, dry_run: bool, output_override: str | None) -> None:
+    """Reboot the connected device."""
+    if dry_run:
+        click.echo("would reboot the device (dry run)")
+        return
+    if not yes:
+        raise click.ClickException("pass --yes to confirm rebooting the device")
+
+    async def run(connection: MeshCoreConnection) -> None:
+        await reboot_device(connection)
+
+    state.call(run)
+    fmt = resolve_output(state.output, output_override)
+    click.echo(render_result({"rebooted": True}, fmt, "reboot requested"))