@lenne.tech/nest-server 11.31.0 → 11.31.2

package/migration-guides/11.31.0-to-11.31.1.md

@@ -0,0 +1,89 @@
+# Migration Guide: 11.31.0 → 11.31.1
+
+> Note: written on the feature branch (`feature/migrate-safe-ts-js-transition`).
+> If the release lands under a different version number, rename this file accordingly.
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Extension-agnostic migration identity (safe ts-node → compiled-JS transition); strict integrity mode (`--strict` / `NSC__MIGRATE__STRICT` / `MigrationRunnerOptions.strict`); `status()` reports `missing` files; `migrate list` annotates missing files |
+| **Bugfixes** | Co-present `foo.ts` + `foo.js` no longer execute twice in one `up()` run (deduplicated by identity, `.js` wins) |
+| **Migration Effort** | None — no code changes required. Optional: enable strict mode in production images |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.31.1
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+No code changes required in any project.
+
+---
+
+## What's New in 11.31.1
+
+### Extension-agnostic migration identity (safe ts-node → compiled-JS transition)
+
+`migrate up`, `migrate down`, and `migrate list` now compare migrations by their
+timestamped file stem WITHOUT the `.ts`/`.js` extension. A migration recorded as
+`1699-foo.ts` (run via ts-node) matches the compiled `1699-foo.js` in a production
+image — already-applied migrations are no longer treated as "pending" and re-run
+after switching the image to compiled JavaScript. No state rewrite is needed;
+existing databases keep working as-is.
+
+If both `foo.ts` and `foo.js` are present in the migrations directory (e.g. an
+overlapping `outDir`), they now count as ONE migration: only the `.js` file is
+loaded and executed, with a warning. Previously both files would have executed.
+
+Note: the legacy `synchronizedUp()` helper drives the external `migrate` package's
+own state handling and keeps raw-filename identity — the new semantics apply to the
+`MigrationRunner`/built-in CLI path only.
+
+### Missing migration files tolerated by default (up/list)
+
+Old, already-applied migration files can be deleted (they live in git and can be
+restored). `migrate up` no longer needs their files to be present:
+
+- Default: `up` warns (`[migrate] N recorded migration file(s) missing — tolerated`) and continues, so the server still boots. Previously such entries were silently ignored — log-scraping setups will see a NEW warning.
+- `migrate list` marks affected entries with `(file missing)` and `status()` additionally returns them in a new `missing: string[]` field (additive, backward compatible).
+- `migrate down` ALWAYS fails hard when the rollback file is missing — unchanged from 11.31.0, with a clearer message (`… restore the file from git to roll back.`). Rollback is an explicit operator action, never a boot path.
+
+### Strict integrity mode (opt-in)
+
+Turn the tolerated drift into a hard error (`up` throws, `list` exits non-zero):
+
+| Activation path | Scope |
+|-----------------|-------|
+| `--strict` CLI flag | single invocation |
+| `NSC__MIGRATE__STRICT=1\|true\|yes` env var (case-insensitive) | CLI **and** programmatic `MigrationRunner` instances |
+| `new MigrationRunner({ strict: true, ... })` | programmatic |
+
+**Recommended for production images:** set `NSC__MIGRATE__STRICT=true`. In an
+immutable image, a recorded-but-missing migration file can only mean a broken build
+or a state-store mismatch — refusing to boot is the correct reaction there.
+
+---
+
+## Compatibility Notes
+
+- `status()` return type gained a `missing: string[]` field. Code that destructures
+  only `completed`/`pending` continues to work unchanged.
+- **Vendor mode:** `src/core/modules/migrate/migration-runner.ts` and
+  `src/core/modules/migrate/cli/migrate-cli.ts` are an atomic pair — sync BOTH
+  files together (the CLI passes `strict` into the runner's options interface and
+  imports `parseStrictEnv` from the runner).
+
+## Module Documentation
+
+- [Migrate module README](../src/core/modules/migrate/README.md) — see "Migration Identity & Strict Mode"

