create-m5kdev 0.25.3 → 0.26.1

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

@@ -1,240 +1,133 @@
----
-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.
+---
+globs: apps/**/server/src/modules/**/*.service.ts
+alwaysApply: false
+---
+
+# Module Service File Style Guide
+
+Conventions for service classes in app modules. Services consume the module
+DTO object (`postSchemas`) — they do not import hand-written request/response
+types. Input and output schemas are attached to each procedure and validated
+at runtime.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.service.ts
+```
+
+## Conventions
+
+- Extend `BaseService<Repositories, Services>` or `BasePermissionService<Repositories, Services, Context>` 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 `readonly` procedures using the `this.procedure("name")` builder.
+- Propagate `ServerResultAsync` consistently with `err(...)`/`ok(...)` composition.
+
+## Procedure Builder
+
+Each procedure declares its schemas from the DTO, then auth, resource loading,
+access control, and the handler:
+
+1. `.input(schema)` / `.output(schema)` — DTO schemas; both are validated at runtime.
+2. `.requireAuth(scope?)` — `"user"` (default), `"organization"`, `"team"`, `"admin"`.
+3. `.loadResource(name, loader)` — loads a value into `state`; returns `NOT_FOUND` when falsy.
+4. `.use(name, step)` — arbitrary step storing its result in `state`.
+5. `.access(config)` — permission check (`BasePermissionService` only); action must match a grant.
+6. `.handle(handler)` — terminal; receives `{ input, ctx, state }`.
+
+## Procedure Patterns
+
+### List — delegate to `queryList`, never hand-roll list logic
+
+```typescript
+readonly list = this.procedure("list")
+  .input(postSchemas.input.list)
+  .output(postSchemas.output.list)
+  .requireAuth()
+  .handle(({ input }) => {
+    return this.repository.posts.queryList(input, {
+      globalSearchColumns: ["title", "excerpt", "content"],
+    });
+  });
+```
+
+### Create with business logic
+
+```typescript
+readonly create = this.procedure("create")
+  .requireAuth()
+  .input(postSchemas.input.create)
+  .output(postSchemas.output.single)
+  .access({ action: "write" })
+  .handle(async ({ input, ctx }) => {
+    const uniqueSlug = await this.repository.posts.resolveUniqueSlug({
+      candidate: 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,
+      title: input.title.trim(),
+      slug: uniqueSlug.value,
+      content: input.content.trim(),
+      status: "draft",
+    });
+  });
+```
+
+### Update with resource loading and access control
+
+```typescript
+readonly update = this.procedure("update")
+  .requireAuth()
+  .input(postSchemas.input.update)
+  .output(postSchemas.output.single)
+  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+  .access({ action: "write", entityStep: "post" })
+  .handle(async ({ input, state }) => {
+    return this.repository.posts.update({
+      id: input.id,
+      title: input.title ? input.title.trim() : state.post.title,
+      content: (input.content?.trim() ?? state.post.content).trim(),
+    });
+  });
+```
+
+### Soft delete
+
+```typescript
+readonly softDelete = this.procedure("softDelete")
+  .input(postSchemas.input.delete)
+  .output(postSchemas.output.uuid)
+  .requireAuth()
+  .loadResource("post", ({ input }) => this.repository.posts.findById(input.id))
+  .access({ action: "delete", entityStep: "post" })
+  .handle(async ({ input }) => {
+    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 });
+  });
+```
+
+## Access Control Modes
+
+- **`entityStep`** — references a value stored by `.loadResource()`/`.use()`;
+  the entity's `userId`, `organizationId`, and `teamId` are read automatically.
+- **`entities`** — inline function returning `{ userId?, organizationId?, teamId? }`
+  when the entity is not loaded into state.
+
+## Permissions and Grants
+
+- Keep action names aligned with grants (`read`, `write`, `delete`, `publish`).
+- Do not use undeclared aliases (e.g. guarding `"update"` when grants define `"write"`).
+- If a module never uses `.access()`, extend `BaseService` instead of `BasePermissionService`.
+
+## Best Practices
+
+1. Keep procedures as `readonly` class properties.
+2. `.loadResource()` before `.access({ entityStep })` — it 404s on missing rows for free.
+3. Return `this.error("NOT_FOUND")` / `this.error("FORBIDDEN")` for expected failures; reserve 5xx codes for server faults (they report to Sentry).
+4. Keep pure helpers (slugify, excerpt) in `<module>.utils.ts`.
+5. Propagate `err(...)` from repository results rather than throwing.

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

@@ -1,113 +1,71 @@
----
-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.
+---
+globs: apps/**/server/src/modules/**/*.trpc.ts
+alwaysApply: false
+---
+
+# Module tRPC File Style Guide
+
+Conventions for tRPC router files in app modules. Routers are thin wiring:
+they attach the module DTO schemas and delegate to the service. The router is
+also the type source for the client — the webapp infers all row/list types
+from `AppRouter`, so accurate `.input()`/`.output()` here is what makes
+end-to-end types work.
+
+## File Location
+
+```
+apps/<app>/server/src/modules/<module>/<module>.trpc.ts
+```
+
+## Conventions
+
+- Export a factory function named `create<Module>TRPC`.
+- Import the module DTO object (`postSchemas`) from `./<module>.dto` — not
+  shared schemas, not hand-written types.
+- Use `handleTRPCResult` from `@m5kdev/backend/utils/trpc` to unwrap `Result`s.
+- Keep resolvers one-liners that delegate to the service; no business logic or
+  DB access here.
+- Always pass `ctx` to service methods as the second argument. The first
+  argument (`input`) can be `undefined` for optional-input queries.
+
+## Factory Pattern
+
+```typescript
+import { handleTRPCResult, type TRPCMethods } from "@m5kdev/backend/utils/trpc";
+import { postSchemas } from "./posts.dto";
+import type { PostsService } from "./posts.service";
+
+export function createPostsTRPC(
+  { router, privateProcedure: procedure }: TRPCMethods,
+  postsService: PostsService
+) {
+  return router({
+    list: procedure
+      .input(postSchemas.input.list)
+      .output(postSchemas.output.list)
+      .query(async ({ ctx, input }) => handleTRPCResult(await postsService.list(input ?? {}, ctx))),
+
+    create: procedure
+      .input(postSchemas.input.create)
+      .output(postSchemas.output.single)
+      .mutation(async ({ ctx, input }) => handleTRPCResult(await postsService.create(input, ctx))),
+
+    softDelete: procedure
+      .input(postSchemas.input.delete)
+      .output(postSchemas.output.uuid)
+      .mutation(async ({ ctx, input }) =>
+        handleTRPCResult(await postsService.softDelete(input, ctx))
+      ),
+  });
+}
+```
+
+## Procedure Selection
+
+- `privateProcedure` — authenticated user (most module routes).
+- `organizationProcedure` — requires an active organization.
+- `adminProcedure` — admin role.
+- `publicProcedure` — unauthenticated; use sparingly.
+
+The service's own `.requireAuth()`/`.access()` still run — the tRPC procedure
+choice is transport-level gating, not a replacement for service checks.

package/templates/minimal-app/README.md.tpl

@@ -13,13 +13,13 @@
 
 ```sh
 pnpm install
