@zaaxch/tailframe 4.0.4 → 4.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "4.0.4",
+	"version": "4.0.6",
 	"description": "Tailframe architecture toolkit: validates the Tailframe structure, import-boundary, and file-convention contracts. The package version is the contract version.",
 	"type": "module",
 	"bin": {

package/src/new.mjs

@@ -18,6 +18,7 @@ import {
 	healthRoutesSource,
 	healthSchemasSource,
 	httpErrorsSource,
+	observabilitySource,
 	mongoReadinessProbeSource,
 	postgresReadinessProbeSource,
 	readinessProbeSource,
@@ -221,6 +222,7 @@ const svcDeps = {
 	joi: "^17.13.3",
 	"reflect-metadata": "^0.2.2",
 	tsyringe: "^4.9.1",
+	winston: "^3.19.0",
 	...(postgres ? { pg: "^8.16.3" } : { mongodb: "^6.17.0" }),
 	...(options.auth === "firebase" ? { "firebase-admin": "^13.0.0" } : {}),
 	...(options.redis ? { "rate-limiter-flexible": "^11.2.0", redis: "^5.10.0" } : {})
@@ -290,7 +292,7 @@ export const env = {
 	firebaseServiceAccountPath: process.env.FIREBASE_SERVICE_ACCOUNT_PATH,` : ""}
 	${postgres ? `postgresUri: process.env.POSTGRES_URI ?? "postgresql://${options.name}-app:development@localhost:5432/${databaseName}",` : `mongodbUri: process.env.MONGODB_URI ?? "mongodb://localhost:27017/?replicaSet=rs0&directConnection=true",
 	mongodbDbName: process.env.MONGODB_DB_NAME ?? "${databaseName}",`}
-	${options.redis ? `redisUrl: process.env.REDIS_URL ?? "redis://localhost:6379",` : ""}
+	${options.redis ? `redisUrl: process.env.REDIS_URL ?? "redis://localhost:6379"` : ""}
 };`);
 const databaseSource = postgres ? `import { Pool } from "pg";
 import { env } from "@/platform/config/env";
@@ -331,6 +333,7 @@ if (options.redis) add(`${svc}/src/platform/redis/index.ts`, redisSource);
 add(`${svc}/src/core/RequestContext.ts`, requestContextSource);
 add(`${svc}/src/core/UseCase.ts`, useCaseSource);
 add(`${svc}/src/core/errors.ts`, appErrorSource);
+add(`${svc}/src/app/observability.ts`, observabilitySource);
 add(`${svc}/src/platform/http/createRequestContext.ts`, createRequestContextSource(options.auth));
 if (options.auth === "firebase") add(`${svc}/src/platform/auth/firebase.ts`, firebaseSource);
 add(`${svc}/src/platform/http/rpc.ts`, rpcSource);
@@ -355,15 +358,36 @@ if (options.worker) add(`${svc}/src/worker.ts`, `import "reflect-metadata";\nimp
 add(`${svc}/src/modules/health/__tests__/GetHealth.test.ts`, getHealthTestSource);
 add(`${svc}/src/modules/health/__tests__/GetReadiness.test.ts`, getReadinessTestSource);
 add(`${svc}/src/__tests__/testDb.ts`, postgres ? `import { Pool } from "pg";
-const pool = new Pool({ connectionString: process.env.TEST_POSTGRES_URI ?? "postgresql://postgres:postgres@localhost:5433/${databaseName}_test" });
-export async function openTestDatabase() { await pool.query("SELECT 1"); return pool; }
-export async function resetTestDatabase() { await pool.query("DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public"); return pool; }
-export async function closeTestDatabase() { await pool.end(); }
+const pool = new Pool({
+	connectionString: process.env.TEST_POSTGRES_URI ?? "postgresql://postgres:postgres@localhost:5433/${databaseName}_test"
+});
+export async function openTestDatabase() {
+	await pool.query("SELECT 1");
+	return pool;
+}
+export async function resetTestDatabase() {
+	await pool.query("DROP SCHEMA IF EXISTS public CASCADE; CREATE SCHEMA public");
+	return pool;
+}
+export async function closeTestDatabase() {
+	await pool.end();
+}
 ` : `import { MongoClient } from "mongodb";
-const client = new MongoClient(process.env.TEST_MONGODB_URI ?? "mongodb://localhost:27018/?replicaSet=rs0&directConnection=true");
-export async function openTestDatabase() { await client.connect(); return client.db(process.env.TEST_MONGODB_DB_NAME ?? "${options.name.replaceAll("-", "_")}_test"); }
-export async function resetTestDatabase() { const database = await openTestDatabase(); await database.dropDatabase(); return database; }
-export async function closeTestDatabase() { await client.close(); }
+const client = new MongoClient(
+	process.env.TEST_MONGODB_URI ?? "mongodb://localhost:27018/?replicaSet=rs0&directConnection=true"
+);
+export async function openTestDatabase() {
+	await client.connect();
+	return client.db(process.env.TEST_MONGODB_DB_NAME ?? "${options.name.replaceAll("-", "_")}_test");
+}
+export async function resetTestDatabase() {
+	const database = await openTestDatabase();
+	await database.dropDatabase();
+	return database;
+}
+export async function closeTestDatabase() {
+	await client.close();
+}
 `);
 add(`${svc}/docker-compose.test.yml`, postgres ? `name: ${options.name}-test
 services:
@@ -465,13 +489,20 @@ ${csrf ? `
 ` : ""}${options.ui ? `
 	it("serves the production SPA without falling through for API paths", async () => {
 		const app = createApplication({ production: true, publicPath: path.join(__dirname, "fixtures/public") });
-		await request(app).get("/dashboard").expect(200).expect(({ text }) => expect(text).toContain("boundary-test-spa"));
+		await request(app)
+			.get("/dashboard")
+			.expect(200)
+			.expect(({ text }) => expect(text).toContain("boundary-test-spa"));
 		await request(app).get("/api/v1/does-not-exist").expect(404);
-	});
-` : ""}
+	});` : ""}
 });
 `);
-if (options.ui) add(`${svc}/src/app/__tests__/fixtures/public/index.html`, `<!doctype html><html><body><div id="app">boundary-test-spa</div></body></html>`);
+if (options.ui) add(`${svc}/src/app/__tests__/fixtures/public/index.html`, `<!doctype html>
+<html>
+	<body>
+		<div id="app">boundary-test-spa</div>
+	</body>
+</html>`);
 add(`${svc}/AGENTS.md`, `# ${title} service guidance
 
 ## Scope
@@ -480,7 +511,7 @@ These conventions apply to \`${svc}\`. This service is a modular monolith organi
 ## Architecture vocabulary
 - Use \`src/app\` for process assembly, server creation, route mounting, and dependency registration.
 - Use \`src/core\` only for small technology-neutral contracts such as \`RequestContext\` and \`UseCase\`.
-- Use \`src/platform\` for technical mechanisms such as Express, authentication, configuration, databases, Redis, and shared HTTP behavior.
+- Use \`src/platform\` for technical mechanisms such as Express, authentication, configuration, databases, Redis, structured logging, and shared HTTP behavior.
 - Use \`src/modules/<module>\` for product capabilities.
 - These are the only service architecture roots. Keep \`src/core\` flat. Put external-system adapters under \`src/platform/integrations/<provider>\`; directories immediately under \`src/app\` are limited to \`cli\`, \`jobs\`, \`mcp\`, \`scheduled-tasks\`, \`workers\`, and \`__tests__\`.
 - Inside a module, use \`use-cases/\`, \`http/\`, and tests first. Add \`domain/\` or \`persistence/\` only when behavior requires them.
@@ -496,6 +527,7 @@ These conventions apply to \`${svc}\`. This service is a modular monolith organi
 | Express route or request schema | Owning module's \`http\` |
 | Vendor or external-system adapter | \`src/platform/integrations/<provider>\` |
 | Database, Redis, authentication, or HTTP mechanism | \`src/platform\` |
+| Product-specific Winston transport | \`src/app/observability.ts\` |
 | Process lifecycle, registration, schedule, or consumer | \`src/app/<entry-point-kind>\` |
 | Cross-entry-point technology-neutral contract | Flat \`src/core\` |
 | Root executable | Bootstrap of matching \`src/app\` assembly only |
@@ -544,6 +576,7 @@ ${postgres
 - Keep optional entry-point assembly under \`src/app/<entry-point-kind>\`; root files such as \`src/server.ts\` and \`src/worker.ts\` may only bootstrap that assembly.
 - Initialize infrastructure first, then call \`registerDependencies(...)\` from every process entry point. The composition root resets the container, explicitly constructs dependencies, and registers class-token instances. Keep tsyringe, injection tokens, decorators, and container resolution out of modules and platform adapters.
 - Register routes, workers, and jobs explicitly. Shutdown paths are awaitable and close resources without forcing \`process.exit\`.
+- The canonical Winston JSON console transport logs every HTTP failure with safe request metadata. Add product-specific transports only in \`src/app/observability.ts\`; do not remove, silence, or reconfigure the canonical transport. Preserve diagnostic causes on translated errors without exposing them in client envelopes.
 - Scheduled work prevents unintended overlap, stops intake before shutdown, awaits the active run, destroys its scheduler or consumer, and only then closes Redis and database clients.
 ${options.ui ? "- In production, serve the compiled UI from `dist/public` with a non-API SPA fallback. Never return the SPA for `/api` requests." : ""}
 
@@ -654,8 +687,22 @@ import NotificationHost from "@/app/components/NotificationHost.vue";
 </script>`);
 add(`${ui}/src/app/startApplication.ts`, `import { createApp } from "vue";\nimport { createPinia } from "pinia";\nimport PrimeVue from "primevue/config";\nimport App from "@/app/App.vue";\n${options.auth === "firebase" ? 'import { configureHttp } from "@/app/configureHttp";\n' : ""}import router from "@/app/router";\nimport "@/app/styles.css";\nexport function startApplication() {\n\tconst app = createApp(App);\n\tconst pinia = createPinia();\n\tapp.use(pinia).use(PrimeVue).use(router);\n\t${options.auth === "firebase" ? "configureHttp(pinia);\n\t" : ""}app.mount("#app");\n}\n`);
 add(`${ui}/src/main.ts`, `import { startApplication } from "@/app/startApplication";\nstartApplication();\n`);
