@pingroom/cli 0.7.6 → 0.8.0

package/README.md

@@ -641,6 +641,35 @@ shared by ChatGPT and Codex.
 For a fully typed client, use [`@pingroom/sdk`](https://www.npmjs.com/package/@pingroom/sdk).
 See <https://pingroom.io/connect-mcp.md> for the complete MCP and OAuth guide.
 
+## Agent skills
+
+Two ready-to-install [Claude Code skills](https://github.com/pingroom/skills)
+teach an agent when and how to reach a human — `pingroom-mcp` for conversational
+sessions, `pingroom-cli` for shells, CI, and hooks.
+
+```bash
+pingroom skills           # list them and every install route (prints only)
+pingroom skills install   # copy both into ~/.claude/skills (needs git)
+```
+
+`install` refuses to replace a skill that is already there; pass `--force` to
+replace it, or `--dir <path>` to install somewhere other than
+`~/.claude/skills`. Inside Claude Code you can instead use the plugin system,
+which keeps them updated:
+
+```
+/plugin marketplace add pingroom/skills
+/plugin install pingroom-mcp
+```
+
+## Update notifications
+
+When a newer `@pingroom/cli` is published the CLI prints a one-line notice on
+stderr, at most once every 24 hours. It is deliberately invisible to automation:
+the check is skipped entirely unless both stdout and stderr are a TTY, and
+whenever `CI` or `PINGROOM_NO_UPDATE_CHECK=1` is set. A failed or slow check is
+silent and can never change a command's output or exit code.
+
 ## License
 
 MIT

package/bin/pingroom.js

@@ -23,6 +23,7 @@
 //   live     Drive a live progress card (iOS Live Activity / Android live
 //            update) on the room members' lock screen: start / update / end.
 //   mcp      Print the canonical remote MCP endpoint and client setup snippets.
+//   skills   List the published agent skills, or install them for Claude Code.
 //   activate Send one optional test Question with the saved QR-paired credential.
 //   config   Read/write ~/.pingroom/config.json (default_room, api_url).
 //   logout   Forget the credential in ~/.pingroom/credentials.json.
@@ -39,9 +40,10 @@ import { EXIT } from '../lib/constants.js';
 import { fail, stripControlChars } from '../lib/util.js';
 import { VERSION } from '../lib/version.js';
 import { HELP } from '../lib/help.js';
+import { maybeNotifyUpdate } from '../lib/update-check.js';
 import {
   parseArgs, parseConfigArgs, parseHandoffArgs, parseHandoffsArgs, parseHookArgs,
-  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs,
+  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs, parseSkillsArgs,
 } from '../lib/parser.js';
 import { actions, approval, attachment, rooms, webhooks } from '../lib/commands/manage.js';
 import { ping } from '../lib/commands/ping.js';
@@ -51,6 +53,7 @@ import { listen } from '../lib/commands/listen.js';
 import { live } from '../lib/commands/live.js';
 import { hook } from '../lib/commands/hook.js';
 import { mcp } from '../lib/commands/mcp.js';
+import { skills } from '../lib/commands/skills.js';
 import { activateStoredInbox, bare } from '../lib/commands/connect.js';
 import { config, logout } from '../lib/commands/config.js';
 
@@ -66,6 +69,7 @@ const COMMANDS = {
   listen: (rest) => listen(parseQArgs(rest)),
   hook: (rest) => hook(parseHookArgs(rest)),
   mcp,
+  skills: (rest) => skills(parseSkillsArgs(rest)),
   activate: (rest) => activateStoredInbox(parseQArgs(rest)),
   live: (rest) => live(parseLiveArgs(rest)),
   rooms: (rest) => rooms(parseManageArgs(rest)),
@@ -100,7 +104,9 @@ async function main() {
   // A leading flag with no subcommand (`pingroom --api …`) counts as bare — it
   // configures the connect attempt rather than naming a command.
   if (!command || command.startsWith('-')) {
-    process.exit(await bare(parseQArgs(argv)));
+    const bareCode = await bare(parseQArgs(argv));
+    await maybeNotifyUpdate(VERSION);
+    process.exit(bareCode);
   }
 
   const handler = COMMANDS[command];
@@ -109,6 +115,9 @@ async function main() {
   }
 
   const code = await handler(argv.slice(1));
+  // After the command's own output, never before, and never in place of it:
+  // the notice is advisory and must not lead. It cannot alter `code`.
+  await maybeNotifyUpdate(VERSION);
   process.exit(code);
 }
 

package/lib/commands/skills.js

@@ -0,0 +1,178 @@
+// `skills` — the agent skills published at github.com/pingroom/skills.
+//
+// Bare `skills` prints the catalog and every install route, the same
+// output-only contract `mcp` keeps. `skills install` is the one command in this
+// CLI that writes outside ~/.pingroom, so it is explicit, refuses to clobber,
+// and names every path it touched.
+
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EXIT } from '../constants.js';
+import { fail } from '../util.js';
+import { commandHelp } from '../help.js';
+
+export const SKILLS_REPO = 'https://github.com/pingroom/skills';
+const SKILLS_CLONE_URL = `${SKILLS_REPO}.git`;
+
+// Path in the repo -> the skill directory name it installs as.
+//
+// The repo is laid out as two Claude Code plugins (`mcp/`, `cli/`), each with a
+// `skills/<name>/` directory whose name already matches the skill's frontmatter
+// `name` — that agreement is what lets the same tree also be installed with
+// `/plugin marketplace add`. So the source path is deep and the install name is
+// simply its last segment; a copy install and a plugin install land the same
+// directory name either way.
+const SKILLS = [
+  {
+    source: ['mcp', 'skills', 'pingroom-mcp'],
+    install: 'pingroom-mcp',
+    summary: 'conversational agents — the hosted MCP connector',
+  },
+  {
+    source: ['cli', 'skills', 'pingroom-cli'],
+    install: 'pingroom-cli',
+    summary: 'shells, CI, and Claude Code hooks',
+  },
+];
+
+export function claudeSkillsDir() {
+  return process.env.CLAUDE_SKILLS_DIR || join(homedir(), '.claude', 'skills');
+}
+
+function catalogLines() {
+  const width = Math.max(...SKILLS.map((s) => s.install.length));
+  return SKILLS.map((s) => `  ${s.install.padEnd(width)}  ${s.summary}`).join('\n');
+}
+
+function printCatalog() {
+  process.stdout.write(
+`PingRoom agent skills — ${SKILLS_REPO}
+
+${catalogLines()}
+
+Install with this CLI (copies into ${claudeSkillsDir()}):
+  pingroom skills install
+
+Install as a Claude Code plugin (auto-updates, no copy):
+  /plugin marketplace add pingroom/skills
+  /plugin install pingroom-mcp
+  /plugin install pingroom-cli
+
+Or by hand:
+  git clone ${SKILLS_CLONE_URL} /tmp/pingroom-skills
+${SKILLS.map((s) => `  cp -r /tmp/pingroom-skills/${s.source.join('/')} ${claudeSkillsDir()}`).join('\n')}
+
+Only "pingroom skills install" writes anything; this listing does not.
+`);
+  return EXIT.OK;
+}
+
+function directoryExists(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clone the skills repo into a fresh temp directory and return its path.
+ *
+ * `git` rather than a tarball fetch: the repo is public and shallow-clones in
+ * one round trip, Node ships no tar reader, and vendoring one would put an
+ * archive parser in the dependency-free path every ping goes through. When git
+ * is missing the manual recipe above is still exact, so this fails with that
+ * rather than half-installing.
+ */
+function cloneSkills() {
+  const probe = spawnSync('git', ['--version'], { stdio: 'ignore' });
+  if (probe.error || probe.status !== 0) {
+    fail(`git is required for "skills install".\nInstall git, or copy the skills by hand:\n  pingroom skills`, EXIT.ERROR);
+  }
+
+  const workspace = mkdtempSync(join(tmpdir(), 'pingroom-skills-'));
+  const clone = spawnSync(
+    'git',
+    ['clone', '--depth', '1', '--quiet', SKILLS_CLONE_URL, workspace],
+    { stdio: ['ignore', 'ignore', 'pipe'], encoding: 'utf8' },
+  );
+
+  if (clone.error || clone.status !== 0) {
+    rmSync(workspace, { recursive: true, force: true });
+    const detail = (clone.stderr || clone.error?.message || 'git clone failed').trim().split('\n')[0];
+    fail(`could not fetch ${SKILLS_REPO}: ${detail}`, EXIT.ERROR);
+  }
+
+  return workspace;
+}
+
+function install(args) {
+  const target = args.dir ? String(args.dir) : claudeSkillsDir();
+  const force = Boolean(args.force);
+
+  // Resolve collisions BEFORE the network call. Cloning first and refusing
+  // afterwards would spend the round trip to tell the operator something that
+  // was knowable from the filesystem alone.
+  if (!force) {
+    const existing = SKILLS.filter((s) => directoryExists(join(target, s.install)));
+    if (existing.length > 0) {
+      const names = existing.map((s) => join(target, s.install)).join('\n  ');
+      fail(
+        `already installed:\n  ${names}\nRe-run with --force to replace ${existing.length === 1 ? 'it' : 'them'}.`,
+        EXIT.USAGE,
+      );
+    }
+  }
+
+  const workspace = cloneSkills();
+  const installed = [];
+  try {
+    for (const skill of SKILLS) {
+      const from = join(workspace, ...skill.source);
+      if (!directoryExists(from)) {
+        fail(`${SKILLS_REPO} has no "${skill.source.join('/')}" directory — the repo layout changed.`, EXIT.ERROR);
+      }
+      const to = join(target, skill.install);
+      mkdirSync(target, { recursive: true });
+      // Replace rather than merge: a stale SKILL.md left beside a new one is a
+      // skill that half-describes two versions, and Claude Code would load it.
+      rmSync(to, { recursive: true, force: true });
+      cpSync(from, to, { recursive: true });
+      installed.push({ name: skill.install, path: to, files: countFiles(to) });
+    }
+  } finally {
+    rmSync(workspace, { recursive: true, force: true });
+  }
+
+  const lines = installed.map((s) => `  ${s.name} -> ${s.path} (${s.files} file${s.files === 1 ? '' : 's'})`);
+  process.stdout.write(
+`Installed ${installed.length} skill${installed.length === 1 ? '' : 's'}:
+${lines.join('\n')}
+
+Restart Claude Code (or start a new session) to load them.
+Connect the MCP server so the pingroom-mcp skill has tools to call:
+  pingroom mcp
+`);
+  return EXIT.OK;
+}
+
+function countFiles(dir) {
+  let total = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    total += entry.isDirectory() ? countFiles(join(dir, entry.name)) : 1;
+  }
+  return total;
+}
+
+export function skills(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('skills')}\n`); return EXIT.OK; }
+
+  const [sub] = args._;
+  if (sub === undefined || sub === 'list') return printCatalog();
+  if (sub === 'install') return install(args);
+
+  fail('usage: pingroom skills [list|install] [--dir <path>] [--force]', EXIT.USAGE);
+}

package/lib/help.js

@@ -30,6 +30,7 @@ Commands:
            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
+  skills   List the PingRoom agent skills, or install them for Claude Code
   activate Retry Agent Inbox activation with the saved QR-paired credential
   rooms    List, inspect, create, or join rooms (rooms list|get|create|join)
   webhooks Manage a room's incoming webhooks (webhooks list|create|update|delete)
@@ -156,6 +157,13 @@ export const HELP_MCP = `mcp:
   pingroom mcp add claude-code     Print the Claude Code setup command
                                    (output-only; does not change client config)`;
 
+export const HELP_SKILLS = `skills:
+  pingroom skills                  List the published agent skills and every
+                                   install route (output-only)
+  pingroom skills install          Copy them into ~/.claude/skills (needs git)
+      --dir <path>       Install somewhere other than ~/.claude/skills
+      --force            Replace skills that are already installed`;
+
 export const HELP_ACTIVATE = `activate:
   pingroom activate                Send one test Question to your phone to prove the
                                    saved QR-paired credential works (optional —
@@ -278,7 +286,7 @@ 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_LISTEN, HELP_LIVE, HELP_HOOK, HELP_MCP, HELP_SKILLS, HELP_ACTIVATE, HELP_CONFIG,
   HELP_SHARED, HELP_TAIL,
 ].join('\n\n');
 
@@ -299,6 +307,7 @@ export const COMMAND_HELP_SECTIONS = {
   listen: HELP_LISTEN,
   live: HELP_LIVE,
   hook: HELP_HOOK,
+  skills: HELP_SKILLS,
   activate: HELP_ACTIVATE,
   rooms: `rooms (agent token required):
   pingroom rooms list               List the rooms this account belongs to
@@ -346,6 +355,10 @@ export const COMMAND_HELP_FOOTERS = {
   -h, --help             Show this help`,
   logout: `Shared:
   -h, --help             Show this help`,
+  // `skills` reaches GitHub, never the PingRoom API, so the shared credential
+  // and --json flags would all be lies here.
+  skills: `Shared:
+  -h, --help             Show this help`,
 };
 
 // `<command> --help`: that command's section plus the shared flags, instead of

package/lib/parser.js

@@ -214,6 +214,18 @@ export const parseLogoutArgs = makeParser({
 // Parser for the management nouns (rooms / webhooks / actions / approval /
 // attachment). One shared vocabulary: each sub-command reads the flags it
 // needs and the rest are usage errors at the command layer, same as everywhere.
+// `skills` takes no credential and touches no API: only where to install and
+// whether to replace what is already there. A dedicated vocabulary keeps
+// --force from leaking into the parsers whose commands send real pings.
+export const parseSkillsArgs = makeParser({
+  aliases: {
+    '--dir': 'dir',
+    '--force': 'force',
+    '-h': 'help', '--help': 'help',
+  },
+  booleans: ['force', 'help'],
+});
+
 export const parseManageArgs = makeParser({
   aliases: {
     '-n': 'name', '--name': 'name',

package/lib/update-check.js

@@ -0,0 +1,153 @@
+// "A newer @pingroom/cli is available" — the one piece of output this tool
+// prints that nobody asked for. Everything here exists to make that safe.
+//
+// The hard rule: this must never change what a command does. Not its exit code,
+// not its stdout, not whether it succeeds. A version notice that breaks a
+// deploy pipeline is worse than never shipping the notice at all, so every
+// failure path below is a silent return.
+
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+import { pingroomHome, readJsonFile } from './config.js';
+
+const REGISTRY_URL = 'https://registry.npmjs.org/@pingroom/cli/latest';
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+// Awaited before exit, so this is a real ceiling on how long a successful
+// command can be delayed by a check nobody asked for. Measured round trips to
+// the registry ran 0.63-1.19s warm, so a tighter budget (1.2s was tried) times
+// out often enough to look like "there is never an update".
+const TIMEOUT_MS = 2500;
+
+export function updateCachePath() { return join(pingroomHome(), 'update-check.json'); }
+
+/**
+ * Write the cache, or give up without a word.
+ *
+ * Deliberately NOT config.js's writeJsonFile: that one calls fail() on an
+ * unwritable path, and fail() calls process.exit() — which no try/catch can
+ * intercept. Borrowing it here would mean a read-only or full ~/.pingroom turns
+ * an advisory version check into the thing that kills the operator's ping. The
+ * write is still atomic (temp file + rename) so a crash mid-write cannot leave
+ * a torn file for the next run to parse.
+ */
+function writeCacheQuietly(path, value) {
+  const tmp = `${path}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+  try {
+    mkdirSync(pingroomHome(), { recursive: true, mode: 0o700 });
+    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch {
+    try { unlinkSync(tmp); } catch { /* never created */ }
+  }
+}
+
+/**
+ * Why an env var AND a TTY test:
+ *
+ * `CI` covers the graders that set it (GitHub Actions, GitLab, CircleCI). The
+ * TTY test covers everything else — cron, systemd units, Docker builds, a
+ * pipeline that forgot to set CI, and `pingroom ... | jq`. Neither alone is
+ * enough, and the notice is worthless to a machine either way.
+ */
+function suppressed() {
+  if (process.env.PINGROOM_NO_UPDATE_CHECK === '1') return true;
+  if (process.env.CI) return true;
+  if (process.env.NODE_ENV === 'test') return true;
+  return !process.stdout.isTTY || !process.stderr.isTTY;
+}
+
+/**
+ * Compare two dotted release numbers. Returns true when `candidate` is strictly
+ * newer than `current`.
+ *
+ * Anything carrying a prerelease or build suffix (`-beta.1`, `+sha`) is refused
+ * outright rather than guessed at: npm's `latest` tag should never point at one,
+ * and a wrong guess here nags every single run. Only the numeric release line is
+ * compared, and only when both sides parse.
+ */
+export function isNewer(candidate, current) {
+  const parse = (value) => {
+    if (typeof value !== 'string') return null;
+    const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value.trim());
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse(candidate);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return true;
+    if (a[i] < b[i]) return false;
+  }
+  return false;
+}
+
+/**
+ * Fetch the published `latest` version, or null for any failure at all — no
+ * network, DNS refusal, a 5xx, a proxy returning HTML, a body without a version
+ * string. The caller cannot distinguish these and should not try to.
+ */
+async function fetchLatest() {
+  try {
+    // Plain application/json, NOT npm's abbreviated-metadata type: that one is
+    // only accepted on the full packument, and asking for it here gets a 406
+    // that this function would swallow into a permanent "no update available".
+    // The single-version document is ~1.5 KB, smaller than the packument the
+    // abbreviated type would have saved us from.
+    const res = await fetch(REGISTRY_URL, {
+      headers: { Accept: 'application/json' },
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    return typeof json?.version === 'string' ? json.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Check at most once every 24h and print a notice when a newer release exists.
+ *
+ * The cache timestamp is written on every completed check, including one that
+ * found nothing and one whose fetch failed. Writing it only on success would
+ * turn an offline machine into a machine that retries the registry on every
+ * single invocation.
+ *
+ * Note this is awaited by the caller rather than detached: the CLI ends in an
+ * explicit process.exit(), which would kill a floating promise mid-flight and
+ * leave the cache unwritten — so a detached check would re-fetch forever while
+ * appearing to cost nothing.
+ */
+export async function maybeNotifyUpdate(currentVersion) {
+  try {
+    if (suppressed()) return;
+
+    const path = updateCachePath();
+    const cached = readJsonFile(path);
+    const checkedAt = Number(cached?.checked_at);
+    const fresh = Number.isFinite(checkedAt) && Date.now() - checkedAt < CHECK_INTERVAL_MS;
+
+    // Inside the window, still report what the last check found: the notice
+    // should persist until the operator actually upgrades, not appear once a day
+    // and vanish.
+    const latest = fresh ? cached?.latest : await fetchLatest();
+    if (!fresh) {
+      writeCacheQuietly(path, { checked_at: Date.now(), latest: latest ?? null });
+    }
+
+    if (typeof latest !== 'string' || !isNewer(latest, currentVersion)) return;
+
+    process.stderr.write(
+      `\nnote: @pingroom/cli ${latest} is available (you have ${currentVersion})\n`
+      + '      npm i -g @pingroom/cli\n'
+      + '      set PINGROOM_NO_UPDATE_CHECK=1 to silence this\n',
+    );
+  } catch {
+    // Unreachable by design — every step above already swallows its own
+    // failures. This is the backstop that guarantees the promise this function
+    // returns can never reject into the caller's exit path.
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.7.6",
+  "version": "0.8.0",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {