@tatara/cli 0.1.0 → 0.1.2

package/package.json

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

package/templates/features/auth-keycloak/files/src/core/auth/keycloak-plugin.ts

@@ -0,0 +1,154 @@
+import type { BetterAuthPlugin } from "better-auth";
+import { createAuthEndpoint } from "better-auth/api";
+import { z } from "zod";
+import {
+	type KeycloakClaims,
+	organizationOf,
+	rolesOf,
+	verifyAccessToken,
+} from "#core/auth/keycloak";
+import { logger } from "#core/logging/logger";
+
+export interface KeycloakPrincipal {
+	userId: string;
+	orgId: string | null;
+	roles: string[];
+	kind: "user" | "service";
+	claims: KeycloakClaims;
+}
+
+export interface KeycloakTokensOptions {
+	/** Record the token's organization as a better-auth organization + membership. */
+	organizations?: boolean;
+}
+
+type Adapter = Parameters<NonNullable<BetterAuthPlugin["init"]>>[0]["adapter"];
+
+const ACCOUNT_PROVIDER = "keycloak";
+
+async function ensureUser(adapter: Adapter, claims: KeycloakClaims): Promise<boolean> {
+	// an unverified email could claim someone else's address, so it is never stored
+	const verified = claims.email_verified === true && Boolean(claims.email);
+	const email = verified
+		? (claims.email as string).toLowerCase()
+		: `${claims.sub}@users.keycloak.invalid`;
+	const name = claims.name ?? claims.preferred_username ?? claims.sub;
+	const owner = await adapter.findOne<{ id: string }>({
+		model: "user",
+		where: [{ field: "email", value: email }],
+	});
+	const existing = await adapter.findOne<{ id: string }>({
+		model: "user",
+		where: [{ field: "id", value: claims.sub }],
+	});
+	if (existing) {
+		const emailFree = !owner || owner.id === claims.sub;
+		if (!emailFree) logger.warn({ sub: claims.sub }, "keycloak email belongs to another account");
+		await adapter.update({
+			model: "user",
+			where: [{ field: "id", value: claims.sub }],
+			update: {
+				name,
+				...(emailFree ? { email, emailVerified: verified } : {}),
+				updatedAt: new Date(),
+			},
+		});
+		return true;
+	}
+	if (owner) {
+		// never attach a Keycloak identity to an account that signs in another way
+		logger.warn({ sub: claims.sub }, "keycloak token email belongs to another account");
+		return false;
+	}
+	const now = new Date();
+	await adapter.create({
+		model: "user",
+		data: { id: claims.sub, email, emailVerified: verified, name, createdAt: now, updatedAt: now },
+		forceAllowId: true,
+	});
+	await adapter.create({
+		model: "account",
+		data: {
+			userId: claims.sub,
+			accountId: claims.sub,
+			providerId: ACCOUNT_PROVIDER,
+			createdAt: now,
+			updatedAt: now,
+		},
+	});
+	return true;
+}
+
+async function ensureMembership(adapter: Adapter, orgId: string, userId: string): Promise<void> {
+	const org = await adapter.findOne({
+		model: "organization",
+		where: [{ field: "id", value: orgId }],
+	});
+	if (!org) {
+		await adapter.create({
+			model: "organization",
+			data: { id: orgId, name: orgId, slug: orgId, createdAt: new Date() },
+			forceAllowId: true,
+		});
+	}
+	const member = await adapter.findOne({
+		model: "member",
+		where: [
+			{ field: "organizationId", value: orgId },
+			{ field: "userId", value: userId },
+		],
+	});
+	if (!member) {
+		await adapter.create({
+			model: "member",
+			data: { organizationId: orgId, userId, role: "member", createdAt: new Date() },
+		});
+	}
+}
+
+/**
+ * Lets the API accept access tokens issued by Keycloak (a resource server).
+ * Verified tokens become principals; their users and organizations are kept in better-auth's tables.
+ */
+export function keycloakTokens(options: KeycloakTokensOptions = {}) {
+	// subjects already synced by this process; tokens are re-verified on every request regardless
+	const synced = new Set<string>();
+	return {
+		id: "keycloak-tokens",
+		endpoints: {
+			// no path: callable only on the server as auth.api.verifyKeycloakToken
+			verifyKeycloakToken: createAuthEndpoint(
+				{ method: "POST", body: z.object({ token: z.string() }) },
+				async (ctx): Promise<KeycloakPrincipal | null> => {
+					let claims: KeycloakClaims;
+					try {
+						claims = await verifyAccessToken(ctx.body.token);
+					} catch (error) {
+						logger.debug({ err: error }, "rejected keycloak token");
+						return null;
+					}
+					const isService = claims.preferred_username?.startsWith("service-account-") ?? false;
+					const orgId = organizationOf(claims);
+					if (!isService) {
+						const key = `${claims.sub}|${orgId ?? ""}|${claims.email ?? ""}`;
+						if (!synced.has(key)) {
+							const { adapter } = ctx.context;
+							if (!(await ensureUser(adapter, claims))) return null;
+							if (orgId && options.organizations)
+								await ensureMembership(adapter, orgId, claims.sub);
+							if (synced.size > 10_000) synced.clear();
+							synced.add(key);
+						}
+					}
+					return {
+						userId: claims.sub,
+						orgId,
+						roles: rolesOf(claims),
+						kind: isService ? "service" : "user",
+						claims,
+					};
+				},
+			),
+		},
+	} satisfies BetterAuthPlugin;
+}

