@tatara/cli 0.0.0-stage → 0.1.0

package/templates/features/authz/files+prisma/prisma/models/authz.prisma

@@ -0,0 +1,75 @@
+// Permission system tables. scope "" = unscoped; built-in roles have org_id "".
+
+model AuthzRole {
+  id          String                 @id @db.VarChar(36)
+  orgId       String                 @default("") @map("org_id") @db.VarChar(255)
+  key         String                 @db.VarChar(64)
+  name        String                 @db.VarChar(120)
+  description String?                @db.Text
+  isSystem    Boolean                @default(false) @map("is_system")
+  createdAt   DateTime               @default(now()) @map("created_at")
+  updatedAt   DateTime               @default(now()) @updatedAt @map("updated_at")
+  permissions AuthzRolePermission[]
+  members     AuthzMemberRole[]
+
+  @@unique([orgId, key], map: "authz_roles_org_key")
+  @@map("authz_roles")
+}
+
+model AuthzRolePermission {
+  id       String    @id @db.VarChar(36)
+  roleId   String    @map("role_id") @db.VarChar(36)
+  role     AuthzRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  resource String    @db.VarChar(64)
+  action   String    @db.VarChar(64)
+  scope    String    @default("") @db.VarChar(16)
+
+  @@unique([roleId, resource, action, scope], map: "authz_role_permissions_grant")
+  @@map("authz_role_permissions")
+}
+
+model AuthzMemberRole {
+  id         String    @id @db.VarChar(36)
+  orgId      String    @map("org_id") @db.VarChar(255)
+  userId     String    @map("user_id") @db.VarChar(255)
+  roleId     String    @map("role_id") @db.VarChar(36)
+  role       AuthzRole @relation(fields: [roleId], references: [id], onDelete: Cascade)
+  assignedBy String?   @map("assigned_by") @db.VarChar(255)
+  assignedAt DateTime  @default(now()) @map("assigned_at")
+
+  @@unique([orgId, userId, roleId], map: "authz_member_roles_member_role")
+  @@index([orgId, userId], map: "authz_member_roles_member")
+  @@map("authz_member_roles")
+}
+
+model AuthzOverlay {
+  id        String    @id @db.VarChar(36)
+  orgId     String    @map("org_id") @db.VarChar(255)
+  userId    String    @map("user_id") @db.VarChar(255)
+  resource  String    @db.VarChar(64)
+  action    String    @db.VarChar(64)
+  scope     String    @default("") @db.VarChar(16)
+  effect    String    @db.VarChar(8)
+  grantedBy String?   @map("granted_by") @db.VarChar(255)
+  reason    String?   @db.Text
+  expiresAt DateTime? @map("expires_at")
+  createdAt DateTime  @default(now()) @map("created_at")
+
+  @@unique([orgId, userId, resource, action, scope, effect], map: "authz_overlays_grant")
+  @@index([orgId, userId], map: "authz_overlays_member")
+  @@map("authz_overlays")
+}
+
+model AuthzAuditLog {
+  id           String   @id @db.VarChar(36)
+  orgId        String   @map("org_id") @db.VarChar(255)
+  actorId      String   @map("actor_id") @db.VarChar(255)
+  targetUserId String?  @map("target_user_id") @db.VarChar(255)
+  changeType   String   @map("change_type") @db.VarChar(48)
+  before       String?  @db.Text
+  after        String?  @db.Text
+  at           DateTime @default(now())
+
+  @@index([orgId, at], map: "authz_audit_log_org_at")
+  @@map("authz_audit_log")
+}

package/templates/features/authz/files+prisma/src/core/authz/db/store.ts

