@alexify/migronaut 1.0.0 → 2.1.0

package/src/utils/collection-name.js

@@ -0,0 +1,21 @@
+/**
+ * Collection names we accept for the changelog/lock collections,
+ * `import --from/--to` and declared collections: non-empty, no `$` or NUL
+ * (invalid server-side), and outside the reserved `system.` namespace — so no
+ * config value can ever point a read or write at a system collection.
+ *
+ * Lives here rather than in config.js because the collection-definition
+ * validator (core/collections.js) needs it too, and config.js requires that
+ * validator — keeping the predicate in config.js would make the two a cycle.
+ */
+function isCollectionName(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    !value.includes('$') &&
+    !value.includes('\0') &&
+    !value.startsWith('system.')
+  );
+}
+
+module.exports = { isCollectionName };

package/src/utils/error.js

@@ -1,3 +1,4 @@
+const { MigronautError } = require('../errors/index.js');
 const { redactUris } = require('./redact.js');
 
 /**
@@ -8,4 +9,20 @@ const { redactUris } = require('./redact.js');
  */
 const errorText = (error) => redactUris(error instanceof Error ? error.message : String(error));
 
-module.exports = { errorText };
+/**
+ * {@link errorText} joined with the wrapped cause: "Migration up failed: X"
+ * says WHICH migration failed, and its `context.cause` says WHY — the half
+ * forensics actually needs. Both halves are redacted (the cause is the raw
+ * thrown message). What the changelog's failure trace and a failed span's
+ * status message both carry.
+ */
+function errorWithCause(error) {
+  const message = errorText(error);
+  const cause =
+    error instanceof MigronautError && typeof error.context?.cause === 'string'
+      ? errorText(error.context.cause)
+      : undefined;
+  return cause ? `${message} — ${cause}` : message;
+}
+
+module.exports = { errorText, errorWithCause };

package/src/utils/id.js

@@ -0,0 +1,77 @@
+const { randomUUID } = require('node:crypto');
+const { ConfigInvalidError } = require('../errors/index.js');
+const { errorText } = require('./error.js');
+
+/**
+ * Longest id migronaut accepts. Also the limit a queue worker enforces on a
+ * job's group id — one constant, so a producer can never mint an id its own
+ * worker would reject.
+ */
+const MAX_ID_LENGTH = 128;
+
+/**
+ * The default id: a random (v4) UUID. This module is the only place in `src/`
+ * that mints one — everything else asks for an id through it, which is what
+ * lets the `generateId` config option replace the format everywhere at once.
+ */
+const randomId = () => randomUUID();
+
+/**
+ * Return `value` when it is usable as an id, throw otherwise. An id is stored
+ * as a string field (changelog `runId`, lock `owner`, a job's `groupId`) and
+ * gated on by truthiness in the kit, so an empty or non-string value would
+ * silently switch off the reentrancy guard and the owner-scoped lock release.
+ */
+function assertId(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ID_LENGTH) {
+    throw new ConfigInvalidError(
+      `generateId must return a non-empty string of at most ${MAX_ID_LENGTH} characters`,
+      typeof value === 'string' ? { length: value.length } : { returned: typeof value },
+    );
+  }
+  return value;
+}
+
+/**
+ * Turn the `generateId` config option into the function the kit mints ids
+ * with. `undefined` keeps the default (`randomId`); anything else must be a
+ * function, and every id it returns is checked.
+ *
+ * The user's function is called bare — no arguments, no receiver — so a
+ * third-party generator passes straight through (`generateId: ulid`,
+ * `generateId: nanoid`): their first parameter means something of its own
+ * (a seed time, a size), and any argument migronaut passed would be read as it.
+ *
+ * It must be synchronous: the run id is minted in the same tick as the
+ * reentrancy guard that checks it, and a promise would be stored as a truthy
+ * non-id.
+ */
+function createIdGenerator(generateId) {
+  if (generateId === undefined) return randomId;
+  if (typeof generateId !== 'function') {
+    throw new ConfigInvalidError('generateId must be a function', {
+      generateId: typeof generateId,
+    });
+  }
+  return () => {
+    let value;
+    try {
+      value = generateId();
+    } catch (error) {
+      throw new ConfigInvalidError(
+        'generateId threw',
+        { cause: errorText(error) },
+        { cause: error },
+      );
+    }
+    if (typeof value?.then === 'function') {
+      // The promise is dropped, so its rejection must not surface as an
+      // unhandled one on top of the error below.
+      value.then(undefined, () => {});
+      throw new ConfigInvalidError('generateId must be synchronous — it returned a promise');
+    }
+    return assertId(value);
+  };
+}
+
+module.exports = { MAX_ID_LENGTH, assertId, createIdGenerator, randomId };

