@tatara/cli 0.0.0-stage → 0.1.0

package/templates/features/keycloak/files+drizzle/src/core/auth/users.ts

@@ -0,0 +1,18 @@
+import type { KeycloakClaims } from "#core/auth/keycloak";
+import { users } from "#core/auth/db/user.schema";
+import { db } from "#core/db/client";
+
+const known = new Set<string>();
+
+/** Creates the local user row for a token subject the first time it is seen. */
+export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
+	if (known.has(claims.sub)) return;
+	const values = {
+		id: claims.sub,
+		email: claims.email ?? null,
+		name: claims.name ?? claims.preferred_username ?? null,
+	};
+	// tatara:slot upsert
+	if (known.size > 10_000) known.clear();
+	known.add(claims.sub);
+}

package/templates/features/keycloak/files+drizzle+mysql/src/core/auth/db/user.schema.ts

@@ -0,0 +1,10 @@
+import { mysqlTable, timestamp, varchar } from "drizzle-orm/mysql-core";
+
+/** Local copy of Keycloak users (id = token subject), created on first request. */
+export const users = mysqlTable("users", {
+	id: varchar({ length: 36 }).primaryKey(),
+	email: varchar({ length: 255 }),
+	name: varchar({ length: 255 }),
+	createdAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
+	updatedAt: timestamp({ fsp: 3, mode: "date" }).notNull().defaultNow(),
+});

package/templates/features/keycloak/files+drizzle+postgres/src/core/auth/db/user.schema.ts

@@ -0,0 +1,10 @@
+import { pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+/** Local copy of Keycloak users (id = token subject), created on first request. */
+export const users = pgTable("users", {
+	id: text().primaryKey(),
+	email: text(),
+	name: text(),
+	createdAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
+	updatedAt: timestamp({ withTimezone: true, mode: "date" }).notNull().defaultNow(),
+});

package/templates/features/keycloak/files+prisma/prisma/models/user.prisma

@@ -0,0 +1,10 @@
+/// Local copy of Keycloak users (id = token subject), created on first request.
+model User {
+  id        String   @id @db.VarChar(36)
+  email     String?  @db.VarChar(255)
+  name      String?  @db.VarChar(255)
+  createdAt DateTime @default(now()) @map("created_at")
+  updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
+
+  @@map("users")
+}

package/templates/features/keycloak/files+prisma/src/core/auth/users.ts

@@ -0,0 +1,13 @@
+import type { KeycloakClaims } from "#core/auth/keycloak";
+import { db } from "#core/db/client";
+
+const known = new Set<string>();
+
+/** Creates the local user row for a token subject the first time it is seen. */
+export async function ensureLocalUser(claims: KeycloakClaims): Promise<void> {
+	if (known.has(claims.sub)) return;
+	const data = { email: claims.email ?? null, name: claims.name ?? claims.preferred_username ?? null };
+	await db.user.upsert({ where: { id: claims.sub }, create: { id: claims.sub, ...data }, update: data });
+	if (known.size > 10_000) known.clear();
+	known.add(claims.sub);
+}

package/templates/features/prisma/files/prisma.config.ts

@@ -0,0 +1,10 @@
+import { existsSync } from "node:fs";
+import { defineConfig } from "prisma/config";
+
+if (existsSync(".env")) process.loadEnvFile(".env");
+
+export default defineConfig({
+	schema: "prisma",
+	migrations: { path: "prisma/migrations" },
+	datasource: { url: process.env.DATABASE_URL ?? "" },
+});

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

@@ -0,0 +1,13 @@
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+/** Applies prisma/migrations to the database at `url` (`prisma migrate deploy`). */
+export async function migrateDatabase(url: string): Promise<void> {
+	await run(resolve("node_modules/.bin/prisma"), ["migrate", "deploy"], {
+		// tatara-check-ignore env-access: the Prisma CLI needs the full environment
+		env: { ...process.env, DATABASE_URL: url },
+	});
+}

package/templates/features/prisma/files+mysql/prisma/schema.prisma

@@ -0,0 +1,11 @@
+// Models live in prisma/models/*.prisma (one file per table).
+generator client {
+  provider            = "prisma-client"
+  output              = "../src/generated/prisma"
+  importFileExtension = "ts"
+  moduleFormat        = "esm"
+}
+
+datasource db {
+  provider = "mysql"
+}

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

@@ -0,0 +1,23 @@
+import { PrismaMariaDb } from "@prisma/adapter-mariadb";
+import { env } from "#core/config/env";
+import { connectionConfig } from "#core/db/admin";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import { type Prisma, PrismaClient } from "#generated/prisma/client";
+
+export const db = new PrismaClient({
+	adapter: new PrismaMariaDb({
+		...connectionConfig(env.DATABASE_URL),
+		connectionLimit: env.DATABASE_POOL_MAX,
+	}),
+});
+
+export type Database = typeof db;
+export type Transaction = Prisma.TransactionClient;
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await db.$queryRaw`SELECT 1`;
+});
+onShutdown("database", () => db.$disconnect());

