@zaaxch/tailframe 4.0.4 → 4.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zaaxch/tailframe",
-	"version": "4.0.4",
+	"version": "4.0.5",
 	"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" } : {})
@@ -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);
@@ -480,7 +483,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 +499,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 +548,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." : ""}
 

package/src/owned-sources.mjs

@@ -5,6 +5,7 @@ import {
 	csrfSource,
 	firebaseSource,
 	httpErrorsSource,
+	loggerSource,
 	mongoUsersSource,
 	rateLimitSource,
 	readEnvSource,
@@ -77,6 +78,11 @@ 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 +97,50 @@ 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 +233,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,9 @@ 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 +498,8 @@ 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 +568,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 +636,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 +657,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;
+	}
 }
 `;
 }