-add(`${ui}/src/app/styles.css`, `@import "tailwindcss";\n:root { font-family: Inter, ui-sans-serif, system-ui; color: #17221c; background: #f5f3ec; }\nbody { margin: 0; }`);
-add(`${ui}/src/app/__tests__/App.spec.ts`, `import { mount } from "@vue/test-utils";\nimport App from "@/app/App.vue";\ndescribe("App", () => { it("renders a router view", () => { expect(mount(App, { global: { stubs: ["RouterView", "NotificationHost"] } }).exists()).toBe(true); }); });`);
+add(`${ui}/src/app/styles.css`, `@import "tailwindcss";
+:root {
+	font-family: Inter, ui-sans-serif, system-ui;
+	color: #17221c;
+	background: #f5f3ec;
+}
+body {
+	margin: 0;
+}`);
+add(`${ui}/src/app/__tests__/App.spec.ts`, `import { mount } from "@vue/test-utils";
+import App from "@/app/App.vue";
+describe("App", () => {
+	it("renders a router view", () => {
+		expect(mount(App, { global: { stubs: ["RouterView", "NotificationHost"] } }).exists()).toBe(true);
+	});
+});`);
 add(`${ui}/AGENTS.md`, `# ${title} UI guidance
 
 ## Scope

package/src/owned-sources.mjs

@@ -5,6 +5,7 @@ import {
 	csrfSource,
 	firebaseSource,
 	httpErrorsSource,
+	loggerSource,
 	mongoUsersSource,
 	rateLimitSource,
 	readEnvSource,
@@ -77,6 +78,14 @@ it("maps verified and unverified Firebase email claims and verifies only once",
 
 const errorTranslationTestSource = `import { AppError, type FailureKind } from "@/core/errors";
 import { errorHandler } from "@/platform/http/errors";
+import { logger } from "@/platform/logging/logger";
+
+jest.mock("@/platform/logging/logger", () => ({
+	logger: { log: jest.fn() },
+	serializeError: (error: unknown) => error
+}));
+
+const log = logger.log as jest.MockedFunction<typeof logger.log>;
 
 const statuses: Array<[FailureKind, number]> = [
 	["invalid", 400],
@@ -91,11 +100,58 @@ const statuses: Array<[FailureKind, number]> = [
 ];
 
 it.each(statuses)("translates %s to HTTP %i", (kind, status) => {
+	log.mockClear();
 	const json = jest.fn();
 	const response = { status: jest.fn(() => ({ json })) } as never;
-	errorHandler(new AppError("CODE", "message", kind), {} as never, response, jest.fn());
+	const request = { method: "POST", path: "/health.get", requestContext: { requestId: "request-1" } } as never;
+	errorHandler(new AppError({ code: "CODE", message: "message", kind }), request, response, jest.fn());
 	expect((response as { status: jest.Mock }).status).toHaveBeenCalledWith(status);
 	expect(json).toHaveBeenCalledWith({ error: { code: "CODE", message: "message" } });
+	expect(log).toHaveBeenCalledWith(
+		expect.objectContaining({
+			level: status >= 500 ? "error" : "warn",
+			event: "http.request.failed",
+			requestId: "request-1",
+			code: "CODE",
+			kind
+		})
+	);
+});
+
+it("logs an unknown failure without exposing it to the client", () => {
+	log.mockClear();
+	const json = jest.fn();
+	const response = { status: jest.fn(() => ({ json })) } as never;
+	const error = new Error("database disconnected");
+	errorHandler(error, { method: "POST", path: "/health.get" } as never, response, jest.fn());
+	expect(json).toHaveBeenCalledWith({ error: { code: "INTERNAL", message: "Internal server error" } });
+	expect(log).toHaveBeenCalledWith(
+		expect.objectContaining({
+			level: "error",
+			code: "INTERNAL",
+			error: expect.objectContaining({ message: "database disconnected" })
+		})
+	);
+});
+
+it("logs a preserved application-error cause", () => {
+	log.mockClear();
+	const json = jest.fn();
+	const response = { status: jest.fn(() => ({ json })) } as never;
+	const cause = new Error("Firebase token verification failed");
+	errorHandler(
+		AppError.unauthenticated(cause),
+		{ method: "POST", path: "/health.get" } as never,
+		response,
+		jest.fn()
+	);
+	expect(log).toHaveBeenCalledWith(
+		expect.objectContaining({
+			error: expect.objectContaining({
+				cause: expect.objectContaining({ message: "Firebase token verification failed" })
+			})
+		})
+	);
 });
 `;
 
@@ -188,6 +244,7 @@ export function ownedSources(config) {
 			"src/core/errors.ts": appErrorSource,
 			"src/core/SchemaLifecycle.ts": schemaLifecycleSource,
 			"src/platform/config/readEnv.ts": readEnvSource,
+			"src/platform/logging/logger.ts": loggerSource,
 			"src/platform/http/createRequestContext.ts": createRequestContextSource(profiles.has("firebase") ? "firebase" : "none"),
 			"src/platform/http/csrf.ts": csrfSource,
 			"src/platform/http/errors.ts": httpErrorsSource,

package/src/service-templates.mjs

@@ -43,20 +43,61 @@ export const appErrorSource = `export type FailureKind =
 	| "unavailable"
 	| "internal";
 
+export interface AppErrorOptions {
+	code: string;
+	message: string;
+	kind: FailureKind;
+	details?: unknown;
+	cause?: unknown;
+}
+
 export class AppError extends Error {
 	readonly name = "AppError";
+	readonly code: string;
+	readonly kind: FailureKind;
+	readonly details: unknown;
+
+	constructor({ code, message, kind, details, cause }: AppErrorOptions) {
+		super(message, cause === undefined ? undefined : { cause });
+		this.code = code;
+		this.kind = kind;
+		this.details = details;
+	}
 
-	constructor(
-		readonly code: string,
-		message: string,
-		readonly kind: FailureKind,
-		readonly details?: unknown
-	) {
-		super(message);
+	static unauthenticated(cause?: unknown): AppError {
+		return new AppError({ code: "UNAUTHENTICATED", message: "Unauthorized", kind: "unauthenticated", cause });
 	}
 }
 `;
 
+export const loggerSource = `import { createLogger, format, transports } from "winston";
+
+export function serializeError(error: unknown, depth = 0): unknown {
+	if (!(error instanceof Error)) return error;
+	return {
+		name: error.name,
+		message: error.message,
+		stack: error.stack,
+		...(error.cause === undefined || depth >= 3 ? {} : { cause: serializeError(error.cause, depth + 1) })
+	};
+}
+
+const serializeErrorMetadata = format((info) => {
+	if (info.error !== undefined) info.error = serializeError(info.error);
+	return info;
+});
+
+/**
+ * The service-wide logger. Tailframe always retains the JSON console transport so
+ * canonical failure logging cannot be disabled by application assembly.
+ */
+export const logger = createLogger({
+	level: "info",
+	format: format.combine(format.timestamp(), format.errors({ stack: true }), serializeErrorMetadata(), format.json()),
+	transports: [new transports.Console()]
+});
+`;
+
 export function createRequestContextSource(auth) {
 	if (auth === "firebase") {
 		return `import { randomUUID } from "node:crypto";
@@ -88,7 +129,7 @@ export async function createRequestContext(req: Request): Promise<RequestContext
 		return context;
 	}
 	if (!/^Bearer [^\\s]+$/.test(header)) {
-		throw new AppError("UNAUTHENTICATED", "Unauthorized", "unauthenticated");
+		throw AppError.unauthenticated();
 	}
 
 	try {
@@ -99,8 +140,8 @@ export async function createRequestContext(req: Request): Promise<RequestContext
 		};
 		req.requestContext = context;
 		return context;
-	} catch {
-		throw new AppError("UNAUTHENTICATED", "Unauthorized", "unauthenticated");
+	} catch (error) {
+		throw AppError.unauthenticated(error);
 	}
 }
 
