wldx-cli 0.1.0 → 1.0.0

package/src/chat/watch.mjs

@@ -0,0 +1,251 @@
+// The live feed of the user's chats: the websocket of the stream service (wss://<region>-ws.stream.wildix.com),
+// as the agent skill's watch.mjs. Read only: it sends nothing to any chat and marks nothing read. One event per
+// ctx.emit(); READY when subscribed, RECONNECTING / RECONNECTED while the connection is renewed (the service closes
+// one after two hours; the token, checked only when a connection opens, is renewed with ctx.freshToken()), END at
+// the end (ctx.signal, --count or --for).
+import {jwtClaims} from '../auth.mjs';
+import {AuthError} from '../errors.mjs';
+import {localTime, oneLine, paint} from '../format.mjs';
+import {streamWsUrl} from '../services.mjs';
+import {streamClient} from '../stream.mjs';
+import {displayName, meId} from './lib.mjs';
+
+export const EVENT_GROUPS = {
+  messages: ['message.new', 'message.updated', 'message.deleted'],
+  reactions: ['reaction.new', 'reaction.updated', 'reaction.deleted'],
+  reads: ['read.cursor.updated', 'read.receipt.updated'],
+  members: ['member.added', 'member.updated', 'member.removed'],
+  channels: [
+    'channel.created', 'channel.updated', 'channel.truncated', 'channel.added', 'channel.removed', 'channel.hidden',
+    'channel.visible', 'channel.muted', 'channel.unmuted', 'channel.pinned', 'channel.unpinned',
+  ],
+  typing: ['typing.start', 'typing.stop'],
+};
+export const EVENT_CHOICES = [...Object.keys(EVENT_GROUPS), ...Object.values(EVENT_GROUPS).flat()];
+
+const KEEPALIVE_MS = 4 * 60 * 1000; // the gateway drops a connection that is quiet for 10 minutes
+const BACKOFF = [1, 2, 5, 10]; // seconds, then 30
+const drop = (o) => JSON.parse(JSON.stringify(o)); // removes the undefined fields
+const unreadOf = (counters) => (counters ? Object.values(counters).reduce((n, c) => n + (c?.unmutedUnreadMessageCount ?? 0), 0) : undefined);
+
+// Whether an event passes the filters. A reaction event does not say who reacted (its message is someone else's
+// work), so a reaction has no author: it is never taken for the user's own action, and --from leaves it out.
+export function wanted(e, {channels, senders, types, mine, me}) {
+  if (types.size && !types.has(e.eventType)) return false;
+  if (channels.size && !channels.has(e.channelId)) return false;
+  const isReaction = e.eventType.startsWith('reaction.');
+  const author = isReaction ? undefined : e.message?.userId ?? e.readerUserId ?? e.typingUserId;
+  if (isReaction && senders.size) return false;
+  if (senders.size && !senders.has(author)) return false;
+  if (!mine) {
+    if (e.eventType === 'read.cursor.updated') return false; // always the user's own reading
+    if (author === me) return false;
+  }
+  return true;
+}
+
+// The short form of an event (the fields of the skill's watch.mjs).
+export async function view(e, nameOf) {
+  const person = async (id) => (id ? {id, name: await nameOf(id)} : undefined);
+  const m = e.message;
+  const isReaction = e.eventType.startsWith('reaction.');
+  return drop({
+    event: e.eventType,
+    channelId: e.channelId,
+    channel: e.inboxChannel?.subject,
+    channelType: e.inboxChannel?.channelType,
+    messageId: e.messageId,
+    seq: e.timelineSeq,
+    from: isReaction ? undefined : await person(m?.userId),
+    messageAuthor: isReaction ? await person(m?.userId) : undefined,
+    text: m?.text,
+    attachments: m?.attachments?.length ? m.attachments.map((f) => drop({name: f.name, mime: f.mime})) : undefined,
+    mentions: m?.mentions?.length ? m.mentions : undefined,
+    system: m?.system || undefined,
+    reactions: isReaction ? m?.reactionCounts : undefined,
+    reader: await person(e.readerUserId),
+    readUpTo: e.lastReadVisibleSeq,
+    member: e.member ? {...e.member, name: await nameOf(e.member.userId)} : undefined,
+    typing: await person(e.typingUserId),
+    unread: unreadOf(e.sectionCounters),
+  });
+}
+
+const tokenExp = (token) => (Number.isFinite(jwtClaims(token).exp) ? jwtClaims(token).exp * 1000 : 0);
+
+// Runs until ctx.signal, `count` events (0: no limit) or `seconds` (0: no limit). Resolves when it stops.
+export async function watch(ctx, {channels = new Set(), senders = new Set(), types = new Set(), mine = false, raw = false, count = 0, seconds = 0} = {}) {
+  let token = ctx.token;
+  let client = streamClient({token, env: ctx.env, fetchImpl: ctx.fetch});
+  const me = await meId(ctx, client);
+  const wsBase = streamWsUrl(ctx.env);
+  const WS = globalThis.WebSocket;
+  if (typeof WS !== 'function') throw new Error('This Node.js has no WebSocket: Node.js 22 or newer is needed');
+
+  const names = new Map();
+  const nameOf = async (id) => {
+    if (!id) return undefined;
+    if (!names.has(id)) {
+      let name;
+      try {
+        name = displayName((await client.call('POST', '/users/query', {query: {ids: [id]}}, {timeoutMs: 10_000}))?.users?.[0]);
+      } catch {
+        // a name is a nicety: the id is printed anyway
+      }
+      names.set(id, name);
+    }
+    return names.get(id);
+  };
+  const filters = {channels, senders, types, mine, me};
+
+  return new Promise((resolve, reject) => {
+    let ws;
+    let stopping = false;
+    let attempts = 0;
+    let renewedFor; // the token a "token" reconnection was made for: once per token, then the usual waits
+    let ready = false;
+    let left = count;
+    let keepalive;
+    let retry;
+    let deadline;
+    let queue = Promise.resolve();
+
+    const finish = (error) => {
+      if (stopping) return;
+      stopping = true;
+      clearInterval(keepalive);
+      clearTimeout(retry);
+      clearTimeout(deadline);
+      ctx.signal?.removeEventListener('abort', onAbort);
+      try {
+        ws?.close(1000);
+      } catch {
+        // closing a socket that is gone
+      }
+      queue.then(() => {
+        if (error) return reject(error);
+        ctx.emit({event: 'END', reason: 'stopped'});
+        resolve();
+      });
+    };
+    const onAbort = () => finish();
+    if (ctx.signal?.aborted) return finish();
+    ctx.signal?.addEventListener('abort', onAbort, {once: true});
+    if (seconds > 0) deadline = setTimeout(() => finish(), seconds * 1000);
+
+    const connect = async () => {
+      if (stopping) return;
+      if (ws) {
+        token = await ctx.freshToken(); // renewed when it ended: the service checks it only when a connection opens
+        client = streamClient({token, env: ctx.env, fetchImpl: ctx.fetch});
+      }
+      if (stopping) return;
+      let opened = false;
+      let acked = false;
+      let socket;
+      try {
+        socket = new WS(`${wsBase}/?access_token=${encodeURIComponent(token)}`);
+      } catch {
+        throw new Error(`Cannot open the websocket of the chat service (${wsBase})`); // never the address with the token
+      }
+      ws = socket;
+      const subscribe = () => socket.send(JSON.stringify({action: 'subscribe', version: '2', topic: 'chat'}));
+      socket.onopen = () => {
+        opened = true;
+        subscribe();
+        clearInterval(keepalive);
+        keepalive = setInterval(subscribe, KEEPALIVE_MS); // subscribing again is harmless
+      };
+      socket.onmessage = (m) => {
+        if (stopping || socket !== ws) return;
+        let d;
+        try {
+          d = JSON.parse(typeof m.data === 'string' ? m.data : Buffer.from(m.data).toString('utf8'));
+        } catch {
+          return;
+        }
+        if (d?.event === 'subscribed') {
+          if (acked) return;
+          acked = true;
+          attempts = 0;
+          const shown = drop({
+            channels: channels.size ? [...channels] : undefined,
+            from: senders.size ? [...senders] : undefined,
+            types: types.size ? [...types] : undefined,
+            mine: mine || undefined,
+          });
+          const event = ready ? 'RECONNECTED' : 'READY';
+          ready = true;
+          queue = queue.then(() => !stopping && ctx.emit({event, user: me, ...shown}));
+          return;
+        }
+        const e = d?.data;
+        if (d?.event !== 'broadcast' || typeof e?.eventType !== 'string' || !wanted(e, filters)) return;
+        queue = queue.then(async () => {
+          if (stopping) return;
+          ctx.emit(raw ? {event: e.eventType, ...e} : await view(e, nameOf));
+          if (left > 0 && --left === 0) finish();
+        });
+      };
+      socket.onerror = () => {
+        // onclose follows and decides
+      };
+      socket.onclose = (ev) => {
+        if (socket !== ws) return;
+        clearInterval(keepalive);
+        if (stopping) return;
+        const again = () => connect().catch((err) => finish(err));
+        if (tokenExp(token) && tokenExp(token) - ctx.clock() < 2 * 60 * 1000 && renewedFor !== token) {
+          renewedFor = token;
+          queue = queue.then(() => !stopping && ctx.emit({event: 'RECONNECTING', reason: 'token'}));
+          again();
+          return;
+        }
+        attempts += 1;
+        if (!opened && attempts >= 5) {
+          finish(new AuthError(`The chat service did not accept the connection (code ${ev?.code}): log in again (wx login) if this repeats`));
+          return;
+        }
+        const wait = BACKOFF[attempts - 1] ?? 30;
+        queue = queue.then(() => !stopping && ctx.emit({event: 'RECONNECTING', code: ev?.code, attempt: attempts, inSeconds: wait}));
+        retry = setTimeout(again, wait * 1000);
+      };
+    };
+    connect().catch((err) => finish(err));
+  });
+}
+
+// One event as a line of text.
+export function eventText(e, ctx) {
+  const c = paint(ctx);
+  const at = c.dim(localTime(ctx?.clock ? ctx.clock() : Date.now(), {seconds: true}));
+  const where = e.channel ? c.bold(oneLine(e.channel, 40)) : e.channelId ?? '';
+  const who = (p) => (p ? p.name ?? p.id : '?');
+  switch (true) {
+    case e.event === 'READY':
+      return `${at}  ${c.green('watching the chats')}${e.types ? ` (${e.types.join(', ')})` : ''}${e.channels ? ` in ${e.channels.join(', ')}` : ''}${e.from ? ` from ${e.from.join(', ')}` : ''}. Ctrl-C stops.`;
+    case e.event === 'RECONNECTING':
+      return `${at}  ${c.yellow(e.reason === 'token' ? 'reconnecting (renewing the login)' : `reconnecting in ${e.inSeconds}s (code ${e.code ?? '?'})`)}`;
+    case e.event === 'RECONNECTED':
+      return `${at}  ${c.green('reconnected')} (events of the pause are not sent again)`;
+    case e.event === 'END':
+      return `${at}  stopped`;
+    case e.event?.startsWith('message.'): {
+      const files = (e.attachments ?? []).map((f) => ` [file: ${oneLine(f.name, 60)}]`).join('');
+      const text = e.event === 'message.deleted' ? '(deleted)' : `${oneLine(e.text ?? '', 500)}${files}`;
+      return `${at}  ${e.event.padEnd(15)}  ${where}  ${c.bold(who(e.from))}: ${text}`;
+    }
+    case e.event?.startsWith('reaction.'): {
+      const counts = Object.entries(e.reactions ?? {}).map(([t, n]) => `${t} ${n}`).join(', ');
+      return `${at}  ${e.event.padEnd(15)}  ${where}  on a message of ${who(e.messageAuthor)}: ${counts ? `[${counts}]` : '(none)'}`;
+    }
+    case e.event?.startsWith('read.'):
+      return `${at}  ${e.event.padEnd(15)}  ${where}  ${who(e.reader)} read up to #${e.readUpTo ?? '?'}`;
+    case e.event?.startsWith('member.'):
+      return `${at}  ${e.event.padEnd(15)}  ${where}  ${e.member?.name ?? e.member?.userId ?? '?'}${e.member?.role ? ` (${e.member.role})` : ''}`;
+    case e.event?.startsWith('typing.'):
+      return `${at}  ${e.event.padEnd(15)}  ${where}  ${who(e.typing)}`;
+    default:
+      return `${at}  ${String(e.event ?? '').padEnd(15)}  ${where}`;
+  }
+}

