@starci/hfs 4.2.17 → 4.3.0

package/templates/app/skeleton-lite/.sops.yaml

@@ -1,3 +1,3 @@
 # Lite secrets have encrypted twins only under .starcistacks/<environment>/secrets.
-# Set a project-owned age recipient before encrypting the first secret.
+# Run `starci app secret init` to set a project-owned age recipient before encrypting the first secret.
 creation_rules: []

package/templates/app/skeleton-lite/.starcistacks/application-stacks.yaml

@@ -0,0 +1,16 @@
+# The stack declaration of the lite app, at the app root beside be/, fe/ and .starciwork.
+# Production compute is authored for an operated environment; the starter invents no deployment.
+schema: starci/application-stacks@1
+backing:
+  supabase:
+    provider: supabase
+    managed: true
+services:
+  sonar:
+    provider: sonarqube
+    mode: local
+    qualityGate: {{sonarGate}}
+    stack:
+      owner: host
+      root: .claude/ext/sonar
+      environment: dev

package/templates/app/skeleton-lite/.starciwork/workspace.yaml

@@ -0,0 +1,9 @@
+schema: work/workspace@1
+id: {{project}}
+project: {{project}}
+description: The Work records of {{project}}, one StarCi app with its back end in be/ and its front end in fe/.
+repositories:
+  - role: be
+    name: be
+  - role: fe
+    name: fe

package/templates/app/skeleton-lite/README.md

@@ -16,7 +16,7 @@ TypeScript everywhere, NestJS in `be/`, Next.js with next-intl in `fe/`, Supabas
 - `be/`: the API, shared platform capabilities, verified identity admission, and privileged Supabase integrations.
 - `fe/`: the web app; the only Supabase client is the Auth client of `src/modules/auth`, data goes through `src/modules/api`.
 - `.starcistacks/`: value-free environment metadata and encrypted-secret custody.
-- `.starciwork/`: product workspace, brand, and shell records.
+- `.starciwork/`: `.gitignore`, `workspace.yaml` project metadata and repo roles, and optional `brand/` drawing records, references, and assets.
 
 ## Development
 
@@ -40,4 +40,6 @@ Create a forward-only migration under `supabase/migrations`, keep each table's R
 
 ## Work
 
-The product's Work records live in `.starciwork`.
+Brand records live in `.starciwork/brand/`. `.starciwork/workspace.yaml` supplies the project id and repo roles so Work tools
+can locate the app root and map brand records to the front end. Lite permits this metadata without brand records; the tree
+is required only when brand records exist, and workspace metadata remains optional.

package/templates/app/starciwork.gitignore-lite