package/templates/features/prisma/files+postgres/prisma/schema.prisma

@@ -0,0 +1,11 @@
+// Models live in prisma/models/*.prisma (one file per table).
+generator client {
+  provider            = "prisma-client"
+  output              = "../src/generated/prisma"
+  importFileExtension = "ts"
+  moduleFormat        = "esm"
+}
+
+datasource db {
+  provider = "postgresql"
+}

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

@@ -0,0 +1,19 @@
+import { PrismaPg } from "@prisma/adapter-pg";
+import { env } from "#core/config/env";
+import { registerReadinessCheck } from "#core/http/health";
+import { onShutdown } from "#core/process/lifecycle";
+import { type Prisma, PrismaClient } from "#generated/prisma/client";
+
+export const db = new PrismaClient({
+	adapter: new PrismaPg({ connectionString: env.DATABASE_URL, max: env.DATABASE_POOL_MAX }),
+});
+
+export type Database = typeof db;
+export type Transaction = Prisma.TransactionClient;
+/** `db` or an open transaction; services take an Executor so callers can compose them. */
+export type Executor = Database | Transaction;
+
+registerReadinessCheck("database", async () => {
+	await db.$queryRaw`SELECT 1`;
+});
+onShutdown("database", () => db.$disconnect());

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

@@ -0,0 +1,18 @@
+import { defineCommand } from "#core/commands/define";
+import { env } from "#core/config/env";
+import { storage } from "#core/storage/index";
+import { ensureBucket } from "#core/storage/s3";
+
+export default defineCommand({
+	name: "storage:check",
+	description: "Create the bucket if needed, then write, read and delete a probe object",
+	async run(_args, { logger }) {
+		if (env.STORAGE_DRIVER === "s3" && (await ensureBucket())) logger.info({ bucket: env.S3_BUCKET }, "bucket created");
+		const key = `tatara-check/${Date.now()}.txt`;
+		await storage.put(key, "ok", "text/plain");
+		const body = await storage.get(key);
+		await storage.delete(key);
+		if (new TextDecoder().decode(body ?? new Uint8Array()) !== "ok") throw new Error("storage round-trip failed");
+		logger.info({ driver: env.STORAGE_DRIVER }, "storage OK");
+	},
+});

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

@@ -0,0 +1,8 @@
+import { env } from "#core/config/env";
+import { localStorage } from "#core/storage/local";
+import { s3Storage } from "#core/storage/s3";
+import type { Storage } from "#core/storage/storage";
+
+export type { Storage } from "#core/storage/storage";
+
+export const storage: Storage = env.STORAGE_DRIVER === "s3" ? s3Storage() : localStorage();

package/templates/features/storage/files/src/core/storage/local.ts

