@tatara/cli 0.0.0-stage → 0.1.1

package/templates/features/base/files/src/core/commands/runner.ts

@@ -0,0 +1,54 @@
+import type { CommandDefinition } from "#core/commands/define";
+import { logger } from "#core/logging/logger";
+
+/** Parses `--key value`, `--key=value` and bare `--flag` (true) into an object. */
+export function parseFlags(argv: string[]): Record<string, string | boolean> {
+	const flags: Record<string, string | boolean> = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i] ?? "";
+		if (!arg.startsWith("--")) continue;
+		const [rawKey, inline] = arg.slice(2).split("=", 2);
+		const key = (rawKey ?? "").replace(/-([a-z])/g, (_, ch: string) => ch.toUpperCase());
+		if (inline !== undefined) {
+			flags[key] = inline;
+		} else if (argv[i + 1] !== undefined && !argv[i + 1]?.startsWith("--")) {
+			flags[key] = argv[i + 1] ?? "";
+			i++;
+		} else {
+			flags[key] = true;
+		}
+	}
+	return flags;
+}
+
+export async function runCommand(commands: CommandDefinition[], argv: string[]): Promise<number> {
+	const [name, ...rest] = argv;
+	if (!name || name === "--list" || name === "list" || name === "help") {
+		const width = Math.max(0, ...commands.map((c) => c.name.length));
+		console.log("Commands:");
+		for (const c of [...commands].sort((a, b) => a.name.localeCompare(b.name))) {
+			console.log(`  ${c.name.padEnd(width)}  ${c.description}`);
+		}
+		return 0;
+	}
+	const command = commands.find((c) => c.name === name);
+	if (!command) {
+		console.error(`Unknown command "${name}". Run with --list to see available commands.`);
+		return 1;
+	}
+	const parsed = (command.args ?? null)?.safeParse(parseFlags(rest));
+	if (parsed && !parsed.success) {
+		console.error(`Invalid arguments for ${name}:`);
+		for (const issue of parsed.error.issues) {
+			console.error(`  --${issue.path.join(".")}: ${issue.message}`);
+		}
+		return 1;
+	}
+	try {
+		await command.run(parsed ? parsed.data : {}, { logger: logger.child({ command: name }) });
+		return 0;
+	} catch (error) {
+		logger.error({ err: error, command: name }, "command failed");
+		return 1;
+	}
+}

package/templates/features/base/files/src/core/commands/tests/flags.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { flag } from "#core/commands/define";
+import { parseFlags } from "#core/commands/runner";
+
+const args = z.object({ force: flag() });
+const parse = (argv: string[]) => args.parse(parseFlags(argv)).force;
+
+describe("flag()", () => {
+	it("is true for a bare flag", () => expect(parse(["--force"])).toBe(true));
+	it("reads --flag false as false", () => expect(parse(["--force", "false"])).toBe(false));
+	it("reads --flag=0 as false", () => expect(parse(["--force=0"])).toBe(false));
+	it("reads --flag true as true", () => expect(parse(["--force", "true"])).toBe(true));
+	it("defaults to false", () => expect(parse([])).toBe(false));
+	it("rejects anything else", () => expect(() => parse(["--force", "maybe"])).toThrow());
+});

package/templates/features/base/files/src/core/config/tests/env.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// .env.test is loaded into process.env, so it holds every variable this app requires
+const saved = { ...process.env };
+
+const LOCAL_DEFAULTS = [
+	"APP_URL",
+	"CORS_ORIGINS",
+	"EMAIL_DRIVER",
+	"STORAGE_DRIVER",
+	"SMTP_URL",
+	"KEYCLOAK_URL",
+].filter((key) => saved[key] !== undefined);
+
+async function loadEnv(vars: Record<string, string | undefined>) {
+	vi.resetModules();
+	process.env = { ...vars } as NodeJS.ProcessEnv;
+	return (await import("#core/config/env")).env;
+}
+
+afterEach(() => {
+	process.env = { ...saved };
+	vi.resetModules();
+});
+
+describe("env in production", () => {
+	it("loads when every setting is given", async () => {
+		const env = await loadEnv({ ...saved, NODE_ENV: "production" });
+		expect(env.NODE_ENV).toBe("production");
+	});
+
+	it.each(LOCAL_DEFAULTS)("refuses to fall back to the local default for %s", async (key) => {
+		await expect(loadEnv({ ...saved, NODE_ENV: "production", [key]: undefined })).rejects.toThrow();
+	});
+
+	it("keeps local defaults outside production", async () => {
+		const env = await loadEnv({ ...saved, NODE_ENV: "development", APP_URL: undefined });
+		expect(env.APP_URL).toBe("http://localhost:3000");
+	});
+});

