@alexify/migronaut 2.0.0 → 2.2.0

package/src/bullmq/wait.js

@@ -0,0 +1,124 @@
+const { ConfigInvalidError, QueueJobFailedError } = require('../errors/index.js');
+const { redactOutbound } = require('../utils/redact.js');
+
+/** Rejects a budgeted await that outlived the deadline — told apart from every other failure */
+const DEADLINE = Symbol('wait deadline');
+
+/**
+ * How much longer than the remaining budget BullMQ's own `waitUntilFinished`
+ * timer is given. That timer is only there to take its listeners off
+ * QueueEvents; whether the wait timed out is this module's clock to say.
+ * Given the same remaining time, BullMQ's timer can fire first — while
+ * `Date.now()` is still a millisecond short of the deadline — and a timeout
+ * would be reported as an ordinary job failure.
+ */
+const LISTENER_GRACE_MS = 1000;
+
+/**
+ * Wait for every job of an enqueue group, in group order — and for the
+ * group's converge job last, when it has one — and resolve
+ * `{ groupId, direction, batch, results, converge? }`.
+ *
+ * Rejects with QueueJobFailedError at the first job that fails or outlives the
+ * budget — the jobs after it cannot succeed anyway (they fail as blocked), and
+ * `context.results` keeps what finished before it. `timeoutMs` is one budget
+ * for the whole group, not per job.
+ *
+ * Finished jobs must still exist in the queue when this attaches: a
+ * `removeOnComplete: true` queue gives it nothing to read.
+ */
+async function waitForGroup({
+  queue,
+  queueEvents,
+  groupId,
+  direction,
+  batch,
+  jobs,
+  converge,
+  timeoutMs,
+}) {
+  if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+    throw new ConfigInvalidError('timeoutMs must be a positive finite number', { timeoutMs });
+  }
+  const results = [];
+  // Nothing was enqueued: nothing to wait for, and no reason to need QueueEvents.
+  if (jobs.length === 0 && !converge) return { groupId, direction, batch, results };
+  if (!queueEvents) {
+    throw new ConfigInvalidError(
+      'wait() needs QueueEvents — pass bullmq.QueueEvents to createMigrationQueue, ' +
+        'or a queueEvents instance to wait()',
+      { groupId },
+    );
+  }
+
+  // One budget for everything this call awaits — connecting QueueEvents and
+  // reading a job included: with a Redis that is down, those are the awaits
+  // that would otherwise hang.
+  const deadline = timeoutMs !== undefined ? Date.now() + timeoutMs : undefined;
+  const budgeted = (promise) => {
+    if (deadline === undefined) return promise;
+    let timer;
+    const expired = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => reject(DEADLINE), Math.max(0, deadline - Date.now()));
+    });
+    return Promise.race([promise, expired]).finally(() => clearTimeout(timer));
+  };
+  const timedOut = () => deadline !== undefined && Date.now() >= deadline;
+
+  /**
+   * The typed code a failed job reported in its progress — what a caller
+   * branches on (MIGRATION_BLOCKED, CHECKSUM_MISMATCH, …) instead of parsing
+   * `failedReason`. Best-effort: the job may be gone, or Redis unreachable.
+   */
+  async function failureCode(id) {
+    try {
+      const code = (await budgeted(queue.getJob(id)))?.progress?.code;
+      return typeof code === 'string' && code.length <= 64 ? code : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Wait for one job; `message` and `fields` say which one in a failure */
+  async function finish(id, message, fields) {
+    const fail = (failedReason, timedOut, code) =>
+      new QueueJobFailedError(message, {
+        groupId,
+        jobId: id,
+        ...fields,
+        failedReason,
+        timedOut,
+        ...(code !== undefined ? { code } : {}),
+        results: [...results],
+      });
+
+    const outOfTime = () => fail(`wait timed out after ${timeoutMs}ms`, true);
+    try {
+      await budgeted(queueEvents.waitUntilReady?.());
+      const job = await budgeted(queue.getJob(id));
+      if (!job) throw fail('job not found — it was removed before wait() could read it', false);
+      if (timedOut()) throw outOfTime();
+      return await budgeted(
+        job.waitUntilFinished(
+          queueEvents,
+          deadline === undefined ? undefined : deadline - Date.now() + LISTENER_GRACE_MS,
+        ),
+      );
+    } catch (error) {
+      if (error instanceof QueueJobFailedError) throw error;
+      // Decided by the clock, not by how BullMQ happens to word its timeout.
+      if (error === DEADLINE || timedOut()) throw outOfTime();
+      const reason = redactOutbound(error instanceof Error ? error.message : String(error));
+      throw fail(reason, false, await failureCode(id));
+    }
+  }
+
+  for (const { id, migration } of jobs) {
+    results.push(await finish(id, `Migration job failed: ${migration}`, { migration, direction }));
+  }
+  if (!converge) return { groupId, direction, batch, results };
+  const converged = await finish(converge.id, 'Converge job failed', { kind: 'converge' });
+  return { groupId, direction, batch, results, converge: converged };
+}
+
+module.exports = { waitForGroup };

package/src/cli/args.js

@@ -221,10 +221,20 @@ class Command {
     }
   }
 