@@ -0,0 +1,34 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+import { env } from "#core/config/env";
+import { assertKey, type Storage } from "#core/storage/storage";
+
+/** Files on disk; for development and tests. */
+export function localStorage(root = env.STORAGE_LOCAL_DIR): Storage {
+	const base = resolve(root);
+	const path = (key: string) => {
+		const full = resolve(base, assertKey(key));
+		if (!full.startsWith(base + sep)) throw new Error(`Invalid storage key "${key}"`);
+		return full;
+	};
+	return {
+		async put(key, body) {
+			await mkdir(dirname(path(key)), { recursive: true });
+			await writeFile(path(key), body);
+		},
+		async get(key) {
+			try {
+				return new Uint8Array(await readFile(path(key)));
+			} catch (error) {
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+				throw error;
+			}
+		},
+		async delete(key) {
+			await rm(path(key), { force: true });
+		},
+		async url(key) {
+			return `file://${path(key)}`;
+		},
+	};
+}

package/templates/features/storage/files/src/core/storage/s3.ts

@@ -0,0 +1,66 @@
+import {
+	CreateBucketCommand,
+	DeleteObjectCommand,
+	GetObjectCommand,
+	HeadBucketCommand,
+	NoSuchKey,
+	PutObjectCommand,
+	S3Client,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { env } from "#core/config/env";
+import { assertKey, type Storage } from "#core/storage/storage";
+
+export const s3 = new S3Client({
+	region: env.S3_REGION,
+	...(env.S3_ENDPOINT ? { endpoint: env.S3_ENDPOINT } : {}),
+	forcePathStyle: env.S3_FORCE_PATH_STYLE,
+	...(env.S3_ACCESS_KEY_ID && env.S3_SECRET_ACCESS_KEY
+		? { credentials: { accessKeyId: env.S3_ACCESS_KEY_ID, secretAccessKey: env.S3_SECRET_ACCESS_KEY } }
+		: {}),
+});
+
+/** Any S3-compatible store (AWS S3, R2, RustFS locally). */
+export function s3Storage(bucket = env.S3_BUCKET): Storage {
+	let bucketReady: Promise<boolean> | undefined;
+	return {
+		async put(key, body, contentType) {
+			// local development: create the bucket on first write
+			if (env.NODE_ENV === "development") {
+				bucketReady ??= ensureBucket(bucket);
+				await bucketReady;
+			}
+			await s3.send(
+				new PutObjectCommand({ Bucket: bucket, Key: assertKey(key), Body: body, ContentType: contentType }),
+			);
+		},
+		async get(key) {
+			try {
+				const res = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: assertKey(key) }));
+				return res.Body ? await res.Body.transformToByteArray() : null;
+			} catch (error) {
+				if (error instanceof NoSuchKey) return null;
+				throw error;
+			}
+		},
+		async delete(key) {
+			await s3.send(new DeleteObjectCommand({ Bucket: bucket, Key: assertKey(key) }));
+		},
+		async url(key, expiresInSeconds = 900) {
+			return getSignedUrl(s3, new GetObjectCommand({ Bucket: bucket, Key: assertKey(key) }), {
+				expiresIn: expiresInSeconds,
+			});
+		},
+	};
+}
+
+/** Creates the bucket when it does not exist (local development). */
+export async function ensureBucket(bucket = env.S3_BUCKET): Promise<boolean> {
+	try {
+		await s3.send(new HeadBucketCommand({ Bucket: bucket }));
+		return false;
+	} catch {
+		await s3.send(new CreateBucketCommand({ Bucket: bucket }));
+		return true;
+	}
+}

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

@@ -0,0 +1,21 @@
+/** Object storage used by modules; pick the driver with STORAGE_DRIVER. */
+export interface Storage {
+	put(key: string, body: Uint8Array | string, contentType?: string): Promise<void>;
+	get(key: string): Promise<Uint8Array | null>;
+	delete(key: string): Promise<void>;
+	/** a URL clients can fetch the object from (signed for S3) */
+	url(key: string, expiresInSeconds?: number): Promise<string>;
+}
+
+/** Keys are relative, forward-slash paths without "..", backslashes, NUL bytes or drive prefixes. */
+export function assertKey(key: string): string {
+	const invalid =
+		!key ||
+		key.startsWith("/") ||
+		key.includes("\\") ||
+		key.includes("\0") ||
+		/^[A-Za-z]:/.test(key) ||
+		key.split("/").some((segment) => segment === ".." || segment === ".");
+	if (invalid) throw new Error(`Invalid storage key "${key}"`);
+	return key;
+}

