@tatara/cli 0.4.0 → 0.6.0

package/dist/bin.mjs

@@ -273,13 +273,12 @@ 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 { mergeCatalogs, type PermissionKeysOf } from "#core/authz/catalog";
-import corePermissions from "#core/authz/permissions";
+		await writeIfChanged(join(out, "permissions.ts"), `${HEADER}import { authzPermissions, mergeCatalogs, type PermissionKeysOf } from "@tatara/authz";
 ${imports.join("\n")}${imports.length ? "\n" : ""}
-export const catalog = mergeCatalogs(corePermissions${names.map((n) => `, ${n}`).join("")});
+export const catalog = mergeCatalogs(authzPermissions${names.map((n) => `, ${n}`).join("")});
 
 export type PermissionKey =
-	| PermissionKeysOf<typeof corePermissions>${names.map((n) => `\n\t| PermissionKeysOf<typeof ${n}>`).join("")};
+	| PermissionKeysOf<typeof authzPermissions>${names.map((n) => `\n\t| PermissionKeysOf<typeof ${n}>`).join("")};
 `, written);
 	}
 	if (project.config.database !== "none") {
@@ -682,6 +681,7 @@ const authz = {
 	id: "authz",
 	kind: "addon",
 	label: "Permission system",
+	dependencies: ["@tatara/authz"],
 	slots: [
 		{
 			file: "tests/helpers/auth.ts",
@@ -711,9 +711,9 @@ const authz = {
 
 - Permissions are \`resource:action\` (optionally scoped \`own | team | org\`, where a wider scope
   satisfies a narrower one). Each module declares its resources and the grants built-in roles get
-  in \`permissions/<name>.permissions.ts\` (\`definePermissions\`); \`tatara sync\` merges them into a
+  in \`permissions/<name>.permissions.ts\` (\`definePermissions\` from \`@tatara/authz\`); \`tatara sync\` merges them into a
   typed catalog.
-- Guard routes with \`middleware: [requirePermission("project:read")]\` from \`#core/authz/middleware\`
+- Guard routes with \`middleware: [requirePermission("project:read")]\` from \`#core/authz/index\`
   and declare \`security: [{ bearerAuth: ["project:read"] }]\`. For scoped actions, call
   \`resolveScope(principal, "doc:read")\` in the service and filter rows by the returned scope.
 - Effective permissions = role grants (assigned roles + built-in roles whose key matches an
@@ -837,7 +837,7 @@ const admin = {
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { requireRole } from \"#core/auth/middleware\";"
+			content: "import { requireRole } from \"@tatara/auth\";"
 		},
 		{
 			file: "src/core/http/app.ts",
@@ -1077,6 +1077,7 @@ const auth = {
 	id: "auth",
 	kind: "auth",
 	label: "Auth (shared)",
+	dependencies: ["@tatara/auth"],
 	slots: [
 		{
 			file: "src/core/http/app.ts",
@@ -1107,7 +1108,7 @@ const auth = {
 
 - \`c.var.principal\` is set for every request with valid credentials: \`{ userId, orgId, roles, kind }\`.
 - Protect routes with \`middleware: [requireAuth()]\` or \`requireRole("admin")\` from
-  \`#core/auth/middleware\`, and declare \`security: [{ bearerAuth: [] }]\` so the route is
+  \`@tatara/auth\`, and declare \`security: [{ bearerAuth: [] }]\` so the route is
   documented as protected. Read the caller with \`currentPrincipal(c)\`.
 - In tests, \`asUser()\` from \`#tests/helpers/auth\` returns headers for a fresh authenticated user.
 `
@@ -1121,7 +1122,7 @@ const BETTER_AUTH_AGENTS = `### better-auth
 - Sessions work as cookies (browsers) and as \`Authorization: Bearer <session token>\` (mobile, APIs).
 - Outside production, every email and SMS is kept in an in-memory outbox:
   \`GET /api/dev/outbox?to=<address>\` returns the latest messages, including sign-in codes.
-- To send real SMS, implement \`SmsSender\` in \`src/core/auth/sms.ts\`.
+- To send real SMS, implement \`SmsSender\` (from \`@tatara/auth\`) in \`src/core/auth/sms.ts\`.
 `;
 const drizzlePg = ["drizzle", "postgres"];
 const drizzleMy = ["drizzle", "mysql"];
@@ -1161,12 +1162,12 @@ const betterAuth = {
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { outboxEnabled, readOutbox } from \"#core/auth/delivery\";"
+			content: "import { outbox } from \"#core/auth/delivery\";"
 		},
 		{
 			file: "src/core/http/app.ts",
 			slot: "imports",
-			content: "import { mergeAuthOpenApi } from \"#core/auth/openapi\";"
+			content: "import { mergeAuthOpenApi } from \"@tatara/auth\";"
 		},
 		{
 			file: "src/core/http/app.ts",
@@ -1178,7 +1179,7 @@ const betterAuth = {
 			slot: "openapi-options",
 			content: [
 				"async extend(document) {",
-				"	if (name === \"api\") await mergeAuthOpenApi(document, `${API_PREFIX}/auth`);",
+				"	if (name === \"api\") await mergeAuthOpenApi(document, auth, `${API_PREFIX}/auth`);",
 				"},"
 			].join("\n")
 		},
@@ -1189,8 +1190,8 @@ const betterAuth = {
 			content: [
 				"if (name === \"api\") {",
 				"	app.on([\"GET\", \"POST\"], `${API_PREFIX}/auth/*`, (c) => auth.handler(c.req.raw));",
-				"	if (outboxEnabled()) {",
-				"		app.get(`${API_PREFIX}/dev/outbox`, (c) => c.json({ messages: readOutbox(c.req.query(\"to\")) }));",
+				"	if (outbox.enabled) {",
+				"		app.get(`${API_PREFIX}/dev/outbox`, (c) => c.json({ messages: outbox.read(c.req.query(\"to\")) }));",
 				"	}",
 				"}"
 			].join("\n")
@@ -1453,7 +1454,7 @@ const authOrgs = {
 			file: "src/core/auth/auth.ts",
 			slot: "imports",
 			when: ["authz"],
-			content: "import { removeMemberAccess } from \"#core/authz/services/members\";"
+			content: "import { removeMemberAccess } from \"#core/authz/index\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -1468,64 +1469,11 @@ const authOrgs = {
 		...adminFields
 	]
 };
-const KEYCLOAK_AGENTS = `### Keycloak
-
-- The API also accepts Keycloak access tokens (\`Authorization: Bearer <token>\`). The
-  \`keycloakTokens()\` better-auth plugin (\`src/core/auth/keycloak-plugin.ts\`) verifies signature,
-  issuer, audience \`__APP_NAME__-api\` and expiry; login happens in the frontend via OIDC (PKCE)
-  against the \`__APP_NAME__-web\` client.
-- The token's subject is the user id. The user (and a \`keycloak\` account) is created in
-  better-auth's tables on first use; a token whose email already belongs to another account is
-  rejected. Service-account tokens become \`kind: "service"\` principals with no user row.
-- Roles come from the token (realm roles, \`roles\`, and client roles for the API); a role named like
-  a built-in authz role grants it. The organization comes from the \`organization\` claim.
-- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
-  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
-- Tests sign tokens with a local key: \`keycloakToken()\` from \`#tests/helpers/auth\`.
-`;
-const KEYCLOAK_TEST_HELPER = [
-	"const { publicKey, privateKey } = await generateKeyPair(\"RS256\");",
-	"setKeySource(async (header) => {",
-	"	if (header.kid !== \"test\") throw new Error(\"unknown key\");",
-	"	return publicKey;",
-	"});",
-	"",
-	"export interface KeycloakTokenOptions {",
-	"	sub?: string;",
-	"	email?: string;",
-	"	emailVerified?: boolean;",
-	"	roles?: string[];",
-	"	organization?: string[] | Record<string, unknown>;",
-	"	username?: string;",
-	"	issuer?: string;",
-	"	audience?: string;",
-	"	expiresIn?: string | number;",
-	"}",
-	"",
-	"/** Signs an access token the API accepts, as if Keycloak issued it. */",
-	"export async function keycloakToken(options: KeycloakTokenOptions = {}): Promise<string> {",
-	"	const sub = options.sub ?? newId();",
-	"	return new SignJWT({",
-	"		email: options.email ?? `user-${sub}@example.com`,",
-	"		email_verified: options.emailVerified ?? true,",
-	"		preferred_username: options.username ?? `user-${sub.slice(0, 8)}`,",
-	"		roles: options.roles ?? [\"user\"],",
-	"		...(options.organization ? { organization: options.organization } : {}),",
-	"	})",
-	"		.setProtectedHeader({ alg: \"RS256\", kid: \"test\" })",
-	"		.setSubject(sub)",
-	"		.setIssuer(options.issuer ?? issuer)",
-	"		.setAudience(options.audience ?? env.KEYCLOAK_AUDIENCE)",
-	"		.setIssuedAt()",
-	"		.setExpirationTime(options.expiresIn ?? \"5m\")",
-	"		.sign(privateKey);",
-	"}"
-].join("\n");
 const authKeycloak = {
 	id: "auth-keycloak",
 	kind: "auth-method",
 	label: "Keycloak tokens",
-	dependencies: ["jose"],
+	dependencies: ["@tatara/keycloak", "jose"],
 	env: [
 		{
 			key: "KEYCLOAK_PORT",
@@ -1574,53 +1522,56 @@ const authKeycloak = {
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "imports",
-			content: "import { keycloakTokens } from \"#core/auth/keycloak-plugin\";"
+			content: "import { keycloakTokens } from \"@tatara/keycloak\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { keycloak } from \"#core/auth/keycloak\";"
+		},
+		{
+			file: "src/core/auth/auth.ts",
+			slot: "imports",
+			content: "import { logger } from \"#core/logging/logger\";"
 		},
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "plugins",
 			unless: ["auth-orgs"],
-			content: "keycloakTokens(),",
+			content: "keycloakTokens({ verifier: keycloak, logger }),",
 			order: 800
 		},
 		{
 			file: "src/core/auth/auth.ts",
 			slot: "plugins",
 			when: ["auth-orgs"],
-			content: "keycloakTokens({ organizations: true }),",
+			content: "keycloakTokens({ verifier: keycloak, logger, organizations: true }),",
 			order: 800
 		},
 		{
 			file: "src/core/auth/principal.ts",
-			slot: "no-session",
-			content: [
-				"if (!session) {",
-				"	const header = c.req.header(\"authorization\");",
-				"	const token = header?.startsWith(\"Bearer \") ? header.slice(7) : undefined;",
-				"	const principal = token ? await auth.api.verifyKeycloakToken({ body: { token } }) : null;",
-				"	if (principal) c.set(\"principal\", principal);",
-				"}"
-			].join("\n")
+			slot: "resolvers",
+			content: "(c) => keycloakPrincipal(auth, c.req.header(\"authorization\")),"
 		},
 		{
-			file: "tests/helpers/auth.ts",
+			file: "src/core/auth/principal.ts",
 			slot: "imports",
-			content: "import { generateKeyPair, SignJWT } from \"jose\";"
+			content: "import { keycloakPrincipal } from \"@tatara/keycloak\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
-			content: "import { issuer, setKeySource } from \"#core/auth/keycloak\";"
+			content: "import { useTestKeys } from \"@tatara/keycloak/testing\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "imports",
-			content: "import { env } from \"#core/config/env\";"
+			content: "import { keycloak } from \"#core/auth/keycloak\";"
 		},
 		{
 			file: "tests/helpers/auth.ts",
 			slot: "helpers",
-			content: KEYCLOAK_TEST_HELPER
+			content: ["/** Signs an access token the API accepts, as if Keycloak issued it. */", "export const keycloakToken = await useTestKeys(keycloak);"].join("\n")
 		},
 		{
 			file: "tests/helpers/auth.ts",
@@ -1628,7 +1579,7 @@ const authKeycloak = {
 			unless: ["auth-orgs"],
 			content: [
 				"if (options.roles) {",
-				"	const sub = newId();",
+				"	const sub = crypto.randomUUID();",
 				"	const token = await keycloakToken({ sub, roles: options.roles, email: options.email });",
 				"	return { userId: sub, headers: { authorization: `Bearer ${token}` } };",
 				"}"
@@ -1637,7 +1588,21 @@ const authKeycloak = {
 		{
 			file: "AGENTS.md",
 			slot: "sections",
-			content: KEYCLOAK_AGENTS
+			content: `### Keycloak
+
+- The API also accepts Keycloak access tokens (\`Authorization: Bearer <token>\`). The
+  \`keycloakTokens()\` better-auth plugin (\`@tatara/keycloak\`) verifies signature,
+  issuer, audience \`__APP_NAME__-api\` and expiry; login happens in the frontend via OIDC (PKCE)
+  against the \`__APP_NAME__-web\` client.
+- The token's subject is the user id. The user (and a \`keycloak\` account) is created in
+  better-auth's tables on first use; a token whose email already belongs to another account is
+  rejected. Service-account tokens become \`kind: "service"\` principals with no user row.
+- Roles come from the token (realm roles, \`roles\`, and client roles for the API); a role named like
+  a built-in authz role grants it. The organization comes from the \`organization\` claim.
+- Local dev realm: \`keycloak/realm.json\` (users alice/alice with admin, bob/bob).
+  \`__PM_EXEC__ tatara run keycloak:token --user alice\` prints a token for curl.
+- Tests sign tokens with a local key: \`keycloakToken()\` from \`#tests/helpers/auth\`.
+`
 		}
 	]
 };
@@ -2487,11 +2452,11 @@ function guardSlots(project, n) {
 		order: fills.length
 	});
 	if (project.has("authz")) {
-		add("imports", "import { requirePermission } from \"#core/authz/middleware\";");
+		add("imports", "import { requirePermission } from \"#core/authz/index\";");
 		for (const [route, action] of Object.entries(ACTIONS)) add(`guard-${route}`, `middleware: [requirePermission("${n.kebab}:${action}")] as const,\nsecurity: [{ bearerAuth: ["${n.kebab}:${action}"] }],`);
 		add("auth-errors", "...errorResponses(401, 403),");
 	} else if (project.has("auth")) {
-		add("imports", "import { requireAuth } from \"#core/auth/middleware\";");
+		add("imports", "import { requireAuth } from \"@tatara/auth\";");
 		for (const route of Object.keys(ACTIONS)) add(`guard-${route}`, "middleware: [requireAuth()] as const,\nsecurity: [{ bearerAuth: [] }],");
 		add("auth-errors", "...errorResponses(401),");
 	}
@@ -3221,6 +3186,316 @@ function createBaseline(project, deps) {
 	} };
 }
 //#endregion
+//#region src/upgrade/codemods/imports.ts
+const escapeRegExp$1 = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* The names `text` imports (or re-exports) from `specifier`, or null when it doesn't use it.
+* A namespace, default, side-effect or dynamic import gives ["*"]: it could reach any name.
+*/
+function importsOf(text, specifier) {
+	const spec = `["']${escapeRegExp$1(specifier)}["']`;
+	const names = [];
+	let found = false;
+	const fromClause = new RegExp(`(?:import|export)\\s+(?:type\\s+)?([^;]*?)\\s+from\\s+${spec}`, "g");
+	for (const match of text.matchAll(fromClause)) {
+		found = true;
+		const braces = (match[1] ?? "").match(/^\{([^}]*)\}$/);
+		if (!braces) {
+			names.push("*");
+			continue;
+		}
+		for (const part of (braces[1] ?? "").split(",")) {
+			const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+			if (name) names.push(name);
+		}
+	}
+	if (new RegExp(`import\\s*\\(\\s*${spec}\\s*\\)|import\\s+${spec}`).test(text)) {
+		found = true;
+		names.push("*");
+	}
+	return found ? names : null;
+}
+//#endregion
+//#region src/upgrade/codemods/auth-package.ts
+const AUTH = "@tatara/auth";
+const KEYCLOAK = "@tatara/keycloak";
+const APP$1 = "src/core/http/app.ts";
+const HELPERS = "tests/helpers/auth.ts";
+function groups(keycloak) {
+	const all = [
+		{
+			name: "OpenAPI merge and dev outbox",
+			regenerate: [APP$1, "src/core/auth/delivery.ts"],
+			remove: ["src/core/auth/openapi.ts"],
+			exports: [{ specifier: "#core/auth/openapi" }, {
+				specifier: "#core/auth/delivery",
+				names: [
+					"outboxEnabled",
+					"readOutbox",
+					"OutboxMessage"
+				]
+			}]
+		},
+		{
+			name: "SMS sender",
+			regenerate: ["src/core/auth/sms.ts"],
+			remove: [],
+			exports: [{
+				specifier: "#core/auth/sms",
+				names: ["SmsSender"]
+			}]
+		},
+		{
+			name: "principal middleware",
+			regenerate: ["src/core/auth/principal.ts"],
+			remove: [],
+			exports: []
+		}
+	];
+	if (!keycloak) {
+		all.push({
+			name: "test helpers",
+			regenerate: [HELPERS],
+			remove: [],
+			exports: []
+		});
+		return all;
+	}
+	all.push({
+		name: "Keycloak",
+		regenerate: [
+			"src/core/auth/auth.ts",
+			"src/core/auth/keycloak.ts",
+			"src/core/auth/commands/keycloak-token.ts",
+			"src/core/auth/tests/keycloak-tokens.test.ts",
+			HELPERS
+		],
+		remove: ["src/core/auth/keycloak-plugin.ts"],
+		exports: [
+			{ specifier: "#core/auth/keycloak-plugin" },
+			{
+				specifier: "#core/auth/keycloak",
+				names: [
+					"issuer",
+					"setKeySource",
+					"verifyAccessToken",
+					"rolesOf",
+					"organizationOf",
+					"KeycloakClaims"
+				]
+			},
+			{
+				specifier: "#tests/helpers/auth",
+				names: ["KeycloakTokenOptions"]
+			}
+		]
+	});
+	return all;
+}
+async function read$3(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+/** True when `text` imports `entry` (or one of its gone names). */
+function usesExport(text, entry) {
+	const names = importsOf(text, entry.specifier);
+	if (!names) return false;
+	const gone = entry.names;
+	return !gone || names.some((name) => name === "*" || gone.includes(name));
+}
+/** Why the group can't move, or [] when it can. */
+async function blockersOf(ctx, group, sources) {
+	const blockers = [];
+	for (const path of [...group.regenerate, ...group.remove]) {
+		const text = await read$3(ctx, path);
+		if (text === void 0) continue;
+		if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
+	}
+	const own = /* @__PURE__ */ new Set([...group.regenerate, ...group.remove]);
+	for (const path of sources) {
+		if (own.has(path)) continue;
+		const text = await ctx.read(path);
+		if (group.exports.some((entry) => usesExport(text, entry))) blockers.push(`${path} imports what moves`);
+	}
+	return blockers;
+}
+const authPackage = {
+	version: "0.5.0",
+	id: "auth-package",
+	description: "Use @tatara/auth (guards, principal, OpenAPI merge, outbox) and @tatara/keycloak",
+	async run(ctx) {
+		const { config } = ctx.project;
+		if (config.auth === "none") return;
+		const keycloak = config.authMethods.includes("keycloak");
+		await ctx.addDependency(AUTH, versionOf(AUTH));
+		if (keycloak) await ctx.addDependency(KEYCLOAK, versionOf(KEYCLOAK));
+		const sources = await glob(["src/**/*.ts", "tests/**/*.ts"], {
+			cwd: ctx.project.root,
+			ignore: ["src/generated/**"]
+		});
+		const ready = [];
+		for (const group of groups(keycloak)) {
+			const blockers = await blockersOf(ctx, group, sources);
+			if (blockers.length === 0) ready.push(group);
+			else ctx.report.notes.push(`${group.name} was not moved onto ${group.name === "Keycloak" ? KEYCLOAK : AUTH}: ${blockers.join("; ")}. Compare these files with a newly generated app and move them by hand.`);
+		}
+		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);
+			}
+			for (const path of group.remove) await ctx.removeIfUnchanged(path);
+		}
+		if (await ctx.removeIfUnchanged("src/core/auth/middleware.ts") === "kept") ctx.report.notes.push("src/core/auth/middleware.ts is customised; its imports still point at it.");
+		else await ctx.rewriteImports("#core/auth/middleware", AUTH);
+	}
+};
+//#endregion
+//#region src/upgrade/codemods/authz-package.ts
+const AUTHZ = "@tatara/authz";
+const INDEX = "#core/authz/index";
+const DIR = "src/core/authz";
+/** Copies the package replaces. */
+const REMOVED = [
+	"cache.ts",
+	"catalog.ts",
+	"constants.ts",
+	"middleware.ts",
+	"permissions.ts",
+	"resolver.ts",
+	"types.ts",
+	"validators.ts",
+	"services/audit.ts",
+	"services/grants.ts",
+	"services/members.ts",
+	"services/roles.ts",
+	"services/sync.ts"
+].map((f) => `${DIR}/${f}`);
+/** App files that stay (or are new), and become what this CLI generates. system-roles.ts is the app's config and stays as it is. */
+const REGENERATED$1 = [
+	`${DIR}/index.ts`,
+	`${DIR}/db/seed.ts`,
+	`${DIR}/commands/grant-role.ts`,
+	`${DIR}/commands/sync-permissions.ts`,
+	`${DIR}/routes/authorization.routes.ts`,
+	`${DIR}/tests/authz.test.ts`,
+	"src/core/auth/tests/keycloak-authz.test.ts",
+	"tests/helpers/authz.ts"
+];
+/** Where other files' imports go, and the names that exist there. undefined: every name. */
+const MOVES = [
+	{
+		from: "#core/authz/constants",
+		to: AUTHZ
+	},
+	{
+		from: "#core/authz/types",
+		to: AUTHZ
+	},
+	{
+		from: "#core/authz/catalog",
+		to: AUTHZ
+	},
+	{
+		from: "#core/authz/validators",
+		to: AUTHZ
+	},
+	{
+		from: "#core/authz/middleware",
+		to: INDEX,
+		names: ["requirePermission"]
+	},
+	{
+		from: "#core/authz/resolver",
+		to: INDEX,
+		names: ["checkPermission", "resolveScope"]
+	},
+	{
+		from: "#core/authz/services/members",
+		to: INDEX,
+		names: ["removeMemberAccess"]
+	},
+	{
+		from: "#core/authz/cache",
+		to: INDEX,
+		names: []
+	},
+	{
+		from: "#core/authz/permissions",
+		to: INDEX,
+		names: []
+	},
+	...[
+		"audit",
+		"grants",
+		"roles",
+		"sync"
+	].map((s) => ({
+		from: `#core/authz/services/${s}`,
+		to: INDEX,
+		names: []
+	}))
+];
+/** Names the 0.5 constants file had that the package dropped. */
+const DROPPED_CONSTANTS = ["CACHE_TTL_MS"];
+async function read$2(ctx, path) {
+	return ctx.read(path).catch(() => void 0);
+}
+const authzPackage = {
+	version: "0.6.0",
+	id: "authz-package",
+	description: "Use @tatara/authz (catalog, resolver, guards, services, routes)",
+	async run(ctx) {
+		if (!ctx.project.config.addons.includes("authz")) return;
+		await ctx.addDependency(AUTHZ, versionOf(AUTHZ));
+		const blockers = [];
+		const regenerate = [];
+		for (const path of REGENERATED$1) {
+			const text = await read$2(ctx, path);
+			if (text === void 0) {
+				if (path === `${DIR}/index.ts`) regenerate.push(path);
+				continue;
+			}
+			if (await ctx.baseline.isUnchanged(path, text)) regenerate.push(path);
+			else blockers.push(`${path} is customised`);
+		}
+		const removed = [];
+		for (const path of REMOVED) {
+			const text = await read$2(ctx, path);
+			if (text === void 0) continue;
+			removed.push(path);
+			if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
+		}
+		const own = /* @__PURE__ */ new Set([...REGENERATED$1, ...REMOVED]);
+		const sources = await glob(["src/**/*.ts", "tests/**/*.ts"], {
+			cwd: ctx.project.root,
+			ignore: ["src/generated/**"]
+		});
+		for (const path of sources) {
+			if (own.has(path)) continue;
+			const text = await ctx.read(path);
+			for (const move of MOVES) {
+				const names = importsOf(text, move.from);
+				if (!names) continue;
+				const allowed = move.names;
+				const missing = names.filter((n) => n === "*" || (allowed ? !allowed.includes(n) : move.from.endsWith("/constants") && DROPPED_CONSTANTS.includes(n)));
+				if (missing.length > 0) blockers.push(`${path} imports ${missing.join(", ")} from ${move.from}`);
+			}
+		}
+		if (blockers.length > 0) {
+			ctx.report.notes.push(`Nothing in ${DIR} was changed: ${blockers.join("; ")}. Compare with a newly generated app and move onto @tatara/authz (createAuthz in ${DIR}/index.ts) by hand.`);
+			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 removed) await ctx.removeIfUnchanged(path);
+		for (const move of MOVES) await ctx.rewriteImports(move.from, move.to);
+	}
+};
+//#endregion
 //#region src/upgrade/codemods/core-package.ts
 const CORE = "@tatara/core";
 /** Files @tatara/core replaces, with the import specifier apps used for each. */
@@ -3480,6 +3755,7 @@ const CODEMODS = [
 			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) {
@@ -3494,7 +3770,9 @@ const CODEMODS = [
 			]) await ctx.rewriteImports(specifier, HTTP);
 		}
 	},
-	dbTesting
+	dbTesting,
+	authPackage,
+	authzPackage
 ];
 //#endregion
 //#region src/upgrade/context.ts
@@ -3506,7 +3784,8 @@ function createContext(project, baseline, opts = {}) {
 		regenerated: [],
 		removed: [],
 		kept: [],
-		notes: []
+		notes: [],
+		blocked: []
 	};
 	const abs = (path) => join(project.root, path);
 	let rendered;
@@ -3618,13 +3897,16 @@ async function upgrade(project, opts = {}) {
 	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));
+	let reached = target;
 	for (const mod of due) {
+		const blockedBefore = ctx.report.blocked.length;
 		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 (ctx.report.blocked.length > blockedBefore && reached === target) reached = due.slice(0, due.indexOf(mod)).at(-1)?.version ?? from;
 	}
 	if (opts.dryRun) return ctx.report;
 	const format = opts.formatFile ?? biomeFormat;
@@ -3634,9 +3916,9 @@ async function upgrade(project, opts = {}) {
 	const config = JSON.parse(await readFile(path, "utf8"));
 	const next = {
 		...config,
-		version: target,
+		version: reached,
 		generated: {
-			cli: target,
+			cli: reached,
 			files: await nextRecord(project, ctx.report)
 		}
 	};
@@ -3656,6 +3938,7 @@ function printUpgrade(report, from, to) {
 	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}`);
+	if (report.blocked.length > 0) console.log(pc.yellow(`  ${report.blocked.join(", ")} did not run: make the changes above, then run tatara upgrade again`));
 }
 //#endregion
 //#region src/bin.ts

package/package.json

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