package/templates/features/base/files/src/core/http/app.ts

@@ -0,0 +1,57 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { bodyLimit } from "hono/body-limit";
+import { cors } from "hono/cors";
+import { secureHeaders } from "hono/secure-headers";
+import { env } from "#core/config/env";
+import type { AppEnv } from "#core/http/context";
+import { runReadinessChecks } from "#core/http/health";
+import { errorHandler, notFoundHandler } from "#core/http/middleware/error-handler";
+import { requestContext } from "#core/http/middleware/request-context";
+import { validationHook } from "#core/http/middleware/validation";
+import type { AppName } from "#core/http/routes";
+import { routes } from "#generated/routes";
+// tatara:slot imports
+
+export const API_PREFIX = "/api";
+
+export function createHttpApp(name: AppName, options: { title: string }) {
+	const app = new OpenAPIHono<AppEnv>({ defaultHook: validationHook });
+
+	app.use(requestContext);
+	app.use(secureHeaders());
+	app.use(
+		cors({
+			origin: env.CORS_ORIGINS,
+			credentials: true,
+			allowHeaders: ["Content-Type", "Authorization", "X-Request-Id", "Accept-Language"],
+			exposeHeaders: ["X-Request-Id"],
+		}),
+	);
+	app.use(bodyLimit({ maxSize: env.BODY_LIMIT_BYTES }));
+	// tatara:slot middleware
+
+	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/ready", async (c) => {
+		const result = await runReadinessChecks();
+		return c.json(result, result.ready ? 200 : 503);
+	});
+
+	// tatara:slot routes
+
+	for (const definition of routes) {
+		if (definition.app === name) app.route(`${API_PREFIX}${definition.basePath}`, definition.router);
+	}
+
+	const openApiConfig = { openapi: "3.1.0", info: { title: options.title, version: "1.0.0" } } as const;
+	app.get("/openapi.json", async (c) => {
+		const document = app.getOpenAPI31Document(openApiConfig);
+		// tatara:slot openapi
+		return c.json(document);
+	});
+	app.get("/docs", Scalar({ url: "/openapi.json", pageTitle: options.title }));
+
+	app.onError(errorHandler);
+	app.notFound(notFoundHandler);
+	return app;
+}

package/templates/features/base/files/src/core/http/context.ts

@@ -0,0 +1,18 @@
+import type { Logger } from "#core/logging/logger";
+
+export interface Principal {
+	userId: string;
+	orgId: string | null;
+	roles: string[];
+	kind: "user" | "service";
+	claims: Record<string, unknown>;
+}
+
+export interface AppEnv {
+	Variables: {
+		requestId: string;
+		logger: Logger;
+		principal: Principal | null;
+		language: string;
+	};
+}

package/templates/features/base/files/src/core/http/errors.ts

