@tatara/cli 0.6.0 → 0.8.0

package/dist/bin.mjs

@@ -190,6 +190,18 @@ function ignored(v, text) {
 	return new RegExp(`tatara-check-ignore\\s+${v.rule}:\\s*\\S`).test(previous);
 }
 //#endregion
+//#region src/project/ejected.ts
+/** Packages the app ejected (`tatara eject`); their code lives in src/ejected/<name>. */
+function ejectedPackages(config) {
+	return Object.keys(config.ejected ?? {});
+}
+/** Points `@tatara/<name>` and `@tatara/<name>/<entry>` imports at the app's ejected copy. */
+function pointAtEjected(text, names) {
+	if (names.length === 0) return text;
+	const pattern = new RegExp(`(["'])@tatara/(${names.join("|")})(?:/([\\w-]+))?\\1`, "g");
+	return text.replace(pattern, (_match, quote, name, entry) => `${quote}#ejected/${name}/${entry ?? "index"}${quote}`);
+}
+//#endregion
 //#region src/commands/sync.ts
 var sync_exports = /* @__PURE__ */ __exportAll({
 	specifier: () => specifier,
@@ -235,19 +247,21 @@ async function writeIfChanged(path, content, written) {
 }
 async function sync(project = loadProject()) {
 	const { root } = project;
+	const ejected = ejectedPackages(project.config);
+	const write = (path, content, out) => writeIfChanged(path, pointAtEjected(content, ejected), out);
 	const out = join(root, "src/generated");
 	await mkdir(out, { recursive: true });
 	const written = [];
 	const dirs = ["src/core/*", "src/modules/*"];
 	const routes = await find(root, dirs.map((d) => `${d}/routes/*.routes.ts`));
-	await writeIfChanged(join(out, "routes.ts"), listModule(routes, {
+	await write(join(out, "routes.ts"), listModule(routes, {
 		prefix: "routes",
 		typeImport: "import type { RouteDefinition } from \"#core/http/routes\";",
 		typeName: "RouteDefinition",
 		exportName: "routes"
 	}), written);
 	const commands = await find(root, dirs.map((d) => `${d}/commands/*.ts`));
-	await writeIfChanged(join(out, "commands.ts"), listModule(commands, {
+	await write(join(out, "commands.ts"), listModule(commands, {
 		prefix: "command",
 		typeImport: "import type { CommandDefinition } from \"@tatara/core\";",
 		typeName: "CommandDefinition",
@@ -255,16 +269,16 @@ async function sync(project = loadProject()) {
 	}), written);
 	if (project.has("jobs")) {
 		const consumers = await find(root, dirs.map((d) => `${d}/consumers/*.ts`));
-		await writeIfChanged(join(out, "consumers.ts"), listModule(consumers, {
+		await write(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, {
+		await write(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);
@@ -273,7 +287,7 @@ async function sync(project = loadProject()) {
 		const permissions = await find(root, ["src/modules/*/permissions/*.permissions.ts"]);
 		const imports = permissions.map((f) => `import ${identifier(f, "permissions")} from "${specifier(f)}";`);
 		const names = permissions.map((f) => identifier(f, "permissions"));
-		await writeIfChanged(join(out, "permissions.ts"), `${HEADER}import { authzPermissions, mergeCatalogs, type PermissionKeysOf } from "@tatara/authz";
+		await write(join(out, "permissions.ts"), `${HEADER}import { authzPermissions, mergeCatalogs, type PermissionKeysOf } from "@tatara/authz";
 ${imports.join("\n")}${imports.length ? "\n" : ""}
 export const catalog = mergeCatalogs(authzPermissions${names.map((n) => `, ${n}`).join("")});
 
@@ -283,7 +297,7 @@ export type PermissionKey =
 	}
 	if (project.config.database !== "none") {
 		const seeds = await find(root, dirs.map((d) => `${d}/db/seed.ts`));
-		await writeIfChanged(join(out, "seeds.ts"), listModule(seeds, {
+		await write(join(out, "seeds.ts"), listModule(seeds, {
 			prefix: "seed",
 			typeImport: "import type { SeedDefinition } from \"@tatara/db\";",
 			typeName: "SeedDefinition",
@@ -292,7 +306,7 @@ export type PermissionKey =
 	}
 	if (project.config.orm === "drizzle") {
 		const schemas = await find(root, dirs.map((d) => `${d}/db/*.schema.ts`));
-		await writeIfChanged(join(out, "schema.ts"), `${HEADER}${schemas.map((f) => `export * from "${specifier(f)}";`).join("\n")}\nexport {};\n`, written);
+		await write(join(out, "schema.ts"), `${HEADER}${schemas.map((f) => `export * from "${specifier(f)}";`).join("\n")}\nexport {};\n`, written);
 	}
 	if (project.config.orm === "prisma") {
 		const bin = join(root, "node_modules/.bin/prisma");
@@ -650,6 +664,121 @@ function printDoctor(checks) {
 	}
 }
 //#endregion
+//#region src/commands/eject.ts
+var EjectError = class extends Error {};
+const short = (name) => name.replace(/^@tatara\//, "");
+const full = (name) => `@tatara/${short(name)}`;
+const NOT_LIBRARIES = /* @__PURE__ */ new Set(["cli", "create-tatara"]);
+async function readJson(path) {
+	return JSON.parse(await readFile(path, "utf8"));
+}
+/**
+* Copies a package's source into src/ejected/<name>, points the app's imports at it and records
+* it in tatara.json. From then on the app owns that code and `tatara upgrade` leaves it alone.
+*/
+async function eject(project, name, opts = {}) {
+	const target = short(name);
+	if (NOT_LIBRARIES.has(target)) throw new EjectError(`${full(target)} is a tool, not a library`);
+	const appPkgPath = join(project.root, "package.json");
+	const appPkg = await readJson(appPkgPath);
+	const installed = Object.keys({
+		...appPkg.dependencies,
+		...appPkg.devDependencies
+	}).filter((dep) => dep.startsWith("@tatara/") && !NOT_LIBRARIES.has(short(dep))).map(short);
+	const already = ejectedPackages(project.config);
+	if (already.includes(target)) throw new EjectError(`${full(target)} is already ejected`);
+	if (!installed.includes(target)) throw new EjectError(`${full(target)} is not a dependency of this app`);
+	const manifests = /* @__PURE__ */ new Map();
+	for (const dep of installed) {
+		const path = join(project.root, "node_modules", full(dep), "package.json");
+		if (existsSync(path)) manifests.set(dep, await readJson(path));
+	}
+	const chain = [target];
+	for (let i = 0; i < chain.length; i++) for (const [dep, manifest] of manifests) {
+		if (chain.includes(dep)) continue;
+		if (full(chain[i]) in (manifest.peerDependencies ?? {})) chain.push(dep);
+	}
+	const dependents = chain.slice(1);
+	if (dependents.length > 0 && !opts.withDependents) throw new EjectError(`${dependents.map(full).join(", ")} depend on ${full(target)}. Eject them too with --with-dependents.`);
+	const report = {
+		ejected: chain,
+		copied: [],
+		rewritten: [],
+		added: []
+	};
+	const versions = {};
+	for (const dep of chain) {
+		const manifest = manifests.get(dep);
+		const source = join(project.root, "node_modules", full(dep), "src");
+		if (!manifest || !existsSync(source)) throw new EjectError(`${full(dep)} ships no source to eject; update it to a version that does, then run this again`);
+		versions[dep] = manifest.version;
+		const files = await glob(["**/*.ts"], {
+			cwd: source,
+			ignore: ["**/*.test.ts"]
+		});
+		for (const file of files) {
+			const to = `src/ejected/${dep}/${file}`;
+			await mkdir(dirname(join(project.root, to)), { recursive: true });
+			await cp(join(source, file), join(project.root, to));
+			report.copied.push(to);
+		}
+	}
+	const ejected = [...already, ...chain];
+	for (const file of await glob(["src/**/*.ts", "tests/**/*.ts"], { cwd: project.root })) {
+		const path = join(project.root, file);
+		const text = await readFile(path, "utf8");
+		const next = pointAtEjected(text, ejected);
+		if (next !== text) {
+			await writeFile(path, next);
+			if (!report.copied.includes(file)) report.rewritten.push(file);
+		}
+	}
+	const deps = { ...appPkg.dependencies };
+	const listed = new Set(Object.keys({
+		...appPkg.dependencies,
+		...appPkg.devDependencies
+	}));
+	for (const dep of chain) {
+		const manifest = manifests.get(dep);
+		for (const [peer, range] of Object.entries(manifest.peerDependencies ?? {})) {
+			if (listed.has(peer) || manifest.peerDependenciesMeta?.[peer]?.optional) continue;
+			if (peer.startsWith("@tatara/") && ejected.includes(short(peer))) continue;
+			deps[peer] = range;
+			listed.add(peer);
+			report.added.push(peer);
+		}
+	}
+	for (const dep of chain) delete deps[full(dep)];
+	const devDeps = { ...appPkg.devDependencies };
+	for (const dep of chain) delete devDeps[full(dep)];
+	const nextPkg = {
+		...appPkg,
+		imports: {
+			...appPkg.imports,
+			"#ejected/*": "./src/ejected/*.ts"
+		},
+		dependencies: Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a.localeCompare(b))),
+		devDependencies: devDeps
+	};
+	await writeFile(appPkgPath, `${JSON.stringify(nextPkg, null, "	")}\n`);
+	const configPath = join(project.root, "tatara.json");
+	const config = await readJson(configPath);
+	await writeFile(configPath, `${JSON.stringify({
+		...config,
+		ejected: {
+			...config.ejected,
+			...versions
+		}
+	}, null, "	")}\n`);
+	if (opts.formatFile) for (const file of [
+		...report.copied,
+		...report.rewritten,
+		"package.json",
+		"tatara.json"
+	]) await opts.formatFile(file, project);
+	return report;
+}
+//#endregion
 //#region src/paths.ts
 /** Package root: one level above both src/ (dev) and dist/ (published, bundled). */
 const PACKAGE_ROOT = resolve(import.meta.dirname, "..");
@@ -731,6 +860,7 @@ const jobs = {
 	kind: "addon",
 	label: "Jobs + cron (BullMQ)",
 	dependencies: [
+		"@tatara/jobs",
 		"bullmq",
 		"ioredis",
 		"croner"
@@ -803,8 +933,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 +1001,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 +1107,7 @@ const email = {
 	id: "email",
 	kind: "addon",
 	label: "Email",
-	dependencies: ["nodemailer"],
+	dependencies: ["@tatara/email", "nodemailer"],
 	devDependencies: ["@types/nodemailer"],
 	env: [
 		{
@@ -1033,6 +1167,7 @@ const i18n = {
 	id: "i18n",
 	kind: "addon",
 	label: "i18n",
+	dependencies: ["@tatara/i18n"],
 	env: [{
 		key: "DEFAULT_LANGUAGE",
 		schema: "z.enum([\"en\", \"ar\"]).default(\"en\")",
@@ -2574,7 +2709,7 @@ async function generate(project, request) {
 	for (const [rel, text] of rendered) {
 		const full = join(project.root, rel);
 		await mkdir(dirname(full), { recursive: true });
-		await writeFile(full, text);
+		await writeFile(full, pointAtEjected(text, ejectedPackages(project.config)));
 	}
 	if (!request.skipPostProcess) await postProcess(project, files);
 	return {
@@ -3216,6 +3351,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 +4064,8 @@ const CODEMODS = [
 	},
 	dbTesting,
 	authPackage,
-	authzPackage
+	authzPackage,
+	addonPackages
 ];
 //#endregion
 //#region src/upgrade/context.ts
@@ -3789,7 +4082,9 @@ function createContext(project, baseline, opts = {}) {
 	};
 	const abs = (path) => join(project.root, path);
 	let rendered;
-	const write = async (path, text) => {
+	const ejected = ejectedPackages(project.config);
+	const write = async (path, written) => {
+		const text = path.endsWith(".ts") ? pointAtEjected(written, ejected) : written;
 		if (!report.written.includes(path)) {
 			report.written.push(path);
 			const before = existsSync(abs(path)) ? await readFile(abs(path), "utf8") : void 0;
@@ -3850,6 +4145,11 @@ function createContext(project, baseline, opts = {}) {
 			return (await rendered).get(path);
 		},
 		async addDependency(name, range, { dev = false } = {}) {
+			if (ejected.includes(name.replace(/^@tatara\//, ""))) {
+				const note = `${name} is ejected; it was not added (its code is in src/ejected)`;
+				if (!report.notes.includes(note)) report.notes.push(note);
+				return;
+			}
 			const pkg = JSON.parse(await readFile(abs("package.json"), "utf8"));
 			const key = dev ? "devDependencies" : "dependencies";
 			pkg[key] = {
@@ -4018,6 +4318,17 @@ program.command("upgrade").description("Run this CLI version's codemods on the a
 	printUpgrade(await upgrade(project, { dryRun: flags.dryRun }), from, cliVersion());
 	if (!flags.dryRun && flags.verify !== false && !await verify(loadProject())) process.exitCode = 1;
 });
+program.command("eject <package>").description("Copy a @tatara/* package's source into src/ejected; the app owns it from then on").option("--with-dependents", "also eject installed @tatara/* packages that depend on it").action(async (name, flags) => {
+	const report = await eject(loadProject(), name, {
+		withDependents: flags.withDependents,
+		formatFile: biomeFormat
+	});
+	const names = report.ejected.map((n) => `@tatara/${n}`).join(", ");
+	console.log(pc.green(`ejected ${names} into src/ejected (${report.copied.length} files)`));
+	if (report.rewritten.length > 0) console.log(`  ${report.rewritten.length} files now import the ejected copy`);
+	if (report.added.length > 0) console.log(`  added dependencies: ${report.added.join(", ")}`);
+	console.log(`  run your package manager's install, then verify; tatara upgrade skips ${names} from now on`);
+});
 program.command("doctor").description("Check the toolchain, services, env and layout").option("--json", "machine-readable output").action(async (flags) => {
 	const checks = await doctor(loadProject());
 	if (flags.json) console.log(JSON.stringify(checks, null, 2));
@@ -4025,7 +4336,7 @@ program.command("doctor").description("Check the toolchain, services, env and la
 	if (checks.some((c) => !c.ok)) process.exitCode = 1;
 });
 program.parseAsync().catch((error) => {
-	if (error instanceof OptionsError || error instanceof NotATataraProject || error instanceof GeneratorError || error instanceof DbError) console.error(pc.red(error.message));
+	if (error instanceof OptionsError || error instanceof EjectError || error instanceof NotATataraProject || error instanceof GeneratorError || error instanceof DbError) console.error(pc.red(error.message));
 	else console.error(error);
 	process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.6.0",
+  "version": "0.8.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

@@ -31,11 +31,15 @@
   "@aws-sdk/s3-request-presigner": "3.1152.0",
   "nodemailer": "10.1.1",
   "@types/nodemailer": "8.0.2",
-  "@tatara/core": "0.1.0",
-  "@tatara/http": "0.1.0",
-  "@tatara/db": "0.1.0",
-  "@tatara/testing": "0.1.0",
-  "@tatara/auth": "0.1.0",
-  "@tatara/keycloak": "0.1.0",
-  "@tatara/authz": "0.1.0"
+  "@tatara/core": "0.1.1",
+  "@tatara/http": "0.1.1",
+  "@tatara/db": "0.1.1",
+  "@tatara/testing": "0.1.1",
+  "@tatara/auth": "0.1.1",
+  "@tatara/keycloak": "0.1.1",
+  "@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;
-}