@zaaxch/tailframe 2.2.0 → 3.0.0

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,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.mjs";
+import { readFlutterPackageName } from "./flutter.mjs";
+import { OWNED_GUIDANCE_END, OWNED_GUIDANCE_START, ownedGuidance } from "./owned-guidance.mjs";
+import { ownedSources } from "./owned-sources.mjs";
+
+export function runSync(rootArgument, mode, runningVersion) {
+	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 = [];
+	const sourceOptions = {};
+	if (loaded.config.kind === "flutter") {
+		const packageName = readFlutterPackageName(loaded.root);
+		if (!packageName) return { changed, errors: ["pubspec.yaml must declare a package name"] };
+		sourceOptions.flutterPackageName = packageName;
+	}
+	const guidanceFile = path.join(loaded.root, "AGENTS.md");
+	const guidance = ownedGuidance(loaded.config);
+	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) {
+		if (mode === "check") errors.push("AGENTS.md Tailframe-owned section differs from the canonical guidance");
+		else {
+			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.writeFileSync(guidanceFile, next);
+			changed.push("AGENTS.md");
+		}
+	}
+	for (const [relative, expected] of Object.entries(ownedSources(loaded.config, sourceOptions))) {
+		const absolute = path.join(loaded.root, relative);
+		const actual = fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : undefined;
+		if (actual === expected) continue;
+		if (mode === "check") errors.push(`${relative} differs from the Tailframe ${runningVersion} canonical source`);
+		else {
+			fs.mkdirSync(path.dirname(absolute), { recursive: true });
+			fs.writeFileSync(absolute, expected);
+			changed.push(relative);
+		}
+	}
+	return { changed, errors };
+}

package/src/ui-templates.mjs

