@tatara/cli 0.1.0 → 0.1.1

package/dist/bin.mjs

@@ -90,6 +90,36 @@ function loadProject(from = process.cwd()) {
 	};
 }
 //#endregion
+//#region src/commands/route-mounts.ts
+const ROUTE_FILE = /\/routes\/[^/]+\.routes\.ts$/;
+const DEFINE_ROUTES = /defineRoutes\(\s*\{([^}]*)\}/;
+function lineOf$1(text, index) {
+	return text.slice(0, index).split("\n").length;
+}
+/** Route files that mount on an app + basePath already taken by an earlier file (sorted by path). */
+function routeMountCollisions(sources) {
+	const owners = /* @__PURE__ */ new Map();
+	const violations = [];
+	for (const file of [...sources.keys()].sort()) {
+		if (!ROUTE_FILE.test(file)) continue;
+		const text = sources.get(file) ?? "";
+		const call = DEFINE_ROUTES.exec(text);
+		const app = call && /\bapp:\s*["']([^"']+)["']/.exec(call[1] ?? "")?.[1];
+		const basePath = call && /\bbasePath:\s*["']([^"']+)["']/.exec(call[1] ?? "")?.[1];
+		if (!call || !app || !basePath) continue;
+		const key = `${app} "${basePath}"`;
+		const owner = owners.get(key);
+		if (owner) violations.push({
+			file,
+			line: lineOf$1(text, call.index),
+			rule: "duplicate-base-path",
+			message: `${key} is already mounted by ${owner}; routers on one base path shadow each other, so give this one its own basePath`
+		});
+		else owners.set(key, file);
+	}
+	return violations;
+}
+//#endregion
 //#region src/commands/check.ts
 const IMPORT = /(?:import|export)\s[^"']*?from\s*["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/g;
 function lineOf(text, index) {
@@ -150,6 +180,7 @@ async function check(project = loadProject()) {
 			});
 		}
 	}
+	violations.push(...routeMountCollisions(sources));
 	return violations.filter((v) => !ignored(v, sources.get(v.file) ?? ""));
 }
 /** `// tatara-check-ignore <rule>: <reason>` on the line above a violation silences it. */
@@ -835,7 +866,7 @@ const storage = {
 	env: [
 		{
 			key: "STORAGE_DRIVER",
-			schema: "z.enum([\"local\", \"s3\"]).default(\"local\")",
+			schema: "localDefault(z.enum([\"local\", \"s3\"]), \"local\")",
 			example: "s3",
 			test: "local"
 		},
@@ -905,20 +936,29 @@ const storage = {
 		}
 	} },
 	composeVolumes: ["storage-data"],
