@lenne.tech/nest-server 11.43.3 → 12.0.0

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

@@ -1,25 +1,25 @@
-export * from './core-hub-actions.controller';
-export * from './core-hub-html.service';
-export * from './core-hub.controller';
-export * from './core-hub.module';
-export * from './core-hub.service';
-export * from './services/core-hub-actions.service';
-export * from './services/core-hub-db.service';
-export * from './services/core-hub-email.service';
-export * from './services/core-hub-mailbox.service';
-export * from './services/core-hub-migrations.service';
-export * from './services/core-hub-sources.service';
-export * from './services/hub-log-buffer.service';
-export * from './services/hub-query-profiler.service';
-export * from './services/hub-trace-buffer.service';
-export * from './middleware/hub-trace.middleware';
-export * from './helpers/hub-command-shape.helper';
-export * from './helpers/hub-mask.helper';
-export * from './helpers/hub-mermaid.helper';
-export * from './helpers/hub-shell.helper';
-export * from './hub-config.helper';
-export * from './hub-nav';
-export * from './hub-ring-buffer';
-export * from './hub.constants';
-export * from './interfaces/hub-config.interface';
-export * from './interfaces/hub-panels.interface';
+export * from './core-hub-actions.controller.js';
+export * from './core-hub-html.service.js';
+export * from './core-hub.controller.js';
+export * from './core-hub.module.js';
+export * from './core-hub.service.js';
+export * from './services/core-hub-actions.service.js';
+export * from './services/core-hub-db.service.js';
+export * from './services/core-hub-email.service.js';
+export * from './services/core-hub-mailbox.service.js';
+export * from './services/core-hub-migrations.service.js';
+export * from './services/core-hub-sources.service.js';
+export * from './services/hub-log-buffer.service.js';
+export * from './services/hub-query-profiler.service.js';
+export * from './services/hub-trace-buffer.service.js';
+export * from './middleware/hub-trace.middleware.js';
+export * from './helpers/hub-command-shape.helper.js';
+export * from './helpers/hub-mask.helper.js';
+export * from './helpers/hub-mermaid.helper.js';
+export * from './helpers/hub-shell.helper.js';
+export * from './hub-config.helper.js';
+export * from './hub-nav.js';
+export * from './hub-ring-buffer.js';
+export * from './hub.constants.js';
+export * from './interfaces/hub-config.interface.js';
+export * from './interfaces/hub-panels.interface.js';

package/src/core/modules/hub/middleware/hub-trace.middleware.ts

