@tatara/cli 0.9.2 → 0.11.0

package/templates/features/base/files/src/apps/api/server.ts

@@ -2,5 +2,11 @@ import { startServer } from "@tatara/http";
 import { app } from "#apps/api/app";
 import { env } from "#core/config/env";
 import { logger } from "#core/logging/logger";
+// tatara:slot imports
 
-startServer(app, { port: env.PORT, name: "api", logger });
+startServer(app, {
+	port: env.PORT,
+	name: "api",
+	logger,
+	// tatara:slot server-options
+});

package/templates/features/base/files/src/apps/cli/index.ts

@@ -1,6 +1,9 @@
 import { runCommand, shutdown } from "@tatara/core";
 import { logger } from "#core/logging/logger";
 import { commands } from "#generated/commands";
+// tatara:slot imports
 
-const code = await runCommand(commands, process.argv.slice(2), logger);
+const code = await runCommand(commands, process.argv.slice(2), logger, {
+	// tatara:slot options
+});
 await shutdown(code, logger);

package/templates/features/base/files/src/{core/http/app.ts → apps/http.ts}

@@ -20,6 +20,12 @@ export function createHttpApp(name: AppName, options: { title: string }) {
 			],
 		},
 		bodyLimitBytes: env.BODY_LIMIT_BYTES,
+		timeouts: {
+			defaultMs: env.REQUEST_TIMEOUT_MS,
+			paths: {
+				// tatara:slot timeout-paths
+			},
+		},
 		defaults: { principal: null, language: "en" },
 	});
 	// tatara:slot middleware

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

@@ -3,6 +3,8 @@ import type { Logger } from "#core/logging/logger";
 export interface Principal {
 	userId: string;
 	orgId: string | null;
+	/** the caller's role in orgId, set by requireOrg() */
+	orgRole?: string | null;
 	roles: string[];
 	kind: "user" | "service";
 	claims: Record<string, unknown>;

package/templates/features/base/files/src/core/logging/logger.ts

@@ -1,9 +1,11 @@
 import { loggerOptions } from "@tatara/core";
 import { pino } from "pino";
 import { env } from "#core/config/env";
+// tatara:slot imports
 
-export const logger = pino(
-	loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "__APP_NAME__" }),
-);
+export const logger = pino({
+	...loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "__APP_NAME__" }),
+	// tatara:slot logger-options
+});
 
 export type Logger = typeof logger;

package/templates/features/better-auth/files/src/{core/auth → modules/users}/db/seed.ts

@@ -1,4 +1,4 @@
-import { auth } from "#core/auth/auth";
+import { auth } from "#modules/users/services/auth";
 import { env } from "#core/config/env";
 import { defineSeed } from "@tatara/db";
 

package/templates/features/better-auth/files/src/modules/users/services/auth.ts

@@ -0,0 +1,37 @@
+import { createAuthInstance } from "@tatara/auth";
+import { newId } from "@tatara/db";
+import { bearer, openAPI } from "better-auth/plugins";
+import { env } from "#core/config/env";
+import { database } from "#modules/users/services/adapter";
+// tatara:slot imports
+
+/**
+ * The app's better-auth for its users. The options are the app's own; tatara only adds the
+ * principal middleware and the org check that come back with the instance.
+ */
+export const { auth, attachPrincipal, requireOrg } = createAuthInstance(
+	{
+		appName: "__APP_NAME__",
+		baseURL: env.APP_URL,
+		basePath: "/api/auth",
+		secret: env.BETTER_AUTH_SECRET,
+		trustedOrigins: env.CORS_ORIGINS,
+		database,
+		advanced: { database: { generateId: () => newId() } },
+		// tatara:slot options
+		plugins: [
+			// Authorization: Bearer <session token> for mobile and API clients
+			bearer(),
+			// reference for the auth endpoints at /api/auth/reference
+			openAPI(),
+			// tatara:slot plugins
+		],
+	},
+	{
+		resolvers: [
+			// tatara:slot resolvers
+		],
+	},
+);
+
+export type Session = typeof auth.$Infer.Session;