-	slots: [{
-		file: ".gitignore",
-		slot: "ignore",
-		content: ".storage/"
-	}, {
-		file: "AGENTS.md",
-		slot: "sections",
-		content: `## Storage
+	slots: [
+		{
+			file: "Dockerfile",
+			slot: "docker-runtime",
+			order: 50,
+			content: "RUN mkdir -p .storage && chown node:node .storage"
+		},
+		{
+			file: ".gitignore",
+			slot: "ignore",
+			content: ".storage/"
+		},
+		{
+			file: "AGENTS.md",
+			slot: "sections",
+			content: `## Storage
 
 - Use \`storage\` from \`#core/storage/index\` (\`put\`, \`get\`, \`delete\`, \`url\`). \`STORAGE_DRIVER=s3\` works with
   any S3-compatible store (RustFS locally, AWS S3, R2); \`local\` writes to \`STORAGE_LOCAL_DIR\` (tests).
 - \`tatara run storage:check\` creates the bucket and does a round-trip.
 `
-	}]
+		}
+	]
 };
 const email = {
 	id: "email",
@@ -929,13 +969,13 @@ const email = {
 	env: [
 		{
 			key: "EMAIL_DRIVER",
-			schema: "z.enum([\"smtp\", \"console\"]).default(\"console\")",
+			schema: "localDefault(z.enum([\"smtp\", \"console\"]), \"console\")",
 			example: "smtp",
 			test: "console"
 		},
 		{
 			key: "SMTP_URL",
-			schema: "z.string().default(\"smtp://localhost:1025\")",
+			schema: "localDefault(z.string(), \"smtp://localhost:1025\")",
 			example: "smtp://localhost:1025"
 		},
 		{
@@ -1009,7 +1049,7 @@ const i18n = {
 		{
 			file: "src/core/http/middleware/error-handler.ts",
 			slot: "error-message",
-			content: "message = t(c.get(\"language\"), `errors.${err.code}`, message);"
+			content: "if (err.translatable) message = t(c.get(\"language\"), `errors.${err.code}`, message);"
 		},
 		{
 			file: "AGENTS.md",
@@ -1067,7 +1107,8 @@ const auth = {
 };
 const BETTER_AUTH_AGENTS = `### better-auth
 
-- Endpoints are served at \`/api/auth/*\`; their reference is at \`/api/auth/reference\`.
+- Endpoints are served at \`/api/auth/*\` and listed in \`/openapi.json\` and \`/docs\` under the Auth tag
+  (schemas prefixed \`Auth\`). better-auth's own reference is also at \`/api/auth/reference\`.
 - Sessions work as cookies (browsers) and as \`Authorization: Bearer <session token>\` (mobile, APIs).
 - Outside production, every email and SMS is kept in an in-memory outbox:
   \`GET /api/dev/outbox?to=<address>\` returns the latest messages, including sign-in codes.
@@ -1113,6 +1154,16 @@ const betterAuth = {
 			slot: "imports",
 			content: "import { outboxEnabled, readOutbox } from \"#core/auth/delivery\";"
 		},
+		{
+			file: "src/core/http/app.ts",
+			slot: "imports",
+			content: "import { mergeAuthOpenApi } from \"#core/auth/openapi\";"
+		},
+		{
+			file: "src/core/http/app.ts",
+			slot: "openapi",
+			content: "if (name === \"api\") await mergeAuthOpenApi(document, `${API_PREFIX}/auth`);"
+		},
 		{
 			file: "src/core/http/app.ts",
 			slot: "routes",
@@ -1288,6 +1339,64 @@ const authPassword = {
 		}
 	]
 };
+const adminFields = [
+	{
+		file: "src/core/auth/db/auth.schema.ts",
+		slot: "user-fields",
+		when: drizzlePg,
+		content: "role: text(),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ withTimezone: true, mode: \"date\" }),"
+	},
+	{
+		file: "src/core/auth/db/auth.schema.ts",
+		slot: "user-fields",
+		when: drizzleMy,
+		content: "role: varchar({ length: 255 }),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ fsp: 3, mode: \"date\" }),"
+	},
+	{
+		file: "src/core/auth/db/auth.schema.ts",
+		slot: "session-fields",
+		when: drizzlePg,
+		content: "activeOrganizationId: text(),\nimpersonatedBy: text(),"
+	},
+	{
+		file: "src/core/auth/db/auth.schema.ts",
+		slot: "session-fields",
+		when: drizzleMy,
+		content: "activeOrganizationId: varchar({ length: 36 }),\nimpersonatedBy: varchar({ length: 36 }),"
+	},
+	{
+		file: "prisma/models/auth.prisma",
+		slot: "user-fields",
+		content: [
+			"role       String?   @db.VarChar(255)",
+			"banned     Boolean?  @default(false)",
+			"banReason  String?   @map(\"ban_reason\") @db.Text",
+			"banExpires DateTime? @map(\"ban_expires\")"
+		].join("\n")
+	},
+	{
+		file: "prisma/models/auth.prisma",
+		slot: "user-relations",
+		content: "members     Member[]\ninvitations Invitation[]"
+	},
+	{
+		file: "prisma/models/auth.prisma",
+		slot: "session-fields",
+		content: ["activeOrganizationId String? @map(\"active_organization_id\") @db.VarChar(36)", "impersonatedBy       String? @map(\"impersonated_by\") @db.VarChar(36)"].join("\n")
+	},
+	{
+		file: "src/core/auth/adapter.ts",
+		slot: "imports",
+		when: ["drizzle"],
+		content: "import * as orgSchema from \"#core/auth/db/organization.schema\";"
+	},
+	{
+		file: "src/core/auth/adapter.ts",
+		slot: "adapter-schema",
+		when: ["drizzle"],
+		content: "organization: orgSchema.organizations,\nmember: orgSchema.members,\ninvitation: orgSchema.invitations,"
+	}
+];
 const authOrgs = {
 	id: "auth-orgs",
 	kind: "auth-method",
@@ -1301,9 +1410,33 @@ const authOrgs = {
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "plugins",
+			unless: ["authz"],
 			content: "organization(),\nadmin(),",
 			order: 900
 		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "plugins",
+			when: ["authz"],
+			content: [
+				"organization({",
+				"	organizationHooks: {",
+				"		// authz rows outlive better-auth's member row; without this, re-adding restores old roles",
+				"		afterRemoveMember: async ({ member }) => {",
+				"			await removeMemberAccess(member.organizationId, member.userId);",
+				"		},",
+				"	},",
+				"}),",
+				"admin(),"
+			].join("\n"),
+			order: 900
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			when: ["authz"],
+			content: "import { removeMemberAccess } from \"#core/authz/services/members\";"
+		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "user-fields",
@@ -1314,64 +1447,7 @@ const authOrgs = {
 			slot: "seed-user-fields",
 			content: "role: \"admin\","
 		},
-		...[
-			{
-				file: "src/core/auth/db/auth.schema.ts",
-				slot: "user-fields",
-				when: drizzlePg,
-				content: "role: text(),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ withTimezone: true, mode: \"date\" }),"
-			},
-			{
-				file: "src/core/auth/db/auth.schema.ts",
-				slot: "user-fields",
-				when: drizzleMy,
-				content: "role: varchar({ length: 255 }),\nbanned: boolean().default(false),\nbanReason: text(),\nbanExpires: timestamp({ fsp: 3, mode: \"date\" }),"
-			},
-			{
-				file: "src/core/auth/db/auth.schema.ts",
-				slot: "session-fields",
-				when: drizzlePg,
-				content: "activeOrganizationId: text(),\nimpersonatedBy: text(),"
-			},
-			{
-				file: "src/core/auth/db/auth.schema.ts",
-				slot: "session-fields",
-				when: drizzleMy,
-				content: "activeOrganizationId: varchar({ length: 36 }),\nimpersonatedBy: varchar({ length: 36 }),"
-			},
-			{
-				file: "prisma/models/auth.prisma",
-				slot: "user-fields",
-				content: [
-					"role       String?   @db.VarChar(255)",
-					"banned     Boolean?  @default(false)",
-					"banReason  String?   @map(\"ban_reason\") @db.Text",
-					"banExpires DateTime? @map(\"ban_expires\")"
-				].join("\n")
-			},
-			{
-				file: "prisma/models/auth.prisma",
-				slot: "user-relations",
-				content: "members     Member[]\ninvitations Invitation[]"
-			},
-			{
-				file: "prisma/models/auth.prisma",
-				slot: "session-fields",
-				content: ["activeOrganizationId String? @map(\"active_organization_id\") @db.VarChar(36)", "impersonatedBy       String? @map(\"impersonated_by\") @db.VarChar(36)"].join("\n")
-			},
-			{
-				file: "src/core/auth/adapter.ts",
-				slot: "imports",
-				when: ["drizzle"],
-				content: "import * as orgSchema from \"#core/auth/db/organization.schema\";"
-			},
-			{
-				file: "src/core/auth/adapter.ts",
-				slot: "adapter-schema",
-				when: ["drizzle"],
-				content: "organization: orgSchema.organizations,\nmember: orgSchema.members,\ninvitation: orgSchema.invitations,"
-			}
-		]
+		...adminFields
 	]
 };
 const keycloak = {
@@ -1389,7 +1465,7 @@ const keycloak = {
 		},
 		{
 			key: "KEYCLOAK_URL",
-			schema: "z.url().default(\"http://localhost:8080\")",
+			schema: "localDefault(z.url(), \"http://localhost:8080\")",
 			example: "http://localhost:8080"
 		},
 		{
@@ -1509,13 +1585,13 @@ const base = {
 		},
 		{
 			key: "APP_URL",
-			schema: "z.url().default(\"http://localhost:3000\")",
+			schema: "localDefault(z.url(), \"http://localhost:3000\")",
 			example: "http://localhost:3000",
 			comment: "Public URL of the API"
 		},
 		{
 			key: "CORS_ORIGINS",
-			schema: "z.string().default(\"http://localhost:5173\").transform((v) => v.split(\",\").map((o) => o.trim()).filter(Boolean))",
+			schema: "localDefault(z.string(), \"http://localhost:5173\").transform((v) => v.split(\",\").map((o) => o.trim()).filter(Boolean))",
 			example: "http://localhost:5173",
 			comment: "Comma-separated browser origins allowed to call the API"
 		},
@@ -1550,7 +1626,7 @@ const pnpm = {
 			slot: "docker-build",
 			content: [
 				"COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./",
-				"RUN pnpm install --frozen-lockfile",
+				"RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store --mount=type=cache,id=pnpm-cache,target=/root/.cache/pnpm pnpm install --frozen-lockfile",
 				"COPY . .",
 				"RUN pnpm run build"
 			].join("\n")
@@ -1561,7 +1637,8 @@ const pnpm = {
 			order: 0,
 			content: [
 				"COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./",
-				"RUN pnpm install --frozen-lockfile --prod",
+				"# cache mounts keep the package store out of the image",
+				"RUN --mount=type=cache,id=pnpm-store,target=/root/.local/share/pnpm/store --mount=type=cache,id=pnpm-cache,target=/root/.cache/pnpm pnpm install --frozen-lockfile --prod",
 				"COPY --from=build /app/dist ./dist"
 			].join("\n")
 		},
@@ -1589,7 +1666,7 @@ const npm = {
 			slot: "docker-build",
 			content: [
 				"COPY package.json package-lock.json ./",
-				"RUN npm ci",
+				"RUN --mount=type=cache,target=/root/.npm npm ci",
 				"COPY . .",
 				"RUN npm run build"
 			].join("\n")
@@ -1600,7 +1677,7 @@ const npm = {
 			order: 0,
 			content: [
 				"COPY package.json package-lock.json ./",
-				"RUN npm ci --omit=dev",
+				"RUN --mount=type=cache,target=/root/.npm npm ci --omit=dev",
 				"COPY --from=build /app/dist ./dist"
 			].join("\n")
 		},
@@ -1632,7 +1709,7 @@ const bun = {
 			slot: "docker-build",
 			content: [
 				"COPY package.json bun.lock ./",
-				"RUN bun install --frozen-lockfile",
+				"RUN --mount=type=cache,target=/root/.bun/install/cache bun install --frozen-lockfile",
 				"COPY . .",
 				"RUN bun run build"
 			].join("\n")
@@ -1643,7 +1720,7 @@ const bun = {
 			order: 0,
 			content: [
 				"COPY package.json bun.lock ./",
-				"RUN bun install --frozen-lockfile --production",
+				"RUN --mount=type=cache,target=/root/.bun/install/cache bun install --frozen-lockfile --production",
 				"COPY --from=build /app/dist ./dist"
 			].join("\n")
 		},
@@ -2002,6 +2079,13 @@ function envModule(vars) {
 	return `import { createEnv } from "@t3-oss/env-core";
 import { z } from "zod";
 
+const production = process.env.NODE_ENV === "production";
+
+/** A default for local development; production must set the value explicitly. */
+function localDefault<T extends z.ZodType>(schema: T, value: z.input<T>): T {
+	return production ? schema : (schema.default(value as never) as unknown as T);
+}
+
 /** The only place that reads process.env. Add new variables here and to .env.example. */
 export const env = createEnv({
 	server: {
@@ -2370,6 +2454,13 @@ async function generate(project, request) {
 	}
 	const existing = [...rendered.keys()].filter((rel) => existsSync(join(project.root, rel)));
 	if (existing.length > 0) throw new GeneratorError(`Refusing to overwrite existing file(s):\n  ${existing.join("\n  ")}`);
+	const routeSources = /* @__PURE__ */ new Map();
+	for (const rel of await glob("src/**/routes/*.routes.ts", { cwd: project.root })) routeSources.set(rel, await readFile(join(project.root, rel), "utf8"));
+	const before = routeMountCollisions(routeSources).length;
+	for (const [rel, text] of rendered) routeSources.set(rel, text);
+	const after = routeMountCollisions(routeSources);
+	const collision = after.length > before ? after.at(-1) : void 0;
+	if (collision) throw new GeneratorError(`${collision.file}: ${collision.message}. Pick another --name, or create it and change basePath.`);
 	const files = [...rendered.keys()].sort();
 	if (request.dryRun) return {
 		kind: request.kind,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",

package/templates/features/authz/files/src/core/authz/constants.ts

@@ -15,9 +15,13 @@ export const AUDIT_CHANGE_TYPES = [
 	"member_role_revoked",
 	"overlay_granted",
 	"overlay_revoked",
+	"member_removed",
 ] as const;
 export type AuditChangeType = (typeof AUDIT_CHANGE_TYPES)[number];
 
+/** Audit actor for changes made by the system rather than a user (e.g. org membership hooks). */
+export const SYSTEM_ACTOR = "system";
+
 /** Org used when the principal has none (single-tenant apps, users without an active org). */
 export const DEFAULT_ORG_ID = "default";
 

package/templates/features/authz/files/src/core/authz/routes/authorization.routes.ts

@@ -19,7 +19,7 @@ import {
 	userParams,
 	userRoleParams,
 } from "#core/authz/validators";
-import { errorResponses, jsonContent, success, successSchema } from "#core/http/response";
+import { errorResponses, jsonBody, jsonContent, success, successSchema } from "#core/http/response";
 import { createRouter, defineRoutes } from "#core/http/routes";
 import { catalog } from "#generated/permissions";
 
@@ -100,7 +100,7 @@ router.openapi(
 		summary: "Create a custom role",
 		middleware: [requirePermission("role:create")] as const,
 		security: [{ bearerAuth: ["role:create"] }],
-		request: { body: jsonContent(createRoleSchema, "The role") },
+		request: { body: jsonBody(createRoleSchema, "The role") },
 		responses: {
 			201: jsonContent(successSchema(roleSchema), "Created"),
 			...errorResponses(400, 409),
@@ -122,7 +122,7 @@ router.openapi(
 		summary: "Update a custom role",
 		middleware: [requirePermission("role:update")] as const,
 		security: [{ bearerAuth: ["role:update"] }],
-		request: { params: idParams, body: jsonContent(updateRoleSchema, "Fields to change") },
+		request: { params: idParams, body: jsonBody(updateRoleSchema, "Fields to change") },
 		responses: {
 			200: jsonContent(successSchema(roleSchema), "Updated"),
 			...errorResponses(400, 404),
@@ -179,7 +179,7 @@ router.openapi(
 		summary: "Assign a role to a member",
 		middleware: [requirePermission("member:update")] as const,
 		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userParams, body: jsonContent(z.object({ roleId: z.string() }), "Role") },
+		request: { params: userParams, body: jsonBody(z.object({ roleId: z.string() }), "Role") },
 		responses: {
 			200: jsonContent(successSchema(z.object({ assigned: z.boolean() })), "Assigned"),
 			...errorResponses(404),
@@ -225,7 +225,7 @@ router.openapi(
 		summary: "Grant or deny one permission to a member",
 		middleware: [requirePermission("member:update")] as const,
 		security: [{ bearerAuth: ["member:update"] }],
-		request: { params: userParams, body: jsonContent(overlayInputSchema, "Overlay") },
+		request: { params: userParams, body: jsonBody(overlayInputSchema, "Overlay") },
 		responses: {
 			201: jsonContent(successSchema(z.object({ id: z.string() })), "Created"),
 			...errorResponses(400),

package/templates/features/authz/files/src/core/authz/services/members.ts

@@ -1,5 +1,5 @@
 import { invalidateMember } from "#core/authz/cache";
-import type { OverlayEffect, Scope } from "#core/authz/constants";
+import { type OverlayEffect, type Scope, SYSTEM_ACTOR } from "#core/authz/constants";
 import { store } from "#core/authz/db/store";
 import { audit } from "#core/authz/services/audit";
 import { validateGrants } from "#core/authz/services/grants";
@@ -31,6 +31,22 @@ export async function revokeRole(actorId: string, orgId: string, userId: string,
 	await audit({ orgId, actorId, targetUserId: userId, changeType: "member_role_revoked", before: { roleId } });
 }
 
+/** Removes all of a user's access in an org; called when they stop being a member. */
+export async function removeMemberAccess(orgId: string, userId: string, actorId = SYSTEM_ACTOR) {
+	const removed = await store.removeMember(orgId, userId);
+	invalidateMember(userId, orgId);
+	if (removed.roles + removed.overlays > 0) {
+		await audit({
+			orgId,
+			actorId,
+			targetUserId: userId,
+			changeType: "member_removed",
+			before: removed,
+		});
+	}
+	return removed;
+}
+
 export interface OverlayInput {
 	resource: string;
 	action: string;

package/templates/features/authz/files/src/core/authz/tests/error-messages.test.ts

@@ -0,0 +1,34 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { api } from "#tests/helpers/api";
+import { asUser, authenticate } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("error messages", () => {
+	it("keeps a specific message instead of the generic one for its code", async () => {
+		const headers = await asUser({ systemRoles: ["admin"] });
+		const role = await api.post<{ data: { id: string } }>(
+			"/api/authorization/roles",
+			{ key: "auditor", name: "Auditor", grants: [] },
+			{ headers },
+		);
+		const member = await authenticate();
+		await api.post(
+			`/api/authorization/members/${member.userId}/roles`,
+			{ roleId: role.body.data.id },
+			{ headers },
+		);
+		const res = await api.delete<{ code: string; error: string }>(
+			`/api/authorization/roles/${role.body.data.id}`,
+			{ headers },
+		);
+		expect(res.status).toBe(409);
+		expect(res.body).toMatchObject({
+			code: "CONFLICT",
+			error: 'Role "auditor" is assigned to 1 member(s)',
+		});
+	});
+});

package/templates/features/authz/files/src/core/authz/tests/request-body.test.ts

@@ -0,0 +1,27 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { app } from "#apps/api/app";
+import { asUser } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+// A body sent without Content-Type used to skip validation and reach services as {}
+describe("JSON request bodies", () => {
+	it("rejects a missing body with 400", async () => {
+		const headers = await asUser({ systemRoles: ["admin"] });
+		const res = await app.request("/api/authorization/roles", { method: "POST", headers });
+		expect(res.status).toBe(400);
+		expect(await res.json()).toMatchObject({ code: "VALIDATION_ERROR" });
+	});
+
+	it("does not assign a role from a missing body", async () => {
+		const headers = await asUser({ systemRoles: ["admin"] });
+		const res = await app.request("/api/authorization/members/someone/roles", {
+			method: "POST",
+			headers,
+		});
+		expect(res.status).toBe(400);
+	});
+});

package/templates/features/authz/files/src/core/authz/types.ts

@@ -77,6 +77,8 @@ export interface AuthzStore {
 	memberRoles(orgId: string, userId: string): Promise<RoleRow[]>;
 	assignRole(orgId: string, userId: string, roleId: string, by: string | null): Promise<boolean>;
 	revokeRole(orgId: string, userId: string, roleId: string): Promise<boolean>;
+	/** Deletes every role assignment and overlay the user has in the org. */
+	removeMember(orgId: string, userId: string): Promise<{ roles: number; overlays: number }>;
 	listOverlays(orgId: string, userId: string): Promise<OverlayRow[]>;
 	addOverlay(input: Omit<OverlayRow, "id" | "createdAt">): Promise<string>;
 	removeOverlay(orgId: string, userId: string, overlayId: string): Promise<OverlayRow | null>;

package/templates/features/authz/files+drizzle/src/core/authz/db/store.ts

@@ -194,6 +194,19 @@ export const store: AuthzStore = {
 		return true;
 	},
 
+	async removeMember(orgId, userId) {
+		const roleWhere = and(eq(authzMemberRoles.orgId, orgId), eq(authzMemberRoles.userId, userId));
+		const overlayWhere = and(eq(authzOverlays.orgId, orgId), eq(authzOverlays.userId, userId));
+		// count first: MySQL has no RETURNING
+		return db.transaction(async (tx) => {
+			const [roles] = await tx.select({ n: count() }).from(authzMemberRoles).where(roleWhere);
+			const [overlays] = await tx.select({ n: count() }).from(authzOverlays).where(overlayWhere);
+			await tx.delete(authzMemberRoles).where(roleWhere);
+			await tx.delete(authzOverlays).where(overlayWhere);
+			return { roles: roles?.n ?? 0, overlays: overlays?.n ?? 0 };
+		});
+	},
+
 	async listOverlays(orgId, userId) {
 		const rows = await db
 			.select()

package/templates/features/authz/files+prisma/src/core/authz/db/store.ts

@@ -168,6 +168,13 @@ export const store: AuthzStore = {
 		return count > 0;
 	},
 
+	async removeMember(orgId, userId) {
+		const [roles, overlays] = await db.$transaction([
+			db.authzMemberRole.deleteMany({ where: { orgId, userId } }),
+			db.authzOverlay.deleteMany({ where: { orgId, userId } }),
+		]);
+		return { roles: roles.count, overlays: overlays.count };
+	},
 	async listOverlays(orgId, userId) {
 		const rows = await db.authzOverlay.findMany({
 			where: { orgId, userId },

package/templates/features/base/files/AGENTS.md

@@ -45,6 +45,8 @@ __PM_EXEC__ tatara routes                # every route and what protects it
 ## HTTP
 
 - Every route uses `createRoute` from `@hono/zod-openapi`, with request and response schemas.
+  Declare request bodies with `jsonBody(schema, description)` (required; a missing body is a 400),
+  responses with `jsonContent(...)`.
   The spec is served at `/openapi.json`, the reference UI at `/docs`.
 - Responses use the envelope: `success(data)`, `paginated(items, page, pageSize, total)`.
   Errors are thrown as `AppError` subclasses (`NotFoundError`, `ConflictError`,

package/templates/features/base/files/Dockerfile

@@ -1,3 +1,4 @@
+# syntax=docker/dockerfile:1
 # One image for every entrypoint. Default: the API.
 # Other processes: override the command, e.g. `node dist/apps/worker/index.mjs`.
 FROM node:24-alpine AS base

package/templates/features/base/files/_github/workflows/ci.yml

@@ -5,6 +5,9 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 jobs:
   verify:
     runs-on: ubuntu-latest
@@ -14,3 +17,10 @@ jobs:
       - run: cp .env.example .env
       # tatara:slot ci-services
       - run: __PM_RUN__ verify
+
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # catch a broken Dockerfile on the PR, not at deploy
+      - run: docker build --tag app:ci .

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

@@ -9,7 +9,7 @@ export interface CommandDefinition<S extends z.ZodType = z.ZodType> {
 	/** `module:action`, e.g. "billing:recalculate" */
 	name: string;
 	description: string;
-	/** flags parsed from `--key value`; use z.coerce for numbers and booleans */
+	/** flags parsed from `--key value`; use z.coerce for numbers and `flag()` for booleans */
 	args?: S;
 	run(args: z.infer<S>, ctx: CommandContext): Promise<void> | void;
 }
@@ -23,3 +23,11 @@ export function defineCommand<S extends z.ZodType = typeof noArgs>(
 }
 
 export const noArgs = z.object({});
+
+/**
+ * A boolean flag: bare `--force` is true, `--force false|0|no|off` is false.
+ * (`z.coerce.boolean()` would read the string "false" as true.)
+ */
+export function flag() {
+	return z.union([z.boolean(), z.stringbool()]).default(false);
+}

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

@@ -43,7 +43,12 @@ export function createHttpApp(name: AppName, options: { title: string }) {
 		if (definition.app === name) app.route(`${API_PREFIX}${definition.basePath}`, definition.router);
 	}
 
-	app.doc31("/openapi.json", { openapi: "3.1.0", info: { title: options.title, version: "1.0.0" } });
+	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);

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())

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+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"),