package/templates/features/auth-keycloak/files/src/core/auth/tests/keycloak-tokens.test.ts

@@ -0,0 +1,109 @@
+import { generateKeyPair, SignJWT } from "jose";
+import { beforeEach, describe, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { issuer } from "#core/auth/keycloak";
+import { env } from "#core/config/env";
+import { newId } from "#core/db/id";
+import { api } from "#tests/helpers/api";
+import { createTestUser, keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+interface Me {
+	data: { userId: string; orgId: string | null; roles: string[]; kind: string };
+}
+
+const bearer = (token: string) => ({ authorization: `Bearer ${token}` });
+const me = (token: string) => api.get<Me>("/api/me", { headers: bearer(token) });
+
+// read through better-auth's adapter so the tests work with any ORM
+async function find<T>(model: string, where: Record<string, string>): Promise<T | null> {
+	const { adapter } = await auth.$context;
+	return adapter.findOne<T>({
+		model,
+		where: Object.entries(where).map(([field, value]) => ({ field, value })),
+	});
+}
+type UserRow = { email: string; emailVerified: boolean };
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens", () => {
+	it("authenticates a valid token as the token's subject", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, roles: ["teacher"] }));
+		expect(res.status).toBe(200);
+		expect(res.body.data).toMatchObject({ userId: sub, kind: "user", orgId: null });
+		expect(res.body.data.roles).toContain("teacher");
+	});
+
+	it("creates the local user and links a keycloak account on first use", async () => {
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "kc@example.com" }));
+		const user = await find<UserRow>("user", { id: sub });
+		expect(user?.email).toBe("kc@example.com");
+		const account = await find<{ accountId: string }>("account", {
+			userId: sub,
+			providerId: "keycloak",
+		});
+		expect(account?.accountId).toBe(sub);
+	});
+
+	it.each([
+		["an expired token", { expiresIn: Math.floor(Date.now() / 1000) - 60 }],
+		["a token from another issuer", { issuer: "https://evil.example.com/realms/app" }],
+		["a token for another audience", { audience: "someone-else" }],
+	])("rejects %s", async (_label, options) => {
+		expect((await me(await keycloakToken(options))).status).toBe(401);
+	});
+
+	it("rejects a token signed with an unknown key", async () => {
+		const { privateKey } = await generateKeyPair("RS256");
+		const forged = await new SignJWT({ roles: ["admin"] })
+			.setProtectedHeader({ alg: "RS256", kid: "test" })
+			.setSubject(newId())
+			.setIssuer(issuer)
+			.setAudience(env.KEYCLOAK_AUDIENCE)
+			.setExpirationTime("5m")
+			.sign(privateKey);
+		expect((await me(forged)).status).toBe(401);
+	});
+
+	it("rejects a bearer value that is not a token", async () => {
+		expect((await me("not-a-token")).status).toBe(401);
+	});
+
+	it("treats service-account tokens as services without a user row", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, username: "service-account-billing" }));
+		expect(res.body.data).toMatchObject({ userId: sub, kind: "service" });
+		expect(await find<UserRow>("user", { id: sub })).toBeNull();
+	});
+
+
+	it("rejects a token whose email belongs to another account", async () => {
+		await createTestUser({ email: "taken@example.com" });
+		const sub = newId();
+		expect((await me(await keycloakToken({ sub, email: "taken@example.com" }))).status).toBe(401);
+		expect(await find<UserRow>("user", { id: sub })).toBeNull();
+	});
+
+
+	it("does not store an email Keycloak has not verified", async () => {
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "victim@example.com", emailVerified: false }));
+		const user = await find<UserRow>("user", { id: sub });
+		expect(user?.email).not.toBe("victim@example.com");
+		expect(user?.emailVerified).toBe(false);
+	});
+
+	it("keeps the old email when the token's new email belongs to another account", async () => {
+		await createTestUser({ email: "taken@example.com" });
+		const sub = newId();
+		await me(await keycloakToken({ sub, email: "first@example.com" }));
+		const res = await me(await keycloakToken({ sub, email: "taken@example.com" }));
+		expect(res.status).toBe(200);
+		expect((await find<UserRow>("user", { id: sub }))?.email).toBe("first@example.com");
+	});
+});

