@tatara/cli 0.0.0-stage → 0.1.1

package/templates/features/better-auth/files+prisma+postgres/src/core/auth/adapter.ts

@@ -0,0 +1,4 @@
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import { db } from "#core/db/client";
+
+export const database = prismaAdapter(db, { provider: "postgresql" });

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

@@ -0,0 +1,12 @@
+import { defineCommand } from "#core/commands/define";
+import { env } from "#core/config/env";
+import { migrateDatabase } from "#core/db/migrate";
+
+export default defineCommand({
+	name: "db:migrate",
+	description: "Apply pending database migrations",
+	async run(_args, { logger }) {
+		await migrateDatabase(env.DATABASE_URL);
+		logger.info("migrations applied");
+	},
+});

package/templates/features/db/files/src/core/db/commands/reset.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import { defineCommand, flag } from "#core/commands/define";
+import { env } from "#core/config/env";
+import { dropAllTables } from "#core/db/admin";
+import { migrateDatabase } from "#core/db/migrate";
+
+export default defineCommand({
+	name: "db:reset",
+	description: "Drop every table and re-apply migrations (refuses to run in production)",
+	args: z.object({ force: flag() }),
+	async run({ force }, { logger }) {
+		if (env.NODE_ENV === "production" && !force) {
+			throw new Error("db:reset refuses to run with NODE_ENV=production (pass --force to override)");
+		}
+		await dropAllTables(env.DATABASE_URL);
+		await migrateDatabase(env.DATABASE_URL);
+		logger.info("database reset");
+	},
+});

package/templates/features/db/files/src/core/db/commands/seed.ts

@@ -0,0 +1,13 @@
+import { defineCommand } from "#core/commands/define";
+import { seeds } from "#generated/seeds";
+
+export default defineCommand({
+	name: "db:seed",
+	description: "Run every idempotent seed (core first, then modules)",
+	async run(_args, { logger }) {
+		for (const seed of [...seeds].sort((a, b) => (a.order ?? 100) - (b.order ?? 100))) {
+			await seed.run({ logger: logger.child({ seed: seed.name }) });
+			logger.info({ seed: seed.name }, "seeded");
+		}
+	},
+});

package/templates/features/db/files/src/core/db/id.ts

@@ -0,0 +1,13 @@
+import { randomFillSync } from "node:crypto";
+
+/** UUIDv7: random but time-ordered, so sorting by id is sorting by creation time. */
+export function newId(): string {
+	const bytes = new Uint8Array(16);
+	randomFillSync(bytes);
+	const ms = BigInt(Date.now());
+	for (let i = 0; i < 6; i++) bytes[i] = Number((ms >> BigInt(8 * (5 - i))) & 0xffn);
+	bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x70;
+	bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+	const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/templates/features/db/files/src/core/db/seed.ts

@@ -0,0 +1,14 @@
+import type { Logger } from "#core/logging/logger";
+
+export interface SeedDefinition {
+	name: string;
+	/** lower runs first */
+	order?: number;
+	/** must be idempotent: seeds run on every `tatara dev` */
+	run(ctx: { logger: Logger }): Promise<void>;
+}
+
+/** Default export of every `db/seed.ts`; discovered by `tatara sync`. */
+export function defineSeed(definition: SeedDefinition): SeedDefinition {
+	return definition;
+}

package/templates/features/db/files/src/core/db/tests/reset.test.ts

@@ -0,0 +1,7 @@
+import { expect, it } from "vitest";
+import { parseFlags } from "#core/commands/runner";
+import reset from "#core/db/commands/reset";
+
+it("does not treat --force false as forcing db:reset", () => {
+	expect(reset.args?.parse(parseFlags(["--force", "false"]))).toEqual({ force: false });
+});

package/templates/features/db/files/tests/global-setup.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parseEnv } from "node:util";
+import { ensureDatabase } from "#core/db/admin";
+import { migrateDatabase } from "#core/db/migrate";
+import { TEST_WORKERS, workerDatabaseUrl } from "#tests/helpers/database-url";
+
+/** Creates and migrates one database per test worker, once per run. */
+export default async function setup() {
+	const fileEnv = existsSync(".env.test")
+		? (parseEnv(readFileSync(".env.test", "utf8")) as Record<string, string>)
+		: {};
+	const base = process.env.DATABASE_URL ?? fileEnv.DATABASE_URL;
+	if (!base) throw new Error("DATABASE_URL is not set for tests (.env.test)");
+	try {
+		await Promise.all(
+			Array.from({ length: TEST_WORKERS }, async (_, i) => {
+				const url = workerDatabaseUrl(base, i + 1);
+				await ensureDatabase(url);
+				await migrateDatabase(url);
+			}),
+		);
+	} catch (error) {
+		throw new Error(
+			`Could not prepare the test databases. Is the database running? (\`docker compose up -d --wait\`)\n${String(error)}`,
+		);
+	}
+}