package/src/cli.mjs

@@ -1,29 +1,96 @@
-// wx <group> <command> [options]: the router. Groups are listed in src/commands/index.mjs; a group is
-// {summary, auth?, commands: {name: {summary, usage, options, args: [min, max], run(ctx)}}}; `auth: true` loads a
-// valid token before the command runs. What run() returns is printed as JSON on stdout.
-import {parseArgs} from 'node:util';
+// The router: `wx <group> <command> [options]` and `wx <command> [options]`. The commands are listed in
+// src/commands/index.mjs. What run() returns is printed on stdout: as text by default (the command's text()
+// formatter, else toText()), as JSON with --output json (--pretty indents it). A streaming command prints one
+// line per event with ctx.emit() (text, or one JSON object per line) and returns nothing. Like the internal Wildix
+// CLI, --output, --pretty and --no-color may stand anywhere on the command line.
+//
+// The context of run():
+//   values, positionals     parsed options and arguments
+//   token                   a valid IdToken when the command needs auth (undefined otherwise)
+//   freshToken()            a valid IdToken again (renewed when it expired): for long-running commands
+//   profile                 the --profile value (or undefined)
+//   client(factory)         factory({token, env, fetchImpl}): a service client bound to the token
+//   emit(data)              print one JSON line on stdout now (streaming commands)
+//   info(text)              print a line for the person on stderr (progress, prompts); never data
+//   signal                  aborted on Ctrl-C / SIGTERM: long-running commands stop and return
+//   output ('text'|'json'), color (colors allowed)
+//   env, stdin, stdout, stderr, fetch, WebSocket, now (ms at the start), clock() (ms now), cwd
 import path from 'node:path';
