@alexify/migronaut 2.1.0 → 2.3.0

package/src/cli/commands/background.js

@@ -0,0 +1,500 @@
+const { ConfigInvalidError, LockAlreadyHeldError } = require('../../errors/index.js');
+const { createColors } = require('../../utils/colors.js');
+const { errorText } = require('../../utils/error.js');
+const { confirm, defineCommand, EXIT_CODES } = require('../shared.js');
+const { renderTable } = require('../table.js');
+
+/**
+ * `migronaut background <action> [name]` — background migrations from the
+ * command line: see them, run them, control them, dry-run them, watch for
+ * drift. One command with an action (the argument parser has one level of
+ * subcommands); each action takes the flags it needs and refuses the others.
+ */
+
+const ACTIONS = new Set([
+  'status',
+  'run',
+  'pause',
+  'resume',
+  'cancel',
+  'retry',
+  'repin',
+  'dry-run',
+  'unlock',
+  'verify',
+  'watch',
+]);
+
+/** Which flags each action takes (besides the global ones) */
+const FLAGS = {
+  status: ['partitions', 'check'],
+  run: ['all', 'concurrency', 'once'],
+  pause: ['wait', 'reason'],
+  resume: ['reason'],
+  cancel: ['wait', 'reason', 'yes'],
+  retry: ['fromStart', 'repin', 'reason', 'yes'],
+  repin: ['reason', 'yes'],
+  'dry-run': [
+    'sample',
+    'first',
+    'validate',
+    'steps',
+    'revert',
+    'maxDocs',
+    'fromStart',
+    'deadlineMs',
+  ],
+  unlock: ['yes'],
+  verify: ['report'],
+  watch: ['report'],
+};
+const ALL_FLAGS = new Set(Object.values(FLAGS).flat());
+
+/** What `run --all` drives */
+const RUNNABLE = new Set(['blocked', 'pending', 'running']);
+
+/** Actions a name is required for */
+const NEEDS_NAME = new Set(['pause', 'resume', 'cancel', 'retry', 'repin', 'dry-run', 'unlock']);
+
+const flagName = (key) => `--${key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
+
+/** A positive integer flag, or undefined when not given */
+function integerFlag(opts, key, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (opts[key] === undefined) return undefined;
+  const value = Number(opts[key]);
+  if (!Number.isSafeInteger(value) || value < min || value > max) {
+    throw new ConfigInvalidError(`${flagName(key)} must be an integer from ${min} to ${max}`, {
+      [key]: opts[key],
+    });
+  }
+  return value;
+}
+
+/** Check the action, its name and its flags — before anything connects */
+function preflight(opts, [action, name]) {
+  if (!ACTIONS.has(action)) {
+    throw new ConfigInvalidError(
+      `Unknown background action "${action}" (one of: ${[...ACTIONS].join(', ')})`,
+    );
+  }
+  if (NEEDS_NAME.has(action) && name === undefined) {
+    throw new ConfigInvalidError(`background ${action} needs a migration name`);
+  }
+  if (action === 'run' && (name === undefined) === !opts.all) {
+    throw new ConfigInvalidError('background run takes a migration name, or --all');
+  }
+  if (action === 'verify' && name !== undefined) {
+    throw new ConfigInvalidError('background verify checks every background migration — no name');
+  }
+  const allowed = new Set(FLAGS[action]);
+  for (const key of ALL_FLAGS) {
+    if (opts[key] !== undefined && opts[key] !== false && !allowed.has(key)) {
+      throw new ConfigInvalidError(`${flagName(key)} does not apply to background ${action}`);
+    }
+  }
+  integerFlag(opts, 'concurrency', { max: 64 });
+  integerFlag(opts, 'sample', { max: 1000 });
+  integerFlag(opts, 'first', { max: 1000 });
+  integerFlag(opts, 'steps', { max: 50 });
+  integerFlag(opts, 'maxDocs', { max: 1000 });
+  integerFlag(opts, 'deadlineMs', { max: 50_000 });
+  return true;
+}
+
+/** The controls that cannot be taken back ask first; `--json` needs `--yes` */
+async function confirmed(action, state, { opts, json, logger }) {
+  const asks =
+    action === 'cancel' ||
+    action === 'repin' ||
+    action === 'unlock' ||
+    (action === 'retry' && opts.fromStart);
+  if (!asks || opts.yes) return true;
+  if (json) {
+    throw new ConfigInvalidError(
+      `background ${action} needs confirmation — pass --yes in --json mode`,
+    );
+  }
+  if (state) {
+    logger.warn(
+      `⚠ ${state.migration} is ${state.status} (pass ${state.pass}, ` +
+        `${state.totals.migrated ?? 0} migrated, ${state.liveLeases} lane(s) working)`,
+    );
+  }
+  const what = action === 'retry' ? 'retry from the start' : action;
+  return confirm(`${what[0].toUpperCase()}${what.slice(1)} ${state?.migration ?? 'it'}? [y/N] `);
+}
+
+/**
+ * `watch`: the live drift watcher in the foreground — every collection with a
+ * completed background migration, or the one named — until SIGINT or
+ * SIGTERM, which end it cleanly (exit 0): streams closed, positions saved,
+ * locks released. What it does is printed as it happens.
+ */
+async function watchAction(migrator, opts, collection, { logger, json }) {
+  const controller = new AbortController();
+  const onWatch = (event) => logger.info(`… ${event.collection}: ${event.state}`);
+  const onDrift = (event) => {
+    if (event.source !== 'stream') return;
+    const line = `${event.collection}: ${event.action} (${event.migration})`;
+    if (event.action === 'upgraded') logger.info(`✔ ${line}`);
+    else logger.warn(`⚠ ${line}`);
+  };
+  if (!json) {
+    migrator.on('background:watch', onWatch);
+    migrator.on('background:drift', onDrift);
+  }
+  let stop;
+  const stopped = new Promise((resolve) => {
+    stop = resolve;
+  });
+  const handlers = ['SIGINT', 'SIGTERM'].map((signal) => [
+    signal,
+    () => {
+      controller.abort();
+      stop();
+    },
+  ]);
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  try {
+    const watcher = await migrator.watchBackground({
+      ...(collection !== undefined ? { collections: [collection] } : {}),
+      ...(opts.report ? { upgrade: false } : {}),
+      signal: controller.signal,
+      onError: (error, where) =>
+        logger.warn(`⚠ Drift watcher${where ? ` (${where})` : ''}: ${errorText(error)}`),
+    });
+    if (!json) logger.info('Watching for old-shape writes — Ctrl-C to stop');
+    await stopped;
+    const rows = watcher.status();
+    await watcher.stop();
+    return { watch: rows };
+  } finally {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+    migrator.off('background:watch', onWatch);
+    migrator.off('background:drift', onDrift);
+  }
+}
+
+/** `run`: drive one background migration (or every runnable one, in order) from here */
+async function runAction(migrator, opts, name, { logger }) {
+  const concurrency = integerFlag(opts, 'concurrency', { max: 64 }) ?? 1;
+  const controller = new AbortController();
+  let stopping = false;
+  const onSignal = (signal) => {
+    if (stopping) process.exit(signal === 'SIGINT' ? 130 : 143);
+    stopping = true;
+    logger.warn(
+      `⚠ ${signal} received — the lanes stop at their next batch; the background migration ` +
+        'goes on from there next time. Press again to exit immediately.',
+    );
+    controller.abort();
+  };
+  const handlers = ['SIGINT', 'SIGTERM'].map((signal) => [signal, () => onSignal(signal)]);
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+  try {
+    const runOne = async (target) => {
+      const status = await migrator.backgroundStatus(target);
+      if (status === null) {
+        throw new ConfigInvalidError(
+          `Background migration ${target} is not registered — run up first`,
+        );
+      }
+      if (concurrency > status.maxParallel) {
+        logger.warn(
+          `⚠ --concurrency ${concurrency} is more than ${target}'s maxParallel ` +
+            `(${status.maxParallel}) — using ${status.maxParallel}`,
+        );
+      }
+      if (opts.once) {
+        const answer = await migrator.coordinateBackground(target, {
+          signal: controller.signal,
+          driver: { kind: 'cli' },
+        });
+        if (answer.next === 'busy') {
+          throw new LockAlreadyHeldError(`Another process is coordinating ${target} right now`, {
+            migration: target,
+          });
+        }
+      }
+      return migrator.runBackground(target, {
+        signal: controller.signal,
+        concurrency,
+        untilDone: !opts.once,
+      });
+    };
+    if (!opts.all) return [await runOne(name)];
+    // Round after round: one that waited for another (run later in the same
+    // round) is unblocked when that one completes, and runs in the next.
+    // Done when a round changes nothing, or after one with --once.
+    const results = new Map();
+    let previous;
+    for (;;) {
+      const runnable = [];
+      for (const state of await migrator.backgroundStatus()) {
+        if (RUNNABLE.has(state.status)) runnable.push(state.migration);
+      }
+      const key = runnable.join('\n');
+      if (runnable.length === 0 || key === previous) break;
+      previous = key;
+      for (const target of runnable) results.set(target, await runOne(target));
+      if (opts.once) break;
+    }
+    return [...results.values()];
+  } finally {
+    for (const [signal, handler] of handlers) process.off(signal, handler);
+  }
+}
+
+const STATUS_COLORS = {
+  completed: 'green',
+  running: 'cyan',
+  pending: 'yellow',
+  blocked: 'yellow',
+  paused: 'yellow',
+  failed: 'red',
+  cancelled: 'dim',
+};
+
+function renderStatuses(states) {
+  const colors = createColors(process.stdout);
+  const rows = states.map((state) => {
+    const color = colors[STATUS_COLORS[state.status]] ?? ((text) => text);
+    const parts = state.partitions;
+    return [
+      state.migration,
+      color(state.status),
+      state.collection ?? '—',
+      state.from !== undefined ? `${state.from} → ${state.to}` : 'step',
+      String(state.pass),
+      parts ? `${parts.done}/${parts.total}` : '—',
+      `${state.liveLeases}/${state.maxParallel}`,
+      String(state.totals.migrated ?? 0),
+      state.waitsFor.length > 0
+        ? `waits for ${state.waitsFor.join(', ')}`
+        : (state.lastError ?? ''),
+    ];
+  });
+  return renderTable(
+    [
+      'Background migration',
+      'Status',
+      'Collection',
+      'Versions',
+      'Pass',
+      'Partitions',
+      'Lanes',
+      'Migrated',
+      'Note',
+    ],
+    rows,
+  );
+}
+
+function renderPartitions(partitions) {
+  return renderTable(
+    ['#', 'Status', 'Scope', 'Migrated', 'Lease', 'Claims', 'Error'],
+    partitions.map((partition) => [
+      String(partition.seq),
+      partition.status,
+      partition.scope.kind === 'step'
+        ? 'step'
+        : `${partition.scope.bracket ?? ''}${partition.group ? ` @${partition.group}` : ''}`,
+      String(partition.counters.migrated ?? 0),
+      partition.lease
+        ? `slot ${partition.lease.slot} · ${partition.lease.host}:${partition.lease.pid}`
+        : '',
+      String(partition.claims),
+      partition.lastError ?? '',
+    ]),
+  );
+}
+
+/** Register the `background` command */
+function registerBackground(program) {
+  defineCommand(program, {
+    name: 'background',
+    description:
+      'Background migrations: status, run, pause, resume, cancel, retry, repin, dry-run, unlock, ' +
+      'verify, watch',
+    args: [
+      [
+        '<action>',
+        'status | run | pause | resume | cancel | retry | repin | dry-run | unlock | verify | watch',
+      ],
+      ['[name]', 'The background migration (its file name) — watch: a collection'],
+    ],
+    options: [
+      ['--partitions', 'status: list the partitions of the latest generation'],
+      [
+        '--check',
+        `status: exit ${EXIT_CODES.BACKGROUND_FAILED} if one failed, ${EXIT_CODES.BACKGROUND_PENDING} if one is not completed`,
+      ],
+      ['--all', 'run: every runnable background migration, in order'],
+      ['--concurrency <n>', 'run: lanes in this process (at most its maxParallel; default 1)'],
+      ['--once', 'run: one round, not to the end'],
+      ['--wait', 'pause, cancel: wait until no lane works any more'],
+      ['--from-start', 'retry: plan everything again; dry-run: from no checkpoint'],
+      ['--repin', 'retry: pin the file on disk first'],
+      ['--sample <n>', 'dry-run: a random sample of n documents (default 5)'],
+      ['--first <n>', 'dry-run: the first n documents by _id'],
+      ['--validate', 'dry-run: through the real write path, in an always-aborted transaction'],
+      ['--steps <k>', 'dry-run: run k steps of a step migration (default 1)'],
+      ['--revert', 'dry-run: the way back'],
+      ['--max-docs <n>', 'dry-run: document images to keep (default 20)'],
+      ['--deadline-ms <ms>', 'dry-run: stop the sandbox after this long (default 50000)'],
+      ['--report', 'verify: only report drift, never reopen; watch: never upgrade'],
+      ['--reason <text>', 'controls: why — recorded in its history'],
+      ['-y, --yes', 'cancel, retry --from-start, repin, unlock: do not ask (required with --json)'],
+    ],
+    spinner: false,
+    preflight: (opts, positionals) => preflight(opts, positionals),
+    run: async (migrator, opts, [action, name], cli) => {
+      const control = {
+        ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+        ...(opts.wait ? { wait: true } : {}),
+      };
+      switch (action) {
+        case 'status': {
+          if (opts.partitions) {
+            if (name === undefined) {
+              throw new ConfigInvalidError('background status --partitions needs a name');
+            }
+            return { partitions: await migrator.backgroundPartitions(name) };
+          }
+          if (name !== undefined) {
+            const one = await migrator.backgroundStatus(name);
+            if (one === null) {
+              throw new ConfigInvalidError(`Background migration ${name} is not registered`);
+            }
+            return { background: [one] };
+          }
+          return { background: await migrator.backgroundStatus() };
+        }
+        case 'run':
+          return { background: await runAction(migrator, opts, name, cli) };
+        case 'pause':
+          return migrator.pauseBackground(name, control);
+        case 'resume':
+          return migrator.resumeBackground(name, control);
+        case 'cancel':
+        case 'repin':
+        case 'retry':
+        case 'unlock': {
+          const state = await migrator.backgroundStatus(name);
+          if (!(await confirmed(action, state, { ...cli, opts }))) {
+            cli.logger.info('Aborted');
+            return undefined;
+          }
+          if (action === 'cancel') return migrator.cancelBackground(name, control);
+          if (action === 'repin') return migrator.repinBackground(name, control);
+          if (action === 'unlock') return migrator.unlockBackground(name);
+          return migrator.retryBackground(name, {
+            ...control,
+            ...(opts.fromStart ? { fromStart: true } : {}),
+            ...(opts.repin ? { repin: true } : {}),
+          });
+        }
+        case 'dry-run':
+          return {
+            dryRun: await migrator.dryRunBackground(name, {
+              ...(opts.sample !== undefined ? { sample: Number(opts.sample) } : {}),
+              ...(opts.first !== undefined ? { first: Number(opts.first) } : {}),
+              ...(opts.validate ? { validate: true } : {}),
+              ...(opts.steps !== undefined ? { steps: Number(opts.steps) } : {}),
+              ...(opts.revert ? { direction: 'revert' } : {}),
+              ...(opts.maxDocs !== undefined ? { maxDocuments: Number(opts.maxDocs) } : {}),
+              ...(opts.fromStart ? { fromStart: true } : {}),
+              ...(opts.deadlineMs !== undefined ? { deadlineMs: Number(opts.deadlineMs) } : {}),
+            }),
+          };
+        case 'watch':
+          return watchAction(migrator, opts, name, cli);
+        default:
+          return {
+            verify: await migrator.verifyBackground(opts.report ? { onDrift: 'report' } : {}),
+          };
+      }
+    },
+    render: (data, { logger }) => {
+      if (data.partitions) {
+        logger.info(renderPartitions(data.partitions));
+      } else if (data.background) {
+        if (data.background.length === 0) logger.info('No background migrations registered');
+        else logger.info(renderStatuses(data.background));
+      } else if (data.dryRun) {
+        renderDryRun(data.dryRun, logger);
+      } else if (data.verify) {
+        const { checked, skipped, drift } = data.verify;
+        if (drift.length === 0) {
+          logger.info(`✔ No drift (${checked} checked, ${skipped} skipped)`);
+        }
+        for (const entry of drift) {
+          logger.warn(
+            `⚠ ${entry.collection}: old-shape documents after ${entry.migration} — ${entry.action}`,
+          );
+        }
+      } else if (data.watch) {
+        let upgraded = 0;
+        for (const row of data.watch) upgraded += row.counters.upgraded;
+        logger.info(`✔ Stopped watching — ${upgraded} document(s) upgraded`);
+      } else if (data.applied !== undefined) {
+        logger.info(`✔ ${data.applied === 'changed' ? 'Done' : 'Nothing to do'} — ${data.status}`);
+      } else if (data.leases !== undefined) {
+        logger.info(
+          `✔ Released the coordinator lock${data.lock ? '' : ' (none held)'} and ${data.leases} lease(s)`,
+        );
+      }
+    },
+    after: (data, { opts, logger }) => {
+      if (data === undefined) return;
+      const states = data.background;
+      if (opts.check && Array.isArray(states)) {
+        if (states.some((state) => state.status === 'failed')) {
+          logger.error('✖ A background migration failed');
+          process.exitCode = EXIT_CODES.BACKGROUND_FAILED;
+        } else if (states.some((state) => state.status !== 'completed')) {
+          logger.error('✖ Background migrations are not all completed');
+          process.exitCode = EXIT_CODES.BACKGROUND_PENDING;
+        }
+      }
+      if (data.verify?.drift.length > 0) process.exitCode = EXIT_CODES.BACKGROUND_PENDING;
+      const dry = data.dryRun;
+      if (dry !== undefined) {
+        if (dry.mode === 'step') {
+          if (dry.refusals.length > 0) process.exitCode = EXIT_CODES.SANDBOX_REFUSED;
+          else if (!dry.ok) process.exitCode = 1;
+        } else if (dry.refusals?.length > 0) {
+          process.exitCode = EXIT_CODES.SANDBOX_REFUSED;
+        } else if (dry.migrated === 0) {
+          process.exitCode = 1;
+        }
+      }
+    },
+  });
+}
+
+/** A dry run, for people: one line per document or step, then what the sandbox saw */
+function renderDryRun(dry, logger) {
+  if (dry.mode === 'step') {
+    for (const step of dry.steps) {
+      logger.info(
+        `◎ Step ${step.step}: ${JSON.stringify(step.checkpointIn)} → ` +
+          `${step.error ? `✖ ${step.error}` : JSON.stringify(step.checkpointOut)}${step.done ? ' (done)' : ''}`,
+      );
+    }
+  } else {
+    for (const row of dry.documents) {
+      const id = JSON.stringify(row._id);
+      if (row.error) logger.warn(`✖ ${id}: ${row.error}`);
+      else logger.info(`✔ ${id}: ${JSON.stringify(row.change ?? row.after)}`);
+    }
+    logger.info(`◎ ${dry.migrated} of ${dry.found} would be migrated, ${dry.failed} would fail`);
+  }
+  for (const refusal of dry.refusals ?? []) {
+    logger.error(`✖ Refused ${refusal.method}: ${refusal.reason}`);
+  }
+  if (dry.ops) logger.info(`◎ ${dry.ops.length} operation(s), all rolled back`);
+  if (dry.stoppedBy === 'deadline') logger.warn('⚠ Stopped at the deadline');
+}
+
+module.exports = { registerBackground };