package/templates/features/db/files/tests/helpers/database-url.ts

@@ -0,0 +1,9 @@
+/** Number of Vitest workers; global setup prepares one database per worker. */
+export const TEST_WORKERS = 4;
+
+/** postgres://…/app_test → postgres://…/app_test_<worker> */
+export function workerDatabaseUrl(baseUrl: string, worker: number | string): string {
+	const url = new URL(baseUrl);
+	url.pathname = `${url.pathname}_${worker}`;
+	return url.toString();
+}

package/templates/features/db/files/tests/helpers/db.ts

@@ -0,0 +1,7 @@
+import { env } from "#core/config/env";
+import { truncateAllTables } from "#core/db/admin";
+
+/** Empties every application table in this worker's test database. Use in beforeEach. */
+export async function resetDatabase(): Promise<void> {
+	await truncateAllTables(env.DATABASE_URL);
+}

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

@@ -0,0 +1,53 @@
+import mysql from "mysql2/promise";
+
+const MIGRATION_TABLES = ["__drizzle_migrations", "_prisma_migrations"];
+
+function databaseName(url: string): string {
+	return decodeURIComponent(new URL(url).pathname.slice(1));
+}
+
+async function withConnection<T>(url: string, fn: (c: mysql.Connection) => Promise<T>): Promise<T> {
+	const connection = await mysql.createConnection({ uri: url, multipleStatements: true });
+	try {
+		return await fn(connection);
+	} finally {
+		await connection.end();
+	}
+}
+
+/** Creates the database named in `url` if it does not exist. */
+export async function ensureDatabase(url: string): Promise<void> {
+	const name = databaseName(url);
+	const server = new URL(url);
+	server.pathname = "/";
+	await withConnection(server.toString(), async (c) => {
+		await c.query(`create database if not exists \`${name.replaceAll("`", "``")}\``);
+	});
+}
+
+async function tables(c: mysql.Connection): Promise<string[]> {
+	const [rows] = await c.query<mysql.RowDataPacket[]>(
+		"select table_name as name from information_schema.tables where table_schema = database() and table_type = 'BASE TABLE'",
+	);
+	return rows.map((r) => String(r.name));
+}
+
+export async function dropAllTables(url: string): Promise<void> {
+	await withConnection(url, async (c) => {
+		const names = await tables(c);
+		if (names.length === 0) return;
+		await c.query(
+			`set foreign_key_checks = 0; drop table ${names.map((t) => `\`${t}\``).join(", ")}; set foreign_key_checks = 1;`,
+		);
+	});
+}
+
+export async function truncateAllTables(url: string): Promise<void> {
+	await withConnection(url, async (c) => {
+		const names = (await tables(c)).filter((t) => !MIGRATION_TABLES.includes(t));
+		if (names.length === 0) return;
+		await c.query(
+			`set foreign_key_checks = 0; ${names.map((t) => `truncate table \`${t}\`;`).join(" ")} set foreign_key_checks = 1;`,
+		);
+	});
+}

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

@@ -0,0 +1,78 @@
+import * as mariadb from "mariadb";
+
+const MIGRATION_TABLES = ["__drizzle_migrations", "_prisma_migrations"];
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+/**
+ * mariadb connection options from a mysql:// URL. Public-key retrieval (needed by MySQL's
+ * caching_sha2_password without TLS) is only enabled for local hosts or when the URL asks
+ * for it; use `?ssl=true` for remote databases.
+ */
+export function connectionConfig(url: string): mariadb.ConnectionConfig {
+	const u = new URL(url);
+	const param = (name: string) => u.searchParams.get(name);
+	return {
+		host: u.hostname,
+		port: Number(u.port || 3306),
+		user: decodeURIComponent(u.username),
+		password: decodeURIComponent(u.password),
+		database: decodeURIComponent(u.pathname.slice(1)) || undefined,
+		allowPublicKeyRetrieval:
+			param("allowPublicKeyRetrieval") === "true" || LOCAL_HOSTS.has(u.hostname),
+		...(param("ssl") === "true" ? { ssl: { rejectUnauthorized: true } } : {}),
+	};
+}
+
+const adminConfig = (url: string): mariadb.ConnectionConfig => ({
+	...connectionConfig(url),
+	multipleStatements: true,
+});
+
+async function withConnection<T>(
+	config: mariadb.ConnectionConfig,
+	fn: (c: mariadb.Connection) => Promise<T>,
+): Promise<T> {
+	const connection = await mariadb.createConnection(config);
+	try {
+		return await fn(connection);
+	} finally {
+		await connection.end();
+	}
+}
+
+/** Creates the database named in `url` if it does not exist. */
+export async function ensureDatabase(url: string): Promise<void> {
+	const config = adminConfig(url);
+	const name = String(config.database);
+	await withConnection({ ...config, database: undefined }, async (c) => {
+		await c.query(`create database if not exists \`${name.replaceAll("`", "``")}\``);
+	});
+}
+
+async function tables(c: mariadb.Connection): Promise<string[]> {
+	const rows: { name: string }[] = await c.query(
+		"select table_name as name from information_schema.tables where table_schema = database() and table_type = 'BASE TABLE'",
+	);
+	return rows.map((r) => String(r.name));
+}
+
+export async function dropAllTables(url: string): Promise<void> {
+	await withConnection(adminConfig(url), async (c) => {
+		const names = await tables(c);
+		if (names.length === 0) return;
+		await c.query(
+			`set foreign_key_checks = 0; drop table ${names.map((t) => `\`${t}\``).join(", ")}; set foreign_key_checks = 1;`,
+		);
+	});
+}
+
+export async function truncateAllTables(url: string): Promise<void> {
+	await withConnection(adminConfig(url), async (c) => {
+		const names = (await tables(c)).filter((t) => !MIGRATION_TABLES.includes(t));
+		if (names.length === 0) return;
+		await c.query(
+			`set foreign_key_checks = 0; ${names.map((t) => `truncate table \`${t}\`;`).join(" ")} set foreign_key_checks = 1;`,
+		);
+	});
+}

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

@@ -0,0 +1,50 @@
+import pg from "pg";
+
+const MIGRATION_TABLES = ["__drizzle_migrations", "_prisma_migrations"];
+
+function databaseName(url: string): string {
+	return decodeURIComponent(new URL(url).pathname.slice(1));
+}
+
+async function withClient<T>(url: string, fn: (client: pg.Client) => Promise<T>): Promise<T> {
+	const client = new pg.Client({ connectionString: url });
+	await client.connect();
+	try {
+		return await fn(client);
+	} finally {
+		await client.end();
+	}
+}
+
+/** Creates the database named in `url` if it does not exist. */
+export async function ensureDatabase(url: string): Promise<void> {
+	const name = databaseName(url);
+	const admin = new URL(url);
+	admin.pathname = "/postgres";
+	await withClient(admin.toString(), async (client) => {
+		const found = await client.query("select 1 from pg_database where datname = $1", [name]);
+		if (found.rowCount === 0) await client.query(`create database "${name.replaceAll('"', '""')}"`);
+	});
+}
+
+export async function dropAllTables(url: string): Promise<void> {
+	await withClient(url, async (client) => {
+		await client.query("drop schema if exists drizzle cascade");
+		await client.query("drop schema public cascade");
+		await client.query("create schema public");
+	});
+}
+
+export async function truncateAllTables(url: string): Promise<void> {
+	await withClient(url, async (client) => {
+		const { rows } = await client.query<{ tablename: string }>(
+			"select tablename from pg_tables where schemaname = 'public'",
+		);
+		const tables = rows.map((r) => r.tablename).filter((t) => !MIGRATION_TABLES.includes(t));
+		if (tables.length > 0) {
+			await client.query(
+				`truncate table ${tables.map((t) => `"${t}"`).join(", ")} restart identity cascade`,
+			);
+		}
+	});
+}

