@lenne.tech/nest-server 11.43.2 → 12.0.0

package/src/core/modules/migrate/helpers/ts-compiler.cjs

@@ -0,0 +1,183 @@
+/**
+ * TypeScript loader for running sources without a build — the migrate CLI, the dev server and scripts.
+ *
+ * Registers a CommonJS `require` hook that compiles `.ts` / `.cts` files with SWC (`@swc/core`) on load, and — for
+ * ESM projects (`"type": "module"`, what `nest new` creates since NestJS 12) — the matching ESM hooks
+ * (`ts-compiler-hooks.mjs`, through `module.register()`), so `import` reaches TypeScript sources the same way.
+ * It is the framework's replacement for ts-node (12.0.0): ts-node is unmaintained, needed TypeScript-6
+ * workarounds (TS5011 / TS5107 / TS5110 from inherited compiler options), type-checked what it
+ * loaded on every start, and — like `@swc-node/register`, whose peer range ends below TypeScript 7 —
+ * depends on TypeScript's JavaScript API. This loader does not touch TypeScript at all: it only
+ * strips types and lowers decorators, with the same compiler vitest (unplugin-swc) and
+ * `nest build -b swc` already use. Type errors are reported by `tsc` (build, `check`, the IDE), not here.
+ *
+ * Usage:
+ *
+ *   migrate up --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+ *   node -r ./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js src/main.ts
+ *
+ * Requiring the file registers the hook; the exported function does the same and is idempotent, which
+ * is the contract `--compiler ts:<file>` relies on (the CLI requires the file and calls its export).
+ *
+ * `@swc/core` is resolved from the working directory first (the project that runs the sources), then
+ * from this file — in an isolated pnpm layout only the project's own `node_modules` holds it.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const Module = require('node:module');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { isMainThread } = require('node:worker_threads');
+
+// The loader table Node's CommonJS `require` dispatches on by extension — what every require hook patches.
+// oxlint-disable-next-line no-underscore-dangle -- Node's own name for it
+const extensionHandlers = Module._extensions;
+
+// A CONTRACT, not an implementation detail: the lt CLI's vendor bootstrap (migrations-utils/ts-compiler.js)
+// checks the registered `.ts` handler for this exact key to tell this loader from an older core's ts-node
+// export. Renaming it makes every vendor project fall back to ts-node — pinned by tests/unit/ts-compiler.spec.ts.
+const MARKER = Symbol.for('lenne.tech/nest-server/ts-compiler');
+
+/**
+ * Mirrors the `tsc` build (`tsconfig.json` → `target: es2022`), so a source run behaves like `dist/`:
+ *
+ * - legacy decorators + decorator metadata: NestJS DI, `@UnifiedField`, `@Prop` and `@Field` read the
+ *   emitted `design:*` metadata;
+ * - `useDefineForClassFields: true` is what `tsc` does for `target: es2022`. `@nestjs/cli`'s own SWC
+ *   defaults use `false`, under which a declared field without an initializer is not an own property —
+ *   a difference from the production build, not a detail;
+ * - `keepClassNames`: class names are DI tokens, logger contexts and GraphQL type names.
+ *
+ * `.swcrc` is ignored on purpose: the result must not depend on a file a project keeps for another tool.
+ * `tests/unit/ts-compiler.spec.ts` pins these against the repository's tsconfig.
+ */
+const SWC_OPTIONS = {
+  configFile: false,
+  jsc: {
+    keepClassNames: true,
+    parser: { decorators: true, dynamicImport: true, syntax: 'typescript' },
+    target: 'es2022',
+    transform: { decoratorMetadata: true, legacyDecorator: true, useDefineForClassFields: true },
+  },
+  module: { type: 'commonjs' },
+  sourceMaps: 'inline',
+  swcrc: false,
+};
+
+/** Extensions the hook compiles. `.mts` is ESM and never reaches a `require` hook. */
+const EXTENSIONS = ['.ts', '.cts'];
+
+/**
+ * The TypeScript source a `.js` / `.cjs` specifier names, the way `tsc` and vitest read it: ESM requires the
+ * extension of the EMITTED file (`./x.js`), so a relative specifier written for both module systems points at
+ * a file that only exists after a build. A source run maps it back to `x.ts` / `x.cts`.
+ */
+const SOURCE_EXTENSIONS = { '.cjs': ['.cts'], '.js': ['.ts', '.cts'] };
+
+/** Marks the patched resolver, so registering twice does not wrap it twice. */
+const RESOLVE_MARKER = Symbol.for('lenne.tech/nest-server/ts-compiler/resolve');
+
+/**
+ * Let `require('./x.js')` from a TypeScript file find `x.ts` when no `x.js` exists. Only path-like requests
+ * from a compiled TypeScript parent are retried, and only after Node's own resolution failed — a real `.js`
+ * file always wins, and package specifiers are never touched.
+ */
+function patchResolver() {
+  // oxlint-disable-next-line no-underscore-dangle -- Node's own resolver, what every TypeScript require hook wraps
+  const original = Module._resolveFilename;
+  if (original[RESOLVE_MARKER]) {
+    return;
+  }
+  function resolveTypeScriptSource(request, parent, ...rest) {
+    try {
+      return original.call(this, request, parent, ...rest);
+    } catch (error) {
+      const extension = request.match(/\.c?js$/)?.[0];
+      const fromTypeScript = /\.c?ts$/.test(parent?.filename ?? '');
+      if (error?.code !== 'MODULE_NOT_FOUND' || !extension || !fromTypeScript || !/^\.{0,2}\//.test(request)) {
+        throw error;
+      }
+      const stem = request.slice(0, -extension.length);
+      for (const sourceExtension of SOURCE_EXTENSIONS[extension]) {
+        try {
+          return original.call(this, stem + sourceExtension, parent, ...rest);
+        } catch {
+          // try the next one; the original error is the one worth reporting
+        }
+      }
+      throw error;
+    }
+  }
+  resolveTypeScriptSource[RESOLVE_MARKER] = true;
+  // oxlint-disable-next-line no-underscore-dangle -- see above
+  Module._resolveFilename = resolveTypeScriptSource;
+}
+
+/**
+ * Load `@swc/core`, or fail with the one instruction that fixes it.
+ *
+ * @param {string[]} [paths] - Where to resolve it from; defaults to the working directory, then this file.
+ */
+function loadSwc(paths = [process.cwd(), __dirname]) {
+  let resolved;
+  try {
+    resolved = require.resolve('@swc/core', { paths });
+  } catch {
+    const error = new Error(
+      'Running TypeScript sources needs @swc/core, which this project does not have. ' +
+        'Add it as a devDependency: pnpm add -D @swc/core',
+    );
+    error.code = 'LT_SWC_CORE_MISSING';
+    throw error;
+  }
+  return require(resolved);
+}
+
+/**
+ * Register the hook. Safe to call more than once.
+ */
+function register() {
+  if (extensionHandlers['.ts']?.[MARKER]) {
+    return;
+  }
+  const swc = loadSwc();
+  // Stack traces point at the TypeScript lines (the code carries inline source maps).
+  process.setSourceMapsEnabled(true);
+
+  function compileTypeScript(module, filename) {
+    const { code } = swc.transformSync(fs.readFileSync(filename, 'utf8'), { ...SWC_OPTIONS, filename });
+    // oxlint-disable-next-line no-underscore-dangle -- the CommonJS module API every require hook calls
+    module._compile(code, filename);
+  }
+  compileTypeScript[MARKER] = true;
+  for (const extension of EXTENSIONS) {
+    extensionHandlers[extension] = compileTypeScript;
+  }
+  patchResolver();
+  registerEsmHooks();
+}
+
+/** Marks the process once the ESM hooks are registered. */
+const ESM_MARKER = Symbol.for('lenne.tech/nest-server/ts-compiler/esm');
+
+/**
+ * Register the ESM hooks (`ts-compiler-hooks.mjs`) for `import`ed TypeScript: an ESM project's entry and everything it
+ * imports. Without them Node would hand a `.ts` entry to its own type stripping, which cannot lower decorators or emit
+ * their metadata — NestJS needs both. Only on the main thread: the hooks run on a thread of their own, which loads this
+ * file for its SWC options and must not register itself again.
+ */
+function registerEsmHooks() {
+  if (!isMainThread || typeof Module.register !== 'function' || globalThis[ESM_MARKER]) {
+    return;
+  }
+  globalThis[ESM_MARKER] = true;
+  Module.register(pathToFileURL(path.join(__dirname, 'ts-compiler-hooks.mjs')).href);
+}
+
+register();
+
+module.exports = register;
+module.exports.loadSwc = loadSwc;
+module.exports.SWC_OPTIONS = SWC_OPTIONS;
+module.exports.SOURCE_EXTENSIONS = SOURCE_EXTENSIONS;

