@tatara/cli 0.0.0-stage → 0.1.1

package/templates/features/jobs/files/src/core/jobs/define.ts

@@ -0,0 +1,37 @@
+import type { z } from "zod";
+import type { Logger } from "#core/logging/logger";
+
+export interface JobContext {
+	logger: Logger;
+	jobId: string;
+	attempt: number;
+}
+
+export interface ConsumerDefinition<S extends z.ZodType = z.ZodType> {
+	/** job name, e.g. "billing.invoice-paid" */
+	topic: string;
+	description: string;
+	schema: S;
+	/** retries before the job is marked failed (default 3) */
+	attempts?: number;
+	handle(data: z.infer<S>, ctx: JobContext): Promise<void>;
+}
+
+/** Default export of every `consumers/*.ts`; run by the worker app. */
+export function defineConsumer<S extends z.ZodType>(definition: ConsumerDefinition<S>) {
+	return definition;
+}
+
+export interface ScheduleDefinition {
+	name: string;
+	/** cron expression (seconds optional), evaluated in UTC */
+	cron: string;
+	/** how long the run holds its lock; one run per tick across all cron processes */
+	lockTtlMs?: number;
+	run(ctx: { logger: Logger }): Promise<void>;
+}
+
+/** Default export of every `schedules/*.ts`; run by the cron app. */
+export function defineSchedule(definition: ScheduleDefinition): ScheduleDefinition {
+	return definition;
+}

package/templates/features/jobs/files/src/core/jobs/lock.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+import { redis } from "#core/jobs/redis";
+
+const RELEASE = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
+
+/** Runs `fn` only if this process wins the lock; returns false when another holder has it. */
+export async function withLock(key: string, ttlMs: number, fn: () => Promise<void>): Promise<boolean> {
+	const token = randomUUID();
+	const acquired = await redis().set(`lock:${key}`, token, "PX", ttlMs, "NX");
+	if (acquired !== "OK") return false;
+	try {
+		await fn();
+	} finally {
+		await redis().eval(RELEASE, 1, `lock:${key}`, token);
+	}
+	return true;
+}

package/templates/features/jobs/files/src/core/jobs/process.ts

@@ -0,0 +1,19 @@
+import type { ConsumerDefinition, JobContext } from "#core/jobs/define";
+
+export class UnknownTopicError extends Error {}
+
+/** Validates and runs one job; shared by the worker and by tests. */
+export async function processJob(
+	consumers: ConsumerDefinition[],
+	topic: string,
+	data: unknown,
+	ctx: JobContext,
+): Promise<void> {
+	const consumer = consumers.find((c) => c.topic === topic);
+	if (!consumer) throw new UnknownTopicError(`No consumer for topic "${topic}"`);
+	const parsed = consumer.schema.safeParse(data);
+	if (!parsed.success) {
+		throw new Error(`Invalid payload for ${topic}: ${parsed.error.message}`);
+	}
+	await consumer.handle(parsed.data, ctx);
+}

package/templates/features/jobs/files/src/core/jobs/queue.ts

@@ -0,0 +1,29 @@
+import { type JobsOptions, Queue } from "bullmq";
+import { env } from "#core/config/env";
+import { redis } from "#core/jobs/redis";
+import { onShutdown } from "#core/process/lifecycle";
+
+export const QUEUE_NAME = "__APP_NAME__-jobs";
+
+let queue: Queue | undefined;
+
+function getQueue(): Queue {
+	if (!queue) {
+		const q = new Queue(QUEUE_NAME, { connection: redis(), prefix: env.JOBS_PREFIX });
+		queue = q;
+		onShutdown("queue", () => q.close());
+	}
+	return queue;
+}
+
+/** Enqueues a job for the consumer with this topic. The consumer validates the payload. */
+export async function enqueue(topic: string, data: unknown, options: JobsOptions = {}): Promise<string> {
+	const job = await getQueue().add(topic, data, {
+		attempts: 3,
+		backoff: { type: "exponential", delay: 1000 },
+		removeOnComplete: 1000,
+		removeOnFail: 5000,
+		...options,
+	});
+	return job.id ?? "";
+}

package/templates/features/jobs/files/src/core/jobs/redis.ts

