@pingroom/cli 0.7.0 → 0.7.3

package/lib/commands/live.js

@@ -0,0 +1,165 @@
+import { EXIT } from '../constants.js';
+import { fail, numberOption, parseDataObject, requireMaxLength } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson, requireSafeUrl } from '../http.js';
+import { requireStoredCredentialOrigin, resolveApiBase, resolveRoom, resolveToken } from '../config.js';
+import {
+  buildLiveOptions, buildMetrics, buildSide, canonicalTemplate, LIVE_TEMPLATE_NAMES, LIVE_TEMPLATES,
+  normalizeAccent,
+} from '../render.js';
+
+/**
+ * Drive a live progress card on the room members' lock screen.
+ *
+ * One correlation id = one stream: `start` opens it (one alert), `update` moves
+ * it silently, `end` closes it with one completion alert. Works with either an
+ * agent token (--token, needs pingroom:live:write) or a room's incoming webhook
+ * (--webhook), which speak the same `live_status` contract.
+ */
+export async function live(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('live')}\n`); return EXIT.OK; }
+  const sub = args._[0];
+  const known = ['start', 'update', 'end', 'get'];
+  if (!sub || !known.includes(sub)) {
+    fail(`live needs a subcommand: ${known.join(' | ')}`, EXIT.USAGE);
+  }
+
+  const correlationId = args.correlation_id;
+  if (!correlationId) fail('--correlation-id is required', EXIT.USAGE);
+
+  const webhook = args.webhook || process.env.PINGROOM_WEBHOOK_URL;
+  const token = resolveToken(args);
+  const apiBase = resolveApiBase(args);
+  const room = resolveRoom(args);
+
+  if (sub === 'get') {
+    if (!token) fail('live get requires an agent token (--token or PINGROOM_TOKEN)', EXIT.USAGE);
+    requireStoredCredentialOrigin(args, apiBase);
+    if (!room) fail('--room is required', EXIT.USAGE);
+    requireSafeUrl('--api', apiBase);
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live/${encodeURIComponent(correlationId)}`;
+    const { res, text, json } = await httpJson('GET', url, { headers: { Authorization: `Bearer ${token}` } });
+    if (args.json) process.stdout.write(`${text || '{}'}\n`);
+    if (!res.ok) {
+      fail(`read failed: ${apiDetail(res, json)}`);
+    }
+    if (!args.json) process.stdout.write(`${(json && json.state) || 'unknown'}\n`);
+    return EXIT.OK;
+  }
+
+  const liveStatus = {
+    state: sub === 'end' ? (args.failed ? 'failed' : 'done') : 'running',
+  };
+
+  // 256, not the 500 a ping body gets: this is the card's one live line.
+  requireMaxLength(args.message, 256, '--message');
+  requireMaxLength(args.title, 40, '--title');
+  requireMaxLength(args.prompt, 256, '--prompt');
+  requireMaxLength(args.center, 40, '--center');
+  if (args.message !== undefined) liveStatus.message = args.message;
+  if (args.prompt !== undefined) liveStatus.prompt = args.prompt;
+
+  const progress = numberOption(args.progress, '--progress', { min: 0, max: 1 });
+  if (progress !== undefined) liveStatus.progress = progress;
+
+  const step = numberOption(args.step, '--step', { min: 0, max: 8, integer: true });
+  if (step !== undefined) liveStatus.current_step = step;
+
+  const deadlineAt = numberOption(args.deadline_at, '--deadline-at', { min: 0, integer: true });
+  if (deadlineAt !== undefined) liveStatus.deadline_at = deadlineAt;
+
+  const etaAt = numberOption(args.eta_at, '--eta-at', { min: 0, integer: true });
+  if (etaAt !== undefined) liveStatus.eta_at = etaAt;
+
+  const metrics = buildMetrics(args.metric);
+  if (metrics) liveStatus.metrics = metrics;
+
+  const options = buildLiveOptions(args.option);
+  if (options) {
+    if (options.length > 4) fail('--option accepts at most 4 choices', EXIT.USAGE);
+    liveStatus.options = options;
+  }
+
+  const left = buildSide(args.left, '--left');
+  if (left) liveStatus.left = left;
+  const right = buildSide(args.right, '--right');
+  if (right) liveStatus.right = right;
+  if (args.center !== undefined) liveStatus.center = args.center;
+
+  const accent = normalizeAccent(args.accent_override);
+  if (accent) liveStatus.accent_override = accent;
+
+  // Template, category and step labels are fixed when the stream is created;
+  // sending them on an update is a no-op server-side, so only `start` takes them.
+  if (sub === 'start') {
+    // Validated locally for the same reason --category is: a typo'd name is a
+    // usage error, and letting it reach the server turns it into a 422 round
+    // trip that reads like an outage.
+    if (args.template) {
+      const template = canonicalTemplate(args.template);
+      if (!LIVE_TEMPLATES.includes(template)) {
+        fail(`--template must be one of: ${LIVE_TEMPLATE_NAMES.join(', ')}`, EXIT.USAGE);
+      }
+      liveStatus.template = template;
+    }
+    // `alert` has no template equivalent and is the only way to start a stream
+    // time-sensitive (breaking through Focus) without also demanding an ack.
+    if (args.category) {
+      if (!['status', 'steps', 'alert'].includes(args.category)) {
+        fail('--category must be status, steps or alert', EXIT.USAGE);
+      }
+      liveStatus.category = args.category;
+    }
+    if (args.steps) {
+      const labels = args.steps.split(',').map((s) => s.trim()).filter(Boolean);
+      if (labels.length < 2 || labels.length > 8) {
+        fail('--steps needs between 2 and 8 comma-separated labels', EXIT.USAGE);
+      }
+      liveStatus.steps = labels;
+    }
+  } else if (args.template || args.steps || args.category) {
+    fail('--template, --category and --steps are fixed at stream creation; pass them to "live start"', EXIT.USAGE);
+  }
+
+  const body = { correlation_id: correlationId, live_status: liveStatus };
+  if (args.title) body.title = args.title;
+  if (args.action !== undefined) body.action = Number(args.action);
+  // Same object-shape guard ping/ask/handoff use. A bare JSON.parse also accepts
+  // an array, which the server then rejects — a wasted round trip for what is a
+  // local usage error.
+  // `!== undefined`, not truthiness: `-d ''` is a malformed value, and a
+  // truthiness test drops it on the floor and ships the ping without the data
+  // the caller believed they attached. ping/ask/handoff all reject it loudly.
+  if (args.data !== undefined) body.data = parseDataObject(args.data);
+  if (args.require_ack) body.requires_ack = true;
+  const ackTimeout = numberOption(args.ack_timeout, '--ack-timeout', { min: 1, max: 86_400, integer: true });
+  if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
+
+  let result;
+  if (webhook) {
+    requireSafeUrl('--webhook', webhook);
+    result = await httpJson('POST', webhook, { body });
+  } else if (token) {
+    requireStoredCredentialOrigin(args, apiBase);
+    if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+    requireSafeUrl('--api', apiBase);
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/live`;
+    result = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
+  } else {
+    fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN, or run "pingroom" to connect)', EXIT.USAGE);
+  }
+
+  const { res, text, json } = result;
+  if (args.json) process.stdout.write(`${text || '{}'}\n`);
+
+  if (!res.ok || (json && json.success === false)) {
+    const detail = apiDetail(res, json);
+    fail(`live ${sub} failed: ${detail}`);
+  }
+
+  if (!args.json) {
+    const state = (json && (json.state || (json.live_status && json.live_status.state))) || sub;
+    process.stdout.write(`live ${sub} → ${state} ✅\n`);
+  }
+  return EXIT.OK;
+}

package/lib/commands/mcp.js

@@ -0,0 +1,47 @@
+// `mcp` — print the remote MCP endpoint and client setup. Output only: it never
+// edits a client's configuration.
+
+import { EXIT, MCP_ENDPOINT } from '../constants.js';
+import { fail } from '../util.js';
+
+export function mcp(rest) {
+  const claudeCommand = `claude mcp add --transport http pingroom ${MCP_ENDPOINT}`;
+
+  if (rest.length === 0 || (rest.length === 1 && (rest[0] === '-h' || rest[0] === '--help'))) {
+    const config = {
+      mcpServers: {
+        pingroom: { url: MCP_ENDPOINT },
+      },
+    };
+    process.stdout.write(
+`PingRoom MCP endpoint:
+  ${MCP_ENDPOINT}
+
+Claude Code:
+  ${claudeCommand}
+
+Cursor JSON (~/.cursor/mcp.json):
+${JSON.stringify(config, null, 2)}
+
+Claude Desktop:
+  Customize > Connectors > Add custom connector
+  Name: PingRoom
+  URL:  ${MCP_ENDPOINT}
+
+After adding the server, use your client's MCP controls to authenticate in the
+browser. No API key is needed.
+This command only prints setup instructions and does not modify client config.
+`);
+    return EXIT.OK;
+  }
+
+  if (rest.length === 2 && rest[0] === 'add' && rest[1] === 'claude-code') {
+    process.stdout.write(
+`No client configuration was changed. Copy and run:
+  ${claudeCommand}
+`);
+    return EXIT.OK;
+  }
+
+  fail('usage: pingroom mcp [add claude-code]', EXIT.USAGE);
+}

package/lib/commands/ping.js

@@ -0,0 +1,123 @@
+import { EXIT } from '../constants.js';
+import { fail, parseDataObject, requireMaxLength } from '../util.js';
+import { commandHelp } from '../help.js';
+import { apiDetail, httpJson, requireSafeUrl, uploadAttachments } from '../http.js';
+import { requireStoredCredentialOrigin, resolveApiBase, resolveRoom, resolveToken } from '../config.js';
+
+export async function ping(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('ping')}\n`); return EXIT.OK; }
+
+  const message = args.message;
+  if (!message) fail('a --message is required', EXIT.USAGE);
+  requireMaxLength(message, 500, '--message');
+  requireMaxLength(args.title, 40, '--title');
+
+  if (args.action !== undefined && !/^[1-4]$/.test(String(args.action))) {
+    fail('--action must be an integer 1–4', EXIT.USAGE);
+  }
+
+  let ackTimeout;
+  if (args.ack_timeout !== undefined) {
+    if (!args.require_ack) {
+      fail('--ack-timeout requires --require-ack', EXIT.USAGE);
+    }
+    if (!/^\d+$/.test(String(args.ack_timeout))) {
+      fail('--ack-timeout must be an integer number of seconds', EXIT.USAGE);
+    }
+    ackTimeout = Number(args.ack_timeout);
+  }
+
+  let data;
+  if (args.data !== undefined) {
+    data = parseDataObject(args.data);
+  }
+
+  // Link ping: --url/--button-label fold into the structured data object
+  // (server contract: data.url = absolute http(s) <= 2048, data.button_label <= 26).
+  if (args.button_label !== undefined && args.url === undefined) {
+    fail('--button-label requires --url', EXIT.USAGE);
+  }
+  if (args.url !== undefined) {
+    let linkUrl;
+    try {
+      linkUrl = new URL(args.url);
+    } catch {
+      fail('--url is not a valid URL', EXIT.USAGE);
+    }
+    if (linkUrl.protocol !== 'https:' && linkUrl.protocol !== 'http:') {
+      fail('--url must be an absolute http(s) URL', EXIT.USAGE);
+    }
+    if (args.url.length > 2048) {
+      fail('--url must be at most 2048 characters', EXIT.USAGE);
+    }
+    if (args.button_label !== undefined && args.button_label.length > 26) {
+      fail('--button-label must be at most 26 characters', EXIT.USAGE);
+    }
+    data = { ...(data || {}), url: args.url };
+    if (args.button_label !== undefined) data.button_label = args.button_label;
+  }
+
+  const webhook = args.webhook || process.env.PINGROOM_WEBHOOK_URL;
+  const token = resolveToken(args);
+  const apiBase = resolveApiBase(args);
+  const room = resolveRoom(args);
+
+  let result;
+
+  // Attachments exist only on the agent-token path: an incoming webhook has no
+  // uploader identity to bind private files to, so the API takes no ids there.
+  const attachPaths = args.attach ?? [];
+  if (attachPaths.length && (webhook || !token)) {
+    fail('--attach requires an agent token (--token / PINGROOM_TOKEN), not a webhook ping', EXIT.USAGE);
+  }
+
+  if (webhook) {
+    if (ackTimeout !== undefined && (ackTimeout < 1 || ackTimeout > 86_400)) {
+      fail('--ack-timeout must be between 1 and 86400 seconds for a webhook ping', EXIT.USAGE);
+    }
+    requireSafeUrl('--webhook', webhook);
+    const body = { message };
+    if (args.title) body.title = args.title;
+    if (args.action !== undefined) body.action = Number(args.action);
+    if (data) body.data = data;
+    if (args.require_ack) body.requires_ack = true;
+    if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
+    result = await httpJson('POST', webhook, { body });
+  } else if (token) {
+    requireStoredCredentialOrigin(args, apiBase);
+    if (!room) fail('--room is required when using --token (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+    if (ackTimeout !== undefined && (ackTimeout < 60 || ackTimeout > 86_400)) {
+      fail('--ack-timeout must be between 60 and 86400 seconds for an agent room ping', EXIT.USAGE);
+    }
+    requireSafeUrl('--api', apiBase);
+    const url = `${apiBase}/api/agent/rooms/${encodeURIComponent(room)}/notifications`;
+    const body = { message };
+    if (args.title) body.title = args.title;
+    if (args.action !== undefined) body.action_number = Number(args.action);
+    if (data) body.data = data;
+    if (args.require_ack) body.requires_ack = true;
+    if (ackTimeout !== undefined) body.ack_timeout_seconds = ackTimeout;
+    if (attachPaths.length) {
+      body.attachment_ids = await uploadAttachments(attachPaths, apiBase, token);
+    }
+    result = await httpJson('POST', url, { body, headers: { Authorization: `Bearer ${token}` } });
+  } else {
+    fail('provide a webhook (--webhook / PINGROOM_WEBHOOK_URL) or an agent token (--token / PINGROOM_TOKEN, or run "pingroom" to connect)', EXIT.USAGE);
+  }
+
+  const { res, text, json } = result;
+
+  if (args.json) {
+    process.stdout.write(`${text || '{}'}\n`);
+  }
+
+  const ok = res.ok && !(json && json.success === false);
+
+  if (!ok) {
+    const detail = apiDetail(res, json);
+    fail(`delivery failed: ${detail}`);
+  }
+
+  if (!args.json) process.stdout.write('ping sent ✅\n');
+  return EXIT.OK;
+}