-  /** Seed negatable options: declaring `--no-x` makes `x` default to true */
+  /**
+   * Seed negatable options: declaring `--no-x` makes `x` default to true —
+   * unless `--x` is declared too. Then, as in commander, the pair is
+   * tri-state: `true`, `false`, or unset (`undefined`) when neither was given,
+   * which is how a flag can override a config value only when actually passed.
+   */
   #seedNegatableDefaults() {
     for (const option of this.#options) {
-      if (option.negated) this.#values[option.key] = true;
+      if (!option.negated) continue;
+      let twin = false;
+      for (const other of this.#options) {
+        if (!other.negated && other.key === option.key) twin = true;
+      }
+      if (!twin) this.#values[option.key] = true;
     }
   }
 

package/src/cli/commands/converge.js

@@ -0,0 +1,188 @@
+const { needsConfirmation } = require('../../core/converge-plan.js');
+const { searchBuildState } = require('../../core/search-index-spec.js');
+const { ConfigInvalidError, RunAbortedError } = require('../../errors/index.js');
+const { confirm, defineCommand, EXIT_CODES } = require('../shared.js');
+const { renderConvergeHistory, renderConvergeTable } = require('../table.js');
+
+/**
+ * Every row the operator must confirm, across all collections: a dropped or
+ * rebuilt index, a dropped search index, or a validator change on a
+ * collection that holds data.
+ */
+function actionsToConfirm(plan) {
+  const found = [];
+  for (const collection of plan.collections) {
+    for (const action of collection.actions) {
+      if (needsConfirmation(action, collection.actions)) {
+        found.push({ collection: collection.name, ...action });
+      }
+    }
+  }
+  return found;
+}
+
+/** Whether a plan holds a conflict — the run refuses it whatever the answer */
+function hasConflict(plan) {
+  return plan.collections.some((collection) =>
+    collection.actions.some((action) => action.action === 'conflict'),
+  );
+}
+
+function assertNotStopped(stopRequested) {
+  if (stopRequested()) {
+    throw new RunAbortedError('Stopped by signal before anything was changed', { results: [] });
+  }
+}
+
+/** Register the `converge` command (declared indexes and validators → the database) */
+function registerConverge(program) {
+  defineCommand(program, {
+    name: 'converge',
+    description:
+      'Bring declared collections (indexes, search indexes, validators) to their declared state',
+    options: [
+      ['--dry-run', 'Show what would change without changing anything'],
+      [
+        '--check',
+        `Exit with code ${EXIT_CODES.COLLECTIONS_DRIFT} if anything would change (CI gate; implies --dry-run)`,
+      ],
+      [
+        '--prune',
+        'Drop undeclared indexes and search indexes (in collections whose definition does not decide)',
+      ],
+      ['--ordered', 'Refuse while any migration is still pending'],
+      ['--reason <text>', 'Why — recorded in the converge history (who: the OS user)'],
+      ['--history', 'Show the converge history instead of converging (read-only)'],
+      ['--limit <n>', 'How many history entries to show (with --history; default 20)'],
+      [
+        '--rebuild-unique',
+        'Allow rebuilding a unique index (drops the constraint until the new one is built)',
+      ],
+      [
+        '--wait-search',
+        'Wait until every declared search index is queryable (overrides waitForSearchIndexes)',
+      ],
+      ['--no-wait-search', 'Do not wait for search indexes, whatever waitForSearchIndexes says'],
+      [
+        '-y, --yes',
+        'Drop and rebuild indexes, and change validators, without asking (required with --json)',
+      ],
+    ],
+    lockable: true,
+    mutating: true,
+    // Whether a run is destructive is only known once the live database has
+    // been read, so the confirmation cannot live in a preflight: plan first,
+    // ask only when the plan drops or rebuilds an index, then apply — the way
+    // `unlock` reads the lock before asking.
+    run: async (migrator, opts, _positionals, { logger, json, spinner, stopRequested }) => {
+      const waitSearch = typeof opts.waitSearch === 'boolean' ? opts.waitSearch : undefined;
+      if (waitSearch !== undefined && (opts.history || opts.dryRun || opts.check)) {
+        throw new ConfigInvalidError(
+          `--${waitSearch ? '' : 'no-'}wait-search applies to a real converge — not to ` +
+            `${opts.history ? '--history' : opts.check ? '--check' : '--dry-run'}`,
+        );
+      }
+      if (opts.history) {
+        return migrator.convergeHistory(
+          opts.limit !== undefined ? { limit: Number(opts.limit) } : {},
+        );
+      }
+      if (opts.limit !== undefined) {
+        throw new ConfigInvalidError('--limit only applies to --history');
+      }
+      const prune = {
+        ...(opts.prune ? { prune: true } : {}),
+        ...(opts.rebuildUnique ? { rebuildUnique: true } : {}),
+      };
+      const ordered = opts.ordered ? { ordered: true } : {};
+      const planOnly = Boolean(opts.dryRun || opts.check);
+      if (planOnly || !opts.yes) {
+        spinner?.start('Comparing declared collections with the database…');
+        let plan;
+        try {
+          plan = await migrator.converge({ dryRun: true, ...prune });
+        } finally {
+          spinner?.stop();
+        }
+        if (planOnly) return plan;
+        assertNotStopped(stopRequested);
+        const destructive = actionsToConfirm(plan);
+        // A plan with a conflict is refused by the run itself — asking first
+        // would be a question whose answer changes nothing.
+        if (destructive.length > 0 && !hasConflict(plan)) {
+          // --json is non-interactive: dropping an index the operator never
+          // saw listed is exactly what the confirmation is for, so it needs an
+          // explicit --yes rather than a silent go-ahead. An additive plan
+          // applies without one.
+          if (json) {
+            throw new ConfigInvalidError(
+              `converge would drop or rebuild an index, drop a search index, or change a validator ` +
+                `(${destructive.length} change(s)) — pass --yes to confirm in --json mode`,
+              { destructive },
+            );
+          }
+          logger.info(renderConvergeTable(plan));
+          if (opts.rebuildUnique && destructive.some((action) => action.action === 'recreate')) {
+            logger.warn(
+              '⚠ --rebuild-unique: a rebuilt unique index enforces nothing until it is built ' +
+                'again — a duplicate written in between makes it unbuildable',
+            );
+          }
+          const proceed = await confirm('Apply these changes? [y/N] ');
+          if (!proceed) {
+            logger.info('Aborted');
+            return undefined;
+          }
+          assertNotStopped(stopRequested);
+        }
+      }
+      spinner?.start('Converging…');
+      try {
+        return await migrator.converge({
+          noLock: opts.noLock,
+          ...prune,
+          ...ordered,
+          ...(waitSearch !== undefined ? { waitForSearchIndexes: waitSearch } : {}),
+          ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+        });
+      } finally {
+        spinner?.stop();
+      }
+    },
+    render: (result, { logger, opts }) => {
+      if (Array.isArray(result)) {
+        logger.info(renderConvergeHistory(result));
+        return;
+      }
+      // A real run's own lines (✔ Created …, the rollup) are already out.
+      if (!result.dryRun) return;
+      if (result.collections.length === 0) {
+        logger.info('No collections declared — set collections or collectionsDir');
+        return;
+      }
+      logger.info(renderConvergeTable(result, { all: Boolean(opts.verbose) }));
+    },
+    after: (result, { logger, opts }) => {
+      if (!opts.check || result === undefined) return;
+      // A search index that failed to build serves nothing, whatever its
+      // definition says — the gate fails on it too, though converge cannot fix it.
+      // .error writes to stderr, so JSON stdout stays a single clean document.
+      let failed = 0;
+      for (const index of result.search?.notReady ?? []) {
+        if (searchBuildState(index) !== 'failed') continue;
+        failed += 1;
+        logger.error(
+          `✖ Search index ${index.collection} "${index.name}" failed to build` +
+            `${index.message ? `: ${index.message}` : ''}`,
+        );
+      }
+      if (result.inSync && failed === 0) return;
+      if (!result.inSync) logger.error('✖ The database differs from the declared collections');
+      // A dedicated code: a CI gate must tell "out of step" (act: converge)
+      // from "the check itself crashed" (act: page).
+      process.exitCode = EXIT_CODES.COLLECTIONS_DRIFT;
+    },
+  });
+}
+
+module.exports = { registerConverge };