@@ -0,0 +1,229 @@
+import type { OverlayEffect, Scope } from "#core/authz/constants";
+import { SYSTEM_ORG_ID } from "#core/authz/constants";
+import type { AuthzStore, OverlayRow, PermissionGrant, RoleRow } from "#core/authz/types";
+import { db } from "#core/db/client";
+import { newId } from "#core/db/id";
+
+const toScope = (scope: string): Scope | null => (scope === "" ? null : (scope as Scope));
+
+interface OverlayRecord {
+	id: string;
+	orgId: string;
+	userId: string;
+	resource: string;
+	action: string;
+	scope: string;
+	effect: string;
+	grantedBy: string | null;
+	reason: string | null;
+	expiresAt: Date | null;
+	createdAt: Date;
+}
+
+function toOverlay(row: OverlayRecord): OverlayRow {
+	return { ...row, scope: toScope(row.scope), effect: row.effect as OverlayEffect };
+}
+
+const roleInclude = (orgId: string) => ({
+	permissions: true,
+	_count: { select: { members: { where: { orgId } } } },
+});
+
+interface RoleRecord {
+	id: string;
+	orgId: string;
+	key: string;
+	name: string;
+	description: string | null;
+	isSystem: boolean;
+	permissions: { resource: string; action: string; scope: string }[];
+	_count: { members: number };
+}
+
+function toRole(role: RoleRecord): RoleRow {
+	return {
+		id: role.id,
+		orgId: role.orgId,
+		key: role.key,
+		name: role.name,
+		description: role.description,
+		isSystem: role.isSystem,
+		grants: role.permissions.map((g) => ({
+			resource: g.resource,
+			action: g.action,
+			scope: toScope(g.scope),
+		})),
+		memberCount: role._count.members,
+	};
+}
+
+const grantRows = (grants: PermissionGrant[]) =>
+	grants.map((g) => ({ id: newId(), resource: g.resource, action: g.action, scope: g.scope ?? "" }));
+
+export const store: AuthzStore = {
+	async roleGrants(orgId, userId, impliedRoleKeys) {
+		const roles = await db.authzRole.findMany({
+			where: {
+				OR: [
+					{ members: { some: { orgId, userId } } },
+					...(impliedRoleKeys.length
+						? [{ orgId: SYSTEM_ORG_ID, key: { in: impliedRoleKeys } }]
+						: []),
+				],
+			},
+			include: { permissions: true },
+		});
+		return {
+			roles: roles.map((r) => r.key),
+			grants: roles.flatMap((r) =>
+				r.permissions.map((g) => ({ resource: g.resource, action: g.action, scope: toScope(g.scope) })),
+			),
+		};
+	},
+
+	async activeOverlays(orgId, userId, now) {
+		const rows = await db.authzOverlay.findMany({
+			where: { orgId, userId, OR: [{ expiresAt: null }, { expiresAt: { gt: now } }] },
+		});
+		return rows.map(toOverlay);
+	},
+
+	async listRoles(orgId) {
+		const roles = await db.authzRole.findMany({
+			where: { orgId: { in: [SYSTEM_ORG_ID, orgId] } },
+			include: roleInclude(orgId),
+			orderBy: { key: "asc" },
+		});
+		return roles.map(toRole);
+	},
+
+	async findRole(orgId, roleId) {
+		const role = await db.authzRole.findFirst({
+			where: { id: roleId, orgId: { in: [SYSTEM_ORG_ID, orgId] } },
+			include: roleInclude(orgId),
+		});
+		return role ? toRole(role) : null;
+	},
+
+	async findRoleByKey(orgId, key) {
+		const role = await db.authzRole.findFirst({ where: { key, orgId }, include: roleInclude(orgId) });
+		return role ? toRole(role) : null;
+	},
+
+	async createRole(input) {
+		const id = newId();
+		await db.authzRole.create({
+			data: {
+				id,
+				orgId: input.orgId,
+				key: input.key,
+				name: input.name,
+				description: input.description,
+				isSystem: input.isSystem,
+				permissions: { create: grantRows(input.grants) },
+			},
+		});
+		return id;
+	},
+
+	async updateRole(roleId, input) {
+		await db.$transaction(async (tx) => {
+			await tx.authzRole.update({
+				where: { id: roleId },
+				data: {
+					...(input.name === undefined ? {} : { name: input.name }),
+					...(input.description === undefined ? {} : { description: input.description }),
+				},
+			});
+			if (input.grants) {
+				await tx.authzRolePermission.deleteMany({ where: { roleId } });
+				await tx.authzRolePermission.createMany({
+					data: grantRows(input.grants).map((g) => ({ ...g, roleId })),
+				});
+			}
+		});
+	},
+
+	async deleteRole(roleId) {
+		await db.authzRole.delete({ where: { id: roleId } });
+	},
+
+	async memberRoles(orgId, userId) {
+		const roles = await db.authzRole.findMany({
+			where: { members: { some: { orgId, userId } } },
+			include: roleInclude(orgId),
+		});
+		return roles.map(toRole);
+	},
+
+	async assignRole(orgId, userId, roleId, by) {
+		const existing = await db.authzMemberRole.findFirst({ where: { orgId, userId, roleId } });
+		if (existing) return false;
+		await db.authzMemberRole.create({ data: { id: newId(), orgId, userId, roleId, assignedBy: by } });
+		return true;
+	},
+
+	async revokeRole(orgId, userId, roleId) {
+		const { count } = await db.authzMemberRole.deleteMany({ where: { orgId, userId, roleId } });
+		return count > 0;
+	},
+
+	async listOverlays(orgId, userId) {
+		const rows = await db.authzOverlay.findMany({
+			where: { orgId, userId },
+			orderBy: { createdAt: "desc" },
+		});
+		return rows.map(toOverlay);
+	},
+
+	async addOverlay(input) {
+		const id = newId();
+		const scope = input.scope ?? "";
+		await db.authzOverlay.deleteMany({
+			where: {
+				orgId: input.orgId,
+				userId: input.userId,
+				resource: input.resource,
+				action: input.action,
+				scope,
+				effect: input.effect,
+			},
+		});
+		await db.authzOverlay.create({ data: { ...input, id, scope } });
+		return id;
+	},
+
+	async removeOverlay(orgId, userId, overlayId) {
+		const row = await db.authzOverlay.findFirst({ where: { id: overlayId, orgId, userId } });
+		if (!row) return null;
+		await db.authzOverlay.deleteMany({ where: { id: overlayId, orgId, userId } });
+		return toOverlay(row);
+	},
+
+	async writeAudit(input) {
+		await db.authzAuditLog.create({
+			data: {
+				id: newId(),
+				orgId: input.orgId,
+				actorId: input.actorId,
+				targetUserId: input.targetUserId,
+				changeType: input.changeType,
+				before: input.before === undefined ? null : JSON.stringify(input.before),
+				after: input.after === undefined ? null : JSON.stringify(input.after),
+			},
+		});
+	},
+
+	async listAudit(orgId, limit) {
+		const rows = await db.authzAuditLog.findMany({
+			where: { orgId },
+			orderBy: { id: "desc" },
+			take: limit,
+		});
+		return rows.map((r) => ({
+			...r,
+			before: r.before ? (JSON.parse(r.before) as unknown) : null,
+			after: r.after ? (JSON.parse(r.after) as unknown) : null,
+		}));
+	},
+};

