create-m5kdev 0.41.0 → 0.43.0

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

@@ -1,167 +1,167 @@
----
-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>;
-```
-
-## Prefer Built-in Base Methods (Strong Default)
-
-`BaseTableRepository` provides typed CRUD helpers. **Always use these before
-adding custom repository methods or raw Drizzle.** Services should call these
-helpers directly in most cases.
-
-- `queryList(query, options)` — filtered/sorted/paginated lists (`page`,
-  `limit`, `sort`, `order`, `q`, `filters`). Pass `globalSearchColumns` for
-  `q`, `conditions` for extra scoping, `showDeleted` to include soft-deleted
-  rows (excluded by default when the table has `deletedAt`).
-- `queryFind(query, options)` — filtered/sorted single-row lookup (no
-  pagination/count). Same filter/`conditions` contract as `queryList`.
-- `findById(id)` / `findManyById(ids)` — primary-key lookups.
-- `create(data)` / `createMany(data)` — inserts.
-- `update(data)` / `updateMany(data)` — updates.
-- `softDeleteById(id)` / `deleteById(id)` — deletes.
-
-```typescript
-// Preferred from the service — no custom repository list method
-this.repository.posts.queryList(input, {
-  globalSearchColumns: ["title", "excerpt", "content"],
-});
-```
-
-### Usually Do Not Add Custom List / Getter / Create / Update Methods
-
-- **Lists and getters**: `queryList` / `queryFind` already expose read APIs
-  via `filters` (and optional `conditions`). Prefer calling them from the
-  service with the needed filters (or `.addFilters` on the procedure). Do not
-  add thin `listPublished`, `findBySlug`, `getMain`, etc. unless the same
-  filter set is reused heavily *and* belongs in the repository boundary.
-- **Creates**: `create` is permissive — stamp defaults (`status`, `memberId`,
-  …) in the **service** and pass them to `create`. Do not add a custom
-  repository `create*` just to apply defaults.
-- **Updates**: `update` accepts partial payloads — omit fields you do not
-  want to change. Do not add a custom repository `update*` just to restrict
-  columns or merge patches.
-- Write raw `this.orm.select()...` or a custom method only for joins, CTEs,
-  multi-table writes, transactions, or predicates that cannot be expressed
-  with filters / `TableConditionBuilder`.
-
-Filter shape: `{ columnId, type, method, value }` (`type`: `string` |
-`number` | `date` | `boolean` | `enum` | `jsonArray`; common `method`s:
-`equals`, `contains`, `oneOf`, `is_null`, …). Soft-delete exclusion is
-applied automatically when the table has `deletedAt` (unless
-`showDeleted: true`).
-
-## Custom queries: the `this.query()` builder
-
-Use the builder only when a shared lookup truly belongs in the repository.
-Wire DTO schemas for inputs/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.
-
-Wrap `queryFind` / `queryList` with filters — never reimplement
-select/where/limit:
-
-```typescript
-import { z } from "zod";
-import { postSchemas } from "./posts.dto";
-
-// Shared domain lookup used from multiple services/jobs — still no hand-written SQL
-findBySlug = this.query("findBySlug")
-  .input(z.object({ slug: z.string() }))
-  .output(postSchemas.output.found) // NOT output.single — may return undefined
-  .handle(({ slug }) =>
-    this.queryFind({
-      filters: [
-        { columnId: "slug", type: "string", method: "equals", value: slug },
-      ],
-    })
-  );
-```
-
-### Extend With `conditions` When Filters Alone Are Not Enough
-
-Pass a `TableConditionBuilder` via `options.conditions` for extra predicates
-(optional excludes, `ne`, `inArray`, …) while still reusing soft-delete and
-column picking from `queryFind` / `queryList`:
-
-```typescript
-import { ne } from "drizzle-orm";
-import { z } from "zod";
-import { postSchemas } from "./posts.dto";
-
-// Prefer calling queryFind with conditions from the service when one-off;
-// repository wrapper only if shared across callers.
-findBySlug = this.query("findBySlug")
-  .input(
-    z.object({
-      slug: z.string(),
-      excludeId: z.string().optional(),
-    })
-  )
-  .output(postSchemas.output.found)
-  .handle(({ slug, excludeId }) => {
-    const conditions = this.getConditionBuilder(this.table);
-    if (excludeId) {
-      conditions.push(ne(this.table.id, excludeId));
-    }
-
-    return this.queryFind(
-      {
-        filters: [
-          { columnId: "slug", type: "string", method: "equals", value: slug },
-        ],
-      },
-      { conditions }
-    );
-  });
-```
-
-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 **raw** Drizzle call — it converts
-  thrown database errors into `ServerResultAsync`. Do not wrap whole method
-  bodies.
-- Built-in helpers (`queryFind`, `queryList`, `findById`, `create`, …)
-  already use `throwableQuery` internally — do not wrap their return values
-  again.
-- Chain results with `isErr()` checks and `err(result.error)`.
-- Soft-deleted rows are excluded automatically by `queryList` / `queryFind`
-  when the table has `deletedAt` (unless `showDeleted: true`). Only add
-  `isNull(this.table.deletedAt)` in raw custom queries.
+---
+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>;
+```
+
+## Prefer Built-in Base Methods (Strong Default)
+
+`BaseTableRepository` provides typed CRUD helpers. **Always use these before
+adding custom repository methods or raw Drizzle.** Services should call these
+helpers directly in most cases.
+
+- `queryList(query, options)` — filtered/sorted/paginated lists (`page`,
+  `limit`, `sort`, `order`, `q`, `filters`). Pass `globalSearchColumns` for
+  `q`, `conditions` for extra scoping, `showDeleted` to include soft-deleted
+  rows (excluded by default when the table has `deletedAt`).
+- `queryFind(query, options)` — filtered/sorted single-row lookup (no
+  pagination/count). Same filter/`conditions` contract as `queryList`.
+- `findById(id)` / `findManyById(ids)` — primary-key lookups.
+- `create(data)` / `createMany(data)` — inserts.
+- `update(data)` / `updateMany(data)` — updates.
+- `softDeleteById(id)` / `deleteById(id)` — deletes.
+
+```typescript
+// Preferred from the service — no custom repository list method
+this.repository.posts.queryList(input, {
+  globalSearchColumns: ["title", "excerpt", "content"],
+});
+```
+
+### Usually Do Not Add Custom List / Getter / Create / Update Methods
+
+- **Lists and getters**: `queryList` / `queryFind` already expose read APIs
+  via `filters` (and optional `conditions`). Prefer calling them from the
+  service with the needed filters (or `.addFilters` on the procedure). Do not
+  add thin `listPublished`, `findBySlug`, `getMain`, etc. unless the same
+  filter set is reused heavily *and* belongs in the repository boundary.
+- **Creates**: `create` is permissive — stamp defaults (`status`, `memberId`,
+  …) in the **service** and pass them to `create`. Do not add a custom
+  repository `create*` just to apply defaults.
+- **Updates**: `update` accepts partial payloads — omit fields you do not
+  want to change. Do not add a custom repository `update*` just to restrict
+  columns or merge patches.
+- Write raw `this.orm.select()...` or a custom method only for joins, CTEs,
+  multi-table writes, transactions, or predicates that cannot be expressed
+  with filters / `TableConditionBuilder`.
+
+Filter shape: `{ columnId, type, method, value }` (`type`: `string` |
+`number` | `date` | `boolean` | `enum` | `jsonArray`; common `method`s:
+`equals`, `contains`, `oneOf`, `is_null`, …). Soft-delete exclusion is
+applied automatically when the table has `deletedAt` (unless
+`showDeleted: true`).
+
+## Custom queries: the `this.query()` builder
+
+Use the builder only when a shared lookup truly belongs in the repository.
+Wire DTO schemas for inputs/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.
+
+Wrap `queryFind` / `queryList` with filters — never reimplement
+select/where/limit:
+
+```typescript
+import { z } from "zod";
+import { postSchemas } from "./posts.dto";
+
+// Shared domain lookup used from multiple services/jobs — still no hand-written SQL
+findBySlug = this.query("findBySlug")
+  .input(z.object({ slug: z.string() }))
+  .output(postSchemas.output.found) // NOT output.single — may return undefined
+  .handle(({ slug }) =>
+    this.queryFind({
+      filters: [
+        { columnId: "slug", type: "string", method: "equals", value: slug },
+      ],
+    })
+  );
+```
+
+### Extend With `conditions` When Filters Alone Are Not Enough
+
+Pass a `TableConditionBuilder` via `options.conditions` for extra predicates
+(optional excludes, `ne`, `inArray`, …) while still reusing soft-delete and
+column picking from `queryFind` / `queryList`:
+
+```typescript
+import { ne } from "drizzle-orm";
+import { z } from "zod";
+import { postSchemas } from "./posts.dto";
+
+// Prefer calling queryFind with conditions from the service when one-off;
+// repository wrapper only if shared across callers.
+findBySlug = this.query("findBySlug")
+  .input(
+    z.object({
+      slug: z.string(),
+      excludeId: z.string().optional(),
+    })
+  )
+  .output(postSchemas.output.found)
+  .handle(({ slug, excludeId }) => {
+    const conditions = this.getConditionBuilder(this.table);
+    if (excludeId) {
+      conditions.push(ne(this.table.id, excludeId));
+    }
+
+    return this.queryFind(
+      {
+        filters: [
+          { columnId: "slug", type: "string", method: "equals", value: slug },
+        ],
+      },
+      { conditions }
+    );
+  });
+```
+
+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 **raw** Drizzle call — it converts
+  thrown database errors into `ServerResultAsync`. Do not wrap whole method
+  bodies.
+- Built-in helpers (`queryFind`, `queryList`, `findById`, `create`, …)
+  already use `throwableQuery` internally — do not wrap their return values
+  again.
+- Chain results with `isErr()` checks and `err(result.error)`.
+- Soft-deleted rows are excluded automatically by `queryList` / `queryFind`
+  when the table has `deletedAt` (unless `showDeleted: true`). Only add
+  `isNull(this.table.deletedAt)` in raw custom queries.

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

@@ -1,53 +1,53 @@
----
-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)`.
+---
+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)`.