package/src/cli/commands/down.js

@@ -11,6 +11,7 @@ function registerDown(program) {
       ['--batch <n>', 'Revert a specific batch number'],
       ['--steps <n>', 'Revert the last N migrations, regardless of batch'],
       ['--to <file>', 'Revert everything applied after this file (it stays applied)'],
+      ['--reason <text>', 'Why — recorded on the changelog with the run (who: the OS user)'],
     ],
     lockable: true,
     mutating: true,
@@ -22,6 +23,7 @@ function registerDown(program) {
         ...(opts.batch !== undefined ? { batch: Number(opts.batch) } : {}),
         ...(opts.steps !== undefined ? { steps: Number(opts.steps) } : {}),
         ...(opts.to ? { to: opts.to } : {}),
+        ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
       }),
     // No render: core logs every ↩ Reverted line itself.
   });

package/src/cli/commands/lock.js

@@ -26,7 +26,8 @@ function registerLock(program) {
       }
       logger.info(
         `Lock held by pid ${holder.pid} on ${holder.host} (${holder.executedBy}) ` +
-          `since ${lockedAtText(holder.lockedAt)}`,
+          `since ${lockedAtText(holder.lockedAt)}` +
+          (holder.runId ? ` — run ${holder.runId}` : ''),
       );
     },
   });

