@zaaxch/tailframe 1.0.0 → 2.0.0

package/src/service-templates.mjs

@@ -0,0 +1,483 @@
+const pascal = (kebab) => kebab.split("-").map((part) => part[0].toUpperCase() + part.slice(1)).join("");
+const camel = (kebab) => {
+	const value = pascal(kebab);
+	return value[0].toLowerCase() + value.slice(1);
+};
+
+export function serviceOperationName(moduleName, verbNoun) {
+	const moduleSuffix = pascal(moduleName);
+	if (verbNoun.endsWith(moduleSuffix) && verbNoun !== moduleSuffix) {
+		const prefix = verbNoun.slice(0, -moduleSuffix.length);
+		return prefix[0].toLowerCase() + prefix.slice(1);
+	}
+	return verbNoun[0].toLowerCase() + verbNoun.slice(1);
+}
+
+export const requestContextSource = `export interface AuthenticatedPrincipal {
+	uid: string;
+	email?: string;
+}
+
+export interface RequestContext {
+	requestId: string;
+	principal?: AuthenticatedPrincipal;
+}
+`;
+
+export const useCaseSource = `import type { RequestContext } from "@/core/RequestContext";
+
+export interface UseCase<Input, Output> {
+	execute(context: RequestContext, input: Input): Promise<Output>;
+}
+`;
+
+export const appErrorSource = `export type FailureKind =
+	| "invalid"
+	| "unauthenticated"
+	| "forbidden"
+	| "not_found"
+	| "conflict"
+	| "unprocessable"
+	| "rate_limited"
+	| "unavailable"
+	| "internal";
+
+export class AppError extends Error {
+	readonly name = "AppError";
+
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly kind: FailureKind,
+		readonly details?: unknown
+	) {
+		super(message);
+	}
+}
+`;
+
+export function createRequestContextSource(auth) {
+	if (auth === "firebase") {
+		return `import { randomUUID } from "node:crypto";
+import type { Request } from "express";
+import type { RequestContext } from "@/core/RequestContext";
+import { AppError } from "@/core/errors";
+import { verifyFirebaseToken } from "@/platform/auth/firebase";
+
+export async function createRequestContext(req: Request): Promise<RequestContext> {
+	const requestId = String(req.headers["x-request-id"] ?? randomUUID());
+	const header = req.headers.authorization;
+	if (!header?.startsWith("Bearer ")) return { requestId };
+
+	try {
+		const decoded = await verifyFirebaseToken(header.slice(7));
+		return { requestId, principal: { uid: decoded.uid, email: decoded.email } };
+	} catch {
+		throw new AppError("UNAUTHENTICATED", "Unauthorized", "unauthenticated");
+	}
+}
+
+export function systemRequestContext(requestId = "system"): RequestContext {
+	return { requestId };
+}
+`;
+	}
+	return `import { randomUUID } from "node:crypto";
+import type { Request } from "express";
+import type { RequestContext } from "@/core/RequestContext";
+
+export async function createRequestContext(req: Request): Promise<RequestContext> {
+	return { requestId: String(req.headers["x-request-id"] ?? randomUUID()) };
+}
+
+export function systemRequestContext(requestId = "system"): RequestContext {
+	return { requestId };
+}
+`;
+}
+
+export const firebaseSource = `import { applicationDefault, 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 });
+	}
+	return getAuth().verifyIdToken(token);
+}
+`;
+
+export const rpcSource = `import type { Response } from "express";
+
+export function rpcResult(res: Response, result: unknown) {
+	return res.json({ result });
+}
+`;
+
+export const rpcHandlerSource = `import type { NextFunction, Request, RequestHandler, Response } from "express";
+import type Joi from "joi";
+import type { RequestContext } from "@/core/RequestContext";
+import { createRequestContext } from "@/platform/http/createRequestContext";
+import { rpcResult } from "@/platform/http/rpc";
+
+interface RpcOperation<Input, Output> {
+	execute(context: RequestContext, input: Input): Output | Promise<Output>;
+}
+
+export interface RpcHandlerOptions<Input, WireInput> {
+	mapInput?: (input: WireInput) => Input;
+	status?: number;
+}
+
+/** Translates one validated RPC request into a use-case call and the shared result envelope. */
+export function rpcHandler<Input, Output, WireInput = Input>(
+	schema: Joi.Schema<WireInput>,
+	operation: RpcOperation<Input, Output>,
+	options: RpcHandlerOptions<Input, WireInput> = {}
+): RequestHandler {
+	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);
+			if (options.status !== undefined) res.status(options.status);
+			rpcResult(res, await operation.execute(await createRequestContext(req), input));
+		} catch (error) {
+			next(error);
+		}
+	};
+}
+`;
+
+export const httpErrorsSource = `import type { ErrorRequestHandler } from "express";
+import Joi from "joi";
+import { AppError } from "@/core/errors";
+
+const statusByKind: Readonly<Record<AppError["kind"], number>> = {
+	invalid: 400,
+	unauthenticated: 401,
+	forbidden: 403,
+	not_found: 404,
+	conflict: 409,
+	unprocessable: 422,
+	rate_limited: 429,
+	unavailable: 503,
+	internal: 500
+};
+
+export const errorHandler: ErrorRequestHandler = (error, _req, res, _next) => {
+	if (error instanceof AppError) {
+		res.status(statusByKind[error.kind]).json({
+			error: {
+				code: error.code,
+				message: error.message,
+				...(error.details === undefined ? {} : { details: error.details })
+			}
+		});
+		return;
+	}
+	if (Joi.isError(error)) {
+		res.status(400).json({
+			error: {
+				code: "VALIDATION_FAILED",
+				message: error.message,
+				...(error.details === undefined ? {} : { details: error.details })
+			}
+		});
+		return;
+	}
+	console.error(error);
+	res.status(500).json({ error: { code: "INTERNAL", message: "Internal server error" } });
+};
+`;
+
+export const csrfSource = `import type { RequestHandler } from "express";
+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;
+	}
+	next();
+};
+`;
+
+export const getHealthSource = `import type { RequestContext } from "@/core/RequestContext";
+import type { UseCase } from "@/core/UseCase";
+
+export type HealthResult = { status: "ok" };
+
+export class GetHealth implements UseCase<Record<string, never>, HealthResult> {
+	async execute(_context: RequestContext, _input: Record<string, never>): Promise<HealthResult> {
+		return { status: "ok" };
+	}
+}
+`;
+
+export const readinessProbeSource = `export interface ReadinessProbe {
+	check(): Promise<void>;
+}
+`;
+
+export const getReadinessSource = `import type { RequestContext } from "@/core/RequestContext";
+import type { UseCase } from "@/core/UseCase";
+import { AppError } from "@/core/errors";
+import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
+
+export type ReadinessResult = { status: "ready" };
+
+export class GetReadiness implements UseCase<Record<string, never>, ReadinessResult> {
+	constructor(private readonly probes: readonly ReadinessProbe[]) {}
+
+	async execute(_context: RequestContext, _input: Record<string, never>): Promise<ReadinessResult> {
+		try {
+			await Promise.all(this.probes.map((probe) => probe.check()));
+			return { status: "ready" };
+		} catch {
+			throw new AppError("NOT_READY", "Service is not ready", "unavailable");
+		}
+	}
+}
+`;
+
+export const healthSchemasSource = `import Joi from "joi";
+
+export const GetHealthSchema = Joi.object({}).unknown(false);
+export const GetReadinessSchema = Joi.object({}).unknown(false);
+`;
+
+export const healthRoutesSource = `import { Router } from "express";
+import type { GetHealth } from "@/modules/health/use-cases/GetHealth";
+import type { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
+import { GetHealthSchema, GetReadinessSchema } from "@/modules/health/http/health.schemas";
+import { rpcHandler } from "@/platform/http/rpcHandler";
+
+interface HealthUseCases {
+	get: GetHealth;
+	readiness: GetReadiness;
+}
+
+export function healthRoutes(useCases: HealthUseCases) {
+	const router = Router();
+	router.post("/health.get", rpcHandler(GetHealthSchema, useCases.get));
+	router.post("/health.readiness", rpcHandler(GetReadinessSchema, useCases.readiness));
+	return router;
+}
+`;
+
+export const mongoReadinessProbeSource = `import type { Db } from "mongodb";
+import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
+
+export class MongoReadinessProbe implements ReadinessProbe {
+	constructor(private readonly db: Db) {}
+
+	async check(): Promise<void> {
+		await this.db.command({ ping: 1 });
+	}
+}
+`;
+
+export const redisReadinessProbeSource = `import type { RedisClientType } from "redis";
+import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
+
+export class RedisReadinessProbe implements ReadinessProbe {
+	constructor(private readonly redis: RedisClientType) {}
+
+	async check(): Promise<void> {
+		await this.redis.ping();
+	}
+}
+`;
+
+export const redisSource = `import { createClient, type RedisClientType } from "redis";
+import { env } from "@/platform/config/env";
+
+export const redis: RedisClientType = createClient({ url: env.redisUrl });
+redis.on("error", (error) => console.error("Redis client error", error));
+
+export async function connectRedis() {
+	if (!redis.isOpen) await redis.connect();
+	return redis;
+}
+
+export async function closeRedis() {
+	if (redis.isOpen) await redis.quit();
+}
+`;
+
+export function containerSource({ redis }) {
+	return `import { container, type InjectionToken } from "tsyringe";
+import type { Db } from "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";
+${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;
+${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)];
+${redis ? "\treadinessProbes.push(new RedisReadinessProbe(dependencies.redis));\n" : ""}
+	register(GetHealth, new GetHealth());
+	register(GetReadiness, new GetReadiness(readinessProbes));
+
+	return container;
+}
+
+export { container };
+`;
+}
+
+export const applicationRoutesSource = `import { Router } from "express";
+import { container } from "@/app/container";
+import { GetHealth } from "@/modules/health/use-cases/GetHealth";
+import { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
+import { healthRoutes } from "@/modules/health/http/health.routes";
+
+export function applicationRoutes() {
+	const router = Router();
+	router.use(
+		healthRoutes({
+			get: container.resolve(GetHealth),
+			readiness: container.resolve(GetReadiness)
+		})
+	);
+	return router;
+}
+`;
+
+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 { 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";
+
+export interface ApplicationOptions {
+${ui ? "\tpublicPath?: string;\n\tproduction?: boolean;\n" : ""}}
+
+export function createApplication(options: ApplicationOptions = {}) {
+	const app = express();
+${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());
+${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;
+}
+
+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 };
+}
+`;
+}
+
+export function workerSource() {
+	return `import { container, registerDependencies } from "@/app/container";
+import { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
+import { closeDatabase, connectDatabase } from "@/platform/database";
+import { systemRequestContext } from "@/platform/http/createRequestContext";
+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 };
+}
+`;
+}
+
+export const getHealthTestSource = `import { GetHealth } from "@/modules/health/use-cases/GetHealth";
+
+describe("GetHealth", () => {
+	it("returns health through the use-case contract", async () => {
+		await expect(new GetHealth().execute({ requestId: "test" }, {})).resolves.toEqual({ status: "ok" });
+	});
+});
+`;
+
+export const getReadinessTestSource = `import { GetReadiness } from "@/modules/health/use-cases/GetReadiness";
+import type { ReadinessProbe } from "@/modules/health/use-cases/ports/ReadinessProbe";
+
+const probe = (check: () => Promise<void>): ReadinessProbe => ({ check });
+
+describe("GetReadiness", () => {
+	it("returns ready after every probe succeeds", async () => {
+		const first = jest.fn().mockResolvedValue(undefined);
+		const second = jest.fn().mockResolvedValue(undefined);
+		const useCase = new GetReadiness([probe(first), probe(second)]);
+
+		await expect(useCase.execute({ requestId: "test" }, {})).resolves.toEqual({ status: "ready" });
+		expect(first).toHaveBeenCalledTimes(1);
+		expect(second).toHaveBeenCalledTimes(1);
+	});
+
+	it("maps a failed probe to the shared unavailable error", async () => {
+		const useCase = new GetReadiness([probe(jest.fn().mockRejectedValue(new Error("offline")))]);
+
+		await expect(useCase.execute({ requestId: "test" }, {})).rejects.toMatchObject({
+			code: "NOT_READY",
+			kind: "unavailable"
+		});
+	});
+});
+`;
+
+export function serviceHttpFiles(moduleName, verbNoun) {
+	const operation = serviceOperationName(moduleName, verbNoun);
+	const dependency = operation;
+	return {
+		[`src/modules/${moduleName}/http/${moduleName}.schemas.ts`]: `import Joi from "joi";
+
+export const ${verbNoun}Schema = Joi.object({}).unknown(false);
+`,
+		[`src/modules/${moduleName}/http/${moduleName}.routes.ts`]: `import { Router } from "express";
+import type { ${verbNoun} } from "@/modules/${moduleName}/use-cases/${verbNoun}";
+import { ${verbNoun}Schema } from "@/modules/${moduleName}/http/${moduleName}.schemas";
+import { rpcHandler } from "@/platform/http/rpcHandler";
+
+interface ${pascal(moduleName)}UseCases {
+	${dependency}: ${verbNoun};
+}
+
+export function ${camel(moduleName)}Routes(useCases: ${pascal(moduleName)}UseCases) {
+	const router = Router();
+	router.post("/${moduleName}.${operation}", rpcHandler(${verbNoun}Schema, useCases.${dependency}));
+	return router;
+}
+`
+	};
+}

package/src/ui-templates.mjs

@@ -0,0 +1,141 @@
+export const uiErrorsSource = `export type FailureKind =
+	| "invalid"
+	| "unauthenticated"
+	| "forbidden"
+	| "not_found"
+	| "conflict"
+	| "unprocessable"
+	| "rate_limited"
+	| "unavailable"
+	| "internal"
+	| "network";
+
+export interface ServiceError {
+	code: string;
+	message: string;
+	kind: FailureKind;
+	details?: unknown;
+}
+
+export const isServiceError = (value: unknown): value is ServiceError =>
+	typeof value === "object" &&
+	value !== null &&
+	typeof (value as ServiceError).code === "string" &&
+	typeof (value as ServiceError).message === "string" &&
+	typeof (value as ServiceError).kind === "string";
+`;
+
+export const uiRpcSource = `export interface RpcResponse<T> {
+	result: T;
+}
+
+export interface RpcErrorEnvelope {
+	error: { code: string; message: string; details?: unknown };
+}
+`;
+
+export const uiHttpSource = `import axios, { type AxiosError } from "axios";
+import type { ServiceError } from "@/core/errors";
+import type { RpcErrorEnvelope, RpcResponse } from "@/core/rpc";
+
+const failureKind = (status?: number): ServiceError["kind"] => {
+	if (!status) return "network";
+	if (status === 401) return "unauthenticated";
+	if (status === 403) return "forbidden";
+	if (status === 404) return "not_found";
+	if (status === 409) return "conflict";
+	if (status === 422) return "unprocessable";
+	if (status === 429) return "rate_limited";
+	if (status === 503) return "unavailable";
+	if (status >= 500) return "internal";
+	return "invalid";
+};
+
+export const http = axios.create({
+	baseURL: \`\${window.location.origin}/api/v1\`,
+	headers: {
+		"Content-Type": "application/json",
+		Accept: "application/json",
+		"X-Requested-With": "XMLHttpRequest"
+	}
+});
+
+export interface HttpConfiguration {
+	getIdToken?: () => Promise<string | undefined>;
+	handleUnauthorized?: () => Promise<void> | void;
+}
+
+let configuration: HttpConfiguration = {};
+
+export function configureHttpClient(next: HttpConfiguration) {
+	configuration = next;
+}
+
+http.interceptors.request.use(async (config) => {
+	const token = await configuration.getIdToken?.();
+	if (token) config.headers.Authorization = \`Bearer \${token}\`;
+	return config;
+});
+
+http.interceptors.response.use(
+	(response) => response,
+	async (error: AxiosError<RpcErrorEnvelope>) => {
+		const status = error.response?.status;
+		if (status === 401) await configuration.handleUnauthorized?.();
+		const envelope = error.response?.data?.error;
+		const serviceError: ServiceError = {
+			code: envelope?.code ?? (status ? \`HTTP_\${status}\` : "NETWORK"),
+			message: envelope?.message ?? error.message,
+			kind: failureKind(status),
+			...(envelope?.details === undefined ? {} : { details: envelope.details })
+		};
+		return Promise.reject(serviceError);
+	}
+);
+
+export async function rpc<T>(operation: string, payload: unknown = {}): Promise<T> {
+	return (await http.post<RpcResponse<T>>(operation, payload)).data.result;
+}
+`;
+
+export const configureHttpSource = `import type { Pinia } from "pinia";
+import router from "@/app/router";
+import { useAuthStore } from "@/app/stores/auth.store";
+import { RouteNames } from "@/core/RouteNames";
+import { configureHttpClient } from "@/platform/http";
+
+export function configureHttp(pinia: Pinia) {
+	const auth = useAuthStore(pinia);
+
+	configureHttpClient({
+		getIdToken: async () => auth.getIdToken(),
+		handleUnauthorized: async () => {
+			await auth.logout();
+			await router.push({ name: RouteNames.HOME });
+		}
+	});
+}
+`;
+
+export const healthApiSource = `import { rpc } from "@/platform/http";
+
+export interface Health {
+	status: "ok";
+}
+
+export interface Readiness {
+	status: "ready";
+}
+
+export const getHealth = () => rpc<Health>("health.get");
+export const getReadiness = () => rpc<Readiness>("health.readiness");
+`;
+
+export function moduleApiSource(moduleName, typeName) {
+	return `import { rpc } from "@/platform/http";
+
+export async function get${typeName}() {
+	return rpc<unknown>("${moduleName}.get");
+}
+`;
+}

package/src/validate.mjs

@@ -2,7 +2,7 @@ import { validateArchitecture } from "./architecture.mjs";
 import { validateConventions } from "./conventions.mjs";
 import { isExcepted, loadExceptions } from "./exceptions.mjs";
 
-const NON_EXCEPTABLE_RULES = new Set(["U5", "U6", "U7"]);
+const NON_EXCEPTABLE_RULES = new Set(["S8", "S9", "U5", "U6", "U7"]);
 
 export function runValidate(root, kind) {
 	const structural = validateArchitecture(root, kind);