@tatara/cli 0.6.0 → 0.7.0

package/dist/bin.mjs

@@ -257,14 +257,14 @@ async function sync(project = loadProject()) {
 		const consumers = await find(root, dirs.map((d) => `${d}/consumers/*.ts`));
 		await writeIfChanged(join(out, "consumers.ts"), listModule(consumers, {
 			prefix: "consumer",
-			typeImport: "import type { ConsumerDefinition } from \"#core/jobs/define\";",
+			typeImport: "import type { ConsumerDefinition } from \"@tatara/jobs\";",
 			typeName: "ConsumerDefinition",
 			exportName: "consumers"
 		}), written);
 		const schedules = await find(root, dirs.map((d) => `${d}/schedules/*.ts`));
 		await writeIfChanged(join(out, "schedules.ts"), listModule(schedules, {
 			prefix: "schedule",
-			typeImport: "import type { ScheduleDefinition } from \"#core/jobs/define\";",
+			typeImport: "import type { ScheduleDefinition } from \"@tatara/jobs\";",
 			typeName: "ScheduleDefinition",
 			exportName: "schedules"
 		}), written);
@@ -731,6 +731,7 @@ const jobs = {
 	kind: "addon",
 	label: "Jobs + cron (BullMQ)",
 	dependencies: [
+		"@tatara/jobs",
 		"bullmq",
 		"ioredis",
 		"croner"
@@ -803,8 +804,8 @@ const jobs = {
 			slot: "sections",
 			content: `## Jobs and schedules
 
-- Background work: \`enqueue(topic, payload)\` from \`#core/jobs/queue\`; a module handles it in
-  \`consumers/<name>.ts\` (\`defineConsumer({ topic, schema, handle })\`). Payloads are validated by the
+- Background work: \`enqueue(topic, payload)\` from \`#core/jobs/index\`; a module handles it in
+  \`consumers/<name>.ts\` (\`defineConsumer({ topic, schema, handle })\` from \`@tatara/jobs\`). Payloads are validated by the
   consumer's zod schema. Handlers must be idempotent: jobs retry.
 - Recurring work: \`schedules/<name>.ts\` (\`defineSchedule({ name, cron, run })\`). A Redis lock makes
   each tick run once across every cron process.
@@ -871,7 +872,11 @@ const storage = {
 	id: "storage",
 	kind: "addon",
 	label: "File storage",
-	dependencies: ["@aws-sdk/client-s3", "@aws-sdk/s3-request-presigner"],
+	dependencies: [
+		"@tatara/storage",
+		"@aws-sdk/client-s3",
+		"@aws-sdk/s3-request-presigner"
+	],
 	env: [
 		{
 			key: "STORAGE_DRIVER",
@@ -973,7 +978,7 @@ const email = {
 	id: "email",
 	kind: "addon",
 	label: "Email",
-	dependencies: ["nodemailer"],
+	dependencies: ["@tatara/email", "nodemailer"],
 	devDependencies: ["@types/nodemailer"],
 	env: [
 		{
@@ -1033,6 +1038,7 @@ const i18n = {
 	id: "i18n",
 	kind: "addon",
 	label: "i18n",
+	dependencies: ["@tatara/i18n"],
 	env: [{
 		key: "DEFAULT_LANGUAGE",
 		schema: "z.enum([\"en\", \"ar\"]).default(\"en\")",
@@ -3216,6 +3222,163 @@ function importsOf(text, specifier) {
 	return found ? names : null;
 }
 //#endregion
+//#region src/upgrade/codemods/groups.ts
+async function read$4(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+function sourceFiles(ctx) {
+	return glob(["src/**/*.ts", "tests/**/*.ts"], {
+		cwd: ctx.project.root,
+		ignore: ["src/generated/**"]
+	});
+}
+/** Why the group can't move ([] when it can). Changes nothing. */
+async function blockersOf$1(ctx, group, sources) {
+	const blockers = [];
+	for (const path of [...group.regenerate, ...group.remove]) {
+		const text = await read$4(ctx, path);
+		if (text === void 0) continue;
+		if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
+	}
+	const own = /* @__PURE__ */ new Set([...group.regenerate, ...group.remove]);
+	for (const path of sources) {
+		if (own.has(path)) continue;
+		const text = await ctx.read(path);
+		for (const rewrite of group.rewrites) {
+			const names = importsOf(text, rewrite.from);
+			if (!names) continue;
+			const allowed = rewrite.names;
+			const missing = names.filter((n) => n === "*" || allowed !== void 0 && !allowed.includes(n));
+			if (missing.length > 0) blockers.push(`${path} imports ${missing.join(", ")} from ${rewrite.from}`);
+		}
+	}
+	return blockers;
+}
+async function applyGroup(ctx, group) {
+	for (const path of group.regenerate) {
+		const next = await ctx.renderCurrent(path);
+		if (next !== void 0) await ctx.write(path, next);
+	}
+	for (const path of group.remove) await ctx.removeIfUnchanged(path);
+	for (const rewrite of group.rewrites) await ctx.rewriteImports(rewrite.from, rewrite.to);
+}
+//#endregion
+//#region src/upgrade/codemods/addon-packages.ts
+const groups$1 = {
+	storage: {
+		name: "storage",
+		regenerate: [
+			"src/core/storage/index.ts",
+			"src/core/storage/commands/check.ts",
+			"src/core/storage/tests/storage.test.ts"
+		],
+		remove: [
+			"storage.ts",
+			"local.ts",
+			"s3.ts"
+		].map((f) => `src/core/storage/${f}`),
+		rewrites: [
+			{
+				from: "#core/storage/storage",
+				to: "@tatara/storage"
+			},
+			{
+				from: "#core/storage/local",
+				to: "@tatara/storage",
+				names: []
+			},
+			{
+				from: "#core/storage/s3",
+				to: "#core/storage/index",
+				names: ["s3"]
+			}
+		]
+	},
+	email: {
+		name: "email",
+		regenerate: ["src/core/email/send.ts"],
+		remove: [],
+		rewrites: []
+	},
+	i18n: {
+		name: "i18n",
+		regenerate: ["src/core/i18n/index.ts"],
+		remove: [],
+		rewrites: []
+	},
+	jobs: {
+		name: "jobs",
+		regenerate: [
+			"src/core/jobs/index.ts",
+			"src/apps/worker/index.ts",
+			"src/apps/cron/index.ts",
+			"src/core/jobs/commands/enqueue.ts",
+			"src/modules/example/tests/jobs.test.ts"
+		],
+		remove: [
+			"define.ts",
+			"process.ts",
+			"lock.ts",
+			"redis.ts",
+			"queue.ts"
+		].map((f) => `src/core/jobs/${f}`),
+		rewrites: [
+			{
+				from: "#core/jobs/define",
+				to: "@tatara/jobs"
+			},
+			{
+				from: "#core/jobs/process",
+				to: "@tatara/jobs"
+			},
+			{
+				from: "#core/jobs/queue",
+				to: "#core/jobs/index",
+				names: ["enqueue", "QUEUE_NAME"]
+			},
+			{
+				from: "#core/jobs/redis",
+				to: "#core/jobs/index",
+				names: ["redis"]
+			},
+			{
+				from: "#core/jobs/lock",
+				to: "@tatara/jobs",
+				names: []
+			}
+		]
+	}
+};
+/** Written even though the app has no copy yet; other files are only replaced when present. */
+const NEW = /* @__PURE__ */ new Set(["src/core/jobs/index.ts"]);
+const addonPackages = {
+	version: "0.7.0",
+	id: "addon-packages",
+	description: "Use @tatara/storage, @tatara/email, @tatara/i18n and @tatara/jobs",
+	async run(ctx) {
+		const addons = ctx.project.config.addons;
+		const sources = await sourceFiles(ctx);
+		const ready = [];
+		for (const [addon, group] of Object.entries(groups$1)) {
+			if (!addons.includes(addon)) continue;
+			await ctx.addDependency(`@tatara/${addon}`, versionOf(`@tatara/${addon}`));
+			const blockers = await blockersOf$1(ctx, group, sources);
+			if (blockers.length > 0) {
+				ctx.report.notes.push(`${addon} was not moved onto @tatara/${addon}: ${blockers.join("; ")}. Compare with a newly generated app and move it by hand.`);
+				if (!ctx.report.blocked.includes("addon-packages")) ctx.report.blocked.push("addon-packages");
+				continue;
+			}
+			const present = [];
+			for (const path of group.regenerate) if (await ctx.read(path).then(() => true, () => false) || NEW.has(path)) present.push(path);
+			ready.push({
+				...group,
+				regenerate: present
+			});
+		}
+		for (const group of ready) await applyGroup(ctx, group);
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/auth-package.ts
 const AUTH = "@tatara/auth";
 const KEYCLOAK = "@tatara/keycloak";
@@ -3772,7 +3935,8 @@ const CODEMODS = [
 	},
 	dbTesting,
 	authPackage,
-	authzPackage
+	authzPackage,
+	addonPackages
 ];
 //#endregion
 //#region src/upgrade/context.ts

package/package.json

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

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

@@ -1,22 +1,13 @@
-import { createTransport, type Transporter } from "nodemailer";
+import { createMailer } from "@tatara/email";
 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;
+export type { EmailMessage } from "@tatara/email";
 
 /** 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 });
-}
+export const { send: sendEmail } = createMailer({
+	driver: env.EMAIL_DRIVER,
+	smtpUrl: env.SMTP_URL,
+	from: env.EMAIL_FROM,
+	logger,
+});

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

@@ -1,41 +1,11 @@
-import { createMiddleware } from "hono/factory";
+import { createI18n } from "@tatara/i18n";
 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 i18n = createI18n({ dictionaries: { en, ar }, defaultLanguage: env.DEFAULT_LANGUAGE });
 
-const dictionaries: Record<string, Dictionary> = { en, ar };
+export const SUPPORTED_LANGUAGES = i18n.languages;
 
-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();
-});
+/** `t(language, "errors.NOT_FOUND")`, and the middleware that sets `c.var.language`. */
+export const { t, detectLanguage } = i18n;

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

@@ -1,25 +1,8 @@
-import { Cron } from "croner";
-import { withLock } from "#core/jobs/lock";
+import { handleSignals } from "@tatara/core";
+import { startCron } from "@tatara/jobs";
+import { redis } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
-import { handleSignals, onShutdown } from "@tatara/core";
 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();
-});
+startCron({ schedules, redis, logger });
 handleSignals(logger);
-logger.info({ schedules: schedules.map((s) => `${s.name} (${s.cron})`) }, "cron started");

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

@@ -1,24 +1,16 @@
-import { Worker } from "bullmq";
+import { handleSignals } from "@tatara/core";
+import { startWorker } from "@tatara/jobs";
 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 { QUEUE_NAME, redis } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
-import { handleSignals, onShutdown } from "@tatara/core";
 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());
+startWorker({
+	queue: QUEUE_NAME,
+	prefix: env.JOBS_PREFIX,
+	redis: redis(),
+	concurrency: env.WORKER_CONCURRENCY,
+	consumers,
+	logger,
+});
 handleSignals(logger);
-logger.info({ topics: consumers.map((c) => c.topic) }, "worker started");

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { defineCommand } from "@tatara/core";
-import { enqueue } from "#core/jobs/queue";
+import { enqueue } from "#core/jobs/index";
 
 export default defineCommand({
 	name: "jobs:enqueue",

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

@@ -0,0 +1,10 @@
+import { createQueue, lazyRedis } from "@tatara/jobs";
+import { env } from "#core/config/env";
+
+export const QUEUE_NAME = "__APP_NAME__-jobs";
+
+/** The shared Redis connection, 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 });

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineConsumer } from "#core/jobs/define";
+import { defineConsumer } from "@tatara/jobs";
 
 export default defineConsumer({
 	topic: "example.send-welcome",

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

@@ -1,4 +1,4 @@
-import { defineSchedule } from "#core/jobs/define";
+import { defineSchedule } from "@tatara/jobs";
 
 export default defineSchedule({
 	name: "example.heartbeat",

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
-import { withLock } from "#core/jobs/lock";
-import { processJob } from "#core/jobs/process";
+import { processJob, withLock } from "@tatara/jobs";
+import { redis } from "#core/jobs/index";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 
@@ -20,8 +20,8 @@ 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(key, 5000, async () => {
-			inner = await withLock(key, 5000, async () => {});
+		const outer = await withLock(redis(), key, 5000, async () => {
+			inner = await withLock(redis(), key, 5000, async () => {});
 		});
 		expect(outer).toBe(true);
 		expect(inner).toBe(false);

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

@@ -1,13 +1,13 @@
 import { defineCommand } from "@tatara/core";
 import { env } from "#core/config/env";
-import { storage } from "#core/storage/index";
-import { ensureBucket } from "#core/storage/s3";
+import { ensureBucket } from "@tatara/storage/s3";
+import { s3, storage } from "#core/storage/index";
 
 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");
+		if (env.STORAGE_DRIVER === "s3" && (await ensureBucket(s3, env.S3_BUCKET))) 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);

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

@@ -1,8 +1,22 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { localStorage, type Storage } from "@tatara/storage";
+import { s3Storage } from "@tatara/storage/s3";
 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 type { Storage } from "@tatara/storage";
 
-export const storage: Storage = env.STORAGE_DRIVER === "s3" ? s3Storage() : localStorage();
+export const s3 = new S3Client({
+	region: env.S3_REGION,
+	...(env.S3_ENDPOINT ? { endpoint: env.S3_ENDPOINT } : {}),
+	forcePathStyle: env.S3_FORCE_PATH_STYLE,
+	...(env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY
+		? { credentials: { accessKeyId: env.S3_ACCESS_KEY_ID, secretAccessKey: env.S3_SECRET_ACCESS_KEY } }
+		: {}),
+});
+
+/** Object storage for modules; pick the driver with STORAGE_DRIVER. */
+export const storage: Storage =
+	env.STORAGE_DRIVER === "s3"
+		? // local development: the bucket is created on first write
+			s3Storage({ client: s3, bucket: env.S3_BUCKET, createBucket: env.NODE_ENV === "development" })
+		: localStorage(env.STORAGE_LOCAL_DIR);

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

@@ -2,7 +2,7 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { localStorage } from "#core/storage/local";
+import { localStorage } from "@tatara/storage";
 
 describe("local storage", () => {
 	it("round-trips an object", async () => {

package/templates/generators/consumer/files/src/modules/__moduleKebab__/consumers/__nameKebab__.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineConsumer } from "#core/jobs/define";
+import { defineConsumer } from "@tatara/jobs";
 
 export const __nameCamel__Payload = z.object({ id: z.string().min(1) });
 

package/templates/generators/consumer/files/src/modules/__moduleKebab__/tests/__nameKebab__.consumer.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { processJob } from "#core/jobs/process";
+import { processJob } from "@tatara/jobs";
 import { logger } from "#core/logging/logger";
 import { consumers } from "#generated/consumers";
 

package/templates/generators/schedule/files/src/modules/__moduleKebab__/schedules/__nameKebab__.ts

@@ -1,4 +1,4 @@
-import { defineSchedule } from "#core/jobs/define";
+import { defineSchedule } from "@tatara/jobs";
 
 export default defineSchedule({
 	name: "__moduleKebab__.__nameKebab__",

package/templates/versions.json

@@ -37,5 +37,9 @@
   "@tatara/testing": "0.1.0",
   "@tatara/auth": "0.1.0",
   "@tatara/keycloak": "0.1.0",
-  "@tatara/authz": "0.1.0"
+  "@tatara/authz": "0.1.0",
+  "@tatara/storage": "0.1.0",
+  "@tatara/email": "0.1.0",
+  "@tatara/i18n": "0.1.0",
+  "@tatara/jobs": "0.1.0"
 }

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

@@ -1,37 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,29 +0,0 @@
-import { type JobsOptions, Queue } from "bullmq";
-import { env } from "#core/config/env";
-import { redis } from "#core/jobs/redis";
-import { onShutdown } from "@tatara/core";
-
-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

@@ -1,17 +0,0 @@
-import { Redis } from "ioredis";
-import { env } from "#core/config/env";
-import { onShutdown } from "@tatara/core";
-
-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/storage/files/src/core/storage/local.ts

@@ -1,34 +0,0 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { dirname, resolve, sep } from "node:path";
-import { env } from "#core/config/env";
-import { assertKey, type Storage } from "#core/storage/storage";
-
-/** Files on disk; for development and tests. */
-export function localStorage(root = env.STORAGE_LOCAL_DIR): Storage {
-	const base = resolve(root);
-	const path = (key: string) => {
-		const full = resolve(base, assertKey(key));
-		if (!full.startsWith(base + sep)) throw new Error(`Invalid storage key "${key}"`);
-		return full;
-	};
-	return {
-		async put(key, body) {
-			await mkdir(dirname(path(key)), { recursive: true });
-			await writeFile(path(key), body);
-		},
-		async get(key) {
-			try {
-				return new Uint8Array(await readFile(path(key)));
-			} catch (error) {
-				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
-				throw error;
-			}
-		},
-		async delete(key) {
-			await rm(path(key), { force: true });
-		},
-		async url(key) {
-			return `file://${path(key)}`;
-		},
-	};
-}

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

@@ -1,66 +0,0 @@
-import {
-	CreateBucketCommand,
-	DeleteObjectCommand,
-	GetObjectCommand,
-	HeadBucketCommand,
-	NoSuchKey,
-	PutObjectCommand,
-	S3Client,
-} from "@aws-sdk/client-s3";
-import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
-import { env } from "#core/config/env";
-import { assertKey, type Storage } from "#core/storage/storage";
-
-export const s3 = new S3Client({
-	region: env.S3_REGION,
-	...(env.S3_ENDPOINT ? { endpoint: env.S3_ENDPOINT } : {}),
-	forcePathStyle: env.S3_FORCE_PATH_STYLE,
-	...(env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY
-		? { credentials: { accessKeyId: env.S3_ACCESS_KEY_ID, secretAccessKey: env.S3_SECRET_ACCESS_KEY } }
-		: {}),
-});
-
-/** Any S3-compatible store (AWS S3, R2, RustFS locally). */
-export function s3Storage(bucket = env.S3_BUCKET): Storage {
-	let bucketReady: Promise<boolean> | undefined;
-	return {
-		async put(key, body, contentType) {
-			// local development: create the bucket on first write
-			if (env.NODE_ENV === "development") {
-				bucketReady ??= ensureBucket(bucket);
-				await bucketReady;
-			}
-			await s3.send(
-				new PutObjectCommand({ Bucket: bucket, Key: assertKey(key), Body: body, ContentType: contentType }),
-			);
-		},
-		async get(key) {
-			try {
-				const res = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: assertKey(key) }));
-				return res.Body ? await res.Body.transformToByteArray() : null;
-			} catch (error) {
-				if (error instanceof NoSuchKey) return null;
-				throw error;
-			}
-		},
-		async delete(key) {
-			await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: assertKey(key) }));
-		},
-		async url(key, expiresInSeconds = 900) {
-			return getSignedUrl(s3, new GetObjectCommand({ Bucket: bucket, Key: assertKey(key) }), {
-				expiresIn: expiresInSeconds,
-			});
-		},
-	};
-}
-
-/** Creates the bucket when it does not exist (local development). */
-export async function ensureBucket(bucket = env.S3_BUCKET): Promise<boolean> {
-	try {
-		await s3.send(new HeadBucketCommand({ Bucket: bucket }));
-		return false;
-	} catch {
-		await s3.send(new CreateBucketCommand({ Bucket: bucket }));
-		return true;
-	}
-}

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

@@ -1,21 +0,0 @@
-/** Object storage used by modules; pick the driver with STORAGE_DRIVER. */
-export interface Storage {
-	put(key: string, body: Uint8Array | string, contentType?: string): Promise<void>;
-	get(key: string): Promise<Uint8Array | null>;
-	delete(key: string): Promise<void>;
-	/** a URL clients can fetch the object from (signed for S3) */
-	url(key: string, expiresInSeconds?: number): Promise<string>;
-}
-
-/** Keys are relative, forward-slash paths without "..", backslashes, NUL bytes or drive prefixes. */
-export function assertKey(key: string): string {
-	const invalid =
-		!key ||
-		key.startsWith("/") ||
-		key.includes("\\") ||
-		key.includes("\0") ||
-		/^[A-Za-z]:/.test(key) ||
-		key.split("/").some((segment) => segment === ".." || segment === ".");
-	if (invalid) throw new Error(`Invalid storage key "${key}"`);
-	return key;
-}