package/src/cli/commands/converge.js

@@ -1,11 +1,13 @@
 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, or a validator change on a collection that holds data.
+ * rebuilt index, a dropped search index, or a validator change on a
+ * collection that holds data.
  */
 function actionsToConfirm(plan) {
   const found = [];
@@ -36,14 +38,18 @@ function assertNotStopped(stopRequested) {
 function registerConverge(program) {
   defineCommand(program, {
     name: 'converge',
-    description: 'Bring declared collections (indexes, validators) to their declared state',
+    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 (in collections whose definition does not decide)'],
+      [
+        '--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)'],
@@ -52,6 +58,11 @@ function registerConverge(program) {
         '--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)',
@@ -64,6 +75,13 @@ function registerConverge(program) {
     // 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) } : {},
@@ -98,16 +116,13 @@ function registerConverge(program) {
           // applies without one.
           if (json) {
             throw new ConfigInvalidError(
-              `converge would drop or rebuild an index, or change a validator ` +
+              `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));
-          const uniqueRebuilds = destructive.filter(
-            (action) => action.action === 'recreate' && opts.rebuildUnique,
-          );
-          if (uniqueRebuilds.length > 0) {
+          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',
@@ -127,6 +142,7 @@ function registerConverge(program) {
           noLock: opts.noLock,
           ...prune,
           ...ordered,
+          ...(waitSearch !== undefined ? { waitForSearchIndexes: waitSearch } : {}),
           ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
         });
       } finally {
@@ -147,9 +163,21 @@ function registerConverge(program) {
       logger.info(renderConvergeTable(result, { all: Boolean(opts.verbose) }));
     },
     after: (result, { logger, opts }) => {
-      if (!opts.check || result === undefined || result.inSync) return;
+      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.
-      logger.error('✖ The database differs from the declared collections');
+      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;

package/src/cli/commands/create.js

@@ -1,3 +1,4 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
 const { defineCommand } = require('../shared.js');
 
 /** Register the `create` command */
@@ -10,15 +11,20 @@ function registerCreate(program) {
       ['--js', 'Force a .js file (overrides config createExtension)'],
       ['--ts', 'Force a .ts file (overrides config createExtension)'],
       ['--template <path>', 'Use a custom template file'],
+      ['--background', 'Create a background migration (export const background)'],
     ],
     // Writing a file needs no database — no spinner, no pre-connect.
     spinner: false,
     run: async (migrator, opts, [name]) => {
       // Tri-state: explicit flag wins; otherwise leave undefined so config decides.
       const js = opts.ts ? false : opts.js ? true : undefined;
+      if (opts.background && opts.template) {
+        throw new ConfigInvalidError('--background and --template cannot be combined');
+      }
       const path = await migrator.create(name, {
         ...(js !== undefined ? { js } : {}),
         ...(opts.template ? { template: opts.template } : {}),
+        ...(opts.background ? { background: true } : {}),
       });
       return { path };
     },

package/src/cli/exit-codes.js

@@ -41,6 +41,12 @@ const EXIT_CODES = {
   QUEUE_JOB_FAILED: 26,
   CONVERGE_FAILED: 27,
   COLLECTIONS_DRIFT: 28,
+  REVISION_CONFLICT: 29,
+  SHAPE_VERSION_UNSUPPORTED: 30,
+  BACKGROUND_PENDING: 31,
+  BACKGROUND_FAILED: 32,
+  BACKGROUND_CONFLICT: 33,
+  SANDBOX_REFUSED: 34,
 };
 
 module.exports = { EXIT_CODES };

package/src/cli/index.js

@@ -1,5 +1,6 @@
 const { Command } = require('./args.js');
 const { registerAudit } = require('./commands/audit.js');
+const { registerBackground } = require('./commands/background.js');
 const { registerBaseline } = require('./commands/baseline.js');
 const { registerConverge } = require('./commands/converge.js');
 const { registerCreate } = require('./commands/create.js');
@@ -44,6 +45,7 @@ function buildProgram() {
   registerDown(program);
   registerRedo(program);
   registerConverge(program);
+  registerBackground(program);
   registerStatus(program);
   registerList(program);
   registerDryRun(program);