@tatara/cli 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,51 @@
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+
+export class AppError extends Error {
+	readonly status: ContentfulStatusCode;
+	readonly code: string;
+	readonly details?: unknown;
+
+	constructor(status: ContentfulStatusCode, code: string, message: string, details?: unknown) {
+		super(message);
+		this.name = new.target.name;
+		this.status = status;
+		this.code = code;
+		this.details = details;
+	}
+}
+
+export class ValidationError extends AppError {
+	constructor(message = "Invalid request", details?: unknown) {
+		super(400, "VALIDATION_ERROR", message, details);
+	}
+}
+
+export class BusinessRuleError extends AppError {
+	constructor(code: string, message: string, details?: unknown) {
+		super(400, code, message, details);
+	}
+}
+
+export class UnauthorizedError extends AppError {
+	constructor(message = "Authentication required") {
+		super(401, "UNAUTHORIZED", message);
+	}
+}
+
+export class ForbiddenError extends AppError {
+	constructor(message = "You do not have permission to do this") {
+		super(403, "FORBIDDEN", message);
+	}
+}
+
+export class NotFoundError extends AppError {
+	constructor(resource = "Resource") {
+		super(404, "NOT_FOUND", `${resource} not found`);
+	}
+}
+
+export class ConflictError extends AppError {
+	constructor(message = "Resource already exists", details?: unknown) {
+		super(409, "CONFLICT", message, details);
+	}
+}

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(
+			"Invalid request",
+			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,67 @@
+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 };
+}
+
+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

package/templates/features/base/files/tsconfig.json

@@ -0,0 +1,20 @@
+{
+	"compilerOptions": {
+		"target": "es2024",
+		"lib": ["es2024"],
+		"module": "nodenext",
+		"moduleResolution": "nodenext",
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noFallthroughCasesInSwitch": true,
+		"erasableSyntaxOnly": true,
+		"verbatimModuleSyntax": true,
+		"allowImportingTsExtensions": true,
+		"noEmit": true,
+		"skipLibCheck": true,
+		"resolveJsonModule": true,
+		"types": ["node"]
+	},
+	"include": ["src", "tests", "*.config.ts"]
+}

package/templates/features/base/files/tsdown.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+	entry: {
+		"apps/api/server": "src/apps/api/server.ts",
+		"apps/cli/index": "src/apps/cli/index.ts",
+		// tatara:slot entries
+	},
+	format: "esm",
+	platform: "node",
+	target: "node24",
+	outDir: "dist",
+	dts: false,
+	clean: true,
+});

package/templates/features/base/files/vitest.config.ts

@@ -0,0 +1,16 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parseEnv } from "node:util";
+import { defineConfig } from "vitest/config";
+
+const env = existsSync(".env.test")
+	? (parseEnv(readFileSync(".env.test", "utf8")) as Record<string, string>)
+	: {};
+
+export default defineConfig({
+	test: {
+		include: ["src/**/*.test.ts", "tests/**/*.test.ts"],
+		env,
+		setupFiles: ["tests/setup.ts"],
+		// tatara:slot vitest
+	},
+});

package/templates/features/better-auth/files/src/core/auth/auth.ts

@@ -0,0 +1,26 @@
+import { betterAuth } from "better-auth";
+import { bearer, openAPI } from "better-auth/plugins";
+import { database } from "#core/auth/adapter";
+import { env } from "#core/config/env";
+import { newId } from "#core/db/id";
+// tatara:slot imports
+
+export const auth = betterAuth({
+	appName: "__APP_NAME__",
+	baseURL: env.APP_URL,
+	basePath: "/api/auth",
+	secret: env.BETTER_AUTH_SECRET,
+	trustedOrigins: env.CORS_ORIGINS,
+	database,
+	advanced: { database: { generateId: () => newId() } },
+	// tatara:slot options
+	plugins: [
+		// Authorization: Bearer <session token> for mobile and API clients
+		bearer(),
+		// reference for the auth endpoints at /api/auth/reference
+		openAPI(),
+		// tatara:slot plugins
+	],
+});
+
+export type Session = typeof auth.$Infer.Session;

package/templates/features/better-auth/files/src/core/auth/db/seed.ts

