wldx-cli 0.1.1 → 1.1.0

package/src/chat/lib.mjs

@@ -0,0 +1,210 @@
+// Helpers of the chat commands (wx chat, channel, inbox, file, user, section): the checks of the agent skill's
+// lib.sh (whole numbers in a range, ids, reaction types, secret paths), the user id of the logged-in user, names
+// of users for the text output, and the presigned upload and download of files (no token goes to those URLs).
+import {randomUUID} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {jwtClaims} from 'wldx-core/auth';
+import {UsageError} from 'wldx-core/errors';
+import {readForUpload, refuseUnsafeWrite} from 'wldx-core/files';
+import {apiPath, request} from 'wldx-core/http';
+import {streamClient} from '../stream.mjs';
+
+// The operations the service answers with HTTP 400 "Operation <Name> is not implemented." (checked 2026-11-05).
+export const NOT_IMPLEMENTED_CHECKED = '2026-11-05';
+export const NOT_IMPLEMENTED = ' (not implemented by the service yet)';
+export const notImplemented = (operation) =>
+  `The service does not implement ${operation} yet (it answers HTTP 400 "Operation ${operation} is not implemented.", checked ${NOT_IMPLEMENTED_CHECKED}). Do not retry it.`;
+
+// A whole number from min to max (the service refuses anything else with a 400 that tells little); undefined stays.
+export function checkInt(name, value, min, max) {
+  if (value === undefined) return undefined;
+  const s = String(value);
+  if (!/^\d{1,12}$/.test(s) || Number(s) < min || Number(s) > max)
+    throw new UsageError(`--${name} must be a whole number from ${min} to ${max}: ${value}`);
+  return Number(s);
+}
+
+// An id that goes into a request path or a body: id characters only, never "/", "?", "#", ".." or nothing.
+export function checkId(what, value) {
+  const v = String(value ?? '');
+  if (!/^[A-Za-z0-9_+][A-Za-z0-9_.:+-]*$/.test(v) || v.includes('..'))
+    throw new UsageError(`${what} is not a valid id: ${value}`);
+  return v;
+}
+
+export function checkReaction(type) {
+  if (!/^[a-z0-9_+-]{1,64}$/.test(String(type)))
+    throw new UsageError(`A reaction type must match [a-z0-9_+-] (up to 64): ${type}`);
+  return type;
+}
+
+// The id of a new group channel: 8-4-4-4-8 characters. Without one the service makes a 36-character id that none
+// of its own calls accepts afterwards.
+export const CHANNEL_ID = /^[0-9a-z_]{8}-[0-9a-z_]{4}-[0-9a-z_]{4}-[0-9a-z_]{4}-[0-9a-z_]{8}$/;
+export const newChannelId = () => randomUUID().slice(0, -4);
+
+// The text argument; "-" reads stdin.
+export async function readText(arg, stdin) {
+  if (arg !== '-') return arg;
+  const chunks = [];
+  for await (const c of stdin) chunks.push(Buffer.from(c));
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+export const api = (ctx) => ctx.client(streamClient);
+
+// The stream user id of the logged-in user, found by the e-mail of the token (once per context).
+const ME = Symbol('me');
+export async function meId(ctx, client = api(ctx)) {
+  if (ctx[ME]) return ctx[ME];
+  const email = jwtClaims(ctx.token).email;
+  if (!email) throw new Error('The login token carries no e-mail');
+  const r = await client.call('POST', '/users/query', {query: {emails: [email]}});
+  const id = r?.users?.[0]?.id;
+  if (!id) throw new Error('Could not find your chat user');
+  ctx[ME] = id;
+  return id;
+}
+
+export const displayName = (u) => u?.displayName ?? u?.name;
+
+// The users of these ids, one users query per 100 ids: Map id -> user. A lookup that fails gives no users (a name
+// is a nicety of the text output: the id is printed instead).
+export async function usersById(client, ids) {
+  const unique = [...new Set(ids.filter((id) => typeof id === 'string' && id))];
+  const out = new Map();
+  for (let i = 0; i < unique.length; i += 100) {
+    try {
+      const r = await client.call('POST', '/users/query', {query: {ids: unique.slice(i, i + 100)}});
+      for (const u of r?.users ?? []) out.set(u.id, u);
+    } catch {
+      // names stay ids
+    }
+  }
+  return out;
+}
+
+// Names for the text output ride on the result under a symbol: JSON output (JSON.stringify) never sees them.
+export const NAMES = Symbol('names');
+export async function withNames(ctx, data, ids, client = api(ctx)) {
+  if (ctx.output !== 'text' || !data || typeof data !== 'object') return data;
+  const users = await usersById(client, ids);
+  Object.defineProperty(data, NAMES, {value: users, enumerable: false});
+  return data;
+}
+export const nameIn = (data, id) => (id ? (displayName(data?.[NAMES]?.get(id)) ?? id) : '');
+
+// The ids of people a message names: its author, the author of its quote.
+export const messageUserIds = (m) => [m?.userId, m?.quote?.userId, m?.pinnedBy];
+
+// ── files ───────────────────────────────────────────────────────────────────────────────────────────────────
+
+// The checks of files to attach and to save: src/files.mjs.
+export {refuseSecretPath} from 'wldx-core/files';
+
+const MIME = {
+  txt: 'text/plain',
+  md: 'text/markdown',
+  csv: 'text/csv',
+  html: 'text/html',
+  htm: 'text/html',
+  css: 'text/css',
+  js: 'text/javascript',
+  json: 'application/json',
+  xml: 'application/xml',
+  pdf: 'application/pdf',
+  zip: 'application/zip',
+  gz: 'application/gzip',
+  tar: 'application/x-tar',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  heic: 'image/heic',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  m4a: 'audio/mp4',
+  mp4: 'video/mp4',
+  mov: 'video/quicktime',
+  webm: 'video/webm',
+};
+export const mimeOf = (file) => MIME[path.extname(file).slice(1).toLowerCase()] ?? 'application/octet-stream';
+
+// A presigned URL of the storage: https (http only with WILDIX_ALLOW_CUSTOM_URL=1, tests). It gets no token.
+function presigned(url, env) {
+  let u;
+  try {
+    u = new URL(url);
+  } catch {
+    throw new Error('The service gave no valid storage link');
+  }
+  if (u.protocol !== 'https:' && !(env.WILDIX_ALLOW_CUSTOM_URL === '1' && u.protocol === 'http:'))
+    throw new Error(`The storage link is not https: ${u.protocol}`);
+  return u.href;
+}
+
+const ATTACHMENT_FIELDS = ['fsId', 'name', 'size', 'mime', 'width', 'height', 'thumbnail'];
+export const attachmentOf = (f) =>
+  Object.fromEntries(ATTACHMENT_FIELDS.filter((k) => f?.[k] !== undefined && f?.[k] !== null).map((k) => [k, f[k]]));
+
+// Uploads a file to a channel and returns the attachment object to put into a message (fsId, name, size, mime…).
+export async function uploadFile(ctx, channel, file, client = api(ctx)) {
+  const data = readForUpload(path.resolve(ctx.cwd ?? process.cwd(), file), ctx.env);
+  const name = path.basename(file);
+  const r = await client.call('POST', apiPath`/channels/${channel}/files`, {name});
+  if (!r?.fsId || !r?.presignedUploadUrl) throw new Error('Unexpected answer of the upload: no fsId or link');
+  const fsId = checkId('The file id of the answer', r.fsId);
+  await request(presigned(r.presignedUploadUrl, ctx.env), {
+    method: 'PUT',
+    raw: {data, contentType: mimeOf(file)},
+    responseType: 'text',
+    fetchImpl: ctx.fetch,
+    timeoutMs: 600_000,
+    service: 'the storage',
+  });
+  const info = await client.call('GET', apiPath`/channels/${channel}/files/${fsId}`);
+  return attachmentOf(info?.file ?? {fsId, name, size: data.length});
+}
+
+// Saves a file of a message to `to`, which must not exist yet (nothing is ever overwritten).
+export async function downloadFile(ctx, channel, message, fsId, to, client = api(ctx)) {
+  const out = path.resolve(ctx.cwd ?? process.cwd(), to);
+  refuseUnsafeWrite(out, ctx.env);
+  if (fs.existsSync(out))
+    throw new UsageError(`${to} exists already: choose another path (nothing was overwritten or deleted)`);
+  const dir = path.dirname(out);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory())
+    throw new UsageError(`The folder of ${to} does not exist`);
+  const r = await client.call(
+    'GET',
+    apiPath`/channels/${channel}/messages/${message}/files/${fsId}/download-url` + '?download=1',
+  );
+  if (!r?.presignedDownloadUrl) throw new Error('No download link in the answer');
+  const data = await request(presigned(r.presignedDownloadUrl, ctx.env), {
+    responseType: 'buffer',
+    fetchImpl: ctx.fetch,
+    timeoutMs: 600_000,
+    service: 'the storage',
+  });
+  const tmp = path.join(dir, `.download.${process.pid}.${randomUUID().slice(0, 8)}`);
+  fs.writeFileSync(tmp, data, {flag: 'wx', mode: 0o600});
+  try {
+    fs.linkSync(tmp, out); // fails when the path appeared meanwhile: never overwrites
+  } catch (e) {
+    if (e.code === 'EEXIST') throw new UsageError(`${to} appeared meanwhile: nothing was overwritten`);
+    throw e;
+  } finally {
+    fs.rmSync(tmp, {force: true});
+  }
+  return {ok: true, file: out, bytes: data.length};
+}