package/templates/features/auth-keycloak/files+auth-orgs/src/core/auth/tests/keycloak-organizations.test.ts

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { auth } from "#core/auth/auth";
+import { newId } from "#core/db/id";
+import { api } from "#tests/helpers/api";
+import { keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+interface Me {
+	data: { orgId: string | null };
+}
+
+const me = (token: string) =>
+	api.get<Me>("/api/me", { headers: { authorization: `Bearer ${token}` } });
+
+// read through better-auth's adapter so the tests work with any ORM
+async function find<T>(model: string, where: Record<string, string>): Promise<T | null> {
+	const { adapter } = await auth.$context;
+	return adapter.findOne<T>({
+		model,
+		where: Object.entries(where).map(([field, value]) => ({ field, value })),
+	});
+}
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens with organizations", () => {
+	it("takes the organization from the token and records the membership", async () => {
+		const sub = newId();
+		const res = await me(await keycloakToken({ sub, organization: ["riyadh-school"] }));
+		expect(res.body.data.orgId).toBe("riyadh-school");
+		expect(await find("organization", { id: "riyadh-school" })).not.toBeNull();
+		expect(await find("member", { organizationId: "riyadh-school", userId: sub })).not.toBeNull();
+	});
+});

package/templates/features/auth-keycloak/files+authz/src/core/auth/tests/keycloak-authz.test.ts

@@ -0,0 +1,23 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { syncSystemRoles } from "#core/authz/services/sync";
+import { api } from "#tests/helpers/api";
+import { keycloakToken } from "#tests/helpers/auth";
+import { resetDatabase } from "#tests/helpers/db";
+
+const bearer = (token: string) => ({ authorization: `Bearer ${token}` });
+
+beforeEach(async () => {
+	await resetDatabase();
+});
+
+describe("Keycloak access tokens with authz", () => {
+	it("lets token roles match built-in authz roles", async () => {
+		await syncSystemRoles();
+		const admin = await keycloakToken({ roles: ["admin"] });
+		const user = await keycloakToken({ roles: ["user"] });
+		expect((await api.get("/api/authorization/roles", { headers: bearer(admin) })).status).toBe(
+			200,
+		);
+		expect((await api.get("/api/authorization/roles", { headers: bearer(user) })).status).toBe(403);
+	});
+});

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