package/templates/features/better-auth/files/src/{core/auth → modules/users/services}/delivery.ts

@@ -1,5 +1,5 @@
 import { createOutbox } from "@tatara/auth";
-import { smsSender } from "#core/auth/sms";
+import { smsSender } from "#modules/users/services/sms";
 import { env } from "#core/config/env";
 // tatara:slot imports
 

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

@@ -1,5 +1,5 @@
 import { createTestUser as createUser, sessionHeaders } from "@tatara/auth/testing";
-import { auth } from "#core/auth/auth";
+import { auth } from "#modules/users/services/auth";
 // tatara:slot imports
 
 export interface AsUserOptions {
@@ -24,10 +24,11 @@ export async function createTestUser(options: AsUserOptions = {}): Promise<strin
 /** A new user with a real session; the token is sent as a bearer token. */
 export async function authenticate(
 	options: AsUserOptions = {},
-): Promise<{ userId: string; headers: Record<string, string> }> {
+): Promise<{ userId: string; orgId?: string; headers: Record<string, string> }> {
 	// tatara:slot authenticate
 	const userId = await createTestUser(options);
-	return { userId, headers: await sessionHeaders(auth, userId) };
+	const headers = await sessionHeaders(auth, userId);
+	// tatara:slot authenticated
 }
 
 /** Headers that authenticate as a new user. */

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

@@ -0,0 +1,10 @@
+import { expect, it } from "vitest";
+import { adminApi } from "#tests/helpers/api";
+
+it("documents the staff auth on the admin app, not the users' sign-up", async () => {
+	const res = await adminApi.get<{ paths: Record<string, unknown> }>("/openapi.json");
+	expect(res.status).toBe(200);
+	const paths = Object.keys(res.body.paths);
+	expect(paths).toContain("/api/auth/sign-in/email");
+	expect(paths.some((path) => path.startsWith("/api/auth/sign-in/anonymous"))).toBe(false);
+});

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

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { auth } from "#core/auth/auth";
+import { auth } from "#modules/users/services/auth";
 import { api } from "#tests/helpers/api";
 import { authenticate } from "#tests/helpers/auth";
 import { resetDatabase } from "#tests/helpers/db";

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

@@ -1,5 +1,5 @@
 import { beforeEach, expect, it } from "vitest";
-import { auth } from "#core/auth/auth";
+import { auth } from "#modules/users/services/auth";
 import { api } from "#tests/helpers/api";
 import { authenticate } from "#tests/helpers/auth";
 import { applyTestAccess } from "#tests/helpers/authz";

package/templates/features/better-auth/files+drizzle+mysql/src/{core/auth → modules/users/services}/adapter.ts

@@ -1,5 +1,5 @@
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
-import * as authSchema from "#core/auth/db/auth.schema";
+import * as authSchema from "#modules/users/db/auth.schema";
 import { db } from "#core/db/client";
 // tatara:slot imports
 

package/templates/features/better-auth/files+drizzle+postgres/src/{core/auth → modules/users/services}/adapter.ts

@@ -1,5 +1,5 @@
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
-import * as authSchema from "#core/auth/db/auth.schema";
+import * as authSchema from "#modules/users/db/auth.schema";
 import { db } from "#core/db/client";
 // tatara:slot imports
 

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

@@ -0,0 +1,23 @@
+import { onShutdown } from "@tatara/core";
+import { type Cache, createCache, type CacheStore, memoryStore } from "@tatara/cache";
+import { redisStore } from "@tatara/cache/redis";
+import { Redis } from "ioredis";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export type { Cache } from "@tatara/cache";
+
+function redis(): CacheStore {
+	// connects on first command, so importing this file opens nothing
+	const client = new Redis(env.REDIS_URL, { lazyConnect: true, maxRetriesPerRequest: 3 });
+	onShutdown("cache", async () => {
+		await client.quit();
+	});
+	return redisStore(client);
+}
+
+/** The app's cache; pick the store with CACHE_DRIVER. */
+export const cache: Cache = createCache(env.CACHE_DRIVER === "redis" ? redis() : memoryStore(), {
+	prefix: "__APP_NAME__",
+	onError: (error, key) => logger.warn({ err: error, key }, "cache unavailable, computing instead"),
+});

package/templates/features/cache/files/src/core/http/rate-limit.ts

@@ -0,0 +1,15 @@
+import { clientIp, type RateLimitOptions, rateLimit } from "@tatara/http";
+import { cache } from "#core/cache/index";
+import { env } from "#core/config/env";
+
+/**
+ * `middleware: [limitRequests({ name: "contact", windowMs: 60_000, max: 5 })]` on a route: per
+ * caller IP, or per whatever `key` returns (e.g. the signed-in user).
+ */
+export function limitRequests(options: Omit<RateLimitOptions, "counter" | "key"> & Partial<Pick<RateLimitOptions, "key">>) {
+	return rateLimit({
+		counter: cache,
+		key: (c) => clientIp(c, { trustedHops: env.TRUSTED_PROXY_HOPS }),
+		...options,
+	});
+}

package/templates/features/cache/files/tests/tatara/cache.test.ts

@@ -0,0 +1,22 @@
+import { orgKey } from "@tatara/cache";
+import { describe, expect, it, vi } from "vitest";
+import { cache } from "#core/cache/index";
+
+describe("cache", () => {
+	it("wraps a computation and drops an org's keys together", async () => {
+		const orgId = crypto.randomUUID();
+		const load = vi.fn(async () => ({ total: 3 }));
+		expect(await cache.wrap(orgKey(orgId, "dashboard"), 60_000, load)).toEqual({ total: 3 });
+		expect(await cache.wrap(orgKey(orgId, "dashboard"), 60_000, load)).toEqual({ total: 3 });
+		expect(load).toHaveBeenCalledTimes(1);
+		expect(await cache.delPrefix(orgKey(orgId))).toBe(1);
+		expect(await cache.get(orgKey(orgId, "dashboard"))).toBeNull();
+	});
+
+	it("lets one holder run under a lock", async () => {
+		const key = crypto.randomUUID();
+		const first = cache.lock(key, 10_000, () => new Promise((r) => setTimeout(() => r("ran"), 50)));
+		expect(await cache.lock(key, 10_000, async () => "second")).toEqual({ acquired: false });
+		expect(await first).toEqual({ acquired: true, value: "ran" });
+	});
+});

package/templates/features/cache/files/tests/tatara/rate-limit.test.ts

@@ -0,0 +1,27 @@
+import { createRoute } from "@hono/zod-openapi";
+import { createRouter, handleErrors } from "@tatara/http";
+import { describe, expect, it } from "vitest";
+import { limitRequests } from "#core/http/rate-limit";
+
+describe("limitRequests", () => {
+	it("answers 429 once a caller passes the limit", async () => {
+		const name = crypto.randomUUID();
+		const app = createRouter();
+		app.openapi(
+			createRoute({
+				method: "post",
+				path: "/contact",
+				middleware: [limitRequests({ name, windowMs: 60_000, max: 2, key: (c) => c.req.header("x-who") })],
+				responses: { 204: { description: "Sent" } },
+			}),
+			(c) => c.body(null, 204),
+		);
+		handleErrors(app);
+		const send = () => app.request("/contact", { method: "POST", headers: { "x-who": "a" } });
+		expect((await send()).status).toBe(204);
+		expect((await send()).status).toBe(204);
+		const limited = await send();
+		expect(limited.status).toBe(429);
+		expect(limited.headers.get("retry-after")).toBe("60");
+	});
+});

package/templates/features/cache/files+postgres/src/core/cache/index.ts

@@ -0,0 +1,36 @@
+import { onShutdown } from "@tatara/core";
+import { type Cache, createCache, type CacheStore, memoryStore } from "@tatara/cache";
+import { postgresStore } from "@tatara/cache/postgres";
+import { redisStore } from "@tatara/cache/redis";
+import { Redis } from "ioredis";
+import pg from "pg";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export type { Cache } from "@tatara/cache";
+
+function redis(): CacheStore {
+	// connects on first command, so importing this file opens nothing
+	const client = new Redis(env.REDIS_URL, { lazyConnect: true, maxRetriesPerRequest: 3 });
+	onShutdown("cache", async () => {
+		await client.quit();
+	});
+	return redisStore(client);
+}
+
+function postgres(): CacheStore {
+	// an unlogged table in the "tatara" schema, created on first use
+	const pool = new pg.Pool({ connectionString: env.DATABASE_URL, max: 5 });
+	onShutdown("cache", async () => {
+		await pool.end();
+	});
+	return postgresStore(pool);
+}
+
+const stores = { redis, postgres, memory: memoryStore };
+
+/** The app's cache; pick the store with CACHE_DRIVER. */
+export const cache: Cache = createCache(stores[env.CACHE_DRIVER](), {
+	prefix: "__APP_NAME__",
+	onError: (error, key) => logger.warn({ err: error, key }, "cache unavailable, computing instead"),
+});

package/templates/features/db/files+mysql+drizzle/src/core/commands/db/command-runs.schema.ts

@@ -0,0 +1,10 @@
+import { sql } from "drizzle-orm";
+import { datetime, int, mysqlTable, varchar } from "drizzle-orm/mysql-core";
+
+/** Which "once" commands this database has run (written by `deploy`). */
+export const tataraCommandRuns = mysqlTable("tatara_command_runs", {
+	name: varchar({ length: 255 }).primaryKey(),
+	phase: varchar({ length: 16 }).notNull(),
+	ranAt: datetime({ fsp: 3 }).notNull().default(sql`current_timestamp(3)`),
+	durationMs: int().notNull(),
+});

package/templates/features/db/files+mysql+drizzle/src/core/db/admin.ts

@@ -1,2 +1,7 @@
 // This app uses MySQL through mysql2.
-export { dropAllTables, ensureDatabase, truncateAllTables } from "@tatara/db/mysql2";
+export {
+	commandLedger,
+	dropAllTables,
+	ensureDatabase,
+	truncateAllTables,
+} from "@tatara/db/mysql2";

package/templates/features/db/files+mysql+prisma/prisma/models/command-runs.prisma

@@ -0,0 +1,9 @@
+// Which "once" commands this database has run (written by `deploy`).
+model TataraCommandRun {
+  name       String   @id @db.VarChar(255)
+  phase      String   @db.VarChar(16)
+  ranAt      DateTime @default(now()) @map("ran_at") @db.DateTime(3)
+  durationMs Int      @map("duration_ms")
+
+  @@map("tatara_command_runs")
+}

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

@@ -1,5 +1,6 @@
 // This app uses MySQL through the mariadb driver (Prisma adapter).
 export {
+	commandLedger,
 	connectionConfig,
 	dropAllTables,
 	ensureDatabase,

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

@@ -1,2 +1,7 @@
 // This app uses PostgreSQL through node-postgres.
-export { dropAllTables, ensureDatabase, truncateAllTables } from "@tatara/db/postgres";
+export {
+	commandLedger,
+	dropAllTables,
+	ensureDatabase,
+	truncateAllTables,
+} from "@tatara/db/postgres";

package/templates/features/email/files/src/core/email/send.ts

@@ -1,13 +1,33 @@
-import { createMailer } from "@tatara/email";
+import { createMailer, renderEmail } from "@tatara/email";
 import { env } from "#core/config/env";
 import { logger } from "#core/logging/logger";
+import type { emails } from "#generated/emails";
 
 export type { EmailMessage } from "@tatara/email";
 
-/** Sends through SMTP (Mailpit locally) or logs it when EMAIL_DRIVER=console. */
+/** Sends through SMTP (Mailpit locally) or Mailgun, or logs it when EMAIL_DRIVER=console. */
 export const { send: sendEmail } = createMailer({
 	driver: env.EMAIL_DRIVER,
 	smtpUrl: env.SMTP_URL,
+	...(env.MAILGUN_API_KEY && env.MAILGUN_DOMAIN
+		? { mailgun: { apiKey: env.MAILGUN_API_KEY, domain: env.MAILGUN_DOMAIN, apiUrl: env.MAILGUN_API_URL } }
+		: {}),
 	from: env.EMAIL_FROM,
 	logger,
 });
+
+type Templates = { [E in (typeof emails)[number] as E["name"]]: Parameters<E["render"]>[0] };
+
+/** Renders an `emails/*.ts` template in `language` and sends it. */
+export async function sendTemplate<N extends keyof Templates & string>(
+	name: N,
+	to: string,
+	data: Templates[N],
+	language = "en",
+): Promise<void> {
+	// loaded on first use: core doesn't import module code until it's needed
+	const { emails: all } = await import("#generated/emails");
+	const template = all.find((e) => e.name === name);
+	if (!template) throw new Error(`No email template named "${name}"`);
+	await sendEmail({ to, ...renderEmail(template, data, language) });
+}

package/templates/features/email/files/src/modules/example/emails/welcome.ts

@@ -0,0 +1,11 @@
+import { defineEmail } from "@tatara/email";
+import { z } from "zod";
+
+export default defineEmail({
+	name: "example.welcome",
+	schema: z.object({ name: z.string().min(1) }),
+	render: ({ name }, language) =>
+		language === "ar"
+			? { subject: "أهلاً بك", text: `أهلاً ${name}` }
+			: { subject: "Welcome", text: `Hello ${name}, welcome aboard.` },
+});

package/templates/features/jobs/files/src/apps/cron/index.ts

@@ -1,8 +1,7 @@
 import { handleSignals } from "@tatara/core";
 import { startCron } from "@tatara/jobs";
-import { redis } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
-import { schedules } from "#generated/schedules";
+import { scheduleRunner } from "#apps/cron/runner";
 
-startCron({ schedules, redis, logger });
+startCron({ ...scheduleRunner, logger });
 handleSignals(logger);

package/templates/features/jobs/files/src/apps/cron/runner.ts

@@ -0,0 +1,11 @@
+import { cache } from "#core/cache/index";
+import { schedules } from "#generated/schedules";
+// tatara:slot imports
+
+/** What runs a schedule, wherever it's triggered from: the cron app, `schedule:run`, or HTTP. */
+export const scheduleRunner = {
+	schedules,
+	// one run per tick across every process and trigger
+	lock: cache,
+	// tatara:slot options
+};

package/templates/features/jobs/files/src/apps/worker/index.ts

@@ -1,16 +1,9 @@
 import { handleSignals } from "@tatara/core";
 import { startWorker } from "@tatara/jobs";
 import { env } from "#core/config/env";
-import { QUEUE_NAME, redis } from "#core/jobs/index";
+import { jobs } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 
-startWorker({
-	queue: QUEUE_NAME,
-	prefix: env.JOBS_PREFIX,
-	redis: redis(),
-	concurrency: env.WORKER_CONCURRENCY,
-	consumers,
-	logger,
-});
+await startWorker({ driver: jobs.driver, consumers, concurrency: env.WORKER_CONCURRENCY, logger });
 handleSignals(logger);

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

@@ -1,10 +1,41 @@
-import { createQueue, lazyRedis } from "@tatara/jobs";
+import { createJobs, inlineDriver, type JobDriver, lazyRedis, type TopicsOf } from "@tatara/jobs";
+import { bullmqDriver } from "@tatara/jobs/bullmq";
+import { kafkaDriver } from "@tatara/jobs/kafka";
+import { Kafka } from "kafkajs";
 import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+import type { consumers } from "#generated/consumers";
 
-export const QUEUE_NAME = "__APP_NAME__-jobs";
-
-/** The shared Redis connection, opened on first use. */
+/** The shared Redis connection for BullMQ, opened on first use. */
 export const redis = lazyRedis(env.REDIS_URL);
 
-/** `enqueue(topic, data)`: the consumer with that topic validates the payload. */
-export const { enqueue } = createQueue({ name: QUEUE_NAME, prefix: env.JOBS_PREFIX, redis });
+function kafka(): JobDriver {
+	if (!env.KAFKA_BROKERS) throw new Error("JOBS_DRIVER=kafka needs KAFKA_BROKERS");
+	const client = new Kafka({
+		clientId: env.KAFKA_CLIENT_ID,
+		brokers: env.KAFKA_BROKERS.split(","),
+		ssl: env.KAFKA_SSL,
+		...(env.KAFKA_SASL_USERNAME && env.KAFKA_SASL_PASSWORD
+			? {
+					sasl: {
+						mechanism: "scram-sha-512",
+						username: env.KAFKA_SASL_USERNAME,
+						password: env.KAFKA_SASL_PASSWORD,
+					},
+				}
+			: {}),
+	});
+	return kafkaDriver({ kafka: client, topic: "__APP_NAME__.jobs", groupId: env.KAFKA_CLIENT_ID });
+}
+
+const drivers: Record<typeof env.JOBS_DRIVER, () => JobDriver> = {
+	bullmq: () => bullmqDriver({ name: "__APP_NAME__-jobs", prefix: env.JOBS_PREFIX, redis }),
+	kafka,
+	// jobs run where they're sent, with no worker: tests and quick local work
+	inline: () =>
+		inlineDriver({ consumers: async () => (await import("#generated/consumers")).consumers, logger }),
+};
+
+/** `jobs.enqueue(topic, data, { orgId })`, typed by the app's consumers; pick the driver with JOBS_DRIVER. */
+export const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: drivers[env.JOBS_DRIVER]() });
+export const { enqueue } = jobs;

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { processJob, withLock } from "@tatara/jobs";
-import { redis } from "#core/jobs/index";
+import { type InlineDriver, processJob } from "@tatara/jobs";
+import { enqueue, jobs } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 
@@ -17,13 +17,10 @@ describe("jobs", () => {
 		);
 	});
 