package/migration-guides/11.31.1-to-11.31.2.md

@@ -0,0 +1,127 @@
+# Migration Guide: 11.31.1 → 11.31.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None (one behavior change for admins — see below) |
+| **New Features** | Admin cross-user conversation listing (`?all=true`), creator attribution (`createdByUser`) |
+| **Bugfixes** | Non-admins can list their own AI conversations again (was HTTP 403 / GraphQL "Access denied") |
+| **Migration Effort** | None for most projects — no code changes required |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm update @lenne.tech/nest-server@11.31.2
+
+# Verify
+pnpm run build && pnpm test
+```
+
+No configuration changes are required. Everything below is automatic (the
+bugfix) or opt-in (the two new features).
+
+---
+
+## What's New in 11.31.2
+
+### 1. Non-admins can list their own AI conversations again (bugfix)
+
+`GET /ai/conversations` and the GraphQL `findAiConversations` query returned
+`403` / "Access denied" for every non-admin user, so their own conversations
+never loaded. The list endpoints passed the per-document roles
+`[ADMIN, S_CREATOR, S_SELF]`, which a LIST operation can never satisfy (there is
+no single object to check ownership against), so non-admins were rejected before
+ownership scoping ran.
+
+Both endpoints now authorize the list with `S_USER` and scope the result to the
+caller via a server-side `createdBy` filter plus the model's `securityCheck`.
+Cross-user isolation is unchanged — a non-admin still only ever sees their own
+conversations. **No action required**; it simply works after the update.
+
+### 2. Admins can opt in to a cross-user view (`?all=true`)
+
+By default every user — **admins included** — now receives only their own
+conversations. An admin can list every user's conversations on demand:
+
+```bash
+# REST
+GET /ai/conversations?all=true
+```
+
+```graphql
+# GraphQL
+query { findAiConversations(all: true) { id title createdBy createdByUser } }
+```
+
+The flag is ignored for non-admins, so it can never widen a regular user's
+scope. Results are ordered newest-first.
+
+### 3. Creator attribution in the admin cross-user view (`createdByUser`)
+
+In the admin cross-user view (`all: true`) each conversation additionally
+carries a resolved `createdByUser` object so the list is attributable to a named
+user:
+
+```jsonc
+{
+  "id": "…",
+  "title": "…",
+  "createdBy": "665f…",                // owner user id (always present)
+  "createdByUser": {                    // only in the admin all-view
+    "id": "665f…",
+    "email": "user@example.com",
+    "firstName": "…",
+    "lastName": "…",
+    "username": "…"
+  }
+}
+```
+
+On a normal own-only fetch `createdByUser` is left unset (the owner is the
+caller, so no lookup is needed).
+
+---
+
+## Behavior Change (admins only)
+
+Before 11.31.2, `GET /ai/conversations` returned **all** users' conversations
+for an admin by default. It now returns the **admin's own** conversations by
+default, matching every other role. If your admin UI relied on the unscoped
+list, request the cross-user view explicitly with `?all=true` (REST) or
+`all: true` (GraphQL). Non-admin behavior is unchanged.
+
+---
+
+## Compatibility Notes
+
+- `getConversation` / `deleteConversation` (single-object operations) are
+  unchanged — they still use `[ADMIN, S_CREATOR, S_SELF]`, which is correct
+  because a single loaded object exists to check ownership against.
+- Projects that extend `CoreAiConversationService` and override its constructor
+  must forward the new `@InjectConnection()` parameter to `super(...)` (used to
+  resolve creators for the admin view). Projects that do not subclass the
+  service are unaffected.
+
+---
+
+## Module Documentation
+
+### AI Module
+
+- **README:** [src/core/modules/ai/README.md](../src/core/modules/ai/README.md)
+- **Integration Checklist:** [src/core/modules/ai/INTEGRATION-CHECKLIST.md](../src/core/modules/ai/INTEGRATION-CHECKLIST.md)
+- **Reference Implementation:** `src/server/modules/ai/`
+- **Key Files:**
+  - `core-ai.controller.ts` / `core-ai.resolver.ts` — list endpoints delegate to the shared service method
+  - `services/core-ai-conversation.service.ts` — `findForCurrentUser()` (shared owner-scoped list + admin all-scope + creator attribution)
+  - `models/core-ai-conversation.model.ts` — `createdByUser` field, ownership `securityCheck`
+
+---
+
+## References
+
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.31.0",
+  "version": "11.31.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",

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

@@ -1,4 +1,4 @@
-import { Body, Controller, Delete, Get, Param, Post, Put, Res } from '@nestjs/common';
+import { Body, Controller, Delete, Get, Param, Post, Put, Query, Res } from '@nestjs/common';
 import { Response } from 'express';
 
 import { RESTServiceOptions } from '../../common/decorators/rest-service-options.decorator';
@@ -266,7 +266,9 @@ export class CoreAiController {
   }
 
   /**
-   * Find the current user's AI conversations (admins see all).
+   * Find the current user's AI conversations (own only by default). An admin may
+   * pass `?all=true` to list every user's conversations; each result carries its
+   * `createdBy` owner id for attribution. The flag is ignored for non-admins.
    *
    * The `messages` subdocument array is excluded from the list result — clients
    * fetching the conversation detail via `getConversation` get the full message
@@ -274,13 +276,14 @@ export class CoreAiController {
    */
   @Get('conversations')
   @Roles(RoleEnum.S_USER)
-  async findConversations(@RESTServiceOptions() serviceOptions: ServiceOptions): Promise<CoreAiConversation[]> {
-    const currentUser = serviceOptions?.currentUser;
-    const filterQuery = currentUser?.roles?.includes(RoleEnum.ADMIN) ? {} : { createdBy: currentUser?.id };
-    return this.conversationService.find(
-      { filterQuery },
-      { ...serviceOptions, roles: [RoleEnum.ADMIN, RoleEnum.S_CREATOR, RoleEnum.S_SELF], select: '-messages' },
-    );
+  async findConversations(
+    @RESTServiceOptions() serviceOptions: ServiceOptions,
+    @Query('all') all?: string,
+  ): Promise<CoreAiConversation[]> {
+    // Owner-scoped list shared with the GraphQL resolver — see
+    // CoreAiConversationService.findForCurrentUser for the role/ownership rationale.
+    // Admins default to their own conversations and opt in to the cross-user view via ?all=true.
+    return this.conversationService.findForCurrentUser(serviceOptions, { all: all === 'true' });
   }
 
   /**

package/src/core/modules/ai/core-ai.resolver.ts

@@ -270,21 +270,26 @@ export class CoreAiResolver {
   }
 
   /**
-   * Find the current user's AI conversations (admins see all).
+   * Find the current user's AI conversations (own only by default). An admin may
+   * pass `all: true` to list every user's conversations; each result carries its
+   * `createdBy` owner id for attribution. The argument is ignored for non-admins.
    *
    * The `messages` subdocument array is excluded from the list result — clients
    * fetching the conversation detail via `getAiConversation` get the full message
    * history. List payloads stay small even for users with many long conversations.
    */
-  @Query(() => [CoreAiConversation], { description: 'Find AI conversations of the current user' })
+  @Query(() => [CoreAiConversation], {
+    description: "Find AI conversations of the current user (admins may pass all: true to see every user's)",
+  })
   @Roles(RoleEnum.S_USER)
-  async findAiConversations(@GraphQLServiceOptions() serviceOptions: ServiceOptions): Promise<CoreAiConversation[]> {
-    const currentUser = serviceOptions?.currentUser;
-    const filterQuery = currentUser?.roles?.includes(RoleEnum.ADMIN) ? {} : { createdBy: currentUser?.id };
-    return this.conversationService.find(
-      { filterQuery },
-      { ...serviceOptions, roles: [RoleEnum.ADMIN, RoleEnum.S_CREATOR, RoleEnum.S_SELF], select: '-messages' },
-    );
+  async findAiConversations(
+    @GraphQLServiceOptions() serviceOptions: ServiceOptions,
+    @Args('all', { nullable: true, type: () => Boolean }) all?: boolean,
+  ): Promise<CoreAiConversation[]> {
+    // Owner-scoped list shared with the REST controller — see
+    // CoreAiConversationService.findForCurrentUser for the role/ownership rationale.
+    // Admins default to their own conversations and opt in to the cross-user view via all: true.
+    return this.conversationService.findForCurrentUser(serviceOptions, { all: all === true });
   }
 
   /**

package/src/core/modules/ai/models/core-ai-conversation.model.ts

@@ -6,6 +6,7 @@ import { Restricted } from '../../../common/decorators/restricted.decorator';
 import { UnifiedField } from '../../../common/decorators/unified-field.decorator';
 import { RoleEnum } from '../../../common/enums/role.enum';
 import { CorePersistenceModel } from '../../../common/models/core-persistence.model';
+import { JSON } from '../../../common/scalars/json.scalar';
 import { CoreAiMessage } from './core-ai-message.model';
 
 export type AiConversationDocument = CoreAiConversation & Document;
@@ -45,6 +46,22 @@ export class CoreAiConversation extends CorePersistenceModel {
   })
   createdBy?: string = undefined;
 
+  /**
+   * Resolved creator identity (`{ id, email, firstName, lastName, username }`),
+   * attached at read time ONLY for an admin's cross-user list view (`all: true`)
+   * so each conversation is attributable to a named user. Not persisted and left
+   * unset on a normal own-only fetch, where the owner is the caller.
+   */
+  @UnifiedField({
+    description:
+      'Resolved creator identity (id, email, name) — set only in the admin cross-user list view, not persisted',
+    gqlType: JSON,
+    isOptional: true,
+    roles: RoleEnum.S_USER,
+    type: () => Object,
+  })
+  createdByUser?: Record<string, any> = undefined;
+
   /**
    * Conversation messages (appended via $push).
    */
@@ -76,7 +93,7 @@ export class CoreAiConversation extends CorePersistenceModel {
     if (force) {
       return this;
     }
-    if (user && (user.hasRole?.(RoleEnum.ADMIN) || (this.createdBy && String(this.createdBy) === user.id))) {
+    if (user && (user.hasRole?.(RoleEnum.ADMIN) || (this.createdBy && String(this.createdBy) === String(user.id)))) {
       return this;
     }
     // Hide conversations owned by other users (filtered out of list responses).

package/src/core/modules/ai/services/core-ai-conversation.service.ts

@@ -1,7 +1,9 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { InjectModel } from '@nestjs/mongoose';
-import { Model, Types } from 'mongoose';
+import { InjectConnection, InjectModel } from '@nestjs/mongoose';
+import { Connection, Model, Types } from 'mongoose';
 
+import { RoleEnum } from '../../../common/enums/role.enum';
+import { ServiceOptions } from '../../../common/interfaces/service-options.interface';
 import { CrudService } from '../../../common/services/crud.service';
 import { CoreModelConstructor } from '../../../common/types/core-model-constructor.type';
 import { CoreAiConversationCreateInput } from '../inputs/core-ai-conversation-create.input';
@@ -21,8 +23,15 @@ export { AI_CONVERSATION_CLASS, AI_CONVERSATION_MODEL } from '../core-ai.constan
  * CRUD service for multi-turn {@link CoreAiConversation}s.
  *
  * `appendMessage()` adds a turn via `$push` (never round-trips the subdocument
- * array through `update()`). Ownership is enforced by the model's `securityCheck`
- * and by the resolver/controller passing `S_CREATOR`/`S_SELF` roles.
+ * array through `update()`). `findForCurrentUser()` is the shared owner-scoped
+ * list used by both the REST controller and the GraphQL resolver.
+ *
+ * Ownership is enforced differently per operation shape:
+ * - single-object `get`/`delete`: the controller/resolver pass
+ *   `S_CREATOR`/`S_SELF`, evaluated against the loaded `dbObject`.
+ * - list (`findForCurrentUser`): a list has no single `dbObject`, so the gate
+ *   uses `S_USER` and ownership is scoped by the server-computed `createdBy`
+ *   filterQuery plus the model's `securityCheck`.
  */
 @Injectable()
 export class CoreAiConversationService extends CrudService<
@@ -37,10 +46,107 @@ export class CoreAiConversationService extends CrudService<
     @InjectModel(AI_CONVERSATION_MODEL) protected override readonly mainDbModel: Model<AiConversationDocument>,
     @Inject(AI_CONVERSATION_CLASS)
     protected override readonly mainModelConstructor: CoreModelConstructor<CoreAiConversation>,
+    @InjectConnection() protected readonly connection: Connection,
   ) {
     super();
   }
 
+  /**
+   * List the AI conversations visible to the current user. By default — for
+   * every user, admins included — this returns only the caller's own
+   * conversations, newest first. An admin may opt in to the cross-user view
+   * (every user's conversations) by passing `{ all: true }`; the flag is
+   * ignored for non-admins, so it can never widen a regular user's scope.
+   *
+   * Each result carries its `createdBy` owner id. In the admin cross-user view
+   * (`all: true`) each result additionally carries a resolved `createdByUser`
+   * (`{ id, email, firstName, lastName, username }`) so the list is attributable
+   * to named users; on a normal own-only fetch that lookup is skipped, since the
+   * owner is the caller. The heavy `messages` subdocument array is excluded from
+   * the list payload — fetch a single conversation via `get()` for the full
+   * message history.
+   *
+   * Shared by the REST controller (`GET /ai/conversations`) and the GraphQL
+   * resolver (`findAiConversations`) so both API surfaces enforce ownership
+   * identically and cannot drift apart.
+   *
+   * A LIST operation has no single `dbObject`, so the per-document roles
+   * `S_CREATOR` / `S_SELF` can never be satisfied at the operation level —
+   * passing them rejected every non-admin with a 403 before ownership scoping
+   * ran. The operation gate therefore uses `[S_USER]`; the server-computed
+   * `createdBy` filterQuery and the model `securityCheck` scope the result to
+   * the owner.
+   */
+  async findForCurrentUser(
+    serviceOptions?: ServiceOptions,
+    options?: { all?: boolean },
+  ): Promise<CoreAiConversation[]> {
+    const currentUser = serviceOptions?.currentUser;
+    const isAdmin = !!currentUser?.roles?.includes(RoleEnum.ADMIN);
+    // Default is own-only for everyone; only an admin may opt in to all users' conversations.
+    const seeAll = isAdmin && options?.all === true;
+    const filterQuery = seeAll ? {} : { createdBy: currentUser?.id };
+    const conversations = await this.find(
+      { filterQuery, queryOptions: { sort: { createdAt: -1 } } },
+      { ...serviceOptions, roles: [RoleEnum.S_USER], select: '-messages' },
+    );
+    // Resolve creators to named users ONLY for the admin cross-user view — a normal
+    // fetch returns just the caller's own conversations, so the owner is already known.
+    if (seeAll && conversations.length) {
+      await this.attachCreators(conversations);
+    }
+    return conversations;
+  }
+
+  /**
+   * Attach a lightweight resolved creator (`{ id, email, firstName, lastName,
+   * username }`) as `createdByUser` to each conversation, so an admin's
+   * cross-user list is attributable to named users. Read-only lookup of
+   * non-sensitive identity fields via the shared `User` model on the same
+   * connection; fails soft (leaves `createdByUser` unset) when no `User` model is
+   * registered. Never called on a normal own-only fetch.
+   */
+  protected async attachCreators(conversations: CoreAiConversation[]): Promise<void> {
+    const ids = [
+      ...new Set(
+        conversations
+          .map((conversation) => conversation.createdBy)
+          .filter(Boolean)
+          .map(String),
+      ),
+    ];
+    if (!ids.length) {
+      return;
+    }
+    let userModel: Model<any>;
+    try {
+      userModel = this.connection.model('User');
+    } catch {
+      // No `User` model registered on this connection (exotic setup) — skip attribution.
+      return;
+    }
+    const users = await userModel
+      .find({ _id: { $in: ids } })
+      .select('email firstName lastName username')
+      .lean()
+      .exec();
+    const byId = new Map(
+      (users as any[]).map((user) => [
+        String(user._id),
+        {
+          email: user.email,
+          firstName: user.firstName,
+          id: String(user._id),
+          lastName: user.lastName,
+          username: user.username,
+        },
+      ]),
+    );
+    for (const conversation of conversations) {
+      conversation.createdByUser = byId.get(String(conversation.createdBy));
+    }
+  }
+
   /**
    * Append a message to a conversation via `$push` (system-internal; the user
    * already authorized the prompt that produced it). The array is capped at

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

@@ -432,6 +432,62 @@ The `migrate` command comes from `@lenne.tech/nest-server` - no external package
 
 See the [Migration Guide](./MIGRATION_FROM_NODEPIT.md) for detailed migration instructions from @nodepit.
 
+## Migration Identity & Strict Mode
+
+### Extension-agnostic identity (safe ts-node → 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
+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.
+
+Note: identity normalization applies to the `MigrationRunner`/CLI path only. The legacy
+`synchronizedUp()` helper drives the external `migrate` package's own state handling and
+keeps raw-filename identity.
+
+### Missing migration files & strict mode
+
+Old, already-applied migration files can be deleted (they live in git and can be restored).
+By default the runner **tolerates** a recorded migration whose file is gone:
+
+- `migrate up` warns (`[migrate] N recorded migration file(s) missing — tolerated`) and continues, so the server still boots.
+- `migrate list` marks the entry with `(file missing)`.
+- `migrate down` **always fails hard** on a missing rollback file — independent of strict mode. Rollback is an explicit operator action, never a boot path; exiting 0 without rolling anything back would mislead scripts. Restore the file from git, then retry.
+
+Strict mode turns the tolerated drift into a hard error (`up` throws, `list` exits non-zero).
+Enable it via any of:
+
+| Activation path                              | Scope                                                                            |
+| -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `--strict` CLI flag                          | single invocation                                                                |
+| `NSC__MIGRATE__STRICT=1\|true\|yes` env var  | CLI **and** programmatic runners (resolved in the `MigrationRunner` constructor) |
+| `new MigrationRunner({ strict: true, ... })` | programmatic                                                                     |
+
+**Recommended for production images:** set `NSC__MIGRATE__STRICT=true` in the container
+environment. In an immutable image, a recorded-but-missing migration file can only mean a
+broken build (empty/miscopied `migrations/` directory) or a state-store mismatch (wrong
+database) — both are conditions where refusing to boot is correct.
+
+### Programmatic usage (MigrationRunner)
+
+```typescript
+import { MigrationRunner, MongoStateStore } from '@lenne.tech/nest-server';
+
+const runner = new MigrationRunner({
+  migrationsDirectory: './migrations',
+  stateStore: new MongoStateStore(process.env.NSC__MONGOOSE__URI),
+  strict: true, // optional; defaults to NSC__MIGRATE__STRICT, else false
+});
+
+await runner.up();
+const { completed, missing, pending } = await runner.status();
+```
+
 ## Project Integration
 
 The migration utilities are designed to minimize boilerplate in your projects. Instead of copying multiple utility files, you can:

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

@@ -17,18 +17,21 @@
  *   --store, -s            Path to state store module
  *   --compiler, -c         Compiler to use (e.g., ts:./path/to/ts-compiler.js)
  *   --template-file, -t    Template file for creating migrations
+ *   --strict               Fail if a recorded migration's file is missing (default: off / tolerate).
+ *                          Applies to up/list; down always fails hard on a missing rollback file.
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
 
-import { MigrationRunner } from '../migration-runner';
+import { MigrationRunner, parseStrictEnv } from '../migration-runner';
 import { MongoStateStore } from '../mongo-state-store';
 
 interface CliOptions {
   compiler?: string;
   migrationsDir: string;
   store?: string;
+  strict?: boolean;
   templateFile?: string;
 }
 
@@ -90,9 +93,11 @@ async function listMigrations(options: CliOptions) {
   const runner = new MigrationRunner({
     migrationsDirectory: path.resolve(process.cwd(), options.migrationsDir),
     stateStore,
+    strict: options.strict,
   });
 
   const status = await runner.status();
+  const missing = new Set(status.missing);
 
   console.log('\nMigration Status:');
   console.log('=================\n');
@@ -100,7 +105,7 @@ async function listMigrations(options: CliOptions) {
   if (status.completed.length > 0) {
     console.log('Completed:');
     status.completed.forEach((name) => {
-      console.log(`  ✓ ${name}`);
+      console.log(`  ✓ ${name}${missing.has(name) ? '  (file missing)' : ''}`);
     });
     console.log('');
   }
@@ -116,6 +121,14 @@ async function listMigrations(options: CliOptions) {
   if (status.completed.length === 0 && status.pending.length === 0) {
     console.log('No migrations found\n');
   }
+
+  // In strict mode, integrity drift is an error also on the inspection surface —
+  // exit non-zero (via main's error handler) instead of hiding it in the listing.
+  if (options.strict && status.missing.length > 0) {
+    throw new Error(
+      `Strict mode: ${status.missing.length} recorded migration file(s) missing: ${status.missing.join(', ')}`,
+    );
+  }
 }
 
 /**
@@ -198,6 +211,9 @@ function parseArgs(): { command: string; name?: string; options: CliOptions } {
   let name: string | undefined;
   const options: CliOptions = {
     migrationsDir: './migrations',
+    // Off by default: a recorded migration whose file was deleted is tolerated so the
+    // server still starts. Enable per-run via `--strict` or globally via NSC__MIGRATE__STRICT.
+    strict: parseStrictEnv(),
   };
 
   // Check if second arg is a name (not a flag)
@@ -217,6 +233,8 @@ function parseArgs(): { command: string; name?: string; options: CliOptions } {
       options.compiler = args[++i];
     } else if (arg === '--template-file' || arg === '-t') {
       options.templateFile = args[++i];
+    } else if (arg === '--strict') {
+      options.strict = true;
     }
   }
 
@@ -254,6 +272,7 @@ async function runDown(options: CliOptions) {
   const runner = new MigrationRunner({
     migrationsDirectory: path.resolve(process.cwd(), options.migrationsDir),
     stateStore,
+    strict: options.strict,
   });
 
   await runner.down();
@@ -269,6 +288,7 @@ async function runUp(options: CliOptions) {
   const runner = new MigrationRunner({
     migrationsDirectory: path.resolve(process.cwd(), options.migrationsDir),
     stateStore,
+    strict: options.strict,
   });
 
   await runner.up();
@@ -292,6 +312,8 @@ Options:
   --store, -s <path>                 Path to state store module
   --compiler, -c <compiler>          Compiler to use (e.g., ts:./path/to/ts-compiler.js)
   --template-file, -t <path>         Template file for creating migrations
+  --strict                           Fail if a recorded migration's file is missing (default: off / tolerate).
+                                     Applies to up/list; down always fails hard on a missing rollback file.
 
 Examples:
   migrate create add-user-email
@@ -302,6 +324,7 @@ Examples:
 
 Environment Variables:
   NODE_ENV                           Set environment (e.g., development, production)
+  NSC__MIGRATE__STRICT               1|true|yes → fail on a missing recorded migration file (default: tolerate)
 `);
 }
 
@@ -313,4 +336,5 @@ if (require.main === module) {
   });
 }
 
-export { main };
+// parseArgs is exported for unit testing only (same pattern as resolveCliPath in bin/migrate.js)
+export { main, parseArgs };