@pingroom/cli 0.2.0 → 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PingRoom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -3,14 +3,69 @@
 Send PingRoom pings — and ask a human a question and block for their answer —
 from CI, scripts, and agents. Delivered as push straight to your phone.
 
-Zero dependencies. Works anywhere Node ≥ 20 runs.
+One dependency (`qrcode-terminal`, used only to draw the pairing QR). Works
+anywhere Node ≥ 20 runs.
 
 ```bash
 npx @pingroom/cli ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"
 ```
 
 Commands: `ping` (send), `ask` (ask a human), `watch` (block on an existing
-question), `list`, `cancel`. Run `pingroom --help` for the full reference.
+question), `list`, `cancel`, `handoff` (hand a decision to a specific human),
+`handoffs` (list open or recent Handoffs), `live` (lock-screen progress card),
+`hook` (Claude Code), `config`, and `logout`.
+Run `pingroom --help` for the full reference.
+
+## Connecting
+
+Run `pingroom` with no arguments. It prints a QR code — scan it with the PingRoom
+app and pick both the account and the room the agent delivers to — or take the
+emailed-code fallback.
+
+```
+$ pingroom
+  Not connected. How do you want to connect?
+    1) Scan a QR code with the PingRoom app
+    2) Email me a code
+  Choose [1]:
+
+  [QR]
+  Or open: https://pingroom.io/app/agents/pair?token=…
+  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X
+```
+
+There is deliberately no `login` command: being unconnected is a state the tool
+resolves, not one you have to discover. Once connected, bare `pingroom` prints
+that status line followed by the usual help.
+
+The credential lands in `~/.pingroom/credentials.json` (mode `0600`, inside a
+`0700` directory). `PINGROOM_HOME` moves that directory; `pingroom logout`
+clears it.
+
+**CI is unaffected.** `PINGROOM_TOKEN` in the environment always outranks the
+stored credential, and a non-interactive shell never prompts and never draws a
+QR — a command that needs a credential and has none fails with exit `2` pointing
+at `PINGROOM_TOKEN`.
+
+### Local settings
+
+```bash
+pingroom config set default_room ab12cd     # fallback for --room
+pingroom config set api_url https://api.pingroom.io
+pingroom config get default_room
+pingroom config list
+pingroom config set api_url ""              # an empty value clears the key
+```
+
+Precedence, highest first:
+
+```
+explicit flag  >  env var  >  ~/.pingroom/config.json  >  built-in default
+```
+
+So `--room` beats `PINGROOM_ROOM` beats `default_room` (and, last of all, the
+room the credential was paired to); `--api` beats `PINGROOM_API_URL` beats
+`api_url`.
 
 ## Getting a webhook URL
 
@@ -26,6 +81,10 @@ pingroom ping [options]
   -t, --title <text>     Ping title (<= 40 chars)
   -a, --action <1-4>     Quick-action slot to attribute the ping to
   -d, --data <json>      Extra JSON data, e.g. '{"commit":"abc123"}'
+      --url <https-url>  Make the ping a tappable link (absolute http(s) URL)
+      --button-label <t> Link button text (<= 26 chars; requires --url)
+      --require-ack      Keep the ping open until an eligible recipient acknowledges it
+      --ack-timeout <s>  Ack deadline in seconds (requires --require-ack)
   -w, --webhook <url>    Room webhook URL (or env PINGROOM_WEBHOOK_URL)
       --token <token>    Agent access token (or env PINGROOM_TOKEN)
       --room <code>      Room invite code (used with --token)