-	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(redis(), key, 5000, async () => {
-			inner = await withLock(redis(), key, 5000, async () => {});
-		});
-		expect(outer).toBe(true);
-		expect(inner).toBe(false);
+	it("runs an enqueued job in tests (JOBS_DRIVER=inline)", async () => {
+		await enqueue("example.send-welcome", { name: "Ada" });
+		const driver = jobs.driver as InlineDriver;
+		await driver.drain();
+		expect(driver.dead).toEqual([]);
 	});
 });

package/templates/features/jobs/files+drizzle+postgres/src/core/jobs/outbox.ts

@@ -0,0 +1,23 @@
+import { type SQL, sql } from "drizzle-orm";
+import type { Queryable } from "@tatara/jobs/postgres";
+import { type Executor, pool } from "#core/db/client";
+
+/** The app's own pool: the Postgres driver needs no connection of its own. */
+export const outboxPool: Queryable = pool;
+
+/**
+ * `enqueue(topic, data, { executor: inTransaction(tx) })`: with JOBS_DRIVER=postgres the job is
+ * written in `tx`, so it exists exactly when the transaction commits.
+ */
+export function inTransaction(executor: Executor): Queryable {
+	return {
+		query(text, values = []) {
+			// $1, $2… become drizzle parameters
+			const parts = text.split(/\$(\d+)/);
+			let query: SQL = sql.raw(parts[0] ?? "");
+			for (let i = 1; i < parts.length; i += 2)
+				query = sql`${query}${values[Number(parts[i]) - 1]}${sql.raw(parts[i + 1] ?? "")}`;
+			return executor.execute(query);
+		},
+	};
+}