@@ -1,7 +1,7 @@
 import { Injectable, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
-import { HubTraceBufferService } from '../services/hub-trace-buffer.service';
+import { HubTraceBufferService } from '../services/hub-trace-buffer.service.js';
 
 /**
  * Measures request duration and records a trace at response completion.

package/src/core/modules/hub/services/core-hub-actions.service.ts

@@ -1,17 +1,17 @@
 import { Injectable, Logger, Optional } from '@nestjs/common';
 
-import { EmailService } from '../../../common/services/email.service';
-import { RequestContext } from '../../../common/services/request-context.service';
-import { HubActionMessage } from '../hub-action-messages';
-import { HubFileStore } from '../interfaces/hub-panels.interface';
-import { CoreHubDbService } from './core-hub-db.service';
-import { CoreHubEmailService } from './core-hub-email.service';
-import { CoreHubMailboxService } from './core-hub-mailbox.service';
-import { CoreHubMigrationsService } from './core-hub-migrations.service';
-import { CoreHubSourcesService } from './core-hub-sources.service';
-import { HubLogBufferService } from './hub-log-buffer.service';
-import { HubQueryProfilerService } from './hub-query-profiler.service';
-import { HubTraceBufferService } from './hub-trace-buffer.service';
+import { EmailService } from '../../../common/services/email.service.js';
+import { RequestContext } from '../../../common/services/request-context.service.js';
+import { HubActionMessage } from '../hub-action-messages.js';
+import { HubFileStore } from '../interfaces/hub-panels.interface.js';
+import { CoreHubDbService } from './core-hub-db.service.js';
+import { CoreHubEmailService } from './core-hub-email.service.js';
+import { CoreHubMailboxService } from './core-hub-mailbox.service.js';
+import { CoreHubMigrationsService } from './core-hub-migrations.service.js';
+import { CoreHubSourcesService } from './core-hub-sources.service.js';
+import { HubLogBufferService } from './hub-log-buffer.service.js';
+import { HubQueryProfilerService } from './hub-query-profiler.service.js';
+import { HubTraceBufferService } from './hub-trace-buffer.service.js';
 
 /** Illustrative sample data for the test-mail action. */
 const TEST_MAIL_DATA = {

package/src/core/modules/hub/services/core-hub-db.service.ts

@@ -1,20 +1,20 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import * as mongo from 'mongodb';
-import { Connection, Types } from 'mongoose';
+import { type Connection, Types } from 'mongoose';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { CoreS3Service } from '../../../common/services/core-s3.service';
-import { ModelRegistry } from '../../../common/services/model-registry.service';
+import { ConfigService } from '../../../common/services/config.service.js';
+import { CoreS3Service } from '../../../common/services/core-s3.service.js';
+import { ModelRegistry } from '../../../common/services/model-registry.service.js';
 import {
   DEFAULT_FILESYSTEM_DIR,
   FILESYSTEM_FILES_COLLECTION,
   FilesystemFileHelper,
-} from '../../file/filesystem-file.helper';
-import { S3_FILES_COLLECTION, S3FileHelper } from '../../file/s3-file.helper';
-import { HubActionMessage } from '../hub-action-messages';
-import { HUB_CONFIG } from '../hub.constants';
-import { buildErDiagram, HubModelDescriptor, HubModelField } from '../helpers/hub-mermaid.helper';
+} from '../../file/filesystem-file.helper.js';
+import { S3_FILES_COLLECTION, S3FileHelper } from '../../file/s3-file.helper.js';
+import { HubActionMessage } from '../hub-action-messages.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { buildErDiagram, HubModelDescriptor, HubModelField } from '../helpers/hub-mermaid.helper.js';
 import {
   HubDbData,
   HubFilesData,
@@ -22,8 +22,8 @@ import {
   HubFileStoreSummary,
   HubModelsData,
   HubUnavailable,
-} from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+} from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 /**
  * Read-only MongoDB introspection for the DB, Models/ERD and Files panels.

package/src/core/modules/hub/services/core-hub-email.service.ts

@@ -2,11 +2,12 @@ import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { existsSync, readdirSync } from 'fs';
 import { join, resolve } from 'path';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { TemplateService } from '../../../common/services/template.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubEmailsData, HubUnavailable } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { ConfigService } from '../../../common/services/config.service.js';
+import { TemplateService } from '../../../common/services/template.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubEmailsData, HubUnavailable } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
+import { callerDirectory } from '../../../common/helpers/module-location.helper.js';
 
 /** Sample data used to render an email template preview. Values are illustrative, never real user data. */
 const SAMPLE_PAYLOAD: Record<string, unknown> = {
@@ -118,7 +119,7 @@ export class CoreHubEmailService {
 
   protected frameworkTemplatesDir(): string {
     // From src/core/modules/hub/services → src/templates (same relative offset in dist/).
-    return resolve(__dirname, '../../../../templates');
+    return resolve(callerDirectory(), '../../../../templates');
   }
 
   protected listEjs(dir: string): string[] {

package/src/core/modules/hub/services/core-hub-mailbox.service.ts

@@ -1,11 +1,11 @@
 import { Inject, Injectable, Optional } from '@nestjs/common';
 
-import { redactSensitiveText } from '../../../common/helpers/logging.helper';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { HubMailboxData, HubMailboxEntry } from '../interfaces/hub-panels.interface';
-import { IHubCapturedMailInput, IHubEmailCapture, ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { HubMailboxData, HubMailboxEntry } from '../interfaces/hub-panels.interface.js';
+import { IHubCapturedMailInput, IHubEmailCapture, type ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 /** A captured mail: the list metadata plus the (truncated) bodies kept for the preview iframe. */
 interface StoredMail extends HubMailboxEntry {

package/src/core/modules/hub/services/core-hub-migrations.service.ts

@@ -1,16 +1,16 @@
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
 import { readdir } from 'fs/promises';
-import { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 import { resolve } from 'path';
 
-import { ConfigService } from '../../../common/services/config.service';
-import { DEFAULT_MIGRATION_FILE_PATTERN, MigrationRunner } from '../../migrate/migration-runner';
-import { MongoStateStore } from '../../migrate/mongo-state-store';
-import { HubActionMessage } from '../hub-action-messages';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubMigrationsData, HubUnavailable } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { ConfigService } from '../../../common/services/config.service.js';
+import { DEFAULT_MIGRATION_FILE_PATTERN, MigrationRunner } from '../../migrate/migration-runner.js';
+import { MongoStateStore } from '../../migrate/mongo-state-store.js';
+import { HubActionMessage } from '../hub-action-messages.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubMigrationsData, HubUnavailable } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 /**
  * Reads migration status for the Migrations panel.

package/src/core/modules/hub/services/core-hub-sources.service.ts

@@ -2,11 +2,11 @@ import { Injectable, Logger, Optional } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import { SchedulerRegistry } from '@nestjs/schedule';
 
-import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.service';
-import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper';
-import { CoreErrorCodeService } from '../../error-code/core-error-code.service';
-import { CorePermissionsService } from '../../permissions/core-permissions.service';
-import { HubCronData, HubErrorCodesData, HubUnavailable } from '../interfaces/hub-panels.interface';
+import { CoreAiInteractionService } from '../../ai/services/core-ai-interaction.service.js';
+import { CoreBetterAuthUserMapper } from '../../better-auth/core-better-auth-user.mapper.js';
+import { CoreErrorCodeService } from '../../error-code/core-error-code.service.js';
+import { CorePermissionsService } from '../../permissions/core-permissions.service.js';
+import { HubCronData, HubErrorCodesData, HubUnavailable } from '../interfaces/hub-panels.interface.js';
 
 /**
  * Single choke point for the Hub's OPTIONAL data sources.
@@ -124,7 +124,13 @@ export class CoreHubSourcesService {
     if (action === 'start') {
       job.start();
     } else if (action === 'stop') {
-      job.stop();
+      // With `waitForCompletion`, cron's stop() returns a promise that waits for the running tick and `onComplete`;
+      // a rejection from either must not become an unhandled one.
+      job.stop()?.catch((error: unknown) => {
+        this.logger.warn(
+          `Cron job "${name}" failed while stopping: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      });
     } else {
       // Fire the job's callback once now.
       const fire = (job as unknown as { fireOnTick?: () => void }).fireOnTick;

package/src/core/modules/hub/services/hub-log-buffer.service.ts

@@ -11,12 +11,12 @@ import {
 } from '@nestjs/common';
 import { inspect } from 'util';
 
-import { redactSensitiveText } from '../../../common/helpers/logging.helper';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { HubLogRecord, HubLogsData } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface BufferedLog extends HubLogRecord {
   timestamp: number;

package/src/core/modules/hub/services/hub-query-profiler.service.ts

@@ -1,14 +1,14 @@
 import { Inject, Injectable, Logger, OnModuleDestroy, OnModuleInit, Optional } from '@nestjs/common';
 import { InjectConnection } from '@nestjs/mongoose';
-import { Connection } from 'mongoose';
+import type { Connection } from 'mongoose';
 
-import { redactSensitiveText } from '../../../common/helpers/logging.helper';
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { normalizeCommandShape } from '../helpers/hub-command-shape.helper';
-import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { redactSensitiveText } from '../../../common/helpers/logging.helper.js';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG, HUB_QUERY_PENDING_LIMIT } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { normalizeCommandShape } from '../helpers/hub-command-shape.helper.js';
+import { HubQueriesData, HubQueryRecord, HubQueryTemplate } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface ProfilerRecord extends HubQueryRecord {
   timestamp: number;

package/src/core/modules/hub/services/hub-trace-buffer.service.ts

@@ -1,11 +1,11 @@
 import { Inject, Injectable, Optional } from '@nestjs/common';
 import { Request, Response } from 'express';
 
-import { CoreRedisService } from '../../../common/services/core-redis.service';
-import { HUB_CONFIG } from '../hub.constants';
-import { HubBuffer } from '../hub-buffer';
-import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface';
-import { ResolvedHubConfig } from '../interfaces/hub-config.interface';
+import { CoreRedisService } from '../../../common/services/core-redis.service.js';
+import { HUB_CONFIG } from '../hub.constants.js';
+import { HubBuffer } from '../hub-buffer.js';
+import { HubTraceRecord, HubTracesData } from '../interfaces/hub-panels.interface.js';
+import type { ResolvedHubConfig } from '../interfaces/hub-config.interface.js';
 
 interface TraceRecord extends HubTraceRecord {
   timestamp: number;

package/src/core/modules/migrate/MIGRATION_FROM_NODEPIT.md

@@ -266,7 +266,7 @@ export const down = async () => {
 If issues occur during migration:
 
 - Check that `@lenne.tech/nest-server` is at version 11.3.0 or higher
-- Verify `ts-node` is installed as devDependency
+- Verify `@swc/core` is installed as devDependency (the `--compiler ts:…` loader needs it since 12.0.0)
 - Ensure `migrations-utils/migrate.js` exports the state store correctly
 - Test with `migrate --help` to verify CLI is available
 - Remember: Command must come FIRST in CLI syntax

package/src/core/modules/migrate/README.md

@@ -417,8 +417,10 @@ const fileId = await uploadFileToGridFS('mongodb://localhost/mydb', '../assets/i
 });
 ```
 
-`relativePath` is resolved against the **helper module's** directory, not the migration file's — the
-paths in this example and in the migration template are written accordingly.
+Since 12.0.0 a relative `relativePath` is resolved against the directory of the **migration** that calls the
+helper (`../assets/image.png` above: an `assets` folder next to `migrations/`). Until then it was resolved against the
+helper module's own directory — inside `node_modules/@lenne.tech/nest-server/dist` in npm mode; that location is still
+tried when the file does not exist next to the migration, so paths written for it keep working.
 
 The returned promise settles only after three guarantees hold:
 
@@ -460,14 +462,34 @@ Ready-to-use template for nest-server projects:
 
 This template automatically imports `getDb()` and `uploadFileToGridFS()` from nest-server, along with your project's config. It's ready to use with zero configuration.
 
-### TypeScript Compiler
+**Vendor mode (12.0.0+):** a project with the core vendored into `src/core/` has no `@lenne.tech/nest-server` package, so
+`migrate create` rewrites the template's `'@lenne.tech/nest-server'` import to the relative path from the migrations
+directory to the vendored core (e.g. `'../src/core'`). It does so only when the package does not resolve from the
+project and the core it runs from has its own `index`; in npm mode the template is written unchanged.
 
-Pre-configured TypeScript compiler for migrate CLI:
+### TypeScript Loader
+
+`helpers/ts-compiler.js` lets the migrate CLI load TypeScript migrations and `config.env.ts`:
 
 ```bash
-migrate --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
+migrate up --compiler="ts:./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js"
 ```
 
+Since 12.0.0 it compiles `.ts` / `.cts` / `.mts` with **SWC** (`@swc/core`) instead of ts-node. It strips types and
+lowers decorators with the options of the `tsc` build (target `es2022`, legacy decorators with metadata, define
+semantics for class fields), and type-checks nothing — `tsc` and the IDE do that. It needs `@swc/core` in the project
+(`pnpm add -D @swc/core`; starter-based projects have it), resolved from the working directory. The same file runs
+the dev server from source: `node -r <path>/ts-compiler.js src/main.ts`.
+
+It covers both module systems: a `require` hook for CommonJS, and Node module hooks (`ts-compiler-hooks.mjs`,
+registered on load) for ES modules — an ESM project's entry and everything it imports. Both map a `./x.js` specifier to
+`./x.ts` when only the source exists. The implementation is `ts-compiler.cjs`; `ts-compiler.js` is the established
+entry path and forwards to it. `helpers/package.json` declares `"type": "commonjs"`, so that path works in CommonJS and
+ESM projects, in npm and vendor mode.
+
+Production images do not use it: migrations are compiled with the build and run as `.js` (see
+[Extension-agnostic identity](#extension-agnostic-identity-safe-source--compiled-js-transition)).
+
 ## Complete Setup Guide
 
 For a complete step-by-step guide on migrating from @nodepit/migrate-state-store-mongodb, see [MIGRATION_FROM_NODEPIT.md](./MIGRATION_FROM_NODEPIT.md).
@@ -476,7 +498,9 @@ For a complete step-by-step guide on migrating from @nodepit/migrate-state-store
 
 **No need to install the `migrate` package!** nest-server now includes a built-in migration CLI.
 
-1. Install ts-node (dev dependency): `npm install --save-dev ts-node`
+1. Make sure `@swc/core` is a dev dependency (`pnpm add -D @swc/core`) — the `--compiler ts:…` loader
+   below compiles TypeScript migrations with it (since 12.0.0; ts-node before, see
+   [TypeScript Loader](#typescript-loader))
 2. Create `migrations-utils/migrate.js` using `createMigrationStore()`
 3. Add migration scripts to your `package.json`
 4. Run migrations using the built-in CLI
@@ -499,14 +523,14 @@ See the [Migration Guide](./MIGRATION_FROM_NODEPIT.md) for detailed migration in
 
 ## Migration Identity & Strict Mode
 
-### Extension-agnostic identity (safe ts-node → compiled-JS transition)
+### Extension-agnostic identity (safe source → compiled-JS transition)
 
 A migration's identity is its timestamped file stem **without** the `.ts`/`.js` extension
 (`migrationId('1699-foo.ts') === migrationId('1699-foo.js') === '1699-foo'`). `up`, `down`,
 and `list`/`status` all compare identities, not raw filenames.
 
 This makes the recommended production setup — running compiled `.js` migrations in the image
-while the state was recorded under `.ts` names via ts-node — safe: already-applied migrations
+while the state was recorded under `.ts` names by source runs — safe: already-applied migrations
 are **not** re-run after the switch, and no state rewrite is needed. If both `foo.ts` and
 `foo.js` are present in the migrations directory (e.g. an overlapping `outDir`), they count
 as ONE migration: only the `.js` file is loaded and executed, and a warning is emitted.

package/src/core/modules/migrate/cli/migrate-cli.ts

@@ -24,8 +24,18 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MigrationRunner, parseStrictEnv } from '../migration-runner';
-import { MongoStateStore } from '../mongo-state-store';
+import { MigrationRunner, parseStrictEnv } from '../migration-runner.js';
+import { MongoStateStore } from '../mongo-state-store.js';
+import { createRequire } from 'node:module';
+import { callerDirectory } from '../../../common/helpers/module-location.helper.js';
+
+/**
+ * Loads a file the CLI was pointed at (store, `--compiler`) by absolute path. `createRequire` instead of `require`:
+ * the core's source is valid as CommonJS and as ESM, and only the former has a `require` in scope.
+ */
+function requireFromProject(absolutePath: string): any {
+  return createRequire(path.join(process.cwd(), 'package.json'))(absolutePath);
+}
 
 interface CliOptions {
   compiler?: string;
@@ -35,10 +45,59 @@ interface CliOptions {
   templateFile?: string;
 }
 
+const FRAMEWORK_PACKAGE = '@lenne.tech/nest-server';
+
+/**
+ * The import specifier a migration created in `migrationsDir` must use for the framework's helpers.
+ *
+ * The shipped template imports `getDb` / `uploadFileToGridFS` from `@lenne.tech/nest-server`. A
+ * vendor-mode project has no such package — its core lives in `src/core/` — so a migration created
+ * from the unchanged template fails with TS2307 in the IDE and `tsc`, and with MODULE_NOT_FOUND at run time.
+ * Returns the relative path from the migrations directory to the vendored core when the package does
+ * not resolve from `cwd` AND this CLI runs from a vendored core (one with its own `index` next to
+ * `modules/`, as the vendor flatten-fix leaves it); otherwise `undefined`, i.e. keep the package name.
+ * In npm mode the package resolves, and in this framework repo `src/core/` has no `index`, so neither
+ * is rewritten.
+ *
+ * @param migrationsDir - Directory the migration is written to, absolute or relative to `cwd`
+ * @param cwd - Project directory the package is resolved from
+ * @param coreRoot - Root of the core this CLI belongs to
+ */
+export function vendoredFrameworkSpecifier(
+  migrationsDir: string,
+  cwd: string = process.cwd(),
+  coreRoot: string = path.resolve(callerDirectory(), '..', '..', '..'),
+): string | undefined {
+  try {
+    createRequire(path.join(cwd, 'package.json')).resolve(FRAMEWORK_PACKAGE);
+    return undefined;
+  } catch {
+    // Not installed — the vendor-mode case, if the core below has an entry point of its own.
+  }
+  if (!['index.ts', 'index.js'].some((entry) => fs.existsSync(path.join(coreRoot, entry)))) {
+    return undefined;
+  }
+  const relativePath = path.relative(path.resolve(cwd, migrationsDir), coreRoot).split(path.sep).join('/');
+  return relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+}
+
+/**
+ * Replaces the exact `@lenne.tech/nest-server` specifier (`from '…'`, `require('…')`, single or double
+ * quotes) in a migration template. Subpaths of the package are left alone.
+ */
+export function rewriteFrameworkSpecifier(template: string, specifier: string): string {
+  return template.replace(
+    /(['"])@lenne\.tech\/nest-server\1/g,
+    (_match, quote: string) => `${quote}${specifier}${quote}`,
+  );
+}
+
 /**
  * Create a new migration file
+ *
+ * @param coreRoot - Root of the core this CLI belongs to; defaults to the one it runs from (tests only)
  */
-async function createMigration(name: string, options: CliOptions) {
+async function createMigration(name: string, options: CliOptions, coreRoot?: string) {
   if (!name) {
     console.error('Error: Migration name is required');
     console.log('Usage: migrate create <name> [options]');
@@ -60,6 +119,10 @@ async function createMigration(name: string, options: CliOptions) {
   if (options.templateFile) {
     const templatePath = path.resolve(process.cwd(), options.templateFile);
     template = fs.readFileSync(templatePath, 'utf-8');
+    const specifier = vendoredFrameworkSpecifier(options.migrationsDir, process.cwd(), coreRoot);
+    if (specifier) {
+      template = rewriteFrameworkSpecifier(template, specifier);
+    }
   } else {
     // Default template
     template = `/**
@@ -141,7 +204,7 @@ function loadStateStore(storePath: string | undefined): MongoStateStore {
 
   const absolutePath = path.resolve(process.cwd(), storePath);
 
-  const StoreClass = require(absolutePath);
+  const StoreClass = requireFromProject(absolutePath);
 
   // Handle different export patterns
   if (StoreClass.default) {
@@ -255,7 +318,7 @@ function registerCompiler(compiler: string | undefined) {
   if (type === 'ts' && compilerPath) {
     const absolutePath = path.resolve(process.cwd(), compilerPath);
 
-    const register = require(absolutePath);
+    const register = requireFromProject(absolutePath);
     if (typeof register === 'function') {
       register();
     }
@@ -395,9 +458,10 @@ const runCli = async (): Promise<void> => {
 
 // Run CLI if executed directly (`node migrate-cli.js`). The bin shim calls
 // runCli() itself, so this only covers a direct invocation of the compiled file.
-if (require.main === module) {
+// `typeof` first: as ESM neither `require` nor `module` exists, and reading them would throw at load time.
+if (typeof require !== 'undefined' && typeof module !== 'undefined' && require.main === module) {
   void runCli();
 }
 
 // parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
-export { flushAndExit, main, parseArgs, runCli };
+export { createMigration, flushAndExit, main, parseArgs, runCli };