@starci/hfs 1.0.0 → 2.0.0

package/templates/be/hooks/husky/pre-commit

@@ -0,0 +1,13 @@
+{{header}}
+# Commit gate: the secrets guard and work hygiene of the staged files, types, lint and format of the staged files, the unit specs the staged files touch. Never integration, e2e or contract.
+npx hfs work-hygiene
+npm run typecheck
+sources=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' '*.mts' '*.cts' '*.js' '*.mjs' '*.cjs' || true)
+if [ -n "$sources" ]; then
+  npx eslint $sources
+  npx prettier --check $sources
+fi
+specs=$(git diff --cached --name-only --diff-filter=ACMR -- '*.ts' | grep -v -E '(^|/)src/tests/(world|integration|e2e|contract)/|\.(integration|e2e|contract)-spec\.ts$' || true)
+if [ -n "$specs" ]; then
+  npm run test:affected -- --findRelatedTests $specs
+fi

package/templates/be/hooks/husky/pre-push

@@ -0,0 +1,7 @@
+{{header}}
+# Push gate: types, lint, format, the architecture check on the owners this push touches, unit specs affected since main. Never integration, e2e or contract.
+npm run typecheck
+npm run lint:check
+npm run format:check
+npm run hfs:check -- --fast
+npm run test:affected -- --changedSince=origin/main

package/templates/be/package-scripts/package.json

@@ -0,0 +1,21 @@
+{
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
+    {{appScripts}}
+    "typecheck": "tsc -p tsconfig.json",
+    "typecheck:tests": "tsc -p src/tests/tsconfig.json",
+    "lint": "eslint --fix .",
+    "lint:check": "eslint .",
+    "lint:report": "eslint . --format json --output-file reports/eslint.json",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "jest --selectProjects unit --coverage",
+    "test:affected": "jest --selectProjects unit --passWithNoTests",
+    "test:integration": "npm run typecheck:tests && jest --selectProjects integration",
+    "test:e2e": "npm run typecheck:tests && jest --selectProjects e2e",
+    "test:contract": "npm run typecheck:tests && jest --selectProjects contract",
+    "contract:emit": "hfs emit-contracts",
+    "hfs:check": "hfs check",
+    "hfs:report": "hfs check --sonar reports/hfs.sonar.json"
+  }
+}

package/templates/be/{sonar-project.properties → quality-config/sonar-project.properties}

@@ -1,10 +1,9 @@
+{{header}}
 sonar.projectKey={{sonarKey}}
-sonar.host.url=https://sonar.starci.org
 sonar.sourceEncoding=UTF-8
 sonar.sources=apps,src
 sonar.tests=apps,src
 sonar.exclusions={{sonarExclusions}}
 sonar.test.inclusions=**/*.spec.ts
-sonar.coverage.exclusions={{sonarCoverageExclusions}}
-sonar.javascript.lcov.reportPaths=coverage/lcov.info
+sonar.externalIssuesReportPaths=reports/hfs.sonar.json,reports/eslint.sonar.json
 sonar.nodejs.maxspace=8192

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

@@ -1,19 +1,29 @@
-import { DynamicModule, Module } from "@nestjs/common"
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
 import { APP_FILTER } from "@nestjs/core"
-import { SystemHealthModule } from "@features/system-health"
+import { SystemHealthHttpModule } from "@features/system-health"
+import { LivenessModule } from "@modules/domain/liveness"
+import { ClockModule } from "@modules/platform/clock"
 import { SERVER_OPTIONS } from "@modules/platform/config"
+import { CqrsModule } from "@modules/platform/cqrs"
 import { ErrorFilter } from "@modules/platform/errors"
 import { LoggingModule } from "@modules/platform/logging"
 import type { {{appPascal}}Options } from "./{{app}}.options"
 
-/** Composition root of the {{app}} app: the features it runs, the platform it needs and its one error filter. */
 @Module({})
+/** Composition root of the {{app}} app: every capability is registered once, app-wide, the features it runs and its one error filter. */
 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: [LoggingModule, SystemHealthModule],