@@ -0,0 +1,6 @@
+# StarCi lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore).
+# Runtime output lives in runtime.sqlite rows and blobs outside the repository.
+/*
+!/.gitignore
+!/workspace.yaml
+!/brand/

package/templates/be/inbox/database-client.spec.ts.tpl

@@ -2,46 +2,41 @@ import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
 import type { EntityManager } from "typeorm"
 import { sql } from "./database.sql"
 import { DatabaseErrorCode } from "./errors/database.error"
-import { acceptWebhookDelivery } from "./webhook-inbox.client"
+import { recordWebhookDelivery } from "./webhook-inbox.client"
 
-// The client runs whatever claim and completion statements its caller owns; opaque function calls stand in for them here.
-const INSERT = sql`SELECT id FROM claim_spec_inbox($1, $2, $3::jsonb)`
-const COMPLETE = sql`SELECT id FROM complete_spec_inbox($1)`
+// The caller owns the conflict-safe pending-row insert; an opaque function call stands in for it here.
+const INSERT = sql`SELECT id FROM record_spec_inbox($1, $2, $3::jsonb)`
 const PAYLOAD = { id: "delivery-1" }
 
-const accept = (entityManager: EntityManager, deliveryId: string | undefined, process: (manager: EntityManager) => Promise<void>) =>
-    acceptWebhookDelivery({ entityManager, insert: INSERT, complete: COMPLETE, provider: "spec", deliveryId, payload: PAYLOAD, process })
+const record = (entityManager: EntityManager, deliveryId: string | undefined) =>
+    recordWebhookDelivery({ entityManager, insert: INSERT, provider: "spec", deliveryId, payload: PAYLOAD })
 
-describe("acceptWebhookDelivery", () => {
-    it("claims a new delivery, processes it and marks it complete in one committed transaction", async () => {
-        const transaction = fakeTransaction(mockEntityManager({ query: [[INSERT, [{ id: "inbox-1" }]], [COMPLETE, [{ id: "inbox-1" }]]] }))
-        const process = jest.fn<Promise<void>, [EntityManager]>().mockResolvedValue(undefined)
+describe("recordWebhookDelivery", () => {
+    it("records a new delivery and commits before any business processing", async () => {
+        const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, [{ id: "inbox-1" }]] }))
 
-        await accept(transaction.em, "  delivery-1  ", process)
+        await record(transaction.em, "  delivery-1  ")
 
-        expect(process).toHaveBeenCalledTimes(1)
+        expect(transaction.em.query).toHaveBeenCalledTimes(1)
         expect(transaction.em.query).toHaveBeenCalledWith(INSERT, ["spec", "delivery-1", JSON.stringify(PAYLOAD)])
-        expect(transaction.em.query).toHaveBeenCalledWith(COMPLETE, ["inbox-1"])
         expect(transaction.commits).toBe(1)
     })
 
-    it("acknowledges a duplicate without processing it again", async () => {
+    it("acknowledges a duplicate without any completion or business write", async () => {
         const transaction = fakeTransaction(mockEntityManager({ query: [INSERT, []] }))
-        const process = jest.fn<Promise<void>, [EntityManager]>()
 
-        await accept(transaction.em, "delivery-1", process)
+        await record(transaction.em, "delivery-1")
 
-        expect(process).not.toHaveBeenCalled()
         expect(transaction.em.query).toHaveBeenCalledTimes(1)
+        expect(transaction.commits).toBe(1)
     })
 
     it.each([["no", undefined], ["a blank", "   "]])("refuses %s delivery id before opening a transaction", async (_label, deliveryId) => {
         const transaction = fakeTransaction(mockEntityManager())
-        const process = jest.fn<Promise<void>, [EntityManager]>()
 
-        await expect(accept(transaction.em, deliveryId, process)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
+        await expect(record(transaction.em, deliveryId)).rejects.toMatchObject({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
 
         expect(transaction.outcomes).toEqual([])
-        expect(process).not.toHaveBeenCalled()
+        expect(transaction.em.query).not.toHaveBeenCalled()
     })
 })

package/templates/be/inbox/database-client.ts.tpl

@@ -2,49 +2,34 @@ import type { EntityManager } from "typeorm"
 import { DatabaseError, DatabaseErrorCode } from "./errors/database.error"
 import type { SqlText } from "./database.sql"
 
-interface WebhookInboxStatements {
-    readonly insert: SqlText
-    readonly complete: SqlText
-}
-
-interface AcceptWebhookDelivery extends WebhookInboxStatements {
+interface RecordWebhookDelivery {
     readonly entityManager: EntityManager
+    readonly insert: SqlText
     readonly provider: string
     readonly deliveryId: string | undefined
     readonly payload: object
-    readonly process: (manager: EntityManager) => Promise<void>
-}
-
-interface InboxIdentity {
-    readonly id: string
 }
 
 /**
- * Claims and processes one delivery in one EntityManager transaction. A conflict returns without calling `process`, so
- * a redelivery receives the original empty acknowledgement and cannot repeat the domain mutation.
+ * Records one pending delivery in one EntityManager transaction. The conflict-safe insert keeps redelivery a no-op.
+ * Business processing and the completion marker belong to the reactor or job that consumes the committed row.
  */