package/lib/config.js

@@ -0,0 +1,206 @@
+// Local state (~/.pingroom) and the layered resolution every command shares:
+// explicit flag > env var > config file > the paired credential > built-in.
+
+import { randomBytes } from 'node:crypto';
+import {
+  chmodSync, closeSync, fchmodSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { BUILTIN_API, EXIT } from './constants.js';
+import { fail } from './util.js';
+import { requireSafeUrl } from './http.js';
+
+// --- local state (~/.pingroom) ---------------------------------------------
+//
+// Two files, both under a 0700 directory:
+//   credentials.json  the agent credential this machine paired (mode 0600)
+//   config.json       user settings: default_room, api_url
+//
+// PINGROOM_HOME relocates the directory (tests, sandboxes, multi-account
+// shells). Every lookup is layered: explicit flag > env var > config file >
+// the paired credential > built-in default. PINGROOM_TOKEN is the one env var
+// that also outranks the stored credential, which is what keeps CI working
+// untouched.
+
+export function pingroomHome() {
+  return process.env.PINGROOM_HOME || join(homedir(), '.pingroom');
+}
+
+export function credentialsPath() { return join(pingroomHome(), 'credentials.json'); }
+export function configPath() { return join(pingroomHome(), 'config.json'); }
+
+// Read a JSON object, or null for anything unreadable/corrupt. Local state must
+// never be able to crash a ping: a hand-edited file degrades to "not set".
+export function readJsonFile(path) {
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); } catch { return null; }
+  let value;
+  try { value = JSON.parse(raw); } catch { return null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return value;
+}
+
+// Write JSON with restrictive permissions, atomically.
+//
+// Writing in place truncates first, so a crash or a full disk between truncate
+// and write leaves a half-written file — and readJsonFile() degrades anything
+// unparseable to {}, so the *next* `config set` would silently drop every other
+// setting. Writing a sibling temp file and renaming over the target means a
+// reader only ever sees the old file or the new one, never a torn one.
+//
+// The temp file is opened 'wx' with mode 0600 and fchmod'd before a single byte
+// is written: `mode` on an existing file is ignored and a post-write chmod
+// leaves a window where the credential is world-readable. rename() carries the
+// 0600 over the target, so a pre-existing loose file is tightened too.
+//
+// mkdirSync(recursive) returns the first path it created, or undefined when the
+// directory already existed. chmod'ing only on the former keeps this from
+// narrowing a directory the user deliberately created at 0755.
+export function writeJsonFile(path, value) {
+  const dir = pingroomHome();
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  let fd;
+  try {
+    const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (created !== undefined) chmodSync(dir, 0o700);
+
+    fd = openSync(tmp, 'wx', 0o600);
+    fchmodSync(fd, 0o600); // defeat a permissive umask masking the open mode
+    writeFileSync(fd, `${JSON.stringify(value, null, 2)}\n`);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, path);
+  } catch (err) {
+    if (fd !== undefined) { try { closeSync(fd); } catch { /* already gone */ } }
+    try { unlinkSync(tmp); } catch { /* never created */ }
+    fail(`could not write ${path}: ${err.message}`);
+  }
+}
+
+export function readStoredCredential() {
+  const cred = readJsonFile(credentialsPath());
+  if (!cred || typeof cred.token !== 'string' || cred.token === '') return null;
+  return cred;
+}
+
+export function readConfigFile() {
+  return readJsonFile(configPath()) || {};
+}
+
+/** Agent token: --token > PINGROOM_TOKEN > the paired credential. */
+export function resolveToken(args) {
+  return args.token || process.env.PINGROOM_TOKEN || readStoredCredential()?.token || undefined;
+}
+
+/**
+ * API base: --api > PINGROOM_API_URL > config.api_url > the host the credential
+ * was paired against > built-in, no trailing slash.
+ *
+ * The credential layer is not optional. saveCredential() records `api_url`, and
+ * a token minted by a self-hosted / staging server is only valid there; without
+ * this layer the next command would present that bearer to api.pingroom.io —
+ * leaking it to a host it was never issued for. resolveRoom() already consults
+ * the credential last, so the two layerings now agree.
+ *
+ * It is also an issuer boundary when resolveToken() falls through to the stored
+ * credential. Overrides may change the path on the same origin, but
+ * requireStoredCredentialOrigin() refuses a different origin unless the caller
+ * supplies an explicit --token or PINGROOM_TOKEN for that host.
+ */
+export function resolveApiBase(args) {
+  const raw = args.api
+    || process.env.PINGROOM_API_URL
+    || readConfigFile().api_url
+    || readStoredCredential()?.api_url
+    || BUILTIN_API;
+  return String(raw).replace(/\/$/, '');
+}
+
+/**
+ * A paired bearer belongs to the API origin that minted it. API settings still
+ * resolve independently so callers can select a path or an intentional custom
+ * host, but a stored token may only follow them within its recorded origin.
+ * Supplying --token / PINGROOM_TOKEN makes the token source explicit and opts
+ * out of this stored-credential binding.
+ */
+export function storedCredentialOriginError(args, apiBase) {
+  if (args.token || process.env.PINGROOM_TOKEN) return null;
+
+  const credential = readStoredCredential();
+  if (!credential || typeof credential.api_url !== 'string' || credential.api_url === '') return null;
+
+  let credentialOrigin;
+  let targetOrigin;
+  try {
+    credentialOrigin = new URL(credential.api_url).origin;
+    targetOrigin = new URL(apiBase).origin;
+  } catch {
+    // URL validation owns malformed values. This guard only compares origins.
+    return null;
+  }
+
+  if (credentialOrigin === targetOrigin) return null;
+  return `stored credential is bound to ${credentialOrigin}; refusing to send it to ${targetOrigin}. Provide --token or PINGROOM_TOKEN for an intentional API origin override`;
+}
+
+export function requireStoredCredentialOrigin(args, apiBase) {
+  const error = storedCredentialOriginError(args, apiBase);
+  if (error) fail(error, EXIT.USAGE);
+}
+
+/**
+ * Room invite code: --room > PINGROOM_ROOM > config.default_room > the room the
+ * credential was paired to. The paired room is last because it is the weakest
+ * signal — it is where the agent was told to deliver, not necessarily where
+ * this invocation means to.
+ */
+export function resolveRoom(args) {
+  return args.room
+    || process.env.PINGROOM_ROOM
+    || readConfigFile().default_room
+    || readStoredCredential()?.room?.invite_code
+    || undefined;
+}
+
+// Resolve the credential + endpoint a token-only command needs. When nothing is
+// available this is a usage error pointing at PINGROOM_TOKEN — never a prompt,
+// so a CI job fails in a second instead of hanging on an invisible question.
+export function agentContext(args, { needRoom = false } = {}) {
+  const token = resolveToken(args);
+  if (!token) {
+    fail(
+      'an agent token is required (--token or PINGROOM_TOKEN). Run "pingroom" in an interactive terminal to connect this machine; in CI set PINGROOM_TOKEN.',
+      EXIT.USAGE,
+    );
+  }
+  const apiBase = resolveApiBase(args);
+  requireStoredCredentialOrigin(args, apiBase);
+  requireSafeUrl('--api', apiBase);
+  const room = resolveRoom(args);
+  if (needRoom && !room) {
+    fail('--room is required (or set one with "pingroom config set default_room <code>")', EXIT.USAGE);
+  }
+  return { token, apiBase, room };
+}
+
+/** Persist the active credential plus the bits the status line prints. */
+export function saveCredential({ token, handle, room, rooms, roomAccess, account, scopes, apiBase }) {
+  writeJsonFile(credentialsPath(), {
+    version: 1,
+    token,
+    handle: handle || null,
+    // `room` is the delivery room — where handoffs and questions land. `rooms`
+    // is the whole grant, which can be wider; `room_access: "all"` means the
+    // human granted every room they are in, listing none.
+    room: room || null,
+    rooms: Array.isArray(rooms) ? rooms : [],
+    room_access: roomAccess || null,
+    account: account || null,
+    scopes: scopes || [],
+    api_url: apiBase,
+    created_at: new Date().toISOString(),
+  });
+}