package/src/chat/watch.mjs

@@ -0,0 +1,282 @@
+// 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 'wldx-core/auth';
+import {AuthError} from 'wldx-core/errors';
+import {localTime, oneLine, paint} from 'wldx-core/format';
+import {streamWsUrl} from 'wldx-core/services';
+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,136 +1,17 @@
-// 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';
-import path from 'node:path';
-import {getToken} from './auth.mjs';
-import {COMMON_OPTIONS, GROUPS, commandOf, groupOf} from './commands/index.mjs';
-import {SHELLS, TOP_LEVEL, complete, completionScript, completionUsage} from './completion.mjs';
-import {AuthError, UsageError} from './errors.mjs';
+// wx: the spec of the command line (its commands, its lines in the help) on the router of wldx-core.
+import {createMain} from 'wldx-core/cli';
+import {complete as completeOf} from 'wldx-core/completion';
+import {setProgram} from 'wldx-core/program';
+import {COMMANDS, GROUPS} from './commands/index.mjs';
 import {VERSION} from './version.mjs';
 
-const pad = (s, n) => s + ' '.repeat(Math.max(1, n - s.length));
+setProgram({name: 'wx', pkg: 'wldx-cli', version: VERSION});
 
-function mainUsage() {
-  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}`),
-    '',
-    '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',
-    '',
-    'Without installing: npx wldx-cli <command>',
-  ].join('\n');
-}
+export const SPEC = {
+  groups: GROUPS,
+  commands: COMMANDS,
+  help: {exitCodes: 'Exit codes: 0 done, 1 error, 2 not logged in, 3 nothing to show (no transcript), 64 wrong usage.'},
+};
 
-function groupUsage(name, g) {
-  return [`Usage: wx ${name} <command> [options]`, '', ...Object.values(g.commands).flatMap((cmd) => [`  ${cmd.usage}`, `      ${cmd.summary}`])].join('\n');
-}
-
-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 ?? ''}`;
-  });
-  return [`Usage: ${cmd.usage}`, '', cmd.summary, '', '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());
-  const shell = args[0] ?? path.basename(io.env.SHELL ?? '');
-  const script = completionScript(shell);
-  if (!script) throw new UsageError(`No completion for the shell "${shell}": give one of ${SHELLS.join(', ')}`, completionUsage());
-  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));
-
-  const options = {...COMMON_OPTIONS, ...cmd.options};
-  let parsed;
-  try {
-    parsed = parseArgs({args: rest, 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));
-  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 [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 ctx = {
-    values,
-    positionals,
-    env: io.env,
-    stdin: io.stdin,
-    now: io.now(),
-    client: (factory) => factory({token, env: io.env, fetchImpl: io.fetch}),
-  };
-  const result = await cmd.run(ctx);
-  if (result !== undefined) print(io.stdout, result);
-}
-
-// Runs wx with the arguments and returns the exit code: 0 done, 1 error, 2 not logged in, 64 wrong usage.
-export async function main(argv, io = {}) {
-  io = {
-    stdout: process.stdout,
-    stderr: process.stderr,
-    stdin: process.stdin,
-    env: process.env,
-    fetch: globalThis.fetch,
-    now: Date.now,
-    ...io,
-  };
-  try {
-    await dispatch(argv, io);
-    return 0;
-  } catch (e) {
-    line(io.stderr, `wx: ${e.message}`);
-    if (e instanceof UsageError) {
-      if (e.usage) line(io.stderr, `\n${e.usage}`);
-      return 64;
-    }
-    if (e instanceof AuthError) return 2;
-    if (io.env.WX_DEBUG === '1' && e.stack) line(io.stderr, e.stack);
-    return 1;
-  }
-}
+export const main = createMain(SPEC);
+export const complete = (words, env = process.env) => completeOf(words, env, SPEC);