package/templates/features/drizzle/files+mysql/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { existsSync } from "node:fs";
+import { defineConfig } from "drizzle-kit";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+
+export default defineConfig({
+	dialect: "mysql",
+	schema: ["./src/core/*/db/*.schema.ts", "./src/modules/*/db/*.schema.ts"],
+	out: "./drizzle",
+	casing: "snake_case",
+	dbCredentials: { url: process.env.DATABASE_URL ?? "" },
+});

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

@@ -0,0 +1,20 @@
+import { drizzle } from "drizzle-orm/mysql2";
+import mysql from "mysql2/promise";
+import { env } from "#core/config/env";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import * as schema from "#generated/schema";
+
+export const pool = mysql.createPool({ uri: env.DATABASE_URL, connectionLimit: env.DATABASE_POOL_MAX });
+
+export const db = drizzle({ client: pool, schema, mode: "default", casing: "snake_case" });
+
+export type Database = typeof db;
+export type Transaction = Parameters<Parameters<Database["transaction"]>[0]>[0];
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await pool.query("select 1");
+});
+onShutdown("database", () => pool.end());

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

@@ -0,0 +1,13 @@
+import { drizzle } from "drizzle-orm/mysql2";
+import { migrate } from "drizzle-orm/mysql2/migrator";
+import mysql from "mysql2/promise";
+
+/** Applies ./drizzle migrations to the database at `url`. */
+export async function migrateDatabase(url: string): Promise<void> {
+	const connection = await mysql.createConnection({ uri: url });
+	try {
+		await migrate(drizzle({ client: connection }), { migrationsFolder: "drizzle" });
+	} finally {
+		await connection.end();
+	}
+}