package/templates/features/jobs/files+drizzle+postgres/tests/tatara/jobs-outbox.test.ts

@@ -0,0 +1,34 @@
+import { createJobs, type TopicsOf } from "@tatara/jobs";
+import { postgresDriver } from "@tatara/jobs/postgres";
+import { describe, expect, it } from "vitest";
+import { db } from "#core/db/client";
+import { inTransaction, outboxPool } from "#core/jobs/outbox";
+import type { consumers } from "#generated/consumers";
+
+const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: postgresDriver({ db: outboxPool }) });
+
+async function stored(id: string): Promise<number> {
+	const result = (await outboxPool.query("select count(*)::int as n from tatara.jobs where id = $1", [id])) as {
+		rows: { n: number }[];
+	};
+	return result.rows[0]?.n ?? 0;
+}
+
+describe("the Postgres job outbox", () => {
+	it("stores a job with the caller's transaction, and drops it on rollback", async () => {
+		let rolledBack = "";
+		await expect(
+			db.transaction(async (tx) => {
+				rolledBack = await jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) });
+				throw new Error("rollback");
+			}),
+		).rejects.toThrow("rollback");
+		expect(await stored(rolledBack)).toBe(0);
+
+		const committed = await db.transaction(async (tx) =>
+			jobs.enqueue("example.send-welcome", { name: "Ada" }, { executor: inTransaction(tx) }),
+		);
+		expect(await stored(committed)).toBe(1);
+		await outboxPool.query("delete from tatara.jobs where id = $1", [committed]);
+	});
+});

