biblioplex 0.1.1 → 0.2.1

package/src/mutate.mjs

@@ -1,76 +1,151 @@
-// Unified write path. Every mutating command (add/rm/move/edit/tag/container/
-// import) expresses itself as a pure transform of the snapshot; we diff before
-// vs after into granular sync ops (reusing the app's diffSyncSnapshots) and push
-// once with optimistic concurrency, retrying on a revision conflict by
-// re-reading and re-diffing. This never emits snapshot.replace/history/ui ops,
-// so it stays within what a CLI OAuth token is allowed to push.
-import { diffSyncSnapshots } from '../vendor/syncOps.js';
-import { collectionKey } from '../vendor/collection.js';
-import { mergeIntoCollection } from '../vendor/importMerge.js';
-import { emptySnapshot } from './snapshot.mjs';
-import { CliError } from './errors.mjs';
-
-const clone = (v) => JSON.parse(JSON.stringify(v));
-
-// Capture the before-values of exactly the keys a set of ops touches, so `bp
-// undo` can restore them without disturbing anything else.
-function captureUndo(before, ops) {
-  const collectionKeys = new Set();
-  const containerKeys = new Set();
-  for (const op of ops) {
-    const p = op.payload || {};
-    if (op.type.startsWith('collection.')) {
-      for (const k of [p.key, p.beforeKey, p.afterKey]) if (k) collectionKeys.add(k);
-    } else if (op.type.startsWith('container.') && p.key) {
-      containerKeys.add(p.key);
-    }
+// Safe write flow for mutate_inventory. Public clients can't use the two-phase
+// changeToken path (the server never issues a token to non-chat clients), so we
+// use single-call mutate_inventory: ALWAYS preview with dryRun, let the user
+// confirm, then apply WITHOUT dryRun — reusing the dryRun-suggested
+// idempotencyKey + expectedRevision. Safety (recovery point, 409 concurrency,
+// idempotent retry) is enforced server-side; we just drive it correctly.
+import { createInterface } from 'node:readline';
+import { boolFlag } from './args.mjs';
+import { CliError, usageError } from './errors.mjs';
+import { EXIT } from './constants.mjs';
+import { pickRows } from './render.mjs';
+
+const STATUS_EXIT = {
+  parse_error: EXIT.USAGE,
+  needs_input: EXIT.USAGE,
+  invalid: EXIT.USAGE,
+  not_found: EXIT.NOT_FOUND,
+  unsafe: EXIT.CONFLICT,
+};
+
+function isErrorStatus(sc) {
+  const s = sc && typeof sc === 'object' ? sc.status : undefined;
+  return !!s && s in STATUS_EXIT;
+}
+
+function statusError(sc) {
+  return new CliError(
+    sc.message || sc.error || `mutation ${sc.status}`,
+    STATUS_EXIT[sc.status] || EXIT.ERROR,
+    sc,
+  );
+}
+
+function isConflict(err) {
+  return (
+    err?.code === EXIT.CONFLICT ||
+    err?.extra?.data?.recoveryStrategy === 're_preview' ||
+    err?.extra?.status === 409
+  );
+}
+
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(`${question} [y/N] `, (ans) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test(ans.trim()));
+    });
+  });
+}
+
+// Confirm a side-effecting action. --yes/--force skips; under --json or a
+// non-TTY we refuse rather than hang waiting for input.
+export async function confirm(ctx, question) {
+  if (boolFlag(ctx.flags, 'yes', 'force')) return true;
+  if (ctx.out.json || !process.stdin.isTTY) {
+    throw usageError('refusing to proceed without confirmation — pass --yes (or --dry-run)');
+  }
+  return promptYesNo(question);
+}
+
+function showPreview(out, preview) {
+  const items = preview.previews || preview.preview || pickRows(preview);
+  if (Array.isArray(items) && items.length) {
+    for (const p of items) out.line('  • ' + (p.summary || p.description || JSON.stringify(p)));
+  } else if (preview.summary) {
+    out.line('  • ' + preview.summary);
   }
-  const collection = {};
-  for (const key of collectionKeys) {
-    collection[key] = (before.app.collection || []).find(e => collectionKey(e) === key) || null;
+  if (preview.tagsCleanup)
+    out.info('note: tags normalized — ' + JSON.stringify(preview.tagsCleanup));
+  const removes = preview.removeCount ?? preview.totalRemoves;
+  if (typeof removes === 'number' && removes >= 20) {
+    out.info(`warning: this removes ${removes} rows (server caps removes at 25/operation).`);
   }
-  const containers = {};
-  for (const key of containerKeys) containers[key] = (before.app.containers || {})[key] || null;
-  return { collection, containers };
 }
 
-export async function loadSnapshot(session) {
-  const boot = await session.bootstrap();
-  return {
-    snapshot: boot.hasCloudData && boot.snapshot ? boot.snapshot : emptySnapshot(),
-    revision: boot.revision || 0,
-    collectionId: boot.collectionId || null,
-    hasCloudData: !!boot.hasCloudData,
-  };
+function applyArgsFrom(baseArgs, preview) {
+  const out = { ...baseArgs };
+  const key = preview.idempotencyKey || preview.suggestedIdempotencyKey;
+  if (key) out.idempotencyKey = key;
+  const rev = preview.expectedRevision ?? preview.revision;
+  if (rev != null) out.expectedRevision = rev;
+  return out;
 }
 
-// mutate(draft) edits the snapshot clone in place. It may return metadata (e.g.
-// a human summary) and may throw a CliError to abort. Returns { ops, revision,
-// snapshot, noop, meta }. With dryRun, computes ops but does not push.
-export async function applyMutation(session, mutate, { attempts = 4, dryRun = false } = {}) {
-  let lastConflict;
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    const { snapshot, revision } = await loadSnapshot(session);
-    const before = clone(snapshot);
-    const draft = clone(snapshot);
-    const meta = mutate(draft) || {};
-    // Coalesce any stacks the mutation made collide on the same collectionKey
-    // (e.g. moving a copy into a container that already holds it, or editing
-    // finish/condition to match another stack). Without this, diffSyncSnapshots
-    // keys before/after by collectionKey and would silently drop the colliding
-    // entry, losing quantity. mergeIntoCollection sums qty and unions tags.
-    draft.app.collection = mergeIntoCollection([], draft.app.collection || []);
-    const ops = diffSyncSnapshots(before, draft);
-    if (!ops.length) return { ops: [], revision, snapshot: draft, noop: true, meta };
-    const undo = captureUndo(before, ops);
-    if (dryRun) return { ops, revision, snapshot: draft, dryRun: true, meta, undo };
-    try {
-      const result = await session.push({ ops, baseRevision: revision });
-      return { ops, revision: result.revision, snapshot: result.snapshot, meta, undo: { ...undo, resultRevision: result.revision } };
-    } catch (err) {
-      if (err.conflict && attempt < attempts - 1) { lastConflict = err; continue; }
-      throw err;
+// Drive a mutate_inventory operation. baseArgs is everything except dryRun.
+export async function runMutation(ctx, session, baseArgs, { verb = 'apply' } = {}) {
+  const { out } = ctx;
+
+  let preview = await session.call('mutate_inventory', { ...baseArgs, dryRun: true });
+  if (isErrorStatus(preview)) throw statusError(preview);
+
+  out.line(`${verb}:`);
+  showPreview(out, preview);
+
+  if (boolFlag(ctx.flags, 'dry-run')) {
+    return out.emit(preview, () => out.line('(dry run — nothing applied)')) ?? EXIT.OK;
+  }
+
+  if (!(await confirm(ctx, 'apply this change?'))) {
+    out.info('aborted.');
+    return EXIT.OK;
+  }
+
+  let applied;
+  try {
+    applied = await session.call('mutate_inventory', applyArgsFrom(baseArgs, preview));
+  } catch (err) {
+    if (!isConflict(err)) throw err;
+    // Collection changed between preview and apply: re-preview, re-confirm, re-apply.
+    out.info('collection changed since preview — re-previewing…');
+    preview = await session.call('mutate_inventory', { ...baseArgs, dryRun: true });
+    if (isErrorStatus(preview)) throw statusError(preview);
+    showPreview(out, preview);
+    if (!(await confirm(ctx, 're-apply with the updated state?'))) {
+      out.info('aborted.');
+      return EXIT.OK;
     }
+    applied = await session.call('mutate_inventory', applyArgsFrom(baseArgs, preview));
+  }
+
+  if (isErrorStatus(applied)) throw statusError(applied);
+  return (
+    out.emit(applied, () => {
+      out.line('done.');
+      showPreview(out, applied);
+    }) ?? EXIT.OK
+  );
+}
+
+// Resolve a single concrete printing for `add`. Throws with guidance when
+// ambiguous so the user can narrow with --set/--cn.
+export async function resolveOnePrinting(session, { query, setCode, cn, finish }) {
+  const args = {};
+  if (query) args.query = query;
+  if (setCode) args.setCode = setCode;
+  if (cn) args.cn = cn;
+  if (finish) args.finish = finish;
+  const res = await session.call('resolve_printing', args);
+  if (res?.status === 'not_found') {
+    throw new CliError('no printing matched — try `bp resolve` to explore', EXIT.NOT_FOUND);
+  }
+  const candidates = pickRows(res);
+  if (res?.status === 'ambiguous' || candidates.length > 1) {
+    throw usageError('multiple printings match — narrow with --set and --cn (see `bp resolve`)');
   }
-  throw lastConflict || new CliError('could not apply change after several retries');
+  const one = candidates[0] || res;
+  const scryfallId = one.scryfallId || one.id || res.scryfallId;
+  if (!scryfallId) throw new CliError('could not resolve a printing id', EXIT.ERROR, res);
+  return { scryfallId, candidate: one };
 }

package/src/oauth.mjs

@@ -1,10 +1,13 @@
-// OAuth 2.1 authorization-code + PKCE with an RFC 8252 loopback redirect, plus
-// refresh and revoke. Talks to the biblioplex worker's /authorize, /token and
-// /revoke endpoints. fetchImpl + openBrowser are injectable for tests.
+// OAuth 2.0 authorization-code + PKCE (S256) against the Biblioplex MCP OAuth
+// endpoints, using dynamic client registration (RFC 7591) and an RFC 8252
+// loopback redirect. The Biblioplex worker has no revocation endpoint, so
+// logout is local-only (see commands/logout.mjs).
+//
+// fetchImpl + openBrowser are injectable for tests.
 import http from 'node:http';
 import { execFile } from 'node:child_process';
 import { createPkce, randomState } from './pkce.mjs';
-import { CLI_CLIENT_ID } from './constants.mjs';
+import { CLIENT_LABEL } from './constants.mjs';
 import { CliError } from './errors.mjs';
 
 const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>biblioplex</title>
@@ -14,116 +17,251 @@ const SUCCESS_HTML = `<!doctype html><meta charset="utf-8"><title>biblioplex</ti
 </body>`;
 
 export function defaultOpenBrowser(url) {
-  const cmds = process.platform === 'darwin'
-    ? ['open', [url]]
-    : process.platform === 'win32'
-      ? ['cmd', ['/c', 'start', '', url]]
-      : ['xdg-open', [url]];
+  const cmds =
+    process.platform === 'darwin'
+      ? ['open', [url]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : ['xdg-open', [url]];
   return new Promise((resolve) => {
     execFile(cmds[0], cmds[1], (err) => resolve(!err));
   });
 }
 
-function postForm(base, path, body, fetchImpl) {
-  return fetchImpl(base + path, {
+function postJson(url, body, fetchImpl) {
+  return fetchImpl(url, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
     body: JSON.stringify(body),
   });
 }
 
-export async function exchangeCode({ base, code, verifier, redirectUri, fetchImpl = fetch }) {
-  const res = await postForm(base, '/token', {
-    grant_type: 'authorization_code',
-    code,
-    client_id: CLI_CLIENT_ID,
-    redirect_uri: redirectUri,
-    code_verifier: verifier,
-  }, fetchImpl);
+// An endpoint advertised in server metadata may be absolute or origin-relative.
+function resolveEndpoint(origin, value, fallbackPath) {
+  if (!value) return origin + fallbackPath;
+  try {
+    return new URL(value).href;
+  } catch {
+    return origin + (value.startsWith('/') ? value : '/' + value);
+  }
+}
+
+// GET /.well-known/oauth-authorization-server -> normalized endpoint set.
+export async function discover(origin, fetchImpl = fetch) {
+  let res;
+  try {
+    res = await fetchImpl(origin + '/.well-known/oauth-authorization-server', {
+      headers: { Accept: 'application/json' },
+    });
+  } catch (e) {
+    throw new CliError(`could not reach ${origin}: ${e.message}`);
+  }
+  if (!res.ok) throw new CliError(`OAuth discovery failed (${res.status}) at ${origin}`);
+  const meta = await res.json().catch(() => ({}));
+  const methods = meta.code_challenge_methods_supported || ['S256'];
+  if (!methods.includes('S256')) {
+    throw new CliError('server does not advertise PKCE S256 — cannot log in safely');
+  }
+  return {
+    authorizationEndpoint: resolveEndpoint(origin, meta.authorization_endpoint, '/authorize'),
+    tokenEndpoint: resolveEndpoint(origin, meta.token_endpoint, '/token'),
+    registrationEndpoint: resolveEndpoint(origin, meta.registration_endpoint, '/register'),
+    raw: meta,
+  };
+}
+
+// Dynamic client registration (RFC 7591) for a public, loopback client.
+export async function registerClient({
+  registrationEndpoint,
+  redirectUris,
+  scope,
+  fetchImpl = fetch,
+}) {
+  const res = await postJson(
+    registrationEndpoint,
+    {
+      client_name: CLIENT_LABEL,
+      redirect_uris: redirectUris,
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      scope,
+    },
+    fetchImpl,
+  );
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new CliError('token exchange failed: ' + (data.error_description || data.error || res.status));
+  if (!res.ok || !data.client_id) {
+    throw new CliError(
+      'client registration failed: ' + (data.error_description || data.error || res.status),
+      3,
+    );
+  }
   return data;
 }
 
-export async function refreshTokens({ base, refreshToken, fetchImpl = fetch }) {
-  const res = await postForm(base, '/token', {
-    grant_type: 'refresh_token',
-    refresh_token: refreshToken,
-    client_id: CLI_CLIENT_ID,
-  }, fetchImpl);
+export async function exchangeCode({
+  tokenEndpoint,
+  clientId,
+  code,
+  verifier,
+  redirectUri,
+  fetchImpl = fetch,
+}) {
+  const res = await postJson(
+    tokenEndpoint,
+    {
+      grant_type: 'authorization_code',
+      code,
+      client_id: clientId,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    },
+    fetchImpl,
+  );
   const data = await res.json().catch(() => ({}));
-  if (!res.ok) throw new CliError('session expired — run `bp login` again', 3);
+  if (!res.ok) {
+    throw new CliError(
+      'token exchange failed: ' + (data.error_description || data.error || res.status),
+      3,
+    );
+  }
   return data;
 }
 
-export async function revokeToken({ base, token, fetchImpl = fetch }) {
-  try {
-    await postForm(base, '/revoke', { token }, fetchImpl);
-  } catch { /* logout is best-effort; local creds are cleared regardless */ }
+// Single-use rotating refresh. On invalid_client the caller should re-login
+// (the dynamic registration likely expired). Distinguishes the error cause so
+// the caller can react.
+export async function refreshTokens({ tokenEndpoint, clientId, refreshToken, fetchImpl = fetch }) {
+  const res = await postJson(
+    tokenEndpoint,
+    { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: clientId },
+    fetchImpl,
+  );
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const err = new CliError('session expired — run `bp login` again', 3);
+    err.oauthError = data.error || String(res.status);
+    err.invalidClient = data.error === 'invalid_client';
+    throw err;
+  }
+  return data;
 }
 
-// Runs the interactive browser login. Returns the raw /token response.
+// Interactive browser login. Starts a loopback listener, registers a public
+// client bound to that exact redirect URI, runs the authorization-code+PKCE
+// flow, and exchanges the code. Returns { tokens, clientId } to persist.
 export async function login({
-  base, scope, out, noBrowser = false,
-  openBrowser = defaultOpenBrowser, fetchImpl = fetch, timeoutMs = 300000,
+  origin,
+  scope,
+  out,
+  noBrowser = false,
+  openBrowser = defaultOpenBrowser,
+  fetchImpl = fetch,
+  timeoutMs = 300000,
 }) {
+  const meta = await discover(origin, fetchImpl);
   const { verifier, challenge, method } = createPkce();
   const state = randomState();
 
+  let clientId = null;
   const { code, redirectUri } = await new Promise((resolve, reject) => {
     let redirect = '';
     let timer;
-    function cleanup() { clearTimeout(timer); try { server.close(); } catch {} }
+    const cleanup = () => {
+      clearTimeout(timer);
+      try {
+        server.close();
+      } catch {
+        /* already closed */
+      }
+    };
 
     const server = http.createServer((req, res) => {
       const url = new URL(req.url, 'http://127.0.0.1');
-      if (url.pathname === '/favicon.ico') { res.writeHead(204); res.end(); return; }
-      if (url.pathname !== '/callback') { res.writeHead(404); res.end('not found'); return; }
-
+      if (url.pathname === '/favicon.ico') {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end('not found');
+        return;
+      }
       const params = url.searchParams;
-      // Validate CSRF state first — including on error responses — so a stray
-      // local request can't abort or influence the in-flight login.
+      // Validate CSRF state first — even on error responses — so a stray local
+      // request cannot abort or influence the in-flight login.
       if (params.get('state') !== state) {
         res.writeHead(400, { 'Content-Type': 'text/plain' });
         res.end('state mismatch');
-        cleanup(); reject(new CliError('login aborted: OAuth state mismatch (possible CSRF)', 3));
+        cleanup();
+        reject(new CliError('login aborted: OAuth state mismatch (possible CSRF)', 3));
         return;
       }
       if (params.get('error')) {
         res.writeHead(400, { 'Content-Type': 'text/plain' });
         res.end('authorization failed: ' + params.get('error'));
-        cleanup(); reject(new CliError('authorization denied: ' + params.get('error'), 3));
+        cleanup();
+        reject(new CliError('authorization denied: ' + params.get('error'), 3));
         return;
       }
       res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
       res.end(SUCCESS_HTML);
-      const code = params.get('code');
+      const received = params.get('code');
       cleanup();
-      resolve({ code, redirectUri: redirect });
+      resolve({ code: received, redirectUri: redirect });
+    });
+
+    server.on('error', (e) => {
+      cleanup();
+      reject(new CliError('could not start local login listener: ' + e.message));
     });
 
-    server.on('error', (e) => { cleanup(); reject(new CliError('could not start local login listener: ' + e.message)); });
     server.listen(0, '127.0.0.1', async () => {
-      redirect = `http://127.0.0.1:${server.address().port}/callback`;
-      const authUrl = new URL(base + '/authorize');
-      authUrl.searchParams.set('response_type', 'code');
-      authUrl.searchParams.set('client_id', CLI_CLIENT_ID);
-      authUrl.searchParams.set('redirect_uri', redirect);
-      authUrl.searchParams.set('code_challenge', challenge);
-      authUrl.searchParams.set('code_challenge_method', method);
-      authUrl.searchParams.set('scope', scope);
-      authUrl.searchParams.set('state', state);
-
-      out.info('opening your browser to sign in…');
-      out.info('if it does not open, visit:\n  ' + authUrl.href + '\n');
-      timer = setTimeout(() => { cleanup(); reject(new CliError('login timed out after ' + Math.round(timeoutMs / 1000) + 's', 3)); }, timeoutMs);
-      if (!noBrowser) {
-        const opened = await openBrowser(authUrl.href);
-        if (!opened) out.info('(could not launch a browser automatically — open the link above)');
+      try {
+        redirect = `http://127.0.0.1:${server.address().port}/callback`;
+        const reg = await registerClient({
+          registrationEndpoint: meta.registrationEndpoint,
+          redirectUris: [redirect],
+          scope,
+          fetchImpl,
+        });
+        clientId = reg.client_id;
+
+        const authUrl = new URL(meta.authorizationEndpoint);
+        authUrl.searchParams.set('response_type', 'code');
+        authUrl.searchParams.set('client_id', clientId);
+        authUrl.searchParams.set('redirect_uri', redirect);
+        authUrl.searchParams.set('code_challenge', challenge);
+        authUrl.searchParams.set('code_challenge_method', method);
+        authUrl.searchParams.set('scope', scope);
+        authUrl.searchParams.set('state', state);
+
+        out.info('opening your browser to sign in…');
+        out.info('if it does not open, visit:\n  ' + authUrl.href + '\n');
+        timer = setTimeout(() => {
+          cleanup();
+          reject(new CliError('login timed out after ' + Math.round(timeoutMs / 1000) + 's', 3));
+        }, timeoutMs);
+        if (!noBrowser) {
+          const opened = await openBrowser(authUrl.href);
+          if (!opened) out.info('(could not launch a browser automatically — open the link above)');
+        }
+      } catch (e) {
+        cleanup();
+        reject(e);
       }
     });
   });
 
   if (!code) throw new CliError('no authorization code received', 3);
-  return exchangeCode({ base, code, verifier, redirectUri, fetchImpl });
+  const tokens = await exchangeCode({
+    tokenEndpoint: meta.tokenEndpoint,
+    clientId,
+    code,
+    verifier,
+    redirectUri,
+    fetchImpl,
+  });
+  return { tokens, clientId, tokenEndpoint: meta.tokenEndpoint };
 }

package/src/output.mjs

@@ -5,8 +5,13 @@
 // stays a single clean JSON document.
 
 const COLORS = {
-  reset: '\x1b[0m', dim: '\x1b[2m', bold: '\x1b[1m',
-  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan: '\x1b[36m',
 };
 
 export function createOutput({ json = false, color = true } = {}) {
@@ -17,12 +22,12 @@ export function createOutput({ json = false, color = true } = {}) {
     json,
     useColor,
     c: {
-      dim: s => paint(COLORS.dim, s),
-      bold: s => paint(COLORS.bold, s),
-      red: s => paint(COLORS.red, s),
-      green: s => paint(COLORS.green, s),
-      yellow: s => paint(COLORS.yellow, s),
-      cyan: s => paint(COLORS.cyan, s),
+      dim: (s) => paint(COLORS.dim, s),
+      bold: (s) => paint(COLORS.bold, s),
+      red: (s) => paint(COLORS.red, s),
+      green: (s) => paint(COLORS.green, s),
+      yellow: (s) => paint(COLORS.yellow, s),
+      cyan: (s) => paint(COLORS.cyan, s),
     },
 
     // Primary success payload. JSON mode prints one envelope; otherwise calls
@@ -49,15 +54,17 @@ export function createOutput({ json = false, color = true } = {}) {
     table(columns, rows) {
       if (json || !rows.length) return;
       const widths = columns.map((col, i) =>
-        Math.max(col.header.length, ...rows.map(r => String(r[i] ?? '').length)));
-      const fmt = cells => cells
-        .map((cell, i) => {
-          const s = String(cell ?? '');
-          return columns[i].align === 'right' ? s.padStart(widths[i]) : s.padEnd(widths[i]);
-        })
-        .join('  ')
-        .replace(/\s+$/, '');
-      process.stdout.write(this.c.dim(fmt(columns.map(c => c.header))) + '\n');
+        Math.max(col.header.length, ...rows.map((r) => String(r[i] ?? '').length)),
+      );
+      const fmt = (cells) =>
+        cells
+          .map((cell, i) => {
+            const s = String(cell ?? '');
+            return columns[i].align === 'right' ? s.padStart(widths[i]) : s.padEnd(widths[i]);
+          })
+          .join('  ')
+          .replace(/\s+$/, '');
+      process.stdout.write(this.c.dim(fmt(columns.map((c) => c.header))) + '\n');
       for (const row of rows) process.stdout.write(fmt(row) + '\n');
     },
 
@@ -70,7 +77,9 @@ export function createOutput({ json = false, color = true } = {}) {
     error(err) {
       const message = err?.message || String(err);
       if (json) {
-        process.stdout.write(JSON.stringify({ ok: false, error: { message, ...(err?.extra || {}) } }, null, 2) + '\n');
+        process.stdout.write(
+          JSON.stringify({ ok: false, error: { message, ...(err?.extra || {}) } }, null, 2) + '\n',
+        );
       } else {
         process.stderr.write(this.c.red('error: ') + message + '\n');
       }