package/lib/constants.js

@@ -0,0 +1,7 @@
+// Endpoints and exit codes shared by every command surface.
+
+export const BUILTIN_API = 'https://api.pingroom.io';
+export const MCP_ENDPOINT = `${BUILTIN_API}/api/agent/mcp`;
+export const DEFAULT_API = process.env.PINGROOM_API_URL || BUILTIN_API;
+
+export const EXIT = { OK: 0, ERROR: 1, USAGE: 2, EXPIRED: 3, CANCELLED: 4 };

package/lib/github-output.js

@@ -0,0 +1,76 @@
+// The GitHub Actions output file. The CLI owns $GITHUB_OUTPUT end to end: the
+// shell in action.yml never parses stdout, never redirects into the file, and
+// never gets to name a key.
+
+import { randomBytes } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+
+import { EXIT } from './constants.js';
+import { fail } from './util.js';
+
+/**
+ * Append the composite Action's declared outputs without interpreting stdout.
+ * Values use GitHub's multiline protocol with a fresh random delimiter. The
+ * `fields` a caller passes are a FIXED allowlist built from constants — never
+ * from server data — so untrusted answer text can never create a key.
+ */
+export function writeGitHubOutputs(path, fields) {
+  if (typeof path !== 'string' || path.length === 0) {
+    fail('--github-output must be a non-empty path', EXIT.USAGE);
+  }
+
+  const blocks = fields.map(([name, rawValue]) => {
+    const value = String(rawValue ?? '');
+    let delimiter;
+    do {
+      delimiter = `pingroom_${randomBytes(24).toString('hex')}`;
+    } while (value.includes(delimiter));
+    // Keep the collision check next to serialization: a delimiter must never
+    // occur in an untrusted value, even though a 192-bit collision is remote.
+    if (value.includes(delimiter)) {
+      fail('could not create a safe GitHub output delimiter');
+    }
+    return `${name}<<${delimiter}\n${value}\n${delimiter}\n`;
+  });
+
+  try {
+    appendFileSync(path, blocks.join(''), { encoding: 'utf8' });
+  } catch {
+    fail('could not write GitHub outputs');
+  }
+}
+
+/** The handoff half of the Action's output contract. */
+export function writeGitHubHandoffOutputs(path, h) {
+  const ackerId = h.acked_by && typeof h.acked_by === 'object'
+    ? h.acked_by.id
+    : h.acked_by;
+  const fields = [
+    ['handoff-id', h.id ?? ''],
+    ['state', h.state ?? ''],
+  ];
+  if (h.delivery_state != null) fields.push(['delivery-state', h.delivery_state]);
+  if (h.state === 'answered') {
+    fields.push(['answer', h.answer && (h.answer.value ?? h.answer.text) || '']);
+  }
+  if (h.state === 'acked') fields.push(['acknowledged-by', ackerId ?? '']);
+
+  writeGitHubOutputs(path, fields);
+}
+
+/**
+ * The `ask` half. Deliberately narrower than the handoff mapper: a question has
+ * no delivery_state and no acker, so the allowlist is exactly question-id,
+ * state, and — only once answered — answer.
+ */
+export function writeGitHubQuestionOutputs(path, q) {
+  const fields = [
+    ['question-id', q.id ?? ''],
+    ['state', q.state ?? ''],
+  ];
+  if (q.state === 'answered') {
+    fields.push(['answer', q.answer && (q.answer.value ?? q.answer.text) || '']);
+  }
+
+  writeGitHubOutputs(path, fields);
+}