package/templates/features/base/files/AGENTS.md

@@ -0,0 +1,69 @@
+# __APP_NAME__ — working agreement
+
+Read this before changing code. It applies to people and coding agents alike.
+
+## Definition of done
+
+- A change is done when `__PM_RUN__ verify` exits 0 (lint + layout + typecheck + tests + build).
+- Never disable, skip or weaken a test, a type or a lint rule to make it pass. Fix the code.
+- Report what you ran and its result, not that something "should work".
+
+## Layout
+
+```
+src/apps/<name>/        one folder per process; thin wiring only
+src/core/<area>/        shared infrastructure; never imports from modules
+src/modules/<module>/   business code, one folder per domain
+src/generated/          written by `tatara sync`; never edit or commit
+tests/                  shared test helpers and setup
+```
+
+A module holds `routes/`, `services/`, `validators/`, and optionally `db/`, `commands/`
+and other folders described below. Business logic lives in `services/`: plain functions
+with no knowledge of Hono. Routes validate input, call services and shape the response.
+
+Rules enforced by `tatara check` (part of lint):
+
+- Import with `#core/…`, `#modules/…`, `#apps/…`, `#generated/…`, `#tests/…`; no `../` imports.
+- `src/core` never imports from `src/modules`.
+- A module uses another module only through its `services/`.
+- Module routers never call `use("*")`; attach middleware per route or per path.
+- `process.env` is read only in `src/core/config/env.ts`.
+
+## Generators
+
+Prefer generators to hand-writing boilerplate; they only add files and never overwrite:
+
+```
+__PM_EXEC__ tatara make module <name>
+__PM_EXEC__ tatara make resource <name> --module <module>   # CRUD slice
+__PM_EXEC__ tatara make route|service|command <name> --module <module>
+__PM_EXEC__ tatara run --list            # app commands
+__PM_EXEC__ tatara routes                # every route and what protects it
+```
+
+## HTTP
+
+- Every route uses `createRoute` from `@hono/zod-openapi`, with request and response schemas.
+  The spec is served at `/openapi.json`, the reference UI at `/docs`.
+- Responses use the envelope: `success(data)`, `paginated(items, page, pageSize, total)`.
+  Errors are thrown as `AppError` subclasses (`NotFoundError`, `ConflictError`,
+  `BusinessRuleError`, `ForbiddenError`, …) and become
+  `{ success: false, error, code, details }`.
+- Route files are `routes/<name>.routes.ts` and default-export `defineRoutes({ app, basePath, router })`.
+  They are found automatically; there is no central list to edit.
+
+## Configuration and logging
+
+- Add environment variables to `src/core/config/env.ts` (validated at startup) and to
+  `.env.example`. Never read `process.env` elsewhere.
+- Log with `c.get("logger")` in requests and `logger` from `#core/logging/logger` elsewhere.
+  No `console.*` outside commands and tests.
+
+## Tests
+
+- Tests live next to the code in `src/modules/<module>/tests/`. Use `api` from
+  `#tests/helpers/api` to call routes in-process.
+- Test behaviour through the public surface (routes, services); mock only external services.
+
+<!-- tatara:slot sections -->