@@ -0,0 +1,79 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export class AppError extends Error {
+	readonly status: ContentfulStatusCode;
+	readonly code: string;
+	readonly details?: unknown;
+	/** True when the message is generic, so the response may replace it with `errors.<code>` in the caller's language. */
+	readonly translatable: boolean;
+
+	constructor(
+		status: ContentfulStatusCode,
+		code: string,
+		message: string,
+		details?: unknown,
+		translatable = false,
+	) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+		this.code = code;
+		this.details = details;
+		this.translatable = translatable;
+	}
+}
+
+export class ValidationError extends AppError {
+	constructor(message?: string, details?: unknown) {
+		super(400, "VALIDATION_ERROR", message ?? "Invalid request", details, message === undefined);
+	}
+}
+
+export class BusinessRuleError extends AppError {
+	constructor(code: string, message: string, details?: unknown) {
+		// codes are specific to the rule, so a translation for the code is never less precise
+		super(400, code, message, details, true);
+	}
+}
+
+export class UnauthorizedError extends AppError {
+	constructor(message?: string) {
+		super(
+			401,
+			"UNAUTHORIZED",
+			message ?? "Authentication required",
+			undefined,
+			message === undefined,
+		);
+	}
+}
+
+export class ForbiddenError extends AppError {
+	constructor(message?: string) {
+		super(
+			403,
+			"FORBIDDEN",
+			message ?? "You do not have permission to do this",
+			undefined,
+			message === undefined,
+		);
+	}
+}
+
+export class NotFoundError extends AppError {
+	constructor(resource?: string) {
+		super(
+			404,
+			"NOT_FOUND",
+			`${resource ?? "Resource"} not found`,
+			undefined,
+			resource === undefined,
+		);
+	}
+}
+
+export class ConflictError extends AppError {
+	constructor(message?: string, details?: unknown) {
+		super(409, "CONFLICT", message ?? "Resource already exists", details, message === undefined);
+	}
+}

package/templates/features/base/files/src/core/http/health.ts

@@ -0,0 +1,25 @@
+type Check = () => Promise<void>;
+
+const checks = new Map<string, Check>();
+
+/** Registers a dependency checked by GET /ready (database, redis, …). */
+export function registerReadinessCheck(name: string, check: Check): void {
+	checks.set(name, check);
+}
+
+export async function runReadinessChecks() {
+	const results = await Promise.all(
+		[...checks].map(async ([name, check]) => {
+			try {
+				await check();
+				return [name, "ok"] as const;
+			} catch {
+				return [name, "failed"] as const;
+			}
+		}),
+	);
+	return {
+		ready: results.every(([, status]) => status === "ok"),
+		checks: Object.fromEntries(results),
+	};
+}

package/templates/features/base/files/src/core/http/middleware/error-handler.ts

@@ -0,0 +1,36 @@
+import type { Context } from "hono";
+import { HTTPException } from "hono/http-exception";
+import type { AppEnv } from "#core/http/context";
+import { AppError } from "#core/http/errors";
+// tatara:slot imports
+
+export function errorHandler(err: Error, c: Context<AppEnv>) {
+	if (err instanceof AppError) {
+		let message = err.message;
+		// tatara:slot error-message
+		return c.json(
+			{
+				success: false as const,
+				error: message,
+				code: err.code,
+				...(err.details === undefined ? {} : { details: err.details }),
+			},
+			err.status,
+		);
+	}
+	if (err instanceof HTTPException) {
+		return c.json(
+			{ success: false as const, error: err.message || "Request failed", code: "HTTP_ERROR" },
+			err.status,
+		);
+	}
+	c.get("logger").error({ err }, "unhandled error");
+	return c.json(
+		{ success: false as const, error: "Something went wrong", code: "INTERNAL_ERROR" },
+		500,
+	);
+}
+
+export function notFoundHandler(c: Context<AppEnv>) {
+	return c.json({ success: false as const, error: "Route not found", code: "NOT_FOUND" }, 404);
+}

package/templates/features/base/files/src/core/http/middleware/request-context.ts

