MeshTerm/meshterm/tools/monitor.py

"""The ``monitor`` tool: review what the always-on passive monitor has heard.

Passive monitoring records every advert and telemetry frame the companion overhears —
with SNR, RSSI, and any shared location — to the database, building the longitudinal
history that the coverage map and link-quality alerting read back. It transmits nothing;
it only listens.

Recording is always on: the session-wide
:class:`~meshterm.services.event_hub.EventHub` overhears every packet, and
:class:`~meshterm.services.monitor_service.MonitorService` (``ctx.monitor``) writes them
to history as one of its subscribers, from the moment the radio opens. There is nothing
to switch, so in the menu this tool is purely the read side: the all-time heard-node
summary (the live packet counters are shown in the main-menu header, not here). On the
CLI it is instead a bounded foreground capture — ``meshterm monitor --seconds 60`` tails
each overheard packet to the console and summarizes the window when it ends.
"""

from __future__ import annotations

import asyncio
from typing import Any

import typer
from rich.table import Table
from rich.text import Text

from ..context import AppContext
from ..core.events import EventKind, MeshEvent
from ..core.models import HeardNode, Observation
from .base import Tool, ToolResult, register


@register
class MonitorTool(Tool):
    """Review the nodes the always-on passive monitor has heard."""

    name = "monitor"
    title = "Heard nodes"
    help = "Review every node the passive monitor has overheard"
    category = "Diagnostics"
    order = 20

    async def execute(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Run directly, without a logged ``runs`` row.

        The heard-node review is a read of existing history, not a measurement, so it is
        deliberately not wrapped in run-logging (unlike the base :meth:`Tool.execute`).
        The CLI capture's observations are recorded under the monitor service's own
        ``monitor`` run instead.

        Args:
            ctx: Shared application context.
            params: Parameters for this invocation.

        Returns:
            The :class:`ToolResult` from :meth:`run`.
        """
        return await self.run(ctx, params)

    async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Show the heard-node review, or run the CLI's bounded capture.

        Args:
            ctx: Shared application context.
            params: Empty for the menu's review; ``action="capture"`` plus ``seconds``
                for the CLI capture.

        Returns:
            A :class:`ToolResult` describing the outcome.
        """
        if params.get("action") == "capture":
            return await self._capture(ctx, params)
        return self._view(ctx)

    @staticmethod
    async def _capture(ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Record overheard packets in the foreground for a bounded window (CLI only).

        Connects the device, ensures history recording and the event hub are running,
        and tails each overheard packet to the console until the window ends (or the
        user interrupts). Observations are persisted by the monitor service exactly as
        in an interactive session; this adds a live console view and a window-scoped
        heard-node summary on top.

        Args:
            ctx: Shared application context.
            params: ``seconds`` — how long to capture (``0``/``None`` = until Ctrl-C).

        Returns:
            A :class:`ToolResult` with the window's packet and node counts.
        """
        seconds = int(params.get("seconds") or 0)
        await ctx.device()  # surface connection problems before announcing the capture
        await ctx.monitor.start()  # register history recording before the hub pumps
        await ctx.events.start()
        ctx.console.print(
            "[muted]monitoring"
            f"{f' for {seconds}s' if seconds else ' — press Ctrl-C to stop'}…[/muted]"
        )
        seen: list[Observation] = []

        def on_observation(event: MeshEvent) -> None:
            obs = event.observation
            if obs is None:
                return
            seen.append(obs)
            stamp = obs.observed_at.astimezone().strftime("%H:%M:%S")
            who = obs.name or obs.node or "?"
            snr = f" [muted]{obs.snr:+.1f} dB[/muted]" if obs.snr is not None else ""
            rssi = f" [muted]{obs.rssi:.0f} dBm[/muted]" if obs.rssi is not None else ""
            loc = " [ok]●[/ok]" if obs.lat is not None else ""
            ctx.console.print(
                f"[muted]{stamp}[/muted] [accent]{who}[/accent]{snr}{rssi}{loc}"
            )

        unsubscribe = ctx.events.subscribe(on_observation, EventKind.OBSERVATION)
        try:
            if seconds:
                await asyncio.sleep(seconds)
            else:
                await asyncio.Event().wait()  # until Ctrl-C / cancellation
        except (KeyboardInterrupt, asyncio.CancelledError):  # pragma: no cover - interactive
            pass
        finally:
            unsubscribe()
            await ctx.monitor.stop()  # close the run row so the capture is a full record

        by_node: dict[str, list[Observation]] = {}
        for obs in seen:
            by_node.setdefault(obs.node, []).append(obs)
        nodes = [HeardNode.from_observations(node, group) for node, group in by_node.items()]
        if nodes:
            nodes.sort(key=lambda n: n.last_seen, reverse=True)
            ctx.ui.show(_heard_table(nodes, lambda _node: None))
        return ToolResult(
            summary={"seconds": seconds, "packets": len(seen), "nodes": len(nodes)},
            message=(
                f"[ok]✓[/ok] heard [brand]{len(seen)}[/brand] "
                f"packet{'' if len(seen) == 1 else 's'} from "
                f"[brand]{len(nodes)}[/brand] node{'' if len(nodes) == 1 else 's'}"
            ),
        )

    @staticmethod
    def _view(ctx: AppContext) -> ToolResult:
        """Render the all-time heard-node summary from stored observations.

        Reads only the database, so it needs no device connection and works whether or
        not packets are currently arriving.

        Args:
            ctx: Shared application context.

        Returns:
            A :class:`ToolResult` summarizing the heard nodes.
        """
        heard = ctx.repo.heard_nodes()
        if heard:
            # Names come from the stored observations, so no device lookup is needed.
            ctx.ui.show(_heard_table(heard, lambda _node: None))
        else:
            ctx.ui.note(
                "[muted]no packets heard yet — history accumulates while MeshTerm runs[/muted]"
            )

        packets = sum(n.count for n in heard)
        located = sum(1 for n in heard if n.has_location)
        return ToolResult(
            summary={
                "nodes_heard": len(heard),
                "observations": packets,
                "nodes_with_location": located,
            },
            message=(
                f"[ok]✓[/ok] heard [brand]{packets}[/brand] packets from "
                f"[brand]{len(heard)}[/brand] nodes (all time)"
            ),
        )

    def register_cli(self, app: typer.Typer) -> None:
        """Register the ``monitor`` subcommand (the bounded foreground capture).

        Args:
            app: The Typer application.
        """
        from ..cli import run_tool_command

        @app.command(
            name=self.name,
            help="Capture overheard packets live for a while and summarize them",
        )
        def _monitor(
            seconds: int = typer.Option(
                0, "--seconds", "-s", help="How long to capture (0 = until Ctrl-C)"
            ),
        ) -> None:
            run_tool_command(self, {"action": "capture", "seconds": seconds})


def _heard_table(heard: list[HeardNode], resolve) -> Table:  # noqa: ANN001
    """Render the heard-node summary table.

    Args:
        heard: Aggregated per-node statistics.
        resolve: Maps a raw node hash to a friendly contact name when known.

    Returns:
        A Rich :class:`Table` of node, packet count, SNR, RSSI, and location.
    """
    from ..ui.theme import snr_style

    table = Table(title=f"Heard nodes ({len(heard)})", border_style="muted", expand=False)
    table.add_column("NODE")
    table.add_column("PKTS", justify="right")
    table.add_column("MEDIAN SNR", justify="right")
    table.add_column("BEST SNR", justify="right")
    table.add_column("RSSI", justify="right")
    table.add_column("LOC", justify="center")
    for node in heard:
        label = node.name or resolve(node.node) or node.node or "?"
        median = node.median_snr
        best = node.best_snr
        median_cell = (
            Text(f"{median:+.1f}", style=snr_style(median)) if median is not None else Text("—")
        )
        best_cell = (
            Text(f"{best:+.1f}", style=snr_style(best)) if best is not None else Text("—")
        )
        rssi_cell = f"{node.last_rssi:.0f}" if node.last_rssi is not None else "—"
        loc_cell = Text("●", style="ok") if node.has_location else Text("·", style="muted")
        table.add_row(
            str(label), str(node.count), median_cell, best_cell, rssi_cell, loc_cell
        )
    return table