package/templates/features/base/files/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/features/base/files/Dockerfile

@@ -0,0 +1,15 @@
+# One image for every entrypoint. Default: the API.
+# Other processes: override the command, e.g. `node dist/apps/worker/index.mjs`.
+FROM node:24-alpine AS base
+WORKDIR /app
+# tatara:slot docker-base
+
+FROM base AS build
+# tatara:slot docker-build
+
+FROM base AS runtime
+ENV NODE_ENV=production
+# tatara:slot docker-runtime
+USER node
+EXPOSE 3000
+CMD ["node", "dist/apps/api/server.mjs"]

package/templates/features/base/files/README.md

@@ -0,0 +1,31 @@
+# __APP_NAME__
+
+A Hono API created with [tatara](https://github.com/mohammed-bageri/tatara).
+
+## Getting started
+
+```sh
+__PM_RUN__ dev
+```
+
+This starts the local services, prepares the database and runs every process with
+reload. Then open:
+
+- API: http://localhost:3000/api
+- API reference: http://localhost:3000/docs
+- Health: http://localhost:3000/health
+
+## Scripts
+
+| Script | What it does |
+|---|---|
+| `dev` | Start local services and every process in watch mode |
+| `dev:down` / `dev:reset` | Stop local services / stop and delete their data |
+| `verify` | Lint, layout checks, typecheck, tests and build |
+| `test` | Run tests |
+| `build` | Bundle to `dist/` |
+| `start` | Run the built API |
+
+Conventions are in [AGENTS.md](./AGENTS.md).
+
+<!-- tatara:slot readme -->

package/templates/features/base/files/_github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # tatara:slot ci-setup
+      - run: cp .env.example .env
+      # tatara:slot ci-services
+      - run: __PM_RUN__ verify

package/templates/features/base/files/biome.template.json

@@ -0,0 +1,20 @@
+{
+	"$schema": "https://biomejs.dev/schemas/__BIOME_VERSION__/schema.json",
+	"files": {
+		"includes": ["**", "!**/node_modules", "!**/dist", "!**/coverage", "!src/generated", "!drizzle", "!prisma/migrations"]
+	},
+	"formatter": { "indentStyle": "tab", "lineWidth": 100 },
+	"javascript": { "formatter": { "quoteStyle": "double" } },
+	"linter": {
+		"rules": {
+			"style": { "useImportType": "error" },
+			"suspicious": { "noConsole": "error" }
+		}
+	},
+	"overrides": [
+		{
+			"includes": ["src/apps/cli/**", "src/**/commands/**", "tests/**", "*.config.ts"],
+			"linter": { "rules": { "suspicious": { "noConsole": "off" } } }
+		}
+	]
+}

package/templates/features/base/files/dockerignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+coverage
+src/generated
+.env
+.env.*
+!.env.example
+.git

package/templates/features/base/files/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+dist/
+coverage/
+src/generated/
+.env
+.env.local
+*.log
+.DS_Store
+# tatara:slot ignore

package/templates/features/base/files/src/apps/api/app.ts

@@ -0,0 +1,3 @@
+import { createHttpApp } from "#core/http/app";
+
+export const app = createHttpApp("api", { title: "__APP_NAME__ API" });

package/templates/features/base/files/src/apps/api/server.ts

@@ -0,0 +1,5 @@
+import { app } from "#apps/api/app";
+import { env } from "#core/config/env";
+import { startServer } from "#core/http/server";
+
+startServer(app, env.PORT, "api");

package/templates/features/base/files/src/apps/cli/index.ts

@@ -0,0 +1,6 @@
+import { runCommand } from "#core/commands/runner";
+import { shutdown } from "#core/process/lifecycle";
+import { commands } from "#generated/commands";
+
+const code = await runCommand(commands, process.argv.slice(2));
+await shutdown(code);

package/templates/features/base/files/src/core/commands/define.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { Logger } from "#core/logging/logger";
+
+export interface CommandContext {
+	logger: Logger;
+}
+
+export interface CommandDefinition<S extends z.ZodType = z.ZodType> {
+	/** `module:action`, e.g. "billing:recalculate" */
+	name: string;
+	description: string;
+	/** flags parsed from `--key value`; use z.coerce for numbers and booleans */
+	args?: S;
+	run(args: z.infer<S>, ctx: CommandContext): Promise<void> | void;
+}
+
+
+/** Default export of every `commands/*.ts`; discovered by `tatara sync`. */
+export function defineCommand<S extends z.ZodType = typeof noArgs>(
+	definition: CommandDefinition<S>,
+): CommandDefinition<S> {
+	return definition;
+}
+
+export const noArgs = z.object({});

package/templates/features/base/files/src/core/commands/runner.ts

@@ -0,0 +1,54 @@
+import type { CommandDefinition } from "#core/commands/define";
+import { logger } from "#core/logging/logger";
+
+/** Parses `--key value`, `--key=value` and bare `--flag` (true) into an object. */
+export function parseFlags(argv: string[]): Record<string, string | boolean> {
+	const flags: Record<string, string | boolean> = {};
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i] ?? "";
+		if (!arg.startsWith("--")) continue;
+		const [rawKey, inline] = arg.slice(2).split("=", 2);
+		const key = (rawKey ?? "").replace(/-([a-z])/g, (_, ch: string) => ch.toUpperCase());
+		if (inline !== undefined) {
+			flags[key] = inline;
+		} else if (argv[i + 1] !== undefined && !argv[i + 1]?.startsWith("--")) {
+			flags[key] = argv[i + 1] ?? "";
+			i++;
+		} else {
+			flags[key] = true;
+		}
+	}
+	return flags;
+}
+
+export async function runCommand(commands: CommandDefinition[], argv: string[]): Promise<number> {
+	const [name, ...rest] = argv;
+	if (!name || name === "--list" || name === "list" || name === "help") {
+		const width = Math.max(0, ...commands.map((c) => c.name.length));
+		console.log("Commands:");
+		for (const c of [...commands].sort((a, b) => a.name.localeCompare(b.name))) {
+			console.log(`  ${c.name.padEnd(width)}  ${c.description}`);
+		}
+		return 0;
+	}
+	const command = commands.find((c) => c.name === name);
+	if (!command) {
+		console.error(`Unknown command "${name}". Run with --list to see available commands.`);
+		return 1;
+	}
+	const parsed = (command.args ?? null)?.safeParse(parseFlags(rest));
+	if (parsed && !parsed.success) {
+		console.error(`Invalid arguments for ${name}:`);
+		for (const issue of parsed.error.issues) {
+			console.error(`  --${issue.path.join(".")}: ${issue.message}`);
+		}
+		return 1;
+	}
+	try {
+		await command.run(parsed ? parsed.data : {}, { logger: logger.child({ command: name }) });
+		return 0;
+	} catch (error) {
+		logger.error({ err: error, command: name }, "command failed");
+		return 1;
+	}
+}

