@tatara/cli 0.0.0-stage → 0.1.1

package/templates/features/authz/files+drizzle+postgres/src/core/authz/db/authz.schema.ts

@@ -0,0 +1,88 @@
+import { boolean, index, pgTable, text, timestamp, uniqueIndex, varchar } from "drizzle-orm/pg-core";
+
+const ts = () => timestamp({ withTimezone: true, mode: "date" });
+
+/** Built-in roles have orgId "" (they apply to every org); custom roles belong to one org. */
+export const authzRoles = pgTable(
+	"authz_roles",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull().default(""),
+		key: varchar({ length: 64 }).notNull(),
+		name: varchar({ length: 120 }).notNull(),
+		description: text(),
+		isSystem: boolean().notNull().default(false),
+		createdAt: ts().notNull().defaultNow(),
+		updatedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [uniqueIndex("authz_roles_org_key").on(t.orgId, t.key)],
+);
+
+/** scope "" means the action is unscoped (keeps unique keys identical on every database). */
+export const authzRolePermissions = pgTable(
+	"authz_role_permissions",
+	{
+		id: text().primaryKey(),
+		roleId: text()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+	},
+	(t) => [uniqueIndex("authz_role_permissions_grant").on(t.roleId, t.resource, t.action, t.scope)],
+);
+
+export const authzMemberRoles = pgTable(
+	"authz_member_roles",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		userId: text().notNull(),
+		roleId: text()
+			.notNull()
+			.references(() => authzRoles.id, { onDelete: "cascade" }),
+		assignedBy: text(),
+		assignedAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_member_roles_member_role").on(t.orgId, t.userId, t.roleId),
+		index("authz_member_roles_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzOverlays = pgTable(
+	"authz_overlays",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		userId: text().notNull(),
+		resource: varchar({ length: 64 }).notNull(),
+		action: varchar({ length: 64 }).notNull(),
+		scope: varchar({ length: 16 }).notNull().default(""),
+		effect: varchar({ length: 8 }).notNull(),
+		grantedBy: text(),
+		reason: text(),
+		expiresAt: ts(),
+		createdAt: ts().notNull().defaultNow(),
+	},
+	(t) => [
+		uniqueIndex("authz_overlays_grant").on(t.orgId, t.userId, t.resource, t.action, t.scope, t.effect),
+		index("authz_overlays_member").on(t.orgId, t.userId),
+	],
+);
+
+export const authzAuditLog = pgTable(
+	"authz_audit_log",
+	{
+		id: text().primaryKey(),
+		orgId: text().notNull(),
+		actorId: text().notNull(),
+		targetUserId: text(),
+		changeType: varchar({ length: 48 }).notNull(),
+		before: text(),
+		after: text(),
+		at: ts().notNull().defaultNow(),
+	},
+	(t) => [index("authz_audit_log_org_at").on(t.orgId, t.at)],
+);

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,236 @@
+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 removeMember(orgId, userId) {
+		const [roles, overlays] = await db.$transaction([
+			db.authzMemberRole.deleteMany({ where: { orgId, userId } }),
+			db.authzOverlay.deleteMany({ where: { orgId, userId } }),
+		]);
+		return { roles: roles.count, overlays: overlays.count };
+	},
+	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,71 @@
+# __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.
+  Declare request bodies with `jsonBody(schema, description)` (required; a missing body is a 400),
+  responses with `jsonContent(...)`.
+  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,16 @@
+# syntax=docker/dockerfile:1
+# 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,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+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
+
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      # catch a broken Dockerfile on the PR, not at deploy
+      - run: docker build --tag app:ci .

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,33 @@
+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 `flag()` for 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({});
+
+/**
+ * A boolean flag: bare `--force` is true, `--force false|0|no|off` is false.
+ * (`z.coerce.boolean()` would read the string "false" as true.)
+ */
+export function flag() {
+	return z.union([z.boolean(), z.stringbool()]).default(false);
+}