+            imports: [
+                ClockModule.register({ isGlobal: true }),
+                LoggingModule.register({ isGlobal: true }),
+                CqrsModule.register({ isGlobal: true }),
+                LivenessModule.register({ isGlobal: true }),
+                SystemHealthHttpModule,
+            ],
             providers: [
                 { provide: SERVER_OPTIONS, useValue: options.server },
                 { provide: APP_FILTER, useClass: ErrorFilter },

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

@@ -1,20 +1,23 @@
 import { NestFactory } from "@nestjs/core"
+import { SystemClockService } from "@modules/platform/clock"
 import { EnvSource, parseServerConfig } from "@modules/platform/config"
-import { createJsonLogger, LogId } from "@modules/platform/logging"
+import { createJsonLogger, LoggingLogEvent } from "@modules/platform/logging"
 import { AppModule } from "./app.module"
 import type { {{appPascal}}Options } from "./{{app}}.options"
 
 /** 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) }
+    const options: {{appPascal}}Options = { server: parseServerConfig(EnvSource.fromProcess()) }
     const app = await NestFactory.create(AppModule.register(options))
     app.enableShutdownHooks()
     await app.listen(options.server.port)
+    createJsonLogger(new SystemClockService()).info(LoggingLogEvent.ServerStarted, {
+        service: "{{app}}",
+        port: options.server.port,
+    })
 }
 
-const logger = createJsonLogger()
-bootstrap().catch((cause: unknown) => {
-    logger.error(LogId.StartupFailed, { failure: cause instanceof Error ? { name: cause.name, message: cause.message } : { name: typeof cause } })
+bootstrap().catch((error: unknown) => {
+    createJsonLogger(new SystemClockService()).error(LoggingLogEvent.StartupFailed, error, { service: "{{app}}" })
     process.exitCode = 1
 })

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

@@ -0,0 +1,2 @@
+/** Checking liveness takes no input. */
+export type CheckLivenessRequest = Readonly<Record<string, never>>

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

@@ -0,0 +1,22 @@
+import { QueryHandler } from "@nestjs/cqrs"
+import { LivenessService } from "@modules/domain/liveness"
+import type { LivenessReport } from "@modules/domain/liveness"
+import { ICQRSHandler } from "@modules/platform/cqrs"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { CheckLivenessQuery } from "./check-liveness.query"
+
+@QueryHandler(CheckLivenessQuery)
+/** Answers the liveness probe from the liveness service: no dependency is touched, so an outage never restarts the process. */
+export class CheckLivenessHandler extends ICQRSHandler<CheckLivenessQuery, LivenessReport> {
+    constructor(
+        @InjectLogger() logger: Logger,
+        private readonly liveness: LivenessService,
+    ) {
+        super(logger)
+    }
+
+    protected override process(): Promise<LivenessReport> {
+        return this.liveness.check()
+    }
+}

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

@@ -0,0 +1,11 @@
+import { Query } from "@nestjs/cqrs"
+import type { LivenessReport } from "@modules/domain/liveness"
+import type { PublicExecuteParams } from "@modules/platform/cqrs"
+import type { CheckLivenessRequest } from "./check-liveness.contracts"
+
+/** Asks whether this process is alive. */
+export class CheckLivenessQuery extends Query<LivenessReport> {
+    constructor(readonly params: PublicExecuteParams<CheckLivenessRequest>) {
+        super()
+    }
+}

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

@@ -1 +1 @@
-export { SystemHealthModule } from "./system-health.module"
+export { SystemHealthHttpModule } from "./transport/http/system-health-http.module"

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

@@ -1,6 +1,6 @@
 import { Module } from "@nestjs/common"
-import { SystemHealthHttpModule } from "./transport/http/system-health-http.module"
+import { CheckLivenessHandler } from "./application/check-liveness.handler"
 
-/** Application module of the health feature: process-local liveness now, readiness with the design that declares dependencies. */
-@Module({ imports: [SystemHealthHttpModule] })
+@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 {}

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

@@ -1,18 +1,17 @@
 import { Controller, Get } from "@nestjs/common"
-import { HealthCheck, HealthCheckResult, HealthCheckService } from "@nestjs/terminus"
+import type { QueryBus } from "@nestjs/cqrs"
+import type { LivenessReport } from "@modules/domain/liveness"
+import { InjectQueryBus } from "@modules/platform/cqrs"
+import { CheckLivenessQuery } from "../../application/check-liveness.query"
 
-/** Liveness probe: answers `{ status, info, error, details }` from process-local state and never touches a dependency. */
 @Controller("health")
+/** Liveness probe: answers the liveness report from process-local state and never touches a dependency. */
 export class LiveController {
-    constructor(
-        /** Terminus executor; it runs no indicator, so a dependency outage never restarts the process. */
-        private readonly health: HealthCheckService,
-    ) {}
+    constructor(@InjectQueryBus() private readonly queryBus: QueryBus) {}
 
     /** Reports the process alive while its event loop still answers requests. */
     @Get("live")
-    @HealthCheck()
-    live(): Promise<HealthCheckResult> {
-        return this.health.check([])
+    live(): Promise<LivenessReport> {
+        return this.queryBus.execute(new CheckLivenessQuery({ request: {} }))
     }
 }

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

@@ -1,10 +1,7 @@
 import { Module } from "@nestjs/common"
-import { TerminusModule } from "@nestjs/terminus"
+import { SystemHealthModule } from "../../system-health.module"
 import { LiveController } from "./live.controller"
 
-/** The HTTP transport of the health feature. */
-@Module({
-    imports: [TerminusModule],
-    controllers: [LiveController],
-})
+@Module({ imports: [SystemHealthModule], controllers: [LiveController] })
+/** The HTTP transport of the health feature: the liveness door. */
 export class SystemHealthHttpModule {}

package/templates/be/skeleton/src/modules/domain/liveness/index.ts

@@ -0,0 +1,3 @@
+export type { LivenessReport } from "./liveness.contracts"
+export { LivenessModule } from "./liveness.module"
+export { LivenessService } from "./liveness.service"

package/templates/be/skeleton/src/modules/domain/liveness/liveness.contracts.ts

@@ -0,0 +1,9 @@
+/** What a liveness probe answers. */
+export interface LivenessReport {
+    /** Always ok: the probe answers only while the process does. */
+    readonly status: "ok"
+    /** When this process started, as an ISO 8601 instant. */
+    readonly startedAt: string
+    /** Whole seconds the process has been up. */
+    readonly uptimeSeconds: number
+}

package/templates/be/skeleton/src/modules/domain/liveness/liveness.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { LivenessOptions } from "./liveness.options"
+
+/** The configurable-module base of the liveness capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<LivenessOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/domain/liveness/liveness.module.ts

@@ -0,0 +1,14 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { LivenessService } from "./liveness.service"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./liveness.module-definition"
+
+@Module({})
+/** The liveness capability: the process reports itself alive from the Clock, with no dependency to probe. */
+export class LivenessModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return { ...base, providers: [...(base.providers ?? []), LivenessService], exports: [LivenessService] }
+    }
+}

