#2024 feat(cli): swamp inbox — read swamp-club notifications without leaving the terminal

Filed against swamp (the CLI). Parent: the swamp-club product-nurture epic. Optional / stretch — the epic is complete without it.

Problem

The notice tells an operative something is waiting and then sends them to a browser. For the audience these nurture messages target — people who live in a terminal — that is a hop worth removing. It is also the difference between the CLI being notified and the CLI being a channel.

What ships

swamp inbox                  # list unread, newest first
swamp inbox --all            # include read
swamp inbox <id>             # render one message
swamp inbox <id> --read      # mark read
swamp inbox --json

Reads GET /api/v1/notifications (the full view, which is the right endpoint here — this is a deliberate command, not a per-invocation poll) and POST /api/v1/notifications/<id> to mark read. Bodies are markdown; render them through the existing src/presentation/markdown_renderer.ts rather than printing raw.

Why it is separate from the notice

The notice must be free on every invocation; this command is allowed to be a network round trip because the operative asked for it. Keeping them apart means the expensive one can never accidentally end up on the hot path — which is the same separation the update notice and swamp update already keep.

Things to get right

• --json is a contract. Shape it once and pin it, the way the other commands' JSON output is.
• Do not invent read state locally. Marking read is a server write; a local cache of read state would disagree with the web inbox the moment either side moves.
• Empty is a first-class render, and it is not an error. So is "unavailable" — a failed fetch must not print "no notifications".

Verification

Unit coverage for the renderer against fixture payloads including an empty list, a markdown body with a link, and a fetch failure. Manually: send yourself a message from /admin/messages, read it with swamp inbox, confirm it shows as read on the web.