@lenne.tech/nest-server 11.26.2 → 11.27.0

package/migration-guides/11.26.2-to-11.26.3.md

@@ -0,0 +1,186 @@
+# Migration Guide: 11.26.2 → 11.26.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | `@UnifiedField({ enum: … })` no longer emits a broken, unnamed `$ref` in the generated OpenAPI document under `@nestjs/swagger >= 11.4` — enum fields now produce proper named component schemas (or clean inline enums when `enumName: null` / auto-detection fails) instead of `allOf: [{ $ref: '#/components/schemas/' }]`, which crashed OpenAPI client generators like `@hey-api/openapi-ts` |
+| **New Features** | None |
+| **Migration Effort** | 0 minutes (automatic) — drop-in patch release |
+
+---
+
+## Quick Migration
+
+No code changes required. The fix applies automatically as soon as the package is updated.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.26.3
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# (Optional) regenerate REST client SDK against the new OpenAPI document
+pnpm --filter @your-app/api-sdk openapi-ts
+```
+
+---
+
+## What's Fixed in 11.26.3
+
+### OpenAPI: broken empty `$ref` on enum-typed `@UnifiedField` properties
+
+**Affects:** Any project that
+
+- consumes `@lenne.tech/nest-server` together with `@nestjs/swagger >= 11.4` (this repo pinned to `11.4.2`), AND
+- exposes REST endpoints whose DTOs declare enum fields via `@UnifiedField({ enum: … })`, AND
+- runs an OpenAPI client generator (e.g. `@hey-api/openapi-ts`, `openapi-typescript`, `openapi-generator-cli`) against the bundled OpenAPI document.
+
+**Symptom (before 11.26.3):**
+
+The decorator passed `type: () => String` to `@nestjs/swagger` ALONGSIDE `enum` + `enumName`. `@nestjs/swagger <= 11.2` silently tolerated the combination, but `@nestjs/swagger >= 11.4` emits a broken, **unnamed** enum reference and never registers the enum under `components.schemas`:
+
+```jsonc
+// Generated OpenAPI document — BROKEN
+{
+  "components": {
+    "schemas": {
+      "SomeInput": {
+        "properties": {
+          "status": {
+            "allOf": [
+              { "$ref": "#/components/schemas/" }   // ← empty target!
+            ]
+          }
+        }
+      }
+      // ← StatusEnum is missing entirely from components.schemas
+    }
+  }
+}
+```
+
+Downstream tools crash:
+
+```
+@hey-api/openapi-ts: Missing $ref pointer "#/components/schemas/". Token "" does not exist.
+```
+
+**Fix (in 11.26.3):**
+
+`@UnifiedField` no longer sets `swaggerOpts.type` when the field is an enum. `@nestjs/swagger` derives the schema from `enum` + `enumName` correctly:
+
+```jsonc
+// Generated OpenAPI document — CORRECT
+{
+  "components": {
+    "schemas": {
+      "StatusEnum": { "type": "string", "enum": ["draft", "published", "review"] },
+      "SomeInput": {
+        "properties": {
+          "status": {
+            "allOf": [
+              { "$ref": "#/components/schemas/StatusEnum" }   // ← named, resolvable
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Behaviour matrix:**
+
+| `@UnifiedField` form | OpenAPI output before 11.26.3 | OpenAPI output in 11.26.3 |
+|---|---|---|
+| `{ enum: MyEnum, enumName: 'MyEnum' }` | Empty `$ref`, `MyEnum` missing from `components.schemas` | Named `MyEnum` schema, property uses `$ref` |
+| `{ enum: MyEnum }` + `registerEnum(MyEnum, { name: 'MyEnum' })` | Empty `$ref` | Named `MyEnum` schema, property uses `$ref` |
+| `{ enum: MyEnum, enumName: null }` (opt out) | Empty `$ref` | Inline `enum: [...]`, no `$ref`, no named schema |
+| `{ enum: MyEnum }` without registration | Empty `$ref` | Inline `enum: [...]`, no `$ref`, no named schema |
+| Long-form `{ enum: { enum: MyEnum, enumName: 'MyEnum' } }` (deprecated) | Empty `$ref` | Named `MyEnum` schema, property uses `$ref` (deprecation warning unchanged) |
+| Non-enum fields (`String`, `Number`, `Date`, custom classes, …) | Unchanged | Unchanged |
+
+GraphQL schema, class-validator runtime validation (`IsEnum`), Mongoose `@Prop`, and field-level `@Restricted` / `@Roles` behaviour are all bit-for-bit identical to 11.26.2.
+
+---
+
+## Compatibility Notes
+
+- **`@nestjs/swagger <= 11.2` consumers:** The previously emitted `type: () => String` was redundant; removing it produces the same enum schema as before. No observable change.
+- **`@nestjs/swagger >= 11.4` consumers:** The OpenAPI document for enum fields changes from a **broken** empty `$ref` to a **correct** named schema (or clean inline enum). This is strictly a defect fix — any client generator that was previously crashing now succeeds.
+- **OpenAPI client generators / SDK consumers:** After updating, regenerate the SDK once. Enum properties that were previously typed `string` (when the generator silently dropped the broken `$ref`) will now be typed as the proper enum union — review the generated SDK once and adjust call-sites if you relied on the loose `string` type.
+- **GraphQL consumers:** No change. The `Field(...)` factory and enum resolution are untouched.
+- **`@UnifiedField` public API:** Unchanged. All option shapes (`enum: MyEnum`, `enumName`, deprecated long-form `{ enum: { … } }`, `enumName: null`) keep their documented semantics.
+- **Mongoose / class-validator:** Unchanged. `@Prop({ type: baseType })` still applied for enum fields; `IsEnum(...)` is still the authoritative validator.
+- **Vendor-mode consumers:** Same fix lands in `src/core/common/decorators/unified-field.decorator.ts`. Sync via `/lt-dev:backend:update-nest-server-core`. No flatten-fix change required.
+- **Hidden / excluded enum fields (`@UnifiedField({ exclude: true })`):** Unaffected — those still hide from the OpenAPI document via `ApiHideProperty()`.
+
+---
+
+## Verifying the Fix
+
+If you previously hit the empty-`$ref` defect, confirm the regenerated OpenAPI document:
+
+```bash
+# 1. Boot the API and dump the OpenAPI document
+pnpm start &
+curl -s http://localhost:3000/api-json > /tmp/openapi.json
+
+# 2. There must be no empty/unnamed component refs
+grep -F '"$ref": "#/components/schemas/"' /tmp/openapi.json && echo 'BROKEN' || echo 'OK'
+
+# 3. Every enum used in a DTO must appear in components.schemas
+jq '.components.schemas | keys' /tmp/openapi.json
+```
+
+A complete regression test ships in `tests/unified-field-enum-swagger.e2e-spec.ts` and inspects the real document built by `SwaggerModule.createDocument()` for:
+
+- no empty `$ref` anywhere in the document,
+- a named component schema per enum (string / numeric / array / auto-detected / deprecated long-form),
+- correct enum values and property references,
+- inline-enum fallback for `enumName: null` and for unregistered enums (no empty `$ref`).
+
+---
+
+## Troubleshooting
+
+### After updating, my generated SDK still has an empty `$ref` error
+
+Make sure the SDK is regenerated against a **freshly rebuilt** API. Stale `openapi.json` artefacts checked into the consumer repo continue to be broken. Rebuild the API (`pnpm run build`) and re-export the document (`/api-json` or `SwaggerModule.createDocument` snapshot) before running your codegen.
+
+### My enum properties used to be typed `string` in the generated client and now they're a strict union
+
+That is the corrected behaviour — the previous client was generated against a broken document and silently widened the type. Update call-sites to use the enum union (or import the enum from your shared package). If you need the loose `string` type during the rollout, your codegen typically offers an `--enum-style` flag (e.g. `@hey-api/openapi-ts` → `enums: 'javascript'`) to keep the old shape.
+
+### I rely on the deprecated long-form `enum: { enum: MyEnum, enumName: 'MyEnum' }`
+
+It still works and now produces the same named schema as the shortcut form. The deprecation warning emitted at decoration time is unchanged. Plan to migrate to the shortcut form (`enum: MyEnum, enumName: 'MyEnum'`) before a future MINOR removes the long form.
+
+---
+
+## Module Documentation
+
+### Core Common — `@UnifiedField`
+
+- **Decorator:** `src/core/common/decorators/unified-field.decorator.ts`
+- **Architecture notes:** [.claude/rules/architecture.md](../.claude/rules/architecture.md) (Input Validation section)
+- **Reference tests:**
+  - `tests/unified-field-enum-swagger.e2e-spec.ts` — OpenAPI schema regression guard (the contract this release restores)
+  - `tests/unified-field-enum.e2e-spec.ts` — metadata-level enum behaviour
+  - `tests/unified-field-enum-api.e2e-spec.ts` — runtime REST/GraphQL enum behaviour
+
+---
+
+## References
+
+- [Migration Guide 11.26.1 → 11.26.2](./11.26.1-to-11.26.2.md) — Previous release (`COOKIE_PREFIX` env, cross-layer cookie-prefix lockstep)
+- [Architecture rules — Input Validation](../.claude/rules/architecture.md)
+- [@nestjs/swagger 11.4 release notes](https://github.com/nestjs/swagger/releases) — context for the schema-emission change that surfaced the latent defect
+- [@hey-api/openapi-ts](https://heyapi.dev/) — one of the OpenAPI client generators that was crashing on the broken document
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/migration-guides/11.26.3-to-11.27.0.md

@@ -0,0 +1,249 @@
+# Migration Guide: 11.26.3 → 11.27.0
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | Build-identity helpers (`getCommit()` / `getBuildInfo()`); the running build's commit / version / environment is now surfaced in the `/health-check` response; new `IServerOptions.version` and `healthCheck.configs.build` options |
+| **Bugfixes** | None |
+| **Migration Effort** | 0 minutes (automatic) — the health check exposes the build identity on update. ~5 minutes optional to bake the real commit SHA into your image so it stops reporting `unknown` |
+
+This release makes the **running build identifiable at runtime**. App and API are
+typically deployed together but versioned independently, so a partial / stale
+rollout (one container older than the other) is otherwise hard to spot. The build
+**commit SHA** is the drift detector: bake the same CI commit into both images and
+compare them.
+
+---
+
+## Quick Migration
+
+No code changes required. The build indicator is added to `/health-check`
+automatically — the commit just reports `'unknown'` until you bake it into the
+image (see [Adopt the full drift detection](#adopt-the-full-drift-detection-optional)).
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.0
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+---
+
+## What's New in 11.27.0
+
+### 1. Build-identity helpers: `getCommit()` / `getBuildInfo()`
+
+Two pure helpers are now exported from `@lenne.tech/nest-server`. They give every
+project ONE canonical way to resolve which build is running, instead of re-reading
+`process.env` ad hoc.
+
+```typescript
+import { getBuildInfo, getCommit } from '@lenne.tech/nest-server';
+
+// Commit SHA the build was produced from. Reads process.env.APP_VERSION_COMMIT
+// (override the var name if you like), falling back to 'unknown' for local builds.
+getCommit();                 // → 'a1b2c3d…' or 'unknown'
+getCommit('MY_COMMIT_ENV');  // → reads a custom env var
+
+// Full build identity, ready to surface via a meta / info endpoint.
+getBuildInfo({ env: 'production', version: '1.4.0' });
+// → { commit: 'a1b2c3d…', env: 'production', version: '1.4.0' }
+```
+
+Also exported: `BuildInfo` (type), `DEFAULT_COMMIT_ENV` (`'APP_VERSION_COMMIT'`),
+`UNKNOWN_COMMIT` (`'unknown'`).
+
+### 2. Build identity in the `/health-check` response
+
+The core health check now includes a `build` indicator. It is **always** reported
+with status `up`, so it surfaces under `info`/`details` **without ever affecting
+the overall health status**. Ops and monitoring can detect a drifted / stale
+container, not just the admin UI.
+
+```jsonc
+// GET /health-check  (and the GraphQL `healthCheck` query)
+{
+  "status": "ok",
+  "info": {
+    "database": { "status": "up" },
+    "build": {
+      "status": "up",
+      "commit": "a1b2c3d4e5f6…",   // process.env.APP_VERSION_COMMIT, or "unknown"
+      "env": "production",          // from IServerOptions.env
+      "version": "1.4.0"            // from IServerOptions.version (see #3), or "unknown"
+    }
+  },
+  "details": { "database": { "status": "up" }, "build": { /* same */ } }
+}
+```
+
+Opt out (e.g. if you prefer to keep build info out of an unauthenticated probe):
+
+```typescript
+// config.env.ts
+healthCheck: {
+  configs: {
+    build: { enabled: false },
+  },
+}
+```
+
+### 3. New `IServerOptions.version` config field
+
+So the health-check build indicator can report your app version, set it from your
+`package.json` / `meta.json`:
+
+```typescript
+// config.env.ts
+import metaData = require('./meta.json');
+
+const base: Partial<IServerOptions> = {
+  env: envName,
+  version: metaData.version, // ← surfaced in /health-check build identity
+  // …
+};
+```
+
+Without it, the indicator reports `version: 'unknown'` — harmless, but less useful.
+
+### Adopt the full drift detection (optional)
+
+For the end-to-end "is App on the same build as API?" check, the commit must be
+baked into the image at build time and exposed publicly. The
+[nest-server-starter](https://github.com/lenneTech/nest-server-starter) reference
+implementation wires all three layers:
+
+1. **Image** — bake the commit at build time:
+   ```dockerfile
+   # In the runtime stage (the API reads it at runtime):
+   ARG APP_VERSION_COMMIT=unknown
+   ENV APP_VERSION_COMMIT=$APP_VERSION_COMMIT
+   ```
+2. **Build arg** — feed the CI commit SHA:
+   ```yaml
+   # docker-compose.yml
+   build:
+     args:
+       APP_VERSION_COMMIT: ${IMAGE_TAG:-unknown}   # IMAGE_TAG = CI_COMMIT_SHA
+   ```
+3. **Public endpoint** — the starter's `meta` module exposes `GET /meta`
+   (`S_EVERYONE`) returning `{ version, commit, environment, package, title }`,
+   so the frontend can read the API commit and compare it against its own.
+
+The contract end to end:
+
+```
+CI commit SHA → IMAGE_TAG (CI) → APP_VERSION_COMMIT build arg (compose)
+             → ENV in the image (Dockerfile) → getCommit() → /health-check + /meta
+```
+
+Versions (semver) are per-component and may legitimately differ — only the
+**commit** is compared. Local builds without CI report `unknown`, which clients
+use to suppress the drift warning.
+
+---
+
+## Breaking Changes
+
+None. All additions are backward compatible.
+
+---
+
+## Compatibility Notes
+
+- **Existing `/health-check` consumers:** The response gains one extra key
+  (`build`) under `info` and `details`. `status` is unchanged and the `build`
+  indicator can never flip the overall status to `error` (it always reports `up`).
+  Only consumers that assert the *exact* set of keys need updating; disable it via
+  `healthCheck.configs.build.enabled: false` if you must keep the old shape.
+- **GraphQL `healthCheck` query:** `info`/`details` are `JSON` scalars, so the new
+  `build` key flows through without any schema change.
+- **`IServerOptions`:** `version` and `healthCheck.configs.build` are new optional
+  fields. Existing configs compile unchanged.
+- **Commit resolution:** If you previously read `process.env.APP_VERSION_COMMIT`
+  yourself, you can switch to `getCommit()` for the identical result (with the
+  `'unknown'` fallback) — optional, not required.
+- **Vendor-mode consumers:** The same additions land in
+  `src/core/common/helpers/meta.helper.ts` and
+  `src/core/modules/health-check/core-health-check.service.ts`. Sync via the
+  vendored-core updater. No flatten-fix change required.
+
+---
+
+## Verifying
+
+```bash
+# Boot the API and read the health check
+pnpm start &
+curl -s http://localhost:3000/health-check | jq '.info.build'
+# → { "status": "up", "commit": "unknown", "env": "local", "version": "1.4.0" }
+
+# After a CI build that passes APP_VERSION_COMMIT, "commit" is the real SHA:
+APP_VERSION_COMMIT=$(git rev-parse HEAD) pnpm start &
+curl -s http://localhost:3000/health-check | jq '.info.build.commit'
+```
+
+A unit test for the helpers ships in `tests/unit/meta-helper.spec.ts`.
+
+---
+
+## Troubleshooting
+
+### `commit` is always `"unknown"`
+
+The build arg never reached the process. Check, in order:
+
+1. CI passes the commit SHA into the build (`IMAGE_TAG` / `APP_VERSION_COMMIT`).
+2. `docker-compose.yml` forwards it as a `build.args.APP_VERSION_COMMIT`.
+3. The **API** Dockerfile declares `ARG`/`ENV APP_VERSION_COMMIT` in the **runtime
+   stage** (the API reads it at runtime, not build time).
+4. For a frontend, the commit must be set **before** the bundler runs (e.g. Nuxt
+   freezes `runtimeConfig.public` at build time) — there the `ARG`/`ENV` belongs in
+   the **build stage**, not the runtime stage.
+
+### `version` is `"unknown"`
+
+Set `IServerOptions.version` (see [#3](#3-new-iserveroptionsversion-config-field)).
+The health check reads `config.version`; nothing else populates it.
+
+### I don't want build info on an unauthenticated endpoint
+
+`/health-check` is `S_EVERYONE` by design (probes need it). Disable just the build
+indicator with `healthCheck.configs.build.enabled: false`, or restrict the route
+in your project.
+
+---
+
+## Module Documentation
+
+### Core Common — build-identity helpers
+
+- **Helpers:** `src/core/common/helpers/meta.helper.ts` (`getCommit`, `getBuildInfo`, `BuildInfo`, `DEFAULT_COMMIT_ENV`, `UNKNOWN_COMMIT`)
+- **Unit tests:** `tests/unit/meta-helper.spec.ts`
+
+### Core Health Check
+
+- **Service:** `src/core/modules/health-check/core-health-check.service.ts` (build indicator)
+- **Controller / Resolver:** `src/core/modules/health-check/core-health-check.controller.ts`, `core-health-check.resolver.ts`
+- **Config:** `IServerOptions.healthCheck.configs.build` + `IServerOptions.version` in `src/core/common/interfaces/server-options.interface.ts`
+
+### Reference implementation (full drift detection)
+
+- **API meta module + Dockerfile build arg:** [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — `src/server/modules/meta/` exposes `GET /meta` with `commit`
+- **Frontend system page:** [nuxt-base-starter](https://github.com/lenneTech/nuxt-base-starter) — `/app/admin/system` compares App vs. API builds
+
+---
+
+## References
+
+- [Migration Guide 11.26.2 → 11.26.3](./11.26.2-to-11.26.3.md) — Previous release (OpenAPI enum `$ref` fix)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+- [nuxt-base-starter](https://github.com/lenneTech/nuxt-base-starter) (frontend drift detection)
+- [lt-monorepo](https://github.com/lenneTech/lt-monorepo) — `docker-compose.yml` + CI wiring for the `APP_VERSION_COMMIT` contract

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.26.2",
+  "version": "11.27.0",
   "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",
@@ -232,7 +232,8 @@
       "defu@<=6.1.6": "6.1.7",
       "follow-redirects@<=1.15.11": "1.16.0",
       "uuid@<14.0.0": "14.0.0",
-      "postcss@<8.5.10": "8.5.12"
+      "postcss@<8.5.10": "8.5.12",
+      "esbuild@>=0.17.0 <0.28.1": "0.28.1"
     },
     "//peerDependencyRules": "allowedVersions: deps lag behind our newer majors (graphql-upload wants @types/express@^4, the deprecated apollo playground plugin wants @apollo/server@^4) — both work with our v5. ignoreMissing: browser-only vis-network peers pulled in transitively via yuml-diagram (server-side UML generation never renders, so these are not needed).",
     "peerDependencyRules": {

package/src/core/common/decorators/unified-field.decorator.ts

@@ -408,13 +408,19 @@ export function UnifiedField(opts: UnifiedFieldOptions = {}): PropertyDecorator
       swaggerOpts.required = true;
     }
 
-    // Set type for swagger
-    if (baseType) {
-      if (normalizedEnum) {
-        swaggerOpts.type = () => String;
-      } else {
-        swaggerOpts.type = baseType;
-      }
+    // Set type for swagger.
+    //
+    // For enum fields we deliberately do NOT set `type`: @nestjs/swagger derives
+    // the schema from `enum` + `enumName` (set further below). Passing
+    // `type: () => String` ALONGSIDE `enum`/`enumName` makes @nestjs/swagger
+    // >= 11.4 emit a broken, UNNAMED enum reference
+    // (`allOf: [{ $ref: '#/components/schemas/' }]`) and never adds the enum to
+    // `components.schemas`. That crashes OpenAPI client generators — e.g.
+    // @hey-api/openapi-ts fails with «Missing $ref pointer "#/components/schemas/"».
+    // (On @nestjs/swagger <= 11.2 the extra `type` was tolerated, which is why
+    // this only surfaced after a swagger bump.)
+    if (baseType && !normalizedEnum) {
+      swaggerOpts.type = baseType;
     }
 
     // Set description

package/src/core/common/helpers/meta.helper.ts

@@ -0,0 +1,69 @@
+/**
+ * Build identity helpers.
+ *
+ * A deployed image's exact build is identified by its git commit SHA, baked in
+ * at build time via an environment variable (default `APP_VERSION_COMMIT`, fed
+ * from the CI commit SHA — the same value typically used as the image tag).
+ *
+ * Unlike the semantic `version` (a rarely-bumped semver that may legitimately
+ * differ between an API and its frontend, since each is versioned independently)
+ * the commit SHA uniquely pins the exact running build. A frontend and backend
+ * deployed together bake the SAME commit, but each reads its own at runtime — so
+ * comparing them detects a drifted / stale container after a partial rollout.
+ *
+ * @see getCommit
+ * @see getBuildInfo
+ */
+
+/** Default environment variable the build commit SHA is baked into. */
+export const DEFAULT_COMMIT_ENV = 'APP_VERSION_COMMIT';
+
+/** Defined value returned when no commit could be resolved. */
+export const UNKNOWN_COMMIT = 'unknown';
+
+/**
+ * Build identity of the running process.
+ */
+export interface BuildInfo {
+  /** Git commit SHA the build was produced from, or `'unknown'`. */
+  commit: string;
+
+  /** Environment the process runs in (e.g. `'production'`), if provided. */
+  env?: string;
+
+  /** Semantic version of the build, or `'unknown'`. */
+  version?: string;
+}
+
+/**
+ * Resolve the git commit SHA the running build was produced from.
+ *
+ * Reads `process.env[envName]` (default `APP_VERSION_COMMIT`). Falls back to
+ * `'unknown'` so local / un-tagged builds still return a defined value — clients
+ * use `'unknown'` to suppress the "builds drifted" warning instead of comparing
+ * against an empty string.
+ *
+ * @param envName Name of the environment variable holding the commit SHA.
+ */
+export function getCommit(envName: string = DEFAULT_COMMIT_ENV): string {
+  return process.env[envName] || UNKNOWN_COMMIT;
+}
+
+/**
+ * Assemble the build identity of the running process.
+ *
+ * Combines the commit SHA (from the environment) with an optionally supplied
+ * `version` and `env`. Designed to be surfaced via a public meta / info endpoint
+ * and the health check so deployments can be compared at a glance.
+ *
+ * @param options.commitEnvName Override the env var the commit SHA is read from.
+ * @param options.env Environment label to include (e.g. from the config).
+ * @param options.version Semantic version to include (e.g. from package.json).
+ */
+export function getBuildInfo(options: { commitEnvName?: string; env?: string; version?: string } = {}): BuildInfo {
+  return {
+    commit: getCommit(options.commitEnvName),
+    env: options.env,
+    version: options.version || UNKNOWN_COMMIT,
+  };
+}

package/src/core/common/interfaces/server-options.interface.ts

@@ -1591,6 +1591,17 @@ export interface IServerOptions {
    */
   env?: string;
 
+  /**
+   * Semantic version of the running build (e.g. from package.json / meta.json).
+   *
+   * Surfaced via the build-identity health indicator alongside the commit SHA.
+   * Unlike the commit (which uniquely pins the exact build), the version is a
+   * rarely-bumped semver and may legitimately differ between API and frontend.
+   *
+   * @since 11.27.0
+   */
+  version?: string;
+
   /**
    * Configuration for the error code module
    *
@@ -1671,6 +1682,24 @@ export interface IServerOptions {
      * Configuration of single health checks
      */
     configs?: {
+      /**
+       * Configuration for the build-identity health indicator.
+       *
+       * Always reports status "up" and surfaces the running build's commit SHA,
+       * version and environment under the health check's `info`/`details`, so a
+       * drifted / stale container can be detected after a partial rollout. The
+       * commit is read from `process.env.APP_VERSION_COMMIT` (baked at build
+       * time from the CI commit SHA); `version` comes from {@link IServerOptions.version}.
+       *
+       * @since 11.27.0
+       */
+      build?: {
+        /**
+         * Whether to include build identity in the health check (default: true)
+         */
+        enabled?: boolean;
+      };
+
       /**
        * Configuration for database health check
        */

package/src/core/modules/health-check/core-health-check.service.ts

@@ -9,6 +9,7 @@ import {
 import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health.js';
 import type { DiskHealthIndicatorOptions } from '@nestjs/terminus/dist/health-indicator/disk/disk-health-options.type.js';
 
+import { getBuildInfo } from '../../common/helpers/meta.helper';
 import { ConfigService } from '../../common/services/config.service';
 
 /**
@@ -64,6 +65,18 @@ export class CoreHealthCheckService {
         ),
       );
     }
+    // Build identity (commit / version / env) — always reported as "up", so it
+    // surfaces under `info`/`details` without ever affecting the overall health
+    // status. Lets ops/monitoring detect a drifted or stale container after a
+    // partial rollout (the same commit-SHA signal the admin UI compares). The
+    // commit is baked into the image at build time (APP_VERSION_COMMIT, fed from
+    // the CI commit SHA); `version`/`env` come from the config. Opt out with
+    // `healthCheck.configs.build.enabled: false`.
+    if (this.config.get<boolean>('healthCheck.configs.build.enabled') !== false) {
+      const build = getBuildInfo({ env: this.config.get<string>('env'), version: this.config.get<string>('version') });
+      healthIndicatorFunctions.push(async () => ({ build: { ...build, status: 'up' as const } }));
+    }
+
     return this.health.check(healthIndicatorFunctions);
   }
 }

package/src/index.ts

@@ -40,6 +40,7 @@ export * from './core/common/helpers/interceptor.helper';
 export * from './core/common/helpers/gridfs.helper';
 export * from './core/common/helpers/input.helper';
 export * from './core/common/helpers/logging.helper';
+export * from './core/common/helpers/meta.helper';
 export * from './core/common/helpers/model.helper';
 export * from './core/common/helpers/register-enum.helper';
 export * from './core/common/helpers/scim.helper';