@@ -0,0 +1,24 @@
+import { createMiddleware } from "hono/factory";
+import type { AppEnv } from "#core/http/context";
+import { logger } from "#core/logging/logger";
+
+const REQUEST_ID = /^[\w-]{8,128}$/;
+
+/** Sets requestId, a request-scoped logger and defaults; logs one line per request. */
+export const requestContext = createMiddleware<AppEnv>(async (c, next) => {
+	const incoming = c.req.header("x-request-id");
+	const requestId = incoming && REQUEST_ID.test(incoming) ? incoming : crypto.randomUUID();
+	const log = logger.child({ requestId });
+	c.set("requestId", requestId);
+	c.set("logger", log);
+	c.set("principal", null);
+	c.set("language", "en");
+	c.header("x-request-id", requestId);
+	const start = performance.now();
+	await next();
+	const ms = Math.round(performance.now() - start);
+	const status = c.res.status;
+	const entry = { method: c.req.method, path: c.req.path, status, ms };
+	if (status >= 500) log.error(entry, "request failed");
+	else log.info(entry, "request");
+});

package/templates/features/base/files/src/core/http/middleware/validation.ts

@@ -0,0 +1,17 @@
+import type { Hook } from "@hono/zod-openapi";
+import type { AppEnv } from "#core/http/context";
+import { ValidationError } from "#core/http/errors";
+
+// biome-ignore lint/suspicious/noExplicitAny: the hook is shared by every route schema
+export const validationHook: Hook<any, AppEnv, any, any> = (result) => {
+	if (!result.success) {
+		throw new ValidationError(
+			undefined,
+			result.error.issues.map((issue) => ({
+				path: issue.path.join("."),
+				message: issue.message,
+				code: issue.code,
+			})),
+		);
+	}
+};

package/templates/features/base/files/src/core/http/response.ts

@@ -0,0 +1,72 @@
+import { z } from "@hono/zod-openapi";
+
+export const errorSchema = z
+	.object({
+		success: z.literal(false),
+		error: z.string(),
+		code: z.string(),
+		details: z.unknown().optional(),
+	})
+	.openapi("Error");
+
+export const paginationMetaSchema = z
+	.object({
+		page: z.number().int(),
+		pageSize: z.number().int(),
+		total: z.number().int(),
+		totalPages: z.number().int(),
+	})
+	.openapi("PaginationMeta");
+
+export const paginationQuerySchema = z.object({
+	page: z.coerce.number().int().min(1).default(1),
+	pageSize: z.coerce.number().int().min(1).max(100).default(20),
+});
+
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
+
+export function successSchema<T extends z.ZodType>(data: T) {
+	return z.object({ success: z.literal(true), data });
+}
+
+export function paginatedSchema<T extends z.ZodType>(item: T) {
+	return z.object({ success: z.literal(true), data: z.array(item), meta: paginationMetaSchema });
+}
+
+export function success<T>(data: T) {
+	return { success: true as const, data };
+}
+
+export function paginated<T>(data: T[], page: number, pageSize: number, total: number) {
+	return {
+		success: true as const,
+		data,
+		meta: { page, pageSize, total, totalPages: Math.max(1, Math.ceil(total / pageSize)) },
+	};
+}
+
+export function jsonContent<T extends z.ZodType>(schema: T, description: string) {
+	return { content: { "application/json": { schema } }, description };
+}
+
+/** A required JSON request body. Without `required`, a request with no body skips validation. */
+export function jsonBody<T extends z.ZodType>(schema: T, description: string) {
+	return { ...jsonContent(schema, description), required: true };
+}
+
+const ERROR_DESCRIPTIONS = {
+	400: "Invalid request",
+	401: "Authentication required",
+	403: "Forbidden",
+	404: "Not found",
+	409: "Conflict",
+} as const;
+
+type ErrorStatus = keyof typeof ERROR_DESCRIPTIONS;
+
+/** OpenAPI error responses for the given statuses, all using the shared error envelope. */
+export function errorResponses<const S extends ErrorStatus[]>(...statuses: S) {
+	return Object.fromEntries(
+		statuses.map((status) => [status, jsonContent(errorSchema, ERROR_DESCRIPTIONS[status])]),
+	) as { [K in S[number]]: ReturnType<typeof jsonContent<typeof errorSchema>> };
+}

package/templates/features/base/files/src/core/http/routes.ts

