@tatara/cli 0.5.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
@@ -1454,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",
@@ -2452,7 +2452,7 @@ 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")) {
@@ -3186,6 +3186,36 @@ 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";
@@ -3262,27 +3292,21 @@ function groups(keycloak) {
 	});
 	return all;
 }
-async function read$2(ctx, path) {
+async function read$3(ctx, path) {
 	return ctx.read(path).catch(() => void 0);
 }
-const escapeRegExp$1 = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 /** True when `text` imports `entry` (or one of its gone names). */
 function usesExport(text, entry) {
-	const from = new RegExp(`import\\s+(?:type\\s+)?([^;]*?)\\s+from\\s+["']${escapeRegExp$1(entry.specifier)}["']`, "g");
+	const names = importsOf(text, entry.specifier);
+	if (!names) return false;
 	const gone = entry.names;
-	for (const match of text.matchAll(from)) {
-		if (!gone) return true;
-		const braces = (match[1] ?? "").match(/\{([^}]*)\}/);
-		if (!braces) return true;
-		if ((braces[1] ?? "").split(",").map((part) => part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim()).some((name) => name && gone.includes(name))) return true;
-	}
-	return false;
+	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$2(ctx, path);
+		const text = await read$3(ctx, path);
 		if (text === void 0) continue;
 		if (!await ctx.baseline.isUnchanged(path, text)) blockers.push(`${path} is customised`);
 	}
@@ -3316,7 +3340,7 @@ const authPackage = {
 		}
 		for (const group of ready) {
 			for (const path of group.regenerate) {
-				if (await read$2(ctx, path) === void 0) continue;
+				if (await read$3(ctx, path) === void 0) continue;
 				const next = await ctx.renderCurrent(path);
 				if (next !== void 0) await ctx.write(path, next);
 			}
@@ -3327,6 +3351,151 @@ const authPackage = {
 	}
 };
 //#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. */
@@ -3586,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) {
@@ -3601,7 +3771,8 @@ const CODEMODS = [
 		}
 	},
 	dbTesting,
-	authPackage
+	authPackage,
+	authzPackage
 ];
 //#endregion
 //#region src/upgrade/context.ts
@@ -3613,7 +3784,8 @@ function createContext(project, baseline, opts = {}) {
 		regenerated: [],
 		removed: [],
 		kept: [],
-		notes: []
+		notes: [],
+		blocked: []
 	};
 	const abs = (path) => join(project.root, path);
 	let rendered;
@@ -3725,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;
@@ -3741,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)
 		}
 	};
@@ -3763,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.5.0",
+  "version": "0.6.0",
   "description": "Create and grow opinionated Hono backends",
   "type": "module",
   "license": "MIT",

package/templates/features/auth-keycloak/files+authz/src/core/auth/tests/keycloak-authz.test.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it } from "vitest";
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 import { api } from "#tests/helpers/api";
 import { keycloakToken } from "#tests/helpers/auth";
 import { resetDatabase } from "#tests/helpers/db";
@@ -12,7 +12,7 @@ beforeEach(async () => {
 
 describe("Keycloak access tokens with authz", () => {
 	it("lets token roles match built-in authz roles", async () => {
-		await syncSystemRoles();
+		await authz.syncSystemRoles();
 		const admin = await keycloakToken({ roles: ["admin"] });
 		const user = await keycloakToken({ roles: ["user"] });
 		expect((await api.get("/api/authorization/roles", { headers: bearer(admin) })).status).toBe(

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

@@ -1,7 +1,6 @@
 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 { DEFAULT_ORG_ID, SYSTEM_ORG_ID } from "@tatara/authz";
+import { authz } from "#core/authz/index";
 import { defineCommand } from "@tatara/core";
 
 export default defineCommand({
@@ -13,9 +12,10 @@ export default defineCommand({
 		org: z.string().default(DEFAULT_ORG_ID),
 	}),
 	async run({ user, role, org }, { logger }) {
-		const found = (await store.findRoleByKey(org, role)) ?? (await store.findRoleByKey(SYSTEM_ORG_ID, role));
+		const found = (await authz.store.findRoleByKey(org, role)) ??
+			(await authz.store.findRoleByKey(SYSTEM_ORG_ID, role));
 		if (!found) throw new Error(`No role "${role}" (run authz:sync-permissions first for built-in roles)`);
-		const added = await assignRole(null, org, user, found.id);
+		const added = await authz.assignRole(null, org, user, found.id);
 		logger.info({ user, role, org, added }, added ? "role assigned" : "role already assigned");
 	},
 });

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

@@ -1,11 +1,11 @@
 import { defineCommand } from "@tatara/core";
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 
 export default defineCommand({
 	name: "authz:sync-permissions",
 	description: "Create/update built-in roles so their grants match the code (run on every deploy)",
 	async run(_args, { logger }) {
-		const result = await syncSystemRoles();
+		const result = await authz.syncSystemRoles();
 		logger.info(result, "built-in roles in sync");
 	},
 });

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

@@ -1,10 +1,10 @@
-import { syncSystemRoles } from "#core/authz/services/sync";
+import { authz } from "#core/authz/index";
 import { defineSeed } from "@tatara/db";
 
 export default defineSeed({
 	name: "authz:system-roles",
 	order: -10,
 	async run({ logger }) {
-		logger.info(await syncSystemRoles(), "built-in roles in sync");
+		logger.info(await authz.syncSystemRoles(), "built-in roles in sync");
 	},
 });

package/templates/features/authz/files/src/core/authz/index.ts

@@ -0,0 +1,9 @@
+import { createAuthz } from "@tatara/authz";
+import { store } from "#core/authz/db/store";
+import { SYSTEM_ROLES } from "#core/authz/system-roles";
+import { catalog, type PermissionKey } from "#generated/permissions";
+
+/** The app's authorization: its store, the permission catalog from `tatara sync`, built-in roles. */
+export const authz = createAuthz<PermissionKey>({ store, catalog, systemRoles: SYSTEM_ROLES });
+
+export const { checkPermission, removeMemberAccess, requirePermission, resolveScope } = authz;