@zaaxch/tailframe 2.2.0 → 4.0.0

package/src/owned-guidance.mjs

@@ -0,0 +1,27 @@
+export const OWNED_GUIDANCE_START = "<!-- tailframe:owned:start -->";
+export const OWNED_GUIDANCE_END = "<!-- tailframe:owned:end -->";
+
+export function productGuidance(config) {
+	const apps = config.apps.map((app) => `\`${app.kind}\` at \`${app.path}\` (${app.profiles.join(", ") || "no optional profiles"})`).join("; ");
+	return `${OWNED_GUIDANCE_START}
+## Tailframe-owned product contract
+
+- Contract: \`${config.contractVersion}\`; kind: \`product\`.
+- Applications: ${apps}.
+- Run \`pnpm sync:architecture\` and \`pnpm validate:architecture\` from the product root after architectural changes.
+- The product root is the only Git, package-manager, lockfile, Tailframe-manifest, and agent-context boundary.
+- Files written by \`tailframe sync --write\` are generated sources. Change their canonical templates in Tailframe, not in this product.
+${OWNED_GUIDANCE_END}`;
+}
+
+export function appGuidance(productConfig, app) {
+	const profileList = app.profiles.length ? app.profiles.join(", ") : "none";
+	const client = app.kind !== "service";
+	return `${OWNED_GUIDANCE_START}
+## Tailframe-owned application contract
+
+- Product contract: \`${productConfig.contractVersion}\`; kind: \`${app.kind}\`; path: \`${app.path}\`; profiles: ${profileList}.
+- Run product-level validation and sync from the repository root; use \`tailframe validate --app ${app.kind}\` for a focused architecture check.
+- Keep product capabilities under \`src/modules/<module>\`; keep application assembly, technology-neutral contracts, and provider adapters in their canonical app/core/platform roots.
+${client ? "- Notifications use the Tailframe-owned application-shell queue and host. Product copy remains in the owning capability module.\n" : "- Every use case exposes \`execute(context, input)\`. Entry points construct a request or system context and pass an explicit input object.\n- Resident processes perform no DDL. \`schema:apply\` is the only schema lifecycle entry point.\n- RPC operations use \`<owning-module>.<operation>\` with no compatibility aliases.\n"}${OWNED_GUIDANCE_END}`;
+}

package/src/owned-sources.mjs

