@tatara/cli 0.1.0 → 0.1.2

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

@@ -4,48 +4,76 @@ 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) {
+	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 = "Invalid request", details?: unknown) {
-		super(400, "VALIDATION_ERROR", message, details);
+	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) {
-		super(400, code, message, details);
+		// 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 = "Authentication required") {
-		super(401, "UNAUTHORIZED", message);
+	constructor(message?: string) {
+		super(
+			401,
+			"UNAUTHORIZED",
+			message ?? "Authentication required",
+			undefined,
+			message === undefined,
+		);
 	}
 }
 
 export class ForbiddenError extends AppError {
-	constructor(message = "You do not have permission to do this") {
-		super(403, "FORBIDDEN", message);
+	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 = "Resource") {
-		super(404, "NOT_FOUND", `${resource} not found`);
+	constructor(resource?: string) {
+		super(
+			404,
+			"NOT_FOUND",
+			`${resource ?? "Resource"} not found`,
+			undefined,
+			resource === undefined,
+		);
 	}
 }
 
 export class ConflictError extends AppError {
-	constructor(message = "Resource already exists", details?: unknown) {
-		super(409, "CONFLICT", message, details);
+	constructor(message?: string, details?: unknown) {
+		super(409, "CONFLICT", message ?? "Resource already exists", details, message === undefined);
 	}
 }

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

@@ -6,7 +6,7 @@ import { ValidationError } from "#core/http/errors";
 export const validationHook: Hook<any, AppEnv, any, any> = (result) => {
 	if (!result.success) {
 		throw new ValidationError(
-			"Invalid request",
+			undefined,
 			result.error.issues.map((issue) => ({
 				path: issue.path.join("."),
 				message: issue.message,

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

@@ -49,6 +49,11 @@ 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",

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

@@ -0,0 +1,60 @@
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import { auth } from "#core/auth/auth";
+
+type JsonObject = Record<string, unknown>;
+type OpenApiDocument = ReturnType<OpenAPIHono["getOpenAPI31Document"]>;
+type Paths = NonNullable<OpenApiDocument["paths"]>;
+type Components = NonNullable<OpenApiDocument["components"]>;
+
+interface AuthDocument {
+	paths?: Record<string, JsonObject>;
+	components?: { schemas?: JsonObject; securitySchemes?: JsonObject };
+}
+
+const SCHEMA_REF = "#/components/schemas/";
+
+// better-auth names schemas like the app (User, Member, …); prefix them so neither side is overwritten
+function renameRefs(value: unknown, rename: (name: string) => string): AuthDocument {
+	return JSON.parse(
+		JSON.stringify(value).replaceAll(
+			new RegExp(`"\\$ref":"${SCHEMA_REF}([^"]+)"`, "g"),
+			(_match, name: string) => `"$ref":"${SCHEMA_REF}${rename(name)}"`,
+		),
+	) as AuthDocument;
+}
+
+function retag(paths: Record<string, JsonObject>, tag: string): Record<string, JsonObject> {
+	for (const operations of Object.values(paths)) {
+		for (const operation of Object.values(operations as Record<string, JsonObject>)) {
+			if (operation && typeof operation === "object") operation.tags = [tag];
+		}
+	}
+	return paths;
+}
+
+/** Adds better-auth's endpoints (served under `basePath`) to the app's OpenAPI document. */
+export async function mergeAuthOpenApi(document: OpenApiDocument, basePath: string): Promise<void> {
+	const authDoc = renameRefs(await auth.api.generateOpenAPISchema(), (name) => `Auth${name}`);
+
+	document.paths ??= {};
+	for (const [path, operations] of Object.entries(retag(authDoc.paths ?? {}, "Auth"))) {
+		document.paths[`${basePath}${path}`] = operations as Paths[string];
+	}
+
+	document.components ??= {};
+	document.components.schemas ??= {};
+	for (const [name, schema] of Object.entries(authDoc.components?.schemas ?? {})) {
+		document.components.schemas[`Auth${name}`] = schema as NonNullable<
+			Components["schemas"]
+		>[string];
+	}
+	document.components.securitySchemes = {
+		...(authDoc.components?.securitySchemes as Components["securitySchemes"]),
+		...document.components.securitySchemes,
+	};
+
+	document.tags = [
+		...(document.tags ?? []),
+		{ name: "Auth", description: "Sign-up, sign-in, sessions, organizations (better-auth)" },
+	];
+}

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

@@ -2,6 +2,23 @@ import { createMiddleware } from "hono/factory";
 import { auth } from "#core/auth/auth";
 import type { AppEnv } from "#core/http/context";
 
+/**
+ * The session's active organization, or null once the user stops being a member of it.
+ * better-auth leaves `activeOrganizationId` on the removed member's session.
+ */
+async function activeMembership(userId: string, orgId: string | null | undefined) {
+	if (!orgId) return null;
+	const { adapter } = await auth.$context;
+	const member = await adapter.findOne({
+		model: "member",
+		where: [
+			{ field: "organizationId", value: orgId },
+			{ field: "userId", value: userId },
+		],
+	});
+	return member ? orgId : null;
+}
+
 /** 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 });
@@ -10,7 +27,7 @@ export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
 		const s = session.session as typeof session.session & { activeOrganizationId?: string | null };
 		c.set("principal", {
 			userId: user.id,
-			orgId: s.activeOrganizationId ?? null,
+			orgId: await activeMembership(user.id, s.activeOrganizationId),
 			roles: (user.role ?? "user")
 				.split(",")
 				.map((role) => role.trim())
@@ -19,5 +36,6 @@ export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
 			claims: {},
 		});
 	}
+	// tatara:slot no-session
 	await next();
 });

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

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { api } from "#tests/helpers/api";
+
+interface Document {
+	paths: Record<string, Record<string, { tags?: string[] }>>;
+	components: { schemas: Record<string, unknown>; securitySchemes: Record<string, unknown> };
+}
+
+async function apiDocument(): Promise<Document> {
+	const res = await api.get<Document>("/openapi.json");
+	expect(res.status).toBe(200);
+	return res.body;
+}
+
+function refs(value: unknown): string[] {
+	return [...JSON.stringify(value).matchAll(/"\$ref":"#\/components\/schemas\/([^"]+)"/g)].map(
+		(match) => match[1] ?? "",
+	);
+}
+
+describe("OpenAPI document", () => {
+	it("documents better-auth endpoints next to the app's own", async () => {
+		const doc = await apiDocument();
+		expect(doc.paths["/api/auth/get-session"]?.get).toBeDefined();
+		expect(doc.paths["/api/me"]?.get).toBeDefined();
+	});
+
+	it("tags better-auth operations as Auth", async () => {
+		const doc = await apiDocument();
+		expect(doc.paths["/api/auth/get-session"]?.get?.tags).toEqual(["Auth"]);
+	});
+
+	it("prefixes better-auth schemas so app schemas keep their names", async () => {
+		const doc = await apiDocument();
+		expect(doc.components.schemas.AuthUser).toBeDefined();
+		expect(doc.components.schemas.Principal).toBeDefined();
+		expect(doc.components.securitySchemes.bearerAuth).toBeDefined();
+	});
+
+	it("resolves every schema reference", async () => {
+		const doc = await apiDocument();
+		const missing = refs(doc).filter((name) => !(name in doc.components.schemas));
+		expect(missing).toEqual([]);
+	});
+});

package/templates/features/better-auth/files/tests/helpers/auth.ts

@@ -26,6 +26,7 @@ export async function createTestUser(options: AsUserOptions = {}): Promise<strin
 export async function authenticate(
 	options: AsUserOptions = {},
 ): Promise<{ userId: string; headers: Record<string, string> }> {
+	// tatara:slot authenticate
 	const userId = await createTestUser(options);
 	const ctx = await auth.$context;
 	const session = await ctx.internalAdapter.createSession(userId);
@@ -38,3 +39,4 @@ export async function asUser(options: AsUserOptions = {}): Promise<Record<string
 	// tatara:slot as-user
 	return user.headers;
 }
+// tatara:slot helpers

package/templates/features/better-auth/files+admin/src/core/auth/tests/openapi-admin.test.ts

@@ -0,0 +1,8 @@
+import { expect, it } from "vitest";
+import { adminApi } from "#tests/helpers/api";
+
+it("leaves auth out of the admin OpenAPI document", async () => {
+	const res = await adminApi.get<{ paths: Record<string, unknown> }>("/openapi.json");
+	expect(res.status).toBe(200);
+	expect(Object.keys(res.body.paths).some((path) => path.startsWith("/api/auth/"))).toBe(false);
+});

package/templates/features/better-auth/files+auth-orgs/src/core/auth/tests/principal.test.ts

@@ -0,0 +1,44 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { api } from "#tests/helpers/api";
+import { authenticate } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("principal", () => {
+	it("drops the active organization once the user is no longer a member", async () => {
+		const owner = await authenticate();
+		const member = await authenticate({ email: "member@example.com" });
+		const org = await api.post<{ id: string }>(
+			"/api/auth/organization/create",
+			{ name: "School", slug: "school" },
+			{ headers: owner.headers },
+		);
+		await auth.api.addMember({
+			body: { userId: member.userId, role: "member", organizationId: org.body.id },
+		});
+		await api.post(
+			"/api/auth/organization/set-active",
+			{ organizationId: org.body.id },
+			{ headers: member.headers },
+		);
+		const before = await api.get<{ data: { orgId: string | null } }>("/api/me", {
+			headers: member.headers,
+		});
+		expect(before.body.data.orgId).toBe(org.body.id);
+
+		const removed = await api.post(
+			"/api/auth/organization/remove-member",
+			{ memberIdOrEmail: "member@example.com", organizationId: org.body.id },
+			{ headers: owner.headers },
+		);
+		expect(removed.status).toBe(200);
+		const after = await api.get<{ data: { orgId: string | null } }>("/api/me", {
+			headers: member.headers,
+		});
+		expect(after.body.data.orgId).toBeNull();
+	});
+});

package/templates/features/better-auth/files+auth-orgs+authz/src/core/auth/tests/principal-authz.test.ts

@@ -0,0 +1,40 @@
+import { beforeEach, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { api } from "#tests/helpers/api";
+import { authenticate } from "#tests/helpers/auth";
+import { applyTestAccess } from "#tests/helpers/authz";
+import { resetDatabase } from "#tests/helpers/db";
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+it("does not restore old org roles when a removed member is added back", async () => {
+	const owner = await authenticate();
+	const member = await authenticate({ email: "member@example.com" });
+	const org = await api.post<{ id: string }>(
+		"/api/auth/organization/create",
+		{ name: "School", slug: "school" },
+		{ headers: owner.headers },
+	);
+	await auth.api.addMember({
+		body: { userId: member.userId, role: "member", organizationId: org.body.id },
+	});
+	await applyTestAccess(member.userId, { systemRoles: ["admin"], orgId: org.body.id });
+	await api.post(
+		"/api/auth/organization/remove-member",
+		{ memberIdOrEmail: "member@example.com", organizationId: org.body.id },
+		{ headers: owner.headers },
+	);
+
+	await auth.api.addMember({
+		body: { userId: member.userId, role: "member", organizationId: org.body.id },
+	});
+	await api.post(
+		"/api/auth/organization/set-active",
+		{ organizationId: org.body.id },
+		{ headers: member.headers },
+	);
+	const roles = await api.get("/api/authorization/roles", { headers: member.headers });
+	expect(roles.status).toBe(403);
+});

package/templates/features/db/files/src/core/db/commands/reset.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand, flag } from "#core/commands/define";
 import { env } from "#core/config/env";
 import { dropAllTables } from "#core/db/admin";
 import { migrateDatabase } from "#core/db/migrate";
@@ -7,7 +7,7 @@ import { migrateDatabase } from "#core/db/migrate";
 export default defineCommand({
 	name: "db:reset",
 	description: "Drop every table and re-apply migrations (refuses to run in production)",
-	args: z.object({ force: z.coerce.boolean().default(false) }),
+	args: z.object({ force: flag() }),
 	async run({ force }, { logger }) {
 		if (env.NODE_ENV === "production" && !force) {
 			throw new Error("db:reset refuses to run with NODE_ENV=production (pass --force to override)");

package/templates/features/db/files/src/core/db/tests/reset.test.ts

@@ -0,0 +1,7 @@
+import { expect, it } from "vitest";
+import { parseFlags } from "#core/commands/runner";
+import reset from "#core/db/commands/reset";
+
+it("does not treat --force false as forcing db:reset", () => {
+	expect(reset.args?.parse(parseFlags(["--force", "false"]))).toEqual({ force: false });
+});

package/templates/generators/command/files/src/modules/__moduleKebab__/commands/__nameKebab__.ts

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand, flag } from "#core/commands/define";
 
 export default defineCommand({
 	name: "__moduleKebab__:__nameKebab__",
 	description: "__nameTitle__",
-	args: z.object({ dryRun: z.coerce.boolean().default(false) }),
+	args: z.object({ dryRun: flag() }),
 	async run({ dryRun }, { logger }) {
 		logger.info({ dryRun }, "__moduleKebab__:__nameKebab__ ran");
 	},

package/templates/generators/resource/files/src/modules/__moduleKebab__/routes/__nameKebab__.routes.ts

@@ -1,6 +1,7 @@
 import { createRoute } from "@hono/zod-openapi";
 import {
 	errorResponses,
+	jsonBody,
 	jsonContent,
 	paginated,
 	paginatedSchema,
@@ -72,7 +73,7 @@ router.openapi(
 		tags,
 		summary: "Create a __nameKebab__",
 		// tatara:slot guard-create
-		request: { body: jsonContent(create__namePascal__Schema, "The new __nameKebab__") },
+		request: { body: jsonBody(create__namePascal__Schema, "The new __nameKebab__") },
 		responses: {
 			201: jsonContent(successSchema(__nameCamel__Schema), "Created"),
 			...errorResponses(400),
@@ -91,7 +92,7 @@ router.openapi(
 		// tatara:slot guard-update
 		request: {
 			params: __nameCamel__ParamsSchema,
-			body: jsonContent(update__namePascal__Schema, "Fields to change"),
+			body: jsonBody(update__namePascal__Schema, "Fields to change"),
 		},
 		responses: {
 			200: jsonContent(successSchema(__nameCamel__Schema), "Updated"),

package/templates/features/keycloak/files/src/core/auth/principal.ts

@@ -1,27 +0,0 @@
-import { createMiddleware } from "hono/factory";
-import { organizationOf, rolesOf, verifyAccessToken } from "#core/auth/keycloak";
-import { ensureLocalUser } from "#core/auth/users";
-import type { AppEnv } from "#core/http/context";
-
-/** Verifies `Authorization: Bearer <Keycloak access token>` into `c.var.principal`. */
-export const attachPrincipal = createMiddleware<AppEnv>(async (c, next) => {
-	const header = c.req.header("authorization");
-	const token = header?.startsWith("Bearer ") ? header.slice(7) : undefined;
-	if (token) {
-		try {
-			const claims = await verifyAccessToken(token);
-			const isService = claims.preferred_username?.startsWith("service-account-") ?? false;
-			if (!isService) await ensureLocalUser(claims);
-			c.set("principal", {
-				userId: claims.sub,
-				orgId: organizationOf(claims),
-				roles: rolesOf(claims),
-				kind: isService ? "service" : "user",
-				claims,
-			});
-		} catch (error) {
-			c.get("logger").debug({ err: error }, "rejected bearer token");
-		}
-	}
-	await next();
-});

package/templates/features/keycloak/files/tests/helpers/auth.ts

@@ -1,52 +0,0 @@
-import { generateKeyPair, SignJWT } from "jose";
-import { issuer, setKeySource } from "#core/auth/keycloak";
-import { env } from "#core/config/env";
-import { newId } from "#core/db/id";
-// tatara:slot imports
-
-const { publicKey, privateKey } = await generateKeyPair("RS256");
-setKeySource(async (header) => {
-	if (header.kid !== "test") throw new Error("unknown key");
-	return publicKey;
-});
-
-export interface AsUserOptions {
-	sub?: string;
-	email?: string;
-	roles?: string[];
-	orgId?: string;
-	// tatara:slot options
-}
-
-/** Signs a token the API accepts, as if Keycloak issued it for a new user. */
-export async function tokenFor(options: AsUserOptions = {}): Promise<string> {
-	const sub = options.sub ?? newId();
-	return new SignJWT({
-		email: options.email ?? `user-${sub}@example.com`,
-		preferred_username: `user-${sub.slice(0, 8)}`,
-		roles: options.roles ?? ["user"],
-		...(options.orgId ? { organization: [options.orgId] } : {}),
-	})
-		.setProtectedHeader({ alg: "RS256", kid: "test" })
-		.setSubject(sub)
-		.setIssuer(issuer)
-		.setAudience(env.KEYCLOAK_AUDIENCE)
-		.setIssuedAt()
-		.setExpirationTime("5m")
-		.sign(privateKey);
-}
-
-/** A new user (random subject) with a signed access token. */
-export async function authenticate(
-	options: AsUserOptions = {},
-): Promise<{ userId: string; headers: Record<string, string> }> {
-	const sub = options.sub ?? newId();
-	return { userId: sub, headers: { authorization: `Bearer ${await tokenFor({ ...options, sub })}` } };
-}
-
-/** Headers that authenticate as a new user. */
-export async function asUser(options: AsUserOptions = {}): Promise<Record<string, string>> {
-	const user = await authenticate(options);
-	// tatara:slot as-user
-	return user.headers;
-}

package/templates/features/keycloak/files+drizzle/src/core/auth/users.ts

@@ -1,18 +0,0 @@
-import type { KeycloakClaims } from "#core/auth/keycloak";
-import { users } from "#core/auth/db/user.schema";
-import { db } from "#core/db/client";
-
-const known = new Set<string>();
-
-/** Creates the local user row for a token subject the first time it is seen. */
-export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
-	if (known.has(claims.sub)) return;
-	const values = {
-		id: claims.sub,
-		email: claims.email ?? null,
-		name: claims.name ?? claims.preferred_username ?? null,
-	};
-	// tatara:slot upsert
-	if (known.size > 10_000) known.clear();
-	known.add(claims.sub);
-}

package/templates/features/keycloak/files+drizzle+mysql/src/core/auth/db/user.schema.ts

@@ -1,10 +0,0 @@
-import { mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
-
-/** Local copy of Keycloak users (id = token subject), created on first request. */
-export const users = mysqlTable("users", {
-	id: varchar({ length: 36 }).primaryKey(),
-	email: varchar({ length: 255 }),
-	name: varchar({ length: 255 }),
-	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
-	updatedAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
-});

package/templates/features/keycloak/files+drizzle+postgres/src/core/auth/db/user.schema.ts

@@ -1,10 +0,0 @@
-import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
-
-/** Local copy of Keycloak users (id = token subject), created on first request. */
-export const users = pgTable("users", {
-	id: text().primaryKey(),
-	email: text(),
-	name: text(),
-	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
-	updatedAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
-});

package/templates/features/keycloak/files+prisma/prisma/models/user.prisma

@@ -1,10 +0,0 @@
-/// Local copy of Keycloak users (id = token subject), created on first request.
-model User {
-  id        String   @id @db.VarChar(36)
-  email     String?  @db.VarChar(255)
-  name      String?  @db.VarChar(255)
-  createdAt DateTime @default(now()) @map("created_at")
-  updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
-
-  @@map("users")
-}

package/templates/features/keycloak/files+prisma/src/core/auth/users.ts

@@ -1,13 +0,0 @@
-import type { KeycloakClaims } from "#core/auth/keycloak";
-import { db } from "#core/db/client";
-
-const known = new Set<string>();
-
-/** Creates the local user row for a token subject the first time it is seen. */
-export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
-	if (known.has(claims.sub)) return;
-	const data = { email: claims.email ?? null, name: claims.name ?? claims.preferred_username ?? null };
-	await db.user.upsert({ where: { id: claims.sub }, create: { id: claims.sub, ...data }, update: data });
-	if (known.size > 10_000) known.clear();
-	known.add(claims.sub);
-}