package/templates/be/skeleton/src/modules/domain/liveness/liveness.options.ts

@@ -0,0 +1,2 @@
+/** The liveness capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type LivenessOptions = Record<never, never>

package/templates/be/skeleton/src/modules/domain/liveness/liveness.service.spec.ts

@@ -0,0 +1,40 @@
+import { Test } from "@nestjs/testing"
+import { FakeClock } from "@starci/jest-preset"
+import { CLOCK } from "@modules/platform/clock"
+import { LivenessService } from "./liveness.service"
+
+const START = "2026-01-01T00:00:00.000Z"
+
+const build = async () => {
+    const clock = new FakeClock(START)
+    const moduleRef = await Test.createTestingModule({
+        providers: [LivenessService, { provide: CLOCK, useValue: clock }],
+    }).compile()
+    return { service: moduleRef.get(LivenessService), clock }
+}
+
+describe("LivenessService", () => {
+    describe("check", () => {
+        it("answers ok with the start instant and no uptime right after the start", async () => {
+            const { service } = await build()
+
+            await expect(service.check()).resolves.toEqual({ status: "ok", startedAt: START, uptimeSeconds: 0 })
+        })
+
+        it("counts whole seconds of uptime from the clock and keeps the start instant", async () => {
+            const { service, clock } = await build()
+
+            clock.advance(90_999)
+
+            await expect(service.check()).resolves.toEqual({ status: "ok", startedAt: START, uptimeSeconds: 90 })
+        })
+
+        it("rounds a partial second down and stays at zero under one second", async () => {
+            const { service, clock } = await build()
+
+            clock.advance(999)
+
+            await expect(service.check()).resolves.toMatchObject({ uptimeSeconds: 0 })
+        })
+    })
+})

package/templates/be/skeleton/src/modules/domain/liveness/liveness.service.ts

@@ -0,0 +1,26 @@
+import { Injectable } from "@nestjs/common"
+import { InjectClock } from "@modules/platform/clock"
+import type { Clock } from "@modules/platform/clock"
+import type { LivenessReport } from "./liveness.contracts"
+
+const MS_PER_SECOND = 1000
+
+@Injectable()
+/** The liveness of this process: it answers ok with when it started and how long it has been up, read from the Clock. */
+export class LivenessService {
+    private readonly startedAt: Date
+
+    constructor(@InjectClock() private readonly clock: Clock) {
+        this.startedAt = clock.now()
+    }
+
+    /** The report of one probe; it reads no dependency, so an outage elsewhere never restarts the process. */
+    check(): Promise<LivenessReport> {
+        const uptime = this.clock.now().getTime() - this.startedAt.getTime()
+        return Promise.resolve({
+            status: "ok",
+            startedAt: this.startedAt.toISOString(),
+            uptimeSeconds: Math.floor(uptime / MS_PER_SECOND),
+        })
+    }
+}

