@starci/hfs 4.2.17 → 4.4.0

package/templates/be/platform/graphql/localize-errors.mapper.spec.ts

@@ -31,27 +31,41 @@ const sendResponse = async (
 }
 
 describe("localizeError", () => {
-    it("returns an error without a string code unchanged", () => {
-        const errors = mock<ErrorsService>()
-        const error: GraphQLFormattedError = { message: "syntax error", extensions: { kind: "invalid" } }
+    it.each([undefined, {}, { code: 400 }, { code: null }, { code: false }])(
+        "returns an error without a string code unchanged (%p)",
+        (extensions) => {
+            const errors = mock<ErrorsService>()
+            const error: GraphQLFormattedError = { message: "syntax error", extensions }
 
-        expect(localizeError(errors, "en", error)).toBe(error)
-        expect(errors.text).not.toHaveBeenCalled()
-    })
+            expect(localizeError(errors, "en", error)).toBe(error)
+            expect(errors.text).not.toHaveBeenCalled()
+        },
+    )
 
     it("replaces a coded error's message with the catalog text and keeps only string and number params", () => {
         const errors = mock<ErrorsService>()
         errors.text.mockReturnValue("The item was not found")
         const error: GraphQLFormattedError = {
             message: "ITEM_NOT_FOUND",
-            extensions: { code: "ITEM_NOT_FOUND", params: { id: "i-1", retries: 2, transient: false } },
+            locations: [{ line: 1, column: 2 }],
+            path: ["items", 0],
+            extensions: {
+                code: "ITEM_NOT_FOUND",
+                params: { id: "i-1", retries: 2, transient: false, missing: null, nested: { id: "i-2" } },
+                kind: "missing",
+            },
         }
 
-        expect(localizeError(errors, "en", error)).toEqual({ ...error, message: "The item was not found" })
+        const localized = localizeError(errors, "en", error)
+
+        expect(localized).toEqual({ ...error, message: "The item was not found" })
+        expect(localized).not.toBe(error)
+        expect(localized.extensions).toBe(error.extensions)
+        expect(error.message).toBe("ITEM_NOT_FOUND")
         expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", { id: "i-1", retries: 2 }, "en")
     })
 
-    it.each([undefined, null, ["i-1"], "i-1"])("interpolates no params when extensions.params is %p", (params) => {
+    it.each([undefined, null, ["i-1"], "i-1", 42, false])("interpolates no params when extensions.params is %p", (params) => {
         const errors = mock<ErrorsService>()
         errors.text.mockReturnValue("The item was not found")
         const error: GraphQLFormattedError = {
@@ -65,40 +79,54 @@ describe("localizeError", () => {
 })
 
 describe("localizeErrorsPlugin", () => {
-    it("localizes a coded error in the language the x-locale header declares", async () => {
+    it("forwards the Accept-Language preferences and localizes every coded error in the resolved locale", async () => {
         const errors = mock<ErrorsService>()
         const requestLocale = mock<RequestLocale>()
         requestLocale.of.mockReturnValue("vi")
-        errors.text.mockReturnValue("localized: not found")
+        errors.text.mockReturnValueOnce("localized: not found").mockReturnValueOnce("localized: denied")
         const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
-        const response = singleResponse([coded])
+        const uncoded: GraphQLFormattedError = { message: "syntax error" }
+        const denied: GraphQLFormattedError = {
+            message: "ACCESS_DENIED",
+            extensions: { code: "ACCESS_DENIED", params: { id: "i-1" } },
+        }
+        const response = singleResponse([coded, uncoded, denied])
 
-        const context = requestContext(response, { "x-locale": "vi", "accept-language": "en" })
+        const context = requestContext(response, { "accept-language": "vi-VN, en;q=0.8" })
 
         await sendResponse(errors, requestLocale, context)
 
-        expect(requestLocale.of).toHaveBeenCalledWith("vi")
+        expect(requestLocale.of).toHaveBeenCalledTimes(1)
+        expect(requestLocale.of).toHaveBeenCalledWith("vi-VN, en;q=0.8")
+        expect(errors.text).toHaveBeenNthCalledWith(1, "ITEM_NOT_FOUND", {}, "vi")
+        expect(errors.text).toHaveBeenNthCalledWith(2, "ACCESS_DENIED", { id: "i-1" }, "vi")
+        expect(errors.text).toHaveBeenCalledTimes(2)
         expect(response.body.kind === "single" && response.body.singleResult.errors).toEqual([
             { ...coded, message: "localized: not found" },
+            uncoded,
+            { ...denied, message: "localized: denied" },
         ])
+        expect(response.body.kind === "single" && response.body.singleResult.errors?.[1]).toBe(uncoded)
     })
 
-    it.each([{}, { "x-locale": "" }])(
-        "falls back to Accept-Language when the x-locale header is absent or empty (%p)",
-        async (declared) => {
+    it.each([undefined, ""])(
+        "delegates an absent or empty Accept-Language header to the locale default (%p)",
+        async (language) => {
             const errors = mock<ErrorsService>()
             const requestLocale = mock<RequestLocale>()
-            requestLocale.of.mockReturnValue("en")
-            errors.text.mockReturnValue("The item was not found")
+            requestLocale.of.mockReturnValue("vi")
+            errors.text.mockReturnValue("localized: not found")
             const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
 
-            await sendResponse(
-                errors,
-                requestLocale,
-                requestContext(singleResponse([coded]), { ...declared, "accept-language": "en" }),
-            )
+            const response = singleResponse([coded])
+
+            await sendResponse(errors, requestLocale, requestContext(response, { "accept-language": language }))
 
-            expect(requestLocale.of).toHaveBeenCalledWith("en")
+            expect(requestLocale.of).toHaveBeenCalledWith(language)
+            expect(errors.text).toHaveBeenCalledWith("ITEM_NOT_FOUND", {}, "vi")
+            expect(response.body.kind === "single" && response.body.singleResult.errors).toEqual([
+                { ...coded, message: "localized: not found" },
+            ])
         },
     )
 
@@ -106,8 +134,34 @@ describe("localizeErrorsPlugin", () => {
         const errors = mock<ErrorsService>()
         const requestLocale = mock<RequestLocale>()
 
-        await sendResponse(errors, requestLocale, requestContext(singleResponse(), { "accept-language": "en" }))
+        const response = singleResponse()
+        const body = response.body
 
+        await sendResponse(errors, requestLocale, requestContext(response, { "accept-language": "en" }))
+
+        expect(response.body).toBe(body)
+        expect(response.body.kind === "single" && response.body.singleResult.errors).toBeUndefined()
+        expect(requestLocale.of).not.toHaveBeenCalled()
+        expect(errors.text).not.toHaveBeenCalled()
+    })
+
+    it("leaves an incremental response alone", async () => {
+        const errors = mock<ErrorsService>()
+        const requestLocale = mock<RequestLocale>()
+        const coded: GraphQLFormattedError = { message: "ITEM_NOT_FOUND", extensions: { code: "ITEM_NOT_FOUND" } }
+        const response = mock<GraphQLResponse>({
+            body: {
+                kind: "incremental",
+                initialResult: { errors: [coded], hasNext: true },
+                subsequentResults: mock<AsyncGenerator>(),
+            },
+        })
+        const body = response.body
+
+        await sendResponse(errors, requestLocale, requestContext(response, { "accept-language": "en" }))
+
+        expect(response.body).toBe(body)
+        expect(response.body.kind === "incremental" && response.body.initialResult.errors).toEqual([coded])
         expect(requestLocale.of).not.toHaveBeenCalled()
         expect(errors.text).not.toHaveBeenCalled()
     })

package/templates/be/platform/graphql/localize-errors.mapper.ts

@@ -14,11 +14,8 @@ const paramsOf = (value: unknown): ErrorParams => {
     return params
 }
 
-/** The language a request asks for: the `x-locale` header the front end's locale link writes, else Accept-Language. */
-const requestedLocale = (context: GraphqlContext): string | undefined => {
-    const declared = context.req.headers["x-locale"]
-    return typeof declared === "string" && declared !== "" ? declared : context.req.headers["accept-language"]
-}
+/** The language a request asks for: Node normalizes the Accept-Language header name to lowercase. */
+const requestedLocale = (context: GraphqlContext): string | undefined => context.req.headers["accept-language"]
 
 /** Replaces the message of an error carrying a code with the catalog text of that code in `locale`; other errors pass unchanged. */
 export const localizeError = (

package/templates/be/skeleton/apps/__app__/src/__app__.env.ts

@@ -0,0 +1,21 @@
+import type { EnvSource } from "@modules/platform/config"
+import { parseServerConfig } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+
+/** The {{app}} environment values required before composition. */
+export interface {{appPascal}}Env {
+    /** The HTTP listener. */
+    readonly server: ReturnType<typeof parseServerConfig>
+    /** The origin allowlist and rate limits. */
+    readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** The primary database connection. */
+    readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
+}
+
+/** Reads the {{app}} environment; missing or invalid values fail boot, and secrets use `_FILE` first. */
+export const read{{appPascal}}Env = (env: EnvSource): {{appPascal}}Env => ({
+    server: parseServerConfig(env),
+    httpSecurity: parseHttpSecurityConfig(env),
+    database: parsePrimaryDatabaseConfig(env),
+})

package/templates/be/skeleton/apps/__app__/src/__app__.options.ts

@@ -2,7 +2,7 @@ import type { HttpSecurityOptions } from "@modules/platform/http-security"
 import type { ServerOptions } from "@modules/platform/config"
 import type { DatabaseConnectionConfig } from "@modules/platform/database"
 
-/** Everything the {{app}} app needs from its environment, parsed once by `main.ts` and handed to `AppModule.register`. */
+/** Everything the {{app}} app needs from its environment, parsed by `{{app}}.env.ts` and handed to `AppModule.register`. */
 export interface {{appPascal}}Options {
     /** The HTTP listener. */
     readonly server: ServerOptions

package/templates/be/skeleton/apps/__app__/src/app.module.ts

@@ -1,65 +1,35 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER, APP_GUARD } from "@nestjs/core"
-import { SystemHealthHttpModule } from "@features/api/system-health"
-import { AuthGuard, IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES, IdentityModule } from "@modules/domain/identity"
-import { LivenessModule } from "@modules/domain/liveness"
-import { NOTE_ERROR_KINDS, NoteModule, noteEntities, noteMigrations } from "@modules/domain/note"
-import { ClockModule } from "@modules/platform/clock"
-import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
-import { CqrsModule } from "@modules/platform/cqrs"
-import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
-import { ERRORS_MESSAGES, ErrorsFilter, ErrorsModule } from "@modules/platform/errors"
-import {
-    HTTP_SECURITY_ERROR_KINDS,
-    HTTP_SECURITY_MESSAGES,
-    HttpSecurityModule,
-    OriginGuard,
-    RateLimitGuard,
-} from "@modules/platform/http-security"
-import { I18nModule } from "@modules/platform/i18n"
-import { LoggingModule } from "@modules/platform/logging"
+import { AuthGuard, CredentialGuard } from "@modules/domain/identity"
+import { ErrorsFilter } from "@modules/platform/errors"
+import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
+import { platformModules } from "./compose/platform"
+import { domainModules } from "./compose/domain"
+import { systemModules } from "./compose/system"
+import { apiModules } from "./compose/api"
+import { webhooksModules } from "./compose/webhooks"
 import type { {{appPascal}}Options } from "./{{app}}.options"
 
 @Module({})
-/** Composition root of the {{app}} app: every capability is registered once, app-wide, and the three guards run in a fixed order. */
+/** Composition root of the {{app}} app: it spreads the composition groups of `compose/`, and the four guards run in a fixed order. */
 export class AppModule {
     /** Builds the module from options parsed once at boot; nothing here reads the environment. */
     static register(options: {{appPascal}}Options): DynamicModule {
         return {
             module: AppModule,
             imports: [
-                ClockModule.register({ isGlobal: true }),
-                LoggingModule.register({ isGlobal: true }),
-                I18nModule.register({
-                    isGlobal: true,
-                    bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
-                }),
-                ErrorsModule.register({
-                    isGlobal: true,
-                    kinds: [
-                        CONFIG_ERROR_KINDS,
-                        DATABASE_ERROR_KINDS,
-                        HTTP_SECURITY_ERROR_KINDS,
-                        IDENTITY_ERROR_KINDS,
-                        NOTE_ERROR_KINDS,
-                    ],
-                }),
-                CqrsModule.register({ isGlobal: true }),
-                HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
-                DatabaseModule.register({
-                    isGlobal: true,
-                    connections: [{ ...options.database, entities: noteEntities, migrations: noteMigrations }],
-                }),
-                IdentityModule.register({ isGlobal: true }),
-                LivenessModule.register({ isGlobal: true }),
-                NoteModule.register({ isGlobal: true }),
-                SystemHealthHttpModule,
+                ...platformModules(options),
+                ...domainModules(),
+                ...systemModules(),
+                ...apiModules(),
+                ...webhooksModules(),
             ],
             providers: [
                 { provide: APP_FILTER, useClass: ErrorsFilter },
                 { provide: APP_GUARD, useClass: RateLimitGuard },
                 { provide: APP_GUARD, useClass: OriginGuard },
+                { provide: APP_GUARD, useClass: CredentialGuard },
                 { provide: APP_GUARD, useClass: AuthGuard },
             ],
         }

package/templates/be/skeleton/apps/__app__/src/compose/api.ts

@@ -0,0 +1,4 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+
+/** The API transports of the app; `starci app add api` registers each generated door here. */
+export const apiModules = (): Array<Type<unknown> | DynamicModule> => []

package/templates/be/skeleton/apps/__app__/src/compose/domain.ts

@@ -0,0 +1,11 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+import { IdentityModule } from "@modules/domain/identity"
+import { LivenessModule } from "@modules/domain/liveness"
+import { NoteModule } from "@modules/domain/note"
+
+/** The domain capabilities of the app; transport scaffolding moves the skeleton registrations here. */
+export const domainModules = (): Array<Type<unknown> | DynamicModule> => [
+    IdentityModule.register({ isGlobal: true }),
+    LivenessModule.register({ isGlobal: true }),
+    NoteModule.register({ isGlobal: true }),
+]

package/templates/be/skeleton/apps/__app__/src/compose/platform.ts

@@ -0,0 +1,44 @@
+import type { DynamicModule } from "@nestjs/common"
+import { IDENTITY_ERROR_KINDS, IDENTITY_MESSAGES } from "@modules/domain/identity"
+import { NOTE_ERROR_KINDS, noteEntities, noteMigrations } from "@modules/domain/note"
+import { ClockModule } from "@modules/platform/clock"
+import { CONFIG_ERROR_KINDS } from "@modules/platform/config"
+import { CqrsModule } from "@modules/platform/cqrs"
+import { DATABASE_ERROR_KINDS, DatabaseModule } from "@modules/platform/database"
+import { ERRORS_MESSAGES, ErrorsModule } from "@modules/platform/errors"
+import { HTTP_SECURITY_ERROR_KINDS, HTTP_SECURITY_MESSAGES, HttpSecurityModule } from "@modules/platform/http-security"
+import { I18nModule } from "@modules/platform/i18n"
+import { LoggingModule } from "@modules/platform/logging"
+import { RetryModule } from "@modules/platform/retry"
+import type { {{appPascal}}Options } from "../{{app}}.options"
+
+/**
+ * The platform area of the {{app}} app: every platform capability, registered once and app-wide. A composition
+ * group holds one area's module list and nothing else (no logic, no environment read); `app.module.ts` spreads it
+ * into its imports.
+ */
+export const platformModules = (options: {{appPascal}}Options): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    RetryModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    I18nModule.register({
+        isGlobal: true,
+        bundles: [ERRORS_MESSAGES, HTTP_SECURITY_MESSAGES, IDENTITY_MESSAGES],
+    }),
+    ErrorsModule.register({
+        isGlobal: true,
+        kinds: [
+            CONFIG_ERROR_KINDS,
+            DATABASE_ERROR_KINDS,
+            HTTP_SECURITY_ERROR_KINDS,
+            IDENTITY_ERROR_KINDS,
+            NOTE_ERROR_KINDS,
+        ],
+    }),
+    CqrsModule.register({ isGlobal: true }),
+    HttpSecurityModule.register({ isGlobal: true, ...options.httpSecurity }),
+    DatabaseModule.register({
+        isGlobal: true,
+        connections: [{ ...options.database, entities: noteEntities, migrations: noteMigrations }],
+    }),
+]

package/templates/be/skeleton/apps/__app__/src/compose/system.ts

@@ -0,0 +1,5 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+import { SystemHealthHttpModule } from "@features/api/system-health"
+
+/** The system probes of the app, registered independently of product API doors. */
+export const systemModules = (): Array<Type<unknown> | DynamicModule> => [SystemHealthHttpModule.register({})]

package/templates/be/skeleton/apps/__app__/src/compose/webhooks.ts

@@ -0,0 +1,4 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+
+/** The signed webhook transports of the app; `starci app add webhook` registers each generated door here. */
+export const webhooksModules = (): Array<Type<unknown> | DynamicModule> => []

package/templates/be/skeleton/apps/__app__/src/main.ts

@@ -1,18 +1,26 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
-import { EnvSource, parseServerConfig } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+import { EnvSource } from "@modules/platform/config"
+import { applyHttpSecurity } from "@modules/platform/http-security"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
-import type { {{appPascal}}Options } from "./{{app}}.options"
+import { read{{appPascal}}Env } from "./{{app}}.env"
 
 /** Reads the environment once, composes the app from the parsed options and serves until a shutdown signal. */
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
-    const options: {{appPascal}}Options = {
-        server: parseServerConfig(env),
-        httpSecurity: parseHttpSecurityConfig(env),
-        database: parsePrimaryDatabaseConfig(env),
-    }
-{{> be/common/main-listen.ts.partial}}
+    const options = read{{appPascal}}Env(env)
+    const app = await NestFactory.create(AppModule.register(options), { rawBody: true })
+    applyHttpSecurity(app, options.httpSecurity, { trustProxy: 1 })
+    app.enableShutdownHooks()
+    await app.listen(options.server.port)
+    createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
+        service: "{{app}}",
+        port: options.server.port,
+    })
+}
+
+bootstrap().catch((error: unknown) => {
+    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "{{app}}" })
+    process.exitCode = 1
+})

package/templates/be/skeleton/apps/cli/src/app.module.ts

@@ -1,9 +1,7 @@
 import { Module } from "@nestjs/common"
 import type { DynamicModule } from "@nestjs/common"
-import { CliModule } from "@features/cli"
-import { ClockModule } from "@modules/platform/clock"
-import { DatabaseModule } from "@modules/platform/database"
-import { LoggingModule } from "@modules/platform/logging"
+import { platformModules } from "./compose/platform"
+import { cliModules } from "./compose/cli"
 import type { CliAppOptions } from "./cli.options"
 
 @Module({})
@@ -16,15 +14,7 @@ export class AppModule {
     static register(options: CliAppOptions): DynamicModule {
         return {
             module: AppModule,
-            imports: [
-                ClockModule.register({ isGlobal: true }),
-                LoggingModule.register({ isGlobal: true }),
-                DatabaseModule.register({
-                    isGlobal: true,
-                    connections: options.connections,
-                }),
-                CliModule,
-            ],
+            imports: [...platformModules(options), ...cliModules()],
         }
     }
 }

package/templates/be/skeleton/apps/cli/src/cli.env.ts

@@ -0,0 +1,13 @@
+import type { EnvSource, Secret } from "@modules/platform/config"
+import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
+
+/** The cli's primary database environment values, before entities and migrations are bound. */
+export interface CliEnv {
+    /** The logical connection name declared in `hfs.json`. */
+    readonly name: string
+    /** The primary database connection URL, read through the secret source. */
+    readonly url: Secret
+}
+
+/** Reads the required cli connection before composition; its secret uses `_FILE` first and has no default. */
+export const readCliEnv = (env: EnvSource): CliEnv => parsePrimaryDatabaseConfig(env)

package/templates/be/skeleton/apps/cli/src/cli.options.ts

@@ -1,22 +1,12 @@
-import { noteEntities, noteMigrations } from "@modules/domain/note"
-import type { EnvSource } from "@modules/platform/config"
-import { parsePrimaryDatabaseConfig } from "@modules/platform/database"
-import type { DatabaseConnectionOptions } from "@modules/platform/database"
+import type { DatabaseConnectionConfig } from "@modules/platform/database"
 
-/** Everything the cli app needs from its environment: every connection with the entities and migrations of its owners. */
+/** The parsed database configuration handed to the cli composition root. */
 export interface CliAppOptions {
-    /** The connections the migrate and seed commands run on, in the order they run them. */
-    readonly connections: ReadonlyArray<DatabaseConnectionOptions>
+    /** The primary connection before its owners' entities and migrations are bound. */
+    readonly database: DatabaseConnectionConfig
 }
 
-/** The primary database: the notes. */
-export const primaryConnectionOf = (env: EnvSource): DatabaseConnectionOptions => ({
-    ...parsePrimaryDatabaseConfig(env),
-    entities: noteEntities,
-    migrations: noteMigrations,
-})
-
-/** Parses the cli options from the environment: one entry per connection, each built by its own function above. */
-export const parseCliAppOptions = (env: EnvSource): CliAppOptions => ({
-    connections: [primaryConnectionOf(env)],
+/** Passes the parsed primary connection to composition without adding registrations. */
+export const createCliAppOptions = (primary: DatabaseConnectionConfig): CliAppOptions => ({
+    database: primary,
 })

package/templates/be/skeleton/apps/cli/src/compose/cli.ts

@@ -0,0 +1,5 @@
+import type { DynamicModule, Type } from "@nestjs/common"
+import { CliModule } from "@features/cli"
+
+/** The command groups of the CLI app. */
+export const cliModules = (): Array<Type<unknown> | DynamicModule> => [CliModule.register({})]

package/templates/be/skeleton/apps/cli/src/compose/platform.ts

@@ -0,0 +1,24 @@
+import type { DynamicModule } from "@nestjs/common"
+import { noteEntities, noteMigrations } from "@modules/domain/note"
+import { ClockModule } from "@modules/platform/clock"
+import { DatabaseModule } from "@modules/platform/database"
+import type { DatabaseConnectionConfig, DatabaseConnectionOptions } from "@modules/platform/database"
+import { LoggingModule } from "@modules/platform/logging"
+import type { CliAppOptions } from "../cli.options"
+
+/** Binds the primary connection to its owners' entities and migrations during composition. */
+const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnectionOptions => ({
+    ...primary,
+    entities: noteEntities,
+    migrations: noteMigrations,
+})
+
+/** The clock, logger and declared database connections shared by CLI commands. */
+export const platformModules = (options: CliAppOptions): Array<DynamicModule> => [
+    ClockModule.register({ isGlobal: true }),
+    LoggingModule.register({ isGlobal: true }),
+    DatabaseModule.register({
+        isGlobal: true,
+        connections: [primaryConnectionOf(options.database)],
+    }),
+]

package/templates/be/skeleton/apps/cli/src/main.ts

@@ -4,12 +4,13 @@ import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource } from "@modules/platform/config"
 import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
-import { parseCliAppOptions } from "./cli.options"
+import { readCliEnv } from "./cli.env"
+import { createCliAppOptions } from "./cli.options"
 
 /** The command line of the back end: reads the environment once and runs the command its arguments name (`cli migrate run`). */
 async function bootstrap(): Promise<void> {
     const logger = createJsonLogger(new SystemClockService())
-    await CommandFactory.run(AppModule.register(parseCliAppOptions(EnvSource.fromProcess())), {
+    await CommandFactory.run(AppModule.register(createCliAppOptions(readCliEnv(EnvSource.fromProcess()))), {
         logger: false,
         errorHandler: (error: Error) => {
             logger.error(LoggingLogEvent.StartupFailed, error, { service: "cli" })

package/templates/be/skeleton/src/features/api/system-health/application/check-readiness.contracts.ts

@@ -0,0 +1,2 @@
+/** Checking required-dependency readiness takes no input. */
+export type CheckReadinessRequest = Readonly<Record<string, never>>

package/templates/be/skeleton/src/features/api/system-health/application/check-readiness.handler.ts

@@ -0,0 +1,22 @@
+import { QueryHandler } from "@nestjs/cqrs"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectReadiness } from "@modules/platform/http-security"
+import type { ReadinessReport, ReadinessService } from "@modules/platform/http-security"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { CheckReadinessQuery } from "./check-readiness.query"
+
+@QueryHandler(CheckReadinessQuery)
+/** Answers readiness only after the bounded required-dependency probe succeeds. */
+export class CheckReadinessHandler extends ICQRSHandler<CheckReadinessQuery, ReadinessReport> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        @InjectReadiness() private readonly readiness: ReadinessService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(): Promise<ReadinessReport> {
+        return this.readiness.probeRequired()
+    }
+}

package/templates/be/skeleton/src/features/api/system-health/application/check-readiness.query.ts

@@ -0,0 +1,11 @@
+import { Query } from "@nestjs/cqrs"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { ReadinessReport } from "@modules/platform/http-security"
+import type { CheckReadinessRequest } from "./check-readiness.contracts"
+
+/** Asks whether the required primary database can serve requests. */
+export class CheckReadinessQuery extends Query<ReadinessReport> {
+    constructor(readonly params: PublicExecuteParams<CheckReadinessRequest>) {
+        super()
+    }
+}

package/templates/be/skeleton/src/features/api/system-health/system-health.module-definition.ts

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { SystemHealthOptions } from "./system-health.options"
+
+/** The configurable-module base of the system-health module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<SystemHealthOptions>().setClassMethodName("register").build()

package/templates/be/skeleton/src/features/api/system-health/system-health.module.ts

@@ -1,6 +1,8 @@
 import { Module } from "@nestjs/common"
 import { CheckLivenessHandler } from "./application/check-liveness.handler"
+import { CheckReadinessHandler } from "./application/check-readiness.handler"
+import { ConfigurableModuleClass } from "./system-health.module-definition"
 
-@Module({ providers: [CheckLivenessHandler] })
-/** Application module of the health feature: the handler of the liveness probe; readiness comes with the design that declares dependencies. */
-export class SystemHealthModule {}
+@Module({ providers: [CheckLivenessHandler, CheckReadinessHandler] })
+/** Application handlers of the independent liveness and required-dependency readiness probes. */
+export class SystemHealthModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/api/system-health/system-health.options.ts

@@ -0,0 +1,2 @@
+/** The system-health module takes no options yet. */
+export type SystemHealthOptions = Record<string, never>

package/templates/be/skeleton/src/features/api/system-health/transport/http/ready.controller.ts

@@ -0,0 +1,19 @@
+import { Controller, Get } from "@nestjs/common"
+import type { QueryBus } from "@nestjs/cqrs"
+import { Public, PublicReason } from "@modules/domain/identity"
+import { InjectQueryBus } from "@modules/platform/cqrs"
+import type { ReadinessReport } from "@modules/platform/http-security"
+import { CheckReadinessQuery } from "../../application/check-readiness.query"
+
+@Controller("health")
+/** Readiness door: reports the bounded required-dependency probe, independently of process liveness. */
+export class ReadyController {
+    constructor(@InjectQueryBus() private readonly queryBus: QueryBus) {}
+
+    /** Answers 503 while the required primary database cannot serve the app. */
+    @Get("ready")
+    @Public({ reason: PublicReason.Health })
+    ready(): Promise<ReadinessReport> {
+        return this.queryBus.execute(new CheckReadinessQuery({ request: {} }))
+    }
+}

package/templates/be/skeleton/src/features/api/system-health/transport/http/system-health-http.module-definition.ts

@@ -0,0 +1,6 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { SystemHealthHttpOptions } from "./system-health-http.options"
+
+/** The configurable-module base of the system-health-http module. */
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE } =
+    new ConfigurableModuleBuilder<SystemHealthHttpOptions>().setClassMethodName("register").build()