@pingroom/cli 0.7.2 → 0.7.3

package/lib/help.js

@@ -0,0 +1,305 @@
+// All --help output. One section per command plus intro/shared/tail, so
+// `pingroom <command> --help` can print a focused excerpt (see commandHelp) and
+// `pingroom --help` still prints the historical single blob.
+//
+// Nothing here is decorative: the subprocess tests assert this text verbatim.
+
+import { BUILTIN_API, DEFAULT_API } from './constants.js';
+
+// The help text lives as one section per command plus intro/shared/tail, so
+// `pingroom <command> --help` can print a focused excerpt (see commandHelp).
+// The full HELP below joins them in the historical order — `pingroom --help`
+// output is byte-identical to the pre-split single blob.
+export const HELP_INTRO = `pingroom — send a ping, or ask a human a question, from CI/scripts/agents
+
+Usage:
+  pingroom <command> [options]
+
+Commands:
+  ping     Send a ping to a room (webhook URL, or agent token + room)
+  ask      Ask a human a question; with --wait, block until they answer
+  watch    Block until a question resolves and print the outcome (alias: await)
+  list     List the agent's questions by state
+  cancel   Withdraw a pending question
+  handoff  Hand a decision (ack or question) to a specific human; with --wait,
+           block until they acknowledge or answer
+  handoffs List the agent's open handoffs or bounded recent history
+  listen   Block on pings arriving in your rooms and print them as they land
+  live     Drive a live progress card on the lock screen (Live Activity)
+  hook     Claude Code hook: ping on Stop/Notification, and route tool
+           permission prompts to a PingRoom question you answer from your phone
+  mcp      Print the remote MCP endpoint and setup for Claude Code, Cursor, and
+           Claude Desktop
+  activate Retry Agent Inbox activation with the saved QR-paired credential
+  config   Read/write local settings (config list | get <key> | set <key> <val>)
+  logout   Forget the stored credential`;
+
+export const HELP_PING = `ping options:
+  -m, --message <text>   Ping body text (required)
+  -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 object, 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)
+      --attach <path>    Attach a file (md/pdf/html/txt/jpg/jpeg/png/zip, <= 5 MiB);
+                         repeat for up to 4. Requires --token and a Pro account
+  -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)`;
+
+export const HELP_ASK = `ask options (agent token required):
+  -p, --prompt <text>    The question a human reads (required)
+  -o, --option <v:label[:style]>
+                         An answer option (style: primary|danger|default);
+                         repeat for 2–4. Omit for Approve/Deny
+  -c, --context <text>   Secondary line, e.g. a build number (<= 40 chars)
+      --scope <s>        Who answers: 'direct' (default) or 'room'
+      --target <uuid>    For --scope direct: a specific room member
+      --ttl <seconds>    Expiry; omit for the server default (1h; 30..86400)
+      --text-input <ph>  Invite a short typed answer; <ph> is the placeholder
+      --text-max <n>     Max typed-answer length (1..60)
+      --wait             Block until answered/expired/cancelled
+      --timeout <sec>    Per long-poll hold with --wait/watch (0–30, default 25)
+  -d, --data <json>      Structured data object echoed back on the answer
+      --correlation-id <id>  Opaque id echoed on every read of this question
+      --reply-to <id>    Id of the ping this question replies to
+      --room <code>      Room invite code (required for ask)
+      --github-output <path>  Safely append question outputs for GitHub Actions`;
+
+export const HELP_LIST = `list options:
+      --state <s>        pending | answered | expired | cancelled | all`;
+
+export const HELP_HANDOFF = `handoff options (agent token required; consent scope pingroom:handoffs:create):
+  -m, --message <text>   The prompt a human reads (required)
+      --question         Make it a question (else a simple acknowledge). Also
+                         implied whenever one or more --option is given.
+  -o, --option <v:label> A question option; repeat for 2–4. Requires --question.
+      --target <id>      Recipient: 'me' (default) or a specific user uuid
+      --expires-in <s>   Expiry in seconds (120..86400, default 900)
+      --urgency <u>      'active' (default) or 'passive'
+      --idempotency-key <key>  Dedupe key; retries reuse it (Idempotency-Key)
+      --correlation-id <id>    Opaque id echoed on every read of this handoff
+      --reply-to <id>    Opaque reply-to id echoed back
+  -d, --data <json>      Structured data object echoed on the handoff
+      --wait             Block until acked / answered / expired / cancelled
+      --timeout <sec>    Per long-poll hold with --wait (0–20, server caps 25)
+      --github-output <path>  Safely append handoff outputs for GitHub Actions`;
+
+export const HELP_HANDOFFS = `handoffs options (agent token required; consent scope pingroom:handoffs:create):
+      --state <s>        open | all (default open)`;
+
+export const HELP_LISTEN = `listen options (agent token required; consent scope pingroom:notifications:read):
+      --timeout <sec>    Per long-poll hold (0-30, default 25)
+      --limit <n>        Max pings per batch (1-100, default 50)
+      --from <id>        Start after this ping id instead of "now"
+      --once             Print one batch and exit instead of blocking forever
+      --json             One JSON object per line instead of a readable line`;
+
+export const HELP_LIVE = `live <start|update|end|get> options (agent token, or a room webhook):
+  -c, --correlation-id <id>  The stream key — reuse it for every ping (required)
+      --template <name>      start only: status | steps | progress | metrics |
+                             countdown | decision | matchup (fixed at creation;
+                             'decision' is the app's name for the wire id
+                             'question', which is still accepted)
+      --category <name>      start only: status | steps | alert. Legacy, but
+                             'alert' has no template equivalent and is the only
+                             way to start time-sensitive without --require-ack
+      --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 (decision template)
+      --option <value:label> Repeatable, up to 4 (decision template). A bare
+                             token is both value and label
+      --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
+  -d, --data <json>          Structured data object carried on this frame
+  -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
+      --room <code>          Room invite code (used with --token)
+  -w, --webhook <url>        Room webhook URL instead of a token`;
+
+export const HELP_HOOK = `hook options (reads a Claude Code event; defaults to stored credentials/config):
+      --room <code>      Room invite code (or env/config/paired room)
+      --ttl <seconds>    Approval-question expiry for PreToolUse (default 900)
+      --quiet            Suppress the informational stderr lines
+      --print-config     Print a ready-to-paste ~/.claude/settings.json block`;
+
+export const HELP_MCP = `mcp:
+  pingroom mcp                     Print the endpoint and client setup snippets
+  pingroom mcp add claude-code     Print the Claude Code setup command
+                                   (output-only; does not change client config)`;
+
+export const HELP_ACTIVATE = `activate:
+  pingroom activate                Send one test Question to your phone to prove the
+                                   saved QR-paired credential works (optional —
+                                   connecting no longer does this for you)`;
+
+export const HELP_CONFIG = `config options:
+  pingroom config list              Print the stored settings
+  pingroom config get <key>         Print one setting
+  pingroom config set <key> <val>   Store a setting (an empty value clears it)
+  Keys: default_room, api_url`;
+
+export const HELP_SHARED = `Shared:
+      --token <token>    Agent access token (or env PINGROOM_TOKEN)
+      --api <url>        API base URL (default ${DEFAULT_API}; env PINGROOM_API_URL)
+      --json             Print the raw JSON response
+  -h, --help             Show this help
+  -v, --version          Show the CLI version`;
+
+export const HELP_TAIL = `Connecting:
+  Install globally, then run with no arguments:
+    npm install --global @pingroom/cli
+    pingroom
+
+  Or connect without installing globally:
+    npx --yes @pingroom/cli
+
+  It prints a QR code you scan with the PingRoom app — you pick the account and
+  the rooms it may reach there (one, several, or all of them). Once paired, it
+  saves the credential and you are done; connecting sends nothing to your phone.
+  Run "pingroom activate" if you want to prove the round-trip with one test
+  Question. The emailed-code fallback stores no server-side delivery room.
+  "config set default_room" enables room-addressed commands, but private
+  Inbox/Handoff delivery requires QR pairing.
+  There is no "login" command: being unconnected is a state the tool resolves,
+  not one you have to discover.
+
+  The credential is written to ~/.pingroom/credentials.json (mode 0600, in a
+  0700 directory). PINGROOM_HOME overrides that directory. PINGROOM_TOKEN in the
+  environment ALWAYS wins over the stored credential, so CI is unaffected.
+  "pingroom logout" forgets it.
+
+  Settings precedence, highest first:
+    explicit flag  >  env var  >  ~/.pingroom/config.json  >  the paired
+    credential  >  built-in default
+  So --room beats PINGROOM_ROOM beats "config set default_room", and --api beats
+  PINGROOM_API_URL beats "config set api_url" beats the host you paired against,
+  beats ${BUILTIN_API}. A stored credential is bound to the origin it was paired
+  against: an API override may change the path on that origin, but a different
+  origin is refused before the token is sent. To target another origin
+  intentionally, provide that host's token with --token or PINGROOM_TOKEN.
+
+  Non-interactive shells (CI, pipes) never prompt and never draw a QR: set
+  PINGROOM_TOKEN there instead.
+
+Examples:
+  pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"
+  pingroom ping --token "$PINGROOM_TOKEN" --room ab12cd -m "Release shipped"
+
+  # Link ping — a tappable button that opens a URL:
+  pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Build 512 ready" \\
+    --url https://ci.example.com/builds/512 --button-label "Open build"
+
+  # Gate a deploy on a human tap — the chosen value prints to stdout:
+  if [ "$(pingroom ask --token "$T" --room ab12cd --wait \\
+        -p 'Deploy 1.4.0 to production?')" = approve ]; then ./deploy.sh; fi
+
+  # Multi-option question, blocking:
+  pingroom ask --token "$T" --room ab12cd --scope room --wait \\
+    -p 'Which environment?' -o prod:Production -o staging:Staging
+
+  pingroom list --token "$T" --state pending
+  pingroom watch --token "$T" q_01H...   # block on an existing question
+  pingroom cancel --token "$T" q_01H...
+
+  # Hand a deploy decision to yourself and block on the acknowledgement:
+  pingroom handoff --token "$T" -m "Prod deploy 1.4.0 — ack to proceed" --wait
+
+  # A blocking question handed to a specific human; branch in CI on exit code:
+  pingroom handoff --token "$T" -m "Ship 1.4.0?" --question \\
+    -o deploy:Deploy -o hold:Hold --wait
+  # -> exit 0 (answered, any value incl. 'hold'); 3 expired; 4 recipient-not-ready
+
+  pingroom handoffs --token "$T" --state all   # recent history (up to 200/kind)
+
+  # A live deploy card on everyone's lock screen — one stream, three calls:
+  pingroom live start --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    --template steps --steps "Build,Test,Stage,Ship" -t "Deploy 2.1.0"
+  pingroom live update --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    --step 2 -m "Smoke tests green"
+  pingroom live end --token "$T" --room ab12cd -c "deploy-$GITHUB_RUN_ID" \\
+    -m "Live on production"
+  # ...or end it as a failure, which still delivers one completion alert:
+  #   pingroom live end ... --failed -m "Rollback triggered"
+
+  # Connect Claude Code hooks to your paired credential (no env vars needed):
+  pingroom hook --print-config
+
+  # Connect an MCP client through browser OAuth (no API key needed):
+  pingroom mcp
+
+Security:
+  Prefer the env vars (PINGROOM_WEBHOOK_URL / PINGROOM_TOKEN) over passing
+  secrets as --webhook / --token flags: argv is visible to other users via the
+  process table (ps) and may be captured in shell history. URLs must use https
+  (loopback http is allowed for local dev).
+
+  A paired credential is only sent to its recorded API origin. --api,
+  PINGROOM_API_URL and config.api_url cannot redirect that stored bearer to a
+  different origin; provide an explicit --token or PINGROOM_TOKEN to override.
+
+Exit codes: 0 on success (answered / acked), 1 on error (network/auth/5xx),
+2 on bad usage, 3 when a handoff or question expired, 4 when it was cancelled
+or the recipient was not ready (409 recipient_not_ready). A question answered
+with ANY value — including a negative one like 'hold' or 'deny' — exits 0: a
+human decision is not an infrastructure failure.`;
+
+export const HELP = [
+  HELP_INTRO, HELP_PING, HELP_ASK, HELP_LIST, HELP_HANDOFF, HELP_HANDOFFS,
+  HELP_LISTEN, HELP_LIVE, HELP_HOOK, HELP_MCP, HELP_ACTIVATE, HELP_CONFIG,
+  HELP_SHARED, HELP_TAIL,
+].join('\n\n');
+
+// Sections for `pingroom <command> --help`. watch/cancel/logout have no block
+// of their own in the full help, so they get a minimal one here.
+export const COMMAND_HELP_SECTIONS = {
+  ping: HELP_PING,
+  ask: HELP_ASK,
+  watch: `watch:
+  pingroom watch <question-id>      Block until the question resolves and
+                                    print the outcome
+      --timeout <sec>    Per long-poll hold (0–30, default 25)`,
+  cancel: `cancel:
+  pingroom cancel <question-id>     Withdraw a pending question`,
+  list: HELP_LIST,
+  handoff: HELP_HANDOFF,
+  handoffs: HELP_HANDOFFS,
+  listen: HELP_LISTEN,
+  live: HELP_LIVE,
+  hook: HELP_HOOK,
+  activate: HELP_ACTIVATE,
+  config: HELP_CONFIG,
+  logout: `logout:
+  pingroom logout                   Forget the stored credential (PINGROOM_TOKEN
+                                    in the environment is unaffected)`,
+};
+
+// config and logout are local-only commands that reject --token/--api (and,
+// for logout, --json), so their help gets a footer that only lists what they
+// actually accept instead of the full shared block.
+export const COMMAND_HELP_FOOTERS = {
+  config: `Shared:
+      --json             Print the raw JSON response
+  -h, --help             Show this help`,
+  logout: `Shared:
+  -h, --help             Show this help`,
+};
+
+// `<command> --help`: that command's section plus the shared flags, instead of
+// the full reference `pingroom --help` / `pingroom help` still print.
+export function commandHelp(name) {
+  const section = COMMAND_HELP_SECTIONS[name];
+  return section ? `${section}\n\n${COMMAND_HELP_FOOTERS[name] ?? HELP_SHARED}` : HELP;
+}

