@alexify/migronaut 1.0.0

package/src/cli/commands/import.js

@@ -0,0 +1,33 @@
+const { defineCommand } = require('../shared.js');
+const { renderImportTable } = require('../table.js');
+
+/** Register the `import` command (adopt a migrate-mongo changelog) */
+function registerImport(program) {
+  defineCommand(program, {
+    name: 'import',
+    description: 'Adopt an existing migrate-mongo changelog into the migronaut changelog',
+    options: [
+      ['--from <collection>', 'Source collection to read (default: changelog)'],
+      ['--to <collection>', 'Target collection to write (default: config migrationsCollection)'],
+      ['--dry-run', 'Preview the mapping without writing anything'],
+      ['--trust-hash', 'Reuse the source fileHash instead of recomputing from disk'],
+      ['--force', 'Proceed even when the target changelog already has records'],
+    ],
+    lockable: true,
+    mutating: true,
+    run: (migrator, opts) =>
+      migrator.import({
+        noLock: opts.noLock,
+        ...(opts.from ? { from: opts.from } : {}),
+        ...(opts.to ? { to: opts.to } : {}),
+        ...(opts.dryRun ? { dryRun: true } : {}),
+        ...(opts.trustHash ? { trustHash: true } : {}),
+        ...(opts.force ? { force: true } : {}),
+      }),
+    render: (result, { logger }) => {
+      if (result.rows.length > 0) logger.info(renderImportTable(result.rows));
+    },
+  });
+}
+
+module.exports = { registerImport };

package/src/cli/commands/init.js

@@ -0,0 +1,64 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
+const { defineCommand } = require('../shared.js');
+
+const FORMATS = new Set(['js', 'ts', 'json']);
+
+/** Register the `init` command */
+function registerInit(program) {
+  defineCommand(program, {
+    name: 'init',
+    description:
+      'Create a migronaut config file in the current directory (migronaut.config.js by default)',
+    options: [
+      ['--format <type>', "Config file format: 'js' (default), 'ts' or 'json'"],
+      ['--ts', 'Shorthand for --format ts'],
+      ['--js', 'Shorthand for --format js'],
+      [
+        '--secret-provider',
+        'Generate a config that loads the connection from a secret manager (js/ts only)',
+      ],
+      ['--force', 'Overwrite an existing config file'],
+    ],
+    // init has no machine-readable output; the deliverable is the file itself.
+    jsonOutput: false,
+    // Writing a file needs no database — no spinner, no pre-connect.
+    spinner: false,
+    preflight: (opts) => {
+      // `--json` used to mean "generate migronaut.config.json" here — the one
+      // command where it did not mean JSON output. Refuse loudly rather than
+      // silently reinterpreting a global output flag as a file format.
+      if (opts.json) {
+        throw new ConfigInvalidError(
+          'init has no JSON output — to generate migronaut.config.json, pass --format json',
+        );
+      }
+      if (opts.format !== undefined && !FORMATS.has(opts.format)) {
+        throw new ConfigInvalidError("--format must be 'js', 'ts' or 'json'", {
+          format: opts.format,
+        });
+      }
+      const format = resolveFormat(opts);
+      if (opts.secretProvider && format === 'json') {
+        throw new ConfigInvalidError(
+          '--secret-provider is only available for js/ts configs (not --format json)',
+        );
+      }
+    },
+    run: async (migrator, opts) => {
+      await migrator.init({
+        format: resolveFormat(opts),
+        force: opts.force ?? false,
+        ...(opts.secretProvider ? { secretProvider: true } : {}),
+      });
+    },
+  });
+}
+
+/** Explicit --format wins; --ts/--js are shorthands; the default is js */
+function resolveFormat(opts) {
+  if (opts.format !== undefined) return opts.format;
+  if (opts.ts) return 'ts';
+  return 'js';
+}
+
+module.exports = { registerInit };

package/src/cli/commands/list.js

@@ -0,0 +1,19 @@
+const { defineCommand } = require('../shared.js');
+const { renderRowsOrEmpty } = require('../table.js');
+
+/** Register the `list` command */
+function registerList(program) {
+  defineCommand(program, {
+    name: 'list',
+    description: 'List migrations, optionally filtered by status',
+    options: [
+      ['--pending', 'Show only pending migrations'],
+      ['--applied', 'Show only applied migrations'],
+    ],
+    run: (migrator, opts) =>
+      migrator.list(opts.pending ? 'pending' : opts.applied ? 'applied' : 'all'),
+    render: renderRowsOrEmpty,
+  });
+}
+
+module.exports = { registerList };