@@ -200,9 +241,10 @@ export function rpcHandler<Input, Output, WireInput = Input>(
 }
 `;
 
-export const httpErrorsSource = `import type { ErrorRequestHandler } from "express";
+export const httpErrorsSource = `import type { ErrorRequestHandler, Request } from "express";
 import Joi from "joi";
 import { AppError } from "@/core/errors";
+import { logger, serializeError } from "@/platform/logging/logger";
 
 const statusByKind: Readonly<Record<AppError["kind"], number>> = {
 	invalid: 400,
@@ -216,9 +258,26 @@ const statusByKind: Readonly<Record<AppError["kind"], number>> = {
 	internal: 500
 };
 
-export const errorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
+function logFailure(req: Request, error: unknown, status: number, code: string, kind?: AppError["kind"]) {
+	logger.log({
+		level: status >= 500 ? "error" : "warn",
+		message: "HTTP request failed",
+		event: "http.request.failed",
+		requestId: req.requestContext?.requestId,
+		method: req.method,
+		path: req.path,
+		status,
+		code,
+		...(kind === undefined ? {} : { kind }),
+		error: serializeError(error)
+	});
+}
+
+export const errorHandler: ErrorRequestHandler = (error, req, res, _next) => {
 	if (error instanceof AppError) {
-		res.status(statusByKind[error.kind]).json({
+		const status = statusByKind[error.kind];
+		logFailure(req, error, status, error.code, error.kind);
+		res.status(status).json({
 			error: {
 				code: error.code,
 				message: error.message,
@@ -228,6 +287,7 @@ export const errorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
 		return;
 	}
 	if (Joi.isError(error)) {
+		logFailure(req, error, 400, "VALIDATION_FAILED", "invalid");
 		res.status(400).json({
 			error: {
 				code: "VALIDATION_FAILED",
@@ -237,11 +297,22 @@ export const errorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
 		});
 		return;
 	}
-	console.error(error);
+	logFailure(req, error, 500, "INTERNAL", "internal");
 	res.status(500).json({ error: { code: "INTERNAL", message: "Internal server error" } });
 };
 `;
 
