@starci/hfs 4.2.17 → 4.4.0

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.spec.ts

@@ -6,21 +6,22 @@ import { createJsonLogger, JsonLoggerService } from "./json-logger.service"
 import { LOG_ERR, LOG_OUT } from "./logging.decorators"
 import { LoggingLogEvent } from "./logging.log-events"
 
+type WrittenLine = { stream: "out" | "err"; line: string }
+
+const readJsonLine = (line: string | undefined): Record<string, unknown> => {
+    try {
+        const entry: Record<string, unknown> = JSON.parse(line ?? "")
+        return entry
+    } catch (error) {
+        throw error
+    }
+}
+
 const build = async () => {
     const clock = new FakeClock("2026-05-06T07:08:09.000Z")
-    const written: Array<{ stream: "out" | "err"; line: string }> = []
-    const out = mock<Writable>({
-        write: (chunk: string) => {
-            written.push({ stream: "out", line: chunk })
-            return true
-        },
-    })
-    const err = mock<Writable>({
-        write: (chunk: string) => {
-            written.push({ stream: "err", line: chunk })
-            return true
-        },
-    })
+    const written: Array<WrittenLine> = []
+    const out = mock<Writable>({ write: (chunk: string) => written.push({ stream: "out", line: chunk }) > 0 })
+    const err = mock<Writable>({ write: (chunk: string) => written.push({ stream: "err", line: chunk }) > 0 })
     const moduleRef = await Test.createTestingModule({
         providers: [
             JsonLoggerService,
@@ -33,84 +34,107 @@ const build = async () => {
 }
 
 describe("JsonLoggerService", () => {
-    it("writes an info line to the out stream stamped by the clock", async () => {
+    it("writes one info JSON line to stdout stamped by the clock", async () => {
         const { logger, written } = await build()
-
         logger.info("cart.opened", { personId: "p-1" })
-
         expect(written).toEqual([
             {
                 stream: "out",
-                line: `${JSON.stringify({ level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z", personId: "p-1" })}\n`,
+                line: `${JSON.stringify({ personId: "p-1", level: "info", event: "cart.opened", time: "2026-05-06T07:08:09.000Z" })}\n`,
             },
         ])
     })
 
-    it("writes a warn line without fields to the err stream", async () => {
+    it("writes a warning without caller fields to stderr", async () => {
         const { logger, clock, written } = await build()
         clock.advance(1000)
-
         logger.warn(LoggingLogEvent.StartupFailed)
-
-        expect(written).toEqual([
-            {
-                stream: "err",
-                line: `${JSON.stringify({ level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:10.000Z" })}\n`,
-            },
-        ])
+        expect(readJsonLine(written[0]?.line)).toEqual({
+            level: "warn",
+            event: LoggingLogEvent.StartupFailed,
+            time: "2026-05-06T07:08:10.000Z",
+        })
+        expect(written[0]?.stream).toBe("err")
     })
+})
 
-    it("writes an error line with the name and message of an Error cause", async () => {
+describe("JsonLoggerService error details", () => {
+    it("retains the error name, message and stack without dumping the Error object", async () => {
         const { logger, written } = await build()
-
-        logger.error("db.failed", new TypeError("boom"), { operation: "PlaceOrderHandler" })
-
-        expect(written).toEqual([
-            {
-                stream: "err",
-                line: `${JSON.stringify({
-                    level: "error",
-                    event: "db.failed",
-                    time: "2026-05-06T07:08:09.000Z",
-                    errorName: "TypeError",
-                    errorMessage: "boom",
-                    operation: "PlaceOrderHandler",
-                })}\n`,
-            },
-        ])
+        const cause = new TypeError("boom")
+        logger.error("db.failed", cause, { operation: "PlaceOrderHandler" })
+        expect(readJsonLine(written[0]?.line)).toEqual({
+            operation: "PlaceOrderHandler",
+            errorName: "TypeError",
+            errorMessage: "boom",
+            stack: cause.stack,
+            level: "error",
+            event: "db.failed",
+            time: "2026-05-06T07:08:09.000Z",
+        })
+        expect(written[0]?.stream).toBe("err")
     })
 
-    it("writes an error line with the text of a cause that is not an Error", async () => {
+    it("retains an error's code, including zero, and protects cause details from caller fields", async () => {
         const { logger, written } = await build()
+        const cause = Object.assign(new Error("connection lost"), { code: 0 })
+        logger.error("db.failed", cause, { errorName: "fake", errorMessage: "fake", errorCode: "fake", stack: "fake" })
+        expect(readJsonLine(written[0]?.line)).toEqual({
+            errorName: "Error",
+            errorMessage: "connection lost",
+            errorCode: 0,
+            stack: cause.stack,
+            level: "error",
+            event: "db.failed",
+            time: "2026-05-06T07:08:09.000Z",
+        })
+    })
 
+    it("serializes a non-Error cause and preserves a code carried by an object cause", async () => {
+        const { logger, written } = await build()
         logger.error("db.failed", "plain failure")
-
-        expect(written).toEqual([
-            {
-                stream: "err",
-                line: `${JSON.stringify({ level: "error", event: "db.failed", time: "2026-05-06T07:08:09.000Z", errorMessage: "plain failure" })}\n`,
-            },
+        logger.error("db.failed", { code: "CONNECTION_CLOSED" })
+        logger.error("db.failed", null)
+        expect(written.map(({ line }) => readJsonLine(line).errorMessage)).toEqual([
+            "plain failure",
+            "[object Object]",
+            "null",
         ])
+        expect(readJsonLine(written[1]?.line).errorCode).toBe("CONNECTION_CLOSED")
+        expect(readJsonLine(written[0]?.line)).not.toHaveProperty("errorCode")
     })
+})
 
-    describe("createJsonLogger", () => {
-        afterEach(() => {
-            jest.restoreAllMocks()
-        })
-
-        it("builds a logger that writes info to stdout and errors to stderr, stamped by the clock", () => {
-            const lines: Array<string> = []
-            jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(`out:${String(chunk)}`) > 0)
-            jest.spyOn(process.stderr, "write").mockImplementation((chunk) => lines.push(`err:${String(chunk)}`) > 0)
-            const logger = createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"))
+describe("JsonLoggerService reserved fields", () => {
+    it("writes reserved level, event and time last so caller fields cannot forge them", async () => {
+        const { logger, written } = await build()
+        const fields = { level: "error", event: "forged", time: "1900-01-01T00:00:00Z", personId: "p-1" }
+        logger.info("cart.opened", fields)
+        logger.warn("cart.warning", fields)
+        logger.error("cart.failed", "failure", fields)
+        expect(written.map(({ line }) => readJsonLine(line).level)).toEqual(["info", "warn", "error"])
+        expect(written.map(({ line }) => readJsonLine(line).event)).toEqual([
+            "cart.opened",
+            "cart.warning",
+            "cart.failed",
+        ])
+        expect(written.every(({ line }) => readJsonLine(line).time === "2026-05-06T07:08:09.000Z")).toBe(true)
+    })
+})
 
-            logger.info(LoggingLogEvent.ServerStarted)
-            logger.warn(LoggingLogEvent.StartupFailed)
+describe("createJsonLogger", () => {
+    afterEach(() => jest.restoreAllMocks())
 
-            expect(lines).toEqual([
-                `out:${JSON.stringify({ level: "info", event: LoggingLogEvent.ServerStarted, time: "2026-05-06T07:08:09.000Z" })}\n`,
-                `err:${JSON.stringify({ level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:09.000Z" })}\n`,
-            ])
-        })
+    it("uses process stdout and stderr before the DI container exists", () => {
+        const lines: Array<string> = []
+        jest.spyOn(process.stdout, "write").mockImplementation((chunk) => lines.push(`out:${String(chunk)}`) > 0)
+        jest.spyOn(process.stderr, "write").mockImplementation((chunk) => lines.push(`err:${String(chunk)}`) > 0)
+        const logger = createJsonLogger(new FakeClock("2026-05-06T07:08:09.000Z"))
+        logger.info(LoggingLogEvent.ServerStarted)
+        logger.warn(LoggingLogEvent.StartupFailed)
+        expect(lines).toEqual([
+            `out:${JSON.stringify({ level: "info", event: LoggingLogEvent.ServerStarted, time: "2026-05-06T07:08:09.000Z" })}\n`,
+            `err:${JSON.stringify({ level: "warn", event: LoggingLogEvent.StartupFailed, time: "2026-05-06T07:08:09.000Z" })}\n`,
+        ])
     })
 })

package/templates/be/skeleton/src/modules/platform/logging/json-logger.service.ts

@@ -24,17 +24,18 @@ export class JsonLoggerService implements Logger {
         this.write("warn", this.err, event, fields)
     }
 
-    /** Writes an error line with the cause serialized by name and message. */
+    /** Writes the cause's name, message, optional error code and stack without allowing caller fields to replace them. */
     error(event: string, cause: unknown, fields?: LogFields): void {
+        const code = typeof cause === "object" && cause !== null && "code" in cause ? { errorCode: cause.code } : {}
         const detail =
             cause instanceof Error
-                ? { errorName: cause.name, errorMessage: cause.message }
+                ? { errorName: cause.name, errorMessage: cause.message, stack: cause.stack }
                 : { errorMessage: String(cause) }
-        this.write("error", this.err, event, { ...detail, ...fields })
+        this.write("error", this.err, event, { ...fields, ...detail, ...code })
     }
 
     private write(level: Level, sink: Writable, event: string, fields?: LogFields): void {
-        sink.write(`${JSON.stringify({ level, event, time: this.clock.now().toISOString(), ...fields })}\n`)
+        sink.write(`${JSON.stringify({ ...fields, level, event, time: this.clock.now().toISOString() })}\n`)
     }
 }
 

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

@@ -4,8 +4,6 @@ export enum LoggingLogEvent {
     ServerStarted = "server.started",
     /** The service failed before it could serve; the process exits non-zero. */
     StartupFailed = "server.startup_failed",
-    /** The worker started: its jobs are ticking and its consumers are polling. */
-    WorkerStarted = "worker.started",
     /** The cli app's migrate run finished; the names of the applied migrations ride in the fields. */
     MigrationsApplied = "migrations.applied",
     /** The seed command finished; the seed files it ran ride in the fields, by connection. */

package/templates/be/skeleton/src/modules/platform/primitives/outcome.mapper.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { DomainError } from "@modules/platform/errors"
 import { ok, refused, unwrapOutcome } from "./outcome.mapper"
 
@@ -5,18 +6,31 @@ type CapabilityErrorCode = "CAPABILITY_REFUSED"
 
 class CapabilityError extends DomainError<CapabilityErrorCode> {}
 
+const OUTCOME_MAPPERS: unique symbol = Symbol("primitives.outcome")
+
+type OutcomeMappers = { ok: typeof ok; refused: typeof refused; unwrapOutcome: typeof unwrapOutcome }
+
 describe("outcome mappers", () => {
+    let subject: OutcomeMappers
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: OUTCOME_MAPPERS, useFactory: () => ({ ok, refused, unwrapOutcome }) }],
+        }).compile()
+        subject = moduleRef.get<OutcomeMappers>(OUTCOME_MAPPERS)
+    })
+
     describe("ok", () => {
         it("wraps the produced value as a success", () => {
             const value = { id: "value-1" }
 
-            expect(ok(value)).toEqual({ kind: "ok", value })
+            expect(subject.ok(value)).toEqual({ kind: "ok", value })
         })
     })
 
     describe("refused", () => {
         it("wraps the capability code and display parameters as a refusal", () => {
-            expect(refused("CAPABILITY_REFUSED", { resource: "value-1" })).toEqual({
+            expect(subject.refused("CAPABILITY_REFUSED", { resource: "value-1" })).toEqual({
                 kind: "refused",
                 code: "CAPABILITY_REFUSED",
                 params: { resource: "value-1" },
@@ -24,7 +38,7 @@ describe("outcome mappers", () => {
         })
 
         it("keeps display parameters optional", () => {
-            expect(refused("CAPABILITY_REFUSED")).toEqual({
+            expect(subject.refused("CAPABILITY_REFUSED")).toEqual({
                 kind: "refused",
                 code: "CAPABILITY_REFUSED",
                 params: undefined,
@@ -34,13 +48,13 @@ describe("outcome mappers", () => {
 
     describe("unwrapOutcome", () => {
         it("returns the value of a successful outcome", () => {
-            expect(unwrapOutcome(ok("value-1"), CapabilityError)).toBe("value-1")
+            expect(subject.unwrapOutcome(subject.ok("value-1"), CapabilityError)).toBe("value-1")
         })
 
         it("turns a refusal into the capability error with its parameters", () => {
-            const outcome = refused<CapabilityErrorCode>("CAPABILITY_REFUSED", { resource: "value-1" })
+            const outcome = subject.refused<CapabilityErrorCode>("CAPABILITY_REFUSED", { resource: "value-1" })
 
-            expect(() => unwrapOutcome(outcome, CapabilityError)).toThrow(
+            expect(() => subject.unwrapOutcome(outcome, CapabilityError)).toThrow(
                 expect.objectContaining({
                     name: "CapabilityError",
                     code: "CAPABILITY_REFUSED",

package/templates/be/skeleton/src/modules/platform/primitives/sequence.policy.spec.ts

@@ -1,3 +1,4 @@
+import { Test } from "@nestjs/testing"
 import { DomainError } from "@modules/platform/errors"
 import { eachInOrder } from "./sequence.policy"
 
@@ -5,13 +6,24 @@ type SequenceErrorCode = "STEP_FAILED"
 
 class SequenceError extends DomainError<SequenceErrorCode> {}
 
+const SEQUENCE: unique symbol = Symbol("primitives.sequence")
+
 const pause = (): Promise<void> => new Promise((resolve) => setImmediate(resolve))
 
 describe("eachInOrder", () => {
+    let subject: typeof eachInOrder
+
+    beforeEach(async () => {
+        const moduleRef = await Test.createTestingModule({
+            providers: [{ provide: SEQUENCE, useFactory: () => eachInOrder }],
+        }).compile()
+        subject = moduleRef.get<typeof eachInOrder>(SEQUENCE)
+    })
+
     it("starts an item only after the one before it settled, in item order", async () => {
         const events: Array<string> = []
 
-        await eachInOrder(new Set(["a", "b", "c"]), async (item, index) => {
+        await subject(new Set(["a", "b", "c"]), async (item, index) => {
             events.push(`start ${item} ${index}`)
             await pause()
             events.push(`end ${item}`)
@@ -21,13 +33,13 @@ describe("eachInOrder", () => {
     })
 
     it("answers nothing for an empty list", async () => {
-        await expect(eachInOrder([], () => Promise.resolve())).resolves.toBeUndefined()
+        await expect(subject([], () => Promise.resolve())).resolves.toBeUndefined()
     })
 
     it("rejects with the first failure and never starts the items after it", async () => {
         const started: Array<number> = []
 
-        const run = eachInOrder([1, 2, 3], async (item) => {
+        const run = subject([1, 2, 3], async (item) => {
             started.push(item)
             await pause()
             if (item === 2) throw new SequenceError({ code: "STEP_FAILED" })
@@ -38,7 +50,7 @@ describe("eachInOrder", () => {
     })
 
     it("rejects when a step throws before it returns a promise", async () => {
-        const run = eachInOrder([1], (): Promise<void> => {
+        const run = subject([1], (): Promise<void> => {
             throw new SequenceError({ code: "STEP_FAILED" })
         })
 

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

@@ -0,0 +1,3 @@
+export type { Timer } from "./retry.port"
+export { TIMER, InjectTimer } from "./retry.decorators"
+export { RetryModule } from "./retry.module"

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

@@ -0,0 +1,9 @@
+import { injector } from "@modules/platform/composition"
+import type { TypedParameterDecorator } from "@modules/platform/composition"
+import type { Timer } from "./retry.port"
+
+/** The cancellable host timer provided by the retry capability. */
+export const TIMER: unique symbol = Symbol("platform.retry.timer")
+
+/** Injects the cancellable timer. Parameter type: Timer. */
+export const InjectTimer = (): TypedParameterDecorator<Timer> => injector<Timer>(TIMER)

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

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

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

@@ -0,0 +1,19 @@
+import { Module } from "@nestjs/common"
+import type { DynamicModule } from "@nestjs/common"
+import { TIMER } from "./retry.decorators"
+import { ConfigurableModuleClass, OPTIONS_TYPE } from "./retry.module-definition"
+import { SystemTimerService } from "./system-timer.service"
+
+@Module({})
+/** Provides the cancellable Timer port backed by the host timer API. */
+export class RetryModule 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: TIMER, useClass: SystemTimerService }],
+            exports: [TIMER],
+        }
+    }
+}

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

@@ -0,0 +1,2 @@
+/** The retry capability takes no options; the module builder supplies the app's global-scope option. */
+export type RetryOptions = Record<never, never>

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

@@ -0,0 +1,11 @@
+/** The work to run when a scheduled timer expires. */
+export type TimerCallback = () => void
+
+/** Cancels a callback that has not run yet. */
+export type CancelTimer = () => void
+
+/** Schedules bounded work without exposing the ambient host timers to consumers. */
+export interface Timer {
+    /** Schedules a callback and returns the function that cancels it. */
+    schedule(callback: TimerCallback, delayMs: number): CancelTimer
+}

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

@@ -0,0 +1,36 @@
+import { Test } from "@nestjs/testing"
+import { SystemTimerService } from "./system-timer.service"
+
+const build = async () => {
+    const moduleRef = await Test.createTestingModule({ providers: [SystemTimerService] }).compile()
+    return moduleRef.get(SystemTimerService)
+}
+
+describe("SystemTimerService", () => {
+    beforeEach(() => jest.useFakeTimers())
+    afterEach(() => jest.useRealTimers())
+
+    it("runs a callback when its delay expires", async () => {
+        const service = await build()
+        const callback = jest.fn()
+
+        service.schedule(callback, 1000)
+        await jest.advanceTimersByTimeAsync(999)
+        expect(callback).not.toHaveBeenCalled()
+        await jest.advanceTimersByTimeAsync(1)
+        expect(callback).toHaveBeenCalledTimes(1)
+        expect(jest.getTimerCount()).toBe(0)
+    })
+
+    it("cancels a scheduled callback", async () => {
+        const service = await build()
+        const callback = jest.fn()
+        const cancel = service.schedule(callback, 1000)
+
+        cancel()
+        await jest.advanceTimersByTimeAsync(1000)
+
+        expect(callback).not.toHaveBeenCalled()
+        expect(jest.getTimerCount()).toBe(0)
+    })
+})

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

@@ -0,0 +1,10 @@
+import type { CancelTimer, Timer, TimerCallback } from "./retry.port"
+
+/** The production timer: owns scheduling and cancellation through the host timer API. */
+export class SystemTimerService implements Timer {
+    /** Runs the callback after its delay unless the returned function cancels it. */
+    schedule(callback: TimerCallback, delayMs: number): CancelTimer {
+        const handle = setTimeout(callback, delayMs)
+        return () => clearTimeout(handle)
+    }
+}

package/templates/be/skeleton/src/tests/contract/http-security/http-security.contract-spec.ts

@@ -0,0 +1,54 @@
+import { EnvSource } from "@modules/platform/config"
+import { parseHttpSecurityConfig } from "@modules/platform/http-security"
+
+describe("HTTP security environment contract", () => {
+    it("defaults to development and permits a local HTTP origin", () => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({ HTTP_SECURITY_ALLOWED_ORIGINS: "http://localhost:3000" }),
+        )
+        expect(config.allowedOrigins).toEqual(["http://localhost:3000"])
+        expect(config.allowHttpOrigins).toBe(true)
+        expect(config.rateLimit).toEqual({ windowMs: 60_000, defaultLimit: 600, strictLimit: 30 })
+        expect(config.webhooks).toEqual({})
+    })
+
+    it.each(["development", "test"])("permits HTTP origins in %s", (mode) => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({ NODE_ENV: mode, HTTP_SECURITY_ALLOWED_ORIGINS: "http://localhost:3000" }),
+        )
+        expect(config.allowedOrigins).toEqual(["http://localhost:3000"])
+        expect(config.allowHttpOrigins).toBe(true)
+    })
+
+    it("trims production HTTPS origins and reads declared rate tunables", () => {
+        const config = parseHttpSecurityConfig(
+            new EnvSource({
+                NODE_ENV: "production",
+                HTTP_SECURITY_ALLOWED_ORIGINS: " https://web.example , https://admin.example:8443 ",
+                HTTP_SECURITY_RATE_WINDOW: "2s",
+                HTTP_SECURITY_RATE_DEFAULT_LIMIT: "100",
+                HTTP_SECURITY_RATE_STRICT_LIMIT: "10",
+            }),
+        )
+        expect(config.allowedOrigins).toEqual(["https://web.example", "https://admin.example:8443"])
+        expect(config.allowHttpOrigins).toBe(false)
+        expect(config.rateLimit).toEqual({ windowMs: 2_000, defaultLimit: 100, strictLimit: 10 })
+    })
+
+    it.each(["production", "staging"])("rejects HTTP origins in %s", (mode) => {
+        expect(() =>
+            parseHttpSecurityConfig(
+                new EnvSource({
+                    NODE_ENV: mode,
+                    HTTP_SECURITY_ALLOWED_ORIGINS: "http://web.example",
+                }),
+            ),
+        ).toThrow(expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }))
+    })
+
+    it("rejects an empty allowlist entry after a comma", () => {
+        expect(() =>
+            parseHttpSecurityConfig(new EnvSource({ HTTP_SECURITY_ALLOWED_ORIGINS: "https://web.example," })),
+        ).toThrow(expect.objectContaining({ code: "HTTP_SECURITY_REQUEST_INVALID" }))
+    })
+})

package/templates/be/skeleton-lite/apps/api/src/api.env.ts

@@ -0,0 +1,25 @@
+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"
+import { parseSupabaseConfig } from "@modules/integrations/supabase"
+
+/** The API environment values required before composition. */
+export interface ApiEnv {
+    /** The HTTP listener. */
+    readonly server: ReturnType<typeof parseServerConfig>
+    /** The origin allowlist and rate limits. */
+    readonly httpSecurity: ReturnType<typeof parseHttpSecurityConfig>
+    /** The least-privilege PostgreSQL connection to the Supabase project. */
+    readonly database: ReturnType<typeof parsePrimaryDatabaseConfig>
+    /** Supabase Auth, Storage and token-verification configuration. */
+    readonly supabase: ReturnType<typeof parseSupabaseConfig>
+}
+
+/** Reads the API environment; missing or invalid values fail boot, and secrets use `_FILE` first. */
+export const readApiEnv = (env: EnvSource): ApiEnv => ({
+    server: parseServerConfig(env),
+    httpSecurity: parseHttpSecurityConfig(env),
+    database: parsePrimaryDatabaseConfig(env),
+    supabase: parseSupabaseConfig(env),
+})

package/templates/be/skeleton-lite/apps/api/src/api.options.ts

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