package/src/cli/commands/redo.js

@@ -6,9 +6,16 @@ function registerRedo(program) {
     name: 'redo',
     description: 'Rollback then re-apply the last applied migration, or a specific file',
     args: [['[file]', 'Specific migration file to redo']],
+    options: [
+      ['--reason <text>', 'Why — recorded on the changelog with the run (who: the OS user)'],
+    ],
     lockable: true,
     mutating: true,
-    run: (migrator, opts, [file]) => migrator.redo(file, { noLock: opts.noLock }),
+    run: (migrator, opts, [file]) =>
+      migrator.redo(file, {
+        noLock: opts.noLock,
+        ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+      }),
     // No render: core logs the ↩/✔ lines itself.
   });
 }

package/src/cli/commands/up.js

@@ -13,6 +13,9 @@ function registerUp(program) {
       ['-f, --force', 'Re-run an already-applied migration (requires a file)'],
       ['-y, --yes', 'Confirm --force non-interactively (required with --json)'],
       ['--step', 'Apply each migration as its own batch (revert individually later)'],
+      ['--converge', 'Converge the declared collections afterwards (overrides convergeAfterUp)'],
+      ['--no-converge', 'Do not converge afterwards, whatever convergeAfterUp says'],
+      ['--reason <text>', 'Why — recorded on the changelog with the run (who: the OS user)'],
     ],
     lockable: true,
     mutating: true,
