@pingroom/cli 0.7.2 → 0.7.4

package/lib/parser.js

@@ -0,0 +1,218 @@
+// One argv parser per command surface, all built from the same table-driven
+// factory. Splitting them out keeps the flag vocabulary in one file.
+
+import { EXIT } from './constants.js';
+import { fail } from './util.js';
+
+/**
+ * Build an argv parser from a flag table. Every command parser runs the same
+ * loop; only the tables differ:
+ *   aliases              flag or alias -> canonical args key
+ *   booleans             keys that take no value
+ *   repeatable           keys collected into an array (the flag may repeat)
+ *   bareDashIsPositional whether a lone `-` collects into `_` (the question-
+ *                        style parsers) or fails as an unknown option (ping,
+ *                        live)
+ * Unknown flags always fail as a usage error; bare words collect into `_`.
+ */
+export function makeParser({ aliases, booleans, repeatable = [], bareDashIsPositional = false }) {
+  const booleanKeys = new Set(booleans);
+  const repeatableKeys = new Set(repeatable);
+  function parse(argv) {
+    const args = { _: [] };
+    for (let i = 0; i < argv.length; i++) {
+      const token = argv[i];
+      // Object.hasOwn, not aliases[token]: a bare lookup walks the prototype
+      // chain, so `constructor` / `toString` / `__proto__` in flag position
+      // resolve to a truthy inherited value, get treated as an option, and
+      // swallow the next argument instead of failing as an unknown flag.
+      const key = Object.hasOwn(aliases, token) ? aliases[token] : undefined;
+      if (key && booleanKeys.has(key)) {
+        args[key] = true;
+      } else if (key) {
+        const value = argv[++i];
+        if (value === undefined) {
+          fail(`option ${token} needs a value`, EXIT.USAGE);
+        }
+        if (repeatableKeys.has(key)) (args[key] ||= []).push(value);
+        else args[key] = value;
+      } else if (token.startsWith('-') && !(bareDashIsPositional && token === '-')) {
+        fail(`Unknown option: ${token}`, EXIT.USAGE);
+      } else {
+        args._.push(token);
+      }
+    }
+    return args;
+  }
+  // The accepted flag vocabulary, published on the parser itself. The release
+  // gate reads it to assert that every flag `action.yml` hands the CLI is one
+  // the matching parser accepts — the check that would have caught `ask
+  // --github-output` being wired into the handoff parser only.
+  parse.flags = new Set(Object.keys(aliases));
+  return parse;
+}
+
+export const parseArgs = makeParser({
+  aliases: {
+    '-m': 'message', '--message': 'message',
+    '-t': 'title', '--title': 'title',
+    '-a': 'action', '--action': 'action',
+    '-d': 'data', '--data': 'data',
+    '-w': 'webhook', '--webhook': 'webhook',
+    '--url': 'url',
+    '--button-label': 'button_label',
+    '--require-ack': 'require_ack',
+    '--urgent': 'urgent',
+    '--ack-timeout': 'ack_timeout',
+    '--attach': 'attach',
+    '--token': 'token',
+    '--room': 'room',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['require_ack', 'urgent', 'json', 'help'],
+  repeatable: ['attach'],
+});
+
+// Parser for the question commands: supports repeatable --option and a trailing
+// positional (a question id). Unknown flags fail like the ping parser.
+export const parseQArgs = makeParser({
+  aliases: {
+    '-p': 'prompt', '--prompt': 'prompt',
+    '-o': 'option', '--option': 'option',
+    '-c': 'context', '--context': 'context',
+    '--scope': 'scope',
+    '--target': 'target',
+    '--ttl': 'ttl',
+    '-d': 'data', '--data': 'data',
+    '--correlation-id': 'correlation_id',
+    '--reply-to': 'reply_to',
+    '--text-input': 'text_input',
+    '--text-max': 'text_max',
+    '--timeout': 'timeout',
+    '--state': 'state',
+    '--limit': 'limit',
+    '--from': 'from',
+    '--once': 'once',
+    '--github-output': 'github_output',
+    '--token': 'token',
+    '--room': 'room',
+    '--api': 'api',
+    '--wait': 'wait',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['wait', 'json', 'help', 'once'],
+  repeatable: ['option'],
+  bareDashIsPositional: true,
+});
+
+// Parser for `handoff`: --message plus repeatable --option, boolean --question,
+// and the handoff-specific flags. Unknown flags fail like the other parsers.
+export const parseHandoffArgs = makeParser({
+  aliases: {
+    '-m': 'message', '--message': 'message',
+    '--question': 'question',
+    '-o': 'option', '--option': 'option',
+    '--target': 'target',
+    '--expires-in': 'expires_in',
+    '--urgency': 'urgency',
+    '--idempotency-key': 'idempotency_key',
+    '--correlation-id': 'correlation_id',
+    '--reply-to': 'reply_to',
+    '-d': 'data', '--data': 'data',
+    '--timeout': 'timeout',
+    '--github-output': 'github_output',
+    '--token': 'token',
+    '--api': 'api',
+    '--wait': 'wait',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['question', 'wait', 'json', 'help'],
+  repeatable: ['option'],
+  bareDashIsPositional: true,
+});
+
+// Parser for `live`: a leading subcommand (start|update|end|get) plus the
+// live-status flags. Unknown flags fail like the other parsers.
+export const parseLiveArgs = makeParser({
+  aliases: {
+    '-c': 'correlation_id', '--correlation-id': 'correlation_id',
+    '-t': 'title', '--title': 'title',
+    '-m': 'message', '--message': 'message',
+    '--template': 'template',
+    '--category': 'category',
+    '--progress': 'progress',
+    '--step': 'step',
+    '--steps': 'steps',
+    '--metric': 'metric',
+    '--deadline-at': 'deadline_at',
+    '--eta-at': 'eta_at',
+    '--prompt': 'prompt',
+    '--option': 'option',
+    '--left': 'left',
+    '--right': 'right',
+    '--center': 'center',
+    '--accent-override': 'accent_override',
+    '--failed': 'failed',
+    '-a': 'action', '--action': 'action',
+    '-d': 'data', '--data': 'data',
+    '--require-ack': 'require_ack',
+    // No --urgent here on purpose. A STREAM starts time-sensitive via
+    // `--category alert` (fixed at creation); the live-status endpoint does not
+    // accept `is_urgent`, so the flag would parse and then be silently dropped.
+    '--ack-timeout': 'ack_timeout',
+    '-w': 'webhook', '--webhook': 'webhook',
+    '--token': 'token',
+    '--room': 'room',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['require_ack', 'json', 'help', 'failed'],
+  repeatable: ['metric', 'option'],
+});
+
+export const parseHookArgs = makeParser({
+  aliases: {
+    '--room': 'room',
+    '--ttl': 'ttl',
+    '--quiet': 'quiet',
+    '--print-config': 'print_config',
+    '--token': 'token',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['quiet', 'print_config', 'json', 'help'],
+  bareDashIsPositional: true,
+});
+
+// config/logout/handoffs used to share parseQArgs, which silently accepted and
+// ignored flags those commands never read (`logout --wait --prompt x`). Minimal
+// tables instead, so an irrelevant flag is a usage error like everywhere else.
+export const parseConfigArgs = makeParser({
+  aliases: { '--json': 'json', '-h': 'help', '--help': 'help' },
+  booleans: ['json', 'help'],
+  bareDashIsPositional: true,
+});
+
+export const parseLogoutArgs = makeParser({
+  aliases: { '-h': 'help', '--help': 'help' },
+  booleans: ['help'],
+  bareDashIsPositional: true,
+});
+
+export const parseHandoffsArgs = makeParser({
+  aliases: {
+    '--state': 'state',
+    '--token': 'token',
+    '--api': 'api',
+    '--json': 'json',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['json', 'help'],
+  bareDashIsPositional: true,
+});

package/lib/render.js

@@ -0,0 +1,174 @@
+// Turning flag strings into wire objects, and wire objects back into the exact
+// lines this CLI prints. Pure functions with no I/O beyond stdout/stderr, which
+// is what makes them unit-testable without a subprocess (see test/render.test.mjs).
+
+import { EXIT } from './constants.js';
+import { fail, stripControlChars } from './util.js';
+
+// The templates the server accepts on `live start`. Mirrored here so a typo is
+// a local usage error instead of a 422 from the API. Keep in lockstep with the
+// --template line in HELP and with LIVE_ACTIVITY_TEMPLATES.md.
+export const LIVE_TEMPLATES = ['status', 'steps', 'progress', 'metrics', 'countdown', 'question', 'matchup'];
+
+/**
+ * Names the API does not take, folded onto the wire id it does.
+ *
+ * The `question` template is labelled **Decision** everywhere a person sees it,
+ * so it is never confused with PingRoom's first-class Question protocol — that
+ * one is answered through `pingroom ask`, carries a real Question id, and this
+ * template does not. The wire id stayed `question`, so someone who reads
+ * "Decision" in the app and types it would otherwise get a usage error for
+ * using the only name they have been shown.
+ */
+export const LIVE_TEMPLATE_ALIASES = { decision: 'question' };
+
+/** The wire id for a template name a human typed, or the name unchanged. */
+export function canonicalTemplate(name) {
+  return LIVE_TEMPLATE_ALIASES[name] ?? name;
+}
+
+/** What we offer in help and errors: the alias leads, since it is what the app shows. */
+export const LIVE_TEMPLATE_NAMES = ['status', 'steps', 'progress', 'metrics', 'countdown', 'decision', 'matchup'];
+
+// "label:value" -> {label, value}. Only the first colon splits.
+export function buildMetrics(list) {
+  if (!list || list.length === 0) return undefined;
+  return list.map((spec) => {
+    const idx = spec.indexOf(':');
+    if (idx <= 0) fail(`--metric must be "label:value" (got "${spec}")`, EXIT.USAGE);
+    return { label: spec.slice(0, idx), value: spec.slice(idx + 1) };
+  });
+}
+
+// "value:label" -> {value, label}; a bare token is both. Matches the `ask`
+// command's option syntax minus `style`, which live_status options don't carry.
+export function buildLiveOptions(list) {
+  if (!list || list.length === 0) return undefined;
+  return list.map((spec) => {
+    const idx = spec.indexOf(':');
+    if (idx < 0) return { value: spec, label: spec };
+    if (idx === 0) fail(`--option needs a value before the colon (got "${spec}")`, EXIT.USAGE);
+    return { value: spec.slice(0, idx), label: spec.slice(idx + 1) };
+  });
+}
+
+// "label:value" -> {label, value}, for --left / --right on the matchup template.
+export function buildSide(spec, flag) {
+  if (spec === undefined) return undefined;
+  const idx = spec.indexOf(':');
+  if (idx <= 0) fail(`${flag} must be "label:value" (got "${spec}")`, EXIT.USAGE);
+  return { label: spec.slice(0, idx), value: spec.slice(idx + 1) };
+}
+
+// The server accepts #rrggbb with or without the leading #; normalize to one
+// form so a shell that ate the # (unquoted) still produces a valid payload.
+export function normalizeAccent(raw) {
+  if (raw === undefined) return undefined;
+  const hex = raw.trim().replace(/^#/, '');
+  if (!/^[0-9A-Fa-f]{6}$/.test(hex)) {
+    fail(`--accent-override must be a 6-digit hex color (got "${raw}")`, EXIT.USAGE);
+  }
+  return `#${hex.toLowerCase()}`;
+}
+
+// value:label -> {value, label}. Labels may contain colons (only the first
+// splits). A bare token is both value and label. Omit all for Approve/Deny.
+export function buildOptions(list) {
+  if (!list || list.length === 0) return undefined;
+  return list.map((spec) => {
+    const idx = spec.indexOf(':');
+    const value = idx === -1 ? spec : spec.slice(0, idx);
+    let label = idx === -1 ? spec : spec.slice(idx + 1);
+    if (!value) fail(`--option must be "value", "value:label" or "value:label:style" (got "${spec}")`, EXIT.USAGE);
+    // A trailing :primary|:danger|:default segment styles the button; any other
+    // trailing segment stays part of the label (labels may contain colons).
+    let style;
+    const lastColon = label.lastIndexOf(':');
+    if (lastColon !== -1) {
+      const candidate = label.slice(lastColon + 1);
+      if (candidate === 'primary' || candidate === 'danger' || candidate === 'default') {
+        style = candidate;
+        label = label.slice(0, lastColon);
+      }
+    }
+    return style ? { value, label, style } : { value, label };
+  });
+}
+
+export function exitForState(state) {
+  switch (state) {
+    case 'answered': return EXIT.OK;
+    case 'expired': return EXIT.EXPIRED;
+    case 'cancelled': return EXIT.CANCELLED;
+    default: return EXIT.ERROR;
+  }
+}
+
+// Print the outcome. On `answered`, the chosen value (or typed text) goes to
+// stdout so `$(pingroom ask --wait ...)` captures it; other outcomes report to
+// stderr and leave stdout empty.
+export function printResolution(q) {
+  if (q.state === 'answered') {
+    const out = q.answer && (q.answer.text || q.answer.value) || '';
+    process.stdout.write(`${out}\n`);
+  } else {
+    process.stderr.write(`pingroom: question ${q.state}\n`);
+  }
+}
+
+/** One readable line per incoming ping. */
+export function formatIncoming(item) {
+  const room = item?.room?.name || item?.room?.code || '?';
+  const body = stripControlChars(item?.message ?? '');
+  const marks = [];
+  if (item?.correlation_id) marks.push(`corr=${stripControlChars(item.correlation_id)}`);
+  if (item?.reply_to) marks.push(`reply_to=${stripControlChars(item.reply_to)}`);
+  if (item?.question) marks.push('question');
+  if (Array.isArray(item?.attachments) && item.attachments.length) {
+    marks.push(`${item.attachments.length} attachment${item.attachments.length === 1 ? '' : 's'}`);
+  }
+  const suffix = marks.length ? `  (${marks.join(' · ')})` : '';
+  return `[${stripControlChars(room)}] ${body}${suffix}`;
+}
+
+// Terminal wire states across both kinds. ack: open→acked|expired.
+// question: pending→answered|expired|cancelled. `open`/`pending` are the only
+// non-terminal states, so a wait loop against these always terminates.
+export const HANDOFF_PENDING = new Set(['open', 'pending']);
+
+// Map a terminal handoff state to an exit code. A `question` answered with ANY
+// value is a success (0) — a negative human decision ('hold'/'deny') is NOT an
+// infra failure. `acked` is likewise 0. `expired` is a distinct 3 so CI can
+// branch; `cancelled` shares 4 with recipient_not_ready.
+export function exitForHandoffState(state) {
+  switch (state) {
+    case 'acked': return EXIT.OK;
+    case 'answered': return EXIT.OK;
+    case 'expired': return EXIT.EXPIRED;
+    case 'cancelled': return EXIT.CANCELLED;
+    default: return EXIT.ERROR;
+  }
+}
+
+// Print a machine-readable summary of a handoff: id, state, delivery-state, and
+// the answer value / acked-by when present, one `key=value` per line to stdout.
+export function printHandoff(h) {
+  const lines = [`id=${h.id ?? ''}`, `state=${h.state ?? ''}`];
+  if (h.delivery_state != null) lines.push(`delivery-state=${h.delivery_state}`);
+  if (h.correlation_id) lines.push(`correlation-id=${h.correlation_id}`);
+  if (h.state === 'answered') {
+    const value = h.answer && (h.answer.value ?? h.answer.text) || '';
+    lines.push(`answer=${value}`);
+  }
+  if (h.state === 'acked') {
+    // The Handoff API returns a privacy-aware actor object. Only expose its id
+    // in the machine-readable CLI/GitHub Action output; a redacted actor yields
+    // an empty value instead of the unhelpful "[object Object]" string.
+    const ackerId = h.acked_by && typeof h.acked_by === 'object'
+      ? h.acked_by.id
+      : h.acked_by;
+    lines.push(`acked-by=${ackerId ?? ''}`);
+    if (h.acked_at) lines.push(`acked-at=${h.acked_at}`);
+  }
+  process.stdout.write(`${lines.join('\n')}\n`);
+}

package/lib/util.js

@@ -0,0 +1,109 @@
+// Small primitives every other module leans on: exiting, sleeping, sanitizing
+// untrusted text, and the local validations that turn a would-be 422 into a
+// usage error.
+
+import { EXIT } from './constants.js';
+
+export function fail(message, code = EXIT.ERROR) {
+  process.stderr.write(`pingroom: ${message}\n`);
+  process.exit(code);
+}
+
+/**
+ * True when it is safe to prompt / draw a QR. Both streams must be a TTY: a
+ * piped stdin cannot answer a prompt and a piped stdout would capture the QR as
+ * garbage.
+ *
+ * The override is deliberately double-locked (internal-looking name AND
+ * NODE_ENV=test) and not documented in --help. A single well-known env var
+ * shipping in the published binary is one stray `export` away from making a CI
+ * job prompt into the void and poll for the full 15-minute pairing window
+ * instead of failing in a second.
+ */
+export function isInteractive() {
+  if (process.env.PINGROOM_INTERNAL_TEST_TTY === '1' && process.env.NODE_ENV === 'test') return true;
+  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+// Drop C0/C1 control characters before echoing server-supplied text to the
+// terminal. Without this an attacker-controlled API base can smuggle ANSI
+// escapes into the output and repaint, erase or overwrite the lines around them.
+export function stripControlChars(value) {
+  // eslint-disable-next-line no-control-regex
+  return String(value).replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
+}
+
+export function truncate(value, max) {
+  const str = String(value ?? '');
+  const characters = Array.from(str);
+  return characters.length <= max ? str : `${characters.slice(0, max - 1).join('')}…`;
+}
+
+/**
+ * Reject an over-long field here rather than letting it become a 422.
+ *
+ * Every bound mirrors a Laravel rule (StoreNotificationRequest,
+ * StoreQuestionRequest, LiveStatusRules) and is documented in --help, so a value
+ * past it was always going to be refused — locally it reads as the usage error
+ * it is, with the limit and the actual length named.
+ */
+export function requireMaxLength(value, max, flag) {
+  if (typeof value === 'string') {
+    const length = Array.from(value).length;
+    if (length > max) {
+      fail(`${flag} must be at most ${max} characters (got ${length})`, EXIT.USAGE);
+    }
+  }
+}
+
+/**
+ * Validate --timeout and resolve the per-poll hold. Called by ask/handoff
+ * BEFORE the create POST: the old in-wait check ran only after the question or
+ * handoff already existed, so `--timeout -5` put a live question on someone's
+ * phone and then exited 2, orphaning it until its TTL.
+ */
+export function resolveWaitHold(args, { def, cap }) {
+  if (args.timeout === undefined) return Math.min(def, cap);
+  const hold = Number(args.timeout);
+  if (!Number.isFinite(hold) || hold < 0) fail('--timeout must be a non-negative integer', EXIT.USAGE);
+  return Math.min(hold, cap);
+}
+
+export function numberOption(raw, flag, { min, max, integer = false } = {}) {
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!Number.isFinite(value)) fail(`${flag} must be a number`, EXIT.USAGE);
+  if (integer && !Number.isInteger(value)) fail(`${flag} must be an integer`, EXIT.USAGE);
+  if (min !== undefined && value < min) fail(`${flag} must be at least ${min}`, EXIT.USAGE);
+  if (max !== undefined && value > max) fail(`${flag} must be at most ${max}`, EXIT.USAGE);
+  return value;
+}
+
+export function parseDataObject(raw) {
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    fail('--data must be valid JSON', EXIT.USAGE);
+  }
+  if (typeof data !== 'object' || Array.isArray(data) || data === null) {
+    fail('--data must be a JSON object', EXIT.USAGE);
+  }
+  return data;
+}
+
+export function isJsonObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+export function isNullableString(value) {
+  return value === null || typeof value === 'string';
+}

package/lib/version.js

@@ -0,0 +1,10 @@
+// Single-sourced from package.json, which npm always ships inside the tarball,
+// so the version can never drift from the package it was published as. The
+// GitHub Action pins the same version in action.yml and a test keeps the two
+// equal. `hook --print-config` emits this version.
+
+import { readFileSync } from 'node:fs';
+
+export const VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "test": "node --test \"test/*.test.mjs\""
   },
   "files": [
-    "bin"
+    "bin",
+    "lib"
   ],
   "engines": {
     "node": ">=20"