@tatara/cli 0.7.0 → 0.9.0

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import pc from "picocolors";
 import { spawn } from "node:child_process";
 import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
@@ -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,
@@ -227,6 +239,55 @@ ${imports.join("\n")}${imports.length ? "\n" : ""}
 export const ${options.exportName}: ${options.typeName}[] = [${names.join(", ")}];
 `;
 }
+/** What the app's installed (or ejected) @tatara/* packages contribute, by package name. */
+async function contributions(project, kind) {
+	const pkg = JSON.parse(await readFile(join(project.root, "package.json"), "utf8"));
+	const ejected = ejectedPackages(project.config);
+	const names = [...Object.keys({
+		...pkg.dependencies,
+		...pkg.devDependencies
+	}).filter((n) => n.startsWith("@tatara/")).map((n) => n.slice(8)), ...ejected];
+	const out = [];
+	for (const name of [...new Set(names)].sort()) {
+		const file = ejected.includes(name) ? join(project.root, "src/ejected", name, "tatara-package.json") : join(project.root, "node_modules/@tatara", name, "package.json");
+		if (!existsSync(file)) continue;
+		const json = JSON.parse(await readFile(file, "utf8"));
+		out.push(...(ejected.includes(name) ? json[kind] : json.tatara?.[kind]) ?? []);
+	}
+	return out;
+}
+/**
+* Like listModule, plus the packages' factories: `own` are the app's files, and an own entry wins
+* over a package's entry with the same name.
+*/
+function listWithPackages(files, from, options) {
+	if (from.length === 0) return listModule(files, options);
+	const imports = /* @__PURE__ */ new Map();
+	const bind = (name, spec) => {
+		const existing = imports.get(name);
+		if (existing && existing !== spec) throw new Error(`tatara packages need "${name}" from both ${existing} and ${spec}`);
+		imports.set(name, spec);
+	};
+	for (const c of from) {
+		bind(c.factory, c.import);
+		for (const [arg, spec] of Object.entries(c.args)) bind(arg, spec);
+	}
+	const named = [...imports].map(([name, spec]) => `import { ${name} } from "${spec}";`);
+	const own = files.map((f) => `import ${identifier(f, options.prefix)} from "${specifier(f)}";`);
+	const calls = from.map((c) => `...${c.factory}({ ${Object.keys(c.args).join(", ")} })`);
+	const t = options.typeName;
+	return `${HEADER}${options.typeImport}
+${[...named, ...own].join("\n")}
+
+const own: ${t}[] = [${files.map((f) => identifier(f, options.prefix)).join(", ")}];
+// from the installed @tatara/* packages; the app's own entry of the same name wins
+const fromPackages: ${t}[] = [${calls.join(", ")}];
+export const ${options.exportName}: ${t}[] = [
+	...own,
+	...fromPackages.filter((c) => !own.some((o) => o.name === c.name)),
+];
+`;
+}
 async function writeIfChanged(path, content, written) {
 	if ((existsSync(path) ? await readFile(path, "utf8") : void 0) !== content) {
 		await writeFile(path, content);
@@ -235,19 +296,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"), listWithPackages(commands, await contributions(project, "commands"), {
 		prefix: "command",
 		typeImport: "import type { CommandDefinition } from \"@tatara/core\";",
 		typeName: "CommandDefinition",
@@ -255,14 +318,14 @@ 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 \"@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 \"@tatara/jobs\";",
 			typeName: "ScheduleDefinition",
@@ -273,7 +336,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 +346,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"), listWithPackages(seeds, await contributions(project, "seeds"), {
 			prefix: "seed",
 			typeImport: "import type { SeedDefinition } from \"@tatara/db\";",
 			typeName: "SeedDefinition",
@@ -292,7 +355,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 +713,125 @@ 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);
+		}
+		if (manifest.tatara) {
+			const to = `src/ejected/${dep}/tatara-package.json`;
+			await writeFile(join(project.root, to), `${JSON.stringify(manifest.tatara, null, "	")}\n`);
+		}
+	}
+	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, "..");
@@ -2254,6 +2436,10 @@ function pnpmWorkspace(features) {
 	lines.push("# tatara's own packages are installed as soon as they are released", "minimumReleaseAgeExclude:", "  - \"@tatara/*\"");
 	return `${lines.join("\n")}\n`;
 }
+/** Tests of tatara's wiring, not of the app; generated apps leave them out. */
+function isFrameworkTest(path) {
+	return /^src\/core\/.+\/tests\/[^/]+\.test\.ts$/.test(path);
+}
 /** Folds applicable variants into each feature so later steps see one flat definition. */
 function effectiveFeatures(options) {
 	const features = resolveFeatures(options);
@@ -2277,6 +2463,9 @@ async function renderApp(options, generate = {}) {
 	const selected = new Set(features.map((f) => f.id));
 	const tokenValues = tokens(options);
 	const files = await collectTemplateFiles(features, selected);
+	if (!generate.frameworkTests) {
+		for (const path of files.keys()) if (isFrameworkTest(path)) files.delete(path);
+	}
 	const env = dedupeEnv(features, tokenValues);
 	files.set("src/core/config/env.ts", envModule(env.filter((v) => !v.composeOnly)));
 	files.set(".env.example", envFile(env, "example"));
@@ -2580,7 +2769,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 {
@@ -2869,7 +3058,10 @@ async function newApp(dir, rawFlags) {
 	const name = root.split(/[\\/]/).at(-1) ?? "app";
 	const options = validateOptions(interactive ? await prompt(name, flags) : fromFlags(name, flags));
 	const pm = pmCommands(options.packageManager);
-	await writeFiles(root, await renderApp(options, { pmVersion: await pmVersion(options.packageManager) }), { env: devEnvFromExample(options) });
+	await writeFiles(root, await renderApp(options, {
+		pmVersion: await pmVersion(options.packageManager),
+		frameworkTests: flags.frameworkTests
+	}), { env: devEnvFromExample(options) });
 	const project = loadProject(root);
 	await afterCreate(project, "files");
 	if (flags.install !== false) {
@@ -3255,10 +3447,7 @@ async function blockersOf$1(ctx, group, sources) {
 	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.regenerate) await ctx.regenerate(path);
 	for (const path of group.remove) await ctx.removeIfUnchanged(path);
 	for (const rewrite of group.rewrites) await ctx.rewriteImports(rewrite.from, rewrite.to);
 }
@@ -3504,8 +3693,7 @@ const authPackage = {
 		for (const group of ready) {
 			for (const path of group.regenerate) {
 				if (await read$3(ctx, path) === void 0) continue;
-				const next = await ctx.renderCurrent(path);
-				if (next !== void 0) await ctx.write(path, next);
+				await ctx.regenerate(path);
 			}
 			for (const path of group.remove) await ctx.removeIfUnchanged(path);
 		}
@@ -3650,15 +3838,43 @@ const authzPackage = {
 			ctx.report.blocked.push("authz-package");
 			return;
 		}
-		for (const path of regenerate) {
-			const next = await ctx.renderCurrent(path);
-			if (next !== void 0) await ctx.write(path, next);
-		}
+		for (const path of regenerate) await ctx.regenerate(path);
 		for (const path of removed) await ctx.removeIfUnchanged(path);
 		for (const move of MOVES) await ctx.rewriteImports(move.from, move.to);
 	}
 };
 //#endregion
+//#region src/upgrade/codemods/authz-stores.ts
+const group = {
+	name: "authz store",
+	regenerate: ["src/core/authz/index.ts"],
+	remove: ["src/core/authz/db/store.ts"],
+	rewrites: [{
+		from: "#core/authz/db/store",
+		to: "#core/authz/index",
+		names: []
+	}]
+};
+const authzStores = {
+	version: "0.9.0",
+	id: "authz-stores",
+	description: "Use the Prisma or Drizzle authz store from @tatara/authz",
+	async run(ctx) {
+		if (!ctx.project.config.addons.includes("authz")) return;
+		if (ejectedPackages(ctx.project.config).includes("authz")) {
+			ctx.report.notes.push("@tatara/authz is ejected; its store stays in src/core/authz/db/store.ts");
+			return;
+		}
+		const blockers = await blockersOf$1(ctx, group, await sourceFiles(ctx));
+		if (blockers.length > 0) {
+			ctx.report.notes.push(`The authz store was not moved onto @tatara/authz: ${blockers.join("; ")}. Pass prismaAuthzStore(db) or drizzleAuthzStore(db, tables) to createAuthz by hand.`);
+			ctx.report.blocked.push("authz-stores");
+			return;
+		}
+		await applyGroup(ctx, group);
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/core-package.ts
 const CORE = "@tatara/core";
 /** Files @tatara/core replaces, with the import specifier apps used for each. */
@@ -3823,6 +4039,20 @@ const dbTesting = {
 	}
 };
 //#endregion
+//#region src/upgrade/codemods/framework-tests.ts
+const frameworkTests = {
+	version: "0.9.0",
+	id: "framework-tests",
+	description: "Remove tatara's own wiring tests from src/core; the packages and tatara's e2e cover them",
+	async run(ctx) {
+		for (const path of await sourceFiles(ctx)) {
+			if (!isFrameworkTest(path)) continue;
+			if (!await ctx.baseline.isUnchanged(path, await ctx.read(path))) continue;
+			await ctx.removeIfUnchanged(path);
+		}
+	}
+};
+//#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. */
@@ -3885,58 +4115,94 @@ async function outsideImporters(ctx) {
 	}
 	return out;
 }
+const httpPackage = {
+	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.`);
+			ctx.report.blocked.push("http-package");
+			return;
+		}
+		for (const path of replace) await ctx.regenerate(path);
+		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/codemods/package-commands.ts
+/** Copies whose commands and seeds the packages contribute now (wired by `tatara sync`). */
+const COPIES = [
+	"src/core/db/commands/migrate.ts",
+	"src/core/db/commands/reset.ts",
+	"src/core/db/commands/seed.ts",
+	"src/core/authz/commands/grant-role.ts",
+	"src/core/authz/commands/sync-permissions.ts",
+	"src/core/authz/db/seed.ts",
+	"src/core/email/commands/send-test.ts",
+	"src/core/storage/commands/check.ts",
+	"src/core/jobs/commands/enqueue.ts"
+];
+const specifierOf = (path) => `#${path.replace(/^src\//, "").replace(/\.ts$/, "")}`;
 //#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,