-export const acceptWebhookDelivery = async ({
+export const recordWebhookDelivery = async ({
     entityManager,
     insert,
-    complete,
     provider,
     deliveryId,
     payload,
-    process,
-}: AcceptWebhookDelivery): Promise<void> => {
+}: RecordWebhookDelivery): Promise<void> => {
     const normalizedDeliveryId = deliveryId?.trim()
     if (!normalizedDeliveryId) {
         throw new DatabaseError({ code: DatabaseErrorCode.WebhookDeliveryIdRequired })
     }
     await entityManager.transaction(async (manager) => {
-        const claimed = await manager.query<Array<InboxIdentity>>(insert, [
+        await manager.query(insert, [
             provider,
             normalizedDeliveryId,
             JSON.stringify(payload),
         ])
-        const identity = claimed[0]
-        if (identity === undefined) return
-        await process(manager)
-        await manager.query(complete, [identity.id])
     })
 }

package/templates/be/inbox/service.spec.ts.tpl

@@ -1,46 +1,42 @@
-import { fakeTransaction, mock, mockEntityManager } from "@starci/jest-preset"
+import { fakeTransaction, mockEntityManager } from "@starci/jest-preset"
 import { Test } from "@nestjs/testing"
-import { @@service@@ } from "@@serviceModule@@"
 import { PRIMARY_ENTITY_MANAGER } from "@modules/platform/database"
-import { COMPLETE_@@providerUpper@@_INBOX, INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
+import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 import { @@Provider@@InboxService } from "./@@provider@@-inbox.service"
 
 const DELIVERY = { id: "delivery-1" }
 
-const build = async (claimed: ReadonlyArray<{ readonly id: string }>) => {
-    const entityManager = mockEntityManager({
-        query: [[INSERT_@@providerUpper@@_INBOX, claimed], [COMPLETE_@@providerUpper@@_INBOX, claimed]],
-    })
+const build = async (recorded: ReadonlyArray<{ readonly id: string }>) => {
+    const entityManager = mockEntityManager({ query: [INSERT_@@providerUpper@@_INBOX, recorded] })
     const transaction = fakeTransaction(entityManager)
-    const deliveries = mock<@@service@@>()
     const moduleRef = await Test.createTestingModule({
         providers: [
             @@Provider@@InboxService,
             { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },
-            { provide: @@service@@, useValue: deliveries },
         ],
     }).compile()
-    return { inbox: moduleRef.get(@@Provider@@InboxService), deliveries, transaction }
+    return { inbox: moduleRef.get(@@Provider@@InboxService), entityManager, transaction }
 }
 
 describe("@@Provider@@InboxService", () => {
-    describe("accept@@Provider@@Delivery", () => {
-        it("claims a new @@provider@@ delivery and runs the domain intake inside the claiming transaction", async () => {
-            const { inbox, deliveries, transaction } = await build([{ id: "inbox-1" }])
+    describe("record@@Provider@@Delivery", () => {
+        it("records a pending @@provider@@ delivery without business processing or a completion write", async () => {
+            const { inbox, entityManager, transaction } = await build([{ id: "inbox-1" }])
 
-            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+            await inbox.record@@Provider@@Delivery("delivery-1", DELIVERY)
 
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY, expect.anything())
+            expect(entityManager.query).toHaveBeenCalledTimes(1)
+            expect(entityManager.query).toHaveBeenCalledWith(INSERT_@@providerUpper@@_INBOX, ["@@provider@@", "delivery-1", JSON.stringify(DELIVERY)])
             expect(transaction.commits).toBe(1)
         })
 
-        it("acknowledges a duplicate @@provider@@ delivery without running the domain intake again", async () => {
-            const { inbox, deliveries } = await build([])
+        it("acknowledges a duplicate @@provider@@ delivery without further work", async () => {
+            const { inbox, entityManager, transaction } = await build([])
 
-            await inbox.accept@@Provider@@Delivery("delivery-1", DELIVERY)
+            await inbox.record@@Provider@@Delivery("delivery-1", DELIVERY)
 
-            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+            expect(entityManager.query).toHaveBeenCalledTimes(1)
+            expect(transaction.commits).toBe(1)
         })
     })
 })

package/templates/be/inbox/service.ts.tpl

@@ -1,8 +1,7 @@
 import { Injectable } from "@nestjs/common"
 import type { EntityManager } from "typeorm"
-import { @@service@@ } from "@@serviceModule@@"
-import { acceptWebhookDelivery, InjectPrimaryEntityManager } from "@modules/platform/database"
-import { COMPLETE_@@providerUpper@@_INBOX, INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
+import { InjectPrimaryEntityManager, recordWebhookDelivery } from "@modules/platform/database"
+import { INSERT_@@providerUpper@@_INBOX } from "./persistence/@@provider@@-inbox.sql"
 
 interface @@Provider@@Delivery {
     readonly id: string
@@ -11,23 +10,20 @@ interface @@Provider@@Delivery {
 type @@Provider@@DeliveryId = string | undefined
 
 @Injectable()
-/** Claims each @@provider@@ delivery once, then runs the domain intake and completion marker in the same transaction. */
+/** Records each @@provider@@ delivery once. Pending rows are consumed by a separate reactor or job after commit. */
 export class @@Provider@@InboxService {
     constructor(
         @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
-        private readonly deliveries: @@service@@,
     ) {}
 
-    /** A duplicate is acknowledged without invoking the domain intake a second time. */
-    accept@@Provider@@Delivery(deliveryId: @@Provider@@DeliveryId, delivery: @@Provider@@Delivery): Promise<void> {
-        return acceptWebhookDelivery({
+    /** A duplicate is acknowledged without creating another pending row; this intake never dispatches a command. */
+    record@@Provider@@Delivery(deliveryId: @@Provider@@DeliveryId, delivery: @@Provider@@Delivery): Promise<void> {
+        return recordWebhookDelivery({
             entityManager: this.entityManager,
             insert: INSERT_@@providerUpper@@_INBOX,
-            complete: COMPLETE_@@providerUpper@@_INBOX,
             provider: "@@provider@@",
             deliveryId,
             payload: delivery,
-            process: (manager) => this.deliveries.accept@@Provider@@Delivery(delivery, manager),
         })
     }
 }

package/templates/be/inbox/sql.ts.tpl

@@ -1,12 +1,12 @@
 import { sql } from "@modules/platform/database"
 
-/** Claims one @@provider@@ delivery and returns its durable inbox identity only to the winning transaction. */
+/** Records one pending @@provider@@ delivery and returns its durable inbox identity only to the winning transaction. */
 export const INSERT_@@providerUpper@@_INBOX = sql`INSERT INTO public.@@table@@ (provider, delivery_id, payload)
 VALUES ($1, $2, $3::jsonb)
 ON CONFLICT (provider, delivery_id) DO NOTHING
 RETURNING id`
 
-/** Marks the claimed delivery complete before the same transaction commits. */
+/** The reactor or job marks a recorded delivery complete in the transaction that applies its effect. Never called by the intake. */
 export const COMPLETE_@@providerUpper@@_INBOX = sql`WITH completed AS (
     UPDATE public.@@table@@
     SET processed_at = now()

package/templates/be/inbox/webhook-door.spec.ts.tpl

@@ -57,8 +57,8 @@ describe("@@Provider@@Webhook", () => {
 
             await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY)
 
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY_ID, DELIVERY)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY_ID, DELIVERY)
         })
 
         it("never reaches the inbox when the signature is not the provider's", async () => {
@@ -69,7 +69,7 @@ describe("@@Provider@@Webhook", () => {
                 door.receive(REQUEST, sign(Buffer.from("other body"), SIGNED_AT), SIGNED_AT, DELIVERY_ID, DELIVERY),
             ).rejects.toMatchObject({ code: "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID" })
 
-            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+            expect(deliveries.record@@Provider@@Delivery).not.toHaveBeenCalled()
         })
     })
 })

package/templates/be/inbox/webhook-door.ts.tpl

@@ -10,7 +10,8 @@ import { @@Event@@Request } from "./dto/@@event@@.request"
 @Controller("webhooks/@@provider@@")
 /**
  * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and replay window are proven
- * first; the verified delivery goes to one domain intake that claims its inbox row and processes it in one transaction.
+ * first; the verified delivery goes to one domain intake that records a pending inbox row in its transaction. A separate
+ * reactor or job consumes the committed row and dispatches the command.
  */
 export class @@Provider@@Webhook {
     constructor(
@@ -18,7 +19,7 @@ export class @@Provider@@Webhook {
         private readonly deliveries: @@Provider@@InboxService,
     ) {}
 
-    /** Acknowledges with 204 and no body: a duplicate receives the same acknowledgement without being processed again. */
+    /** Acknowledges with 204 and no body: a duplicate receives the same acknowledgement without another inbox row. */
     @Post()
     @HttpCode(HttpStatus.NO_CONTENT)
     @Public({ reason: PublicReason.SignedWebhook })
@@ -31,6 +32,6 @@ export class @@Provider@@Webhook {
         @Body() delivery: @@Event@@Request,
     ): Promise<void> {
         this.signature.verify({ provider: "@@provider@@", rawBody: request.rawBody, signature, timestamp })
-        await this.deliveries.accept@@Provider@@Delivery(deliveryId, delivery)
+        await this.deliveries.record@@Provider@@Delivery(deliveryId, delivery)
     }
 }

package/templates/be/patterns/webhooks/webhook.door.spec.ts.tpl

@@ -56,8 +56,8 @@ describe("@@Provider@@Webhook", () => {
 
             await door.receive(REQUEST, sign(RAW_BODY, SIGNED_AT), SIGNED_AT, DELIVERY)
 
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledTimes(1)
-            expect(deliveries.accept@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledTimes(1)
+            expect(deliveries.record@@Provider@@Delivery).toHaveBeenCalledWith(DELIVERY)
         })
 
         it("never reaches the intake when the signature is not the provider's", async () => {
@@ -68,7 +68,7 @@ describe("@@Provider@@Webhook", () => {
                 door.receive(REQUEST, sign(Buffer.from("other body"), SIGNED_AT), SIGNED_AT, DELIVERY),
             ).rejects.toMatchObject({ code: "HTTP_SECURITY_WEBHOOK_SIGNATURE_INVALID" })
 
-            expect(deliveries.accept@@Provider@@Delivery).not.toHaveBeenCalled()
+            expect(deliveries.record@@Provider@@Delivery).not.toHaveBeenCalled()
         })
     })
 })

package/templates/be/patterns/webhooks/webhook.door.ts.tpl

@@ -10,8 +10,8 @@ import { @@Event@@Request } from "./dto/@@event@@.request"
 @Controller("webhooks/@@provider@@")
 /**
  * POST /webhooks/@@provider@@, the signed intake door of the @@provider@@ notifier. The signature and the replay window are proven
- * first; the verified delivery goes to exactly one intake method of @@service@@ (`accept@@Provider@@Delivery`), which records it
- * once and publishes the event in its own transaction.
+ * first; the verified delivery goes to exactly one intake method of @@service@@ (`record@@Provider@@Delivery`), which records it
+ * once in the inbox and writes its outbox event in one transaction. A reactor or job dispatches the command after commit.
  */
 export class @@Provider@@Webhook {
     constructor(
@@ -31,6 +31,6 @@ export class @@Provider@@Webhook {
         @Body() delivery: @@Event@@Request,
     ): Promise<void> {
         this.signature.verify({ provider: "@@provider@@", rawBody: request.rawBody, signature, timestamp })
-        await this.deliveries.accept@@Provider@@Delivery(delivery)
+        await this.deliveries.record@@Provider@@Delivery(delivery)
     }
 }

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

@@ -2,55 +2,23 @@ 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 { AuthGuard, 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 { NoteModule } from "@modules/domain/note"
+import { ErrorsFilter } from "@modules/platform/errors"
+import { OriginGuard, RateLimitGuard } from "@modules/platform/http-security"
+import { platformModules } from "./compose/platform"
 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 three 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 }],
-                }),
+                ...platformModules(options),
                 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,42 @@
+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 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 }),
+    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/main.ts

@@ -1,18 +1,12 @@
 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 { 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),
-    }
+    const options = read{{appPascal}}Env(env)
 {{> be/common/main-listen.ts.partial}}

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,7 +1,5 @@
 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, DatabaseConnectionOptions } from "@modules/platform/database"
 
 /** Everything the cli app needs from its environment: every connection with the entities and migrations of its owners. */
 export interface CliAppOptions {
@@ -10,13 +8,13 @@ export interface CliAppOptions {
 }
 
 /** The primary database: the notes. */
-export const primaryConnectionOf = (env: EnvSource): DatabaseConnectionOptions => ({
-    ...parsePrimaryDatabaseConfig(env),
+export const primaryConnectionOf = (primary: DatabaseConnectionConfig): DatabaseConnectionOptions => ({
+    ...primary,
     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)],
+/** Binds the parsed cli configuration to each connection's entities and migrations. */
+export const createCliAppOptions = (primary: DatabaseConnectionConfig): CliAppOptions => ({
+    connections: [primaryConnectionOf(primary)],
 })

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" })