@alexify/migronaut 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,8 +1,96 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+Release headings carry the publish date (`## vX.Y.Z — YYYY-MM-DD`).
 
-## v1.0.0
+## v2.0.0 — 2026-08-30
+
+A major bump for three narrow contract changes (below); everything else is
+additive. Upgrading is a no-op for the most commonly scripted surface:
+`pendingMigrations()` / `list('pending')` still report a file as `pending`
+even when a failed attempt was recorded for it.
+
+### Breaking changes
+
+- **`unlock --json` now requires `--yes`.** Previously `--json` alone
+  force-released the lock; it now refuses with `CONFIG_INVALID` (exit 6), because
+  a non-interactive mode must never assume consent to a destructive action —
+  force-releasing a live run's lock enables exactly the concurrent migration the
+  lock exists to prevent. **Migration:** add `--yes` to any scripted
+  `migronaut unlock --json`.
+- **`StatusRow.status` and `MigrationStatus` gained `'failed'`.** A recorded
+  failed attempt now renders as `failed` in `status()` / `list('all')` instead of
+  `pending`. **Migration:** TypeScript consumers with an exhaustive `switch` over
+  the status must handle the new member; treat `'failed'` as outstanding work.
+- **`MigronautErrorCode` gained `'MIGRATION_OUT_OF_ORDER'`** (and `EXIT_CODES`
+  the matching key, exit 23). **Migration:** exhaustive `switch` statements over
+  the code union must handle it.
+
+### Added
+
+- **`migronaut baseline`** — adopt an existing database with no prior migration tool: mark
+  migration files on disk as applied (checksum from disk, one shared batch, `origin: 'baseline'`)
+  without executing them. Forward-only, idempotent, confirmation-gated.
+- **Out-of-order detection** — a bulk `up` flags pending migrations that sort before the newest
+  applied one (a file merged late from a parallel branch). New scalar config `onOutOfOrder:
+  'warn' | 'error' | 'allow'` (default `'warn'`, env `MIGRONAUT_ON_OUT_OF_ORDER`), a new
+  `MIGRATION_OUT_OF_ORDER` error code (exit 23), `outOfOrder` on `StatusRow`, and an `ordering`
+  check in `audit`.
+- **Failed-attempt traces** — a failing `up` now leaves a best-effort `status: 'failed'` record
+  (error text, `failedAt`, `runId`) in the changelog; `status` renders it as `failed` while every
+  run path still retries the file; a successful apply clears the trace. A forced re-run's failure
+  never demotes an `applied` record.
+- **Audit-trail read surface** — `StatusRow` now carries `executedBy`, `environment`, `runId`,
+  `revertedAt` and `origin` from the changelog record, so `status --json` can answer "who ran
+  migration X, from which run, and was it ever reverted?".
+- **`onKit` option on `runMigrations`** — receive the internally-constructed `MigratorKit` before
+  connect and subscribe to its lifecycle events (metrics without log parsing).
+- **`createLogger` export** — the default console logger (with level control) for programmatic
+  callers.
+- **`cwd` option on `MigratorKit`** — scope config discovery, `.env` loading and a relative
+  `migrationsDir` to a project root, for processes hosting kits for several projects.
+- **ESM-interop integration test** pinning the "ESM consumers still work" promise.
+
+### Changed
+
+- **Server-time changelog stamps** — `appliedAt`/`revertedAt`/`failedAt` are stamped with the
+  server clock (`$currentDate`, matching the lock's `$$NOW` discipline) unless the record carries
+  an explicit `appliedAt` (import), so `redo`/`down --steps` ordering is immune to host clock skew.
+- **Non-transactional changelog-write failures are reported distinctly** — when a migration's own
+  writes committed but recording them failed, the error now says exactly that (context
+  `phase: 'changelog-write'`, `bodySucceeded: true`) instead of the generic "migration failed"
+  that invited re-running committed writes.
+- **A timed-out migration is told to stop** — `timeoutMs` now aborts `ctx.signal` (with the
+  `MigrationTimeoutError` as reason), so cooperative bodies stop writing instead of racing the
+  next lock holder.
+- **`lockWaitTimeoutMs` bounds stall, not total wait** — while a waiting `runMigrations` observes
+  the holder's heartbeat advancing, the deadline re-arms; only a stalled holder times peers out.
+- **`baseline` requires `--yes` in `--json` mode** — the same non-interactive
+  confirmation policy `up --force --json` and `unlock --json` follow.
+- **Failure telemetry carries timing** — `migration:error` events, error result rows and error
+  contexts now include `durationMs`/`batch`; the run ends with a `✔ Done N applied in Xms`
+  summary line.
+- Signals during the CLI's pre-connect now abort the run (exit 11) instead of being silently
+  dropped; partial-results lists survive hook/load failures and lock-release failures; lock
+  warn lines carry `runId`; import interruptions report progress and that a `--force` re-run
+  resumes idempotently.
+
+### Fixed / hardened
+
+- URI redaction now masks query-string secrets (`tlsCertificateKeyFilePassword`, `proxyPassword`,
+  `sslKeyPassword`, secret `authMechanismProperties` values) and empty-username passwords —
+  in logs, errors, `--json`, events, and `init`-generated config files (which now warn about
+  query-string secrets too).
+- Terminal sanitization strips the whole C1 control block (DCS/OSC/PM/APC, not just CSI), and
+  `bin/migronaut.js`'s last-resort handlers sanitize their output.
+- `MigrationLock.release()` without a held owner token is a no-op instead of an unscoped delete;
+  an uncontended `acquire()` takes one round trip instead of two.
+- Import checksum resolution is concurrency-bounded (no EMFILE on thousands-record changelogs);
+  the strict drift check reuses the instance checksum cache; `dry-run up` fetches applied names
+  instead of full records; a warn/error-only injected logger keeps its output instead of being
+  silenced entirely.
+
+## v1.0.0 — 2026-07-28
 
 Initial release. Requires **Node.js ≥ 22.18**.
 

package/README.md

@@ -23,6 +23,22 @@ change before it touches your database.
 
 </div>
 
+> [!TIP]
+> ### 🔄 Already using `migrate-mongo`? Switch in under a minute.
+>
+> `migronaut` adopts your existing `changelog` **as-is** — no re-running migrations, no data loss, no rewriting
+> files. Point it at the same database and bring your whole history over in one command:
+>
+> ```bash
+> migronaut import     # one-time: adopt your migrate-mongo changelog (it's never modified)
+> migronaut up         # applies only what's new — your past migrations are recognized as already applied
+> ```
+>
+> Your applied history is preserved and new migrations run normally. Your `up`/`down`/`create`/`status`
+> mental model carries over 1:1 — you just gain dry-runs, single-file control, real rollbacks, hooks,
+> and locking. No `migrate-mongo` history at all? `migronaut baseline` adopts an existing database
+> with no prior tool. → **[See how it works](#advanced-features)**
+
 ---
 
 ## Reasons to choose it
@@ -35,6 +51,10 @@ change before it touches your database.
 - **No race conditions** — an atomic MongoDB lock stops two deploys running migrations at once.
 - **Tamper detection** — SHA-256 checksums catch a migration edited after it was applied.
 - **Audit trail kept** — a rollback updates the record, it never deletes it.
+- **Adopt any existing database** — `migronaut import` for a migrate-mongo history,
+  `migronaut baseline` when there was no migration tool at all.
+- **Out-of-order detection** — a migration merged late from a parallel branch is flagged
+  (warn by default, `onOutOfOrder: 'error'` to refuse) instead of silently applying.
 - **Lifecycle hooks** — `beforeAll`, `afterAll`, `beforeEach`, `afterEach`, `onError`.
 - **Opt-in transactions** — wrap a migration so it fully commits or fully aborts.
 - **TypeScript, ESM & CommonJS** — all run with no `ts-node` plumbing.
@@ -51,13 +71,15 @@ change before it touches your database.
 | Roll back a specific batch (not just the last)  |        ❌        |          ✅          |
 | Dry-run preview                                 |        ❌        |          ✅          |
 | `redo` (down + up)                              |        ❌        |          ✅          |
-| SHA-256 checksum / tamper detection             |        ❌        |          ✅          |
+| Concurrency lock                                | opt-in, TTL-only | ✅ always on: heartbeat, owner token, abort-on-loss, `lock`/`unlock` CLI |
+| Checksum / tamper detection                     | opt-in `useFileHash` (re-runs changed files) | ✅ enforced drift detection: per-row `checksumOk`, `--strict`, `audit` |
 | Lifecycle hooks                                 |        ❌        |          ✅          |
 | First-class TypeScript (built-in)               |        ❌        |          ✅          |
 | History preserved on rollback (never deleted)   |        ❌        |          ✅          |
 | Adopt an existing `migrate-mongo` changelog     |        —        | ✅ `migronaut import` |
 
-<sub>Reflects `migrate-mongo`'s documented CLI as of mid-2026. It has since added transaction access
+<sub>Reflects `migrate-mongo`'s documented CLI as of mid-2026 (v14: optional
+`lockCollectionName`/`lockTtl` lock, optional `useFileHash`). It has since added transaction access
 via a `client` argument; `migronaut` exposes the same plus a declarative per-file `useTransaction` flag.</sub>
 
 ### How it compares to `mongo-migrate-kit`
@@ -87,21 +109,6 @@ with no dependency.</sub>
 
 → **[Full comparison, and what stayed the same](https://migronaut.vercel.app/guide/vs-mongo-migrate-kit)**
 
-> [!TIP]
-> ### 🔄 Already using `migrate-mongo`? Switch in under a minute.
->
-> `migronaut` adopts your existing `changelog` **as-is** — no re-running migrations, no data loss, no rewriting
-> files. Point it at the same database and bring your whole history over in one command:
->
-> ```bash
-> migronaut import     # one-time: adopt your migrate-mongo changelog (it's never modified)
-> migronaut up         # applies only what's new — your past migrations are recognized as already applied
-> ```
->
-> Your applied history is preserved and new migrations run normally. Your `up`/`down`/`create`/`status`
-> mental model carries over 1:1 — you just gain dry-runs, single-file control, real rollbacks, hooks,
-> and locking. → **[See how it works](#advanced-features)**
-
 ---
 
 ## Quick start
@@ -168,6 +175,7 @@ Every command accepts the global flags `--uri`, `--db`, `--dir`, `--config`, `--
 |---|---|
 | `migronaut init` | Create a documented `migronaut.config.*` in the current directory |
 | `migronaut import` | Adopt an existing `migrate-mongo` changelog (one-time, forward-only) |
+| `migronaut baseline` | Mark existing migration files as applied without running them (adopt an existing DB) |
 | `migronaut create <name>` | Generate a timestamped migration file |
 | `migronaut up [file]` | Run all pending migrations, one named file, or up to `--to <file>` |
 | `migronaut down [file]` | Roll back the last batch, a chosen batch, the last N steps, one file, or to `--to <file>` |
@@ -179,8 +187,8 @@ Every command accepts the global flags `--uri`, `--db`, `--dir`, `--config`, `--
 | `migronaut lock` | Show who currently holds the migration lock |
 | `migronaut unlock` | Force-release a stuck lock left behind by a crashed run |
 
-Most data commands (`up`, `down`, `redo`, `status`, `list`, `dry-run`, `import`, `create`,
-`audit`, `lock`, `unlock`) accept **`--json`** for machine-readable output — see
+Most data commands (`up`, `down`, `redo`, `status`, `list`, `dry-run`, `import`, `baseline`,
+`create`, `audit`, `lock`, `unlock`) accept **`--json`** for machine-readable output — see
 [CI & automation](#ci--automation).
 
 <details>
@@ -206,6 +214,12 @@ migronaut import --force           # proceed even if the migronaut changelog alr
 migronaut import --no-lock         # skip the concurrency lock (local dev only)
 migronaut import --json            # machine-readable output
 
+# baseline — adopt an existing database (no prior migration tool)
+migronaut baseline                 # mark ALL pending files as applied, without running them
+migronaut baseline --to <file>     # only files up to and including <file>
+migronaut baseline --yes           # skip the confirmation prompt (required with --json)
+migronaut baseline --json          # machine-readable output ({ "baselined": [...], ... })
+
 # create — generate a migration file
 migronaut create <name>            # file type follows config `createExtension` (default .js)
 migronaut create <name> --ts       # force a .ts file
@@ -580,6 +594,11 @@ await migrator.disconnect();
 All errors extend `MigronautError` and carry a typed `code` (`LOCK_ALREADY_HELD`, `CHECKSUM_MISMATCH`,
 `NOT_APPLIED`, …), so `catch` blocks stay type-safe.
 
+> [!NOTE]
+> Running several kits against several databases in **one process**? Pass `envFile: false` and
+> explicit `uri`/`dbName` to each — `.env` loading mutates the shared `process.env` (dotenv
+> semantics), so different env files could otherwise leak `MIGRONAUT_*` values between kits.
+
 </details>
 
 ---
@@ -592,7 +611,9 @@ All errors extend `MigronautError` and carry a typed `code` (`LOCK_ALREADY_HELD`
 
 A config file is optional and auto-discovered in the working directory as `migronaut.config.ts`,
 `migronaut.config.js`, or `migronaut.config.json`. Run `migronaut init` to generate one — it ships fully commented,
-so every setting lives in one documented place:
+so every setting lives in one documented place. A generated `migronaut.config.json` points its
+`$schema` at the hosted copy for editor completion; offline or air-gapped setups can point it at
+the copy every install already ships: `./node_modules/@alexify/migronaut/migronaut.schema.json`.
 
 ```js
 // migronaut.config.js — generated by `migronaut init`, every option explained
@@ -671,6 +692,7 @@ optional rather than merely discouraged:
 | `MIGRONAUT_TEMPLATE_PATH` | `templatePath` | — *(built-in template)* |
 | `MIGRONAUT_TIMEOUT_MS` | `timeoutMs` | — *(no timeout)* |
 | `MIGRONAUT_ON_LOCK_LOST` | `onLockLost` | `abort` |
+| `MIGRONAUT_ON_OUT_OF_ORDER` | `onOutOfOrder` | `warn` |
 | `MIGRONAUT_ENSURE_INDEXES` | `ensureIndexes` | `true` |
 | `MIGRONAUT_RELOAD_MIGRATIONS` | `reloadMigrations` | `false` |
 | `MIGRONAUT_ENV_FILE` | `envFile` | `.env` |

package/bin/migronaut.js

@@ -1,5 +1,13 @@
 #!/usr/bin/env node
 const { errorText } = require('../src/utils/error.js');
+const { sanitizeTerminal } = require('../src/utils/sanitize.js');
+
+// Same hygiene as the default logger: these last-resort handlers are the only
+// paths that write to the TTY directly, and an escaped error message can embed
+// DB-derived text — sanitized by construction, like every other output path.
+const writeError = (error) => {
+  process.stderr.write(`✖ ${sanitizeTerminal(errorText(error))}\n`);
+};
 
 // `status --json | head` closes the pipe early; the resulting EPIPE arrives as
 // a stream 'error' event, not a promise rejection, and would otherwise crash
@@ -13,7 +21,7 @@ for (const stream of [process.stdout, process.stderr]) {
 // A rejection escaping the CLI's own handling still gets the project's error
 // format instead of Node's default trace.
 process.on('unhandledRejection', (error) => {
-  process.stderr.write(`✖ ${errorText(error)}\n`);
+  writeError(error);
   process.exitCode = 1;
 });
 
@@ -22,14 +30,14 @@ process.on('unhandledRejection', (error) => {
 // skips errorText's URI redaction. exit(1), not exitCode: after an uncaught
 // throw the process state is not trustworthy enough to keep draining.
 process.on('uncaughtException', (error) => {
-  process.stderr.write(`✖ ${errorText(error)}\n`);
+  writeError(error);
   process.exit(1);
 });
 
 const { run } = require('../src/cli/index.js');
 
 run(process.argv).catch((error) => {
-  process.stderr.write(`✖ ${errorText(error)}\n`);
+  writeError(error);
   // exitCode, not exit(): letting the event loop drain flushes buffered
   // stdout/stderr writes that process.exit() would truncate on a pipe.
   process.exitCode = 1;

package/index.d.ts

@@ -51,14 +51,15 @@ export interface MigrationModule {
 
 // ─── Changelog ────────────────────────────────────────────────────────────────
 
-export type MigrationStatus = 'applied' | 'reverted';
+export type MigrationStatus = 'applied' | 'reverted' | 'failed';
 
 /**
  * Where a changelog record originated. `'migrate-mongo'` marks a record adopted
- * via `migronaut import`; such records are forward-only and cannot be reverted by migronaut.
- * Absent (or `'migronaut'`) means a natively-applied, reversible migration.
+ * via `migronaut import`, `'baseline'` one stamped by `migronaut baseline`; both are
+ * forward-only and cannot be reverted by migronaut. Absent (or `'migronaut'`)
+ * means a natively-applied, reversible migration.
  */
-export type MigrationOrigin = 'migronaut' | 'migrate-mongo';
+export type MigrationOrigin = 'migronaut' | 'migrate-mongo' | 'baseline';
 
 /** A single record in the _migronaut_migrations changelog collection */
 export interface MigrationRecord {
@@ -71,6 +72,10 @@ export interface MigrationRecord {
   /** When this migration was applied the *first* time; survives a re-apply */
   firstAppliedAt?: Date;
   revertedAt?: Date;
+  /** When the last failed attempt was recorded (status `'failed'` only) */
+  failedAt?: Date;
+  /** Redacted message of the last failed attempt (status `'failed'` only) */
+  error?: string;
   /** Execution time in milliseconds */
   duration: number;
   /** SHA-256 hash of the file at time of execution */
@@ -237,6 +242,19 @@ export interface MigronautConfig {
    * - `'warn'` — log and keep going.
    */
   onLockLost?: 'abort' | 'warn';
+  /**
+   * What a bulk `up` does when a pending migration sorts before the newest
+   * applied one — a file merged late from a parallel branch, which would apply
+   * out of authoring order (environments migrated at different times then
+   * disagree on the effective order).
+   *
+   * - `'warn'` (default) — log the late arrivals and apply them.
+   * - `'error'` — refuse the run with an {@link OutOfOrderMigrationError}.
+   * - `'allow'` — apply silently.
+   *
+   * A single-file `up` (an explicit, deliberate target) is never checked.
+   */
+  onOutOfOrder?: 'warn' | 'error' | 'allow';
   /** Mongoose instance — required only if your migrations use Mongoose models */
   mongoose?: MongooseLike;
   hooks?: MigrationHooks;
@@ -288,8 +306,8 @@ export type LogMethod = (msg: string, fields?: Record<string, unknown>) => void;
 // ─── Progress Reporter ─────────────────────────────────────────────────────────
 
 /**
- * Receives migration lifecycle callbacks so a presentation layer (e.g. an ora
- * spinner) can react. Deliberately separate from {@link MigrationHooks}: hooks
+ * Receives migration lifecycle callbacks so a presentation layer (e.g. a
+ * progress spinner) can react. Deliberately separate from {@link MigrationHooks}: hooks
  * run user DB logic inside the migration; this only drives a UI indicator and
  * never touches the database.
  */
@@ -318,13 +336,39 @@ export interface RunResult {
 
 export interface StatusRow {
   file: string;
-  status: 'applied' | 'pending';
+  /**
+   * `'failed'` marks a recorded failed attempt — the file still counts as
+   * pending for every run path (the next `up` retries it), but the failure is
+   * surfaced instead of rendering as a plain pending row. A reverted record
+   * reports as `'pending'`, with `revertedAt` carrying its history.
+   */
+  status: 'applied' | 'pending' | 'failed';
   batch: number | null;
   appliedAt: Date | null;
   duration: number | null;
   /** null = never applied, true = match, false = mismatch */
   checksumOk: boolean | null;
   description?: string;
+  /** Who ran it — from the changelog's audit trail, when recorded */
+  executedBy?: string;
+  /** Environment stamped at apply time, when recorded */
+  environment?: string;
+  /** Correlation id of the run that wrote the record, when recorded */
+  runId?: string;
+  /** When the migration was reverted — present on reverted history rows */
+  revertedAt?: Date;
+  /** `'migrate-mongo'` / `'baseline'` mark forward-only adopted records */
+  origin?: MigrationOrigin;
+  /** Redacted message of the last failed attempt (status `'failed'` only) */
+  error?: string;
+  /** When the last failed attempt was recorded (status `'failed'` only) */
+  failedAt?: Date;
+  /**
+   * Present (true) on a not-yet-applied row that sorts before the newest
+   * applied migration — a file merged late from a parallel branch, which will
+   * apply out of authoring order. See `MigronautConfig.onOutOfOrder`.
+   */
+  outOfOrder?: true;
   /**
    * Present (true) when the changelog record's name is not a plain filename —
    * a legacy or tampered record. The row is reported as-is instead of failing
@@ -411,7 +455,8 @@ export type MigronautErrorCode =
   | 'CONNECTION_FAILED'
   | 'NOT_APPLIED'
   | 'IMPORT_TARGET_NOT_EMPTY'
-  | 'MIGRATION_IRREVERSIBLE';
+  | 'MIGRATION_IRREVERSIBLE'
+  | 'MIGRATION_OUT_OF_ORDER';
 
 // ─── Config file format ─────────────────────────────────────────────────────────
 
@@ -486,7 +531,7 @@ export interface MigrationEvent extends MigronautEventBase {
 }
 
 export interface RunStartEvent extends MigronautEventBase {
-  /** Which command started the run: 'up' | 'down' | 'redo' | 'import' */
+  /** Which command started the run: 'up' | 'down' | 'redo' | 'import' | 'baseline' */
   command?: string;
   direction?: 'up' | 'down';
 }
@@ -585,6 +630,24 @@ export interface InitOptions {
   secretProvider?: boolean;
 }
 
+/** Options for {@link MigratorKit.baseline} */
+export interface BaselineOptions {
+  /** Baseline pending files up to and including this one, instead of all */
+  to?: string;
+  /** Skip lock acquisition (dev only) */
+  noLock?: boolean;
+}
+
+/** Outcome of a {@link MigratorKit.baseline} call */
+export interface BaselineSummary {
+  /** Files marked applied by this call, in name order */
+  baselined: string[];
+  /** Files on disk that were already applied (or beyond `--to`) and untouched */
+  skipped: number;
+  /** The shared batch number stamped on the baselined records; null when none */
+  batch: number | null;
+}
+
 /** Options for {@link MigratorKit.import} */
 export interface ImportOptions {
   /** Source collection to read. Default: `changelog` (migrate-mongo's default) */
@@ -605,9 +668,16 @@ export interface ImportOptions {
 export interface MigratorKitOptions {
   /** Explicit config file path — overrides auto-discovery */
   configPath?: string;
+  /**
+   * Project root this instance resolves against: config-file discovery, the
+   * `.env` file and a relative `migrationsDir`. Defaults to `process.cwd()`.
+   * Set it when one process hosts kits for several projects, so their
+   * relative paths stop sharing one global working directory.
+   */
+  cwd?: string;
   /**
    * Optional lifecycle reporter, invoked around each migration's execution so a
-   * UI (the CLI's ora spinner) can show progress. Core never imports a spinner
+   * UI (the CLI's spinner) can show progress. Core never imports a spinner
    * library — it only calls these callbacks.
    */
   progress?: ProgressReporter;
@@ -698,6 +768,14 @@ export class MigratorKit extends EventEmitter {
    * records into our schema and writing them to `migrationsCollection`.
    */
   import(options?: ImportOptions): Promise<ImportResult>;
+  /**
+   * Adopt an existing database with no prior migration tool: mark migration
+   * files on disk as applied — checksums from disk, one shared batch,
+   * `origin: 'baseline'` — without executing anything. Forward-only:
+   * `down`/`redo` refuse baselined records. Idempotent: already-applied names
+   * are skipped, so a partial baseline can simply be re-run.
+   */
+  baseline(options?: BaselineOptions): Promise<BaselineSummary>;
 }
 
 // ─── Programmatic entry points ─────────────────────────────────────────────────
@@ -717,13 +795,23 @@ export interface RunMigrationsOptions extends MigratorKitOptions {
    */
   onLockHeld?: OnLockHeld;
   /**
-   * Max time (ms) to wait when `onLockHeld: 'wait'`. Default: 90000 — sized to
-   * outlast a peer's typical run plus one lock TTL, so parallel deploys don't
-   * give up while a healthy peer is still migrating.
+   * Max time (ms) to wait when `onLockHeld: 'wait'` **without observing holder
+   * progress**. While the holder's heartbeat visibly advances its lock, the
+   * deadline is re-armed — a healthy peer working through a long backlog never
+   * times its waiting peers out; only a stalled holder runs this budget down.
+   * Default: 90000.
    */
   lockWaitTimeoutMs?: number;
   /** Poll interval (ms) while waiting for the lock. Default: 500 */
   lockPollIntervalMs?: number;
+  /**
+   * Receives the internally-constructed {@link MigratorKit} right after
+   * construction (before connect), so an embedding application can subscribe
+   * to its lifecycle events — `kit.on('migration:success', …)` for metrics,
+   * lock telemetry, runId correlation — while keeping the managed
+   * connect/run/disconnect lifecycle.
+   */
+  onKit?: (kit: MigratorKit) => void;
 }
 
 /** Outcome of a {@link runMigrations} call */
@@ -771,6 +859,21 @@ export const EXIT_CODES: Readonly<
   Record<MigronautErrorCode | 'PENDING_MIGRATIONS' | 'AUDIT_FAILED', number>
 >;
 
+// ─── Logger factory ───────────────────────────────────────────────────────────
+
+/** Threshold accepted by {@link createLogger} — drops anything less severe */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Create the default console logger (pino-compatible surface, terminal-escape
+ * sanitization and colors included). `debug`/`info` write to `stream`
+ * (stdout by default); `warn`/`error` always write to stderr. For programmatic
+ * callers who want migronaut's own output at a chosen verbosity — e.g.
+ * `logger: createLogger(process.stdout, 'debug')` — without hand-writing a
+ * four-method logger.
+ */
+export function createLogger(stream?: NodeJS.WritableStream, level?: LogLevel): MigronautLogger;
+
 // ─── Errors ───────────────────────────────────────────────────────────────────
 
 /** Construction options shared by every migronaut error — `cause` keeps the wrapped Error */
@@ -897,7 +1000,16 @@ export class ImportTargetNotEmptyError extends MigronautError {
   constructor(message: string, context?: Record<string, unknown>, options?: MigronautErrorOptions);
 }
 
-/** Thrown when attempting to roll back a migrate-mongo-imported (forward-only) migration */
+/** Thrown when attempting to roll back a forward-only (imported or baselined) migration */
 export class IrreversibleMigrationError extends MigronautError {
   constructor(message: string, context?: Record<string, unknown>, options?: MigronautErrorOptions);
 }
+
+/**
+ * Thrown by a bulk `up` under `onOutOfOrder: 'error'` when a pending migration
+ * sorts before the newest applied one — a file merged late from a parallel
+ * branch. `context.names` lists the late arrivals.
+ */
+export class OutOfOrderMigrationError extends MigronautError {
+  constructor(message: string, context?: Record<string, unknown>, options?: MigronautErrorOptions);
+}

package/migronaut.schema.json

@@ -99,6 +99,15 @@
       "default": "abort",
       "description": "What to do when the lock is lost mid-run"
     },
+    "onOutOfOrder": {
+      "enum": [
+        "warn",
+        "error",
+        "allow"
+      ],
+      "default": "warn",
+      "description": "What a bulk `up` does when a pending migration sorts before the newest applied one (a file merged late from a parallel branch)"
+    },
     "envFile": {
       "oneOf": [
         {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alexify/migronaut",
-  "version": "1.0.0",
-  "description": "Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js",
+  "version": "2.0.0",
+  "description": "Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js — adopts an existing migrate-mongo changelog in one command",
   "license": "MIT",
   "author": "Alex Dolid <dolid.sasha@gmail.com>",
   "repository": {
@@ -51,13 +51,16 @@
     "migrations",
     "mongodb-migration",
     "mongodb-migrations",
+    "mongodb-migrate",
     "database-migration",
     "schema-migration",
     "migrate-mongo",
+    "migrate-mongo-alternative",
     "mongoose",
     "mongoose-migration",
     "rollback",
     "transactions",
+    "zero-dependency",
     "cli",
     "typescript",
     "nosql"
@@ -73,6 +76,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
+    "@vercel/analytics": "^2.0.1",
+    "@vercel/speed-insights": "^2.0.0",
     "c8": "^10.1.3",
     "esbuild": "^0.28.1",
     "mongodb": "^6.12.0",

package/src/cli/commands/baseline.js

@@ -0,0 +1,45 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
+const { confirm, defineCommand } = require('../shared.js');
+
+/** Register the `baseline` command (adopt an existing database, no prior tool) */
+function registerBaseline(program) {
+  defineCommand(program, {
+    name: 'baseline',
+    description: 'Mark existing migration files as applied without running them',
+    options: [
+      ['--to <file>', 'Baseline pending files up to and including this one'],
+      ['-y, --yes', 'Skip the confirmation prompt (required with --json)'],
+    ],
+    lockable: true,
+    mutating: true,
+    // Confirmation before any connection: baselining rewrites what the
+    // changelog claims is applied, which is exactly as consequential as a
+    // forced re-run — and --json is non-interactive, so it needs an explicit
+    // --yes rather than a prompt that can never be answered.
+    preflight: async (opts, _positionals, { logger }) => {
+      if (!opts.yes) {
+        if (opts.json) {
+          throw new ConfigInvalidError(
+            'baseline needs confirmation — pass --yes to confirm in --json mode',
+          );
+        }
+        const proceed = await confirm(
+          'Mark pending migration files as applied WITHOUT running them? [y/N] ',
+        );
+        if (!proceed) {
+          logger.info('Aborted');
+          return false;
+        }
+      }
+      return undefined;
+    },
+    run: (migrator, opts) =>
+      migrator.baseline({
+        noLock: opts.noLock,
+        ...(opts.to ? { to: opts.to } : {}),
+      }),
+    // No render: core logs the ✔ Baselined summary itself.
+  });
+}
+
+module.exports = { registerBaseline };

package/src/cli/commands/unlock.js

@@ -1,3 +1,4 @@
+const { ConfigInvalidError } = require('../../errors/index.js');
 const { confirm, defineCommand, emitJson } = require('../shared.js');
 const { lockedAtText } = require('./lock.js');
 
@@ -19,8 +20,17 @@ function registerUnlock(program) {
         return undefined;
       }
 
-      // Confirm before clearing — unless --yes, or --json (non-interactive).
-      if (!json && !opts.yes) {
+      // Confirm before clearing. --json is non-interactive, so it requires an
+      // explicit --yes instead of silently proceeding — force-releasing a live
+      // run's lock enables exactly the concurrent-migration scenario the lock
+      // exists to prevent, and the CLI's one destructive-confirmation policy
+      // (see `up --force`) is: non-interactive modes never assume consent.
+      if (!opts.yes) {
+        if (json) {
+          throw new ConfigInvalidError(
+            'unlock needs confirmation — pass --yes to confirm in --json mode',
+          );
+        }
         const since = lockedAtText(holder.lockedAt);
         logger.warn(
           `⚠ Lock held by pid ${holder.pid} on ${holder.host} (${holder.executedBy}) since ${since}`,

package/src/cli/exit-codes.js

@@ -33,6 +33,7 @@ const EXIT_CODES = {
   MIGRATION_INVALID_EXPORT: 20,
   LOCK_RELEASE_FAILED: 21,
   AUDIT_FAILED: 22,
+  MIGRATION_OUT_OF_ORDER: 23,
 };
 
 module.exports = { EXIT_CODES };