package/templates/features/storage/files/src/core/storage/tests/storage.test.ts

@@ -0,0 +1,22 @@
+import { mkdtemp } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { localStorage } from "#core/storage/local";
+
+describe("local storage", () => {
+	it("round-trips an object", async () => {
+		const store = localStorage(await mkdtemp(join(tmpdir(), "storage-")));
+		await store.put("a/b.txt", "hello");
+		expect(new TextDecoder().decode((await store.get("a/b.txt")) ?? new Uint8Array())).toBe("hello");
+		await store.delete("a/b.txt");
+		expect(await store.get("a/b.txt")).toBeNull();
+	});
+
+	it("rejects keys that escape the root", async () => {
+		const store = localStorage(await mkdtemp(join(tmpdir(), "storage-")));
+		for (const key of ["../x", "a/../../x", "a\\..\\x", "/etc/passwd", "C:/x", "a/\0b"]) {
+			await expect(store.put(key, "no")).rejects.toThrow(/Invalid storage key/);
+		}
+	});
+});

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

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { defineCommand } from "#core/commands/define";
+
+export default defineCommand({
+	name: "__moduleKebab__:__nameKebab__",
+	description: "__nameTitle__",
+	args: z.object({ dryRun: z.coerce.boolean().default(false) }),
+	async run({ dryRun }, { logger }) {
+		logger.info({ dryRun }, "__moduleKebab__:__nameKebab__ ran");
+	},
+});

package/templates/generators/consumer/files/src/modules/__moduleKebab__/consumers/__nameKebab__.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { defineConsumer } from "#core/jobs/define";
+
+export const __nameCamel__Payload = z.object({ id: z.string().min(1) });
+
+export default defineConsumer({
+	topic: "__moduleKebab__.__nameKebab__",
+	description: "__nameTitle__",
+	schema: __nameCamel__Payload,
+	async handle({ id }, { logger }) {
+		// must be idempotent: a job can run more than once
+		logger.info({ id }, "__moduleKebab__.__nameKebab__ handled");
+	},
+});

package/templates/generators/consumer/files/src/modules/__moduleKebab__/tests/__nameKebab__.consumer.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { processJob } from "#core/jobs/process";
+import { logger } from "#core/logging/logger";
+import { consumers } from "#generated/consumers";
+
+describe("__moduleKebab__.__nameKebab__", () => {
+	it("handles a valid payload", async () => {
+		await expect(
+			processJob(consumers, "__moduleKebab__.__nameKebab__", { id: "1" }, { logger, jobId: "t", attempt: 1 }),
+		).resolves.toBeUndefined();
+	});
+});

package/templates/generators/module/files/src/modules/__moduleKebab__/routes/__moduleKebab__.routes.ts

@@ -0,0 +1,20 @@
+import { createRoute } from "@hono/zod-openapi";
+import { jsonContent, success, successSchema } from "#core/http/response";
+import { createRouter, defineRoutes } from "#core/http/routes";
+import { __moduleCamel__Status } from "#modules/__moduleKebab__/services/__moduleKebab__.service";
+import { __moduleCamel__StatusSchema } from "#modules/__moduleKebab__/validators/__moduleKebab__.validators";
+
+const router = createRouter();
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/status",
+		tags: ["__modulePascal__"],
+		summary: "__moduleTitle__ module status",
+		responses: { 200: jsonContent(successSchema(__moduleCamel__StatusSchema), "Status") },
+	}),
+	(c) => c.json(success(__moduleCamel__Status()), 200),
+);
+
+export default defineRoutes({ app: "api", basePath: "/__moduleKebab__", router });

package/templates/generators/module/files/src/modules/__moduleKebab__/services/__moduleKebab__.service.ts