+	httpPackage,
+	dbTesting,
+	authPackage,
+	authzPackage,
+	addonPackages,
+	frameworkTests,
+	authzStores,
 	{
-		version: "0.3.0",
-		id: "http-package",
-		description: "Use @tatara/http for app setup, errors, the envelope, OpenAPI docs and the server",
+		version: "0.9.0",
+		id: "package-commands",
+		description: "Take db, authz, email, storage and jobs commands and seeds from their packages",
 		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.`);
-				ctx.report.blocked.push("http-package");
-				return;
-			}
-			for (const path of replace) {
-				const next = await ctx.renderCurrent(path);
-				if (next !== void 0) await ctx.write(path, next);
+			const sources = await sourceFiles(ctx);
+			const texts = /* @__PURE__ */ new Map();
+			for (const path of sources) texts.set(path, await ctx.read(path));
+			const ejected = ejectedPackages(ctx.project.config);
+			for (const path of COPIES) {
+				if (!texts.has(path)) continue;
+				if (ejected.includes(path.split("/")[2] ?? "")) continue;
+				const importers = [...texts].filter(([other, text]) => other !== path && importsOf(text, specifierOf(path)));
+				if (importers.length > 0) {
+					ctx.report.notes.push(`${path} was kept: ${importers.map(([p]) => p).join(", ")} import it.`);
+					continue;
+				}
+				await ctx.removeIfUnchanged(path);
 			}
-			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);
 		}
-	},
-	dbTesting,
-	authPackage,
-	authzPackage,
-	addonPackages
+	}
 ];
 //#endregion
 //#region src/upgrade/context.ts
@@ -3953,7 +4219,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;
@@ -3963,7 +4231,7 @@ function createContext(project, baseline, opts = {}) {
 		await mkdir(dirname(abs(path)), { recursive: true });
 		await writeFile(abs(path), text);
 	};
-	return {
+	const ctx = {
 		project,
 		baseline,
 		report,
@@ -4013,7 +4281,30 @@ function createContext(project, baseline, opts = {}) {
 			});
 			return (await rendered).get(path);
 		},
+		async regenerate(path) {
+			const next = await ctx.renderCurrent(path);
+			if (next === void 0) {
+				const spec = `#${path.replace(/^src\//, "").replace(/\.ts$/, "")}`;
+				const importers = [];
+				for (const other of await glob(["src/**/*.ts", "tests/**/*.ts"], {
+					cwd: project.root,
+					ignore: ["src/generated/**"]
+				})) if (other !== path && importsOf(await readFile(abs(other), "utf8"), spec)) importers.push(other);
+				if (importers.length > 0) {
+					report.notes.push(`${path} was kept: ${importers.join(", ")} import it.`);
+					return "kept";
+				}
+				return ctx.removeIfUnchanged(path);
+			}
+			await write(path, next);
+			return "written";
+		},
 		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] = {
@@ -4023,9 +4314,33 @@ function createContext(project, baseline, opts = {}) {
 			await write("package.json", `${JSON.stringify(pkg, null, "	")}\n`);
 		}
 	};