package/src/cli/commands/lock.js

@@ -0,0 +1,35 @@
+const { defineCommand } = require('../shared.js');
+
+/**
+ * `lockedAt` as an ISO string, tolerating a lock document whose field is not a
+ * Date (hand-edited, half-written, or from another tool). This command exists
+ * to diagnose a stuck lock — crashing on the document it came to inspect
+ * would fail at exactly the moment it is most needed.
+ */
+function lockedAtText(value) {
+  return value instanceof Date ? value.toISOString() : String(value);
+}
+
+/** Register the `lock` command (inspect the migration lock without touching it) */
+function registerLock(program) {
+  defineCommand(program, {
+    name: 'lock',
+    description: 'Show who holds the migration lock, if anyone',
+    run: async (migrator) => {
+      const holder = await migrator.lockInfo();
+      return { held: holder !== null, holder };
+    },
+    render: ({ holder }, { logger }) => {
+      if (!holder) {
+        logger.info('No migration lock is currently held');
+        return;
+      }
+      logger.info(
+        `Lock held by pid ${holder.pid} on ${holder.host} (${holder.executedBy}) ` +
+          `since ${lockedAtText(holder.lockedAt)}`,
+      );
+    },
+  });
+}
+
+module.exports = { registerLock, lockedAtText };

package/src/cli/commands/redo.js

@@ -0,0 +1,16 @@
+const { defineCommand } = require('../shared.js');
+
+/** Register the `redo` command */
+function registerRedo(program) {
+  defineCommand(program, {
+    name: 'redo',
+    description: 'Rollback then re-apply the last applied migration, or a specific file',
+    args: [['[file]', 'Specific migration file to redo']],
+    lockable: true,
+    mutating: true,
+    run: (migrator, opts, [file]) => migrator.redo(file, { noLock: opts.noLock }),
+    // No render: core logs the ↩/✔ lines itself.
+  });
+}
+
+module.exports = { registerRedo };

package/src/cli/commands/status.js

@@ -0,0 +1,52 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
+const { defineCommand, EXIT_CODES } = require('../shared.js');
+const { renderRowsOrEmpty } = require('../table.js');
+
+/** Register the `status` command */
+function registerStatus(program) {
+  defineCommand(program, {
+    name: 'status',
+    description: 'Show the full migration status table',
+    options: [
+      ['--check', 'Exit with code 2 if any migrations are pending (CI gate)'],
+      ['--pending', 'Show only pending migrations'],
+      ['--limit <n>', 'Show only the last N rows'],
+    ],
+    preflight: (opts) => {
+      if (opts.limit !== undefined) {
+        const limit = Number(opts.limit);
+        if (!Number.isInteger(limit) || limit < 1) {
+          throw new ConfigInvalidError('--limit must be a positive integer', {
+            limit: opts.limit,
+          });
+        }
+        // --check answers "is ANY migration pending?" — a limited window could
+        // hide pending rows and report a clean gate that is not.
+        if (opts.check) {
+          throw new ConfigInvalidError('--check cannot be combined with --limit');
+        }
+      }
+    },
+    run: async (migrator, opts) => {
+      const rows = opts.pending ? await migrator.list('pending') : await migrator.status();
+      return opts.limit !== undefined ? rows.slice(-Number(opts.limit)) : rows;
+    },
+    render: renderRowsOrEmpty,
+    after: (rows, { logger, opts }) => {
+      if (!opts.check) return;
+      let pending = 0;
+      for (const row of rows) {
+        if (row.status === 'pending') pending += 1;
+      }
+      if (pending > 0) {
+        // .error writes to stderr, so JSON stdout stays a single clean document.
+        logger.error(`✖ ${pending} pending migration(s)`);
+        // A dedicated code: a CI gate must be able to tell "database is
+        // behind" (act: migrate) from "the check itself crashed" (act: page).
+        process.exitCode = EXIT_CODES.PENDING_MIGRATIONS;
+      }
+    },
+  });
+}
+
+module.exports = { registerStatus };

package/src/cli/commands/unlock.js

