MeshTerm/meshterm/tools/courier.py

# SPDX-License-Identifier: Apache-2.0
"""The ``courier`` tool: store-and-forward messaging for contacts that aren't there yet.

Interactively it opens the outbox screen (see :mod:`meshterm.ui.courier_screen`):
queued messages with their live state, the queueing flow (recipient → message →
when), forced sends, and the delivered/given-up history. Delivery runs in the
background for the whole session (see :mod:`meshterm.services.courier`): a queued
message goes out when its contact is next heard — or at its scheduled time — as a normal
direct message with acknowledgement tracking and polite exponential backoff, and the
outcome lights the header's Watchtower badge.

On the CLI the same outbox is scriptable through subcommands: ``queue`` adds a message
(reading the contact list to address it — nothing is transmitted) for the next
interactive session's courier to deliver, ``send`` forces one delivery attempt right now,
and ``list`` / ``cancel`` / ``clear`` inspect and prune the outbox — the scriptable face
of the outbox screen's own Send-now, Cancel, and Clear-finished actions.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Any

import typer

from ..context import AppContext
from ..core import exitcodes
from .base import Tool, ToolResult, register

if TYPE_CHECKING:  # pragma: no cover - typing only
    from ..core.courier_store import QueuedMessage
    from ..ui.report import Facts, Listing


@register
class CourierTool(Tool):
    """Queue messages for offline contacts; they go out when the contact is next heard."""

    name = "courier"
    title = "Courier"
    icon = "📨"
    help = "Outbox that delivers when a contact is heard"
    category = "Message"
    order = 30  # after Chat and Channels: the same conversations, minus the waiting around

    async def prompt_params(self, ctx: AppContext) -> dict[str, Any] | None:
        """Run the outbox screen; there are never parameters to collect.

        The screen presents everything itself and returns when dismissed, so
        returning ``None`` tells the menu the invocation is complete (the same
        pattern as the ``dashboard`` tool).

        Args:
            ctx: Shared application context.

        Returns:
            Always ``None``.
        """
        from ..ui.courier_screen import open_courier

        await open_courier(ctx)
        return None

    async def run(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Dispatch a scripted CLI action (the menu path lives in :meth:`prompt_params`).

        Args:
            ctx: Shared application context.
            params: A ``cli_action`` naming the outbox action, plus its arguments.

        Returns:
            A :class:`ToolResult` describing the action's outcome.
        """
        action = params.get("cli_action", "queue")
        if action == "list":
            return await self._cli_list(ctx)
        if action == "send":
            return await self._cli_send(ctx, params)
        if action == "cancel":
            return await self._cli_cancel(ctx, params)
        if action == "clear":
            return await self._cli_clear(ctx)
        return await self._cli_queue(ctx, params)

    # -- CLI --------------------------------------------------------------------

    async def _cli_queue(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Queue one message from the CLI (transmits nothing).

        Args:
            ctx: Shared application context.
            params: ``contact`` (contact name), ``text`` (the message body), and an
                optional local ``at`` clock time (``HH:MM``, next occurrence).

        Returns:
            A :class:`ToolResult` describing the queued entry.
        """
        from ..ui.courier_screen import parse_clock
        from ..ui.watchtower_screen import contact_watch_key

        device = await ctx.device()
        contacts = await device.get_contacts()
        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 typer.BadParameter(f"unknown contact: {name!r}")
        key = contact_watch_key(contact)
        if key is None:
            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 typer.BadParameter(
                    f"--at wants a clock time like 07:00, not {params['at']!r}"
                )
        message = ctx.courier_store.queue(
            key, contact.name, str(params["text"]), not_before=not_before
        )
        when = (
            f"at {not_before.astimezone().strftime('%b %d %H:%M')}"
            if not_before is not None
            else "when the contact is next heard"
        )
        ctx.ui.ack(
            f"[ok]queued[/ok] #{message.ident} for [brand]{contact.name}[/brand] — "
            f"delivers {when} (an interactive session's courier does the sending)"
        )
        return ToolResult(
            summary={"queued": message.ident, "contact": contact.name, "at": params.get("at")},
            report=(_queued(message, contact.name, not_before),),
        )

    async def _cli_list(self, ctx: AppContext) -> ToolResult:
        """State the outbox — waiting entries then finished ones.

        A read-only view over the stored outbox: it needs no device, so it works the same
        whether or not a radio is attached (the scriptable face of the outbox screen).
        """
        entries = ctx.courier_store.entries()
        return ToolResult(
            summary={"entries": len(entries)},
            report=(_outbox(entries),),
            exit_code=exitcodes.OK if entries else exitcodes.NO_RESULT,
        )

    async def _cli_send(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Force one delivery attempt for a waiting entry, right now.

        The scriptable ``Send now`` — one forced attempt through the same courier the
        outbox screen uses, skipping the "wait until the contact is heard" eligibility check.
        """
        ident = int(params["id"])
        if ctx.courier_store.get(ident) is None:
            # A bad argument, not a device failure: the outbox is a local file, nothing was
            # transmitted, and no retry will make an id exist. Exit 4 told a caller to try
            # again; exit 2 tells it to fix the command, which is the truth.
            raise typer.BadParameter(f"no outbox entry #{ident} (see `courier list`)")
        outcome = await ctx.courier.attempt_now(ident)
        notes = {
            "delivered": "[ok]✓ delivered[/ok] — acknowledged by the contact",
            "no ack": "[warn]sent, but no acknowledgement[/warn] — it stays queued for retry",
            "gave up": "[err]✗ gave up[/err] — the retry budget is spent",
            "unknown contact": (
                "[warn]the device's contacts don't know this contact yet[/warn] — it stays queued"
            ),
            "busy": "[muted]another delivery is in flight — try again in a moment[/muted]",
            "gone": "[muted]that entry is no longer waiting[/muted]",
        }
        ctx.ui.ack(notes.get(outcome, outcome))
        return ToolResult(
            summary={"id": ident, "outcome": outcome},
            report=(_attempted(ident, outcome),),
        )

    async def _cli_cancel(self, ctx: AppContext, params: dict[str, Any]) -> ToolResult:
        """Remove a waiting entry from the outbox (finished ones use ``clear``)."""
        ident = int(params["id"])
        if ctx.courier_store.cancel(ident):
            ctx.ui.ack(f"[warn]cancelled outbox entry #{ident}[/warn]")
            return ToolResult(
                summary={"id": ident, "cancelled": True},
                report=(_did(("id", ident), ("cancelled", True)),),
            )
        ctx.ui.ack(f"[muted]no waiting entry #{ident} to cancel[/muted]")
        return ToolResult(
            summary={"id": ident, "cancelled": False},
            report=(_did(("id", ident), ("cancelled", False)),),
            exit_code=exitcodes.NO_RESULT,
        )

    async def _cli_clear(self, ctx: AppContext) -> ToolResult:
        """Drop every finished (delivered / given-up) entry, leaving the queue untouched."""
        before = len(ctx.courier_store.entries())
        ctx.courier_store.clear_done()
        cleared = before - len(ctx.courier_store.entries())
        if cleared:
            ctx.ui.ack(f"[ok]cleared {cleared} finished entr{'y' if cleared == 1 else 'ies'}[/ok]")
        else:
            ctx.ui.ack("[muted]no finished entries to clear[/muted]")
        return ToolResult(
            summary={"cleared": cleared},
            report=(_did(("cleared", cleared)),),
            exit_code=exitcodes.OK if cleared else exitcodes.NO_RESULT,
        )

    def register_cli(self, app: typer.Typer) -> None:
        """Register the ``courier`` subcommand group.

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

        courier_app = typer.Typer(help=self.help, no_args_is_help=True, rich_markup_mode=None)

        @courier_app.command(
            "queue", help="Queue a message for delivery when the contact is next heard"
        )
        def _queue_cmd(
            contact: str = typer.Argument(..., help="The recipient contact's name"),
            text: list[str] = typer.Argument(..., help="The message to queue"),
            at: str | None = typer.Option(
                None, "--at", help="Hold until this local time (HH:MM, next occurrence)"
            ),
        ) -> None:
            tool_params: dict[str, Any] = {
                "cli_action": "queue",
                "contact": contact,
                "text": " ".join(text),
            }
            if at is not None:
                tool_params["at"] = at
            run_tool_command(self, tool_params)

        @courier_app.command("list", help="Show the outbox — waiting and finished entries")
        def _list_cmd() -> None:
            run_tool_command(self, {"cli_action": "list"})

        @courier_app.command("send", help="Force one delivery attempt for a waiting entry now")
        def _send_cmd(
            id: int = typer.Argument(..., help="Outbox entry id (from `courier list`)"),
        ) -> None:
            run_tool_command(self, {"cli_action": "send", "id": id})

        @courier_app.command("cancel", help="Remove a waiting entry from the outbox")
        def _cancel_cmd(
            id: int = typer.Argument(..., help="Outbox entry id (from `courier list`)"),
        ) -> None:
            run_tool_command(self, {"cli_action": "cancel", "id": id})

        @courier_app.command("clear", help="Drop finished (delivered / given-up) entries")
        def _clear_cmd() -> None:
            run_tool_command(self, {"cli_action": "clear"})

        app.add_typer(courier_app, name=self.name)


def _recipient(name: str | None, node_key: str | None) -> object:
    """The outbox's addressee as the shared node shape.

    The outbox stores a name and the 12-hex id it addresses, so three of the five fields
    are honestly ``null`` — and the id goes in ``hash`` rather than ``key``, because that
    is what it is. A key is the full value and is never truncated by this app's choosing;
    calling a six-byte prefix one would hand a caller something ``--to`` cannot take.
    """
    from ..ui.fields import NodeRef

    return NodeRef(name=name, hash=(node_key or "").lower() or None)


def _queued(message: QueuedMessage, name: str, not_before: object) -> Facts:
    """What ``courier queue`` put in the outbox.

    The plain face prints the **id and nothing else**, because the id is the one fact a
    caller has to keep — it is what ``send`` and ``cancel`` take — and everything else on
    the line is what they just typed. The document carries the rest, because a caller
    logging the queue has no other record of it.
    """
    from ..ui import fields
    from ..ui.report import Facts

    return Facts(
        key="queued",
        fields=(
            fields.integer("id", "id"),
            fields.node("node", lanes=()),
            fields.hidden("scheduled_at"),
            fields.hidden("text"),
        ),
        values={
            "id": message.ident,
            "node": _recipient(name, message.node_key),
            "scheduled_at": not_before,
            "text": message.text,
        },
    )


def _outbox(entries: list) -> Listing:
    """The outbox, waiting entries then finished ones.

    The deliberate asymmetry between the two time columns: ``SCHEDULED`` is an
    *appointment* the caller set with ``--at``, so it stays a wall-clock instant, and
    ``FINISHED`` is an age, because "how long ago did it go" is what anyone reading a
    delivered row wants. The mixed widths are the price of both columns being right, and
    ``--absolute`` makes them uniform for anyone who dislikes it.
    """
    from ..core.courier_store import DELIVERED, QUEUED
    from ..ui import fields
    from ..ui.report import Listing

    rows = []
    for m in entries:
        if m.status == QUEUED:
            state = "waiting"
        elif m.status == DELIVERED:
            state = "delivered"
        else:
            state = "gave up"
        rows.append(
            {
                "id": m.ident,
                "state": state,
                "node": _recipient(m.node_name, m.node_key),
                # An entry with no scheduled time goes as soon as the contact is heard,
                # which is not a time and so is not one here either.
                "scheduled_at": m.not_before,
                "finished_at": m.finished,
                # Not shortened the way the outbox screen shortens it: nothing wraps here.
                "text": m.text,
            }
        )
    return Listing(
        key="outbox",
        columns=(
            fields.integer("id", "ID"),
            fields.word("state", "STATE"),
            fields.node("node", lanes=(("name", "NODE"),)),
            fields.instant("scheduled_at", "SCHEDULED"),
            fields.when("finished_at", "FINISHED"),
            fields.free("text", "TEXT"),
        ),
        rows=rows,
    )


def _attempted(ident: int, outcome: str) -> Facts:
    """What one forced delivery attempt came to.

    ``outcome`` is one of the closed set the help lists, kept verbatim — spaces and all —
    so both faces say the same word and a script matching ``no ack`` matches what a person
    reads.
    """
    from ..ui import fields
    from ..ui.report import Facts

    return Facts(
        key="attempt",
        fields=(fields.hidden("id"), fields.word("outcome", "outcome")),
        values={"id": ident, "outcome": outcome},
    )


def _did(*facts: tuple[str, object]) -> Facts:
    """An acknowledgement as data: nothing plain, a document for whoever is logging.

    ``cancel`` and ``clear`` say everything they have to say in their exit status, which
    is the right plain answer — but a caller that wants to record *what* was cancelled has
    nowhere to read it, and that is what the document is for.
    """
    from ..ui import fields
    from ..ui.report import SILENT, Facts

    def column(key: str, value: object):  # noqa: ANN202 - one of two shapes
        return fields.flag(key, key) if isinstance(value, bool) else fields.integer(key, key)

    return Facts(
        key="outcome",
        fields=tuple(column(key, value) for key, value in facts),
        values=dict(facts),
        shape=SILENT,
    )