package/lib/http.js

@@ -0,0 +1,214 @@
+// Everything that touches the network, plus the URL safety rule that decides
+// whether a bearer token may ride along at all.
+
+import { EXIT } from './constants.js';
+import { fail, stripControlChars } from './util.js';
+
+/**
+ * The fixes that live on THIS side of the wire. The server's message always
+ * leads; these are appended only for the codes where the operator would
+ * otherwise have no way to know what to do next, and where the answer is a
+ * local action rather than "try again".
+ */
+const API_HINTS = {
+  room_not_granted:
+    'That room is outside the grant this agent was given. Add it under Connected Agents in the PingRoom app, or run "pingroom" to reconnect and pick it.',
+  insufficient_scope:
+    'This credential was approved before the command needed that permission. Run "pingroom" to reconnect and re-approve.',
+  no_room_configured:
+    'This agent has no delivery room. Pick one under Connected Agents in the PingRoom app.',
+};
+
+/**
+ * What to print when an API call fails: the server's own wording, plus the one
+ * thing that would fix it when we know one.
+ */
+export function apiDetail(res, json) {
+  // The server's wording is untrusted text headed for the terminal — strip
+  // escapes so a hostile API can't smuggle ANSI (same threat model as pair_url).
+  const base = stripControlChars(
+    (json && (json.message || json.error || json.code)) || `HTTP ${res ? res.status : 'error'}`,
+  );
+  const hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  return hint ? `${base}\n  ${hint}` : base;
+}
+
+// True when a URL is safe to attach a bearer token or webhook secret to: https,
+// or http on loopback so local dev against http://localhost still works.
+// Split out of requireSafeUrl for the `hook` command, which must apply the same
+// rule but fails open (it defers instead of exiting — see hook()).
+export function isSafeUrl(raw) {
+  let u;
+  try {
+    u = new URL(raw);
+  } catch {
+    return false;
+  }
+  const isLoopback = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
+  return u.protocol === 'https:' || (u.protocol === 'http:' && isLoopback);
+}
+
+// Refuse to send a bearer token or webhook secret over cleartext http. A
+// loopback host is allowed so local dev against http://localhost still works.
+export function requireSafeUrl(kind, raw) {
+  try {
+    new URL(raw);
+  } catch {
+    fail(`${kind} is not a valid URL`, EXIT.USAGE);
+  }
+  if (!isSafeUrl(raw)) {
+    fail(`${kind} must use https (refusing to send credentials over cleartext)`, EXIT.USAGE);
+  }
+  return raw;
+}
+
+// `soft: true` returns { error } instead of exiting on a transport failure. The
+// bounded pairing and activation loops use it so a single DNS blip or dropped
+// connection does not discard an otherwise recoverable human workflow. Every
+// other caller keeps the hard exit.
+export async function httpJson(method, url, { body, headers = {}, soft = false, signal } = {}) {
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        Accept: 'application/json',
+        ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+        ...headers,
+      },
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      ...(signal ? { signal } : {}),
+    });
+  } catch (err) {
+    if (soft) return { res: null, text: '', json: null, error: err };
+    fail(`network error: ${err.message}`);
+  }
+
+  let text;
+  try {
+    text = await res.text();
+  } catch (err) {
+    // A connection dropped mid-body throws here, not at fetch().
+    if (soft) return { res: null, text: '', json: null, error: err };
+    fail(`network error: ${err.message}`);
+  }
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+
+  return { res, text, json };
+}
+
+// The extensions the attachment endpoint accepts. Mirrored here so a typo is a
+// local usage error instead of a 422 after the bytes have already been sent.
+// Keep in lockstep with laravel config/attachments.php `allowed_extensions`.
+const ATTACHMENT_EXTENSIONS = ['md', 'pdf', 'html', 'txt', 'jpg', 'jpeg', 'png', 'zip'];
+const ATTACHMENT_MAX_BYTES = 5 * 1024 * 1024;
+const ATTACHMENT_MAX_COUNT = 4;
+const ATTACHMENT_MIME = {
+  md: 'text/markdown',
+  pdf: 'application/pdf',
+  html: 'text/html',
+  txt: 'text/plain',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  zip: 'application/zip',
+};
+
+/**
+ * Upload each --attach path and return the ids in flag order. Bytes go up as
+ * multipart; only the resulting ids ride the ping body. An id we never manage
+ * to attach expires server-side after 24h, so a mid-run failure leaks nothing
+ * permanent.
+ */
+export async function uploadAttachments(paths, apiBase, token) {
+  if (paths.length > ATTACHMENT_MAX_COUNT) {
+    fail(`--attach accepts at most ${ATTACHMENT_MAX_COUNT} files`, EXIT.USAGE);
+  }
+
+  const { readFile, stat } = await import('node:fs/promises');
+  const { basename, extname } = await import('node:path');
+  const ids = [];
+
+  for (const path of paths) {
+    const name = basename(path);
+    const ext = extname(name).slice(1).toLowerCase();
+    if (!ATTACHMENT_EXTENSIONS.includes(ext)) {
+      fail(`--attach ${name}: only ${ATTACHMENT_EXTENSIONS.join(', ')} files are supported`, EXIT.USAGE);
+    }
+
+    let info;
+    try {
+      info = await stat(path);
+    } catch {
+      fail(`--attach ${path}: file not found`, EXIT.USAGE);
+    }
+    if (!info.isFile()) fail(`--attach ${path}: not a file`, EXIT.USAGE);
+    if (info.size < 1) fail(`--attach ${name}: file is empty`, EXIT.USAGE);
+    if (info.size > ATTACHMENT_MAX_BYTES) {
+      fail(`--attach ${name}: file exceeds the 5 MiB limit`, EXIT.USAGE);
+    }
+
+    const body = new FormData();
+    body.append('file', new Blob([await readFile(path)], { type: ATTACHMENT_MIME[ext] }), name);
+
+    let res;
+    try {
+      // Not httpJson: that helper JSON-encodes the body and would strip the
+      // multipart boundary the runtime generates for us.
+      res = await fetch(`${apiBase}/api/agent/attachments`, {
+        method: 'POST',
+        headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
+        body,
+      });
+    } catch (err) {
+      fail(`network error uploading ${name}: ${err.message}`);
+    }
+
+    const text = await res.text().catch(() => '');
+    let json = null;
+    try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+
+    if (res.status === 402) {
+      fail(`--attach ${name}: ping attachments are a Pro feature`, EXIT.USAGE);
+    }
+    if (!res.ok || !json?.attachment?.id) {
+      const detail = apiDetail(res, json);
+      fail(`upload failed for ${name}: ${detail}`);
+    }
+
+    ids.push(json.attachment.id);
+  }
+
+  return ids;
+}
+
+// A minimal HTTP helper for the hook path that THROWS instead of calling fail(),
+// so every failure funnels into a fail-open decision. Mirrors httpJson's header
+// handling but leaves control flow to the caller.
+export async function hookFetch(method, url, { body, token } = {}) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Accept: 'application/json',
+      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+  });
+  const text = await res.text();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON response */ }
+  if (!res.ok) {
+    throw new Error(apiDetail(res, json));
+  }
+  return json;
+}
+
+export function retryAfterMs(response) {
+  const raw = response?.headers?.get('retry-after')?.trim();
+  if (!raw) return null;
+  if (/^\d+(?:\.\d+)?$/.test(raw)) return Number(raw) * 1000;
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}