+export const observabilitySource = `import type { Logger } from "winston";
+
+/**
+ * Add product-specific Winston transports here. Do not remove or reconfigure the
+ * Tailframe console transport: it is the required baseline for canonical errors.
+ */
+export function configureObservability(_logger: Pick<Logger, "add">): void {
+	// Add product-specific transports and leave the canonical console transport intact.
+}
+`;
+
 export const csrfSource = `import type { RequestHandler } from "express";
 import { AppError } from "@/core/errors";
 
@@ -255,7 +326,7 @@ export function csrfHeaderGuard(exemptPaths: readonly string[] = []): RequestHan
 			!exempt.has(req.path) &&
 			req.headers["x-requested-with"] !== "XMLHttpRequest"
 		) {
-			next(new AppError("CSRF_HEADER_MISSING", "CSRF header missing", "forbidden"));
+			next(new AppError({ code: "CSRF_HEADER_MISSING", message: "CSRF header missing", kind: "forbidden" }));
 			return;
 		}
 		next();
@@ -271,6 +342,7 @@ export const schemaLifecycleSource = `export interface SchemaLifecycle {
 
 export const applySchemaCliSource = `import "reflect-metadata";
 import { schemaLifecycle } from "@/app/schema";
+import { logger } from "@/platform/logging/logger";
 
 async function main() {
 	try {
@@ -281,7 +353,7 @@ async function main() {
 }
 
 void main().catch((error) => {
-	console.error(error instanceof Error ? error.message : error);
+	logger.error("Schema application failed", { event: "schema.apply.failed", error });
 	process.exitCode = 1;
 });
 `;
@@ -343,9 +415,17 @@ export function createRateLimiter(client: RedisClientType, policy: RateLimitPoli
 			next();
 		} catch (error) {
 			if (error instanceof RateLimiterRes)
-				next(new AppError("RATE_LIMITED", "Too many requests", "rate_limited"));
+				next(new AppError({ code: "RATE_LIMITED", message: "Too many requests", kind: "rate_limited" }));
 			else if (error instanceof AppError) next(error);
-			else next(new AppError("RATE_LIMIT_UNAVAILABLE", "Request protection unavailable", "unavailable"));
+			else
+				next(
+					new AppError({
+						code: "RATE_LIMIT_UNAVAILABLE",
+						message: "Request protection unavailable",
+						kind: "unavailable",
+						cause: error
+					})
+				);
 		}
 	};
 }
