create-m5kdev 0.40.3 → 0.41.0

package/templates/minimal-app/.cursor/rules/frontend-hook-guide.mdc

@@ -1,79 +1,79 @@
----
-globs: apps/**/webapp/src/**/hooks/**
-alwaysApply: false
----
-
-# Frontend Custom Hook Style Guide
-
-Feature logic lives in custom hooks so components stay display-focused.
-
-## When to create a hook
-
-Create a custom hook when a component accumulates real logic: multiple
-`useQuery`/`useMutation` calls, `queryClient` invalidation, nuqs URL state,
-or `useEffect` orchestration. A component that only needs one small hook and
-some ephemeral UI state does not need a wrapper — this rule is about keeping
-the JSX editable, not about ceremony.
-
-## Structure
-
-- Location: `src/modules/<feature>/hooks/use<Name>.ts`
-- Compose small, focused hooks into one screen-level hook so the route
-  component makes a single call:
-
-```
-modules/posts/hooks/
-  usePostsList.ts    // list query + URL state (search, status, page)
-  usePostActions.ts  // reusable mutations: save, publish, delete
-  usePostsRoute.ts   // composes both for the PostsRoute screen
-```
-
-```ts
-export function usePostsRoute() {
-  const list = usePostsList();
-  const actions = usePostActions();
-  return { ...list, ...actions };
-}
-```
-
-## Reusable actions get their own hook
-
-Mutations that more than one component may trigger (delete, publish, archive)
-are always extracted into their own hook — never inlined into a screen hook —
-so other components can reuse them with the same toasts, confirmation dialogs,
-and invalidation.
-
-## What a hook owns
-
-- tRPC queries/mutations and their `queryFilter()` invalidation.
-- nuqs URL state (filters, pagination, tabs) and its update functions
-  (wrap updates in `startTransition`).
-- Derived data (`useMemo`): rows, totals, page counts, stats.
-- Side effects of actions: success/error toasts, confirmation dialogs
-  (`useDialog`), cache invalidation.
-- Pending indicators: booleans (`isSaving`) or row-scoped ids
-  (`deletingId`) derived from `mutation.isPending` + `mutation.variables`.
-
-## Return shape
-
-Return a flat object of data, derived values, pending flags, and action
-functions. Action functions used by forms should resolve to a success boolean
-instead of throwing, so components can close dialogs without try/catch:
-
-```ts
-const savePost = async (payload: PostCreateInputSchema, id?: string): Promise<boolean> => {
-  try {
-    if (id) await updateMutation.mutateAsync({ id, ...payload });
-    else await createMutation.mutateAsync(payload);
-    return true;
-  } catch {
-    return false; // the mutation's onError already showed a toast
-  }
-};
-```
-
-## What a hook must not do
-
-- Return JSX or take React nodes as arguments.
-- Read DOM elements directly (the submit handler that parses `FormData`
-  stays in the form component — see the frontend form guide).
+---
+globs: apps/**/webapp/src/**/hooks/**
+alwaysApply: false
+---
+
+# Frontend Custom Hook Style Guide
+
+Feature logic lives in custom hooks so components stay display-focused.
+
+## When to create a hook
+
+Create a custom hook when a component accumulates real logic: multiple
+`useQuery`/`useMutation` calls, `queryClient` invalidation, nuqs URL state,
+or `useEffect` orchestration. A component that only needs one small hook and
+some ephemeral UI state does not need a wrapper — this rule is about keeping
+the JSX editable, not about ceremony.
+
+## Structure
+
+- Location: `src/modules/<feature>/hooks/use<Name>.ts`
+- Compose small, focused hooks into one screen-level hook so the route
+  component makes a single call:
+
+```
+modules/posts/hooks/
+  usePostsList.ts    // list query + URL state (search, status, page)
+  usePostActions.ts  // reusable mutations: save, publish, delete
+  usePostsRoute.ts   // composes both for the PostsRoute screen
+```
+
+```ts
+export function usePostsRoute() {
+  const list = usePostsList();
+  const actions = usePostActions();
+  return { ...list, ...actions };
+}
+```
+
+## Reusable actions get their own hook
+
+Mutations that more than one component may trigger (delete, publish, archive)
+are always extracted into their own hook — never inlined into a screen hook —
+so other components can reuse them with the same toasts, confirmation dialogs,
+and invalidation.
+
+## What a hook owns
+
+- tRPC queries/mutations and their `queryFilter()` invalidation.
+- nuqs URL state (filters, pagination, tabs) and its update functions
+  (wrap updates in `startTransition`).
+- Derived data (`useMemo`): rows, totals, page counts, stats.
+- Side effects of actions: success/error toasts, confirmation dialogs
+  (`useDialog`), cache invalidation.
+- Pending indicators: booleans (`isSaving`) or row-scoped ids
+  (`deletingId`) derived from `mutation.isPending` + `mutation.variables`.
+
+## Return shape
+
+Return a flat object of data, derived values, pending flags, and action
+functions. Action functions used by forms should resolve to a success boolean
+instead of throwing, so components can close dialogs without try/catch:
+
+```ts
+const savePost = async (payload: PostCreateInputSchema, id?: string): Promise<boolean> => {
+  try {
+    if (id) await updateMutation.mutateAsync({ id, ...payload });
+    else await createMutation.mutateAsync(payload);
+    return true;
+  } catch {
+    return false; // the mutation's onError already showed a toast
+  }
+};
+```
+
+## What a hook must not do
+
+- Return JSX or take React nodes as arguments.
+- Read DOM elements directly (the submit handler that parses `FormData`
+  stays in the form component — see the frontend form guide).

package/templates/minimal-app/.cursor/rules/frontend-i18n-guide.mdc

@@ -1,45 +1,45 @@
----
-globs: apps/**/webapp/src/**/*.tsx
-alwaysApply: false
----
-
-# Frontend i18n Style Guide
-
-All user-facing copy goes through i18next. No hardcoded strings in JSX,
-toasts, aria-labels, or placeholders.
-
-## Usage
-
-```tsx
-const { t } = useTranslation("<app-namespace>");
-<h2>{t("posts.hero.title")}</h2>
-<Input placeholder={t("posts.filters.searchPlaceholder")} aria-label={t("posts.filters.searchLabel")} />
-toast.success(t("posts.toast.created"));
-```
-
-- `useTranslation(...)` is one of the few hooks always allowed directly inside
-  display components.
-- Interpolate variables through i18next, never string concatenation:
-  `t("posts.pagination.summary", { page, pageCount })`.
-
-## Where keys live
-
-- App copy: `apps/webapp/translations/en/<namespace>.json` — add the key in
-  the same change that uses it.
-- Role labels and app-level chrome: `apps/webapp/translations/app.json`
-  (resolved as `app:...`, e.g. `app:organization.role.editor`).
-- Auth/billing route copy ships with `@m5kdev/web-ui` (`web-ui:` namespace) —
-  do not duplicate it.
-
-## Key conventions
-
-- Structure keys as `<feature>.<section>.<name>`:
-  `posts.editor.fields.title`, `posts.toast.created`, `layout.push.cta`.
-- Reuse existing keys before adding near-duplicates.
-
-## Server errors
-
-Backend `ServerError` responses carry i18n-style client messages
-(`server.error.<layer>.<code>`). When surfacing mutation errors, prefer a
-translated, human message; fall back to `error.message` only when no
-translation exists.
+---
+globs: apps/**/webapp/src/**/*.tsx
+alwaysApply: false
+---
+
+# Frontend i18n Style Guide
+
+All user-facing copy goes through i18next. No hardcoded strings in JSX,
+toasts, aria-labels, or placeholders.
+
+## Usage
+
+```tsx
+const { t } = useTranslation("<app-namespace>");
+<h2>{t("posts.hero.title")}</h2>
+<Input placeholder={t("posts.filters.searchPlaceholder")} aria-label={t("posts.filters.searchLabel")} />
+toast.success(t("posts.toast.created"));
+```
+
+- `useTranslation(...)` is one of the few hooks always allowed directly inside
+  display components.
+- Interpolate variables through i18next, never string concatenation:
+  `t("posts.pagination.summary", { page, pageCount })`.
+
+## Where keys live
+
+- App copy: `apps/webapp/translations/en/<namespace>.json` — add the key in
+  the same change that uses it.
+- Role labels and app-level chrome: `apps/webapp/translations/app.json`
+  (resolved as `app:...`, e.g. `app:organization.role.editor`).
+- Auth/billing route copy ships with `@m5kdev/web-ui` (`web-ui:` namespace) —
+  do not duplicate it.
+
+## Key conventions
+
+- Structure keys as `<feature>.<section>.<name>`:
+  `posts.editor.fields.title`, `posts.toast.created`, `layout.push.cta`.
+- Reuse existing keys before adding near-duplicates.
+
+## Server errors
+
+Backend `ServerError` responses carry i18n-style client messages
+(`server.error.<layer>.<code>`). When surfacing mutation errors, prefer a
+translated, human message; fall back to `error.message` only when no
+translation exists.

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