@@ -33,9 +92,121 @@ pingroom ping [options]
       --json             Print the raw JSON response
 ```
 
+To make the ping actionable, add `--require-ack`. The first eligible recipient to
+acknowledge it wins; `--ack-timeout` optionally expires it if nobody responds:
+
+```bash
+pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Production health check failed" \
+  --require-ack --ack-timeout 300
+```
+
+Webhook timeouts accept 1–86400 seconds. Agent-token room pings accept
+60–86400 seconds.
+
+To attach a tappable link button (a "link ping"), add `--url` and optionally
+`--button-label`. They fold into the structured `data` object as
+`{"url": ..., "button_label": ...}` — the same convention accepted raw via
+`--data`:
+
+```bash
+pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Build 512 ready" \
+  --url https://ci.example.com/builds/512 --button-label "Open build"
+```
+
+The URL must be absolute http(s) (≤ 2048 chars); the label caps at 26 chars.
+
 Exit codes: `0` success · `1` delivery failed · `2` bad usage. So CI fails loudly if a
 ping doesn't land.
 
+## Live Activities (`pingroom live`)
+
+A **live-status stream** is one long-running thing shown as a self-updating card
+on the Lock Screen (iOS Live Activity / Dynamic Island, Android live update, and
+a full inline card in the app). `start` opens it with one alert, `update` moves
+it **silently**, `end` closes it with one completion alert.
+
+```
+pingroom live <start|update|end|get> [options]
+
+  -c, --correlation-id <id>  The stream key — reuse it for every ping (required)
+      --template <name>      start only: status | steps | progress | metrics |
+                             countdown | question | matchup (fixed at creation)
+      --steps <a,b,c>        start only: 2-8 comma-separated step labels
+  -m, --message <text>       The card's live message line
+      --progress <0..1>      Progress bar / Dynamic Island gauge
+      --step <n>             Current step index (steps template)
+      --metric <label:value> Repeatable, up to 3 (metrics template)
+      --deadline-at <epoch>  Countdown target (countdown template)
+      --eta-at <epoch>       Live ETA (status/progress templates)
+      --prompt <text>        The ask (question template)
+      --option <value:label> Repeatable, up to 4 (question template)
+      --left <label:value>   Left side (matchup template)
+      --right <label:value>  Right side (matchup template)
+      --center <text>        Center score/clock, <= 40 (matchup template)
+      --accent-override <#rrggbb>  Semantic accent for this frame
+      --failed               end only: finish as failed instead of done
+  -t, --title <text>         Card title (<= 40 chars)
+  -a, --action <1-4>         Quick-action slot supplying the icon and sound
+      --require-ack          Add an Acknowledge button
+      --ack-timeout <s>      Ack deadline in seconds
+  -w, --webhook <url>        Room webhook URL instead of a token
+      --token <token>        Agent access token (or env PINGROOM_TOKEN)
+      --room <code>          Room invite code (used with --token)
+```
+
+Works with either an agent token (`--token`, needs the `pingroom:live:write`
+scope) or a room's incoming webhook (`--webhook`, Pro) — both speak the same
+`live_status` contract.
+
+```bash
+# Track a deploy end to end.
+pingroom live start  -c deploy-42 --template steps \
+  --steps "Build,Test,Deploy,Verify" -t "Release 1.4.0"
+pingroom live update -c deploy-42 --step 2 -m "Deploying to prod"
+pingroom live end    -c deploy-42 -m "Shipped 1.4.0"     # add --failed to fail it
+```
+
+All 7 templates are expressible:
+
+```bash
+# question — up to 4 options. A bare token is both value and label.
+pingroom live start -c q1 --template question \
+  --prompt "Deploy where?" --option prod:Production --option staging:Staging
+
+# matchup — two sides plus a center score/clock.
+pingroom live start -c game-3 --template matchup \
+  --left ARS:2 --right CHE:1 --center "68'"
+
+# metrics — up to 3 counters.
+pingroom live start -c host-1 --template metrics --metric "CPU:45%" --metric "RPS:1.2k"
+
+# countdown — a large live timer.
+pingroom live start -c win-9 --template countdown --deadline-at 1750003600
+```
+
+`--accent-override` takes `#rrggbb` **or** a bare `rrggbb` (case-insensitive;
+it is normalized to lowercase with the `#` before it is sent). Pass it bare, or
+quote it — an *unquoted* `#` starts a comment in `sh`, `bash` and `zsh`, which
+eats the hex and the rest of the line, and the CLI then exits `2` with
+`option --accent-override needs a value`:
+
+```bash
+pingroom live update -c deploy-42 --accent-override e33122      # ok
+pingroom live update -c deploy-42 --accent-override '#e33122'   # ok
+pingroom live update -c deploy-42 --accent-override #e33122     # shell eats it
+```
+
+**Always `end` a stream.** Terminal `done`/`failed` pings are never rate-limited
+or quota-blocked, precisely so a card can't be metered into hanging open on
+someone's Lock Screen. Abandoned streams are swept after ~15 minutes.
+
+`--template` and `--steps` are fixed when the stream is created; passing them to
+`update`/`end` is a usage error rather than a silent no-op. `pingroom live get`
+(agent token only) reads a stream back — every stored field — so a restarted
+producer reconciles instead of opening a duplicate.
+
+Full protocol: <https://pingroom.io/liveactivities.md>
+
 ## GitHub Actions
 
 ```yaml
@@ -55,8 +226,28 @@ ping doesn't land.
     title: 'CI failed'
     message: '❌ ${{ github.workflow }} failed on ${{ github.ref_name }}'
     action: '2'
+    require-ack: 'true'
+    ack-timeout: '300'
+
+# Gate a job on a human handoff — the step fails (non-zero) on expiry, so the
+# job stops unless someone answers. Read the decision from the step outputs.
+- id: gate
+  uses: pingroom/cli@v0
+  with:
+    token: ${{ secrets.PINGROOM_TOKEN }}
+    message: 'Ship ${{ github.sha }} to production?'
+    handoff: 'true'
+    question: 'true'
+    options: 'deploy:Deploy,hold:Hold'
+    idempotency-key: 'deploy-${{ github.run_id }}'
+    wait: 'true'
+- if: steps.gate.outputs.answer == 'deploy'
+  run: ./deploy-prod.sh
 ```
 