@@ -37,6 +37,7 @@ export interface RpcErrorEnvelope {
 export const uiHttpSource = `import axios, { type AxiosError } from "axios";
 import type { ServiceError } from "@/core/errors";
 import type { RpcErrorEnvelope, RpcResponse } from "@/core/rpc";
+import { apiBaseUrl } from "@/platform/config";
 
 const failureKind = (status?: number): ServiceError["kind"] => {
 	if (!status) return "network";
@@ -52,7 +53,7 @@ const failureKind = (status?: number): ServiceError["kind"] => {
 };
 
 export const http = axios.create({
-	baseURL: \`\${window.location.origin}/api/v1\`,
+	baseURL: apiBaseUrl,
 	headers: {
 		"Content-Type": "application/json",
 		Accept: "application/json",
@@ -98,6 +99,184 @@ export async function rpc<T>(operation: string, payload: unknown = {}): Promise<
 }
 `;
 
+export const uiErrorMessagesSource = `import { isServiceError } from "@/core/errors";
+
+export type ErrorMessageMap = Record<string, string>;
+
+export function getErrorMessage(
+	error: unknown,
+	fallback = "Please try again.",
+	messages: ErrorMessageMap = {}
+): string {
+	if (isServiceError(error)) return messages[error.code] ?? fallback;
+	return fallback;
+}
+
+export const hasErrorCode = (error: unknown, code: string) => isServiceError(error) && error.code === code;
+`;
+
+export const notificationStoreSource = `import { defineStore } from "pinia";
+import { computed, ref } from "vue";
+
+export type NotificationKind = "info" | "success" | "warning" | "error";
+
+export interface NotificationInput {
+	message: string;
+	kind?: NotificationKind;
+	durationMs?: number;
+}
+
+export interface AppNotification {
+	id: number;
+	message: string;
+	kind: NotificationKind;
+	durationMs: number;
+}
+
+export const useNotificationStore = defineStore("notification", () => {
+	const queue = ref<AppNotification[]>([]);
+	const active = computed<AppNotification | undefined>(() => queue.value[0]);
+	let nextId = 1;
+
+	function notify({ message, kind = "info", durationMs = 4000 }: NotificationInput) {
+		const id = nextId++;
+		queue.value.push({ id, message, kind, durationMs });
+		return id;
+	}
+
+	function dismiss(id: number) {
+		queue.value = queue.value.filter((notification) => notification.id !== id);
+	}
+
+	function clear() {
+		queue.value = [];
+	}
+
+	return { queue, active, notify, dismiss, clear };
+});
+`;
+
+export const notificationHostSource = `<template>
+	<div class="tailframe-notifications" aria-live="polite" aria-atomic="true">
+		<div v-if="active" :class="['tailframe-notification', \`is-\${active.kind}\`]" role="status">
+			<span>{{ active.message }}</span>
+			<button type="button" aria-label="Dismiss notification" @click="notifications.dismiss(active.id)">×</button>
+		</div>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { computed, onBeforeUnmount, watch } from "vue";
+import { useNotificationStore } from "@/app/stores/notification.store";
+
+const notifications = useNotificationStore();
+const active = computed(() => notifications.active);
+let timer: number | undefined;
+
+watch(
+	active,
+	(notification) => {
+		if (timer !== undefined) window.clearTimeout(timer);
+		timer = undefined;
+		if (notification && notification.durationMs > 0) {
+			timer = window.setTimeout(() => notifications.dismiss(notification.id), notification.durationMs);
+		}
+	},
+	{ immediate: true }
+);
+
+onBeforeUnmount(() => {
+	if (timer !== undefined) window.clearTimeout(timer);
+});
+</script>
+
+<style scoped>
+.tailframe-notifications {
+	position: fixed;
+	inset: auto 1rem 1rem;
+	z-index: 10000;
+	display: grid;
+	justify-items: end;
+	pointer-events: none;
+}
+.tailframe-notification {
+	display: flex;
+	max-width: min(32rem, calc(100vw - 2rem));
+	align-items: center;
+	gap: 0.75rem;
+	border-radius: 0.75rem;
+	background: #1e293b;
+	color: white;
+	padding: 0.75rem 1rem;
+	box-shadow: 0 12px 30px rgb(15 23 42 / 0.28);
+	pointer-events: auto;
+}
+.tailframe-notification.is-success {
+	background: #166534;
+}
+.tailframe-notification.is-warning {
+	background: #92400e;
+}
+.tailframe-notification.is-error {
+	background: #991b1b;
+}
+.tailframe-notification button {
+	border: 0;
+	background: transparent;
+	color: inherit;
+	cursor: pointer;
+	font: inherit;
+	font-size: 1.25rem;
+	line-height: 1;
+}
+</style>
+`;
+
+export const extensionAuthStoreSource = `import { auth, signInWithGoogleAccessToken } from "@/platform/firebase";
+import { invalidateGoogleAccessToken, requestGoogleAccessToken, signOutGoogleSession } from "@/platform/extensionAuth";
+import { onIdTokenChanged, signOut, type User } from "firebase/auth/web-extension";
+import { defineStore } from "pinia";
+import { ref } from "vue";
+
+export const useAuthStore = defineStore("auth", () => {
+	const firebaseUser = ref<User | null>(null);
+	const ready = ref(false);
+
+	onIdTokenChanged(auth, (value) => {
+		firebaseUser.value = value;
+		ready.value = true;
+	});
+
+	async function signInWithGoogle(interactive = true) {
+		let accessToken = await requestGoogleAccessToken(interactive);
+		try {
+			return await signInWithGoogleAccessToken(accessToken);
+		} catch (reason: unknown) {
+			if (
+				!interactive ||
+				typeof reason !== "object" ||
+				reason === null ||
+				!("code" in reason) ||
+				reason.code !== "auth/invalid-credential"
+			)
+				throw reason;
+			await invalidateGoogleAccessToken(accessToken);
+			accessToken = await requestGoogleAccessToken(true);
+			return signInWithGoogleAccessToken(accessToken);
+		}
+	}
+
+	async function logout() {
+		await signOut(auth);
+		await signOutGoogleSession();
+	}
+
+	const getIdToken = () => firebaseUser.value?.getIdToken();
+
+	return { firebaseUser, ready, signInWithGoogle, logout, getIdToken };
+});
+`;
+
 export const configureHttpSource = `import type { Pinia } from "pinia";
 import router from "@/app/router";
 import { useAuthStore } from "@/app/stores/auth.store";

package/src/validate.mjs

@@ -1,10 +1,16 @@
+import fs from "node:fs";
+import path from "node:path";
 import { validateArchitecture } from "./architecture.mjs";
 import { validateConventions } from "./conventions.mjs";
+import { loadConfig } from "./config.mjs";
 import { isExcepted, loadExceptions } from "./exceptions.mjs";
+import { validateFlutter } from "./flutter.mjs";
+import { runSync } from "./sync.mjs";
 
 const NON_EXCEPTABLE_RULES = new Set(["S8", "S9", "U5", "U6", "U7"]);
 
 export function runValidate(root, kind) {
+	if (kind === "flutter") return validateFlutter(root);
 	const structural = validateArchitecture(root, kind);
 	if (structural.some((error) => error.startsWith("Architecture root") || error.startsWith("Architecture kind"))) {
 		return structural;
@@ -15,3 +21,41 @@ export function runValidate(root, kind) {
 		.map((violation) => `${violation.rule}: ${violation.message}`);
 	return [...structural, ...conventions];
 }
+
+function validateVersionMetadata(root, runningVersion) {
+	const errors = [];
+	const packageFile = path.join(root, "package.json");
+	const lockFile = path.join(root, "package-lock.json");
+	if (!fs.existsSync(packageFile)) return ["package.json is required to pin the Tailframe build-time contract"];
+	let manifest;
+	try { manifest = JSON.parse(fs.readFileSync(packageFile, "utf8")); }
+	catch { return ["package.json is not valid JSON"]; }
+	if (manifest.devDependencies?.["@zaaxch/tailframe"] !== runningVersion) {
+		errors.push(`package.json must pin @zaaxch/tailframe exactly to ${runningVersion}`);
+	}
+	if (!fs.existsSync(lockFile)) return [...errors, "package-lock.json is required to lock the Tailframe contract"];
+	try {
+		const lock = JSON.parse(fs.readFileSync(lockFile, "utf8"));
+		const rootPin = lock.packages?.[""]?.devDependencies?.["@zaaxch/tailframe"];
+		const installed = lock.packages?.["node_modules/@zaaxch/tailframe"]?.version;
+		if (rootPin !== runningVersion) errors.push(`package-lock.json root must pin @zaaxch/tailframe exactly to ${runningVersion}`);
+		if (installed !== runningVersion) errors.push(`package-lock.json resolves @zaaxch/tailframe ${installed ?? "nowhere"}, expected ${runningVersion}`);
+	} catch {
+		errors.push("package-lock.json is not valid JSON");
+	}
+	return errors;
+}
+
+export function runConfiguredValidate(rootArgument, runningVersion) {
+	const loaded = loadConfig(rootArgument);
+	if (loaded.errors.length) return loaded.errors;
+	const errors = [];
+	if (loaded.config.contractVersion !== runningVersion) {
+		errors.push(`tailframe.json requires ${loaded.config.contractVersion}, but this CLI is ${runningVersion}`);
+	}
+	errors.push(...validateVersionMetadata(loaded.root, runningVersion));
+	if (errors.length) return errors;
+	errors.push(...runValidate(loaded.root, loaded.config.kind));
+	errors.push(...runSync(loaded.root, "check", runningVersion).errors);
+	return errors;
+}