package/templates/be/skeleton/src/modules/platform/clock/clock.decorators.ts

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Clock } from "./clock.port"
+
+/** Token of the Clock port. */
+export const CLOCK: unique symbol = Symbol("platform.clock")
+
+/** Injects the Clock port. Parameter type: Clock. */
+export const InjectClock = (): TypedParameterDecorator<Clock> => injector<Clock>(CLOCK)

package/templates/be/skeleton/src/modules/platform/clock/clock.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { ClockOptions } from "./clock.options"
+
+/** The configurable-module base of the clock capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<ClockOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/platform/clock/clock.module.ts

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CLOCK } from "./clock.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./clock.module-definition"
+import { SystemClockService } from "./system-clock.service"
+
+@Module({})
+/** Provides the Clock port backed by the system clock. */
+export class ClockModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            providers: [...(base.providers ?? []), { provide: CLOCK, useClass: SystemClockService }],
+            exports: [CLOCK],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/clock/clock.options.ts

@@ -0,0 +1,2 @@
+/** The clock capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type ClockOptions = Record<never, never>

package/templates/be/skeleton/src/modules/platform/clock/clock.port.ts

@@ -0,0 +1,5 @@
+/** The clock port: business code asks it for the time instead of reading the ambient clock, so a spec can drive time. */
+export interface Clock {
+    /** The current instant. */
+    now(): Date
+}

package/templates/be/skeleton/src/modules/platform/clock/index.ts

@@ -0,0 +1,4 @@
+export type { Clock } from "./clock.port"
+export { CLOCK, InjectClock } from "./clock.decorators"
+export { ClockModule } from "./clock.module"
+export { SystemClockService } from "./system-clock.service"

package/templates/be/skeleton/src/modules/platform/clock/system-clock.service.spec.ts

@@ -0,0 +1,20 @@
+import { Test } from "@nestjs/testing"
+import { SystemClockService } from "./system-clock.service"
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [SystemClockService] }).compile()
+    return { service: moduleRef.get(SystemClockService) }
+}
+
+describe("SystemClockService", () => {
+    describe("now", () => {
+        it("answers the current instant of the host, a valid date", async () => {
+            const { service } = await build()
+
+            const instant = service.now()
+
+            expect(instant).toBeInstanceOf(Date)
+            expect(Number.isNaN(instant.getTime())).toBe(false)
+        })
+    })
+})

package/templates/be/skeleton/src/modules/platform/clock/system-clock.service.ts

@@ -0,0 +1,9 @@
+import type { Clock } from "./clock.port"
+
+/** The production clock: the one place that reads the ambient system time. It has no dependencies, so the DI container builds it without a decorator and main.ts builds it directly before the container exists. */
+export class SystemClockService implements Clock {
+    /** The current instant of the host clock. */
+    now(): Date {
+        return new Date()
+    }
+}

package/templates/be/skeleton/src/modules/platform/composition/composition.decorators.ts

@@ -0,0 +1,8 @@
+import { Inject } from "@nestjs/common"
+import type { InjectionToken } from "@nestjs/common"
+
+/** A parameter decorator that remembers the type `T` it injects, so a lint rule can compare it with the parameter annotation. */
+export type TypedParameterDecorator<T> = ParameterDecorator & { readonly __injects?: T }
+
+/** Builds the parameter decorator that injects `token`, typed with the value it injects. Every `Inject<Thing>()` is built with it. */
+export const injector = <T>(token: InjectionToken): TypedParameterDecorator<T> => Inject(token)