@@ -0,0 +1,4 @@
+/** Business logic for the __moduleKebab__ module: plain functions, no HTTP. */
+export function __moduleCamel__Status(): { module: string; status: "ok" } {
+	return { module: "__moduleKebab__", status: "ok" };
+}

package/templates/generators/module/files/src/modules/__moduleKebab__/tests/__moduleKebab__.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { api } from "#tests/helpers/api";
+
+describe("__moduleKebab__", () => {
+	it("reports status", async () => {
+		const res = await api.get("/api/__moduleKebab__/status");
+		expect(res.status).toBe(200);
+		expect(res.body).toEqual({ success: true, data: { module: "__moduleKebab__", status: "ok" } });
+	});
+});

package/templates/generators/module/files/src/modules/__moduleKebab__/validators/__moduleKebab__.validators.ts

@@ -0,0 +1,5 @@
+import { z } from "@hono/zod-openapi";
+
+export const __moduleCamel__StatusSchema = z
+	.object({ module: z.string(), status: z.literal("ok") })
+	.openapi("__modulePascal__Status");

package/templates/generators/permission/files/src/modules/__moduleKebab__/permissions/__nameKebab__.permissions.ts

@@ -0,0 +1,18 @@
+import { definePermissions } from "#core/authz/catalog";
+
+export default definePermissions({
+	resources: {
+		"__nameKebab__": {
+			// scoped actions are checked at own | team | org; use resolveScope() in the service
+			read: { scoped: true },
+			manage: { scoped: false },
+		},
+	},
+	roleGrants: {
+		admin: [
+			["__nameKebab__", "read", "org"],
+			["__nameKebab__", "manage"],
+		],
+		member: [["__nameKebab__", "read", "own"]],
+	},
+});

package/templates/generators/resource/files/src/modules/__moduleKebab__/routes/__nameKebab__.routes.ts

@@ -0,0 +1,126 @@
+import { createRoute } from "@hono/zod-openapi";
+import {
+	errorResponses,
+	jsonContent,
+	paginated,
+	paginatedSchema,
+	paginationQuerySchema,
+	success,
+	successSchema,
+} from "#core/http/response";
+import { createRouter, defineRoutes } from "#core/http/routes";
+// tatara:slot imports
+import {
+	create__namePascal__,
+	get__namePascal__,
+	list__namePluralPascal__,
+	remove__namePascal__,
+	update__namePascal__,
+} from "#modules/__moduleKebab__/services/__nameKebab__.service";
+import {
+	__nameCamel__ParamsSchema,
+	__nameCamel__Schema,
+	create__namePascal__Schema,
+	update__namePascal__Schema,
+} from "#modules/__moduleKebab__/validators/__nameKebab__.validators";
+
+const router = createRouter();
+const tags = ["__namePluralPascal__"];
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/",
+		tags,
+		summary: "List __namePluralKebab__",
+		// tatara:slot guard-list
+		request: { query: paginationQuerySchema },
+		responses: {
+			200: jsonContent(paginatedSchema(__nameCamel__Schema), "A page of __namePluralKebab__"),
+			...errorResponses(400),
+			// tatara:slot auth-errors
+		},
+	}),
+	async (c) => {
+		const query = c.req.valid("query");
+		const { items, total } = await list__namePluralPascal__(query);
+		return c.json(paginated(items, query.page, query.pageSize, total), 200);
+	},
+);
+
+router.openapi(
+	createRoute({
+		method: "get",
+		path: "/{id}",
+		tags,
+		summary: "Get a __nameKebab__",
+		// tatara:slot guard-read
+		request: { params: __nameCamel__ParamsSchema },
+		responses: {
+			200: jsonContent(successSchema(__nameCamel__Schema), "The __nameKebab__"),
+			...errorResponses(400, 404),
+			// tatara:slot auth-errors
+		},
+	}),
+	async (c) => c.json(success(await get__namePascal__(c.req.valid("param").id)), 200),
+);
+
+router.openapi(
+	createRoute({
+		method: "post",
+		path: "/",
+		tags,
+		summary: "Create a __nameKebab__",
+		// tatara:slot guard-create
+		request: { body: jsonContent(create__namePascal__Schema, "The new __nameKebab__") },
+		responses: {
+			201: jsonContent(successSchema(__nameCamel__Schema), "Created"),
+			...errorResponses(400),
+			// tatara:slot auth-errors
+		},
+	}),
+	async (c) => c.json(success(await create__namePascal__(c.req.valid("json"))), 201),
+);
+
+router.openapi(
+	createRoute({
+		method: "patch",
+		path: "/{id}",
+		tags,
+		summary: "Update a __nameKebab__",
+		// tatara:slot guard-update
+		request: {
+			params: __nameCamel__ParamsSchema,
+			body: jsonContent(update__namePascal__Schema, "Fields to change"),
+		},
+		responses: {
+			200: jsonContent(successSchema(__nameCamel__Schema), "Updated"),
+			...errorResponses(400, 404),
+			// tatara:slot auth-errors
+		},
+	}),
+	async (c) =>
+		c.json(success(await update__namePascal__(c.req.valid("param").id, c.req.valid("json"))), 200),
+);
+
+router.openapi(
+	createRoute({
+		method: "delete",
+		path: "/{id}",
+		tags,
+		summary: "Delete a __nameKebab__",
+		// tatara:slot guard-delete
+		request: { params: __nameCamel__ParamsSchema },
+		responses: {
+			204: { description: "Deleted" },
+			...errorResponses(400, 404),
+			// tatara:slot auth-errors
+		},
+	}),
+	async (c) => {
+		await remove__namePascal__(c.req.valid("param").id);
+		return c.body(null, 204);
+	},
+);
+
+export default defineRoutes({ app: "api", basePath: "/__namePluralKebab__", router });