package/templates/features/drizzle/files+postgres/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { existsSync } from "node:fs";
+import { defineConfig } from "drizzle-kit";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+
+export default defineConfig({
+	dialect: "postgresql",
+	schema: ["./src/core/*/db/*.schema.ts", "./src/modules/*/db/*.schema.ts"],
+	out: "./drizzle",
+	casing: "snake_case",
+	dbCredentials: { url: process.env.DATABASE_URL ?? "" },
+});

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

@@ -0,0 +1,20 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import { env } from "#core/config/env";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import * as schema from "#generated/schema";
+
+export const pool = new pg.Pool({ connectionString: env.DATABASE_URL, max: env.DATABASE_POOL_MAX });
+
+export const db = drizzle({ client: pool, schema, casing: "snake_case" });
+
+export type Database = typeof db;
+export type Transaction = Parameters<Parameters<Database["transaction"]>[0]>[0];
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await pool.query("select 1");
+});
+onShutdown("database", () => pool.end());

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

@@ -0,0 +1,13 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import pg from "pg";
+
+/** Applies ./drizzle migrations to the database at `url`. */
+export async function migrateDatabase(url: string): Promise<void> {
+	const pool = new pg.Pool({ connectionString: url, max: 1 });
+	try {
+		await migrate(drizzle({ client: pool }), { migrationsFolder: "drizzle" });
+	} finally {
+		await pool.end();
+	}
+}

package/templates/features/email/files/src/core/email/commands/send-test.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { defineCommand } from "#core/commands/define";
+import { sendEmail } from "#core/email/send";
+
+export default defineCommand({
+	name: "email:send-test",
+	description: "Send a test email (see it in Mailpit locally)",
+	args: z.object({ to: z.email().default("dev@example.com") }),
+	async run({ to }, { logger }) {
+		await sendEmail({ to, subject: "Test email", text: "It works." });
+		logger.info({ to }, "test email sent");
+	},
+});

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