package/templates/features/jobs/files+postgres/src/core/jobs/index.ts

@@ -0,0 +1,47 @@
+import { createJobs, inlineDriver, type JobDriver, lazyRedis, type TopicsOf } from "@tatara/jobs";
+import { bullmqDriver } from "@tatara/jobs/bullmq";
+import { kafkaDriver } from "@tatara/jobs/kafka";
+import { postgresDriver } from "@tatara/jobs/postgres";
+import { Kafka } from "kafkajs";
+import { env } from "#core/config/env";
+import { outboxPool } from "#core/jobs/outbox";
+import { logger } from "#core/logging/logger";
+import type { consumers } from "#generated/consumers";
+
+export { inTransaction } from "#core/jobs/outbox";
+
+/** The shared Redis connection for BullMQ, opened on first use. */
+export const redis = lazyRedis(env.REDIS_URL);
+
+function kafka(): JobDriver {
+	if (!env.KAFKA_BROKERS) throw new Error("JOBS_DRIVER=kafka needs KAFKA_BROKERS");
+	const client = new Kafka({
+		clientId: env.KAFKA_CLIENT_ID,
+		brokers: env.KAFKA_BROKERS.split(","),
+		ssl: env.KAFKA_SSL,
+		...(env.KAFKA_SASL_USERNAME && env.KAFKA_SASL_PASSWORD
+			? {
+					sasl: {
+						mechanism: "scram-sha-512",
+						username: env.KAFKA_SASL_USERNAME,
+						password: env.KAFKA_SASL_PASSWORD,
+					},
+				}
+			: {}),
+	});
+	return kafkaDriver({ kafka: client, topic: "__APP_NAME__.jobs", groupId: env.KAFKA_CLIENT_ID });
+}
+
+const drivers: Record<typeof env.JOBS_DRIVER, () => JobDriver> = {
+	bullmq: () => bullmqDriver({ name: "__APP_NAME__-jobs", prefix: env.JOBS_PREFIX, redis }),
+	// a "tatara.jobs" table, claimed with SKIP LOCKED; enqueue with { executor: inTransaction(tx) }
+	postgres: () => postgresDriver({ db: outboxPool }),
+	kafka,
+	// jobs run where they're sent, with no worker: tests and quick local work
+	inline: () =>
+		inlineDriver({ consumers: async () => (await import("#generated/consumers")).consumers, logger }),
+};
+
+/** `jobs.enqueue(topic, data, { orgId })`, typed by the app's consumers; pick the driver with JOBS_DRIVER. */
+export const jobs = createJobs<TopicsOf<typeof consumers>>({ driver: drivers[env.JOBS_DRIVER]() });
+export const { enqueue } = jobs;