@@ -426,8 +506,13 @@ export class GetReadiness implements UseCase<Record<string, never>, ReadinessRes
 		try {
 			await Promise.all(this.probes.map((probe) => probe.check()));
 			return { status: "ready" };
-		} catch {
-			throw new AppError("NOT_READY", "Service is not ready", "unavailable");
+		} catch (error) {
+			throw new AppError({
+				code: "NOT_READY",
+				message: "Service is not ready",
+				kind: "unavailable",
+				cause: error
+			});
 		}
 	}
 }
@@ -496,9 +581,10 @@ export class RedisReadinessProbe implements ReadinessProbe {
 
 export const redisSource = `import { createClient, type RedisClientType } from "redis";
 import { env } from "@/platform/config/env";
+import { logger } from "@/platform/logging/logger";
 
 export const redis: RedisClientType = createClient({ url: env.redisUrl });
-redis.on("error", (error) => console.error("Redis client error", error));
+redis.on("error", (error) => logger.error("Redis client error", { event: "redis.client.error", error }));
 
 export async function connectRedis() {
 	if (!redis.isOpen) await redis.connect();
@@ -563,10 +649,12 @@ export function serverSource({ ui, redis, csrf }) {
 	return `${ui ? 'import path from "node:path";\n' : ""}import express from "express";
 import cors from "cors";
 import { registerDependencies } from "@/app/container";
+import { configureObservability } from "@/app/observability";
 import { applicationRoutes } from "@/app/routes";
 import { env } from "@/platform/config/env";
 import { closeDatabase, connectDatabase } from "@/platform/database";
 ${redis ? 'import { closeRedis, connectRedis } from "@/platform/redis";\n' : ""}${csrf ? 'import { csrfHeaderGuard } from "@/platform/http/csrf";\n' : ""}import { errorHandler } from "@/platform/http/errors";
+import { logger } from "@/platform/logging/logger";
 
 export interface ApplicationOptions {
 ${ui ? "\tpublicPath?: string;\n\tproduction?: boolean;\n" : ""}}
@@ -582,43 +670,57 @@ ${ui ? '\tif (production) {\n\t\tapp.get(/^(?!\\/api(?:\\/|$)).*/, (_req, res) =
 }
 
 export async function startServer() {
-	const db = await connectDatabase();
-${redis ? "\tconst redis = await connectRedis();\n" : ""}	registerDependencies({ db${redis ? ", redis" : ""} });
-	const app = createApplication();
-	const server = app.listen(env.port);
-	const shutdown = async () => {
-		await new Promise<void>((resolve, reject) => {
-			server.close((error) => (error ? reject(error) : resolve()));
-		});
-${redis ? "\t\tawait closeRedis();\n" : ""}		await closeDatabase();
-	};
-	process.once("SIGINT", () => void shutdown());
-	process.once("SIGTERM", () => void shutdown());
-	return { app, server, shutdown };
+	try {
+		configureObservability(logger);
+		const db = await connectDatabase();
+${redis ? "\t\tconst redis = await connectRedis();\n" : ""}		registerDependencies({ db${redis ? ", redis" : ""} });
+		const app = createApplication();
+		const server = app.listen(env.port);
+		const shutdown = async () => {
+			await new Promise<void>((resolve, reject) => {
+				server.close((error) => (error ? reject(error) : resolve()));
+			});
+${redis ? "\t\t\tawait closeRedis();\n" : ""}			await closeDatabase();
+		};
+		process.once("SIGINT", () => void shutdown());
+		process.once("SIGTERM", () => void shutdown());
+		return { app, server, shutdown };
+	} catch (error) {
+		logger.error("Server startup failed", { event: "server.start.failed", error });
+		throw error;
+	}
 }
 `;
 }
 
 export function workerSource() {
 	return `import { container, registerDependencies } from "@/app/container";
+import { configureObservability } from "@/app/observability";
 import { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
 import { closeDatabase, connectDatabase } from "@/platform/database";
 import { systemRequestContext } from "@/platform/http/createRequestContext";
+import { logger } from "@/platform/logging/logger";
 import { closeRedis, connectRedis } from "@/platform/redis";
 
 export async function startWorker() {
-	const db = await connectDatabase();
-	const redis = await connectRedis();
-	registerDependencies({ db, redis });
-	await container.resolve(GetReadiness).execute(systemRequestContext(), {});
-
-	const shutdown = async () => {
-		await closeRedis();
-		await closeDatabase();
-	};
-	process.once("SIGINT", () => void shutdown());
-	process.once("SIGTERM", () => void shutdown());
-	return { shutdown };
+	try {
+		configureObservability(logger);
+		const db = await connectDatabase();
+		const redis = await connectRedis();
+		registerDependencies({ db, redis });
+		await container.resolve(GetReadiness).execute(systemRequestContext(), {});
+
+		const shutdown = async () => {
+			await closeRedis();
+			await closeDatabase();
+		};
+		process.once("SIGINT", () => void shutdown());
+		process.once("SIGTERM", () => void shutdown());
+		return { shutdown };
+	} catch (error) {
+		logger.error("Worker startup failed", { event: "worker.start.failed", error });
+		throw error;
+	}
 }
 `;
 }