@@ -23,6 +26,11 @@ function registerUp(program) {
       if (opts.force && !file) {
         throw new ConfigInvalidError('--force requires a specific migration file');
       }
+      if (opts.converge === true && (file || opts.to)) {
+        throw new ConfigInvalidError(
+          '--converge needs a bulk up — it cannot follow a single file or --to',
+        );
+      }
       if (opts.force && file && !opts.yes) {
         // --json is non-interactive: refuse rather than silently re-running or
         // hanging on a prompt that can't be answered. --yes is the explicit opt-in.
@@ -45,8 +53,13 @@ function registerUp(program) {
         ...(opts.force ? { force: true } : {}),
         ...(opts.step ? { step: true } : {}),
         ...(opts.to ? { to: opts.to } : {}),
+        ...(typeof opts.converge === 'boolean' ? { converge: opts.converge } : {}),
+        ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
       }),
-    // No render: core logs every ✔ Applied line itself.
+    // No render: core logs every ✔ Applied line itself — and, after a bulk run
+    // that converges, every converge line too. `--json` stays the migration
+    // rows: an array cannot carry the converge result without breaking its
+    // consumers (that is what `migronaut converge --json` is for).
   });
 }
 

package/src/cli/exit-codes.js

@@ -4,8 +4,10 @@
  * script testing `!= 0` is unaffected.
  *
  * Every MigronautError code has an entry (pinned by a superset test), plus
- * two CLI-condition codes that have no error class: PENDING_MIGRATIONS
- * (`status --check` found work) and AUDIT_FAILED (an audit check failed).
+ * three CLI-condition codes that have no error class: PENDING_MIGRATIONS
+ * (`status --check` found work), AUDIT_FAILED (an audit check failed) and
+ * COLLECTIONS_DRIFT (`converge --check` found the database out of step with
+ * the declared collections).
  *
  * Exported from the package root so a programmatic wrapper can mirror the
  * CLI's exit semantics without hardcoding numbers from the docs table. Kept
@@ -34,6 +36,11 @@ const EXIT_CODES = {
   LOCK_RELEASE_FAILED: 21,
   AUDIT_FAILED: 22,
   MIGRATION_OUT_OF_ORDER: 23,
+  MIGRATION_BLOCKED: 24,
+  QUEUE_JOB_INVALID: 25,
+  QUEUE_JOB_FAILED: 26,
+  CONVERGE_FAILED: 27,
+  COLLECTIONS_DRIFT: 28,
 };
 
 module.exports = { EXIT_CODES };

package/src/cli/index.js

@@ -1,6 +1,7 @@
 const { Command } = require('./args.js');
 const { registerAudit } = require('./commands/audit.js');
 const { registerBaseline } = require('./commands/baseline.js');
+const { registerConverge } = require('./commands/converge.js');
 const { registerCreate } = require('./commands/create.js');
 const { registerDown } = require('./commands/down.js');
 const { registerDryRun } = require('./commands/dry-run.js');
