@lamalibre/create-lamaste 4.4.1 → 4.6.0

package/vendor/server/src/plugin-approval.js

@@ -1,15 +1,20 @@
 /**
  * `lamaste-server plugins hooks|update|approve-hooks`: why an update waits
- * for approval, the command that approves it, and the arguments that
+ * for approval, what an identity block lets a plugin learn and how an
+ * update changes it, the web tree a version brings and how an update
+ * changes it, the command that approves it, and the arguments that
  * command takes. Pure — no output — so they are tested as they are.
  */
 
 import { terminalText } from './plugin-settings.js';
+import { bytesText, shortDigest } from './plugin-web-surface.js';
 
 const DIGEST_RE = /^[a-f0-9]{64}$/;
 const VERSION_RE = /^[0-9A-Za-z.+-]{1,64}$/;
 /** The reason an update turns secret settings into plain ones. */
 const SETTINGS_SECRET_TO_PLAIN = 'settings.secret-to-plain';
+/** The reason an update adds or removes roles, or widens the attributes its users' records carry. */
+const IDENTITY_CHANGED = 'identity.changed';
 
 /** How `approve-hooks` is called. */
 export const APPROVE_HOOKS_USAGE =
@@ -18,12 +23,13 @@ export const APPROVE_HOOKS_USAGE =
 /**
  * Why a pending update waits, as the terminal shows it: each reason of
  * `approvalRequired` (`[{ code, reason }]`; a secret turned plain is a
- * warning), and the sentences of `autoApproveWithheld` that do not repeat
- * one of them — what auto-approve, when on, could not cover beyond that.
- * Every text as {@link terminalText}.
+ * warning; an identity change carries a note that auto-approve never
+ * covers it), and the sentences of `autoApproveWithheld` that do not
+ * repeat one of them — what auto-approve, when on, could not cover beyond
+ * that. Every text as {@link terminalText}.
  *
  * @param {{ approvalRequired?: unknown, autoApproveWithheld?: unknown }} update
- * @returns {{ required: Array<{ text: string, warning: boolean }>, notCovered: string[] }}
+ * @returns {{ required: Array<{ text: string, warning: boolean, note: string | null }>, notCovered: string[] }}
  */
 export function pendingUpdateReasons(update) {
   const required = (Array.isArray(update?.approvalRequired) ? update.approvalRequired : [])
@@ -31,6 +37,10 @@ export function pendingUpdateReasons(update) {
     .map((entry) => ({
       text: terminalText(entry.reason),
       warning: entry.code === SETTINGS_SECRET_TO_PLAIN,
+      note:
+        entry.code === IDENTITY_CHANGED
+          ? 'who its users are and what it learns about them — auto-approve never covers it'
+          : null,
     }));
   const said = new Set(required.map((line) => line.text));
   const notCovered = (Array.isArray(update?.autoApproveWithheld) ? update.autoApproveWithheld : [])
@@ -39,6 +49,177 @@ export function pendingUpdateReasons(update) {
   return { required, notCovered };
 }
 
+/** What a plugin may declare to receive about its users, in words. */
+const ATTRIBUTE_WORDS = { displayName: 'display name', email: 'email address' };
+
+/** An identity attribute in words (`displayName` → display name). */
+function attributeWords(attribute) {
+  return ATTRIBUTE_WORDS[attribute] ?? terminalText(attribute);
+}
+
+/**
+ * An identity block (normalized: `{ roles: [{ id, label, description? }],
+ * attributes }`) as two lines — its roles, and what it receives about each
+ * member. Empty for anything that is not a block. Every line as
+ * {@link terminalText}.
+ *
+ * @param {unknown} block
+ * @returns {string[]}
+ */
+export function identityBlockLines(block) {
+  if (block === null || typeof block !== 'object' || !Array.isArray(block.roles)) return [];
+  const roles = block.roles
+    .filter((role) => role !== null && typeof role === 'object')
+    .map((role) => `${role.id} (${role.label}${role.description ? ` — ${role.description}` : ''})`);
+  const attributes = Array.isArray(block.attributes) ? block.attributes.map(attributeWords) : [];
+  return [
+    terminalText(`roles:    ${roles.length > 0 ? roles.join(', ') : 'none'}`),
+    terminalText(
+      `receives: ${['user id', 'username', 'roles', 'status', ...attributes].join(', ')} — of the users entitled to it`,
+    ),
+  ];
+}
+
+/**
+ * How an update changes a plugin's identity block (`pendingUpdate.
+ * identity`: `{ before, after, rolesAdded, rolesRemoved, attributesAdded,
+ * attributesRemoved, labelsChanged, grantsAffected? }` — `grantsAffected`:
+ * how many role grants approving it rewrites or revokes, null when unknown):
+ * a headline and a line per kind of
+ * change — roles added or removed and attributes widened wait for an
+ * administrator (`approval`), narrowing and label edits only change the
+ * digest. Null when neither version declares a block, or it is unchanged.
+ * Every text as {@link terminalText}.
+ *
+ * @param {unknown} diff
+ * @returns {{ headline: string, lines: Array<{ text: string, approval: boolean }> } | null}
+ */
+export function identityDiffLines(diff) {
+  if (diff === null || typeof diff !== 'object') return null;
+  const list = (value) => (Array.isArray(value) ? value.map(String) : []);
+  const labelOf = (block, id) =>
+    Array.isArray(block?.roles) ? (block.roles.find((r) => r?.id === id)?.label ?? null) : null;
+  const role = (block) => (id) => {
+    const label = labelOf(block, id);
+    return label ? `${id} (${label})` : id;
+  };
+  const lines = [];
+  const add = (label, entries, approval) => {
+    if (entries.length === 0) return;
+    lines.push({
+      text: terminalText(
+        `${label}: ${entries.join(', ')}${approval ? ' — waits for approval' : ''}`,
+      ),
+      approval,
+    });
+  };
+  add('roles added', list(diff.rolesAdded).map(role(diff.after)), true);
+  add('roles removed', list(diff.rolesRemoved).map(role(diff.before)), true);
+  add('receives more about its users', list(diff.attributesAdded).map(attributeWords), true);
+  add('receives less about its users', list(diff.attributesRemoved).map(attributeWords), false);
+  add('role labels changed', list(diff.labelsChanged).map(role(diff.after)), false);
+  // A removed role stays removed: approving revokes it from the grants that hold it.
+  if (list(diff.rolesRemoved).length > 0 && 'grantsAffected' in diff) {
+    const affected = diff.grantsAffected;
+    const parts =
+      affected === null || typeof affected !== 'object'
+        ? ['not known (Gatekeeper could not be read)']
+        : [
+            ...(affected.revoked > 0 ? [`${affected.revoked} revoked`] : []),
+            ...(affected.rewritten > 0
+              ? [`${affected.rewritten} narrowed to the roles that stay`]
+              : []),
+          ];
+    add('role grants affected', parts.length > 0 ? parts : ['none'], true);
+  }
+  const before = diff.before != null;
+  const after = diff.after != null;
+  if (lines.length === 0 && before === after) return null;
+  const headline = !before
+    ? 'declares identity for the first time'
+    : !after
+      ? 'no longer declares identity — it is sent no users, its role grants are revoked and its user surface is no longer served'
+      : 'changes its identity';
+  return { headline, lines };
+}
+
+/**
+ * What the installed version's web surface brings (the hook status's
+ * `web`: `{ declared, approved, treeSha256, surface }`) as lines — the tree
+ * the approval covers, and the site Lamaste offers for it. Empty when it
+ * declares none.
+ *
+ * @param {unknown} web
+ * @returns {string[]}
+ */
+export function webSurfaceBlockLines(web) {
+  if (web === null || typeof web !== 'object' || !web.declared) return [];
+  const surface = web.surface !== null && typeof web.surface === 'object' ? web.surface : null;
+  const lines = [terminalText(`tree:     ${web.treeSha256 ?? 'unknown'}`)];
+  if (surface) {
+    lines.push(
+      terminalText(
+        `site:     offered on ${surface.defaultSubdomain} (${surface.accessMode}), the shell from ${surface.root}/ of its server package`,
+      ),
+    );
+  }
+  return lines;
+}
+
+/**
+ * How an update changes the plugin's web tree (`pendingUpdate.web`:
+ * `{ before: sha256 | null, after: { sha256, files, totalBytes } | null }`
+ * — part of the digest): a headline and its lines. Null when neither
+ * version declares a web surface.
+ *
+ * @param {unknown} web
+ * @returns {{ headline: string, lines: string[], changed: boolean } | null}
+ */
+export function webTreeDiffLines(web) {
+  if (web === null || typeof web !== 'object') return null;
+  const before = typeof web.before === 'string' ? web.before : null;
+  const after =
+    web.after !== null && typeof web.after === 'object' && typeof web.after.sha256 === 'string'
+      ? web.after
+      : null;
+  if (before === null && after === null) return null;
+  const contents = (tree) => `${tree.files} file(s), ${bytesText(tree.totalBytes)}`;
+  if (after === null) {
+    return {
+      headline:
+        'no longer declares a web surface — its site answers 503 until a version that does is approved',
+      lines: [terminalText(`tree:     ${shortDigest(before)} → none`)],
+      changed: true,
+    };
+  }
+  if (before === null) {
+    return {
+      headline: 'declares a web surface for the first time',
+      lines: [
+        terminalText(`tree:     ${after.sha256}`),
+        terminalText(`contents: ${contents(after)}`),
+      ],
+      changed: true,
+    };
+  }
+  if (before === after.sha256) {
+    return {
+      headline: 'keeps its web tree',
+      lines: [terminalText(`tree:     ${after.sha256} (${contents(after)})`)],
+      changed: false,
+    };
+  }
+  return {
+    headline: 'changes its web tree — its site serves the new shell once approved',
+    lines: [
+      terminalText(`tree:     ${shortDigest(before)} → ${shortDigest(after.sha256)}`),
+      terminalText(`new tree: ${after.sha256}`),
+      terminalText(`contents: ${contents(after)}`),
+    ],
+    changed: true,
+  };
+}
+
 /**
  * The command that approves what plugin `name` brings: the installed
  * version by its digest (`{ digest }`), or a pending update by its version

package/vendor/server/src/plugin-identity.js

@@ -0,0 +1,382 @@
+/**
+ * Users and identity in requests at the terminal — the arguments of
+ * `lamaste-server users …`, `plugins entitlements|identity-sync` and
+ * `tunnels bind-user-surface|unbind-user-surface`, and the words their
+ * output is made of. Pure — no output, no panel — so they are tested as
+ * they are. Every string from the panel goes through `terminalText` before
+ * it is printed; `--json` carries the data as it came.
+ */
+
+import {
+  IDENTITY_ROLE_ID_REGEX,
+  IDENTITY_ROLES_MAX,
+  isIdentityUuid,
+  isLamasteUsername,
+} from '@lamalibre/lamaste';
+import { formatMoment, terminalText } from './plugin-settings.js';
+
+/** A Lamaste (Gatekeeper) group name — Gatekeeper's rule. */
+const GROUP_NAME_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+// ---------------------------------------------------------------------------
+// Arguments
+// ---------------------------------------------------------------------------
+
+/** How `plugins entitlements` is called. */
+export const ENTITLEMENTS_USAGE =
+  'Usage: lamaste-server plugins entitlements <name> [--user <username> | --group <group> --roles <a,b>] [--revoke --user <username> | --group <group>]';
+
+/** The value after `flag` (at `args[index]`): `{ value }`, or `{ error }` when it has none. */
+function flagValue(args, index, flag, usage) {
+  const value = args[index + 1];
+  if (value === undefined || value.startsWith('--')) {
+    return { error: `${flag} needs a value — ${usage}` };
+  }
+  return { value };
+}
+
+/**
+ * The arguments of `plugins entitlements <name> …` after the subcommand:
+ * the plugin and, to change something, a principal — `--user <username>`
+ * or `--group <group>` — with `--roles a,b` (give exactly these roles) or
+ * `--revoke` (take every role away). Without a principal it lists them.
+ *
+ * @param {string[]} args
+ * @returns {{ ok: true, name: string, action: 'list' }
+ *   | { ok: true, name: string, action: 'set', principalType: 'user' | 'group', principalId: string, roles: string[] }
+ *   | { ok: true, name: string, action: 'revoke', principalType: 'user' | 'group', principalId: string }
+ *   | { ok: false, error: string }}
+ */
+export function parseEntitlementsArgs(args) {
+  const usage = ENTITLEMENTS_USAGE;
+  let name = null;
+  let principal = null;
+  let roles = null;
+  let revoke = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--user' || arg === '--group') {
+      const read = flagValue(args, i, arg, usage);
+      if (read.error) return { ok: false, error: read.error };
+      if (principal !== null) {
+        return { ok: false, error: `Name one principal: --user or --group, once — ${usage}` };
+      }
+      principal = { principalType: arg === '--user' ? 'user' : 'group', principalId: read.value };
+      i++;
+    } else if (arg === '--roles') {
+      const read = flagValue(args, i, arg, usage);
+      if (read.error) return { ok: false, error: read.error };
+      roles = read.value.split(',').map((role) => role.trim());
+      i++;
+    } else if (arg === '--revoke') {
+      revoke = true;
+    } else if (arg.startsWith('--')) {
+      return { ok: false, error: `Unknown option ${arg} — ${usage}` };
+    } else if (name === null) {
+      name = arg;
+    } else {
+      return { ok: false, error: `Unexpected argument "${arg}" — ${usage}` };
+    }
+  }
+  if (name === null) return { ok: false, error: usage };
+  if (principal === null) {
+    if (roles !== null || revoke) {
+      return {
+        ok: false,
+        error: `Name whose roles: --user <username> or --group <group> — ${usage}`,
+      };
+    }
+    return { ok: true, name, action: 'list' };
+  }
+  if (principal.principalType === 'user' && !isLamasteUsername(principal.principalId)) {
+    return { ok: false, error: `"${principal.principalId}" is not a username` };
+  }
+  if (
+    principal.principalType === 'group' &&
+    !(
+      principal.principalId.length >= 2 &&
+      principal.principalId.length <= 63 &&
+      GROUP_NAME_RE.test(principal.principalId)
+    )
+  ) {
+    return { ok: false, error: `"${principal.principalId}" is not a group name` };
+  }
+  if (revoke) {
+    if (roles !== null) {
+      return { ok: false, error: `--revoke takes every role away; it takes no --roles — ${usage}` };
+    }
+    return { ok: true, name, action: 'revoke', ...principal };
+  }
+  if (roles === null) {
+    return { ok: false, error: `Give --roles <a,b>, or --revoke — ${usage}` };
+  }
+  const unique = [...new Set(roles)].sort();
+  if (unique.length === 0 || unique.length > IDENTITY_ROLES_MAX || unique.includes('')) {
+    return { ok: false, error: `--roles is a comma-separated list of role ids — ${usage}` };
+  }
+  const bad = unique.find((role) => !IDENTITY_ROLE_ID_REGEX.test(role));
+  if (bad !== undefined) return { ok: false, error: `"${bad}" is not a role id` };
+  return { ok: true, name, action: 'set', ...principal, roles: unique };
+}
+
+/**
+ * The arguments of `plugins identity-sync <name> [--reconcile]`.
+ *
+ * @param {string[]} args
+ * @returns {{ ok: true, name: string, reconcile: boolean } | { ok: false, error: string }}
+ */
+export function parseIdentitySyncArgs(args) {
+  const usage = 'Usage: lamaste-server plugins identity-sync <name> [--reconcile]';
+  let name = null;
+  let reconcile = false;
+  for (const arg of args) {
+    if (arg === '--reconcile') reconcile = true;
+    else if (arg.startsWith('--')) return { ok: false, error: `Unknown option ${arg} — ${usage}` };
+    else if (name === null) name = arg;
+    else return { ok: false, error: `Unexpected argument "${arg}" — ${usage}` };
+  }
+  if (name === null) return { ok: false, error: usage };
+  return { ok: true, name, reconcile };
+}
+
+/**
+ * The arguments of `users disable|enable|delete <username>` (`--erase` for
+ * delete) and `users erase <userId>`.
+ *
+ * @param {'disable' | 'enable' | 'delete' | 'erase'} sub
+ * @param {string[]} args  what follows the subcommand
+ * @returns {{ ok: true, username: string, erase: boolean } | { ok: true, userId: string } | { ok: false, error: string }}
+ */
+export function parseUserArgs(sub, args) {
+  const usage =
+    sub === 'erase'
+      ? 'Usage: lamaste-server users erase <userId> (a deleted user, as `users directory` lists them)'
+      : sub === 'delete'
+        ? 'Usage: lamaste-server users delete <username> [--erase]'
+        : `Usage: lamaste-server users ${sub} <username>`;
+  let target = null;
+  let erase = false;
+  for (const arg of args) {
+    if (arg === '--erase' && sub === 'delete') erase = true;
+    else if (arg.startsWith('--')) return { ok: false, error: `Unknown option ${arg} — ${usage}` };
+    else if (target === null) target = arg;
+    else return { ok: false, error: `Unexpected argument "${arg}" — ${usage}` };
+  }
+  if (target === null) return { ok: false, error: usage };
+  if (sub === 'erase') {
+    if (!isIdentityUuid(target)) {
+      return { ok: false, error: `"${target}" is not a user id — ${usage}` };
+    }
+    return { ok: true, userId: target };
+  }
+  if (!isLamasteUsername(target)) return { ok: false, error: `"${target}" is not a username` };
+  return { ok: true, username: target, erase };
+}
+
+/**
+ * The arguments of `tunnels bind-user-surface|unbind-user-surface <tunnel>
+ * <plugin>`: the tunnel (its id, subdomain or FQDN) and the plugin (its name
+ * or route).
+ *
+ * @param {'bind-user-surface' | 'unbind-user-surface'} sub
+ * @param {string[]} args
+ * @returns {{ ok: true, tunnel: string, plugin: string } | { ok: false, error: string }}
+ */
+export function parseUserSurfaceArgs(sub, args) {
+  const usage = `Usage: lamaste-server tunnels ${sub} <tunnel id | subdomain | fqdn> <plugin>`;
+  const positional = [];
+  for (const arg of args) {
+    if (arg.startsWith('--')) return { ok: false, error: `Unknown option ${arg} — ${usage}` };
+    positional.push(arg);
+  }
+  if (positional.length !== 2) return { ok: false, error: usage };
+  return { ok: true, tunnel: positional[0], plugin: positional[1] };
+}
+
+/**
+ * The tunnel `ref` names among `tunnels` (as `tunnels.json` holds them): by
+ * id, subdomain or FQDN — a host, never an internal plugin tunnel.
+ *
+ * @param {Array<Record<string, unknown>>} tunnels
+ * @param {string} ref
+ * @returns {{ tunnel: Record<string, unknown> } | { error: string }}
+ */
+export function findHostTunnel(tunnels, ref) {
+  const hosts = tunnels.filter((t) => typeof t.subdomain === 'string' && t.subdomain.length > 0);
+  const tunnel =
+    hosts.find((t) => t.id === ref) ??
+    hosts.find((t) => t.fqdn === ref) ??
+    hosts.find((t) => t.subdomain === ref);
+  if (!tunnel) return { error: `No tunnel with the id, subdomain or FQDN "${ref}"` };
+  return { tunnel };
+}
+
+/**
+ * The installed agent-hosted plugin `ref` names (its name or route) among
+ * the panel's plugin list.
+ *
+ * @param {Array<Record<string, unknown>>} plugins
+ * @param {string} ref
+ * @returns {{ plugin: Record<string, unknown> } | { error: string }}
+ */
+export function findPluginByNameOrRoute(plugins, ref) {
+  const plugin = plugins.find((p) => p.name === ref) ?? plugins.find((p) => p.route === ref);
+  if (!plugin) return { error: `No installed plugin named "${ref}" or holding that route` };
+  if (typeof plugin.route !== 'string' || plugin.route.length === 0) {
+    return { error: `Plugin "${ref}" has no route` };
+  }
+  return { plugin };
+}
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+/**
+ * Why users cannot reach a plugin's `/app`, or that they can — the identity
+ * view's `readiness` in words.
+ *
+ * @param {{ ready?: boolean, reason?: string | null, version?: string | null } | null | undefined} readiness
+ * @returns {{ ready: boolean, text: string }}
+ */
+export function readinessText(readiness) {
+  if (!readiness) return { ready: false, text: 'unknown' };
+  if (readiness.ready) return { ready: true, text: 'ready — users reach its application' };
+  const version = readiness.version ? `version ${terminalText(readiness.version)}` : 'it';
+  switch (readiness.reason) {
+    case 'not_installed':
+      return { ready: false, text: 'not installed' };
+    case 'no_identity':
+      return { ready: false, text: `${version} declares no identity` };
+    case 'not_approved':
+      return { ready: false, text: `${version} waits for approval (plugins hooks <name>)` };
+    case 'not_hosted':
+      return { ready: false, text: 'not hosted on an agent, or its hosting is not active' };
+    case 'not_answered':
+      return {
+        ready: false,
+        text: `its agent half has not answered the identity feed for ${version} yet`,
+      };
+    default:
+      return { ready: false, text: terminalText(readiness.reason ?? 'not ready') };
+  }
+}
+
+/** Why a route bound to a tunnel is not served there (`userSurfaceStatus`'s reason), in words. */
+export function userSurfaceStatusText(status) {
+  if (!status) return 'status unknown';
+  if (status.served) return 'served';
+  switch (status.reason) {
+    case 'not_installed':
+      return 'not served — no installed plugin holds the route';
+    case 'no_identity':
+      return 'not served yet — its installed version declares no identity (requests go down the tunnel)';
+    case 'not_approved':
+      return 'not served yet — its installed version waits for approval (requests go down the tunnel)';
+    case 'not_hosting_agent':
+      return 'not served — the agent carrying this tunnel does not host the plugin (moved, revoked, or hosted elsewhere); requests go down the tunnel';
+    default:
+      return `not served (${terminalText(status.reason)})`;
+  }
+}
+
+/** Why a user left an audience, as the terminal says it. */
+const REMOVED_STATUS = new Map([
+  ['unentitled', 'removed (no longer entitled)'],
+  ['deleted', 'removed (deleted)'],
+  ['erased', 'erased'],
+]);
+
+/**
+ * An audience row (`{ userId, seq, version, updatedAt, change }`) as the
+ * terminal lists it: who (the member's, or the last known, name), the roles
+ * held and where they stand.
+ *
+ * @param {{ userId: string, seq: number, change: Record<string, any> | null }} row
+ * @returns {{ userId: string, seq: number, who: string, roles: string, status: string, member: boolean }}
+ */
+export function audienceRowText(row) {
+  const change = row.change ?? {};
+  const name = (user) =>
+    user?.displayName && user?.username
+      ? `${user.displayName} (${user.username})`
+      : (user?.username ?? '—');
+  // A row the panel cannot read.
+  const text = {
+    userId: terminalText(row.userId),
+    seq: row.seq,
+    who: '—',
+    roles: '',
+    status: 'unreadable',
+    member: false,
+  };
+  if (change.kind === 'upsert' && change.member) {
+    return {
+      ...text,
+      who: terminalText(name(change.member)),
+      roles: terminalText((change.member.roles ?? []).join(', ')),
+      status: change.member.status === 'disabled' ? 'disabled' : 'active',
+      member: true,
+    };
+  }
+  if (change.kind === 'remove') {
+    return {
+      ...text,
+      who: change.reason === 'erased' ? '—' : terminalText(name(change.last)),
+      status: REMOVED_STATUS.get(change.reason) ?? 'removed',
+    };
+  }
+  return text;
+}
+
+/**
+ * The feed's state (the identity view's `sync`) as `[label, value]` rows:
+ * the directory, what the agent half follows, its cursor against the head,
+ * the version that answered, the last sync and reconcile with what it
+ * found, the last error.
+ *
+ * @param {Record<string, any>} sync
+ * @param {number} now  epoch ms
+ * @returns {Array<[string, string]>}
+ */
+export function syncRows(sync, now) {
+  const follows =
+    sync.halfDirectoryId === null || sync.halfDirectoryId === undefined
+      ? 'nothing yet'
+      : sync.halfDirectoryId === sync.directoryId
+        ? 'this directory'
+        : `another directory (${terminalText(sync.halfDirectoryId)}) — the next sync replays`;
+  const rows = [
+    ['directory', terminalText(sync.directoryId)],
+    ['half follows', follows],
+    [
+      'position',
+      `cursor ${sync.cursor ?? '—'} of head ${sync.head}${sync.behind > 0 ? ` — ${sync.behind} change(s) behind` : ' — up to date'}`,
+    ],
+    ['answered for', sync.readyVersion ? `version ${terminalText(sync.readyVersion)}` : '—'],
+    ['last sync', sync.lastSyncAt ? formatMoment(sync.lastSyncAt, now) : '—'],
+    [
+      'last reconcile',
+      sync.lastReconcileAt
+        ? `${formatMoment(sync.lastReconcileAt, now)}${sync.lastMismatches != null ? ` — ${sync.lastMismatches} out of step` : ''}`
+        : '—',
+    ],
+  ];
+  if (sync.lastError) rows.push(['last error', terminalText(sync.lastError)]);
+  return rows;
+}
+
+/**
+ * A warning a users or entitlement change came back with — a sentence, or
+ * `{ step, message }` — as one line.
+ *
+ * @param {unknown} warning
+ * @returns {string}
+ */
+export function warningLine(warning) {
+  if (typeof warning === 'string') return terminalText(warning);
+  if (warning !== null && typeof warning === 'object' && typeof warning.message === 'string') {
+    return terminalText(warning.step ? `${warning.step}: ${warning.message}` : warning.message);
+  }
+  return terminalText(warning);
+}