+The handoff action exposes outputs `handoff-id`, `state`, `acknowledged-by`,
+`answer`, and `delivery-state`.
+
 ## GitLab CI
 
 ```yaml
@@ -120,6 +311,81 @@ Approve/Deny default — two options is the lock-screen fast path. `--ttl` sets
 expiry in seconds (default 1h; 30–86400). `--scope room` lets any eligible member
 answer (first tap wins); the default `direct` asks your bound user.
 
+## Handoffs (agent → human)
+
+`handoff` hands a single decision to a specific human — either a simple
+**acknowledge** ("ack to proceed") or a **question** with options. It needs an
+agent token whose consent grants `pingroom:handoffs:create`. Unlike `ask`, a
+handoff targets a user directly (default `me`, the bound user) rather than a
+room, and prints machine-readable `key=value` lines.
+
+```bash
+# Ack handoff — block until the human acknowledges (exit 0), or it expires (3):
+pingroom handoff --token "$PINGROOM_TOKEN" -m "Prod deploy 1.4.0 — ack to proceed" --wait
+
+# Question handoff, blocking, branch in CI on the exit code:
+pingroom handoff --token "$PINGROOM_TOKEN" --wait \
+  -m "Ship 1.4.0 to production?" --question -o deploy:Deploy -o hold:Hold
+# exit 0 = answered (ANY value, incl. 'hold' — a negative human decision is not a failure)
+# exit 3 = expired    exit 4 = cancelled / recipient not ready    exit 1 = error
+```
+
+Flags: `--question` (or any `-o value:label`, 2–4) makes it a question, else it's
+an ack. `--target me|<uuid>` picks the recipient. `--expires-in <s>` (120–86400,
+default 900). `--urgency active|passive`. `--idempotency-key <key>` is sent as
+the `Idempotency-Key` header so network retries collapse to one handoff (the
+server 409s on a key reused with a different payload). `--correlation-id` /
+`--reply-to` / `-d '{...}'` are echoed back. Add `--wait` to long-poll to a
+terminal state; without it the command prints the created handoff and returns 0.
+
+List unresolved Handoffs or bounded recent history without changing the legacy
+question-only `list` command:
+
+```bash
+pingroom handoffs --token "$PINGROOM_TOKEN"                 # open only
+pingroom handoffs --token "$PINGROOM_TOKEN" --state all     # recent, up to 200 per kind
+```
+
+A negative answer (`hold`, `deny`, …) is a **successful** `answered` state and
+exits `0` — branch on the printed `answer=` line, not on the exit code.
+
+## Claude Code integration (get pinged by your agent)
+
+Wire PingRoom into [Claude Code](https://claude.com/claude-code) hooks so your
+agent pings your phone when it finishes — and asks for your approval, on your
+lock screen, before it runs a command. Approve or Deny with a tap; the agent
+waits for your answer and continues.
+
+Print a ready-to-paste config:
+
+```bash
+pingroom hook --print-config
+```
+
+Then set your credentials and merge the printed `hooks` block into
+`~/.claude/settings.json`:
+
+```bash
+export PINGROOM_TOKEN="<your agent token>"   # a room the agent belongs to
+export PINGROOM_ROOM="<room invite code>"
+```
+
+`pingroom hook` reads the Claude Code hook event on stdin and reacts by event:
+
+| Hook event | What happens |
+| --- | --- |
+| `Stop` / `SubagentStop` | Pings the room with the agent's last message (“Claude finished”). |
+| `Notification` | Pings when the agent is idle or waiting for input (permission prompts are skipped — the `PreToolUse` question already covers those). |
+| `SessionEnd` | Pings when a session ends (except `/clear`). |
+| `PreToolUse` | Asks a PingRoom **question** and gates the tool call on your Approve/Deny tap. Which tools are gated is the settings.json `matcher` (default `Bash`) — not the CLI. |
+
+**It always fails open.** If PingRoom is unreachable, the token/room is missing,
+or the question expires, the hook defers to the normal local prompt
+(`permissionDecision: "ask"`) and exits 0. It never auto-approves and never
+blocks the agent. Because the `PreToolUse` hook holds the tool call open while it
+waits for you, give it a generous `timeout` (the printed config uses 960s) and
+tune the approval-question expiry with `--ttl <seconds>` (default 900).
+
 For a fully typed client, use [`@pingroom/sdk`](https://www.npmjs.com/package/@pingroom/sdk).
 See <https://pingroom.io/connect-mcp.md> to connect Cursor, Claude Desktop, or Claude Code.