@starci/hfs 4.3.0 → 4.4.1

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.module.ts

@@ -1,17 +1,18 @@
 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, IdentityModule } from "@modules/domain/identity"
-import { LivenessModule } from "@modules/domain/liveness"
-import { NoteModule } from "@modules/domain/note"
+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: it spreads the composition groups of `compose/`, 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 {
@@ -19,15 +20,16 @@ export class AppModule {
             module: AppModule,
             imports: [
                 ...platformModules(options),
-                IdentityModule.register({ isGlobal: true }),
-                LivenessModule.register({ isGlobal: true }),
-                NoteModule.register({ isGlobal: true }),
-                SystemHealthHttpModule,
+                ...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

@@ -9,6 +9,7 @@ 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"
 
 /**
@@ -18,6 +19,7 @@ import type { {{appPascal}}Options } from "../{{app}}.options"
  */
 export const platformModules = (options: {{appPascal}}Options): Array<DynamicModule> => [
     ClockModule.register({ isGlobal: true }),
+    RetryModule.register({ isGlobal: true }),
     LoggingModule.register({ isGlobal: true }),
     I18nModule.register({
         isGlobal: true,

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,6 +1,7 @@
 import { NestFactory } from "@nestjs/core"
 import { SystemClockService } from "@modules/platform/clock"
 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 { read{{appPascal}}Env } from "./{{app}}.env"
@@ -9,4 +10,17 @@ import { read{{appPascal}}Env } from "./{{app}}.env"
 const bootstrap = async (): Promise<void> => {
     const env = EnvSource.fromProcess()
     const options = read{{appPascal}}Env(env)
-{{> be/common/main-listen.ts.partial}}
+    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.options.ts

@@ -1,20 +1,12 @@
-import { noteEntities, noteMigrations } from "@modules/domain/note"
-import type { DatabaseConnectionConfig, 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 = (primary: DatabaseConnectionConfig): DatabaseConnectionOptions => ({
-    ...primary,
-    entities: noteEntities,
-    migrations: noteMigrations,
-})
-
-/** Binds the parsed cli configuration to each connection's entities and migrations. */
+/** Passes the parsed primary connection to composition without adding registrations. */
 export const createCliAppOptions = (primary: DatabaseConnectionConfig): CliAppOptions => ({
-    connections: [primaryConnectionOf(primary)],
+    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/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()

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

@@ -1,7 +1,12 @@
 import { Module } from "@nestjs/common"
 import { SystemHealthModule } from "../../system-health.module"
 import { LiveController } from "./live.controller"
+import { ReadyController } from "./ready.controller"
+import { ConfigurableModuleClass } from "./system-health-http.module-definition"
 
-@Module({ imports: [SystemHealthModule], controllers: [LiveController] })
-/** The HTTP transport of the health feature: the liveness door. */
-export class SystemHealthHttpModule {}
+@Module({
+    imports: [SystemHealthModule.register({})],
+    controllers: [LiveController, ReadyController],
+})
+/** The HTTP transport of the health feature: independent liveness and required-dependency readiness doors. */
+export class SystemHealthHttpModule extends ConfigurableModuleClass {}

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

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

package/templates/be/skeleton/src/features/cli/cli.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/cli.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
+import { ConfigurableModuleClass } from "./cli.module-definition"
 import { MigrateModule } from "./migrate/migrate.module"
 import { SeedModule } from "./seed/seed.module"
 
-@Module({ imports: [MigrateModule, SeedModule] })
+@Module({ imports: [MigrateModule.register({}), SeedModule.register({})] })
 /** The cli feature root: every command group of the back end, compiled only into apps/cli. */
-export class CliModule {}
+export class CliModule extends ConfigurableModuleClass {}

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

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

package/templates/be/skeleton/src/features/cli/migrate/migrate.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/migrate/migrate.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { MigrateCli } from "./migrate.cli"
+import { ConfigurableModuleClass } from "./migrate.module-definition"
 import { RunCli } from "./subs/run.cli"
 
 @Module({ providers: [MigrateCli, RunCli] })
 /** The migrate group: its command and its sub-commands; the connections come from the database capability. */
-export class MigrateModule {}
+export class MigrateModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/cli/migrate/migrate.options.ts

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

package/templates/be/skeleton/src/features/cli/seed/seed.module-definition.ts

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

package/templates/be/skeleton/src/features/cli/seed/seed.module.ts

@@ -1,7 +1,8 @@
 import { Module } from "@nestjs/common"
 import { SeedCli } from "./seed.cli"
+import { ConfigurableModuleClass } from "./seed.module-definition"
 import { RunSeedsCli } from "./subs/run.cli"
 
 @Module({ providers: [SeedCli, RunSeedsCli] })
 /** The seed group: its command and its sub-commands; the connections and the seed file reader come from the database capability. */
-export class SeedModule {}
+export class SeedModule extends ConfigurableModuleClass {}

package/templates/be/skeleton/src/features/cli/seed/seed.options.ts

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

package/templates/be/skeleton/src/features/cli/seed/subs/run.cli.spec.ts

@@ -3,17 +3,17 @@ import { Test } from "@nestjs/testing"
 import { SeedRunnerService } from "@modules/platform/database"
 import { RunSeedsCli } from "./run.cli"
 
-const build = async (seeds: SeedRunnerService) => {
+const build = async () => {
+    const seeds = mock<SeedRunnerService>()
     const moduleRef = await Test.createTestingModule({
         providers: [RunSeedsCli, { provide: SeedRunnerService, useValue: seeds }],
     }).compile()
-    return moduleRef.get(RunSeedsCli)
+    return { command: moduleRef.get(RunSeedsCli), seeds }
 }
 
 describe("RunSeedsCli", () => {
     it("delegates the seed run of the named environment to the seed runner once", async () => {
-        const seeds = mock<SeedRunnerService>()
-        const command = await build(seeds)
+        const { command, seeds } = await build()
 
         await command.run([], { env: "staging" })
 
@@ -22,8 +22,7 @@ describe("RunSeedsCli", () => {
     })
 
     it("delegates with no environment when none is named, and takes --env as given", async () => {
-        const seeds = mock<SeedRunnerService>()
-        const command = await build(seeds)
+        const { command, seeds } = await build()
 
         await command.run([])