@alexify/migronaut 1.0.0

package/src/utils/date.js

@@ -0,0 +1,28 @@
+/** Zero-pad a number to two digits */
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+/**
+ * Local-time compact timestamp, e.g. `20240526143021`.
+ * Used as the leading prefix for timestamped migration filenames.
+ */
+function formatStamp(date) {
+  return (
+    `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}` +
+    `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+  );
+}
+
+/**
+ * Human-readable local-time timestamp, e.g. `2024-05-26 14:30:21`.
+ * Used in the status/list/import tables.
+ */
+function formatDateTime(date) {
+  return (
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+    `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
+  );
+}
+
+module.exports = { formatStamp, formatDateTime };

package/src/utils/env.js

@@ -0,0 +1,51 @@
+const fs = require('node:fs/promises');
+const util = require('node:util');
+const { ConfigInvalidError } = require('../errors/index.js');
+
+/** Larger than any sane .env — the same ceiling custom templates get */
+const MAX_ENV_FILE_BYTES = 1024 * 1024;
+
+/**
+ * Keys never copied into the target: with a plain-object `env`, assigning
+ * `__proto__` writes through to the prototype. `process.env` coerces these
+ * harmlessly today, but that is an implementation detail of process.env —
+ * the guard makes the intent explicit instead of leaning on it.
+ */
+const UNSAFE_ENV_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Load `filePath` (.env format) into `env`, never overriding keys that are
+ * already set (dotenv's `override: false` semantics). A missing file is a
+ * silent no-op. Parsing is `util.parseEnv` — always present on the supported
+ * Node range (added in 20.12; engines require ≥22.18).
+ */
+async function applyEnvFile(filePath, env = process.env) {
+  // stat before read: `--env-file /dev/zero` (or a runaway file) must fail
+  // with a typed error, not hang the process reading forever.
+  let stats;
+  try {
+    stats = await fs.stat(filePath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  // A device file (/dev/zero reports size 0), FIFO or directory would hang or
+  // garble the read — only regular files are .env candidates.
+  if (!stats.isFile()) {
+    throw new ConfigInvalidError('env file is not a regular file', { path: filePath });
+  }
+  if (stats.size > MAX_ENV_FILE_BYTES) {
+    throw new ConfigInvalidError('env file is too large (max 1 MB)', {
+      path: filePath,
+      size: stats.size,
+    });
+  }
+  const content = await fs.readFile(filePath, 'utf8');
+  const parsed = util.parseEnv(content);
+  for (const key of Object.keys(parsed)) {
+    if (UNSAFE_ENV_KEYS.has(key)) continue;
+    if (env[key] === undefined) env[key] = parsed[key];
+  }
+}
+
+module.exports = { applyEnvFile };

package/src/utils/error.js

@@ -0,0 +1,11 @@
+const { redactUris } = require('./redact.js');
+
+/**
+ * Human-readable message from any thrown value, with URI credentials masked.
+ * The single chokepoint for turning caught errors into strings — using it
+ * everywhere is what keeps driver messages that echo the connection URI from
+ * leaking passwords into logs, error context, or `--json` output.
+ */
+const errorText = (error) => redactUris(error instanceof Error ? error.message : String(error));
+
+module.exports = { errorText };

package/src/utils/loader.js

@@ -0,0 +1,131 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { MigrationFileNotFoundError, MigrationInvalidExportError } = require('../errors/index.js');
+const { errorText } = require('./error.js');
+
+/** TypeScript source extensions that require a TS-capable runtime to import */
+const TS_EXTENSIONS = new Set(['.ts', '.mts', '.cts']);
+
+/** Distinguishes reload URLs; see the reload comment in loadMigrationFile */
+let reloadCounter = 0;
+
+/** Narrow an unknown value to a function */
+function isFunction(value) {
+  return typeof value === 'function';
+}
+
+/** True when an import failed because Node cannot load the file's extension */
+function isUnknownExtensionError(error) {
+  if (typeof error !== 'object' || error === null) {
+    return false;
+  }
+  const { code, message } = error;
+  return (
+    code === 'ERR_UNKNOWN_FILE_EXTENSION' ||
+    (typeof message === 'string' && message.includes('Unknown file extension'))
+  );
+}
+
+/** True when type stripping refused non-erasable syntax (enum, namespace, …) */
+function isUnsupportedTsSyntaxError(error) {
+  if (typeof error !== 'object' || error === null) {
+    return false;
+  }
+  return error.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX';
+}
+
+/**
+ * Translate a dynamic-import failure into a clear MigrationInvalidExportError
+ * when the cause is a `.ts`/`.mts`/`.cts` file the current runtime refused, or
+ * return null to let the original error propagate.
+ *
+ * The shipped CLI runs as plain Node, whose type stripping (always present on
+ * the supported Node >= 22.18 range) handles erasable TypeScript only. Two
+ * failure shapes get an actionable message instead of the raw Node error:
+ * stripping disabled entirely (`ERR_UNKNOWN_FILE_EXTENSION`, e.g. under
+ * `--no-experimental-strip-types`), and non-erasable syntax such as `enum` or
+ * `namespace` (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`).
+ */
+function tsLoadErrorOrNull(filepath, error) {
+  const ext = path.extname(filepath).toLowerCase();
+  if (!TS_EXTENSIONS.has(ext)) {
+    return null;
+  }
+  const name = path.basename(filepath);
+  let message;
+  if (isUnknownExtensionError(error)) {
+    message = `Cannot load TypeScript migration "${name}" — type stripping is disabled in this Node process. Re-enable it, run migronaut under a TypeScript loader (e.g. tsx), or author the migration as .js.`;
+  } else if (isUnsupportedTsSyntaxError(error)) {
+    message = `Cannot load TypeScript migration "${name}" — it uses syntax Node's type stripping cannot erase (e.g. enum, namespace). Rewrite with erasable-only syntax, or run migronaut under a TypeScript loader (e.g. tsx).`;
+  } else {
+    return null;
+  }
+  return new MigrationInvalidExportError(
+    message,
+    { filepath, cause: errorText(error) },
+    { cause: error },
+  );
+}
+
+/**
+ * Dynamically load a migration file and validate its exports.
+ *
+ * Handles all three supported formats:
+ * - TypeScript / JavaScript ESM named exports (`export async function up/down`)
+ * - CommonJS default export (`module.exports = { up, down }`)
+ *
+ * @throws {MigrationFileNotFoundError} when the file does not exist
+ * @throws {MigrationInvalidExportError} when up/down are not both functions
+ */
+async function loadMigrationFile(filepath, options = {}) {
+  try {
+    await fs.access(filepath);
+  } catch {
+    throw new MigrationFileNotFoundError('Migration file not found', { filepath });
+  }
+
+  // Node caches ESM modules by URL forever. A one-shot CLI never notices, but a
+  // long-lived process (a test runner, a dev server re-running migrations)
+  // would keep executing the version it first imported; a unique query string
+  // forces a fresh evaluation. Off by default — it leaks a module per load.
+  // A monotonic counter, not Date.now(): two reloads in one millisecond must
+  // still get distinct URLs.
+  const url = pathToFileURL(filepath).href;
+  const href = options.reload ? `${url}?migronaut=${++reloadCounter}` : url;
+
+  let imported;
+  try {
+    imported = await import(href);
+  } catch (error) {
+    const tsError = tsLoadErrorOrNull(filepath, error);
+    if (tsError) {
+      throw tsError;
+    }
+    throw error;
+  }
+  // `mod.default ?? mod` handles the CommonJS default-export case
+  const resolved = imported.default ?? imported;
+
+  if (!isFunction(resolved.up) || !isFunction(resolved.down)) {
+    throw new MigrationInvalidExportError('Migration must export async up() and down() functions', {
+      filepath,
+    });
+  }
+
+  const migration = { up: resolved.up, down: resolved.down };
+
+  if (typeof resolved.useTransaction === 'boolean') {
+    migration.useTransaction = resolved.useTransaction;
+  }
+  if (Number.isInteger(resolved.timeoutMs) && resolved.timeoutMs > 0) {
+    migration.timeoutMs = resolved.timeoutMs;
+  }
+  if (typeof resolved.description === 'string') {
+    migration.description = resolved.description;
+  }
+
+  return migration;
+}
+
+module.exports = { tsLoadErrorOrNull, loadMigrationFile };

package/src/utils/logger.js

@@ -0,0 +1,109 @@
+const { createColors } = require('./colors.js');
+const { sanitizeTerminal } = require('./sanitize.js');
+
+/** Severity order, used to drop messages below the configured level */
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, silent: 100 };
+
+/** A logger whose methods are all no-ops — used to silence all output */
+const silentLogger = {
+  debug: () => {},
+  info: () => {},
+  warn: () => {},
+  error: () => {},
+};
+
+/**
+ * Create the default console logger (pino-compatible method surface).
+ *
+ * `debug`/`info` write to `stream` (stdout by default); `warn`/`error`
+ * always write to stderr. Pass `process.stderr` as `stream` to keep stdout
+ * clean for machine-readable output (e.g. `--json` mode routes all human
+ * lines here). Colors: `debug` is dimmed, `warn` yellow, `error` red.
+ *
+ * `level` drops anything less severe than itself — `'debug'` shows everything,
+ * `'error'` only failures. The structured `fields` second argument that core
+ * passes is ignored here: the human line already carries that information.
+ */
+function createLogger(stream = process.stdout, level = 'info') {
+  const outColors = createColors(stream);
+  const errColors = createColors(process.stderr);
+  const threshold = LEVELS[level] ?? LEVELS.info;
+  const writeOut = (msg) => {
+    stream.write(`${msg}\n`);
+  };
+  const writeErr = (msg) => {
+    process.stderr.write(`${msg}\n`);
+  };
+  const at = (name, write) => (LEVELS[name] >= threshold ? write : () => {});
+  // Sanitized by construction: messages routinely embed migration names and
+  // lock-holder fields — values anyone with DB write access can influence —
+  // and no individual call site should have to remember terminal-escape
+  // hygiene. SGR color codes (migronaut's own table/level styling) survive;
+  // cursor movement and screen clearing do not. User-injected loggers are
+  // exempt (their sink is not necessarily a terminal) — this is the default
+  // terminal logger only.
+  return {
+    debug: at('debug', (msg) => writeOut(outColors.dim(sanitizeTerminal(msg)))),
+    info: at('info', (msg) => writeOut(sanitizeTerminal(msg))),
+    warn: at('warn', (msg) => writeErr(errColors.yellow(sanitizeTerminal(msg)))),
+    error: at('error', (msg) => writeErr(errColors.red(sanitizeTerminal(msg)))),
+  };
+}
+
+const hasMethod = (value, name) => typeof value?.[name] === 'function';
+
+/**
+ * Wrap a sink method so a throwing user logger can never break a migration run.
+ * `pinoStyle` swaps the argument order to `(fields, msg)`, which is what pino
+ * and its ecosystem expect for structured logging; everyone else gets
+ * `(msg, fields)` so a plain `(msg) => …` logger keeps working unchanged.
+ */
+const guard = (fn, pinoStyle) => (msg, fields) => {
+  try {
+    if (fields === undefined) fn(msg);
+    else if (pinoStyle) fn(fields, msg);
+    else fn(msg, fields);
+  } catch {
+    // Logging must never break a migration run.
+  }
+};
+
+/** Adapters are cached per user logger so pino's child() binds only once */
+const adapters = new WeakMap();
+
+/**
+ * Resolve the effective logger from a config value: `null` → silent,
+ * `undefined` → default console logger, otherwise the user's logger adapted
+ * to the four-method surface. A pino-style `child` is bound once with a
+ * `component` field; a missing `debug`/`warn`/`error` falls back to `info`
+ * (or `debug` when only that exists), and every call is guarded so a
+ * throwing logger can never abort a half-applied run. A structurally unfit
+ * value (no `info`/`debug` function) silences output instead of crashing.
+ *
+ * A logger exposing `child()` is treated as pino-style, so structured fields
+ * are passed as the first argument rather than the second.
+ */
+function resolveLogger(logger) {
+  if (logger === null) return silentLogger;
+  if (logger === undefined) return createLogger();
+  if (typeof logger !== 'object' || (!hasMethod(logger, 'info') && !hasMethod(logger, 'debug'))) {
+    return silentLogger;
+  }
+  const cached = adapters.get(logger);
+  if (cached !== undefined) return cached;
+  const pinoStyle = hasMethod(logger, 'child');
+  const child = pinoStyle ? logger.child({ component: 'migronaut' }) : null;
+  const sink = child && (hasMethod(child, 'info') || hasMethod(child, 'debug')) ? child : logger;
+  const base = hasMethod(sink, 'info') ? sink.info.bind(sink) : sink.debug.bind(sink);
+  const pick = (name) => (hasMethod(sink, name) ? sink[name].bind(sink) : base);
+  const adapter = {
+    debug: guard(pick('debug'), pinoStyle),
+    info: guard(pick('info'), pinoStyle),
+    warn: guard(pick('warn'), pinoStyle),
+    error: guard(pick('error'), pinoStyle),
+  };
+  adapters.set(logger, adapter);
+  return adapter;
+}
+
+module.exports = { silentLogger, createLogger, resolveLogger };

package/src/utils/redact.js

@@ -0,0 +1,39 @@
+/**
+ * Credential redaction for anything that leaves the process — error messages,
+ * stacks, `--json` payloads, log lines. The MongoDB driver echoes the raw
+ * connection URI in several parse errors, so every captured message must pass
+ * through here before it can be printed or serialized.
+ *
+ * Regex-based, not `new URL()`: multi-host mongodb URIs fail WHATWG parsing,
+ * and the URI may sit anywhere inside a larger message (unlike
+ * `maskUriCredentials` in template.js, which is anchored to a whole-string URI).
+ */
+const URI_CREDENTIALS = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^:@/\s]+):([^@/\s]+)@/g;
+
+/** Mask `scheme://user:secret@` as `scheme://user:****@` anywhere in `text` */
+function redactUris(text) {
+  if (typeof text !== 'string') return text;
+  return text.replace(URI_CREDENTIALS, '$1$2:****@');
+}
+
+/**
+ * Redact every string reachable from `value` (plain objects and arrays only —
+ * class instances are left alone rather than cloned into broken shapes).
+ * Returns a copy; never mutates the input.
+ */
+function redactDeep(value) {
+  if (typeof value === 'string') return redactUris(value);
+  if (Array.isArray(value)) {
+    const copy = new Array(value.length);
+    for (let index = 0; index < value.length; index++) copy[index] = redactDeep(value[index]);
+    return copy;
+  }
+  if (value !== null && typeof value === 'object' && value.constructor === Object) {
+    const copy = {};
+    for (const key of Object.keys(value)) copy[key] = redactDeep(value[key]);
+    return copy;
+  }
+  return value;
+}
+
+module.exports = { redactUris, redactDeep };