+import {parseArgs} from 'node:util';
 import {getToken} from './auth.mjs';
-import {COMMON_OPTIONS, GROUPS, commandOf, groupOf} from './commands/index.mjs';
+import {COMMON_OPTIONS, GLOBAL_OPTIONS, REGISTRY, commandOf, groupOf, singleOf} from './commands/index.mjs';
 import {SHELLS, TOP_LEVEL, complete, completionScript, completionUsage} from './completion.mjs';
 import {AuthError, UsageError} from './errors.mjs';
+import {clean, toText} from './format.mjs';
 import {VERSION} from './version.mjs';
 
+const OUTPUTS = GLOBAL_OPTIONS.output.choices;
+
+// The value of an option given as `--name value` or `--name=value` at argv[i]; [value, next index] or undefined.
+function valueOf(argv, i, names) {
+  const a = argv[i];
+  for (const name of names) {
+    if (a === `--${name}`) return [argv[i + 1], i + 1, name];
+    if (a.startsWith(`--${name}=`)) return [a.slice(name.length + 3), i, name];
+  }
+  return undefined;
+}
+
+// Takes --output, --pretty, --no-color and --profile out of the arguments, wherever they stand (up to a "--").
+export function takeGlobals(argv) {
+  const g = {output: 'text', pretty: false, color: true, profile: undefined};
+  const rest = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--') {
+      rest.push(...argv.slice(i));
+      break;
+    }
+    const profile = valueOf(argv, i, ['profile']);
+    if (profile) {
+      const [value, next, name] = profile;
+      if (!value || value.startsWith('--')) throw new UsageError(`--${name} needs a profile: the e-mail of a login`);
+      if (g.profile !== undefined && g.profile.toLowerCase() !== value.toLowerCase()) throw new UsageError(`Two profiles given: ${g.profile} and ${value}`);
+      g.profile = value;
+      i = next;
+      continue;
+    }
+    if (a === '--output' || a.startsWith('--output=')) {
+      g.output = a === '--output' ? argv[(i += 1)] : a.slice('--output='.length);
+      if (!OUTPUTS.includes(g.output)) throw new UsageError(`--output must be one of ${OUTPUTS.join(', ')}${g.output === undefined ? '' : `: ${g.output}`}`);
+    } else if (a === '--pretty') g.pretty = true;
+    else if (a === '--no-color') g.color = false;
+    else rest.push(a);
+  }
+  return {globals: g, rest};
+}
+
+function render(data, formatter, ctx, pretty) {
+  if (ctx.output === 'json') return JSON.stringify(data, null, pretty ? 2 : 0);
+  const t = formatter ? formatter(data, ctx) : toText(data);
+  return clean(Array.isArray(t) ? t.join('\n') : String(t ?? ''));
+}
+
 const pad = (s, n) => s + ' '.repeat(Math.max(1, n - s.length));
 
