@tatara/cli 0.1.3 → 0.3.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",
@@ -1042,12 +1051,12 @@ const i18n = {
 			content: "app.use(detectLanguage);"
 		},
 		{
-			file: "src/core/http/middleware/error-handler.ts",
+			file: "src/core/http/app.ts",
 			slot: "imports",
 			content: "import { t } from \"#core/i18n/index\";"
 		},
 		{
-			file: "src/core/http/middleware/error-handler.ts",
+			file: "src/core/http/app.ts",
 			slot: "error-message",
 			content: "if (err.translatable) message = t(c.get(\"language\"), `errors.${err.code}`, message);"
 		},
@@ -1159,6 +1168,11 @@ const betterAuth = {
 			slot: "imports",
 			content: "import { mergeAuthOpenApi } from \"#core/auth/openapi\";"
 		},
+		{
+			file: "src/core/http/app.ts",
+			slot: "expose-headers",
+			content: "\"set-auth-token\","
+		},
 		{
 			file: "src/core/http/app.ts",
 			slot: "openapi",
@@ -1630,6 +1644,8 @@ const base = {
 	kind: "base",
 	label: "Hono API",
 	dependencies: [
+		"@tatara/core",
+		"@tatara/http",
 		"hono",
 		"@hono/node-server",
 		"@hono/zod-openapi",
@@ -2172,14 +2188,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 +2272,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. */
@@ -2331,6 +2345,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 +2913,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 +2961,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 +3077,515 @@ 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$1 = {
+	"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$1["src/core/commands/runner.ts"]);
+	const lifecycleGone = gone.includes(MOVED$1["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;
+`);
+}
+const corePackage = {
+	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$1)) 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/codemods/http-package.ts
+const HTTP = "@tatara/http";
+/** Wiring files the app keeps; replaced by what this CLI generates when the app never changed them. */
+const APP = "src/core/http/app.ts";
+const ROUTES = "src/core/http/routes.ts";
+const SERVERS = ["src/apps/api/server.ts", "src/apps/admin/server.ts"];
+/** Files @tatara/http replaces: import specifier, and the wiring files that import them. */
+const MOVED = [
+	{
+		path: "src/core/http/errors.ts",
+		specifier: "#core/http/errors",
+		usedBy: []
+	},
+	{
+		path: "src/core/http/response.ts",
+		specifier: "#core/http/response",
+		usedBy: []
+	},
+	{
+		path: "src/core/http/middleware/validation.ts",
+		specifier: "#core/http/middleware/validation",
+		usedBy: [APP, ROUTES]
+	},
+	{
+		path: "src/core/http/middleware/error-handler.ts",
+		specifier: "#core/http/middleware/error-handler",
+		usedBy: [APP]
+	},
+	{
+		path: "src/core/http/middleware/request-context.ts",
+		specifier: "#core/http/middleware/request-context",
+		usedBy: [APP]
+	},
+	{
+		path: "src/core/http/server.ts",
+		specifier: "#core/http/server",
+		usedBy: SERVERS
+	}
+];
+async function read(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+/** Files outside the group that import one of the moved files (they would break). */
+async function outsideImporters(ctx) {
+	const group = /* @__PURE__ */ new Set([
+		APP,
+		ROUTES,
+		...SERVERS,
+		...MOVED.map((m) => m.path)
+	]);
+	const specifiers = MOVED.filter((m) => m.usedBy.length > 0).map((m) => m.specifier);
+	const pattern = new RegExp(`["'](${specifiers.map((s) => s.replace(/[/.]/g, "\\$&")).join("|")})["']`);
+	const out = [];
+	for (const path of await glob(["src/**/*.ts", "tests/**/*.ts"], {
+		cwd: ctx.project.root,
+		ignore: ["src/generated/**"]
+	})) {
+		if (group.has(path)) continue;
+		if (pattern.test(await ctx.read(path))) out.push(path);
+	}
+	return out;
+}
+//#endregion
+//#region src/upgrade/codemods.ts
+/** Every codemod tatara ships, oldest first. Each step that moves code into a package adds one. */
+const CODEMODS = [corePackage, {
+	version: "0.3.0",
+	id: "http-package",
+	description: "Use @tatara/http for app setup, errors, the envelope, OpenAPI docs and the server",
+	async run(ctx) {
+		await ctx.addDependency(HTTP, versionOf(HTTP));
+		const blockers = [];
+		const replace = [];
+		for (const path of [
+			APP,
+			ROUTES,
+			...SERVERS
+		]) {
+			const text = await read(ctx, path);
+			if (text === void 0) continue;
+			if (await ctx.baseline.isUnchanged(path, text)) replace.push(path);
+			else blockers.push(`${path} is customised`);
+		}
+		const present = [];
+		for (const entry of MOVED) {
+			const text = await read(ctx, entry.path);
+			if (text === void 0) continue;
+			present.push(entry);
+			if (!await ctx.baseline.isUnchanged(entry.path, text)) blockers.push(`${entry.path} is customised`);
+		}
+		for (const path of await outsideImporters(ctx)) blockers.push(`${path} imports one of the moved files`);
+		if (blockers.length > 0) {
+			ctx.report.notes.push(`Nothing in src/core/http was changed: ${blockers.join("; ")}. Move these onto @tatara/http (createApp, mountRoutes, serveOpenApi, handleErrors, startServer and its error classes) by hand, then delete the old files.`);
+			return;
+		}
+		for (const path of replace) {
+			const next = await ctx.renderCurrent(path);
+			if (next !== void 0) await ctx.write(path, next);
+		}
+		for (const entry of present) await ctx.removeIfUnchanged(entry.path);
+		for (const specifier of [
+			"#core/http/errors",
+			"#core/http/response",
+			"#core/http/middleware/validation"
+		]) await ctx.rewriteImports(specifier, HTTP);
+	}
+}];
+//#endregion
+//#region src/upgrade/context.ts
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function createContext(project, baseline, opts = {}) {
+	const report = {
+		ran: [],
+		written: [],
+		regenerated: [],
+		removed: [],
+		kept: [],
+		notes: []
+	};
+	const abs = (path) => join(project.root, path);
+	let rendered;
+	const write = async (path, text) => {
+		if (!report.written.includes(path)) {
+			report.written.push(path);
+			const before = existsSync(abs(path)) ? await readFile(abs(path), "utf8") : void 0;
+			if (before === void 0 || await baseline.isUnchanged(path, before)) report.regenerated.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 renderCurrent(path) {
+			const { name, orm, database, auth, authMethods, addons, packageManager } = project.config;
+			rendered ??= renderApp({
+				name,
+				orm,
+				database,
+				auth,
+				authMethods,
+				addons,
+				packageManager
+			});
+			return (await rendered).get(path);
+		},
+		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.regenerated) {
+		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 +3657,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));