@tatara/cli 0.1.0 → 0.1.2

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. */
@@ -496,7 +527,7 @@ async function dev(project, flags = {}) {
 	if (project.has("admin")) urls.push(`Admin API   http://localhost:${env.ADMIN_PORT ?? "3001"}/docs`);
 	if (project.has("email")) urls.push(`Mailpit     http://localhost:${env.MAILPIT_UI_PORT ?? "8025"}`);
 	if (project.has("storage")) urls.push(`Storage UI  http://localhost:${env.STORAGE_CONSOLE_PORT ?? "9001"}`);
-	if (project.has("keycloak")) urls.push(`Keycloak    http://localhost:${env.KEYCLOAK_PORT ?? "8080"}/admin (admin/admin)`);
+	if (project.has("auth-keycloak")) urls.push(`Keycloak    http://localhost:${env.KEYCLOAK_PORT ?? "8080"}/admin (admin/admin)`);
 	console.log(`\n${urls.map((u) => `  ${pc.green("➜")} ${u}`).join("\n")}\n`);
 	return new Promise((resolve) => {
 		const stop = () => {
@@ -522,7 +553,7 @@ const PACKAGES = {
 	drizzle: ["drizzle-orm", "drizzle-kit"],
 	prisma: ["@prisma/client", "prisma"],
 	"better-auth": ["better-auth"],
-	keycloak: ["jose"],
+	"auth-keycloak": ["jose"],
 	jobs: ["bullmq", "ioredis"]
 };
 async function doctor(project) {
@@ -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,70 +1447,66 @@ 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 = {
-	id: "keycloak",
-	kind: "auth",
-	label: "Keycloak",
+const KEYCLOAK_AGENTS = `### Keycloak
+
+- The API also accepts Keycloak access tokens (\`Authorization: Bearer <token>\`). The
+  \`keycloakTokens()\` better-auth plugin (\`src/core/auth/keycloak-plugin.ts\`) verifies signature,
+  issuer, audience \`__APP_NAME__-api\` and expiry; login happens in the frontend via OIDC (PKCE)
+  against the \`__APP_NAME__-web\` client.
+- The token's subject is the user id. The user (and a \`keycloak\` account) is created in
+  better-auth's tables on first use; a token whose email already belongs to another account is
+  rejected. Service-account tokens become \`kind: "service"\` principals with no user row.
+- Roles come from the token (realm roles, \`roles\`, and client roles for the API); a role named like
+  a built-in authz role grants it. The organization comes from the \`organization\` claim.
+- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
+  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
+- Tests sign tokens with a local key: \`keycloakToken()\` from \`#tests/helpers/auth\`.
+`;
+const KEYCLOAK_TEST_HELPER = [
+	"const { publicKey, privateKey } = await generateKeyPair(\"RS256\");",
+	"setKeySource(async (header) => {",
+	"	if (header.kid !== \"test\") throw new Error(\"unknown key\");",
+	"	return publicKey;",
+	"});",
+	"",
+	"export interface KeycloakTokenOptions {",
+	"	sub?: string;",
+	"	email?: string;",
+	"	emailVerified?: boolean;",
+	"	roles?: string[];",
+	"	organization?: string[] | Record<string, unknown>;",
+	"	username?: string;",
+	"	issuer?: string;",
+	"	audience?: string;",
+	"	expiresIn?: string | number;",
+	"}",
+	"",
+	"/** Signs an access token the API accepts, as if Keycloak issued it. */",
+	"export async function keycloakToken(options: KeycloakTokenOptions = {}): Promise<string> {",
+	"	const sub = options.sub ?? newId();",
+	"	return new SignJWT({",
+	"		email: options.email ?? `user-${sub}@example.com`,",
+	"		email_verified: options.emailVerified ?? true,",
+	"		preferred_username: options.username ?? `user-${sub.slice(0, 8)}`,",
+	"		roles: options.roles ?? [\"user\"],",
+	"		...(options.organization ? { organization: options.organization } : {}),",
+	"	})",
+	"		.setProtectedHeader({ alg: \"RS256\", kid: \"test\" })",
+	"		.setSubject(sub)",
+	"		.setIssuer(options.issuer ?? issuer)",
+	"		.setAudience(options.audience ?? env.KEYCLOAK_AUDIENCE)",
+	"		.setIssuedAt()",
+	"		.setExpirationTime(options.expiresIn ?? \"5m\")",
+	"		.sign(privateKey);",
+	"}"
+].join("\n");
+const authKeycloak = {
+	id: "auth-keycloak",
+	kind: "auth-method",
+	label: "Keycloak tokens",
 	dependencies: ["jose"],
 	env: [
 		{
@@ -1389,7 +1518,7 @@ const keycloak = {
 		},
 		{
 			key: "KEYCLOAK_URL",
-			schema: "z.url().default(\"http://localhost:8080\")",
+			schema: "localDefault(z.url(), \"http://localhost:8080\")",
 			example: "http://localhost:8080"
 		},
 		{
@@ -1425,30 +1554,72 @@ const keycloak = {
 	} },
 	slots: [
 		{
-			file: "src/core/auth/users.ts",
-			slot: "upsert",
-			when: ["drizzle", "postgres"],
-			content: "await db\n	.insert(users)\n	.values(values)\n	.onConflictDoUpdate({ target: users.id, set: { email: values.email, name: values.name, updatedAt: new Date() } });"
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { keycloakTokens } from \"#core/auth/keycloak-plugin\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "plugins",
+			unless: ["auth-orgs"],
+			content: "keycloakTokens(),",
+			order: 800
 		},
 		{
-			file: "src/core/auth/users.ts",
-			slot: "upsert",
-			when: ["drizzle", "mysql"],
-			content: "await db\n	.insert(users)\n	.values(values)\n	.onDuplicateKeyUpdate({ set: { email: values.email, name: values.name } });"
+			file: "src/core/auth/auth.ts",
+			slot: "plugins",
+			when: ["auth-orgs"],
+			content: "keycloakTokens({ organizations: true }),",
+			order: 800
+		},
+		{
+			file: "src/core/auth/principal.ts",
+			slot: "no-session",
+			content: [
+				"if (!session) {",
+				"	const header = c.req.header(\"authorization\");",
+				"	const token = header?.startsWith(\"Bearer \") ? header.slice(7) : undefined;",
+				"	const principal = token ? await auth.api.verifyKeycloakToken({ body: { token } }) : null;",
+				"	if (principal) c.set(\"principal\", principal);",
+				"}"
+			].join("\n")
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { generateKeyPair, SignJWT } from \"jose\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { issuer, setKeySource } from \"#core/auth/keycloak\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "imports",
+			content: "import { env } from \"#core/config/env\";"
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "helpers",
+			content: KEYCLOAK_TEST_HELPER
+		},
+		{
+			file: "tests/helpers/auth.ts",
+			slot: "authenticate",
+			unless: ["auth-orgs"],
+			content: [
+				"if (options.roles) {",
+				"	const sub = newId();",
+				"	const token = await keycloakToken({ sub, roles: options.roles, email: options.email });",
+				"	return { userId: sub, headers: { authorization: `Bearer ${token}` } };",
+				"}"
+			].join("\n")
 		},
 		{
 			file: "AGENTS.md",
 			slot: "sections",
-			content: `### Keycloak
-
-- The API is a resource server: it verifies Keycloak access tokens (signature, issuer,
-  audience \`__APP_NAME__-api\`, expiry). Login happens in the frontend via OIDC (PKCE) against
-  the \`__APP_NAME__-web\` client.
-- Roles come from the token's \`roles\` claim (realm roles) and client roles for the API.
-- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
-  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
-- Tests sign tokens with a local key; see \`#tests/helpers/auth\`.
-`
+			content: KEYCLOAK_AGENTS
 		}
 	]
 };
@@ -1509,13 +1680,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 +1721,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 +1732,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 +1761,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 +1772,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 +1804,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 +1815,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")
 		},
@@ -1837,7 +2009,7 @@ const FEATURES = Object.fromEntries([
 	authPhoneOtp,
 	authPassword,
 	authOrgs,
-	keycloak,
+	authKeycloak,
 	auth,
 	authz,
 	jobs,
@@ -1861,12 +2033,12 @@ function validateOptions(input) {
 	const hasDb = options.database !== "none";
 	if (options.auth !== "none" && !hasDb) throw new OptionsError(`Auth (${options.auth}) needs a database.`);
 	if (options.auth === "better-auth") {
-		if (options.authMethods.filter((m) => m !== "orgs").length === 0) throw new OptionsError("better-auth needs at least one sign-in method: email-otp, phone-otp or password.");
+		if (options.authMethods.filter((m) => m !== "orgs").length === 0) throw new OptionsError("better-auth needs at least one sign-in method: email-otp, phone-otp, password or keycloak.");
 	} else if (options.authMethods.length > 0) throw new OptionsError("Auth methods only apply to better-auth.");
 	for (const addon of options.addons) {
 		if ((addon === "authz" || addon === "admin") && options.auth === "none") throw new OptionsError(`The ${addon} add-on needs an auth provider.`);
 		if (addon === "authz" && !hasDb) throw new OptionsError("The authz add-on needs a database.");
-		if (addon === "admin" && options.auth === "better-auth" && !options.authMethods.includes("orgs")) throw new OptionsError("The admin add-on with better-auth needs the \"orgs\" method (it provides user roles).");
+		if (addon === "admin" && options.auth === "better-auth" && !options.authMethods.includes("orgs") && !options.authMethods.includes("keycloak")) throw new OptionsError("The admin add-on with better-auth needs the \"orgs\" or \"keycloak\" method (they provide user roles).");
 	}
 	return options;
 }
@@ -2002,6 +2174,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 +2549,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,
@@ -2459,17 +2645,25 @@ const DATABASES = [
 	"mysql",
 	"none"
 ];
-const AUTHS = [
-	"better-auth",
-	"keycloak",
-	"none"
-];
+const AUTHS = ["better-auth", "none"];
 const METHODS = [
 	"email-otp",
 	"phone-otp",
 	"password",
+	"keycloak",
 	"orgs"
 ];
+/** `--auth keycloak` (before 0.1.2) is better-auth with the keycloak method. */
+function normalizeAuthFlags(flags) {
+	if (flags.auth !== "keycloak") return flags;
+	const methods = new Set((flags.authMethods ?? "").split(",").filter(Boolean));
+	methods.add("keycloak");
+	return {
+		...flags,
+		auth: "better-auth",
+		authMethods: [...methods].join(",")
+	};
+}
 const ADDONS = [
 	"authz",
 	"jobs",
@@ -2537,22 +2731,14 @@ async function prompt(name, flags) {
 	let auth = "none";
 	if (database !== "none") auth = flags.auth ? oneOf(flags.auth, AUTHS, "auth") : answer(await p.select({
 		message: "Auth",
-		options: [
-			{
-				value: "better-auth",
-				label: "better-auth",
-				hint: "sign-in handled by the API"
-			},
-			{
-				value: "keycloak",
-				label: "Keycloak",
-				hint: "API verifies Keycloak tokens"
-			},
-			{
-				value: "none",
-				label: "None"
-			}
-		]
+		options: [{
+			value: "better-auth",
+			label: "better-auth",
+			hint: "sign-in handled by the API"
+		}, {
+			value: "none",
+			label: "None"
+		}]
 	}));
 	let authMethods = [];
 	if (auth === "better-auth") authMethods = flags.authMethods ? listOf(flags.authMethods, METHODS, "auth-methods") : answer(await p.multiselect({
@@ -2571,6 +2757,11 @@ async function prompt(name, flags) {
 				value: "password",
 				label: "Email + password"
 			},
+			{
+				value: "keycloak",
+				label: "Keycloak tokens",
+				hint: "API accepts Keycloak access tokens"
+			},
 			{
 				value: "orgs",
 				label: "Organizations + roles",
@@ -2645,7 +2836,8 @@ async function run(cmd, args, cwd, label) {
 	}
 	spinner?.stop(label);
 }
-async function newApp(dir, flags) {
+async function newApp(dir, rawFlags) {
+	const flags = normalizeAuthFlags(rawFlags);
 	const interactive = !flags.yes && process.stdout.isTTY;
 	if (interactive) p.intro(pc.bold("tatara"));
 	let target = dir;
@@ -2826,7 +3018,7 @@ server.on("exit", () => process.exit(0));
 //#endregion
 //#region src/bin.ts
 const program = new Command("tatara").description("Create and grow opinionated Hono backends").version(cliVersion());
-program.command("new").description("Create a new app").argument("[dir]", "directory to create").option("--orm <orm>", "drizzle | prisma | none").option("--db <database>", "postgres | mysql | none").option("--auth <provider>", "better-auth | keycloak | none").option("--auth-methods <list>", "email-otp,phone-otp,password,orgs (better-auth)").option("--addons <list>", "authz,jobs,admin,storage,email,i18n").option("--pm <pm>", "pnpm | npm | bun").option("-y, --yes", "skip prompts and use flags/defaults").option("--no-install", "do not install dependencies").option("--no-git", "do not initialise git").action(async (dir, flags) => {
+program.command("new").description("Create a new app").argument("[dir]", "directory to create").option("--orm <orm>", "drizzle | prisma | none").option("--db <database>", "postgres | mysql | none").option("--auth <provider>", "better-auth | none (keycloak = better-auth with --auth-methods keycloak)").option("--auth-methods <list>", "email-otp,phone-otp,password,orgs (better-auth)").option("--addons <list>", "authz,jobs,admin,storage,email,i18n").option("--pm <pm>", "pnpm | npm | bun").option("-y, --yes", "skip prompts and use flags/defaults").option("--no-install", "do not install dependencies").option("--no-git", "do not initialise git").action(async (dir, flags) => {
 	await newApp(dir, flags);
 });
 program.command("sync").description("Regenerate src/generated from discovered module files").option("--quiet", "no output").action(async (flags) => {