@@ -1,60 +1,60 @@
----
-globs: apps/**/server/src/modules/**/*.dto.ts
-alwaysApply: false
----
-
-# Module DTO Style Guide
-
-The DTO is the module's API surface, **derived from the Drizzle table** —
-database schema first. Services, repositories, and tRPC files import the DTO
-*object* (`postSchemas`) and reference `postSchemas.input.x` /
-`postSchemas.output.y`; they do not import hand-written types.
-
-## The pattern
-
-```ts
-import { createZodSchemas } from "@m5kdev/backend/base/base.dto";
-import {
-  postCreateInputSchema,
-  postUpdateInputSchema,
-} from "{{PACKAGE_SCOPE}}/shared/modules/posts/posts.schema";
-import { z } from "zod";
-import { posts } from "./posts.db";
-
-const { output, input } = createZodSchemas(posts);
-
-export const postSchemas = {
-  output,
-  input: {
-    ...input,
-    // create/update come from shared: the same schemas validate the webapp
-    // form, so the API contract and frontend validation cannot drift
-    create: postCreateInputSchema,
-    update: postUpdateInputSchema,
-    publish: z.object({ id: z.string() }),
-  },
-};
-```
-
-## What `createZodSchemas(table)` provides
-
-- `output.single` — the row (from `createSelectSchema`).
-- `output.found` — `single.optional()`, for find-style queries that may
-  return nothing.
-- `output.list` — `{ rows, total }` envelope.
-- `output.uuid` / `output.uuids` — id acknowledgements.
-- `input.list` — the generic `querySchema` (pagination, sorting, `q`,
-  `filters`).
-- `input.read/readMany/delete/deleteMany` — id inputs.
-- `input.create` / `input.update` — raw insert/update schemas from the table.
-
-## Rules
-
-- **Always override `input.create` and `input.update`** with narrower schemas:
-  the raw insert schema exposes server-managed columns (`id`, timestamps,
-  owner ids) that clients must never send. If the frontend validates the same
-  form, import the schema from shared instead of redefining it.
-- Add action-specific inputs (`publish`, `archive`) as plain Zod objects here.
-- Extend `input.list` only when a custom list contract is genuinely needed;
-  prefer the generic `q`/`filters` contract (see repository guide).
-- One exported `<module>Schemas` object per module — no loose schema exports.
+---
+globs: apps/**/server/src/modules/**/*.dto.ts
+alwaysApply: false
+---
+
+# Module DTO Style Guide
+
+The DTO is the module's API surface, **derived from the Drizzle table** —
+database schema first. Services, repositories, and tRPC files import the DTO
+*object* (`postSchemas`) and reference `postSchemas.input.x` /
+`postSchemas.output.y`; they do not import hand-written types.
+
+## The pattern
+
+```ts
+import { createZodSchemas } from "@m5kdev/backend/base/base.dto";
+import {
+  postCreateInputSchema,
+  postUpdateInputSchema,
+} from "{{PACKAGE_SCOPE}}/shared/modules/posts/posts.schema";
+import { z } from "zod";
+import { posts } from "./posts.db";
+
+const { output, input } = createZodSchemas(posts);
+
+export const postSchemas = {
+  output,
+  input: {
+    ...input,
+    // create/update come from shared: the same schemas validate the webapp
+    // form, so the API contract and frontend validation cannot drift
+    create: postCreateInputSchema,
+    update: postUpdateInputSchema,
+    publish: z.object({ id: z.string() }),
+  },
+};
+```
+
+## What `createZodSchemas(table)` provides
+
+- `output.single` — the row (from `createSelectSchema`).
+- `output.found` — `single.optional()`, for find-style queries that may
+  return nothing.
+- `output.list` — `{ rows, total }` envelope.
+- `output.uuid` / `output.uuids` — id acknowledgements.
+- `input.list` — the generic `querySchema` (pagination, sorting, `q`,
+  `filters`).
+- `input.read/readMany/delete/deleteMany` — id inputs.
+- `input.create` / `input.update` — raw insert/update schemas from the table.
+
+## Rules
+
+- **Always override `input.create` and `input.update`** with narrower schemas:
+  the raw insert schema exposes server-managed columns (`id`, timestamps,
+  owner ids) that clients must never send. If the frontend validates the same
+  form, import the schema from shared instead of redefining it.
+- Add action-specific inputs (`publish`, `archive`) as plain Zod objects here.
+- Extend `input.list` only when a custom list contract is genuinely needed;
+  prefer the generic `q`/`filters` contract (see repository guide).
+- One exported `<module>Schemas` object per module — no loose schema exports.