package/src/core/modules/migrate/helpers/ts-compiler.js

@@ -1,14 +1,11 @@
 /**
- * TypeScript compiler for migrate CLI
+ * Entry point of the framework's TypeScript loader — the path `--compiler ts:…` and `node -r …` name.
  *
- * This file registers ts-node to allow TypeScript migrations to be executed.
- *
- * Usage with migrate CLI:
- * migrate --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
- *
- * Or copy this file to your project's migrations-utils folder.
+ * CommonJS in every project: `helpers/package.json` declares `"type": "commonjs"` for this directory, so the file keeps
+ * its format inside this ESM package (12.0.0+) and inside an ESM vendor project alike, and the established path and
+ * its function export stay the contract they have always been. The implementation lives in `ts-compiler.cjs`; see
+ * there for what the loader does.
  */
+'use strict';
 
-const tsNode = require('ts-node');
-
-module.exports = tsNode.register;
+module.exports = require('./ts-compiler.cjs');

package/src/core/modules/migrate/index.ts

@@ -35,7 +35,7 @@
  * ```
  */
 
-export * from './cli/migrate-cli';
-export * from './helpers/migration.helper';
-export * from './migration-runner';
-export * from './mongo-state-store';
+export * from './cli/migrate-cli.js';
+export * from './migration.helper.js';
+export * from './migration-runner.js';
+export * from './mongo-state-store.js';

package/src/core/modules/migrate/migration-runner.ts

@@ -1,7 +1,9 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MongoStateStore, withMigrationLock } from './mongo-state-store';
+import { _endMigration, _startMigration } from './migration.helper.js';
+import { MongoStateStore, withMigrationLock } from './mongo-state-store.js';
+import { createRequire } from 'node:module';
 
 /**
  * Migration file interface
@@ -43,10 +45,11 @@ const MIGRATION_EXTENSION_PATTERN = /\.(ts|js)$/;
  * Migration identity = the timestamped file stem WITHOUT its `.ts`/`.js` extension.
  *
  * A migration keeps its identity when a project switches its production image from
- * ts-node (`1699-foo.ts`) to compiled JavaScript (`1699-foo.js`) — the recommended
- * prod setup, since the image prunes ts-node. Comparing raw filenames would make
- * every compiled `.js` migration look "pending" against a state recorded under `.ts`
- * names and re-run already-applied migrations (data corruption on existing DBs).
+ * TypeScript sources (`1699-foo.ts`) to compiled JavaScript (`1699-foo.js`) — the
+ * recommended prod setup, since the image prunes the TypeScript loader's `@swc/core`.
+ * Comparing raw filenames would make every compiled `.js` migration look "pending"
+ * against a state recorded under `.ts` names and re-run already-applied migrations
+ * (data corruption on existing DBs).
  * Normalising both sides makes the transition safe with no state rewrite.
  *
  * @param title Migration title, usually the filename (e.g. `1699000000000-foo.ts`)
@@ -195,7 +198,7 @@ export class MigrationRunner {
 
       const filePath = path.join(this.options.migrationsDirectory, file);
 
-      const module = require(filePath);
+      const module = createRequire(path.join(process.cwd(), 'package.json'))(filePath);
 
       if (!module.up) {
         console.warn(`Migration ${file} has no 'up' function, skipping...`);
@@ -232,8 +235,6 @@ export class MigrationRunner {
   }
 
   protected async runUp(): Promise<void> {
-    const { _endMigration, _startMigration } = await import('./helpers/migration.helper');
-
     const allMigrations = await this.loadMigrationFiles();
     const state = await this.options.stateStore.loadAsync();
     const recorded = state.migrations || [];
@@ -308,8 +309,6 @@ export class MigrationRunner {
   }
 
   protected async runDown(): Promise<void> {
-    const { _endMigration, _startMigration } = await import('./helpers/migration.helper');
-
     const state = await this.options.stateStore.loadAsync();
     const completedMigrations = state.migrations || [];
 

package/src/core/modules/migrate/migration.helper.ts

@@ -0,0 +1,310 @@
+import * as fs from 'fs';
+import { Db, GridFSBucket, MongoClient, ObjectId } from 'mongodb';
+import * as path from 'path';
+
+import { callerDirectory } from '../../common/helpers/module-location.helper.js';
+import { MongoStateStore } from './mongo-state-store.js';
+
+/**
+ * Migration helper functions for database operations
+ */
+
+// Store active connections for auto-cleanup
+const activeConnections = new Set<MongoClient>();
+
+// Track if we're in a migration context
+let inMigrationContext = false;
+
+/**
+ * Mark the start of a migration
+ * @internal Used by migration runner
+ */
+export const _startMigration = () => {
+  inMigrationContext = true;
+};
+
+/**
+ * Mark the end of a migration and close all connections
+ * @internal Used by migration runner
+ */
+export const _endMigration = async () => {
+  inMigrationContext = false;
+  // Close all active connections
+  const promises = Array.from(activeConnections).map((client) => client.close());
+  activeConnections.clear();
+  await Promise.all(promises);
+};
+
+/**
+ * Get database connection
+ *
+ * When used in migrations, connections are automatically closed after the migration completes.
+ * For manual usage outside migrations, you must close the connection manually.
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @returns Promise with database instance
+ *
+ * @example
+ * ```typescript
+ * // In migrations - connection auto-closes after migration
+ * const db = await getDb('mongodb://localhost/mydb');
+ * await db.collection('users').updateMany(...);
+ *
+ * // Outside migrations - must close manually
+ * const db = await getDb('mongodb://localhost/mydb');
+ * try {
+ *   await db.collection('users').updateMany(...);
+ * } finally {
+ *   await db.client.close();
+ * }
+ * ```
+ */
+export const getDb = async (mongoUrl: string): Promise<Db> => {
+  const client: MongoClient = await MongoClient.connect(mongoUrl);
+
+  // Track connection for auto-cleanup in migrations
+  if (inMigrationContext) {
+    activeConnections.add(client);
+  }
+
+  return client.db();
+};
+
+/**
+ * Throw unless every chunk of a stored GridFS file is present.
+ *
+ * A GridFS upload is not one write but many: N chunk documents plus the files
+ * document that describes them. The write stream's `'finish'` event says the
+ * stream ended — it does not prove every chunk is durably there, and a
+ * connection that goes away at the wrong moment can leave a files document
+ * behind that promises more bytes than exist. The upload then "succeeds", the
+ * caller stores the id, and the defect only surfaces much later as a broken
+ * download from a record that looks perfectly healthy.
+ *
+ * Counts documents rather than reading bytes, so a chunk that was written but
+ * truncated still passes. Catching that would mean streaming the whole file
+ * back on every upload; the cheap count catches the failure that actually
+ * occurs (a missing chunk) and is index-only via the GridFS default index.
+ *
+ * @param db - Database holding the bucket
+ * @param bucketName - GridFS bucket name, i.e. the prefix of `<bucket>.files` / `<bucket>.chunks`
+ * @param id - `_id` of the files document
+ * @param label - Optional human-readable name for the error message; defaults to the id
+ * @throws Error if the files document is missing or fewer chunks are stored than its length implies
+ *
+ * @example
+ * ```typescript
+ * await assertGridFsFileComplete(db, 'images', fileId, 'logo.png');
+ * ```
+ */
+export const assertGridFsFileComplete = async (
+  db: Db,
+  bucketName: string,
+  id: ObjectId,
+  label?: string,
+): Promise<void> => {
+  const name = label || String(id);
+  const fileDoc = await db.collection(`${bucketName}.files`).findOne({ _id: id });
+  if (!fileDoc) {
+    throw new Error(`GridFS file '${name}' has no file document (id ${String(id)})`);
+  }
+
+  const chunkSize: number = fileDoc.chunkSize || 255 * 1024;
+  // NO `Math.max(1, …)` floor here: GridFS stores ZERO chunk documents for a
+  // zero-byte file — the driver's `writeRemnant()` returns early on `pos === 0`
+  // rather than inserting an empty chunk. A floor of 1 would reject every
+  // legitimately empty asset, and because the container entrypoint defaults to
+  // `MIGRATE_FAILURE_POLICY=abort`, that failure would keep the server from
+  // starting at all.
+  const expected = Math.ceil((fileDoc.length || 0) / chunkSize);
+  const actual = await db
+    .collection(`${bucketName}.chunks`)
+    // Read from the primary: this is a read-your-own-write, and a URI carrying
+    // `readPreference=secondaryPreferred` would otherwise fail a healthy upload
+    // against a secondary that has not caught up yet.
+    .countDocuments({ files_id: id }, { readPreference: 'primary' });
+  if (actual < expected) {
+    throw new Error(`GridFS file '${name}' is incomplete: ${actual} of ${expected} chunks stored (id ${String(id)})`);
+  }
+};
+
+/**
+ * The file `uploadFileToGridFS()` reads: an absolute path as given; a relative one against the calling migration's
+ * directory, or — when nothing exists there — against this helper's own directory, which is where it was resolved
+ * until 12.0.0 (a vendored project may have adapted its paths to that).
+ */
+function resolveMigrationFilePath(relativePath: string, callerDir: string): string {
+  if (!relativePath || path.isAbsolute(relativePath)) {
+    return relativePath;
+  }
+  const fromCaller = path.resolve(callerDir, relativePath);
+  if (fs.existsSync(fromCaller)) {
+    return fromCaller;
+  }
+  // Until 12.0.0 this file lived in `helpers/`, and relative paths were anchored there — keep that anchor exact.
+  const legacy = path.resolve(callerDirectory(), 'helpers', relativePath);
+  return fs.existsSync(legacy) ? legacy : fromCaller;
+}
+
+/**
+ * Upload file to GridFS
+ *
+ * Resolves only once the upload is verified complete (see
+ * {@link assertGridFsFileComplete}); rejects — rather than hanging — when the
+ * source file cannot be read. Closes its own connection either way.
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @param relativePath - Path to the file: absolute, or relative to the directory of the file that calls this
+ *   function (the migration). Until 12.0.0 a relative path was resolved against THIS helper's directory — inside
+ *   `node_modules/@lenne.tech/nest-server/…` in npm mode; that location is still tried second.
+ * @param options - Optional bucket name and filename
+ * @returns Promise with ObjectId of uploaded file
+ * @throws Error if the source cannot be read, or if the stored file is incomplete
+ *
+ * @example
+ * ```typescript
+ * const fileId = await uploadFileToGridFS(
+ *   'mongodb://localhost/mydb',
+ *   '../assets/image.png',
+ *   { bucketName: 'images', filename: 'logo.png' }
+ * );
+ * ```
+ */
+export const uploadFileToGridFS = async (
+  mongoUrl: string,
+  relativePath: string,
+  options?: { bucketName?: string; filename?: string },
+): Promise<ObjectId> => {
+  // Before the first `await`: the calling migration's frame is gone after it.
+  const sourcePath = resolveMigrationFilePath(relativePath, relativePath ? callerDirectory(1) : '');
+  if (!relativePath) {
+    throw new Error('relativePath is required');
+  }
+
+  const { bucketName, filename } = {
+    bucketName: 'fs',
+    filename: relativePath.split('/')[relativePath.split('/').length - 1],
+    ...options,
+  };
+
+  const client = await MongoClient.connect(mongoUrl);
+  // Registered unconditionally — unlike `getDb()`, which only registers inside a
+  // migration context. This client is always ours to close, so `_endMigration()`
+  // stays a backstop for the case where the upload throws before `settle()` runs.
+  activeConnections.add(client);
+
+  const db = client.db();
+  const bucket = new GridFSBucket(db, { bucketName });
+  const writeStream = bucket.openUploadStream(filename);
+
+  const readStream = fs.createReadStream(sourcePath);
+  const rs = readStream.pipe(writeStream);
+
+  /**
+   * Read errors need their own handler — `pipe()` does not forward them.
+   *
+   * An unreadable source (missing file, wrong path inside a container image)
+   * emits on the READ stream, where nothing was listening: the write stream
+   * never finished, the promise below never settled, and the migration hung
+   * until something else timed out. Destroying the write stream routes it into
+   * the rejection path so the caller sees the actual cause.
+   */
+  readStream.on('error', (err) => {
+    writeStream.destroy(err);
+  });
+
+  /**
+   * Close the connection before settling.
+   *
+   * This client used to be opened and never closed, and it was not registered
+   * either — so `_endMigration()` could not reach it. Every uploaded file left a
+   * live connection behind, and a live connection keeps an SDAM monitor timer
+   * alive, which keeps the Node event loop busy: `migrate up` finished its work,
+   * printed "All migrations completed successfully" and then never exited. That
+   * is invisible on a developer machine and blocks a CI job until its timeout.
+   *
+   * A failing `close()` must never become the error the caller sees: the reason
+   * the upload ended is what matters, and the settle path is also reached while
+   * rejecting. So the close error is logged and swallowed, and `settled` keeps a
+   * second call (success path falling into `.catch`) from closing twice.
+   */
+  let settled = false;
+  const settle = async <T>(action: () => T): Promise<T> => {
+    if (!settled) {
+      settled = true;
+      try {
+        await client.close();
+      } catch (closeErr) {
+        console.warn('Failed to close migration connection:', closeErr);
+      } finally {
+        activeConnections.delete(client);
+      }
+    }
+    return action();
+  };
+
+  return new Promise<ObjectId>((resolve, reject) => {
+    rs.on('finish', () => {
+      const id = writeStream.id as ObjectId;
+      // Verify BEFORE closing: the check needs the same open client, and a
+      // failure has to reject rather than hand back an id that points at nothing.
+      assertGridFsFileComplete(db, bucketName, id, filename)
+        .then(() => settle(() => id))
+        .then(resolve)
+        .catch((err: unknown) => {
+          // Drop the incomplete file, otherwise every re-run of the migration
+          // leaves another orphaned files document (plus its partial chunks)
+          // behind, since a retry uploads under a fresh ObjectId.
+          void bucket
+            .delete(id)
+            .catch(() => undefined)
+            .then(() => settle(() => undefined))
+            .finally(() => reject(err));
+        });
+    });
+
+    rs.on('error', (err) => {
+      void settle(() => undefined).finally(() => reject(err));
+    });
+  });
+};
+
+/**
+ * Create a migration state store factory
+ *
+ * The lock collection is set by DEFAULT, so `migrate up` from N replicas booting at
+ * the same time serializes instead of applying the same migration twice (the container
+ * entrypoint runs migrations on every boot). Pass an empty string to opt out.
+ *
+ * @param mongoUrl - MongoDB connection URI
+ * @param collectionName - Optional collection name (default: 'migrations')
+ * @param lockCollectionName - Lock collection name (default: 'migrations_lock'); `''` disables locking
+ * @returns MongoStateStore class that can be used with migrate CLI
+ *
+ * @example
+ * ```typescript
+ * // In migrations-utils/migrate.js:
+ * const { createMigrationStore } = require('@lenne.tech/nest-server');
+ * const config = require('../src/config.env');
+ *
+ * module.exports = createMigrationStore(config.default.mongoose.uri);
+ * ```
+ */
+export const createMigrationStore = (
+  mongoUrl: string,
+  collectionName: string = 'migrations',
+  lockCollectionName: string = 'migrations_lock',
+  // Explicit return type: the returned class is anonymous to the declaration emitter, and
+  // MongoStateStore has private members, so an inferred type cannot be written to the .d.ts
+  // (TS4094).
+): new () => MongoStateStore => {
+  return class MigrationStateStore extends MongoStateStore {
+    constructor() {
+      super({
+        collectionName,
+        lockCollectionName: lockCollectionName || undefined,
+        uri: mongoUrl,
+      });
+    }
+  };
+};

package/src/core/modules/migrate/templates/migration-project.template.ts

@@ -1,5 +1,7 @@
 import { getDb, uploadFileToGridFS } from '@lenne.tech/nest-server';
 import { Db, ObjectId } from 'mongodb';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
 
 /**
  * Migration template for nest-server projects
@@ -12,21 +14,36 @@ import { Db, ObjectId } from 'mongodb';
  * - uploadFileToGridFS(uri, filePath, options): Upload file to GridFS
  *
  * MongoDB URI resolution (in order):
- * 1. config.env.ts (local development via ts-node)
+ * 1. the project's config.env — next to `migrations/` when run from source (through the `--compiler ts:` loader), or
+ *    the compiled `dist/src/config.env.js` when run from `dist/migrations`
  * 2. NSC__MONGOOSE__URI environment variable (Docker production)
  */
 
-let MONGO_URL: string;
-try {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const config = require('../src/config.env');
-  MONGO_URL = (config.default || config).mongoose.uri;
-} catch {
-  // Fallback for Docker production where config.env.ts is not available as TypeScript source
-  if (!process.env.NSC__MONGOOSE__URI) {
-    throw new Error('MongoDB URI not available. Set NSC__MONGOOSE__URI or ensure config.env.ts is loadable.');
+// `createRequire` rather than `require`, so the migration works in CommonJS and ESM projects alike. `__dirname` exists
+// in a CommonJS project only and finds config.env relative to this file — in the source tree and in `dist/` alike. An ES
+// module project has no `__dirname` here; it falls back to the directory the migrate scripts run from.
+const projectRequire = createRequire(join(process.cwd(), 'package.json'));
+const configCandidates = [
+  ...(typeof __dirname === 'string' ? [join(__dirname, '..', 'src', 'config.env')] : []),
+  join(process.cwd(), 'src', 'config.env'),
+  join(process.cwd(), 'dist', 'src', 'config.env'),
+];
+
+let configuredUri: string | undefined;
+for (const candidate of configCandidates) {
+  try {
+    const config = projectRequire(candidate);
+    configuredUri = (config.default || config).mongoose?.uri;
+  } catch {
+    // Not loadable in this layout — try the next one.
+  }
+  if (configuredUri) {
+    break;
   }
-  MONGO_URL = process.env.NSC__MONGOOSE__URI;
+}
+const MONGO_URL = configuredUri ?? process.env.NSC__MONGOOSE__URI;
+if (!MONGO_URL) {
+  throw new Error('MongoDB URI not available. Set NSC__MONGOOSE__URI or ensure config.env is loadable.');
 }
 
 /**
@@ -46,7 +63,7 @@ export const up = async () => {
   // Example: Upload a file to GridFS
   // const fileId: ObjectId = await uploadFileToGridFS(
   //   MONGO_URL,
-  //   '../assets/image.png',
+  //   '../assets/image.png', // relative to this migration file
   //   { bucketName: 'images', filename: 'logo.png' }
   // );
 };

package/src/core/modules/permissions/core-permissions.controller.ts

@@ -1,7 +1,7 @@
 import { Controller, Get, Header, Headers, Post } from '@nestjs/common';
 
-import { CorePermissionsService } from './core-permissions.service';
-import type { PermissionsReport } from './interfaces/permissions.interface';
+import { CorePermissionsService } from './core-permissions.service.js';
+import type { PermissionsReport } from './interfaces/permissions.interface.js';
 
 @Controller()
 export class CorePermissionsController {

package/src/core/modules/permissions/core-permissions.module.ts

@@ -1,11 +1,11 @@
 import { DynamicModule, Module } from '@nestjs/common';
 import { PATH_METADATA } from '@nestjs/common/constants';
 
-import { RoleEnum } from '../../common/enums/role.enum';
+import { RoleEnum } from '../../common/enums/role.enum.js';
 
-import { CorePermissionsController } from './core-permissions.controller';
-import { CorePermissionsService } from './core-permissions.service';
-import type { IPermissions } from './interfaces/permissions.interface';
+import { CorePermissionsController } from './core-permissions.controller.js';
+import { CorePermissionsService } from './core-permissions.service.js';
+import type { IPermissions } from './interfaces/permissions.interface.js';
 
 @Module({})
 export class CorePermissionsModule {