@@ -0,0 +1,222 @@
+import {
+	appErrorSource,
+	applySchemaCliSource,
+	createRequestContextSource,
+	csrfSource,
+	firebaseSource,
+	httpErrorsSource,
+	mongoUsersSource,
+	rateLimitSource,
+	readEnvSource,
+	requestContextSource,
+	rpcHandlerSource,
+	rpcSource,
+	schemaLifecycleSource,
+	useCaseSource
+} from "./service-templates.mjs";
+import {
+	notificationHostSource,
+	notificationStoreSource,
+	uiErrorMessagesSource,
+	uiErrorsSource,
+	uiHttpSource,
+	uiRpcSource
+} from "./ui-templates.mjs";
+
+const requestContextTestSource = `import type { Request } from "express";
+import { verifyFirebaseToken } from "@/platform/auth/firebase";
+import { createRequestContext } from "@/platform/http/createRequestContext";
+
+jest.mock("@/platform/auth/firebase", () => ({ verifyFirebaseToken: jest.fn() }));
+
+const verifyToken = verifyFirebaseToken as jest.MockedFunction<typeof verifyFirebaseToken>;
+const request = (headers: Request["headers"] = {}) => ({ headers }) as Request;
+
+beforeEach(() => verifyToken.mockReset());
+
+it("creates and caches an anonymous context with a bounded request id", async () => {
+	const req = request({ "x-request-id": "request.safe:1" });
+	const first = await createRequestContext(req);
+	const second = await createRequestContext(req);
+	expect(first).toEqual({ requestId: "request.safe:1" });
+	expect(second).toBe(first);
+	expect(verifyToken).not.toHaveBeenCalled();
+});
+
+it("replaces malformed and oversized request ids", async () => {
+	for (const value of ["contains spaces", "x".repeat(129)]) {
+		const context = await createRequestContext(request({ "x-request-id": value }));
+		expect(context.requestId).not.toBe(value);
+		expect(context.requestId).toMatch(/^[a-f0-9-]{36}$/);
+	}
+});
+
+it("strictly parses one Bearer token", async () => {
+	for (const authorization of ["bearer token", "Bearer", "Bearer  token", "Bearer token extra", "Basic token"]) {
+		await expect(createRequestContext(request({ authorization }))).rejects.toMatchObject({
+			code: "UNAUTHENTICATED",
+			kind: "unauthenticated"
+		});
+	}
+	expect(verifyToken).not.toHaveBeenCalled();
+});
+
+it("maps verified and unverified Firebase email claims and verifies only once", async () => {
+	verifyToken.mockResolvedValueOnce({ uid: "verified", email: "v@example.com", email_verified: true } as never);
+	const verifiedRequest = request({ authorization: "Bearer verified-token" });
+	const verified = await createRequestContext(verifiedRequest);
+	expect(verified.principal).toEqual({ uid: "verified", email: "v@example.com", emailVerified: true });
+	await createRequestContext(verifiedRequest);
+	expect(verifyToken).toHaveBeenCalledTimes(1);
+
+	verifyToken.mockResolvedValueOnce({ uid: "unverified", email: "u@example.com" } as never);
+	const unverified = await createRequestContext(request({ authorization: "Bearer unverified-token" }));
+	expect(unverified.principal).toEqual({ uid: "unverified", email: "u@example.com", emailVerified: false });
+});
+`;
+
+const errorTranslationTestSource = `import { AppError, type FailureKind } from "@/core/errors";
+import { errorHandler } from "@/platform/http/errors";
+
+const statuses: Array<[FailureKind, number]> = [
+	["invalid", 400],
+	["unauthenticated", 401],
+	["forbidden", 403],
+	["not_found", 404],
+	["conflict", 409],
+	["unprocessable", 422],
+	["rate_limited", 429],
+	["unavailable", 503],
+	["internal", 500]
+];
+
+it.each(statuses)("translates %s to HTTP %i", (kind, status) => {
+	const json = jest.fn();
+	const response = { status: jest.fn(() => ({ json })) } as never;
+	errorHandler(new AppError("CODE", "message", kind), {} as never, response, jest.fn());
+	expect((response as { status: jest.Mock }).status).toHaveBeenCalledWith(status);
+	expect(json).toHaveBeenCalledWith({ error: { code: "CODE", message: "message" } });
+});
+`;
+
+const rateLimitTestSource = `import type { Request } from "express";
+import { RateLimiterRes } from "rate-limiter-flexible";
+import { createRateLimiter } from "@/platform/http/rateLimit";
+
+const mockConsume = jest.fn();
+jest.mock("rate-limiter-flexible", () => {
+	class MockRateLimiterRes {}
+	return {
+		RateLimiterRes: MockRateLimiterRes,
+		RateLimiterRedis: jest.fn().mockImplementation(() => ({ consume: mockConsume }))
+	};
+});
+
+const policy = { keyPrefix: "test", points: 2, durationSeconds: 60, key: "identity-or-ip" as const };
+
+beforeEach(() => mockConsume.mockReset());
+
+it("uses the authenticated identity and allows a request within budget", async () => {
+	mockConsume.mockResolvedValue(undefined);
+	const request = {
+		headers: {},
+		ip: "127.0.0.1",
+		requestContext: { requestId: "test", principal: { uid: "user-1", emailVerified: false } }
+	} as Request;
+	const next = jest.fn();
+	await (createRateLimiter({} as never, policy) as never as Function)(request, {}, next);
+	expect(mockConsume).toHaveBeenCalledWith("user:user-1");
+	expect(next).toHaveBeenCalledWith();
+});
+
+it("translates exhausted and unavailable limiter failures", async () => {
+	const request = { headers: {}, ip: "127.0.0.1", requestContext: { requestId: "test" } } as Request;
+	const exhausted = jest.fn();
+	mockConsume.mockRejectedValueOnce(new RateLimiterRes());
+	await (createRateLimiter({} as never, policy) as never as Function)(request, {}, exhausted);
+	expect(exhausted.mock.calls[0]?.[0]).toMatchObject({ kind: "rate_limited", code: "RATE_LIMITED" });
+
+	const unavailable = jest.fn();
+	mockConsume.mockRejectedValueOnce(new Error("redis down"));
+	await (createRateLimiter({} as never, policy) as never as Function)(request, {}, unavailable);
+	expect(unavailable.mock.calls[0]?.[0]).toMatchObject({ kind: "unavailable", code: "RATE_LIMIT_UNAVAILABLE" });
+});
+`;
+
+const notificationTestSource = `import { mount } from "@vue/test-utils";
+import { createPinia, setActivePinia } from "pinia";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { nextTick } from "vue";
+import NotificationHost from "@/app/components/NotificationHost.vue";
+import { useNotificationStore } from "@/app/stores/notification.store";
+
+describe("notification shell", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		setActivePinia(createPinia());
+	});
+	afterEach(() => vi.useRealTimers());
+
+	it("orders, dismisses, times, and clears notifications", async () => {
+		const store = useNotificationStore();
+		const host = mount(NotificationHost);
+		const first = store.notify({ message: "first", kind: "warning", durationMs: 1000 });
+		const second = store.notify({ message: "second", kind: "success", durationMs: 1000 });
+		expect(store.active?.id).toBe(first);
+		await nextTick();
+		expect(host.text()).toContain("first");
+		vi.advanceTimersByTime(1000);
+		await nextTick();
+		expect(store.active?.id).toBe(second);
+		store.dismiss(second);
+		expect(store.active).toBeUndefined();
+		store.notify({ message: "third" });
+		store.clear();
+		expect(store.queue).toEqual([]);
+		host.unmount();
+	});
+});
+`;
+
+export function ownedSources(config) {
+	if (!["service", "ui"].includes(config.kind)) throw new Error("Tailframe 4 owns only service and UI sources");
+	const profiles = new Set(config.profiles);
+	if (config.kind === "service") {
+		const files = {
+			"src/core/RequestContext.ts": requestContextSource,
+			"src/core/UseCase.ts": useCaseSource,
+			"src/core/errors.ts": appErrorSource,
+			"src/core/SchemaLifecycle.ts": schemaLifecycleSource,
+			"src/platform/config/readEnv.ts": readEnvSource,
+			"src/platform/http/createRequestContext.ts": createRequestContextSource(profiles.has("firebase") ? "firebase" : "none"),
+			"src/platform/http/csrf.ts": csrfSource,
+			"src/platform/http/errors.ts": httpErrorsSource,
+			"src/platform/http/rpc.ts": rpcSource,
+			"src/platform/http/rpcHandler.ts": rpcHandlerSource,
+			"src/app/cli/applySchema.ts": applySchemaCliSource,
+			"src/platform/http/__tests__/errors.test.ts": errorTranslationTestSource
+		};
+		if (profiles.has("firebase")) {
+			files["src/platform/auth/firebase.ts"] = firebaseSource;
+			files["src/platform/http/__tests__/createRequestContext.test.ts"] = requestContextTestSource;
+		}
+		if (profiles.has("rate-limit")) {
+			files["src/platform/http/rateLimit.ts"] = rateLimitSource;
+			files["src/platform/http/__tests__/rateLimit.test.ts"] = rateLimitTestSource;
+		}
+		if (profiles.has("mongo")) files["deploy/mongo/10-create-users.js"] = mongoUsersSource;
+		return files;
+	}
+	const files = {
+		"src/core/errors.ts": uiErrorsSource,
+		"src/core/rpc.ts": uiRpcSource,
+		"src/platform/errors.ts": uiErrorMessagesSource,
+		"src/platform/http.ts": uiHttpSource
+	};
+	if (profiles.has("notifications")) {
+		files["src/app/stores/notification.store.ts"] = notificationStoreSource;
+		files["src/app/components/NotificationHost.vue"] = notificationHostSource;
+		files["src/app/__tests__/notificationStore.test.ts"] = notificationTestSource;
+	}
+	return files;
+}