@@ -42,6 +43,7 @@ function buildProgram() {
   registerUp(program);
   registerDown(program);
   registerRedo(program);
+  registerConverge(program);
   registerStatus(program);
   registerList(program);
   registerDryRun(program);

package/src/cli/shared.js

@@ -162,9 +162,13 @@ function reportError(error, { json, verbose, logger }) {
 /**
  * Construct a MigratorKit from CLI options, run `fn(migrator, cli)`, always
  * disconnect, and translate failures into a non-zero exit code with a
- * readable message. `cli` is `{ logger, json, opts }` — the one level-aware
- * logger every command must render through, so `--quiet`/`--verbose` apply to
- * command output and not only to core's log lines.
+ * readable message. `cli` is `{ logger, json, opts, spinner, stopRequested }`:
+ * the one level-aware logger every command must render through, so
+ * `--quiet`/`--verbose` apply to command output and not only to core's log
+ * lines; the spinner (undefined in JSON or quiet mode) for a command that
+ * drives its own progress text; and whether a signal asked to stop — which a
+ * command that reads, asks, then acts must check between those steps, since
+ * `migrator.stop()` is a no-op while no run is in flight.
  */
 async function withMigrator(opts, fn, options = {}) {
   // Required here, not at module top: the orchestrator is the CLI's one heavy
@@ -237,7 +241,13 @@ async function withMigrator(opts, fn, options = {}) {
     if (detachSignals.stopRequested?.()) {
       throw new RunAbortedError('Stopped by signal before the run started', { results: [] });
     }
-    await fn(migrator, { logger, json, opts });
+    await fn(migrator, {
+      logger,
+      json,
+      opts,
+      spinner,
+      stopRequested: () => detachSignals.stopRequested?.() ?? false,
+    });
   } catch (error) {
     // Safety net: clear any spinner still spinning before printing the error.
     spinner?.stop();

package/src/cli/table.js

@@ -1,3 +1,5 @@
+const { TARGET_LABELS, isDestructive } = require('../core/converge-plan.js');
+const { searchBuildState } = require('../core/search-index-spec.js');
 const { createColors, stripAnsi } = require('../utils/colors.js');
 const { formatDateTime } = require('../utils/date.js');
 // Shared with the logger and spinner — cell values come from the changelog and
@@ -247,6 +249,166 @@ function renderImportTable(rows) {
   return renderTable(head, cells);
 }
 
+/** Longest index or collection name rendered before it is ellipsized */
+const MAX_NAME_WIDTH = 48;
+
+/** Longest converge detail rendered before it is ellipsized */
+const MAX_DETAIL_WIDTH = 72;
+
+/** Render a converge action cell: what changes stands out, what does not recedes */
+function convergeActionCell(colors, action) {
+  switch (action) {
+    case 'create':
+      return colors.green(action);
+    case 'modify':
+      return colors.cyan(action);
+    case 'recreate':
+    case 'drop':
+      return colors.yellow(action);
+    case 'conflict':
+      return colors.red(action);
+    default:
+      return colors.dim(action);
+  }
+}
+
+/** Where the server is with a search index, when it is not simply serving it */
+function searchBuildDetail(build) {
+  if (build === undefined) return '';
+  switch (searchBuildState(build)) {
+    case 'serving':
+      return '';
+    case 'failed':
+      return `FAILED${build.message ? `: ${build.message}` : ''}`;
+    case 'updating':
+      return 'updating';
+    case 'stale':
+      return 'STALE — not replicating';
+    default:
+      return build.status;
+  }
+}
+
+/** Whether a search index row is one worth showing even when nothing changes: not serving yet */
+function searchNotServing(action) {
+  return action.target === 'searchIndex' && searchBuildDetail(action.build) !== '';
+}
+
+/** The detail column: what differs, or why the row is what it is — and a search index's build */
+function convergeDetail(action) {
+  if (action.reason === 'name' && action.liveName !== undefined) {
+    return `renamed from "${action.liveName}"`;
+  }
+  if (action.target !== 'searchIndex') return action.reason ?? '';
+  const parts = [];
+  const type = action.to?.type ?? action.from?.type;
+  if (type === 'vectorSearch' && (action.action === 'create' || action.action === 'modify')) {
+    parts.push('vectorSearch');
+  }
+  if (action.reason) parts.push(action.reason);
+  const build = searchBuildDetail(action.build);
+  if (build) parts.push(build);
+  return parts.join(' · ');
+}
+
+/**
+ * Render a converge plan (or result) as a table plus a one-line summary.
+ * Rows that need nothing are folded into the summary unless `all` — a large
+ * schema would otherwise bury its two changes under fifty "unchanged" lines.
+ */
+function renderConvergeTable(result, { all = false } = {}) {
+  const colors = palette();
+  const cells = [];
+  const counts = {
+    change: 0,
+    destructive: 0,
+    conflict: 0,
+    keep: 0,
+    searchKeep: 0,
+    skip: 0,
+    unchanged: 0,
+    touched: 0,
+  };
+  for (const collection of result.collections) {
+    let changes = 0;
+    for (const action of collection.actions) {
+      if (action.action === 'unchanged') counts.unchanged += 1;
+      else if (action.action === 'keep' && action.target === 'searchIndex') counts.searchKeep += 1;
+      else if (action.action === 'keep') counts.keep += 1;
+      else if (action.action === 'conflict') counts.conflict += 1;
+      else if (action.action === 'skip') counts.skip += 1;
+      else changes += 1;
+      if (isDestructive(action)) counts.destructive += 1;
+      if (action.action === 'unchanged' && !all && !searchNotServing(action)) continue;
+      const named = action.target === 'index' || action.target === 'searchIndex';
+      cells.push([
+        truncate(sanitize(collection.name), MAX_NAME_WIDTH),
+        TARGET_LABELS[action.target] ?? action.target,
+        named ? truncate(sanitize(action.name), MAX_NAME_WIDTH) : '',
+        convergeActionCell(colors, action.action),
+        truncate(sanitize(convergeDetail(action)), MAX_DETAIL_WIDTH),
+      ]);
+    }
+    counts.change += changes;
+    if (changes > 0) counts.touched += 1;
+  }
+  const collections = result.collections.length;
+  let summary;
+  if (counts.change === 0 && counts.conflict === 0) {
+    summary = `✔ ${collections} collection(s) match their declarations`;
+  } else {
+    const verb = result.dryRun ? 'Would make' : 'Made';
+    summary =
+      `${verb} ${counts.change} change(s) in ${counts.touched} of ${collections} ` +
+      'collection(s)';
+  }
+  const parts = [summary];
+  if (counts.destructive > 0) parts.push(`${counts.destructive} drop/rebuild`);
+  if (counts.conflict > 0) parts.push(colors.red(`${counts.conflict} conflict(s)`));
+  if (counts.keep > 0) parts.push(`${counts.keep} undeclared index(es) kept`);
+  if (counts.searchKeep > 0) parts.push(`${counts.searchKeep} undeclared search index(es) kept`);
+  if (counts.skip > 0) {
+    parts.push(colors.yellow(`${counts.skip} search index(es) skipped — Search unavailable`));
+  }
+  let building = 0;
+  let stale = 0;
+  let failed = 0;
+  for (const index of result.search?.notReady ?? []) {
+    const state = searchBuildState(index);
+    if (state === 'failed') failed += 1;
+    else if (state === 'stale') stale += 1;
+    else building += 1;
+  }
+  if (building > 0) parts.push(`${building} search index(es) building`);
+  if (stale > 0) parts.push(colors.yellow(`${stale} search index(es) stale`));
+  if (failed > 0) parts.push(colors.red(`${failed} search index(es) failed`));
+  if (counts.unchanged > 0 && !all) parts.push(`${counts.unchanged} unchanged`);
+  const line = parts.join(' · ');
+  if (cells.length === 0) return line;
+  return `${renderTable(['Collection', 'Target', 'Index', 'Action', 'Detail'], cells)}\n${line}`;
+}
+
+/**
+ * Render the converge history: one line per converge that changed something
+ * or failed, newest first — the audit view (`migronaut converge --history`).
+ */
+function renderConvergeHistory(entries) {
+  if (entries.length === 0) return 'No converge has changed anything yet';
+  const colors = palette();
+  const cells = entries.map((entry) => [
+    entry.startedAt instanceof Date ? entry.startedAt.toISOString() : String(entry.startedAt),
+    entry.trigger,
+    entry.success ? colors.green('ok') : colors.red('failed'),
+    String(entry.changed),
+    truncate(sanitize(entry.requestedBy ?? entry.executedBy ?? ''), MAX_NAME_WIDTH),
+    truncate(
+      sanitize(entry.reason ?? (entry.success ? '' : (entry.error ?? ''))),
+      MAX_DETAIL_WIDTH,
+    ),
+  ]);
+  return renderTable(['When', 'Trigger', 'Result', 'Changes', 'Who', 'Why'], cells);
+}
+
 module.exports = {
   charWidth,
   sanitize,
@@ -256,4 +418,6 @@ module.exports = {
   renderStatusTable,
   renderImportTable,
   renderRowsOrEmpty,
+  renderConvergeTable,
+  renderConvergeHistory,
 };