package/templates/be/skeleton/src/modules/platform/composition/index.ts

@@ -0,0 +1,2 @@
+export { injector } from "./composition.decorators"
+export type { TypedParameterDecorator } from "./composition.decorators"

package/templates/be/skeleton/src/modules/platform/config/config.decorators.ts

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { ServerOptions } from "./server.options"
+
+/** Token under which the app module provides its {@link ServerOptions}. */
+export const SERVER_OPTIONS: unique symbol = Symbol("platform.config.server-options")
+
+/** Injects the server options of the app. Parameter type: ServerOptions. */
+export const InjectServerOptions = (): TypedParameterDecorator<ServerOptions> => injector<ServerOptions>(SERVER_OPTIONS)

package/templates/be/skeleton/src/modules/platform/config/index.ts

@@ -1,5 +1,4 @@
-export { EnvSource } from "./env-source"
-export { ConfigError } from "./errors/config.error"
+export { SERVER_OPTIONS } from "./config.decorators"
+export { EnvSource } from "./env-source.config"
 export { parseServerConfig } from "./server.config"
-export { SERVER_OPTIONS } from "./server.options"
 export type { ServerOptions } from "./server.options"

package/templates/be/skeleton/src/modules/platform/config/server.config.ts

@@ -1,4 +1,4 @@
-import type { EnvSource } from "./env-source"
+import type { EnvSource } from "./env-source.config"
 import { ConfigError } from "./errors/config.error"
 import type { ServerOptions } from "./server.options"
 

package/templates/be/skeleton/src/modules/platform/config/server.options.ts

@@ -3,6 +3,3 @@ export interface ServerOptions {
     /** TCP port the HTTP listener binds. */
     readonly port: number
 }
-
-/** Injection token under which the app module provides its {@link ServerOptions}. */
-export const SERVER_OPTIONS = "SERVER_OPTIONS"

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.contracts.ts

@@ -0,0 +1,5 @@
+/** The params of a public operation (no caller is identified): the request as the transport mapped it. */
+export interface PublicExecuteParams<T> {
+    /** The request mapped by the transport. */
+    readonly request: T
+}

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.decorators.ts

@@ -0,0 +1,9 @@
+import { CommandBus, QueryBus } from "@nestjs/cqrs"
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+
+/** Injects the command bus. Parameter type: CommandBus. */
+export const InjectCommandBus = (): TypedParameterDecorator<CommandBus> => injector<CommandBus>(CommandBus)
+
+/** Injects the query bus. Parameter type: QueryBus. */
+export const InjectQueryBus = (): TypedParameterDecorator<QueryBus> => injector<QueryBus>(QueryBus)

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.handler.ts

@@ -0,0 +1,27 @@
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { CqrsLogEvent } from "./cqrs.log-events"
+
+/**
+ * The template every command and query handler extends. `execute` is what `@nestjs/cqrs` calls: it delegates to the
+ * handler `process` and, when that throws, logs `OperationFailed` with the operation name and rethrows. A handler
+ * implements `process` and never overrides `execute`. It does not `implements ICommandHandler`: since `@nestjs/cqrs` 11
+ * that type is conditional on the message result type, which a class cannot implement; `@CommandHandler` and
+ * `@QueryHandler` check the shape where they are applied.
+ */
+export abstract class ICQRSHandler<TMessage, TResult> {
+    constructor(@InjectLogger() private readonly logger: Logger) {}
+
+    /** The bus entry point. */
+    async execute(message: TMessage): Promise<TResult> {
+        try {
+            return await this.process(message)
+        } catch (error) {
+            this.logger.error(CqrsLogEvent.OperationFailed, error, { operation: this.constructor.name })
+            throw error
+        }
+    }
+
+    /** The one call of the handler: it hands the mapped message to one method of one service and returns the answer. */
+    protected abstract process(message: TMessage): Promise<TResult>
+}

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.log-events.ts

@@ -0,0 +1,5 @@
+/** Log events of the cqrs capability. */
+export enum CqrsLogEvent {
+    /** A handler threw; the operation name rides in the fields and the failure is the cause. */
+    OperationFailed = "cqrs.operation.failed",
+}

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.module-definition.ts