@@ -0,0 +1,28 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "#core/http/context";
+import { validationHook } from "#core/http/middleware/validation";
+
+export const APP_NAMES = [
+	"api",
+	// tatara:slot app-names
+] as const;
+
+export type AppName = (typeof APP_NAMES)[number];
+
+export interface RouteDefinition {
+	/** which HTTP app serves these routes */
+	app: AppName;
+	/** mounted under `/api` + basePath, e.g. "/notes" */
+	basePath: string;
+	router: OpenAPIHono<AppEnv>;
+}
+
+/** Default export of every `routes/*.routes.ts`; discovered by `tatara sync`. */
+export function defineRoutes(definition: RouteDefinition): RouteDefinition {
+	return definition;
+}
+
+/** A router for one routes file. Attach middleware per route or per path, never `use("*")`. */
+export function createRouter(): OpenAPIHono<AppEnv> {
+	return new OpenAPIHono<AppEnv>({ defaultHook: validationHook });
+}

package/templates/features/base/files/src/core/http/server.ts

@@ -0,0 +1,15 @@
+import { serve } from "@hono/node-server";
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { AppEnv } from "#core/http/context";
+import { logger } from "#core/logging/logger";
+import { handleSignals, onShutdown } from "#core/process/lifecycle";
+
+/** Starts an HTTP app; on shutdown stops accepting connections and drains in-flight requests. */
+export function startServer(app: OpenAPIHono<AppEnv>, port: number, name: string) {
+	const server = serve({ fetch: app.fetch, port }, (info) => {
+		logger.info({ port: info.port, app: name }, `${name} listening on http://localhost:${info.port}`);
+	});
+	onShutdown(`${name}-http`, () => new Promise<void>((resolve) => server.close(() => resolve())));
+	handleSignals();
+	return server;
+}

package/templates/features/base/files/src/core/logging/logger.ts

@@ -0,0 +1,17 @@
+import { pino } from "pino";
+import { env } from "#core/config/env";
+
+export const logger = pino({
+	level: env.LOG_LEVEL,
+	base: { service: "__APP_NAME__" },
+	...(env.NODE_ENV === "development"
+		? {
+				transport: {
+					target: "pino-pretty",
+					options: { colorize: true, ignore: "pid,hostname,service" },
+				},
+			}
+		: {}),
+});
+
+export type Logger = typeof logger;

package/templates/features/base/files/src/core/process/lifecycle.ts

@@ -0,0 +1,34 @@
+import { logger } from "#core/logging/logger";
+
+type Hook = () => Promise<void> | void;
+
+const hooks: { name: string; run: Hook }[] = [];
+let shuttingDown = false;
+
+/** Registers cleanup that runs on SIGTERM/SIGINT or `shutdown()`, last registered first. */
+export function onShutdown(name: string, run: Hook): void {
+	hooks.push({ name, run });
+}
+
+export async function shutdown(code = 0): Promise<never> {
+	if (!shuttingDown) {
+		shuttingDown = true;
+		for (const hook of [...hooks].reverse()) {
+			try {
+				await hook.run();
+			} catch (error) {
+				logger.error({ err: error, hook: hook.name }, "shutdown hook failed");
+			}
+		}
+	}
+	process.exit(code);
+}
+
+export function handleSignals(): void {
+	for (const signal of ["SIGTERM", "SIGINT"] as const) {
+		process.once(signal, () => {
+			logger.info({ signal }, "shutting down");
+			void shutdown(0);
+		});
+	}
+}

package/templates/features/base/files/src/modules/example/routes/greeting.routes.ts

@@ -0,0 +1,27 @@
+import { createRoute } from "@hono/zod-openapi";
+import { errorResponses, jsonContent, success, successSchema } from "#core/http/response";
+import { createRouter, defineRoutes } from "#core/http/routes";
+import { greet } from "#modules/example/services/greeting.service";
+import {
+	greetingQuerySchema,
+	greetingSchema,
+} from "#modules/example/validators/greeting.validators";
+
+const router = createRouter();
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/",
+		tags: ["Example"],
+		summary: "Say hello",
+		request: { query: greetingQuerySchema },
+		responses: {
+			200: jsonContent(successSchema(greetingSchema), "A greeting"),
+			...errorResponses(400),
+		},
+	}),
+	(c) => c.json(success(greet(c.req.valid("query").name)), 200),
+);
+
+export default defineRoutes({ app: "api", basePath: "/greetings", router });

