create-m5kdev 0.19.2 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m5kdev",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",
@@ -23,9 +23,9 @@
     "@types/jest": "30.0.0",
     "@types/node": "20.19.11",
     "jest": "30.1.3",
-    "ts-jest": "29.4.4",
+    "ts-jest": "29.4.9",
     "tsdown": "0.21.7",
-    "typescript": "5.9.2"
+    "typescript": "6.0.3"
   },
   "scripts": {
     "build": "tsdown",

package/templates/minimal-app/.cursor/rules/module-db-guide.mdc

@@ -0,0 +1,61 @@
+---
+globs: apps/*/server/src/modules/**/*.db.ts
+alwaysApply: false
+---
+
+# Module DB File Style Guide
+
+Conventions for database table definitions in app modules.
+
+## Conventions
+
+- Import enum-like constants from shared constants: `@appname/shared/modules/<module>/<module>.constants`.
+- Import auth tables for foreign keys: `import { users, organizations, teams } from "@m5kdev/backend/modules/auth/auth.db"`.
+- Define tables with Drizzle's `sqliteTable` aliased as `table`.
+- Use `uuidv4` as the default for string IDs via `.$default(uuidv4)`.
+- Represent booleans with `integer(..., { mode: "boolean" })` and `.default(false)`.
+- Represent timestamps with `integer(..., { mode: "timestamp" })`.
+  - `createdAt`: `integer("created_at", { mode: "timestamp" }).notNull().$default(() => new Date())`
+  - `updatedAt`: `integer("updated_at", { mode: "timestamp" })`
+  - `deletedAt`: `integer("deleted_at", { mode: "timestamp" })`
+- JSON columns: `text("col", { mode: "json" }).default([]).$type<string[]>()` or `.default({}).$type<Record<string, unknown>>()`.
+- Use `references(() => otherTable.id, { onDelete: "cascade" })` for non-nullable FKs and `{ onDelete: "set null" }` for nullable FKs.
+- Composite join tables define primary keys with `primaryKey({ columns: [t.aId, t.bId] })`.
+- Table names are plural; column names are snake_case at DB level, camelCase in code.
+- Inline union types are acceptable for simple status columns: `.$type<"draft" | "published">()`.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.db.ts
+```
+
+## Example
+
+```typescript
+import { organizations, teams, users } from "@m5kdev/backend/modules/auth/auth.db";
+import { integer, sqliteTable as table, text } from "drizzle-orm/sqlite-core";
+import { v4 as uuidv4 } from "uuid";
+
+export const posts = table("posts", {
+  id: text("id").primaryKey().$default(uuidv4),
+  authorUserId: text("author_user_id").references(() => users.id, {
+    onDelete: "set null",
+  }),
+  organizationId: text("organization_id").references(() => organizations.id, {
+    onDelete: "set null",
+  }),
+  teamId: text("team_id").references(() => teams.id, { onDelete: "set null" }),
+  title: text("title").notNull(),
+  slug: text("slug").notNull().unique(),
+  excerpt: text("excerpt"),
+  content: text("content").notNull(),
+  status: text("status").$type<"draft" | "published">().notNull().default("draft"),
+  publishedAt: integer("published_at", { mode: "timestamp" }),
+  createdAt: integer("created_at", { mode: "timestamp" })
+    .notNull()
+    .$default(() => new Date()),
+  updatedAt: integer("updated_at", { mode: "timestamp" }),
+  deletedAt: integer("deleted_at", { mode: "timestamp" }),
+});
+```

package/templates/minimal-app/.cursor/rules/module-grants-guide.mdc

@@ -0,0 +1,134 @@
+---
+globs: apps/*/server/src/modules/**/*.grants.ts
+alwaysApply: false
+---
+
+# Module Grants and Permission Guide
+
+Conventions for defining permission grants in app modules.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.grants.ts
+```
+
+## Core Rules
+
+- Keep grants in `<module>.grants.ts`.
+- Keep authorization checks in `<module>.service.ts` via the procedure builder's `.access()` step.
+- Action names in `.access()` and `accessGuard`/`accessGuardAsync` must exactly match action names defined in grants.
+- Prefer canonical action vocabulary: `read`, `write`, `delete`, `publish`.
+
+## Grant Structure
+
+App modules use flat `ResourceGrant[]` arrays imported from `@m5kdev/backend/modules/base/base.grants`:
+
+```typescript
+import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
+```
+
+Each `ResourceGrant` has four fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `action` | `string` | The permission action (`"read"`, `"write"`, `"delete"`, `"publish"`) |
+| `level` | `"user" \| "team" \| "organization"` | The scope level at which the grant applies |
+| `role` | `string` | The role that receives this grant (`"owner"`, `"admin"`, `"member"`) |
+| `access` | `"all" \| "own"` | `"all"` grants access to any entity; `"own"` requires ownership match |
+
+## Example
+
+```typescript
+import type { ResourceGrant } from "@m5kdev/backend/modules/base/base.grants";
+
+export const postsGrants: ResourceGrant[] = [
+  {
+    action: "write",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "publish",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "delete",
+    level: "team",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "write",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "publish",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+  {
+    action: "delete",
+    level: "organization",
+    role: "owner",
+    access: "own",
+  },
+];
+```
+
+## Wiring Grants to Services
+
+Pass the grants array as the third argument to `BasePermissionService` in the module file:
+
+```typescript
+override services({ repositories }: ModuleServicesContext<Deps, Repositories>) {
+  return {
+    posts: new PostsService({ posts: repositories.posts }, {}, postsGrants),
+  };
+}
+```
+
+## Service Integration
+
+Use `.access()` in procedure chains to enforce grants. The action string must match a grant's `action` field:
+
+```typescript
+readonly update = this.procedure<UpdateInput>("update")
+  .requireAuth()
+  .use("post", async ({ input }) => {
+    const current = await this.repository.posts.findById(input.id);
+    if (current.isErr()) return err(current.error);
+    if (!current.value || current.value.deletedAt) return this.error("NOT_FOUND");
+    return current.value;
+  })
+  .access({
+    action: "write",
+    entityStep: "post",
+  })
+  .handle(async ({ input }) => {
+    return this.repository.posts.update(input);
+  });
+```
+
+The `.access()` step supports two entity resolution modes:
+
+- `entityStep` — reads entity from a previous `.use()` or `.loadResource()` step.
+- `entities` — inline function returning `{ userId?, organizationId?, teamId? }`.
+
+## Service Choice
+
+- Use `BasePermissionService` only when the module actually performs `.access()` checks.
+- If a module has no permission enforcement, use `BaseService` instead.
+
+## Anti-Patterns
+
+- Grant declares `write` while service checks `update` — action names must match exactly.
+- Defining grants but never enforcing them with `.access()` in service procedures.
+- Doing permission checks in tRPC/router files instead of in the service layer.
+- Using `BasePermissionService` when no grants or `.access()` calls exist.

package/templates/minimal-app/.cursor/rules/module-module-guide.mdc

@@ -0,0 +1,183 @@
+---
+globs: apps/*/server/src/modules/**/*.module.ts
+alwaysApply: false
+---
+
+# Module File Style Guide
+
+A `*.module.ts` file is the composition unit for an app module. It wires repositories, services, and tRPC routers into a single class that the backend kernel orchestrates.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.module.ts
+```
+
+## Conventions
+
+- Extend `BaseModule<Deps, Tables, Repositories, Services, Routers>` from `@m5kdev/backend/modules/base/base.module`.
+- Declare local type aliases for each generic slot (`*ModuleDeps`, `*ModuleTables`, `*ModuleRepositories`, `*ModuleServices`, `*ModuleRouters`).
+- Set `readonly id` to match the module directory name (e.g. `readonly id = "posts"`).
+- Declare `dependsOn` as a `readonly` tuple with `as const`. App modules typically depend on framework modules like `AuthModule`.
+- Override only the hooks the module actually needs; omit the rest.
+- Keep hook bodies as pure wiring — no business logic.
+- Use `createBackendRouterMap(namespace, router)` from `@m5kdev/backend/app` in the `trpc()` hook.
+- Export a singleton instance at the bottom of the file.
+
+## Generic Parameters
+
+| Position | Name | Purpose | When unused |
+|----------|------|---------|-------------|
+| 1 | `Deps` | Map of module dependencies (`{ auth: AuthModule }`) | `never` |
+| 2 | `Tables` | `typeof import("./<module>.db")` — DB table exports | `TableMap` |
+| 3 | `Repositories` | Object map of repository instances | `{}` |
+| 4 | `Services` | Object map of service instances | `{}` |
+| 5 | `Routers` | Object map of tRPC routers keyed by namespace | `never` |
+
+## Dependency Declaration
+
+- `dependsOn` lists required modules by their `id`. The kernel initializes them first and provides their output via `ctx.deps`.
+- App modules commonly depend on `"auth"` for the framework's `AuthModule`.
+- Use `optionalDependsOn` when a dependency is not always registered.
+
+## Lifecycle Hooks (Execution Order)
+
+1. `repositories(ctx)` — Instantiate repositories. Context provides `db` (orm, schema, client), `deps`, `infra`.
+2. `services(ctx)` — Instantiate services. Context adds `repositories` from step 1.
+3. `trpc(ctx)` — Return router map fragment. Context adds `services` and `trpc` methods.
+4. `express(ctx)` — Mount Express routes (optional).
+5. `workflows(ctx)` — Register workflow handlers (optional).
+6. `startup(ctx)` — Async hook after full app build (optional).
+7. `shutdown(ctx)` — Async hook on teardown (optional).
+
+## Example
+
+```typescript
+import { createBackendRouterMap } from "@m5kdev/backend/app";
+import type { AuthModule } from "@m5kdev/backend/modules/auth/auth.module";
+import {
+  BaseModule,
+  type ModuleRepositoriesContext,
+  type ModuleServicesContext,
+  type ModuleTRPCContext,
+} from "@m5kdev/backend/modules/base/base.module";
+import type * as postsTables from "./posts.db";
+import { postsGrants } from "./posts.grants";
+import { PostsRepository } from "./posts.repository";
+import { PostsService } from "./posts.service";
+import { createPostsTRPC } from "./posts.trpc";
+
+type PostsModuleDeps = { auth: AuthModule };
+type PostsModuleTables = typeof postsTables;
+type PostsModuleRepositories = {
+  posts: PostsRepository;
+};
+type PostsModuleServices = {
+  posts: PostsService;
+};
+type PostsModuleRouters = {
+  posts: ReturnType<typeof createPostsTRPC>;
+};
+
+export class PostsModule extends BaseModule<
+  PostsModuleDeps,
+  PostsModuleTables,
+  PostsModuleRepositories,
+  PostsModuleServices,
+  PostsModuleRouters
+> {
+  readonly id = "posts";
+  override readonly dependsOn = ["auth"] as const;
+
+  override repositories({ db }: ModuleRepositoriesContext<PostsModuleDeps, PostsModuleTables>) {
+    return {
+      posts: new PostsRepository({
+        orm: db.orm,
+        schema: db.schema,
+        table: db.schema.posts,
+      }),
+    };
+  }
+
+  override services({
+    repositories,
+  }: ModuleServicesContext<PostsModuleDeps, PostsModuleRepositories>) {
+    return {
+      posts: new PostsService({ posts: repositories.posts }, {}, postsGrants),
+    };
+  }
+
+  override trpc({ trpc, services }: ModuleTRPCContext<PostsModuleDeps, PostsModuleServices>) {
+    return createBackendRouterMap("posts", createPostsTRPC(trpc, services.posts));
+  }
+}
+
+export const postsModule = new PostsModule();
+```
+
+## Registration
+
+Register the module in `apps/<app>/server/src/modules.ts`:
+
+```typescript
+import { defineBackendModules } from "@m5kdev/backend/app";
+import { PostsModule } from "./modules/posts/posts.module";
+
+export const postsBackendModule = new PostsModule();
+
+export const backendModules = defineBackendModules([
+  emailBackendModule,
+  authBackendModule,
+  workflowBackendModule,
+  notificationBackendModule,
+  postsBackendModule,
+] as const);
+```
+
+Then chain `.use(postsBackendModule)` in `apps/<app>/server/src/app.ts`.
+
+## Accessing Module Output
+
+After building, module repositories and services are re-exported from composition root files:
+
+```typescript
+// apps/<app>/server/src/repository.ts
+export const postsRepository = builtBackendApp.modules.posts.repositories.posts;
+
+// apps/<app>/server/src/service.ts
+export const postsService = builtBackendApp.modules.posts.services.posts;
+```
+
+## Patterns
+
+### Services-Only Module (No DB)
+
+```typescript
+export class UtilsModule extends BaseModule<
+  never, TableMap, {}, UtilsModuleServices, never
+> {
+  readonly id = "utils";
+
+  override services() {
+    return { utils: new UtilsService() };
+  }
+}
+```
+
+### Module with Constructor Config
+
+```typescript
+export class PaymentsModule extends BaseModule<...> {
+  readonly id = "payments";
+
+  constructor(private readonly config: { apiKey: string }) {
+    super();
+  }
+
+  override services({ repositories }: ModuleServicesContext<...>) {
+    return {
+      payments: new PaymentsService(repositories, {}, this.config),
+    };
+  }
+}
+```

package/templates/minimal-app/.cursor/rules/module-repository-guide.mdc

@@ -0,0 +1,193 @@
+---
+globs: apps/*/server/src/modules/**/*.repository.ts
+alwaysApply: false
+---
+
+# Module Repository File Style Guide
+
+Conventions for repository classes in app modules.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.repository.ts
+```
+
+## Conventions
+
+- Extend `BaseTableRepository<Orm, Schema, NestedRepos, Schema["table"]>` for table-bound modules.
+- Use `BaseRepository` for non-table or multi-table repositories.
+- Keep repositories data-focused: persistence, query composition, and lightweight mapping only.
+- Do not import service classes into repositories.
+- Use Drizzle operators (`and`, `eq`, `inArray`, `isNull`, `like`, etc.) and query helpers from base classes.
+- When running inside `this.orm.transaction`, use `tx` consistently; avoid mixing `this.orm` calls in the same transaction flow.
+- Leave orchestration, policy decisions, and side effects to services.
+
+## Orm/Schema Type Pattern
+
+App repositories define their schema and ORM types inline from local table imports:
+
+```typescript
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import { posts } from "./posts.db";
+
+const schema = { posts };
+type Schema = typeof schema;
+type Orm = LibSQLDatabase<Schema>;
+```
+
+This is passed to `BaseTableRepository` generics and provided by the module's `repositories()` hook via `db.orm` and `db.schema`.
+
+## Built-in Base Methods
+
+`BaseTableRepository` provides typed CRUD helpers. Prefer them over hand-written queries when they fit:
+
+- `queryList(query, options)` — filtered/sorted/paginated lists.
+- `findById(id)` / `findManyById(ids)` — primary-key lookups.
+- `create(data)` / `createMany(data)` — inserts.
+- `update(data)` / `updateMany(data)` — updates.
+- `softDeleteById(id)` / `deleteById(id)` — deletes.
+
+Override only when custom joins, CTEs, or non-standard behavior is required.
+
+## Error Handling
+
+- Use `throwableQuery` to wrap individual Drizzle queries. It converts thrown database errors into `ServerResultAsync`.
+- Do not wrap entire method bodies in `throwableAsync`. Keep `throwableQuery` scoped tightly around the database call so error-handling logic stays outside the wrapper.
+- Chain results with `isErr()` checks and return `err(result.error)` to propagate failures.
+
+## Schema Type Imports
+
+Import schema types from the shared package for method signatures:
+
+```typescript
+import type {
+  PostSchema,
+  PostsListInputSchema,
+  PostsListOutputSchema,
+} from "@appname/shared/modules/posts/posts.schema";
+```
+
+## Example
+
+```typescript
+import type {
+  PostSchema,
+  PostsListInputSchema,
+  PostsListOutputSchema,
+} from "@appname/shared/modules/posts/posts.schema";
+import { BaseTableRepository } from "@m5kdev/backend/modules/base/base.repository";
+import type { ServerResultAsync } from "@m5kdev/backend/utils/types";
+import { and, asc, count, desc, eq, isNull, like, ne, or } from "drizzle-orm";
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import { err, ok } from "neverthrow";
+import { posts } from "./posts.db";
+
+const schema = { posts };
+type Schema = typeof schema;
+type Orm = LibSQLDatabase<Schema>;
+
+export class PostsRepository extends BaseTableRepository<
+  Orm,
+  Schema,
+  Record<string, never>,
+  Schema["posts"]
+> {
+  async list(input: PostsListInputSchema = {}): ServerResultAsync<PostsListOutputSchema> {
+    const page = input.page ?? 1;
+    const limit = input.limit ?? 6;
+    const search = input.search?.trim();
+    const conditions = [isNull(this.table.deletedAt)];
+
+    if (input.status) {
+      conditions.push(eq(this.table.status, input.status));
+    }
+
+    if (search) {
+      const escapedSearch = search.replace(/[%_]/g, "\\$&");
+      const pattern = `%${escapedSearch}%`;
+      const searchCondition = or(
+        like(this.table.title, pattern),
+        like(this.table.slug, pattern),
+        like(this.table.excerpt, pattern),
+        like(this.table.content, pattern)
+      );
+      if (searchCondition) {
+        conditions.push(searchCondition);
+      }
+    }
+
+    const whereClause = and(...conditions);
+    const ordering =
+      input.sort === "title"
+        ? input.order === "asc"
+          ? asc(this.table.title)
+          : desc(this.table.title)
+        : desc(this.table.createdAt);
+
+    const rowsQuery = this.orm
+      .select()
+      .from(this.table)
+      .where(whereClause)
+      .orderBy(ordering, desc(this.table.createdAt))
+      .limit(limit)
+      .offset((page - 1) * limit);
+
+    const countQuery = this.orm.select({ count: count() }).from(this.table).where(whereClause);
+
+    const result = await this.throwableQuery(() => Promise.all([rowsQuery, countQuery]));
+    if (result.isErr()) return err(result.error);
+    const [rows, [totalRow]] = result.value;
+
+    return ok({
+      rows: rows as PostSchema[],
+      total: totalRow?.count ?? 0,
+    });
+  }
+
+  async findBySlug(slug: string, excludeId?: string) {
+    const whereClause = excludeId
+      ? and(eq(this.table.slug, slug), ne(this.table.id, excludeId), isNull(this.table.deletedAt))
+      : and(eq(this.table.slug, slug), isNull(this.table.deletedAt));
+
+    const result = await this.throwableQuery(() =>
+      this.orm.select().from(this.table).where(whereClause).limit(1)
+    );
+    if (result.isErr()) return err(result.error);
+    const [row] = result.value;
+    return ok(row);
+  }
+}
+```
+
+## When to Use `async` Methods vs Query Builder
+
+Use regular `async` methods (as shown above) when:
+
+- The method requires an optional `tx` parameter for transaction support.
+- The method orchestrates multiple sequential queries with branching logic between them.
+- The method wraps a `this.orm.transaction()` call.
+
+Use `this.query()` builder for simpler single-query methods with schema-typed input/output:
+
+```typescript
+findBySlug = this.query("findBySlug")
+  .input(z.object({ slug: z.string() }))
+  .output(postSchema.nullable())
+  .handle(async ({ slug }) => {
+    const result = await this.throwableQuery(() =>
+      this.orm.select().from(this.table).where(eq(this.table.slug, slug)).limit(1)
+    );
+    if (result.isErr()) return err(result.error);
+    const [row] = result.value;
+    return row ?? null;
+  });
+```
+
+## Best Practices
+
+1. Prefer built-in `BaseTableRepository` methods (`findById`, `create`, `update`, `softDeleteById`) over hand-written queries for standard CRUD.
+2. Use `throwableQuery` around each individual Drizzle query, not around the whole method body.
+3. Filter soft-deleted rows with `isNull(this.table.deletedAt)` in custom queries.
+4. Accept optional `tx?: Orm` parameter in methods that participate in transactions.
+5. Return `ServerResultAsync` consistently from all repository methods.

package/templates/minimal-app/.cursor/rules/module-schema-guide.mdc

@@ -0,0 +1,173 @@
+---
+globs: apps/*/shared/src/modules/**/*.schema.ts
+alwaysApply: false
+---
+
+# Module Schema File Style Guide
+
+Conventions for shared Zod schema files that define the contract between server and client.
+
+## File Location
+
+```
+apps/<app>/shared/src/modules/<module>/<module>.schema.ts
+```
+
+Companion constants file:
+
+```
+apps/<app>/shared/src/modules/<module>/<module>.constants.ts
+```
+
+## Core Philosophy
+
+- Define all Zod schemas and their inferred types in the shared package so both server and webapp can import them.
+- Import constants (enum values, page sizes) from the companion `<module>.constants.ts` file.
+- Extend `querySchema` from `@m5kdev/commons/modules/schemas/query.schema` for list inputs that need pagination, sorting, and filtering.
+- Export both the schema and its inferred `type` for every schema.
+
+## Naming Conventions
+
+| Kind | Pattern | Example |
+|---|---|---|
+| Entity schema | `{entity}Schema` | `postSchema` |
+| Entity type | `{Entity}Schema` | `PostSchema` |
+| Enum schema | `{entity}{Field}Schema` | `postStatusSchema` |
+| List input | `{entities}ListInputSchema` | `postsListInputSchema` |
+| List output | `{entities}ListOutputSchema` | `postsListOutputSchema` |
+| Operation input | `{entity}{Action}InputSchema` | `postCreateInputSchema` |
+| Operation output | `{entity}{Action}OutputSchema` | `postCreateOutputSchema` |
+
+## File Structure
+
+```typescript
+import { querySchema } from "@m5kdev/commons/modules/schemas/query.schema";
+import { z } from "zod";
+import { STATUS_VALUES } from "./<module>.constants";
+
+// 1. Enum schemas (from constants)
+// 2. Main entity schema
+// 3. List input/output schemas
+// 4. Operation input/output schemas
+```
+
+## Section 1: Enum Schemas
+
+Derive Zod enums from constant tuples defined in the constants file:
+
+```typescript
+export const postStatusSchema = z.enum(POST_STATUS_VALUES);
+export type PostStatusSchema = z.infer<typeof postStatusSchema>;
+```
+
+## Section 2: Main Entity Schema
+
+Define the full entity shape as a `z.object`. This is the canonical representation of the entity:
+
+```typescript
+export const postSchema = z.object({
+  id: z.string(),
+  authorUserId: z.string().nullish(),
+  organizationId: z.string().nullish(),
+  teamId: z.string().nullish(),
+  title: z.string(),
+  slug: z.string(),
+  excerpt: z.string().nullish(),
+  content: z.string(),
+  status: postStatusSchema,
+  publishedAt: z.date().nullish(),
+  createdAt: z.date(),
+  updatedAt: z.date().nullish(),
+  deletedAt: z.date().nullish(),
+});
+export type PostSchema = z.infer<typeof postSchema>;
+```
+
+## Section 3: List Input/Output Schemas
+
+Extend `querySchema` for list inputs with module-specific filters. Define list output as `{ rows, total }`:
+
+```typescript
+export const postsListInputSchema = querySchema.extend({
+  search: z.string().optional(),
+  status: postStatusSchema.optional(),
+});
+export type PostsListInputSchema = z.infer<typeof postsListInputSchema>;
+
+export const postsListOutputSchema = z.object({
+  rows: z.array(postSchema),
+  total: z.number(),
+});
+export type PostsListOutputSchema = z.infer<typeof postsListOutputSchema>;
+```
+
+## Section 4: Operation Input/Output Schemas
+
+Define per-operation schemas. Output schemas can reuse the main entity schema or a subset:
+
+```typescript
+export const postCreateInputSchema = z.object({
+  title: z.string().min(1),
+  slug: z.string().optional(),
+  excerpt: z.string().optional(),
+  content: z.string().min(1),
+});
+export type PostCreateInputSchema = z.infer<typeof postCreateInputSchema>;
+
+export const postCreateOutputSchema = postSchema;
+export type PostCreateOutputSchema = z.infer<typeof postCreateOutputSchema>;
+```
+
+## Patterns
+
+### Reuse Entity Schema for Output
+
+When the operation returns the full entity, alias the main schema:
+
+```typescript
+export const postUpdateOutputSchema = postSchema;
+```
+
+### Minimal Operation Schemas
+
+For operations that take only an ID and return a subset:
+
+```typescript
+export const postSoftDeleteInputSchema = z.object({
+  id: z.string(),
+});
+
+export const postSoftDeleteOutputSchema = z.object({
+  id: z.string(),
+});
+```
+
+### Omitting Fields for Lighter Outputs
+
+Use `.omit()` or `.pick()` on the main schema to create lighter variants:
+
+```typescript
+export const postSimpleSchema = postSchema.omit({
+  content: true,
+  deletedAt: true,
+});
+```
+
+## Constants File Conventions
+
+Keep enum values, filter presets, and page sizes in `<module>.constants.ts`:
+
+```typescript
+export const POST_STATUS_VALUES = ["draft", "published"] as const;
+export const POST_FILTER_VALUES = ["all", ...POST_STATUS_VALUES] as const;
+export const POSTS_PAGE_SIZE = 6;
+```
+
+## Best Practices
+
+1. Always export both the Zod schema and its inferred type.
+2. Use `.nullish()` for optional nullable fields, `.optional()` for optional-only.
+3. Extend `querySchema` for list inputs rather than redefining pagination fields.
+4. Reuse the main entity schema as operation output when the full entity is returned.
+5. Keep validation rules (`.min()`, `.max()`, `.regex()`) in input schemas.
+6. Keep schemas flat and avoid deep nesting when possible.

package/templates/minimal-app/.cursor/rules/module-service-guide.mdc

@@ -0,0 +1,240 @@
+---
+globs: apps/*/server/src/modules/**/*.service.ts
+alwaysApply: false
+---
+
+# Module Service File Style Guide
+
+Conventions for service classes in app modules.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.service.ts
+```
+
+## Conventions
+
+- Extend `BaseService<Repositories, Services>` or `BasePermissionService<Repositories, Services>` from `@m5kdev/backend/modules/base/base.service`.
+- Declare repository and service dependencies as explicit named maps in generics.
+- Keep orchestration and business logic in services; repositories handle persistence only.
+- Implement service methods as procedures using `this.procedure("name")` builder chains.
+- Propagate `ServerResultAsync` consistently and use `err(...)`/`ok(...)` composition.
+
+## Schema Type Imports
+
+Import types from the shared schema file for procedure type parameters:
+
+```typescript
+import type {
+  PostCreateInputSchema,
+  PostCreateOutputSchema,
+  PostsListInputSchema,
+  PostsListOutputSchema,
+} from "@appname/shared/modules/posts/posts.schema";
+```
+
+## Context Type
+
+Define a `RequestContext` alias from the framework's `Context` type:
+
+```typescript
+import type { Context } from "@m5kdev/backend/utils/trpc";
+
+type RequestContext = Context;
+```
+
+Pass this as the third generic to `BasePermissionService` or `BaseService`.
+
+## Procedure Builder
+
+Service methods are defined using a chainable procedure builder. Each procedure handles input typing, authentication, resource loading, access control, and the final handler.
+
+### Builder Methods (in typical call order)
+
+1. `.requireAuth(scope?)` — Enforces authentication. Scope: `"user"` (default), `"organization"`, `"team"`, `"admin"`.
+2. `.use(name, step)` — Runs an arbitrary step and stores the result in `state`.
+3. `.loadResource(name, loader)` — Loads a value and stores it in `state`; returns `NOT_FOUND` if falsy.
+4. `.access(config)` — Permission check (only on `BasePermissionService`). Action must match a grant.
+5. `.handle(handler)` — Terminal method; runs the handler with `{ input, ctx, state, repository, service, logger }`.
+
+### Input Typing
+
+Use the generic type parameter with shared schema types:
+
+```typescript
+readonly create = this.procedure<PostCreateInputSchema>("create")
+  .requireAuth()
+  .handle(async ({ input, ctx }): ServerResultAsync<PostCreateOutputSchema> => {
+    // ...
+  });
+```
+
+## Procedure Patterns
+
+### Simple List
+
+```typescript
+readonly list = this.procedure<PostsListInputSchema>("list")
+  .requireAuth()
+  .handle(({ input }): ServerResultAsync<PostsListOutputSchema> => {
+    return this.repository.posts.list(input);
+  });
+```
+
+### Create with Business Logic
+
+```typescript
+readonly create = this.procedure<PostCreateInputSchema>("create")
+  .requireAuth()
+  .access({
+    action: "write",
+    entities: ({ ctx }) => ({
+      organizationId: ctx.session.activeOrganizationId ?? null,
+      teamId: ctx.session.activeTeamId ?? null,
+    }),
+  })
+  .handle(async ({ input, ctx }): ServerResultAsync<PostCreateOutputSchema> => {
+    const uniqueSlug = await this.repository.posts.resolveUniqueSlug(
+      this.slugify(input.slug ?? input.title)
+    );
+    if (uniqueSlug.isErr()) return err(uniqueSlug.error);
+
+    return this.repository.posts.create({
+      authorUserId: ctx.user.id,
+      organizationId: ctx.session.activeOrganizationId ?? null,
+      teamId: ctx.session.activeTeamId ?? null,
+      title: input.title.trim(),
+      slug: uniqueSlug.value,
+      content: input.content.trim(),
+      status: "draft",
+    }) as ServerResultAsync<PostCreateOutputSchema>;
+  });
+```
+
+### Update with Resource Loading and Access Control
+
+```typescript
+readonly update = this.procedure<PostUpdateInputSchema>("update")
+  .requireAuth()
+  .use("post", async ({ input }) => {
+    const current = await this.repository.posts.findById(input.id);
+    if (current.isErr()) return err(current.error);
+    if (!current.value || current.value.deletedAt) {
+      return this.error("NOT_FOUND", "Post not found");
+    }
+    return current.value;
+  })
+  .access({
+    action: "write",
+    entityStep: "post",
+  })
+  .handle(async ({ input }): ServerResultAsync<PostUpdateOutputSchema> => {
+    return this.repository.posts.update(input);
+  });
+```
+
+### Soft Delete
+
+```typescript
+readonly softDelete = this.procedure<PostSoftDeleteInputSchema>("softDelete")
+  .requireAuth()
+  .use("post", async ({ input }) => {
+    const current = await this.repository.posts.findById(input.id);
+    if (current.isErr()) return err(current.error);
+    if (!current.value || current.value.deletedAt) {
+      return this.error("NOT_FOUND", "Post not found");
+    }
+    return current.value;
+  })
+  .access({
+    action: "delete",
+    entityStep: "post",
+  })
+  .handle(async ({ input }): ServerResultAsync<PostSoftDeleteOutputSchema> => {
+    const updated = await this.repository.posts.update({
+      id: input.id,
+      deletedAt: new Date(),
+    });
+    if (updated.isErr()) return err(updated.error);
+    return ok({ id: updated.value.id });
+  });
+```
+
+### Public (No Auth)
+
+```typescript
+readonly getPublic = this.procedure<GetPublicInputSchema>("getPublic")
+  .handle(async ({ input }): ServerResultAsync<PostSchema> => {
+    return this.repository.posts.findPublished(input.slug);
+  });
+```
+
+## Access Control Modes
+
+The `.access()` step supports two entity resolution strategies:
+
+- **`entityStep`** — References a value stored by a prior `.use()` or `.loadResource()` step. The entity's `userId`, `organizationId`, and `teamId` are read automatically.
+- **`entities`** — Inline function returning `{ userId?, organizationId?, teamId? }` for cases where the entity is not loaded into state.
+
+## Permission and Grants
+
+- If extending `BasePermissionService`, keep action names aligned with grants (`read`, `write`, `delete`, `publish`).
+- Do not use undeclared action aliases (e.g., guard `"update"` when grants only define `"write"`).
+- If a module has no `.access()` usage, prefer `BaseService` over `BasePermissionService`.
+
+## Example Skeleton
+
+```typescript
+import type {
+  PostCreateInputSchema,
+  PostCreateOutputSchema,
+  PostsListInputSchema,
+  PostsListOutputSchema,
+} from "@appname/shared/modules/posts/posts.schema";
+import { BasePermissionService } from "@m5kdev/backend/modules/base/base.service";
+import type { ServerResultAsync } from "@m5kdev/backend/utils/types";
+import type { Context } from "@m5kdev/backend/utils/trpc";
+import { err, ok } from "neverthrow";
+import type { PostsRepository } from "./posts.repository";
+
+type RequestContext = Context;
+
+export class PostsService extends BasePermissionService<
+  { posts: PostsRepository },
+  Record<string, never>,
+  RequestContext
+> {
+  readonly list = this.procedure<PostsListInputSchema>("list")
+    .requireAuth()
+    .handle(({ input }): ServerResultAsync<PostsListOutputSchema> => {
+      return this.repository.posts.list(input);
+    });
+
+  readonly create = this.procedure<PostCreateInputSchema>("create")
+    .requireAuth()
+    .access({
+      action: "write",
+      entities: ({ ctx }) => ({
+        organizationId: ctx.session.activeOrganizationId ?? null,
+        teamId: ctx.session.activeTeamId ?? null,
+      }),
+    })
+    .handle(async ({ input, ctx }): ServerResultAsync<PostCreateOutputSchema> => {
+      return this.repository.posts.create({
+        authorUserId: ctx.user.id,
+        title: input.title.trim(),
+        content: input.content.trim(),
+        status: "draft",
+      }) as ServerResultAsync<PostCreateOutputSchema>;
+    });
+}
+```
+
+## Best Practices
+
+1. Keep procedures as `readonly` class properties for consistent initialization.
+2. Use `.use()` steps for resource loading with validation before `.access()`.
+3. Return `this.error("NOT_FOUND")` or `this.error("FORBIDDEN")` for expected failures.
+4. Keep private helper methods (slugify, excerpt generation) as regular class methods.
+5. Propagate `err(...)` from repository results rather than throwing.

package/templates/minimal-app/.cursor/rules/module-trpc-guide.mdc

@@ -0,0 +1,113 @@
+---
+globs: apps/*/server/src/modules/**/*.trpc.ts
+alwaysApply: false
+---
+
+# Module tRPC File Style Guide
+
+Conventions for tRPC router files in app modules.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.trpc.ts
+```
+
+## Conventions
+
+- Export a factory function named `create<Module>TRPC`.
+- Import input and output schemas from the shared schema file: `@appname/shared/modules/<module>/<module>.schema`.
+- Use `handleTRPCResult` from `@m5kdev/backend/utils/trpc` to unwrap `Result` types.
+- Separate queries and mutations; keep resolvers thin and delegate to the service.
+- Always pass `ctx` to service methods as the second argument. The first argument (`input`) can be `undefined`.
+- Use `z` inline only for simple ad-hoc inputs with primitives (`z.string()`, `z.number()`, `z.array()` with primitive value, `z.record()`); prefer shared schemas otherwise.
+- Do not perform business logic or DB access directly in tRPC resolvers.
+- To turn a schema into its array version, use `schema.array()` instead of `z.array(schema)`.
+
+## Factory Pattern
+
+The factory function receives `TRPCMethods` (destructured) and the service instance:
+
+```typescript
+import {
+  postCreateInputSchema,
+  postCreateOutputSchema,
+  postsListInputSchema,
+  postsListOutputSchema,
+  postUpdateInputSchema,
+  postUpdateOutputSchema,
+  postPublishInputSchema,
+  postPublishOutputSchema,
+  postSoftDeleteInputSchema,
+  postSoftDeleteOutputSchema,
+} from "@appname/shared/modules/posts/posts.schema";
+import { handleTRPCResult, type TRPCMethods } from "@m5kdev/backend/utils/trpc";
+import type { PostsService } from "./posts.service";
+
+export function createPostsTRPC(
+  { router, privateProcedure: procedure }: TRPCMethods,
+  postsService: PostsService
+) {
+  return router({
+    list: procedure
+      .input(postsListInputSchema)
+      .output(postsListOutputSchema)
+      .query(async ({ ctx, input }) => handleTRPCResult(await postsService.list(input ?? {}, ctx))),
+
+    create: procedure
+      .input(postCreateInputSchema)
+      .output(postCreateOutputSchema)
+      .mutation(async ({ ctx, input }) => handleTRPCResult(await postsService.create(input, ctx))),
+
+    update: procedure
+      .input(postUpdateInputSchema)
+      .output(postUpdateOutputSchema)
+      .mutation(async ({ ctx, input }) => handleTRPCResult(await postsService.update(input, ctx))),
+
+    publish: procedure
+      .input(postPublishInputSchema)
+      .output(postPublishOutputSchema)
+      .mutation(async ({ ctx, input }) => handleTRPCResult(await postsService.publish(input, ctx))),
+
+    softDelete: procedure
+      .input(postSoftDeleteInputSchema)
+      .output(postSoftDeleteOutputSchema)
+      .mutation(async ({ ctx, input }) =>
+        handleTRPCResult(await postsService.softDelete(input, ctx))
+      ),
+  });
+}
+```
+
+## Available Procedure Types
+
+Destructure from `TRPCMethods` based on auth requirements:
+
+| Procedure | Auth | Use for |
+|---|---|---|
+| `publicProcedure` | None | Public endpoints |
+| `privateProcedure` | User session required | Most CRUD operations |
+| `adminProcedure` | Admin role required | Admin-only operations |
+| `organizationProcedure` | Organization context required | Org-scoped operations |
+
+Alias `privateProcedure` as `procedure` for conciseness when most routes are authenticated.
+
+## Wiring to Module
+
+The factory is called in the module's `trpc()` hook:
+
+```typescript
+override trpc({ trpc, services }: ModuleTRPCContext<Deps, Services>) {
+  return createBackendRouterMap("posts", createPostsTRPC(trpc, services.posts));
+}
+```
+
+The namespace string (`"posts"`) becomes the tRPC path prefix (e.g., `trpc.posts.list`).
+
+## Best Practices
+
+1. Keep resolvers one-liners: `handleTRPCResult(await service.method(input, ctx))`.
+2. Never access repositories or database directly in tRPC files.
+3. Use shared schemas for `.input()` and `.output()` to maintain contract consistency.
+4. For optional input, pass a default value: `input ?? {}`.
+5. Use `.query()` for read operations and `.mutation()` for writes.

package/templates/minimal-app/apps/webapp/src/modules/posts/PostsRoute.tsx.tpl

@@ -620,7 +620,7 @@ export function PostsRoute() {
           }
         }}
       >
-        <Modal.Backdrop />
+        <Modal.Backdrop>
         <Modal.Container scroll="inside" size="lg" className="max-w-5xl">
           <Modal.Dialog>
             <form
@@ -718,6 +718,7 @@ export function PostsRoute() {
             </form>
           </Modal.Dialog>
         </Modal.Container>
+        </Modal.Backdrop>
       </Modal>
     </div>
   );

package/templates/minimal-app/pnpm-workspace.yaml.tpl

@@ -49,7 +49,7 @@ catalog:
   tsx: 4.19.2
   turbo: 2.5.6
   tw-animate-css: 1.3.6
-  typescript: 5.9.2
+  typescript: 6.0.3
   uuid: 11.0.5
   vite: 7.0.4
   vite-plugin-i18next-loader: 3.1.2