+	return ctx;
 }
 //#endregion
 //#region src/commands/upgrade.ts
+async function pmInstall(project) {
+	const [cmd = "pnpm", ...args] = pmCommands(project.config.packageManager).install;
+	if ((await x(cmd, args, {
+		throwOnError: false,
+		nodeOptions: {
+			cwd: project.root,
+			stdio: "inherit"
+		}
+	})).exitCode !== 0) throw new Error(`${cmd} ${args.join(" ")} failed; fix it, then run tatara upgrade again`);
+}
+/** Sets every @tatara/* library the app depends on to the range this CLI ships with. */
+async function bumpPackages(ctx) {
+	const pkg = JSON.parse(await ctx.read("package.json"));
+	const known = templateVersions();
+	for (const dev of [false, true]) for (const [name, range] of Object.entries((dev ? pkg.devDependencies : pkg.dependencies) ?? {})) {
+		if (!name.startsWith("@tatara/") || name === "@tatara/cli" || !(name in known)) continue;
+		const current = /^\^(\d+\.\d+\.\d+)$/.exec(range)?.[1];
+		const next = versionOf(name);
+		const shipped = /^\^(\d+\.\d+\.\d+)$/.exec(next)?.[1];
+		if (!current || !shipped || compareVersions(current, shipped) >= 0) continue;
+		await ctx.addDependency(name, next, { dev });
+	}
+}
 async function biomeFormat(file, project) {
 	const biome = join(project.root, "node_modules", ".bin", "biome");
 	if (!existsSync(biome)) return;
@@ -4072,9 +4387,11 @@ async function upgrade(project, opts = {}) {
 		ctx.report.ran.push(mod.id);
 		if (ctx.report.blocked.length > blockedBefore && reached === target) reached = due.slice(0, due.indexOf(mod)).at(-1)?.version ?? from;
 	}
+	await bumpPackages(ctx);
 	if (opts.dryRun) return ctx.report;
 	const format = opts.formatFile ?? biomeFormat;
 	for (const path of ctx.report.written) await format(path, project);
+	await (opts.runInstall ?? pmInstall)(project);
 	await (opts.runSync ?? sync)(project);
 	const path = join(project.root, "tatara.json");
 	const config = JSON.parse(await readFile(path, "utf8"));
@@ -4107,7 +4424,7 @@ function printUpgrade(report, from, to) {
 //#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) => {
+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").addOption(new Option("--framework-tests", "include tatara's own wiring tests (e2e)").hideHelp()).action(async (dir, flags) => {
 	await newApp(dir, flags);
 });
 program.command("sync").description("Regenerate src/generated from discovered module files").option("--quiet", "no output").action(async (flags) => {
@@ -4182,6 +4499,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));
@@ -4189,7 +4517,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);
 });