-pnpm --filter ./apps/server sync
-pnpm --filter ./apps/server seed
+pnpm --filter ./apps/server drizzle:migrate
+pnpm --filter ./apps/server drizzle:seed
 pnpm dev
 ```
 
 The starter uses a local LibSQL file by default and writes local auth emails to `apps/server/.emails`.
-Before running `drizzle-kit`, the starter generates `apps/server/src/generated/schema.ts` from the registered backend modules.
+Database tables are registered by hand in `apps/server/src/schema.ts`; after changing any `*.db.ts`, run `drizzle:generate` and `drizzle:migrate`.
 
 ## Demo Credentials
 

package/templates/minimal-app/apps/.gitignore.tpl

@@ -0,0 +1,13 @@
+# runtime artifacts
+server/local.db*
+server/.e2e/
+server/.emails/
+server/uploads/
+
+# e2e output
+e2e/test-results/
+e2e/playwright-report/
+
+# expo
+expo/.expo/
+expo/dist/

package/templates/minimal-app/apps/e2e/package.json.tpl

@@ -0,0 +1,23 @@
+{
+  "name": "{{PACKAGE_SCOPE}}/e2e",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit",
+    "test:e2e": "playwright test",
+    "test:e2e:expo": "playwright test --config playwright.expo.config.ts --headed"
+  },
+  "devDependencies": {
+    "@m5kdev/backend": "catalog:",
+    "@m5kdev/commons": "catalog:",
+    "@m5kdev/config": "catalog:",
+    "@playwright/test": "catalog:",
+    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
+    "@trpc/client": "catalog:",
+    "@types/node": "catalog:",
+    "typescript": "catalog:"
+  }
+}

package/templates/minimal-app/apps/e2e/playwright.config.ts.tpl

@@ -0,0 +1,39 @@
+import { defineConfig, devices } from "@playwright/test";
+import { BASE_URLS, serverWebServer, webappWebServer } from "./servers";
+
+export default defineConfig({
+  testDir: "./tests",
+  fullyParallel: false,
+  workers: 1,
+  forbidOnly: Boolean(process.env.CI),
+  retries: process.env.CI ? 2 : 0,
+  reporter: [["list"], ["html", { open: "never" }]],
+  use: {
+    trace: "on-first-retry",
+  },
+  webServer: [
+    serverWebServer("standard"),
+    webappWebServer("standard"),
+    serverWebServer("waitlist"),
+    webappWebServer("waitlist"),
+  ],
+  projects: [
+    {
+      name: "standard",
+      // exact filenames — a broad regex would also match the expo-*.spec files
+      testMatch: ["standard.spec.ts", "email.spec.ts"],
+      use: {
+        ...devices["Desktop Chrome"],
+        baseURL: BASE_URLS.standard,
+      },
+    },
+    {
+      name: "waitlist",
+      testMatch: ["waitlist.spec.ts", "email.spec.ts"],
+      use: {
+        ...devices["Desktop Chrome"],
+        baseURL: BASE_URLS.waitlist,
+      },
+    },
+  ],
+});