@@ -0,0 +1,17 @@
+import { Redis } from "ioredis";
+import { env } from "#core/config/env";
+import { onShutdown } from "#core/process/lifecycle";
+
+let client: Redis | undefined;
+
+/** Shared connection (BullMQ requires maxRetriesPerRequest: null). */
+export function redis(): Redis {
+	if (!client) {
+		const connection = new Redis(env.REDIS_URL, { maxRetriesPerRequest: null });
+		client = connection;
+		onShutdown("redis", async () => {
+			await connection.quit();
+		});
+	}
+	return client;
+}

package/templates/features/jobs/files/src/modules/example/consumers/send-welcome.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineConsumer } from "#core/jobs/define";
+
+export default defineConsumer({
+	topic: "example.send-welcome",
+	description: "Example consumer: greets a new user",
+	schema: z.object({ name: z.string().min(1) }),
+	async handle({ name }, { logger }) {
+		logger.info({ name }, "welcome sent");
+	},
+});

package/templates/features/jobs/files/src/modules/example/schedules/heartbeat.ts

@@ -0,0 +1,9 @@
+import { defineSchedule } from "#core/jobs/define";
+
+export default defineSchedule({
+	name: "example.heartbeat",
+	cron: "*/5 * * * *",
+	async run({ logger }) {
+		logger.info("heartbeat");
+	},
+});

package/templates/features/jobs/files/src/modules/example/tests/jobs.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { withLock } from "#core/jobs/lock";
+import { processJob } from "#core/jobs/process";
+import { logger } from "#core/logging/logger";
+import { consumers } from "#generated/consumers";
+
+const ctx = { logger, jobId: "test", attempt: 1 };
+
+describe("jobs", () => {
+	it("runs the consumer for a topic with a valid payload", async () => {
+		await expect(processJob(consumers, "example.send-welcome", { name: "Ada" }, ctx)).resolves.toBeUndefined();
+	});
+
+	it("rejects an invalid payload", async () => {
+		await expect(processJob(consumers, "example.send-welcome", { name: "" }, ctx)).rejects.toThrow(
+			/Invalid payload/,
+		);
+	});
+
+	it("lets only one holder run a locked section", async () => {
+		const key = `test-${Date.now()}-${Math.random()}`;
+		let inner: boolean | undefined;
+		const outer = await withLock(key, 5000, async () => {
+			inner = await withLock(key, 5000, async () => {});
+		});
+		expect(outer).toBe(true);
+		expect(inner).toBe(false);
+	});
+});

package/templates/features/keycloak/files/keycloak/realm.json