package/src/service-templates.mjs

@@ -16,6 +16,7 @@ export function serviceOperationName(moduleName, verbNoun) {
 export const requestContextSource = `export interface AuthenticatedPrincipal {
 	uid: string;
 	email?: string;
+	emailVerified: boolean;
 }
 
 export interface RequestContext {
@@ -64,14 +65,40 @@ import type { RequestContext } from "@/core/RequestContext";
 import { AppError } from "@/core/errors";
 import { verifyFirebaseToken } from "@/platform/auth/firebase";
 
+declare global {
+	namespace Express {
+		interface Request {
+			requestContext?: RequestContext;
+		}
+	}
+}
+
+function validRequestId(value: string | undefined): value is string {
+	return Boolean(value && value.length <= 128 && /^[a-zA-Z0-9._:-]+$/.test(value));
+}
+
 export async function createRequestContext(req: Request): Promise<RequestContext> {
-	const requestId = String(req.headers["x-request-id"] ?? randomUUID());
+	if (req.requestContext) return req.requestContext;
+	const headerRequestId = typeof req.headers["x-request-id"] === "string" ? req.headers["x-request-id"] : undefined;
+	const requestId = validRequestId(headerRequestId) ? headerRequestId : randomUUID();
 	const header = req.headers.authorization;
-	if (!header?.startsWith("Bearer ")) return { requestId };
+	if (!header) {
+		const context = { requestId };
+		req.requestContext = context;
+		return context;
+	}
+	if (!/^Bearer [^\\s]+$/.test(header)) {
+		throw new AppError("UNAUTHENTICATED", "Unauthorized", "unauthenticated");
+	}
 
 	try {
 		const decoded = await verifyFirebaseToken(header.slice(7));
-		return { requestId, principal: { uid: decoded.uid, email: decoded.email } };
+		const context = {
+			requestId,
+			principal: { uid: decoded.uid, email: decoded.email, emailVerified: decoded.email_verified === true }
+		};
+		req.requestContext = context;
+		return context;
 	} catch {
 		throw new AppError("UNAUTHENTICATED", "Unauthorized", "unauthenticated");
 	}
@@ -86,8 +113,24 @@ export function systemRequestContext(requestId = "system"): RequestContext {
 import type { Request } from "express";
 import type { RequestContext } from "@/core/RequestContext";
 
+declare global {
+	namespace Express {
+		interface Request {
+			requestContext?: RequestContext;
+		}
+	}
+}
+
+function validRequestId(value: string | undefined): value is string {
+	return Boolean(value && value.length <= 128 && /^[a-zA-Z0-9._:-]+$/.test(value));
+}
+
 export async function createRequestContext(req: Request): Promise<RequestContext> {
-	return { requestId: String(req.headers["x-request-id"] ?? randomUUID()) };
+	if (req.requestContext) return req.requestContext;
+	const headerRequestId = typeof req.headers["x-request-id"] === "string" ? req.headers["x-request-id"] : undefined;
+	const context = { requestId: validRequestId(headerRequestId) ? headerRequestId : randomUUID() };
+	req.requestContext = context;
+	return context;
 }
 
 export function systemRequestContext(requestId = "system"): RequestContext {
@@ -96,13 +139,16 @@ export function systemRequestContext(requestId = "system"): RequestContext {
 `;
 }
 
