@tatara/cli 0.1.2 → 0.2.0

package/dist/bin.mjs

@@ -2,15 +2,16 @@
 import { Command } from "commander";
 import pc from "picocolors";
 import { spawn } from "node:child_process";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { glob } from "tinyglobby";
-import { existsSync, readFileSync, readdirSync, watch } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, watch } from "node:fs";
 import { x } from "tinyexec";
 import { parseEnv } from "node:util";
 import * as p from "@clack/prompts";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { stringify } from "yaml";
+import { homedir, tmpdir } from "node:os";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -248,7 +249,7 @@ async function sync(project = loadProject()) {
 	const commands = await find(root, dirs.map((d) => `${d}/commands/*.ts`));
 	await writeIfChanged(join(out, "commands.ts"), listModule(commands, {
 		prefix: "command",
-		typeImport: "import type { CommandDefinition } from \"#core/commands/define\";",
+		typeImport: "import type { CommandDefinition } from \"@tatara/core\";",
 		typeName: "CommandDefinition",
 		exportName: "commands"
 	}), written);
@@ -663,11 +664,19 @@ function templateVersions() {
 	versions ??= JSON.parse(readFileSync(resolve(TEMPLATES_DIR, "versions.json"), "utf8"));
 	return versions;
 }
+/** `TATARA_PACKAGE_SPECS='{"@tatara/core":"file:…"}'` installs local builds (e2e, bench). */
+function packageSpecOverride(pkg) {
+	const raw = process.env.TATARA_PACKAGE_SPECS;
+	if (!raw) return void 0;
+	return JSON.parse(raw)[pkg];
+}
 function versionOf(pkg) {
+	const override = packageSpecOverride(pkg);
+	if (override) return override;
 	if (pkg === "@tatara/cli") return process.env.TATARA_CLI_SPEC ?? `^${cliVersion()}`;
 	const version = templateVersions()[pkg];
 	if (!version) throw new Error(`templates/versions.json has no version for "${pkg}"`);
-	return version;
+	return pkg.startsWith("@tatara/") ? `^${version}` : version;
 }
 const authz = {
 	id: "authz",
@@ -1630,6 +1639,7 @@ const base = {
 	kind: "base",
 	label: "Hono API",
 	dependencies: [
+		"@tatara/core",
 		"hono",
 		"@hono/node-server",
 		"@hono/zod-openapi",
@@ -2172,14 +2182,11 @@ function envFile(vars, kind) {
 }
 function envModule(vars) {
 	return `import { createEnv } from "@t3-oss/env-core";
+import { createLocalDefault } from "@tatara/core";
 import { z } from "zod";
 
-const production = process.env.NODE_ENV === "production";
-
 /** A default for local development; production must set the value explicitly. */
-function localDefault<T extends z.ZodType>(schema: T, value: z.input<T>): T {
-	return production ? schema : (schema.default(value as never) as unknown as T);
-}
+const localDefault = createLocalDefault(process.env.NODE_ENV === "production");
 
 /** The only place that reads process.env. Add new variables here and to .env.example. */
 export const env = createEnv({
@@ -2259,8 +2266,9 @@ function composeFile(options, features, tokenValues) {
 function pnpmWorkspace(features) {
 	const builds = [...new Set(features.flatMap((f) => f.allowBuilds ?? []))].sort();
 	const lines = ["# Packages allowed to run install scripts."];
-	if (builds.length === 0) return `${lines.join("\n")}\nallowBuilds: {}\n`;
-	lines.push("allowBuilds:", ...builds.map((b) => `  "${b}": true`));
+	if (builds.length === 0) lines.push("allowBuilds: {}");
+	else lines.push("allowBuilds:", ...builds.map((b) => `  "${b}": true`));
+	lines.push("# tatara's own packages are installed as soon as they are released", "minimumReleaseAgeExclude:", "  - \"@tatara/*\"");
 	return `${lines.join("\n")}\n`;
 }
 /** Folds applicable variants into each feature so later steps see one flat definition. */
@@ -2306,7 +2314,7 @@ async function renderApp(options, generate = {}) {
 	if (compose) files.set("compose.yaml", compose);
 	if (options.packageManager === "pnpm") files.set("pnpm-workspace.yaml", pnpmWorkspace(features));
 	const config = {
-		$schema: "https://raw.githubusercontent.com/mohammed-bageri/tatara/main/schema/tatara.json",
+		$schema: "https://raw.githubusercontent.com/mohammed-bageri/tatara-cli/main/schema/tatara.json",
 		version: cliVersion(),
 		name: options.name,
 		orm: options.orm,
@@ -2331,6 +2339,30 @@ function devEnvFromExample(options) {
 	return envFile(dedupeEnv(effectiveFeatures(options), tokens(options)), "dev");
 }
 //#endregion
+//#region src/project/hashes.ts
+/** Framework files a package can replace; `tatara upgrade` tracks these. */
+const TRACKED_PATTERNS = [
+	"src/core/**",
+	"src/apps/**",
+	"tests/helpers/**",
+	"tests/setup.ts",
+	"tests/global-setup.ts"
+];
+function hashContent(text) {
+	return `sha256-${createHash("sha256").update(text).digest("base64")}`;
+}
+/** Relative POSIX path → content hash, for every tracked file under `root`. */
+async function hashTrackedFiles(root) {
+	const paths = await glob([...TRACKED_PATTERNS], {
+		cwd: root,
+		dot: true,
+		onlyFiles: true
+	});
+	const out = {};
+	for (const path of paths.sort()) out[path.replaceAll("\\", "/")] = hashContent(await readFile(join(root, path), "utf8"));
+	return out;
+}
+//#endregion
 //#region src/engine/names.ts
 function words(input) {
 	return input.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[^A-Za-z0-9]+/g, " ").trim().toLowerCase().split(/\s+/).filter(Boolean);
@@ -2875,6 +2907,20 @@ async function newApp(dir, rawFlags) {
 		});
 		if (format.exitCode !== 0) console.warn(pc.yellow(`Formatting reported problems (please report this as a tatara bug):\n${format.stdout}`));
 	}
+	await recordGenerated(root);
+	if (flags.install !== false) {
+		const [exec, ...execArgs] = pm.exec.split(" ");
+		await x(exec ?? "npx", [
+			...execArgs,
+			"biome",
+			"check",
+			"--write",
+			"tatara.json"
+		], {
+			nodeOptions: { cwd: root },
+			throwOnError: false
+		});
+	}
 	if (flags.git !== false) {
 		if ((await x("git", [
 			"init",
@@ -2909,6 +2955,15 @@ async function newApp(dir, rawFlags) {
 	else console.log(`Created ${root}\nNext:\n  ${next.join("\n  ")}`);
 	return root;
 }
+async function recordGenerated(root) {
+	const path = join(root, "tatara.json");
+	const config = JSON.parse(await readFile(path, "utf8"));
+	config.generated = {
+		cli: cliVersion(),
+		files: await hashTrackedFiles(root)
+	};
+	await writeFile(path, `${JSON.stringify(config, null, "	")}\n`);
+}
 //#endregion
 //#region src/commands/routes.ts
 /** Reads every app's OpenAPI document in-process and lists its routes. */
@@ -3016,6 +3071,391 @@ server.on("exit", () => process.exit(0));
 	});
 }
 //#endregion
+//#region src/upgrade/baseline.ts
+const CACHE_DIR = join(process.env.XDG_CACHE_HOME ?? join(homedir(), ".cache"), "tatara", "baselines");
+/** `major.minor.patch` comparison; prereleases are not considered. */
+function compareVersions(a, b) {
+	const pa = a.split(".").map(Number);
+	const pb = b.split(".").map(Number);
+	for (let i = 0; i < 3; i++) {
+		const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+		if (d !== 0) return d;
+	}
+	return 0;
+}
+/** Published @tatara/cli versions, without prereleases such as 0.0.0-stage. */
+async function releasedVersions() {
+	const res = await fetch("https://registry.npmjs.org/@tatara%2fcli");
+	if (!res.ok) throw new Error(`npm registry answered ${res.status}`);
+	const body = await res.json();
+	return Object.keys(body.versions ?? {}).filter((v) => /^\d+\.\d+\.\d+$/.test(v)).sort(compareVersions);
+}
+function newFlags(config) {
+	return [
+		"--orm",
+		config.orm,
+		"--db",
+		config.database,
+		"--auth",
+		config.auth,
+		...config.authMethods.length ? ["--auth-methods", config.authMethods.join(",")] : [],
+		...config.addons.length ? ["--addons", config.addons.join(",")] : [],
+		"--pm",
+		config.packageManager
+	];
+}
+/** Templates contain the app name, so the release must render an app with the same name. */
+function renderTarget(base, config) {
+	return join(base, config.name);
+}
+/** What `@tatara/cli@<version> new` writes for these options (not installed, not formatted). */
+async function renderRelease(version, config) {
+	const dir = renderTarget(await mkdtemp(join(tmpdir(), `tatara-${version}-`)), config);
+	const res = await x("npx", [
+		"--yes",
+		"--package",
+		`@tatara/cli@${version}`,
+		"--",
+		"tatara",
+		"new",
+		dir,
+		...newFlags(config),
+		"--yes",
+		"--no-install",
+		"--no-git"
+	], {
+		throwOnError: false,
+		nodeOptions: {
+			cwd: dirname(dir),
+			env: {
+				...process.env,
+				TATARA_CLI_SPEC: void 0
+			}
+		}
+	});
+	if (res.exitCode !== 0) throw new Error(`@tatara/cli@${version} could not generate these options: ${res.stderr.slice(-300)}`);
+	return dir;
+}
+function digest(text) {
+	return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+function baselineCacheKey(version, config, biome) {
+	const inputs = JSON.stringify({
+		name: config.name,
+		flags: newFlags(config)
+	});
+	const format = biome ? `-fmt-${digest(`${biome.version}\n${biome.config}`)}` : "";
+	return `${version}-${digest(inputs)}${format}`;
+}
+async function appBiome(appRoot) {
+	const configFile = join(appRoot, "biome.json");
+	const pkgFile = join(appRoot, "node_modules", "@biomejs", "biome", "package.json");
+	if (!existsSync(configFile) || !existsSync(pkgFile)) return void 0;
+	const { version } = JSON.parse(await readFile(pkgFile, "utf8"));
+	return {
+		config: await readFile(configFile, "utf8"),
+		version
+	};
+}
+/**
+* Hashes of the tracked files `@tatara/cli@<version>` generates for `config`. With `formatWith`
+* (an app root with Biome installed), files are first formatted with that app's Biome and
+* biome.json, so formatting differences don't count as changes. Cached on disk.
+*/
+async function releaseBaseline(version, config, opts = {}) {
+	const biome = opts.formatWith ? await appBiome(opts.formatWith) : void 0;
+	const cacheFile = join(CACHE_DIR, `${baselineCacheKey(version, config, biome)}.json`);
+	if (existsSync(cacheFile)) return JSON.parse(await readFile(cacheFile, "utf8"));
+	const dir = await renderRelease(version, config);
+	if (biome && opts.formatWith) {
+		await cp(join(opts.formatWith, "biome.json"), join(dir, "biome.json"));
+		const bin = join(opts.formatWith, "node_modules", ".bin", "biome");
+		const res = await x(bin, [
+			"check",
+			"--write",
+			"."
+		], {
+			throwOnError: false,
+			nodeOptions: { cwd: dir }
+		});
+		if (res.exitCode !== 0 && res.exitCode !== 1) throw new Error(`could not format the ${version} baseline with the app's Biome: ${res.stderr.slice(-300)}`);
+	}
+	const hashes = await hashTrackedFiles(dir);
+	mkdirSync(CACHE_DIR, { recursive: true });
+	await writeFile(cacheFile, JSON.stringify(hashes));
+	return hashes;
+}
+function createBaseline(project, deps) {
+	const resolved = {
+		releasedVersions,
+		releaseBaseline: (version, config) => releaseBaseline(version, config, { formatWith: project.root }),
+		cliVersion: cliVersion(),
+		...deps
+	};
+	const recorded = project.config.generated?.files ?? {};
+	let releases;
+	async function loadReleases() {
+		const from = project.config.version;
+		const versions = (await resolved.releasedVersions()).filter((v) => compareVersions(v, from) >= 0 && compareVersions(v, resolved.cliVersion) <= 0);
+		const out = [];
+		for (const v of versions) out.push(await resolved.releaseBaseline(v, project.config).catch(() => ({})));
+		return out;
+	}
+	return { async isUnchanged(path, content) {
+		const hash = hashContent(content);
+		if (recorded[path] === hash) return true;
+		releases ??= loadReleases();
+		return (await releases).some((files) => files[path] === hash);
+	} };
+}
+//#endregion
+//#region src/upgrade/codemods/core-package.ts
+const CORE = "@tatara/core";
+/** Files @tatara/core replaces, with the import specifier apps used for each. */
+const MOVED = {
+	"src/core/commands/define.ts": "#core/commands/define",
+	"src/core/commands/runner.ts": "#core/commands/runner",
+	"src/core/process/lifecycle.ts": "#core/process/lifecycle",
+	"src/core/http/health.ts": "#core/http/health"
+};
+const ENV = "src/core/config/env.ts";
+const LOGGER = "src/core/logging/logger.ts";
+const CLI_ENTRY = "src/apps/cli/index.ts";
+const SIGNAL_FILES = [
+	"src/core/http/server.ts",
+	"src/apps/worker/index.ts",
+	"src/apps/cron/index.ts"
+];
+const LOGGER_IMPORT = "import { logger } from \"#core/logging/logger\";";
+const OLD_HELPER = /const production = process\.env\.NODE_ENV === "production";\n\n(\/\*\*[^\n]*\*\/\n)?function localDefault<T extends z\.ZodType>\(schema: T, value: z\.input<T>\): T \{\n\treturn production \? schema : \(schema\.default\(value as never\) as unknown as T\);\n\}\n/;
+async function exists(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+/** Adds `line` after the last import, unless the file already has it. */
+function withImport(text, line) {
+	if (text.includes(line)) return text;
+	const last = [...text.matchAll(/^import .*;$/gm)].at(-1);
+	if (!last || last.index === void 0) return `${line}\n${text}`;
+	const end = last.index + last[0].length;
+	return `${text.slice(0, end)}\n${line}${text.slice(end)}`;
+}
+async function rewriteEnv(ctx) {
+	const text = await exists(ctx, ENV);
+	if (!text || !OLD_HELPER.test(text)) return;
+	const next = withImport(text.replace(OLD_HELPER, "/** A default for local development; production must set the value explicitly. */\nconst localDefault = createLocalDefault(process.env.NODE_ENV === \"production\");\n"), "import { createLocalDefault } from \"@tatara/core\";");
+	await ctx.write(ENV, next);
+}
+/** Only call sites of functions that now come from @tatara/core take the logger argument. */
+async function passLogger(ctx, gone) {
+	const runnerGone = gone.includes(MOVED["src/core/commands/runner.ts"]);
+	const lifecycleGone = gone.includes(MOVED["src/core/process/lifecycle.ts"]);
+	const cli = await exists(ctx, CLI_ENTRY);
+	if (cli) {
+		let next = cli;
+		if (runnerGone) next = next.replace("runCommand(commands, process.argv.slice(2));", "runCommand(commands, process.argv.slice(2), logger);");
+		if (lifecycleGone) next = next.replace("await shutdown(code);", "await shutdown(code, logger);");
+		if (next !== cli) await ctx.write(CLI_ENTRY, withImport(next, LOGGER_IMPORT));
+	}
+	if (!lifecycleGone) return;
+	for (const path of SIGNAL_FILES) {
+		const text = await exists(ctx, path);
+		if (text?.includes("handleSignals();")) await ctx.write(path, withImport(text.replace("handleSignals();", "handleSignals(logger);"), LOGGER_IMPORT));
+	}
+}
+const WORKSPACE = "pnpm-workspace.yaml";
+const EXCLUDE_ENTRY = "  - \"@tatara/*\"";
+/** pnpm refuses packages younger than its minimum release age; tatara's own are exempt. */
+async function allowFreshReleases(ctx) {
+	if (ctx.project.config.packageManager !== "pnpm") return;
+	const text = await exists(ctx, WORKSPACE);
+	if (text === void 0 || /["']@tatara\/\*["']/.test(text)) return;
+	const lines = text.replace(/\n$/, "").split("\n");
+	const key = lines.findIndex((line) => line.trim() === "minimumReleaseAgeExclude:");
+	if (key === -1) lines.push("minimumReleaseAgeExclude:", EXCLUDE_ENTRY);
+	else lines.splice(key + 1, 0, EXCLUDE_ENTRY);
+	await ctx.write(WORKSPACE, `${lines.join("\n")}\n`);
+}
+async function useLoggerOptions(ctx) {
+	const text = await exists(ctx, LOGGER);
+	if (!text || text.includes("loggerOptions")) return;
+	if (!await ctx.baseline.isUnchanged(LOGGER, text)) {
+		ctx.report.notes.push(`${LOGGER} is customised and was left as is. It must still export a pino \`logger\`; @tatara/core's loggerOptions() gives the standard options.`);
+		return;
+	}
+	ctx.report.notes.push(`${LOGGER} now uses @tatara/core's loggerOptions: in production the log text is in \`message\` (was \`msg\`) and each line has a Cloud Logging \`severity\`. Update log queries or alerts that read \`msg\`.`);
+	await ctx.write(LOGGER, `import { loggerOptions } from "@tatara/core";
+import { pino } from "pino";
+import { env } from "#core/config/env";
+
+export const logger = pino(
+	loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "${ctx.project.config.name}" }),
+);
+
+export type Logger = typeof logger;
+`);
+}
+//#endregion
+//#region src/upgrade/codemods.ts
+/** Every codemod tatara ships, oldest first. Each step that moves code into a package adds one. */
+const CODEMODS = [{
+	version: "0.2.0",
+	id: "core-package",
+	description: "Use @tatara/core for commands, flags, lifecycle, readiness, logger options and localDefault",
+	async run(ctx) {
+		await ctx.addDependency(CORE, versionOf(CORE));
+		const gone = [];
+		for (const [path, specifier] of Object.entries(MOVED)) if (await ctx.removeIfUnchanged(path) === "kept") ctx.report.notes.push(`${path} is customised; its imports still point at it. Move the change into the app or eject.`);
+		else gone.push(specifier);
+		for (const specifier of gone) await ctx.rewriteImports(specifier, CORE);
+		await rewriteEnv(ctx);
+		await passLogger(ctx, gone);
+		await allowFreshReleases(ctx);
+		await useLoggerOptions(ctx);
+	}
+}];
+//#endregion
+//#region src/upgrade/context.ts
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function createContext(project, baseline, opts = {}) {
+	const report = {
+		ran: [],
+		written: [],
+		removed: [],
+		kept: [],
+		notes: []
+	};
+	const abs = (path) => join(project.root, path);
+	const write = async (path, text) => {
+		if (!report.written.includes(path)) report.written.push(path);
+		if (opts.dryRun) return;
+		await mkdir(dirname(abs(path)), { recursive: true });
+		await writeFile(abs(path), text);
+	};
+	return {
+		project,
+		baseline,
+		report,
+		read: (path) => readFile(abs(path), "utf8"),
+		write,
+		async removeIfUnchanged(path) {
+			if (!existsSync(abs(path))) return "missing";
+			const content = await readFile(abs(path), "utf8");
+			if (await baseline.isUnchanged(path, content)) {
+				if (!opts.dryRun) await rm(abs(path));
+				report.removed.push(path);
+				return "removed";
+			}
+			const diff = content.split("\n").map((line) => `+${line}`).join("\n");
+			report.kept.push({
+				path,
+				diff
+			});
+			return "kept";
+		},
+		async rewriteImports(from, to) {
+			const pattern = new RegExp(`(["'])${escapeRegExp(from)}(?=(?:/[^"']*)?\\1)`, "g");
+			let changed = 0;
+			for (const path of await glob(["src/**/*.ts", "tests/**/*.ts"], {
+				cwd: project.root,
+				ignore: ["src/generated/**"]
+			})) {
+				const text = await readFile(abs(path), "utf8");
+				const next = text.replace(pattern, `$1${to}`);
+				if (next !== text) {
+					await write(path, next);
+					changed++;
+				}
+			}
+			return changed;
+		},
+		async addDependency(name, range, { dev = false } = {}) {
+			const pkg = JSON.parse(await readFile(abs("package.json"), "utf8"));
+			const key = dev ? "devDependencies" : "dependencies";
+			pkg[key] = {
+				...pkg[key],
+				[name]: range
+			};
+			await write("package.json", `${JSON.stringify(pkg, null, "	")}\n`);
+		}
+	};
+}
+//#endregion
+//#region src/commands/upgrade.ts
+async function biomeFormat(file, project) {
+	const biome = join(project.root, "node_modules", ".bin", "biome");
+	if (!existsSync(biome)) return;
+	await x(biome, [
+		"check",
+		"--write",
+		file
+	], {
+		throwOnError: false,
+		nodeOptions: { cwd: project.root }
+	});
+}
+/**
+* The recorded hashes stay what tatara generated: files the app changed keep their old (generated)
+* hash, and only files this upgrade wrote or removed are updated.
+*/
+async function nextRecord(project, report) {
+	const record = { ...project.config.generated?.files ?? {} };
+	for (const path of report.removed) delete record[path];
+	const current = await hashTrackedFiles(project.root);
+	for (const path of report.written) {
+		const hash = current[path];
+		if (hash) record[path] = hash;
+	}
+	return record;
+}
+/**
+* Runs the codemods between the app's tatara version and this CLI's, then syncs and records the
+* new version and file hashes. A failing codemod stops the upgrade before the version is recorded.
+*/
+async function upgrade(project, opts = {}) {
+	const target = opts.cliVersion ?? cliVersion();
+	const from = project.config.version;
+	const ctx = createContext(project, opts.baseline ?? createBaseline(project), { dryRun: opts.dryRun });
+	const due = [...opts.codemods ?? CODEMODS].filter((m) => compareVersions(m.version, from) > 0 && compareVersions(m.version, target) <= 0).sort((a, b) => compareVersions(a.version, b.version));
+	for (const mod of due) {
+		try {
+			await mod.run(ctx);
+		} catch (error) {
+			throw new Error(`codemod ${mod.id} (${mod.version}) failed: ${error.message}`, { cause: error });
+		}
+		ctx.report.ran.push(mod.id);
+	}
+	if (opts.dryRun) return ctx.report;
+	const format = opts.formatFile ?? biomeFormat;
+	for (const path of ctx.report.written) await format(path, project);
+	await (opts.runSync ?? sync)(project);
+	const path = join(project.root, "tatara.json");
+	const config = JSON.parse(await readFile(path, "utf8"));
+	const next = {
+		...config,
+		version: target,
+		generated: {
+			cli: target,
+			files: await nextRecord(project, ctx.report)
+		}
+	};
+	if (JSON.stringify(next) !== JSON.stringify(config)) {
+		await writeFile(path, `${JSON.stringify(next, null, "	")}\n`);
+		await format("tatara.json", project);
+	}
+	return ctx.report;
+}
+function printUpgrade(report, from, to) {
+	if (report.ran.length === 0 && report.removed.length === 0 && report.kept.length === 0) {
+		console.log(pc.green(`nothing to upgrade (${from} → ${to})`));
+		return;
+	}
+	console.log(pc.bold(`tatara upgrade ${from} → ${to}`));
+	for (const id of report.ran) console.log(`  ran ${id}`);
+	for (const path of report.removed) console.log(pc.dim(`  removed ${path} (now provided by a package)`));
+	for (const { path } of report.kept) console.log(pc.yellow(`  kept ${path}: changed in this app; move the change into options or eject`));
+	for (const note of report.notes) console.log(`  ${note}`);
+}
+//#endregion
 //#region src/bin.ts
 const program = new Command("tatara").description("Create and grow opinionated Hono backends").version(cliVersion());
 program.command("new").description("Create a new app").argument("[dir]", "directory to create").option("--orm <orm>", "drizzle | prisma | none").option("--db <database>", "postgres | mysql | none").option("--auth <provider>", "better-auth | none (keycloak = better-auth with --auth-methods keycloak)").option("--auth-methods <list>", "email-otp,phone-otp,password,orgs (better-auth)").option("--addons <list>", "authz,jobs,admin,storage,email,i18n").option("--pm <pm>", "pnpm | npm | bun").option("-y, --yes", "skip prompts and use flags/defaults").option("--no-install", "do not install dependencies").option("--no-git", "do not initialise git").action(async (dir, flags) => {
@@ -3087,6 +3527,12 @@ program.command("routes").description("List every route and what protects it").o
 	if (flags.json) console.log(JSON.stringify(routes, null, 2));
 	else printRoutes(routes);
 });
+program.command("upgrade").description("Run this CLI version's codemods on the app, then sync and verify").option("--dry-run", "show what would change without writing").option("--no-verify", "skip pnpm verify at the end").action(async (flags) => {
+	const project = loadProject();
+	const from = project.config.version;
+	printUpgrade(await upgrade(project, { dryRun: flags.dryRun }), from, cliVersion());
+	if (!flags.dryRun && flags.verify !== false && !await verify(loadProject())) process.exitCode = 1;
+});
 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));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tatara/cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",
@@ -28,6 +28,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-bageri/tatara-cli.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/mohammed-bageri/tatara-cli#readme",
+  "bugs": {
+    "url": "https://github.com/mohammed-bageri/tatara-cli/issues"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"

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

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { issuer } from "#core/auth/keycloak";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { env } from "#core/config/env";
 
 export default defineCommand({

package/templates/features/authz/files/src/core/authz/commands/grant-role.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "#core/authz/constants";
 import { store } from "#core/authz/db/store";
 import { assignRole } from "#core/authz/services/members";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 
 export default defineCommand({
 	name: "authz:grant-role",

package/templates/features/authz/files/src/core/authz/commands/sync-permissions.ts

@@ -1,4 +1,4 @@
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { syncSystemRoles } from "#core/authz/services/sync";
 
 export default defineCommand({

package/templates/features/base/files/AGENTS.md

@@ -40,6 +40,7 @@ __PM_EXEC__ tatara make resource <name> --module <module>   # CRUD slice
 __PM_EXEC__ tatara make route|service|command <name> --module <module>
 __PM_EXEC__ tatara run --list            # app commands
 __PM_EXEC__ tatara routes                # every route and what protects it
+__PM_EXEC__ tatara upgrade               # after bumping @tatara/cli: run its codemods, sync, verify
 ```
 
 ## HTTP

package/templates/features/base/files/README.md

@@ -1,6 +1,6 @@
 # __APP_NAME__
 
-A Hono API created with [tatara](https://github.com/mohammed-bageri/tatara).
+A Hono API created with [tatara](https://github.com/mohammed-bageri/tatara-cli).
 
 ## Getting started
 

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

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

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

@@ -5,7 +5,7 @@ import { cors } from "hono/cors";
 import { secureHeaders } from "hono/secure-headers";
 import { env } from "#core/config/env";
 import type { AppEnv } from "#core/http/context";
-import { runReadinessChecks } from "#core/http/health";
+import { runReadinessChecks } from "@tatara/core";
 import { errorHandler, notFoundHandler } from "#core/http/middleware/error-handler";
 import { requestContext } from "#core/http/middleware/request-context";
 import { validationHook } from "#core/http/middleware/validation";

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

@@ -2,7 +2,7 @@ import { serve } from "@hono/node-server";
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "#core/http/context";
 import { logger } from "#core/logging/logger";
-import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { handleSignals, onShutdown } from "@tatara/core";
 
 /** Starts an HTTP app; on shutdown stops accepting connections and drains in-flight requests. */
 export function startServer(app: OpenAPIHono<AppEnv>, port: number, name: string) {
@@ -10,6 +10,6 @@ export function startServer(app: OpenAPIHono<AppEnv>, port: number, name: string
 		logger.info({ port: info.port, app: name }, `${name} listening on http://localhost:${info.port}`);
 	});
 	onShutdown(`${name}-http`, () => new Promise<void>((resolve) => server.close(() => resolve())));
-	handleSignals();
+	handleSignals(logger);
 	return server;
 }

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

@@ -1,17 +1,9 @@
+import { loggerOptions } from "@tatara/core";
 import { pino } from "pino";
 import { env } from "#core/config/env";
 
-export const logger = pino({
-	level: env.LOG_LEVEL,
-	base: { service: "__APP_NAME__" },
-	...(env.NODE_ENV === "development"
-		? {
-				transport: {
-					target: "pino-pretty",
-					options: { colorize: true, ignore: "pid,hostname,service" },
-				},
-			}
-		: {}),
-});
+export const logger = pino(
+	loggerOptions({ env: env.NODE_ENV, level: env.LOG_LEVEL, service: "__APP_NAME__" }),
+);
 
 export type Logger = typeof logger;

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

@@ -1,4 +1,4 @@
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { env } from "#core/config/env";
 import { migrateDatabase } from "#core/db/migrate";
 

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCommand, flag } from "#core/commands/define";
+import { defineCommand, flag } from "@tatara/core";
 import { env } from "#core/config/env";
 import { dropAllTables } from "#core/db/admin";
 import { migrateDatabase } from "#core/db/migrate";

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

@@ -1,4 +1,4 @@
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { seeds } from "#generated/seeds";
 
 export default defineCommand({

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

@@ -1,5 +1,5 @@
 import { expect, it } from "vitest";
-import { parseFlags } from "#core/commands/runner";
+import { parseFlags } from "@tatara/core";
 import reset from "#core/db/commands/reset";
 
 it("does not treat --force false as forcing db:reset", () => {

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

@@ -1,8 +1,8 @@
 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 { registerReadinessCheck } from "@tatara/core";
+import { onShutdown } from "@tatara/core";
 import * as schema from "#generated/schema";
 
 export const pool = mysql.createPool({ uri: env.DATABASE_URL, connectionLimit: env.DATABASE_POOL_MAX });

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

@@ -1,8 +1,8 @@
 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 { registerReadinessCheck } from "@tatara/core";
+import { onShutdown } from "@tatara/core";
 import * as schema from "#generated/schema";
 
 export const pool = new pg.Pool({ connectionString: env.DATABASE_URL, max: env.DATABASE_POOL_MAX });

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { sendEmail } from "#core/email/send";
 
 export default defineCommand({

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

@@ -1,7 +1,7 @@
 import { Cron } from "croner";
 import { withLock } from "#core/jobs/lock";
 import { logger } from "#core/logging/logger";
-import { handleSignals, onShutdown } from "#core/process/lifecycle";
+import { handleSignals, onShutdown } from "@tatara/core";
 import { schedules } from "#generated/schedules";
 
 const jobs = schedules.map((schedule) => {
@@ -21,5 +21,5 @@ const jobs = schedules.map((schedule) => {
 onShutdown("cron", () => {
 	for (const job of jobs) job.stop();
 });
-handleSignals();
+handleSignals(logger);
 logger.info({ schedules: schedules.map((s) => `${s.name} (${s.cron})`) }, "cron started");

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

@@ -4,7 +4,7 @@ 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 { handleSignals, onShutdown } from "@tatara/core";
 import { consumers } from "#generated/consumers";
 
 const worker = new Worker(
@@ -20,5 +20,5 @@ const worker = new Worker(
 
 worker.on("failed", (job, err) => logger.error({ err, jobId: job?.id, topic: job?.name }, "job failed"));
 onShutdown("worker", () => worker.close());
-handleSignals();
+handleSignals(logger);
 logger.info({ topics: consumers.map((c) => c.topic) }, "worker started");

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { enqueue } from "#core/jobs/queue";
 
 export default defineCommand({

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

@@ -1,7 +1,7 @@
 import { type JobsOptions, Queue } from "bullmq";
 import { env } from "#core/config/env";
 import { redis } from "#core/jobs/redis";
-import { onShutdown } from "#core/process/lifecycle";
+import { onShutdown } from "@tatara/core";
 
 export const QUEUE_NAME = "__APP_NAME__-jobs";
 

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

@@ -1,6 +1,6 @@
 import { Redis } from "ioredis";
 import { env } from "#core/config/env";
-import { onShutdown } from "#core/process/lifecycle";
+import { onShutdown } from "@tatara/core";
 
 let client: Redis | undefined;
 

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

@@ -1,8 +1,8 @@
 import { PrismaMariaDb } from "@prisma/adapter-mariadb";
 import { env } from "#core/config/env";
 import { connectionConfig } from "#core/db/admin";
-import { registerReadinessCheck } from "#core/http/health";
-import { onShutdown } from "#core/process/lifecycle";
+import { registerReadinessCheck } from "@tatara/core";
+import { onShutdown } from "@tatara/core";
 import { type Prisma, PrismaClient } from "#generated/prisma/client";
 
 export const db = new PrismaClient({

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

@@ -1,7 +1,7 @@
 import { PrismaPg } from "@prisma/adapter-pg";
 import { env } from "#core/config/env";
-import { registerReadinessCheck } from "#core/http/health";
-import { onShutdown } from "#core/process/lifecycle";
+import { registerReadinessCheck } from "@tatara/core";
+import { onShutdown } from "@tatara/core";
 import { type Prisma, PrismaClient } from "#generated/prisma/client";
 
 export const db = new PrismaClient({

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

@@ -1,4 +1,4 @@
-import { defineCommand } from "#core/commands/define";
+import { defineCommand } from "@tatara/core";
 import { env } from "#core/config/env";
 import { storage } from "#core/storage/index";
 import { ensureBucket } from "#core/storage/s3";

package/templates/generators/command/files/src/modules/__moduleKebab__/commands/__nameKebab__.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { defineCommand, flag } from "#core/commands/define";
+import { defineCommand, flag } from "@tatara/core";
 
 export default defineCommand({
 	name: "__moduleKebab__:__nameKebab__",

package/templates/versions.json

@@ -30,5 +30,6 @@
   "@aws-sdk/client-s3": "3.1152.0",
   "@aws-sdk/s3-request-presigner": "3.1152.0",
   "nodemailer": "10.1.1",
-  "@types/nodemailer": "8.0.2"
+  "@types/nodemailer": "8.0.2",
+  "@tatara/core": "0.1.0"
 }

package/templates/features/base/files/src/core/commands/define.ts

@@ -1,33 +0,0 @@
-import { z } from "zod";
-import type { Logger } from "#core/logging/logger";
-
-export interface CommandContext {
-	logger: Logger;
-}
-
-export interface CommandDefinition<S extends z.ZodType = z.ZodType> {
-	/** `module:action`, e.g. "billing:recalculate" */
-	name: string;
-	description: string;
-	/** flags parsed from `--key value`; use z.coerce for numbers and `flag()` for booleans */
-	args?: S;
-	run(args: z.infer<S>, ctx: CommandContext): Promise<void> | void;
-}
-
-
-/** Default export of every `commands/*.ts`; discovered by `tatara sync`. */
-export function defineCommand<S extends z.ZodType = typeof noArgs>(
-	definition: CommandDefinition<S>,
-): CommandDefinition<S> {
-	return definition;
-}
-
-export const noArgs = z.object({});
-
-/**
- * A boolean flag: bare `--force` is true, `--force false|0|no|off` is false.
- * (`z.coerce.boolean()` would read the string "false" as true.)
- */
-export function flag() {
-	return z.union([z.boolean(), z.stringbool()]).default(false);
-}

package/templates/features/base/files/src/core/commands/runner.ts

@@ -1,54 +0,0 @@
-import type { CommandDefinition } from "#core/commands/define";
-import { logger } from "#core/logging/logger";
-
-/** Parses `--key value`, `--key=value` and bare `--flag` (true) into an object. */
-export function parseFlags(argv: string[]): Record<string, string | boolean> {
-	const flags: Record<string, string | boolean> = {};
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i] ?? "";
-		if (!arg.startsWith("--")) continue;
-		const [rawKey, inline] = arg.slice(2).split("=", 2);
-		const key = (rawKey ?? "").replace(/-([a-z])/g, (_, ch: string) => ch.toUpperCase());
-		if (inline !== undefined) {
-			flags[key] = inline;
-		} else if (argv[i + 1] !== undefined && !argv[i + 1]?.startsWith("--")) {
-			flags[key] = argv[i + 1] ?? "";
-			i++;
-		} else {
-			flags[key] = true;
-		}
-	}
-	return flags;
-}
-
-export async function runCommand(commands: CommandDefinition[], argv: string[]): Promise<number> {
-	const [name, ...rest] = argv;
-	if (!name || name === "--list" || name === "list" || name === "help") {
-		const width = Math.max(0, ...commands.map((c) => c.name.length));
-		console.log("Commands:");
-		for (const c of [...commands].sort((a, b) => a.name.localeCompare(b.name))) {
-			console.log(`  ${c.name.padEnd(width)}  ${c.description}`);
-		}
-		return 0;
-	}
-	const command = commands.find((c) => c.name === name);
-	if (!command) {
-		console.error(`Unknown command "${name}". Run with --list to see available commands.`);
-		return 1;
-	}
-	const parsed = (command.args ?? null)?.safeParse(parseFlags(rest));
-	if (parsed && !parsed.success) {
-		console.error(`Invalid arguments for ${name}:`);
-		for (const issue of parsed.error.issues) {
-			console.error(`  --${issue.path.join(".")}: ${issue.message}`);
-		}
-		return 1;
-	}
-	try {
-		await command.run(parsed ? parsed.data : {}, { logger: logger.child({ command: name }) });
-		return 0;
-	} catch (error) {
-		logger.error({ err: error, command: name }, "command failed");
-		return 1;
-	}
-}

package/templates/features/base/files/src/core/commands/tests/flags.test.ts

@@ -1,16 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import { flag } from "#core/commands/define";
-import { parseFlags } from "#core/commands/runner";
-
-const args = z.object({ force: flag() });
-const parse = (argv: string[]) => args.parse(parseFlags(argv)).force;
-
-describe("flag()", () => {
-	it("is true for a bare flag", () => expect(parse(["--force"])).toBe(true));
-	it("reads --flag false as false", () => expect(parse(["--force", "false"])).toBe(false));
-	it("reads --flag=0 as false", () => expect(parse(["--force=0"])).toBe(false));
-	it("reads --flag true as true", () => expect(parse(["--force", "true"])).toBe(true));
-	it("defaults to false", () => expect(parse([])).toBe(false));
-	it("rejects anything else", () => expect(() => parse(["--force", "maybe"])).toThrow());
-});

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

@@ -1,25 +0,0 @@
-type Check = () => Promise<void>;
-
-const checks = new Map<string, Check>();
-
-/** Registers a dependency checked by GET /ready (database, redis, …). */
-export function registerReadinessCheck(name: string, check: Check): void {
-	checks.set(name, check);
-}
-
-export async function runReadinessChecks() {
-	const results = await Promise.all(
-		[...checks].map(async ([name, check]) => {
-			try {
-				await check();
-				return [name, "ok"] as const;
-			} catch {
-				return [name, "failed"] as const;
-			}
-		}),
-	);
-	return {
-		ready: results.every(([, status]) => status === "ok"),
-		checks: Object.fromEntries(results),
-	};
-}

package/templates/features/base/files/src/core/process/lifecycle.ts

@@ -1,34 +0,0 @@
-import { logger } from "#core/logging/logger";
-
-type Hook = () => Promise<void> | void;
-
-const hooks: { name: string; run: Hook }[] = [];
-let shuttingDown = false;
-
-/** Registers cleanup that runs on SIGTERM/SIGINT or `shutdown()`, last registered first. */
-export function onShutdown(name: string, run: Hook): void {
-	hooks.push({ name, run });
-}
-
-export async function shutdown(code = 0): Promise<never> {
-	if (!shuttingDown) {
-		shuttingDown = true;
-		for (const hook of [...hooks].reverse()) {
-			try {
-				await hook.run();
-			} catch (error) {
-				logger.error({ err: error, hook: hook.name }, "shutdown hook failed");
-			}
-		}
-	}
-	process.exit(code);
-}
-
-export function handleSignals(): void {
-	for (const signal of ["SIGTERM", "SIGINT"] as const) {
-		process.once(signal, () => {
-			logger.info({ signal }, "shutting down");
-			void shutdown(0);
-		});
-	}
-}