package/src/utils/loader.js

@@ -7,7 +7,7 @@ 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 */
+/** Distinguishes reload URLs; see importUserFile */
 let reloadCounter = 0;
 
 /** Narrow an unknown value to a function */
@@ -36,9 +36,10 @@ function isUnsupportedTsSyntaxError(error) {
 }
 
 /**
- * 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.
+ * An actionable message for a dynamic-import failure whose cause is a
+ * `.ts`/`.mts`/`.cts` file the current runtime refused, or null to let the
+ * original error speak for itself. `noun` names what the file is ("migration",
+ * "collection definition").
  *
  * The shipped CLI runs as plain Node, whose type stripping (always present on
  * the supported Node >= 22.18 range) handles erasable TypeScript only. Two
@@ -47,18 +48,29 @@ function isUnsupportedTsSyntaxError(error) {
  * `--no-experimental-strip-types`), and non-erasable syntax such as `enum` or
  * `namespace` (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`).
  */
-function tsLoadErrorOrNull(filepath, error) {
+function tsLoadMessageOrNull(filepath, error, noun) {
   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 `Cannot load TypeScript ${noun} "${name}" — type stripping is disabled in this Node process. Re-enable it, run migronaut under a TypeScript loader (e.g. tsx), or author the ${noun} as .js.`;
+  }
+  if (isUnsupportedTsSyntaxError(error)) {
+    return `Cannot load TypeScript ${noun} "${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).`;
+  }
+  return null;
+}
+
+/**
+ * Translate a dynamic-import failure of a migration into a clear
+ * MigrationInvalidExportError (see {@link tsLoadMessageOrNull}), or return
+ * null to let the original error propagate.
+ */
+function tsLoadErrorOrNull(filepath, error) {
+  const message = tsLoadMessageOrNull(filepath, error, 'migration');
+  if (message === null) {
     return null;
   }
   return new MigrationInvalidExportError(
@@ -68,6 +80,21 @@ function tsLoadErrorOrNull(filepath, error) {
   );
 }
 
+/**
+ * Import a user-authored module (a migration, a collection definition).
+ *
+ * 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, a
+ * queue worker) would keep evaluating the version it first imported; with
+ * `reload` 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.
+ */
+function importUserFile(filepath, options = {}) {
+  const url = pathToFileURL(filepath).href;
+  return import(options.reload ? `${url}?migronaut=${++reloadCounter}` : url);
+}
+
 /**
  * Dynamically load a migration file and validate its exports.
  *
@@ -85,18 +112,9 @@ async function loadMigrationFile(filepath, options = {}) {
     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);
+    imported = await importUserFile(filepath, { reload: options.reload });
   } catch (error) {
     const tsError = tsLoadErrorOrNull(filepath, error);
     if (tsError) {
@@ -128,4 +146,4 @@ async function loadMigrationFile(filepath, options = {}) {
   return migration;
 }
 
-module.exports = { tsLoadErrorOrNull, loadMigrationFile };
+module.exports = { importUserFile, loadMigrationFile, tsLoadErrorOrNull, tsLoadMessageOrNull };

package/src/utils/logger.js

@@ -52,6 +52,13 @@ function createLogger(stream = process.stdout, level = 'info') {
 
 const hasMethod = (value, name) => typeof value?.[name] === 'function';
 
+/** A sink is usable when it exposes any of the four level methods */
+const isUsableSink = (value) =>
+  hasMethod(value, 'info') ||
+  hasMethod(value, 'debug') ||
+  hasMethod(value, 'warn') ||
+  hasMethod(value, 'error');
+
 /**
  * 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
@@ -75,10 +82,12 @@ 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.
+ * `component` field; a missing method falls back to the nearest present one
+ * of similar severity (a warn/error-only logger keeps its warn/error output —
+ * its missing debug/info become no-ops, never a reason to silence failures),
+ * and every call is guarded so a throwing logger can never abort a
+ * half-applied run. A structurally unfit value (no level method at all)
+ * 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.
@@ -86,21 +95,30 @@ const adapters = new WeakMap();
 function resolveLogger(logger) {
   if (logger === null) return silentLogger;
   if (logger === undefined) return createLogger();
-  if (typeof logger !== 'object' || (!hasMethod(logger, 'info') && !hasMethod(logger, 'debug'))) {
+  if (typeof logger !== 'object' || !isUsableSink(logger)) {
     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 sink = child && isUsableSink(child) ? child : logger;
+  const noop = () => {};
+  // Fallback preference per level: same severity first, then the neighbors a
+  // reader of that sink would expect. debug/info never escalate to warn/error
+  // (running commentary must not masquerade as problems); warn/error always
+  // find SOME sink so failures stay visible.
+  const pick = (order) => {
+    for (const name of order) {
+      if (hasMethod(sink, name)) return sink[name].bind(sink);
+    }
+    return noop;
+  };
   const adapter = {
-    debug: guard(pick('debug'), pinoStyle),
-    info: guard(pick('info'), pinoStyle),
-    warn: guard(pick('warn'), pinoStyle),
-    error: guard(pick('error'), pinoStyle),
+    debug: guard(pick(['debug', 'info']), pinoStyle),
+    info: guard(pick(['info', 'debug']), pinoStyle),
+    warn: guard(pick(['warn', 'info', 'debug', 'error']), pinoStyle),
+    error: guard(pick(['error', 'warn', 'info', 'debug']), pinoStyle),
   };
   adapters.set(logger, adapter);
   return adapter;

package/src/utils/migration-name.js

@@ -0,0 +1,32 @@
+const { MigrationInvalidNameError } = require('../errors/index.js');
+
+/**
+ * Whether `name` is a bare filename: a non-empty string with no path
+ * separator, no NUL byte, and not `.`/`..`. The single definition of the rule
+ * that keeps a migration name from escaping the migrations directory — shared
+ * by the kit's path resolution and by anything that accepts a name from
+ * outside the process (a queue job's payload).
+ */
+function isBareFilename(name) {
+  return (
+    typeof name === 'string' &&
+    name.length > 0 &&
+    name !== '.' &&
+    name !== '..' &&
+    !name.includes('/') &&
+    !name.includes('\\') &&
+    !name.includes('\0')
+  );
+}
+
+/** Throw MigrationInvalidNameError unless `name` is a bare filename */
+function assertMigrationName(name, context = {}) {
+  if (!isBareFilename(name)) {
+    throw new MigrationInvalidNameError(
+      'Invalid migration name — must be a bare filename with no path segments',
+      { name, ...context },
+    );
+  }
+}
+
+module.exports = { assertMigrationName, isBareFilename };

package/src/utils/redact.js

@@ -8,12 +8,65 @@
  * 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;
+const URI_CREDENTIALS = /([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^:@/\s]*):([^@/\s]+)@/g;
 
-/** Mask `scheme://user:secret@` as `scheme://user:****@` anywhere in `text` */
+/**
+ * Query parameters whose value is a secret. The userinfo form is not the only
+ * place a MongoDB URI carries credentials: TLS key passphrases and proxy
+ * passwords travel as plain query parameters and would otherwise survive
+ * redaction into logs, error context and `--json` output.
+ */
+const URI_QUERY_SECRETS =
+  /([?&](?:tlsCertificateKeyFilePassword|proxyPassword|sslKeyPassword)=)[^&\s]+/gi;
+
+/**
+ * `authMechanismProperties` is a comma-separated `KEY:VALUE` list; only the
+ * values of secret-bearing keys (AWS_SESSION_TOKEN et al.) are masked, so
+ * non-secret properties (SERVICE_NAME, …) stay readable.
+ */
+const AUTH_MECHANISM_PROPS = /([?&]authMechanismProperties=)([^&\s]+)/gi;
+const SENSITIVE_PROP_KEY = /TOKEN|SECRET|PASSWORD/i;
+
+/**
+ * Mask credentials anywhere in `text`: `scheme://user:secret@` (an empty
+ * username still hides the password), secret-bearing query parameters, and
+ * secret values inside `authMechanismProperties`.
+ */
 function redactUris(text) {
   if (typeof text !== 'string') return text;
-  return text.replace(URI_CREDENTIALS, '$1$2:****@');
+  return text
+    .replace(URI_CREDENTIALS, '$1$2:****@')
+    .replace(URI_QUERY_SECRETS, '$1****')
+    .replace(AUTH_MECHANISM_PROPS, (_match, prefix, value) => {
+      const pairs = value.split(',');
+      for (let i = 0; i < pairs.length; i++) {
+        const colon = pairs[i].indexOf(':');
+        if (colon === -1) continue;
+        const key = pairs[i].slice(0, colon);
+        if (SENSITIVE_PROP_KEY.test(key)) pairs[i] = `${key}:****`;
+      }
+      return `${prefix}${pairs.join(',')}`;
+    });
+}
+
+/**
+ * The document values a server error can quote: an E11000 duplicate-key
+ * message ends with the offending key's values — an email, a phone number —
+ * which is the database's data, not an error's. Everything from `dup key: {`
+ * to the last `}` on that line is masked; the index name before it still says
+ * which constraint was violated.
+ */
+const DUPLICATE_KEY_VALUES = /(dup key: )\{[^\n]*\}/g;
+
+/**
+ * For text that leaves the process for a third party — a tracing backend, a
+ * queue that keeps failed jobs and serves them to dashboards: credentials
+ * masked (as everywhere) and the data values a server error quotes, too.
+ * Local log lines keep the values; they are what a developer debugs with.
+ */
+function redactOutbound(text) {
+  if (typeof text !== 'string') return text;
+  return redactUris(text).replace(DUPLICATE_KEY_VALUES, '$1{ <redacted> }');
 }
 
 /**
@@ -36,4 +89,4 @@ function redactDeep(value) {
   return value;
 }
 
-module.exports = { redactUris, redactDeep };
+module.exports = { redactDeep, redactOutbound, redactUris };

package/src/utils/sanitize.js

@@ -8,9 +8,14 @@
  * clear the screen, or restyle everything printed after them.
  */
 
-/** Control characters stripped from untrusted values (tab and newline survive) */
+/**
+ * Control characters stripped from untrusted values (tab and newline survive).
+ * The full C1 block (U+0080-U+009F) is included: CSI, OSC, DCS, PM and APC are
+ * single-codepoint escape introducers on terminals that decode C1, and none of
+ * them is ever legitimate text.
+ */
 // oxlint-disable-next-line no-control-regex -- stripping control characters is the point
-const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
+const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u0080-\u009f]/g;
 
 /**
  * SGR color sequences (`ESC[…m`) to preserve, or a control character to drop.
@@ -19,7 +24,7 @@ const CONTROL_CHARS = /[\u0000-\u0008\u000b-\u001f\u007f\u009b]/g;
  * 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;
+const SGR_OR_CONTROL = /(\u001b\[[0-9;]*m)|[\u0000-\u0008\u000b-\u001f\u007f\u0080-\u009f]/g;
 
 /**
  * Strip every terminal control character from an untrusted value. For data