@@ -0,0 +1,43 @@
+const { confirm, defineCommand, emitJson } = require('../shared.js');
+const { lockedAtText } = require('./lock.js');
+
+/** Register the `unlock` command (force-release a stuck migration lock) */
+function registerUnlock(program) {
+  defineCommand(program, {
+    name: 'unlock',
+    description: 'Force-release a stuck migration lock left behind by a crashed run',
+    options: [['-y, --yes', 'Skip the confirmation prompt']],
+    mutating: true,
+    // Owns its output: the confirmation flow branches mid-way, so the shared
+    // "emit what run() returned" envelope does not fit.
+    run: async (migrator, opts, _positionals, { logger, json }) => {
+      const holder = await migrator.lockInfo();
+
+      if (!holder) {
+        if (json) emitJson({ released: false, holder: null });
+        else logger.info('No migration lock is currently held');
+        return undefined;
+      }
+
+      // Confirm before clearing — unless --yes, or --json (non-interactive).
+      if (!json && !opts.yes) {
+        const since = lockedAtText(holder.lockedAt);
+        logger.warn(
+          `⚠ Lock held by pid ${holder.pid} on ${holder.host} (${holder.executedBy}) since ${since}`,
+        );
+        const proceed = await confirm('Force-release this lock? [y/N] ');
+        if (!proceed) {
+          logger.info('Aborted');
+          return undefined;
+        }
+      }
+
+      const released = await migrator.forceUnlock();
+      if (json) emitJson({ released: released !== null, holder: released });
+      else logger.info('✔ Lock released');
+      return undefined;
+    },
+  });
+}
+
+module.exports = { registerUnlock };

package/src/cli/commands/up.js

@@ -0,0 +1,53 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
+const { confirm, defineCommand } = require('../shared.js');
+
+/** Register the `up` command */
+function registerUp(program) {
+  defineCommand(program, {
+    name: 'up',
+    description: 'Run all pending migrations, or a single named file',
+    args: [['[file]', 'Specific migration file to run']],
+    options: [
+      ['--to <file>', 'Apply pending migrations up to and including this file'],
+      ['--strict', 'Abort on checksum mismatch'],
+      ['-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)'],
+    ],
+    lockable: true,
+    mutating: true,
+    // Runs before any connection: validation and the confirmation prompt must
+    // not cost a round trip, and their errors use the same typed envelope as
+    // everything else (CONFIG_INVALID, exit 6).
+    preflight: async (opts, [file], { logger }) => {
+      if (opts.force && !file) {
+        throw new ConfigInvalidError('--force requires a specific migration file');
+      }
+      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.
+        if (opts.json) {
+          throw new ConfigInvalidError(
+            '--force needs confirmation — pass --yes to confirm in --json mode',
+          );
+        }
+        const proceed = await confirm(`are you sure you want to re-run "${file}"? [y/N] `);
+        if (!proceed) {
+          logger.info('Aborted');
+          return false;
+        }
+      }
+      return undefined;
+    },
+    run: (migrator, opts, [file]) =>
+      migrator.up(file, {
+        noLock: opts.noLock,
+        ...(opts.force ? { force: true } : {}),
+        ...(opts.step ? { step: true } : {}),
+        ...(opts.to ? { to: opts.to } : {}),
+      }),
+    // No render: core logs every ✔ Applied line itself.
+  });
+}
+
+module.exports = { registerUp };

package/src/cli/exit-codes.js

@@ -0,0 +1,38 @@
+/**
+ * Exit code per error code, so CI can branch on *why* a run failed instead of
+ * only that it did. Anything unmapped exits 1, and success is still 0 — a
+ * 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).
+ *
+ * Exported from the package root so a programmatic wrapper can mirror the
+ * CLI's exit semantics without hardcoding numbers from the docs table. Kept
+ * in its own module so importing the library never loads the CLI machinery.
+ */
+const EXIT_CODES = {
+  PENDING_MIGRATIONS: 2,
+  LOCK_ALREADY_HELD: 3,
+  CHECKSUM_MISMATCH: 4,
+  CONNECTION_FAILED: 5,
+  CONFIG_INVALID: 6,
+  MIGRATION_EXECUTION_FAILED: 7,
+  MIGRATION_FILE_NOT_FOUND: 8,
+  NOT_APPLIED: 9,
+  LOCK_LOST: 10,
+  RUN_ABORTED: 11,
+  HOOK_FAILED: 12,
+  MIGRATION_IRREVERSIBLE: 13,
+  MIGRATION_TIMEOUT: 14,
+  TRANSACTIONS_UNSUPPORTED: 15,
+  CONFIG_FILE_EXISTS: 16,
+  IMPORT_TARGET_NOT_EMPTY: 17,
+  MIGRATION_FILE_EXISTS: 18,
+  MIGRATION_INVALID_NAME: 19,
+  MIGRATION_INVALID_EXPORT: 20,
+  LOCK_RELEASE_FAILED: 21,
+  AUDIT_FAILED: 22,
+};
+
+module.exports = { EXIT_CODES };