@@ -0,0 +1,22 @@
+import { createTransport, type Transporter } from "nodemailer";
+import { env } from "#core/config/env";
+import { logger } from "#core/logging/logger";
+
+export interface EmailMessage {
+	to: string;
+	subject: string;
+	text: string;
+	html?: string;
+}
+
+let transport: Transporter | undefined;
+
+/** Sends through SMTP (Mailpit locally) or logs it when EMAIL_DRIVER=console. */
+export async function sendEmail(message: EmailMessage): Promise<void> {
+	if (env.EMAIL_DRIVER === "console") {
+		logger.info({ to: message.to, subject: message.subject }, "email (console driver)");
+		return;
+	}
+	transport ??= createTransport(env.SMTP_URL);
+	await transport.sendMail({ from: env.EMAIL_FROM, ...message });
+}

package/templates/features/email/files/src/core/email/tests/email.test.ts

@@ -0,0 +1,8 @@
+import { describe, expect, it } from "vitest";
+import { sendEmail } from "#core/email/send";
+
+describe("email", () => {
+	it("accepts a message with the test (console) driver", async () => {
+		await expect(sendEmail({ to: "a@example.com", subject: "Hi", text: "Hello" })).resolves.toBeUndefined();
+	});
+});

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

@@ -0,0 +1,41 @@
+import { createMiddleware } from "hono/factory";
+import { env } from "#core/config/env";
+import type { AppEnv } from "#core/http/context";
+import ar from "#locales/ar" with { type: "json" };
+import en from "#locales/en" with { type: "json" };
+
+type Dictionary = { [key: string]: string | Dictionary };
+
+const dictionaries: Record<string, Dictionary> = { en, ar };
+
+export const SUPPORTED_LANGUAGES = Object.keys(dictionaries);
+
+function lookup(dict: Dictionary | undefined, key: string): string | undefined {
+	let node: string | Dictionary | undefined = dict;
+	for (const part of key.split(".")) {
+		if (!node || typeof node === "string") return undefined;
+		node = node[part];
+	}
+	return typeof node === "string" ? node : undefined;
+}
+
+/** Translates `key` ("errors.NOT_FOUND"), falling back to the default language, then `fallback`. */
+export function t(language: string, key: string, fallback = key, vars: Record<string, string> = {}): string {
+	const text = lookup(dictionaries[language], key) ?? lookup(dictionaries[env.DEFAULT_LANGUAGE], key) ?? fallback;
+	return text.replace(/\{(\w+)\}/g, (_, name: string) => vars[name] ?? `{${name}}`);
+}
+
+/** ?lang, then the `lang` cookie, then Accept-Language; sets `c.var.language`. */
+export const detectLanguage = createMiddleware<AppEnv>(async (c, next) => {
+	const candidates = [
+		c.req.query("lang"),
+		/(?:^|;\s*)lang=([^;]+)/.exec(c.req.header("cookie") ?? "")?.[1],
+		...(c.req.header("accept-language") ?? "")
+			.split(",")
+			.map((part) => part.split(";")[0]?.trim().toLowerCase().split("-")[0]),
+	];
+	const language = candidates.find((l) => l && SUPPORTED_LANGUAGES.includes(l)) ?? env.DEFAULT_LANGUAGE;
+	c.set("language", language);
+	c.header("content-language", language);
+	await next();
+});

package/templates/features/i18n/files/src/core/i18n/tests/i18n.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { t } from "#core/i18n/index";
+import { api } from "#tests/helpers/api";
+
+describe("i18n", () => {
+	it("translates with a fallback to the default language", () => {
+		expect(t("ar", "errors.NOT_FOUND")).toBe("غير موجود");
+		expect(t("fr", "errors.NOT_FOUND")).toBe("Not found");
+		expect(t("en", "missing.key", "Fallback")).toBe("Fallback");
+	});
+
+	it("localizes error messages from Accept-Language", async () => {
+		const res = await api.get("/api/nope", { headers: { "accept-language": "ar-SA,ar;q=0.9" } });
+		expect(res.status).toBe(404);
+		const invalid = await api.get(`/api/greetings?name=${"x".repeat(60)}`, {
+			headers: { "accept-language": "ar" },
+		});
+		expect(invalid.body).toMatchObject({ code: "VALIDATION_ERROR", error: "الطلب غير صالح" });
+		expect(invalid.headers.get("content-language")).toBe("ar");
+	});
+});