-function mainUsage() {
+function mainUsage(registry) {
   return [
     'Usage: wx <command> [options]',
     '',
     'Commands:',
-    ...Object.entries(GROUPS).map(([name, g]) => `  ${pad(name, 12)}${g.summary}`),
-    ...Object.entries(TOP_LEVEL).map(([name, summary]) => `  ${pad(name, 12)}${summary}`),
+    ...Object.entries(registry.groups).map(([name, g]) => `  ${pad(name, 14)}${g.summary}`),
+    ...Object.entries(registry.commands).map(([name, c]) => `  ${pad(name, 14)}${c.summary}`),
+    ...Object.entries(TOP_LEVEL).map(([name, summary]) => `  ${pad(name, 14)}${summary}`),
     '',
     'Options:',
-    '  --account EMAIL   the logged-in Wildix account to use (or WILDIX_EMAIL)',
-    '  -h, --help        help of wx, a command or a subcommand',
-    '  -v, --version     the version of wx',
+    '  --output text|json  text for people (default), JSON for scripts and agents',
+    '  --pretty            indent the JSON',
+    '  --no-color          no colors in the text',
+    '  --profile EMAIL     the profile (a logged-in e-mail) to use; else WILDIX_EMAIL, else the default',
+    '  -h, --help          help of wx, a command or a subcommand',
+    '  -v, --version       the version of wx',
     '',
+    'Exit codes: 0 done, 1 error, 2 not logged in, 3 nothing to show (no transcript), 64 wrong usage.',
     'Without installing: npx wldx-cli <command>',
   ].join('\n');
 }
@@ -33,21 +100,19 @@ function groupUsage(name, g) {
 }
 
 function commandUsage(cmd) {
-  const options = Object.entries({...cmd.options, ...COMMON_OPTIONS}).map(([name, o]) => {
-    const flag = `${o.short ? `-${o.short}, ` : ''}--${name}${o.type === 'string' ? ` ${o.choices ? o.choices.join('|') : 'VALUE'}` : ''}`;
-    return `  ${pad(flag, 34)}${o.description ?? ''}`;
+  const options = Object.entries({...cmd.options, ...COMMON_OPTIONS, ...GLOBAL_OPTIONS}).map(([name, o]) => {
+    const value = o.choices && o.choices.length <= 8 ? o.choices.join('|') : o.placeholder ?? 'VALUE';
+    const flag = `${o.short ? `-${o.short}, ` : ''}--${name}${o.type === 'string' ? ` ${value}` : ''}`;
+    const values = o.choices && o.choices.length > 8 ? ` (one of: ${o.choices.join(', ')})` : '';
+    return `  ${pad(flag, 34)}${o.description ?? ''}${o.multiple ? ' (repeatable)' : ''}${values}`;
   });
-  return [`Usage: ${cmd.usage}`, '', cmd.summary, '', 'Options:', ...options].join('\n');
+  return [`Usage: ${cmd.usage}`, '', cmd.summary, ...(cmd.details ? ['', cmd.details] : []), '', 'Options:', ...options].join('\n');
 }
 
 function line(stream, text) {
   stream.write(text.endsWith('\n') ? text : `${text}\n`);
 }
 
-function print(stream, data) {
-  line(stream, JSON.stringify(data, null, stream.isTTY ? 2 : 0));
-}
-
 function completion(args, io) {
   if (args.includes('-h') || args.includes('--help')) return line(io.stdout, completionUsage());
   if (args.length > 1) throw new UsageError('wx completion takes one shell', completionUsage());
@@ -57,59 +122,111 @@ function completion(args, io) {
   line(io.stdout, script);
 }
 
-async function dispatch(argv, io) {
-  const [first, sub, ...rest] = argv;
-  if (!first || first === '-h' || first === '--help' || first === 'help') return line(io.stdout, mainUsage());
-  if (first === '-v' || first === '--version') return line(io.stdout, VERSION);
-  if (first === '__complete') {
-    const words = argv.slice(sub === '--' ? 2 : 1);
-    const out = complete(words, io.env);
-    if (out.length) line(io.stdout, out.join('\n'));
-    return;
-  }
-  if (first === 'completion') return completion(argv.slice(1), io);
-
-  const group = groupOf(first);
-  if (!group) throw new UsageError(`Unknown command: ${first}`, mainUsage());
-  if (sub === '-h' || sub === '--help') return line(io.stdout, groupUsage(first, group));
-  if (!sub) throw new UsageError(`wx ${first} needs a command`, groupUsage(first, group));
-  const cmd = commandOf(group, sub);
-  if (!cmd) throw new UsageError(`Unknown command: wx ${first} ${sub}`, groupUsage(first, group));
+// Ctrl-C and SIGTERM abort ctx.signal once; a second Ctrl-C leaves it to Node (exit).
+function stopSignal(io) {
+  if (io.signal) return {signal: io.signal, dispose() {}};
+  const controller = new AbortController();
+  const onSignal = () => {
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+    controller.abort();
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  return {signal: controller.signal, dispose: onSignal};
+}
 
+async function runCommand(cmd, args, needsAuth, io) {
   const options = {...COMMON_OPTIONS, ...cmd.options};
   let parsed;
   try {
-    parsed = parseArgs({args: rest, options, allowPositionals: true, strict: true});
+    parsed = parseArgs({args, options, allowPositionals: true, strict: true});
   } catch (e) {
     if (String(e.code).startsWith('ERR_PARSE_ARGS')) throw new UsageError(e.message, commandUsage(cmd));
     throw e;
   }
   const {values, positionals} = parsed;
   if (values.help) return line(io.stdout, commandUsage(cmd));
+  if (io.globals.profile !== undefined) values.profile = io.globals.profile;
   for (const [name, o] of Object.entries(options)) {
-    if (o.choices && values[name] !== undefined && !o.choices.includes(values[name])) {
-      throw new UsageError(`--${name} must be one of ${o.choices.join(', ')}: ${values[name]}`, commandUsage(cmd));
-    }
+    const given = values[name] === undefined ? [] : [values[name]].flat();
+    const bad = o.choices && given.find((v) => !o.choices.includes(v));
+    if (bad !== undefined) throw new UsageError(`--${name} must be one of ${o.choices.join(', ')}: ${bad}`, commandUsage(cmd));
   }
   const [min, max] = cmd.args;
   if (positionals.length < min || positionals.length > max) {
     throw new UsageError(positionals.length < min ? 'Missing arguments' : `Unexpected argument: ${positionals[max]}`, commandUsage(cmd));
   }
 
-  const token = group.auth ? await getToken({account: values.account, env: io.env, fetchImpl: io.fetch, now: io.now()}) : undefined;
+  const freshToken = () => getToken({profile: values.profile, env: io.env, fetchImpl: io.fetch, now: io.now()});
+  const token = needsAuth ? await freshToken() : undefined;
+  const stop = stopSignal(io);
   const ctx = {
     values,
     positionals,
+    token,
+    freshToken,
+    profile: values.profile,
+    client: (factory) => factory({token, env: io.env, fetchImpl: io.fetch}),
+    output: io.globals.output,
+    color: io.globals.color && !io.env.NO_COLOR && Boolean(io.stdout.isTTY),
+    emit: (data) => {
+      const text = io.globals.output === 'json' ? JSON.stringify(data) : render(data, cmd.textEvent ?? cmd.text, ctx);
+      if (text) line(io.stdout, text);
+    },
+    info: (text) => line(io.stderr, clean(text)),
+    signal: stop.signal,
+    usage: () => commandUsage(cmd),
     env: io.env,
     stdin: io.stdin,
+    stdout: io.stdout,
+    stderr: io.stderr,
+    fetch: io.fetch,
+    WebSocket: io.WebSocket, // only when injected (tests); a command falls back to globalThis.WebSocket
     now: io.now(),
-    client: (factory) => factory({token, env: io.env, fetchImpl: io.fetch}),
+    clock: io.now,
+    cwd: io.cwd,
   };
-  const result = await cmd.run(ctx);
-  if (result !== undefined) print(io.stdout, result);
+  try {
+    const result = await cmd.run(ctx);
+    if (result !== undefined) {
+      const text = render(result, cmd.text, ctx, io.globals.pretty);
+      if (text) line(io.stdout, text);
+    }
+  } finally {
+    stop.dispose();
+  }
+}
+
+async function dispatch(all, io) {
+  const registry = io.registry;
+  const {globals, rest: argv} = takeGlobals(all);
+  io.globals = globals;
+  const [first, sub, ...rest] = argv;
+  if (!first || first === '-h' || first === '--help' || first === 'help') return line(io.stdout, mainUsage(registry));
+  if (first === '-v' || first === '--version') return line(io.stdout, VERSION);
+  if (first === '__complete') {
+    const out = complete(argv.slice(sub === '--' ? 2 : 1), io.env, registry);
+    if (out.length) line(io.stdout, out.join('\n'));
+    return;
+  }
+  if (first === 'completion') return completion(argv.slice(1), io);
+
+  const single = singleOf(first, registry);
+  if (single) return runCommand(single, argv.slice(1), Boolean(single.auth), io);
+
+  const group = groupOf(first, registry);
+  if (!group) throw new UsageError(`Unknown command: ${first}`, mainUsage(registry));
+  if (sub === '-h' || sub === '--help') return line(io.stdout, groupUsage(first, group));
+  if (!sub) throw new UsageError(`wx ${first} needs a command`, groupUsage(first, group));
+  const cmd = commandOf(group, sub);
+  if (!cmd) throw new UsageError(`Unknown command: wx ${first} ${sub}`, groupUsage(first, group));
+  return runCommand(cmd, rest, Boolean(cmd.auth ?? group.auth), io);
 }
 
-// Runs wx with the arguments and returns the exit code: 0 done, 1 error, 2 not logged in, 64 wrong usage.
+// Runs wx with the arguments and returns the exit code: 0 done, 1 error, 2 not logged in, 3 nothing to show (an
+// error with exitCode 3, e.g. no transcript), 64 wrong usage.
+// io replaces the process streams, environment, fetch, clock and (in tests) the commands themselves.
 export async function main(argv, io = {}) {
   io = {
     stdout: process.stdout,
@@ -118,18 +235,21 @@ export async function main(argv, io = {}) {
     env: process.env,
     fetch: globalThis.fetch,
     now: Date.now,
+    cwd: process.cwd(),
+    registry: REGISTRY,
     ...io,
   };
   try {
     await dispatch(argv, io);
     return 0;
   } catch (e) {
-    line(io.stderr, `wx: ${e.message}`);
+    line(io.stderr, `wx: ${clean(e.message)}`);
     if (e instanceof UsageError) {
       if (e.usage) line(io.stderr, `\n${e.usage}`);
       return 64;
     }
     if (e instanceof AuthError) return 2;
+    if (Number.isInteger(e.exitCode)) return e.exitCode;
     if (io.env.WX_DEBUG === '1' && e.stack) line(io.stderr, e.stack);
     return 1;
   }