package/templates/features/base/files/src/core/http/app.ts

@@ -0,0 +1,52 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Scalar } from "@scalar/hono-api-reference";
+import { bodyLimit } from "hono/body-limit";
+import { cors } from "hono/cors";
+import { secureHeaders } from "hono/secure-headers";
+import { env } from "#core/config/env";
+import type { AppEnv } from "#core/http/context";
+import { runReadinessChecks } from "#core/http/health";
+import { errorHandler, notFoundHandler } from "#core/http/middleware/error-handler";
+import { requestContext } from "#core/http/middleware/request-context";
+import { validationHook } from "#core/http/middleware/validation";
+import type { AppName } from "#core/http/routes";
+import { routes } from "#generated/routes";
+// tatara:slot imports
+
+export const API_PREFIX = "/api";
+
+export function createHttpApp(name: AppName, options: { title: string }) {
+	const app = new OpenAPIHono<AppEnv>({ defaultHook: validationHook });
+
+	app.use(requestContext);
+	app.use(secureHeaders());
+	app.use(
+		cors({
+			origin: env.CORS_ORIGINS,
+			credentials: true,
+			allowHeaders: ["Content-Type", "Authorization", "X-Request-Id", "Accept-Language"],
+			exposeHeaders: ["X-Request-Id"],
+		}),
+	);
+	app.use(bodyLimit({ maxSize: env.BODY_LIMIT_BYTES }));
+	// tatara:slot middleware
+
+	app.get("/health", (c) => c.json({ status: "ok" }));
+	app.get("/ready", async (c) => {
+		const result = await runReadinessChecks();
+		return c.json(result, result.ready ? 200 : 503);
+	});
+
+	// tatara:slot routes
+
+	for (const definition of routes) {
+		if (definition.app === name) app.route(`${API_PREFIX}${definition.basePath}`, definition.router);
+	}
+
+	app.doc31("/openapi.json", { openapi: "3.1.0", info: { title: options.title, version: "1.0.0" } });
+	app.get("/docs", Scalar({ url: "/openapi.json", pageTitle: options.title }));
+
+	app.onError(errorHandler);
+	app.notFound(notFoundHandler);
+	return app;
+}

package/templates/features/base/files/src/core/http/context.ts

@@ -0,0 +1,18 @@
+import type { Logger } from "#core/logging/logger";
+
+export interface Principal {
+	userId: string;
+	orgId: string | null;
+	roles: string[];
+	kind: "user" | "service";
+	claims: Record<string, unknown>;
+}
+
+export interface AppEnv {
+	Variables: {
+		requestId: string;
+		logger: Logger;
+		principal: Principal | null;
+		language: string;
+	};
+}