@@ -0,0 +1,7 @@
+import { ConfigurableModuleBuilder } from "@nestjs/common"
+import type { CqrsOptions } from "./cqrs.options"
+
+/** The configurable-module base of the cqrs capability; `isGlobal` is decided by the app root. */
+export const { ConfigurableModuleClass, OPTIONS_TYPE } = new ConfigurableModuleBuilder<CqrsOptions>()
+    .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+    .build()

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.module.ts

@@ -0,0 +1,18 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { CqrsModule as NestCqrsModule } from "@nestjs/cqrs"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./cqrs.module-definition"
+
+@Module({})
+/** Provides the command and query buses; the handlers of every feature register themselves with them. */
+export class CqrsModule extends ConfigurableModuleClass {
+    /** Registers the capability once per app. */
+    static register(options: typeof OPTIONS_TYPE): DynamicModule {
+        const base = super.register(options)
+        return {
+            ...base,
+            imports: [...(base.imports ?? []), NestCqrsModule.forRoot()],
+            exports: [NestCqrsModule],
+        }
+    }
+}

package/templates/be/skeleton/src/modules/platform/cqrs/cqrs.options.ts

@@ -0,0 +1,2 @@
+/** The cqrs capability takes no options; the empty record keeps `isGlobal` assignable through the configurable module. */
+export type CqrsOptions = Record<never, never>

package/templates/be/skeleton/src/modules/platform/cqrs/index.ts

@@ -0,0 +1,4 @@
+export type { PublicExecuteParams } from "./cqrs.contracts"
+export { InjectQueryBus } from "./cqrs.decorators"
+export { ICQRSHandler } from "./cqrs.handler"
+export { CqrsModule } from "./cqrs.module"

package/templates/be/skeleton/src/modules/platform/errors/error.filter.ts

@@ -1,23 +1,19 @@
-import { ArgumentsHost, Catch, ExceptionFilter, HttpException, HttpStatus } from "@nestjs/common"
+import { Catch, HttpException, HttpStatus } from "@nestjs/common"
+import type { ArgumentsHost, ExceptionFilter } from "@nestjs/common"
 import type { Response } from "express"
-import { Logger, LogId } from "@modules/platform/logging"
-import { DomainError } from "./domain-error"
+import { InjectLogger } from "@modules/platform/logging"
+import type { Logger } from "@modules/platform/logging"
+import { ErrorsLogEvent } from "./errors.log-events"
 
-/** What a log line says about a failure: its name and code, never the stack or the request. */
-const describeFailure = (exception: unknown): Readonly<Record<string, unknown>> =>
-    exception instanceof DomainError
-        ? { name: exception.name, code: exception.code }
-        : { name: exception instanceof Error ? exception.name : typeof exception }
-
-/** The one filter of an app: logs every failure once and answers with a status and a code that reveal nothing else. */
 @Catch()
+/** The one filter of an app: logs every failure once and answers with a status and a code that reveal nothing else. */
 export class ErrorFilter implements ExceptionFilter {
-    constructor(private readonly logger: Logger) {}
+    constructor(@InjectLogger() private readonly logger: Logger) {}
 
     /** Answers the request; an unknown failure is a 500 whose body names no detail. */
     catch(exception: unknown, host: ArgumentsHost): void {
         const status = exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR
-        this.logger.error(LogId.RequestFailed, { status, failure: describeFailure(exception) })
+        this.logger.error(ErrorsLogEvent.RequestFailed, exception, { status })
         const code = status === HttpStatus.INTERNAL_SERVER_ERROR ? "internal_error" : `http_${status}`
         host.switchToHttp().getResponse<Response>().status(status).json({ code })
     }

package/templates/be/skeleton/src/modules/platform/errors/errors.log-events.ts

@@ -0,0 +1,5 @@
+/** Log events of the errors capability. */
+export enum ErrorsLogEvent {
+    /** A request ended in a failure the app's filter answered. */
+    RequestFailed = "http.request_failed",
+}

package/templates/be/skeleton/src/modules/platform/errors/index.ts

@@ -1,2 +1,2 @@
-export { DomainError } from "./domain-error"
+export { DomainError } from "./domain.error"
 export { ErrorFilter } from "./error.filter"