package/templates/features/base/files/src/modules/example/services/greeting.service.ts

@@ -0,0 +1,3 @@
+export function greet(name?: string): { message: string } {
+	return { message: `Hello, ${name ?? "world"}!` };
+}

package/templates/features/base/files/src/modules/example/tests/greeting.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { greet } from "#modules/example/services/greeting.service";
+import { api } from "#tests/helpers/api";
+
+describe("greetings", () => {
+	it("greets by name", () => {
+		expect(greet("Ada")).toEqual({ message: "Hello, Ada!" });
+	});
+
+	it("serves GET /api/greetings", async () => {
+		const res = await api.get("/api/greetings?name=Ada");
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual({ success: true, data: { message: "Hello, Ada!" } });
+	});
+
+	it("rejects an invalid query with the error envelope", async () => {
+		const res = await api.get(`/api/greetings?name=${"x".repeat(60)}`);
+		expect(res.status).toBe(400);
+		expect(res.body).toMatchObject({ success: false, code: "VALIDATION_ERROR" });
+	});
+});

package/templates/features/base/files/src/modules/example/validators/greeting.validators.ts

@@ -0,0 +1,9 @@
+import { z } from "@hono/zod-openapi";
+
+export const greetingQuerySchema = z.object({
+	name: z.string().min(1).max(50).optional().openapi({ example: "Ada" }),
+});
+
+export const greetingSchema = z
+	.object({ message: z.string().openapi({ example: "Hello, Ada!" }) })
+	.openapi("Greeting");

package/templates/features/base/files/tests/helpers/api.ts

@@ -0,0 +1,54 @@
+import { app as apiApp } from "#apps/api/app";
+// tatara:slot imports
+
+type HttpApp = { request: (path: string, init?: RequestInit) => Response | Promise<Response> };
+
+export interface ApiResponse<T = unknown> {
+	status: number;
+	headers: Headers;
+	body: T;
+}
+
+export interface RequestOptions {
+	headers?: Record<string, string>;
+}
+
+async function send<T>(
+	target: HttpApp,
+	method: string,
+	path: string,
+	body: unknown,
+	options: RequestOptions = {},
+): Promise<ApiResponse<T>> {
+	const headers: Record<string, string> = { ...options.headers };
+	if (body !== undefined) headers["content-type"] = "application/json";
+	const res = await target.request(path, {
+		method,
+		headers,
+		body: body === undefined ? undefined : JSON.stringify(body),
+	});
+	const text = await res.text();
+	let parsed: unknown = text;
+	try {
+		parsed = text ? JSON.parse(text) : null;
+	} catch {}
+	return { status: res.status, headers: res.headers, body: parsed as T };
+}
+
+export function client(target: HttpApp) {
+	return {
+		get: <T = unknown>(path: string, o?: RequestOptions) => send<T>(target, "GET", path, undefined, o),
+		post: <T = unknown>(path: string, body?: unknown, o?: RequestOptions) =>
+			send<T>(target, "POST", path, body, o),
+		put: <T = unknown>(path: string, body?: unknown, o?: RequestOptions) =>
+			send<T>(target, "PUT", path, body, o),
+		patch: <T = unknown>(path: string, body?: unknown, o?: RequestOptions) =>
+			send<T>(target, "PATCH", path, body, o),
+		delete: <T = unknown>(path: string, o?: RequestOptions) =>
+			send<T>(target, "DELETE", path, undefined, o),
+	};
+}
+
+/** Calls the api app in-process (no network). */
+export const api = client(apiApp);
+// tatara:slot exports

package/templates/features/base/files/tests/setup.ts

@@ -0,0 +1,2 @@
+// Runs in every test worker before the test files.
+// tatara:slot setup