package/templates/features/i18n/files/src/locales/ar.json

@@ -0,0 +1,10 @@
+{
+	"errors": {
+		"VALIDATION_ERROR": "الطلب غير صالح",
+		"UNAUTHORIZED": "يجب تسجيل الدخول",
+		"FORBIDDEN": "ليس لديك صلاحية للقيام بذلك",
+		"NOT_FOUND": "غير موجود",
+		"CONFLICT": "موجود مسبقاً",
+		"INTERNAL_ERROR": "حدث خطأ ما"
+	}
+}

package/templates/features/i18n/files/src/locales/en.json

@@ -0,0 +1,10 @@
+{
+	"errors": {
+		"VALIDATION_ERROR": "Invalid request",
+		"UNAUTHORIZED": "Authentication required",
+		"FORBIDDEN": "You do not have permission to do this",
+		"NOT_FOUND": "Not found",
+		"CONFLICT": "Already exists",
+		"INTERNAL_ERROR": "Something went wrong"
+	}
+}

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

@@ -0,0 +1,25 @@
+import { Cron } from "croner";
+import { withLock } from "#core/jobs/lock";
+import { logger } from "#core/logging/logger";
+import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { schedules } from "#generated/schedules";
+
+const jobs = schedules.map((schedule) => {
+	const log = logger.child({ schedule: schedule.name });
+	return new Cron(schedule.cron, { timezone: "UTC", protect: true, name: schedule.name }, async (self) => {
+		const tick = self.currentRun()?.toISOString() ?? new Date().toISOString();
+		const ran = await withLock(`schedule:${schedule.name}:${tick}`, schedule.lockTtlMs ?? 60_000, () =>
+			schedule.run({ logger: log }),
+		).catch((error: unknown) => {
+			log.error({ err: error }, "schedule failed");
+			return true;
+		});
+		if (!ran) log.debug("skipped: another process holds this tick");
+	});
+});
+
+onShutdown("cron", () => {
+	for (const job of jobs) job.stop();
+});
+handleSignals();
+logger.info({ schedules: schedules.map((s) => `${s.name} (${s.cron})`) }, "cron started");

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

@@ -0,0 +1,24 @@
+import { Worker } from "bullmq";
+import { env } from "#core/config/env";
+import { processJob } from "#core/jobs/process";
+import { QUEUE_NAME } from "#core/jobs/queue";
+import { redis } from "#core/jobs/redis";
+import { logger } from "#core/logging/logger";
+import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { consumers } from "#generated/consumers";
+
+const worker = new Worker(
+	QUEUE_NAME,
+	(job) =>
+		processJob(consumers, job.name, job.data, {
+			logger: logger.child({ jobId: job.id, topic: job.name }),
+			jobId: job.id ?? "",
+			attempt: job.attemptsMade + 1,
+		}),
+	{ connection: redis(), prefix: env.JOBS_PREFIX, concurrency: env.WORKER_CONCURRENCY },
+);
+
+worker.on("failed", (job, err) => logger.error({ err, jobId: job?.id, topic: job?.name }, "job failed"));
+onShutdown("worker", () => worker.close());
+handleSignals();
+logger.info({ topics: consumers.map((c) => c.topic) }, "worker started");

package/templates/features/jobs/files/src/core/jobs/commands/enqueue.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { defineCommand } from "#core/commands/define";
+import { enqueue } from "#core/jobs/queue";
+
+export default defineCommand({
+	name: "jobs:enqueue",
+	description: "Enqueue a job by topic with a JSON payload (for development and debugging)",
+	args: z.object({ topic: z.string().min(1), data: z.string().default("{}") }),
+	async run({ topic, data }, { logger }) {
+		const id = await enqueue(topic, JSON.parse(data) as unknown);
+		logger.info({ topic, id }, "job enqueued");
+	},
+});