package/src/utils/sanitize.js

@@ -0,0 +1,43 @@
+/**
+ * Terminal control-character sanitization for untrusted text.
+ *
+ * Cell values, lock-holder fields and migration filenames come from the
+ * changelog, the lock collection and the filesystem — sources anyone with
+ * write access to the database (or a malicious PR) can influence — so ESC and
+ * friends must never reach the terminal, where they could move the cursor,
+ * clear the screen, or restyle everything printed after them.
+ */
+
+/** Control characters stripped from untrusted values (tab and newline survive) */
+// oxlint-disable-next-line no-control-regex -- stripping control characters is the point
+const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
+
+/**
+ * SGR color sequences (`ESC[…m`) to preserve, or a control character to drop.
+ * Colors are the one escape family migronaut itself emits (tables, log
+ * levels); every other sequence — cursor movement, screen clearing, OSC
+ * titles — has no legitimate reason to be in a log line.
+ */
+// oxlint-disable-next-line no-control-regex -- stripping control characters is the point
+const SGR_OR_CONTROL = /(\u001b\[[0-9;]*m)|[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
+
+/**
+ * Strip every terminal control character from an untrusted value. For data
+ * that should carry no styling at all (table cells, spinner text) — apply
+ * before adding migronaut's own colors, so those survive.
+ */
+function sanitize(text) {
+  return String(text).replace(CONTROL_CHARS, '');
+}
+
+/**
+ * Strip control characters while preserving SGR color sequences. For the
+ * terminal logger's write path, where trusted colored output (a rendered
+ * table) and untrusted substrings (a migration name inside a message) arrive
+ * in the same string.
+ */
+function sanitizeTerminal(text) {
+  return String(text).replace(SGR_OR_CONTROL, (_match, sgr) => sgr ?? '');
+}
+
+module.exports = { sanitize, sanitizeTerminal };