-export const firebaseSource = `import { applicationDefault, getApps, initializeApp } from "firebase-admin/app";
+export const firebaseSource = `import { applicationDefault, cert, getApps, initializeApp } from "firebase-admin/app";
 import { getAuth, type DecodedIdToken } from "firebase-admin/auth";
 import { env } from "@/platform/config/env";
 
 export function verifyFirebaseToken(token: string): Promise<DecodedIdToken> {
 	if (!getApps().length) {
-		initializeApp({ credential: applicationDefault(), projectId: env.firebaseProjectId || undefined });
+		initializeApp({
+			credential: env.firebaseServiceAccountPath ? cert(env.firebaseServiceAccountPath) : applicationDefault(),
+			projectId: env.firebaseProjectId || undefined
+		});
 	}
 	return getAuth().verifyIdToken(token);
 }
@@ -127,6 +173,7 @@ interface RpcOperation<Input, Output> {
 
 export interface RpcHandlerOptions<Input, WireInput> {
 	mapInput?: (input: WireInput) => Input;
+	fromRequest?: (req: Request) => Input;
 	status?: number;
 }
 
@@ -139,7 +186,11 @@ export function rpcHandler<Input, Output, WireInput = Input>(
 	return async (req: Request, res: Response, next: NextFunction) => {
 		try {
 			const validated = await schema.validateAsync(req.body ?? {}, { abortEarly: false });
-			const input = options.mapInput ? options.mapInput(validated) : (validated as unknown as Input);
+			const input = options.fromRequest
+				? options.fromRequest(req)
+				: options.mapInput
+					? options.mapInput(validated)
+					: (validated as unknown as Input);
 			if (options.status !== undefined) res.status(options.status);
 			rpcResult(res, await operation.execute(await createRequestContext(req), input));
 		} catch (error) {
@@ -196,13 +247,152 @@ import { AppError } from "@/core/errors";
 
 const MUTATING = ["POST", "PUT", "PATCH", "DELETE"];
 
-export const requireCsrfHeader: RequestHandler = (req, _res, next) => {
-	if (MUTATING.includes(req.method) && req.headers["x-requested-with"] !== "XMLHttpRequest") {
-		next(new AppError("CSRF_HEADER_MISSING", "CSRF header missing", "forbidden"));
-		return;
+export function csrfHeaderGuard(exemptPaths: readonly string[] = []): RequestHandler {
+	const exempt = new Set(exemptPaths);
+	return (req, _res, next) => {
+		if (
+			MUTATING.includes(req.method) &&
+			!exempt.has(req.path) &&
+			req.headers["x-requested-with"] !== "XMLHttpRequest"
+		) {
+			next(new AppError("CSRF_HEADER_MISSING", "CSRF header missing", "forbidden"));
+			return;
+		}
+		next();
+	};
+}
+`;
+
+export const schemaLifecycleSource = `export interface SchemaLifecycle {
+	apply(): Promise<void>;
+	close(): Promise<void>;
+}
+`;
+
+export const applySchemaCliSource = `import "reflect-metadata";
+import { schemaLifecycle } from "@/app/schema";
+
+async function main() {
+	try {
+		await schemaLifecycle.apply();
+	} finally {
+		await schemaLifecycle.close();
 	}
-	next();
+}
+
+void main().catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exitCode = 1;
+});
+`;
+
+export const readEnvSource = `export function requiredEnv(name: string): string {
+	const value = process.env[name];
+	if (!value) throw new Error(\`Missing required environment variable \${name}\`);
+	return value;
+}
+
+export function integerEnv(name: string, fallback: number): number {
+	const value = process.env[name];
+	if (value === undefined || value === "") return fallback;
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed)) throw new Error(\`Environment variable \${name} must be an integer\`);
+	return parsed;
+}
+
+export function listEnv(name: string, fallback: readonly string[] = []): string[] {
+	const value = process.env[name];
+	return value
+		? value
+				.split(",")
+				.map((item) => item.trim())
+				.filter(Boolean)
+		: [...fallback];
+}
+`;
+
+export const rateLimitSource = `import type { NextFunction, Request, RequestHandler, Response } from "express";
+import { RateLimiterRedis, RateLimiterRes } from "rate-limiter-flexible";
+import type { RedisClientType } from "redis";
+import { AppError } from "@/core/errors";
+import { createRequestContext } from "@/platform/http/createRequestContext";
+
+export interface RateLimitPolicy {
+	keyPrefix: string;
+	points: number;
+	durationSeconds: number;
+	key: "identity-or-ip" | "ip";
+}
+
+export function createRateLimiter(client: RedisClientType, policy: RateLimitPolicy): RequestHandler {
+	const limiter = new RateLimiterRedis({
+		useRedisPackage: true,
+		storeClient: client,
+		keyPrefix: policy.keyPrefix,
+		points: policy.points,
+		duration: policy.durationSeconds
+	});
+	return async (req: Request, _res: Response, next: NextFunction) => {
+		try {
+			const context = await createRequestContext(req);
+			const key =
+				policy.key === "identity-or-ip" && context.principal?.uid
+					? \`user:\${context.principal.uid}\`
+					: \`ip:\${req.ip ?? "unknown"}\`;
+			await limiter.consume(key);
+			next();
+		} catch (error) {
+			if (error instanceof RateLimiterRes)
+				next(new AppError("RATE_LIMITED", "Too many requests", "rate_limited"));
+			else if (error instanceof AppError) next(error);
+			else next(new AppError("RATE_LIMIT_UNAVAILABLE", "Request protection unavailable", "unavailable"));
+		}
+	};
+}
+`;
+
+export const mongoUsersSource = `const required = (name) => {
+	const value = process.env[name];
+	if (!value) throw new Error(\`\${name} is required\`);
+	return value;
 };
+
+const databaseName = required("MONGODB_DB_NAME");
+const applicationUsername = required("MONGODB_APP_USERNAME");
+const applicationPassword = required("MONGODB_APP_PASSWORD");
+const backupUsername = required("MONGODB_BACKUP_USERNAME");
+const backupPassword = required("MONGODB_BACKUP_PASSWORD");
+const applicationCollections = required("MONGODB_APP_COLLECTIONS")
+	.split(",")
+	.map((name) => name.trim())
+	.filter(Boolean);
+
+if (applicationCollections.length === 0) throw new Error("MONGODB_APP_COLLECTIONS must name at least one collection");
+
+const applicationDatabase = db.getSiblingDB(databaseName);
+applicationDatabase.createRole({
+	role: "applicationDml",
+	privileges: [
+		...applicationCollections.map((collection) => ({
+			resource: { db: databaseName, collection },
+			actions: ["find", "insert", "remove", "update", "changeStream", "listIndexes"]
+		})),
+		{ resource: { db: databaseName, collection: "" }, actions: ["listCollections"] }
+	],
+	roles: []
+});
+
+applicationDatabase.createUser({
+	user: applicationUsername,
+	pwd: applicationPassword,
+	roles: [{ role: "applicationDml", db: databaseName }]
+});
+
+db.getSiblingDB("admin").createUser({
+	user: backupUsername,
+	pwd: backupPassword,
+	roles: [{ role: "backup", db: "admin" }]
+});
 `;
 
 export const getHealthSource = `import type { RequestContext } from "@/core/RequestContext";
@@ -280,6 +470,18 @@ export class MongoReadinessProbe implements ReadinessProbe {
 }
 `;
 
+export const postgresReadinessProbeSource = `import type { Pool } from "pg";
+import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
+
+export class PostgresReadinessProbe implements ReadinessProbe {
+	constructor(private readonly pool: Pool) {}
+
+	async check(): Promise<void> {
+		await this.pool.query("SELECT 1");
+	}
+}
+`;
+
 export const redisReadinessProbeSource = `import type { RedisClientType } from "redis";
 import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
 
@@ -308,25 +510,26 @@ export async function closeRedis() {
 }
 `;
 
-export function containerSource({ redis }) {
+export function containerSource({ database = "mongo", redis }) {
+	const postgres = database === "postgres";
 	return `import { container, type InjectionToken } from "tsyringe";
-import type { Db } from "mongodb";
+import type { ${postgres ? "Pool" : "Db"} } from "${postgres ? "pg" : "mongodb"}";
 ${redis ? 'import type { RedisClientType } from "redis";\n' : ""}import { GetHealth } from "@/modules/health/use-cases/GetHealth";
 import { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
 import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
-import { MongoReadinessProbe } from "@/platform/integrations/mongodb/MongoReadinessProbe";
+import { ${postgres ? "PostgresReadinessProbe" : "MongoReadinessProbe"} } from "@/platform/integrations/${postgres ? "postgres/PostgresReadinessProbe" : "mongodb/MongoReadinessProbe"}";
 ${redis ? 'import { RedisReadinessProbe } from "@/platform/integrations/redis/RedisReadinessProbe";\n' : ""}
 const register = <T>(token: InjectionToken<T>, value: T) => container.registerInstance(token, value);
 
 export interface ApplicationDependencies {
-	db: Db;
+	db: ${postgres ? "Pool" : "Db"};
 ${redis ? "\tredis: RedisClientType;\n" : ""}}
 
 /** App-owned composition root. Domain and use-case classes remain dependency-injection-framework free. */
 export function registerDependencies(dependencies: ApplicationDependencies) {
 	container.reset();
 
-	const readinessProbes: ReadinessProbe[] = [new MongoReadinessProbe(dependencies.db)];
+	const readinessProbes: ReadinessProbe[] = [new ${postgres ? "PostgresReadinessProbe" : "MongoReadinessProbe"}(dependencies.db)];
 ${redis ? "\treadinessProbes.push(new RedisReadinessProbe(dependencies.redis));\n" : ""}
 	register(GetHealth, new GetHealth());
 	register(GetReadiness, new GetReadiness(readinessProbes));
@@ -363,7 +566,7 @@ import { registerDependencies } from "@/app/container";
 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 { requireCsrfHeader } from "@/platform/http/csrf";\n' : ""}import { errorHandler } from "@/platform/http/errors";
+${redis ? 'import { closeRedis, connectRedis } from "@/platform/redis";\n' : ""}${csrf ? 'import { csrfHeaderGuard } from "@/platform/http/csrf";\n' : ""}import { errorHandler } from "@/platform/http/errors";
 
 export interface ApplicationOptions {
 ${ui ? "\tpublicPath?: string;\n\tproduction?: boolean;\n" : ""}}
@@ -373,7 +576,7 @@ export function createApplication(options: ApplicationOptions = {}) {
 ${ui ? '\tconst publicPath = options.publicPath ?? path.join(__dirname, "..", "public");\n\tconst production = options.production ?? env.nodeEnv === "production";\n' : ""}	app.set("trust proxy", 1);
 ${ui ? "\tif (production) {\n\t\tapp.use(express.static(publicPath, { index: false, maxAge: \"1y\", immutable: true }));\n\t}\n" : ""}	app.use(cors({ origin: env.corsOrigin }));
 	app.use(express.json());
-	app.use("/api/v1", ${csrf ? "requireCsrfHeader, " : ""}applicationRoutes());
+	app.use("/api/v1", ${csrf ? "csrfHeaderGuard(), " : ""}applicationRoutes());
 ${ui ? '\tif (production) {\n\t\tapp.get(/^(?!\\/api(?:\\/|$)).*/, (_req, res) => res.sendFile(path.join(publicPath, "index.html")));\n\t}\n' : ""}	app.use(errorHandler);
 	return app;
 }

package/src/sync.mjs

@@ -0,0 +1,64 @@
+import fs from "node:fs";
+import path from "node:path";
+import { appRoot, loadConfig } from "./config.mjs";
+import { appGuidance, OWNED_GUIDANCE_END, OWNED_GUIDANCE_START, productGuidance } from "./owned-guidance.mjs";
+import { ownedSources } from "./owned-sources.mjs";
+
+function syncGuidance(productRoot, root, guidance, mode, changed, errors, label) {
+	const guidanceFile = path.join(root, "AGENTS.md");
+	const existingGuidance = fs.existsSync(guidanceFile) ? fs.readFileSync(guidanceFile, "utf8") : "";
+	const start = existingGuidance.indexOf(OWNED_GUIDANCE_START);
+	const end = existingGuidance.indexOf(OWNED_GUIDANCE_END);
+	const validSentinels = start >= 0 && end > start;
+	const currentSection = validSentinels
+		? existingGuidance.slice(start, end + OWNED_GUIDANCE_END.length)
+		: undefined;
+	if (currentSection === guidance) return;
+	if (mode === "check") {
+		errors.push(`${label} AGENTS.md Tailframe-owned section differs from the canonical guidance`);
+		return;
+	}
+	let appendix = validSentinels
+		? `${existingGuidance.slice(0, start)}${existingGuidance.slice(end + OWNED_GUIDANCE_END.length)}`.trim()
+		: existingGuidance.trim();
+	appendix = appendix.replace(/^## Product-specific appendix\s*/u, "");
+	const next = appendix
+		? `${guidance}\n\n## Product-specific appendix\n\n${appendix}\n`
+		: `${guidance}\n`;
+	fs.mkdirSync(root, { recursive: true });
+	fs.writeFileSync(guidanceFile, next);
+	changed.push(path.relative(productRoot, guidanceFile));
+}
+
+export function runSync(rootArgument, mode, runningVersion, selectedKind) {
+	const loaded = loadConfig(rootArgument);
+	if (loaded.errors.length) return { changed: [], errors: loaded.errors };
+	if (loaded.config.contractVersion !== runningVersion) {
+		return { changed: [], errors: [`tailframe.json requires ${loaded.config.contractVersion}, but this CLI is ${runningVersion}`] };
+	}
+	const changed = [];
+	const errors = [];
+	syncGuidance(loaded.root, loaded.root, productGuidance(loaded.config), mode, changed, errors, "root");
+
+	for (const app of loaded.config.apps.filter((candidate) => !selectedKind || candidate.kind === selectedKind)) {
+		const root = appRoot(loaded.root, app);
+		if (!fs.existsSync(root)) {
+			errors.push(`Missing configured application root: ${app.path}`);
+			continue;
+		}
+		syncGuidance(loaded.root, root, appGuidance(loaded.config, app), mode, changed, errors, app.path);
+		for (const [relative, expected] of Object.entries(ownedSources(app))) {
+			const absolute = path.join(root, relative);
+			const productRelative = path.join(app.path, relative);
+			const actual = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : undefined;
+			if (actual === expected) continue;
+			if (mode === "check") errors.push(`${productRelative} differs from the Tailframe ${runningVersion} canonical source`);
+			else {
+				fs.mkdirSync(path.dirname(absolute), { recursive: true });
+				fs.writeFileSync(absolute, expected);
+				changed.push(productRelative);
+			}
+		}
+	}
+	return { changed, errors };
+}