package/src/cli/index.js

@@ -0,0 +1,91 @@
+const { Command } = require('./args.js');
+const { registerAudit } = require('./commands/audit.js');
+const { registerCreate } = require('./commands/create.js');
+const { registerDown } = require('./commands/down.js');
+const { registerDryRun } = require('./commands/dry-run.js');
+const { registerImport } = require('./commands/import.js');
+const { registerInit } = require('./commands/init.js');
+const { registerList } = require('./commands/list.js');
+const { registerLock } = require('./commands/lock.js');
+const { registerRedo } = require('./commands/redo.js');
+const { registerStatus } = require('./commands/status.js');
+const { registerUnlock } = require('./commands/unlock.js');
+const { registerUp } = require('./commands/up.js');
+
+/** Build the root commander program with all commands and global flags */
+function buildProgram() {
+  const program = new Command();
+
+  program
+    .name('migronaut')
+    .description('Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js')
+    .option('--uri <uri>', 'MongoDB connection URI (overrides MIGRONAUT_URI)')
+    .option('--db <name>', 'Database name (overrides MIGRONAUT_DB)')
+    .option('--dir <path>', 'Migrations directory (overrides MIGRONAUT_MIGRATIONS_DIR)')
+    .option('--config <path>', 'Path to a config file (overrides auto-discovery)')
+    .option('--env-file <path>', 'Path to the .env file to load (default: ./.env)')
+    .option('--no-env', 'Do not load a .env file at all')
+    .option('--verbose', 'Show debug output, including error causes')
+    .option('--quiet', 'Suppress everything but errors')
+    .option('--no-color', 'Disable colored output')
+    // Global like --verbose/--quiet: `migronaut --json status` and
+    // `migronaut status --json` must both work. `init` has no JSON output and
+    // rejects the flag with a pointer to `--format json`.
+    .option('--json', 'Output machine-readable JSON instead of human text')
+    // Read straight from package.json at runtime — no build-time injection needed.
+    .version(require('../../package.json').version);
+
+  registerInit(program);
+  registerImport(program);
+  registerUp(program);
+  registerDown(program);
+  registerRedo(program);
+  registerStatus(program);
+  registerList(program);
+  registerDryRun(program);
+  registerCreate(program);
+  registerLock(program);
+  registerAudit(program);
+  registerUnlock(program);
+
+  return program;
+}
+
+/** Parse argv and execute the matching command */
+async function run(argv) {
+  // Checked before parsing: color is decided the first time anything renders,
+  // which can precede the command action that would otherwise read the flag.
+  // Tokens after a `--` terminator are positionals, never flags.
+  const boundary = argv.indexOf('--');
+  const flagTokens = boundary === -1 ? argv : argv.slice(0, boundary);
+  const noColor = flagTokens.includes('--no-color');
+  const saved = noColor
+    ? {
+        MIGRONAUT_FORCE_COLOR: process.env.MIGRONAUT_FORCE_COLOR,
+        MIGRONAUT_NO_COLOR: process.env.MIGRONAUT_NO_COLOR,
+      }
+    : undefined;
+  if (noColor) {
+    // An explicit flag on this invocation outranks every ambient signal.
+    // MIGRONAUT_NO_COLOR is the top of supportsColor()'s precedence chain once
+    // MIGRONAUT_FORCE_COLOR is cleared, so setting these two is enough to beat
+    // an exported FORCE_COLOR (CI runners and many local shells set it) without
+    // touching the shared FORCE_COLOR/NO_COLOR other tools read.
+    delete process.env.MIGRONAUT_FORCE_COLOR;
+    process.env.MIGRONAUT_NO_COLOR = '1';
+  }
+  try {
+    await buildProgram().parseAsync(argv);
+  } finally {
+    // A programmatic embedder calling run() twice must not inherit this
+    // invocation's flag as ambient state.
+    if (saved) {
+      for (const key of Object.keys(saved)) {
+        if (saved[key] === undefined) delete process.env[key];
+        else process.env[key] = saved[key];
+      }
+    }
+  }
+}
+
+module.exports = { run };