package/templates/generators/resource/files/src/modules/__moduleKebab__/tests/__nameKebab__.routes.test.ts

@@ -0,0 +1,59 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { api } from "#tests/helpers/api";
+import { resetDatabase } from "#tests/helpers/db";
+// tatara:slot test-imports
+
+const path = "/api/__namePluralKebab__";
+const headers: Record<string, string> = {};
+
+interface __namePascal__Body {
+	data: { id: string; name: string; description: string | null };
+}
+
+beforeEach(async () => {
+	await resetDatabase();
+	// tatara:slot test-auth
+});
+
+describe("__namePluralKebab__", () => {
+	it("creates, reads, updates, lists and deletes", async () => {
+		const created = await api.post<__namePascal__Body>(path, { name: "First" }, { headers });
+		expect(created.status).toBe(201);
+		const { id } = created.body.data;
+		expect(created.body.data).toMatchObject({ name: "First", description: null });
+
+		const read = await api.get<__namePascal__Body>(`${path}/${id}`, { headers });
+		expect(read.status).toBe(200);
+		expect(read.body.data.id).toBe(id);
+
+		const updated = await api.patch<__namePascal__Body>(
+			`${path}/${id}`,
+			{ description: "Changed" },
+			{ headers },
+		);
+		expect(updated.status).toBe(200);
+		expect(updated.body.data).toMatchObject({ name: "First", description: "Changed" });
+
+		await api.post(path, { name: "Second" }, { headers });
+		const list = await api.get<{ data: { name: string }[]; meta: { total: number } }>(
+			`${path}?pageSize=10`,
+			{ headers },
+		);
+		expect(list.status).toBe(200);
+		expect(list.body.meta.total).toBe(2);
+		expect(list.body.data.map((item) => item.name)).toEqual(["Second", "First"]);
+
+		const removed = await api.delete(`${path}/${id}`, { headers });
+		expect(removed.status).toBe(204);
+		const gone = await api.get(`${path}/${id}`, { headers });
+		expect(gone.status).toBe(404);
+	});
+
+	it("rejects invalid input", async () => {
+		const res = await api.post(path, { name: "" }, { headers });
+		expect(res.status).toBe(400);
+		expect(res.body).toMatchObject({ success: false, code: "VALIDATION_ERROR" });
+	});
+
+	// tatara:slot test-cases
+});