@@ -0,0 +1,24 @@
+import { auth } from "#core/auth/auth";
+import { env } from "#core/config/env";
+import { defineSeed } from "#core/db/seed";
+
+/** Development admin account (never created in production). */
+export default defineSeed({
+	name: "auth:dev-admin",
+	order: 0,
+	async run({ logger }) {
+		if (env.NODE_ENV !== "development" && env.NODE_ENV !== "test") return;
+		const ctx = await auth.$context;
+		const email = env.SEED_ADMIN_EMAIL;
+		const existing = await ctx.internalAdapter.findUserByEmail(email);
+		if (existing) return;
+		const user = await ctx.internalAdapter.createUser({
+			email,
+			name: "Dev admin",
+			emailVerified: true,
+			// tatara:slot seed-user-fields
+		}, { method: "admin" });
+		// tatara:slot seed-after-user
+		logger.info({ email, userId: user.id }, "created development admin");
+	},
+});

package/templates/features/better-auth/files/src/core/auth/delivery.ts

@@ -0,0 +1,48 @@
+import { smsSender } from "#core/auth/sms";
+import { env } from "#core/config/env";
+// tatara:slot imports
+
+export interface OutboxMessage {
+	channel: "email" | "sms";
+	to: string;
+	subject?: string;
+	text: string;
+	/** one-time code, when the message carries one */
+	code?: string;
+	sentAt: string;
+}
+
+const outbox: OutboxMessage[] = [];
+
+/** Only with DEV_OUTBOX=true in development or test: the outbox exposes sign-in codes. */
+export function outboxEnabled(): boolean {
+	return env.DEV_OUTBOX && (env.NODE_ENV === "development" || env.NODE_ENV === "test");
+}
+
+/** Messages are kept here so tests and local sign-in can read codes. */
+function record(message: Omit<OutboxMessage, "sentAt">) {
+	if (!outboxEnabled()) return;
+	outbox.push({ ...message, sentAt: new Date().toISOString() });
+	if (outbox.length > 200) outbox.shift();
+}
+
+/** Newest first. Empty unless the outbox is enabled. */
+export function readOutbox(to?: string): OutboxMessage[] {
+	if (!outboxEnabled()) return [];
+	return outbox.filter((m) => !to || m.to === to).reverse();
+}
+
+export async function deliverEmail(message: {
+	to: string;
+	subject: string;
+	text: string;
+	code?: string;
+}): Promise<void> {
+	record({ channel: "email", ...message });
+	// tatara:slot email-delivery
+}
+
+export async function deliverSms(message: { to: string; text: string; code?: string }): Promise<void> {
+	record({ channel: "sms", ...message });
+	await smsSender.send(message.to, message.text);
+}

package/templates/features/better-auth/files/src/core/auth/principal.ts

@@ -0,0 +1,23 @@
+import { createMiddleware } from "hono/factory";
+import { auth } from "#core/auth/auth";
+import type { AppEnv } from "#core/http/context";
+
+/** Resolves the session (cookie or bearer token) into `c.var.principal`. */
+export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
+	const session = await auth.api.getSession({ headers: c.req.raw.headers });
+	if (session) {
+		const user = session.user as typeof session.user & { role?: string | null };
+		const s = session.session as typeof session.session & { activeOrganizationId?: string | null };
+		c.set("principal", {
+			userId: user.id,
+			orgId: s.activeOrganizationId ?? null,
+			roles: (user.role ?? "user")
+				.split(",")
+				.map((role) => role.trim())
+				.filter(Boolean),
+			kind: "user",
+			claims: {},
+		});
+	}
+	await next();
+});

package/templates/features/better-auth/files/src/core/auth/sms.ts

@@ -0,0 +1,14 @@
+import { logger } from "#core/logging/logger";
+
+/** Implement this for your SMS provider and return it from `smsSender`. */
+export interface SmsSender {
+	send(to: string, text: string): Promise<void>;
+}
+
+const consoleSender: SmsSender = {
+	async send(to) {
+		logger.info({ to }, "sms not sent: no SMS provider configured (see src/core/auth/sms.ts)");
+	},
+};
+
+export const smsSender: SmsSender = consoleSender;