create-m5kdev 0.25.3 → 0.26.1

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

@@ -1,193 +1,98 @@
----
-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.
+---
+globs: apps/**/server/src/modules/**/*.repository.ts
+alwaysApply: false
+---
+
+# Module Repository File Style Guide
+
+Conventions for repository classes in app modules. Repositories consume the
+module DTO object (`postSchemas`) for query inputs/outputs — they do not
+import hand-written types.
+
+## 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
+
+```typescript
+import type { LibSQLDatabase } from "drizzle-orm/libsql";
+import { posts } from "./posts.db";
+
+const schema = { posts };
+type Schema = typeof schema;
+type Orm = LibSQLDatabase<Schema>;
+```
+
+## Built-in Base Methods — write nothing you get for free
+
+`BaseTableRepository` provides typed CRUD. Prefer these over hand-written queries:
+
+- `queryList(query, options)` — the generic list contract (`page`, `limit`,
+  `sort`, `order`, `q`, `filters`) translated to Drizzle. Pass
+  `globalSearchColumns` to enable `q`, `conditions` for extra scoping, and
+  `showDeleted` to include soft-deleted rows (excluded by default when the
+  table has `deletedAt`). Do NOT hand-write list/filter/count queries.
+- `findById(id)` / `findManyById(ids)` — primary-key lookups.
+- `create(data)` / `createMany(data)` — inserts.
+- `update(data)` / `updateMany(data)` — updates.
+- `softDeleteById(id)` / `deleteById(id)` — deletes.
+
+```typescript
+// a full filtered/searched/paginated list — no custom SQL
+this.repository.posts.queryList(input, {
+  globalSearchColumns: ["title", "excerpt", "content"],
+});
+```
+
+## Custom queries: the `this.query()` builder
+
+Single-purpose queries are declared with the builder, using DTO schemas for
+outputs. **Outputs are validated at runtime** — a find-style query that can
+return no row must use `output.found` (the optional row schema), or
+validation will fail on the legitimate "not found" case.
+
+```typescript
+import { z } from "zod";
+import { postSchemas } from "./posts.dto";
+
+findBySlug = this.query("findBySlug")
+  .input(z.object({ slug: z.string(), excludeId: z.string().optional() }))
+  .output(postSchemas.output.found) // NOT output.single — may return undefined
+  .handle(async ({ slug, excludeId }) => {
+    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);
+  });
+```
+
+Use plain `async` methods instead of the builder only when the method needs an
+optional `tx` parameter, wraps `this.orm.transaction()`, or orchestrates
+multiple queries with branching between them.
+
+## Error Handling
+
+- Use `throwableQuery` tightly around each Drizzle call — it converts thrown
+  database errors into `ServerResultAsync`. Do not wrap whole method bodies.
+- Chain results with `isErr()` checks and `err(result.error)`.
+- Filter soft-deleted rows with `isNull(this.table.deletedAt)` in custom
+  queries (`queryList` does this automatically).

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

@@ -1,173 +1,53 @@
----
-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.
+---
+globs: apps/**/shared/src/modules/**/*.schema.ts
+alwaysApply: false
+---
+
+# Shared Schema Style Guide
+
+Shared schemas have a **deliberately narrow role**. Do not mirror server types
+here — types flow from the server:
+
+- Row and list types are **inferred from the tRPC router**:
+  `inferRouterOutputs<AppRouter>` with `AppRouter` from
+  `{{PACKAGE_SCOPE}}/server/types`.
+- The API surface (inputs/outputs) is defined by the server module's DTO
+  (`<module>.dto.ts`), derived from the Drizzle table.
+
+## When a schema belongs in shared
+
+Put a Zod schema here only when at least one of these holds:
+
+1. **The frontend needs it at runtime** — e.g. validating a form beyond native
+   HTML validation.
+2. **Both sides genuinely share it** — then the server DTO must import it
+   (`postSchemas.input.create = postCreateInputSchema`), so the API contract
+   and the frontend validation are the same object and cannot drift.
+3. **It cannot be re-exported from the server** because the server version
+   depends on Drizzle (`drizzle-zod` schemas) and shipping that dependency to
+   the client is not acceptable.
+
+Everything else — row schemas, list outputs, trivial `{ id }` inputs — must
+NOT be duplicated in shared. Hand-written mirrors silently drift from the real
+contract.
+
+```ts
+// GOOD — form-validation schema, imported by both the DTO and the webapp form
+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>;
+
+// BAD — hand-mirrored row schema; the table already defines this shape
+export const postSchema = z.object({ id: z.string(), title: z.string(), /* ... */ });
+```
+
+## Conventions
+
+- File location: `apps/shared/src/modules/<module>/<module>.schema.ts`, with
+  enum values and constants in the companion `<module>.constants.ts`.
+- Export both the schema and its inferred `type`.
+- Build enums from constants: `z.enum(POST_STATUS_VALUES)`.