@@ -0,0 +1,83 @@
+{
+	"realm": "__APP_NAME__",
+	"enabled": true,
+	"displayName": "__APP_NAME__ (development)",
+	"sslRequired": "none",
+	"accessTokenLifespan": 900,
+	"registrationAllowed": false,
+	"roles": {
+		"realm": [
+			{ "name": "user", "description": "Signed-in user" },
+			{ "name": "admin", "description": "Administrator" }
+		]
+	},
+	"clients": [
+		{
+			"clientId": "__APP_NAME__-api",
+			"name": "__APP_NAME__ API (token audience)",
+			"enabled": true,
+			"publicClient": false,
+			"bearerOnly": true,
+			"standardFlowEnabled": false,
+			"directAccessGrantsEnabled": false
+		},
+		{
+			"clientId": "__APP_NAME__-web",
+			"name": "__APP_NAME__ web (public, PKCE)",
+			"enabled": true,
+			"publicClient": true,
+			"standardFlowEnabled": true,
+			"directAccessGrantsEnabled": true,
+			"redirectUris": ["http://localhost:5173/*", "http://localhost:3000/*"],
+			"webOrigins": ["+"],
+			"attributes": { "pkce.code.challenge.method": "S256", "post.logout.redirect.uris": "+" },
+			"protocolMappers": [
+				{
+					"name": "api-audience",
+					"protocol": "openid-connect",
+					"protocolMapper": "oidc-audience-mapper",
+					"config": {
+						"included.client.audience": "__APP_NAME__-api",
+						"access.token.claim": "true",
+						"id.token.claim": "false"
+					}
+				},
+				{
+					"name": "realm-roles",
+					"protocol": "openid-connect",
+					"protocolMapper": "oidc-usermodel-realm-role-mapper",
+					"config": {
+						"claim.name": "roles",
+						"multivalued": "true",
+						"jsonType.label": "String",
+						"access.token.claim": "true",
+						"id.token.claim": "false",
+						"userinfo.token.claim": "false"
+					}
+				}
+			]
+		}
+	],
+	"users": [
+		{
+			"username": "alice",
+			"email": "alice@example.com",
+			"emailVerified": true,
+			"firstName": "Alice",
+			"lastName": "Admin",
+			"enabled": true,
+			"credentials": [{ "type": "password", "value": "alice", "temporary": false }],
+			"realmRoles": ["user", "admin"]
+		},
+		{
+			"username": "bob",
+			"email": "bob@example.com",
+			"emailVerified": true,
+			"firstName": "Bob",
+			"lastName": "User",
+			"enabled": true,
+			"credentials": [{ "type": "password", "value": "bob", "temporary": false }],
+			"realmRoles": ["user"]
+		}
+	]
+}

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

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { issuer } from "#core/auth/keycloak";
+import { defineCommand } from "#core/commands/define";
+import { env } from "#core/config/env";
+
+export default defineCommand({
+	name: "keycloak:token",
+	description: "Print an access token for a dev-realm user (development only)",
+	args: z.object({
+		user: z.string().default("alice"),
+		password: z.string().optional(),
+		client: z.string().default("__APP_NAME__-web"),
+	}),
+	async run({ user, password, client }) {
+		if (env.NODE_ENV === "production") throw new Error("keycloak:token is for development only");
+		const res = await fetch(`${issuer}/protocol/openid-connect/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({
+				grant_type: "password",
+				client_id: client,
+				username: user,
+				password: password ?? user,
+			}),
+		});
+		const body = (await res.json()) as { access_token?: string; error_description?: string };
+		if (!res.ok || !body.access_token) {
+			throw new Error(`Keycloak refused: ${body.error_description ?? res.statusText}`);
+		}
+		console.log(body.access_token);
+	},
+});

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

@@ -0,0 +1,58 @@
+import { createRemoteJWKSet, type JWTPayload, type JWTVerifyGetKey, jwtVerify } from "jose";
+import { env } from "#core/config/env";
+
+export const issuer = `${env.KEYCLOAK_URL.replace(/\/$/, "")}/realms/${env.KEYCLOAK_REALM}`;
+
+let keySource: JWTVerifyGetKey = createRemoteJWKSet(
+	new URL(`${issuer}/protocol/openid-connect/certs`),
+);
+
+/** Tests replace the realm's key set with a local one. */
+export function setKeySource(source: JWTVerifyGetKey): void {
+	keySource = source;
+}
+
+export interface KeycloakClaims extends JWTPayload {
+	sub: string;
+	email?: string;
+	name?: string;
+	preferred_username?: string;
+	azp?: string;
+	roles?: string[];
+	realm_access?: { roles?: string[] };
+	resource_access?: Record<string, { roles?: string[] }>;
+	organization?: string[] | Record<string, unknown>;
+}
+
+/** Verifies signature, issuer, audience and expiry. Throws when the token is not valid. */
+export async function verifyAccessToken(token: string): Promise<KeycloakClaims> {
+	const { payload } = await jwtVerify(token, keySource, {
+		issuer,
+		audience: env.KEYCLOAK_AUDIENCE,
+	});
+	if (typeof payload.sub !== "string") throw new Error("token has no subject");
+	return payload as KeycloakClaims;
+}
+
+export function rolesOf(claims: KeycloakClaims): string[] {
+	const roles = new Set<string>([
+		...(claims.roles ?? []),
+		...(claims.realm_access?.roles ?? []),
+		...(claims.resource_access?.[env.KEYCLOAK_AUDIENCE]?.roles ?? []),
+	]);
+	return [...roles];
+}
+
+/** Keycloak organizations put memberships in the `organization` claim; the first one wins. */
+export function organizationOf(claims: KeycloakClaims): string | null {
+	const org = claims.organization;
+	if (Array.isArray(org)) return org[0] ?? null;
+	if (org && typeof org === "object") {
+		const [first] = Object.entries(org);
+		if (!first) return null;
+		const [alias, value] = first;
+		const id = (value as { id?: unknown } | undefined)?.id;
+		return typeof id === "string" ? id : alias;
+	}
+	return null;
+}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/templates/features/prisma/files/prisma.config.ts

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { defineConfig } from "prisma/config";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+
+export default defineConfig({
+	schema: "prisma",
+	migrations: { path: "prisma/migrations" },
+	datasource: { url: process.env.DATABASE_URL ?? "" },
+});

package/templates/features/prisma/files/src/core/db/migrate.ts

@@ -0,0 +1,13 @@
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+/** Applies prisma/migrations to the database at `url` (`prisma migrate deploy`). */
+export async function migrateDatabase(url: string): Promise<void> {
+	await run(resolve("node_modules/.bin/prisma"), ["migrate", "deploy"], {
+		// tatara-check-ignore env-access: the Prisma CLI needs the full environment
+		env: { ...process.env, DATABASE_URL: url },
+	});
+}

package/templates/features/prisma/files+mysql/prisma/schema.prisma

@@ -0,0 +1,11 @@
+// Models live in prisma/models/*.prisma (one file per table).
+generator client {
+  provider            = "prisma-client"
+  output              = "../src/generated/prisma"
+  importFileExtension = "ts"
+  moduleFormat        = "esm"
+}
+
+datasource db {
+  provider = "mysql"
+}

package/templates/features/prisma/files+mysql/src/core/db/client.ts

@@ -0,0 +1,23 @@
+import { PrismaMariaDb } from "@prisma/adapter-mariadb";
+import { env } from "#core/config/env";
+import { connectionConfig } from "#core/db/admin";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import { type Prisma, PrismaClient } from "#generated/prisma/client";
+
+export const db = new PrismaClient({
+	adapter: new PrismaMariaDb({
+		...connectionConfig(env.DATABASE_URL),
+		connectionLimit: env.DATABASE_POOL_MAX,
+	}),
+});
+
+export type Database = typeof db;
+export type Transaction = Prisma.TransactionClient;
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await db.$queryRaw`SELECT 1`;
+});
+onShutdown("database", () => db.$disconnect());

package/templates/features/prisma/files+postgres/prisma/schema.prisma

@@ -0,0 +1,11 @@
+// Models live in prisma/models/*.prisma (one file per table).
+generator client {
+  provider            = "prisma-client"
+  output              = "../src/generated/prisma"
+  importFileExtension = "ts"
+  moduleFormat        = "esm"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/templates/features/prisma/files+postgres/src/core/db/client.ts

@@ -0,0 +1,19 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { env } from "#core/config/env";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import { type Prisma, PrismaClient } from "#generated/prisma/client";
+
+export const db = new PrismaClient({
+	adapter: new PrismaPg({ connectionString: env.DATABASE_URL, max: env.DATABASE_POOL_MAX }),
+});
+
+export type Database = typeof db;
+export type Transaction = Prisma.TransactionClient;
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await db.$queryRaw`SELECT 1`;
+});
+onShutdown("database", () => db.$disconnect());

package/templates/features/storage/files/src/core/storage/commands/check.ts

@@ -0,0 +1,18 @@
+import { defineCommand } from "#core/commands/define";
+import { env } from "#core/config/env";
+import { storage } from "#core/storage/index";
+import { ensureBucket } from "#core/storage/s3";
+
+export default defineCommand({
+	name: "storage:check",
+	description: "Create the bucket if needed, then write, read and delete a probe object",
+	async run(_args, { logger }) {
+		if (env.STORAGE_DRIVER === "s3" && (await ensureBucket())) logger.info({ bucket: env.S3_BUCKET }, "bucket created");
+		const key = `tatara-check/${Date.now()}.txt`;
+		await storage.put(key, "ok", "text/plain");
+		const body = await storage.get(key);
+		await storage.delete(key);
+		if (new TextDecoder().decode(body ?? new Uint8Array()) !== "ok") throw new Error("storage round-trip failed");
+		logger.info({ driver: env.STORAGE_DRIVER }, "storage OK");
+	},
+});

package/templates/features/storage/files/src/core/storage/index.ts

@@ -0,0 +1,8 @@
+import { env } from "#core/config/env";
+import { localStorage } from "#core/storage/local";
+import { s3Storage } from "#core/storage/s3";
+import type { Storage } from "#core/storage/storage";
+
+export type { Storage } from "#core/storage/storage";
+
+export const storage: Storage = env.STORAGE_DRIVER === "s3" ? s3Storage() : localStorage();