create-m5kdev 0.40.2 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m5kdev",
-  "version": "0.40.2",
+  "version": "0.41.0",
   "license": "GPL-3.0-only",
   "engines": {
     "node": ">=24"

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

@@ -1,95 +1,95 @@
----
-globs: apps/**/webapp/src/**/*.tsx
-alwaysApply: false
----
-
-# Frontend Component Style Guide
-
-Conventions for React components in the webapp. The stack is fixed: React 19,
-HeroUI v3, Tailwind CSS v4, react-router v7, nuqs, TanStack Query over tRPC,
-i18next. Do not introduce alternatives.
-
-## HeroUI before raw Tailwind
-
-When a HeroUI component exists for the element you are building, use it instead
-of hand-rolled HTML + Tailwind: `Button`, `Input`, `TextField`, `TextArea`,
-`Select`, `ListBox`, `Modal`, `Card`, `Chip`, `Skeleton`, `Form`, `Label`,
-`FieldError`, `toast`. Tailwind utilities are for layout, spacing, and visual
-styling on top of these primitives — not for rebuilding them.
-
-```tsx
-// GOOD
-<Button variant="primary" isPending={isSaving} onPress={openCreate}>...</Button>
-
-// BAD — hand-rolled button
-<div className="cursor-pointer rounded bg-blue-600 px-4 py-2" onClick={...}>
-```
-
-## Components stay readable, logic lives in hooks
-
-The measure is readability, not dogma: someone editing the JSX should not have
-to scroll through business logic to find it. Data fetching, mutations, URL
-state, and effect chains belong in custom hooks (see the frontend hook guide).
-
-Allowed directly in a component:
-
-- `useTranslation` and small formatting helpers (dates, reading time).
-- `useId` for accessibility wiring.
-- Ephemeral UI state that never leaves the component: modal open/closed,
-  selected row, hover/expanded toggles.
-- A few small hooks that comfortably fit before the returned JSX.
-
-Not allowed directly in feature/route components:
-
-- `useQuery` / `useMutation` clusters, `queryClient` calls, tRPC wiring.
-- `useEffect` chains that synchronize state.
-- nuqs URL-state definitions for filters/pagination/tabs.
-
-```tsx
-// GOOD — one feature hook, ephemeral UI state local, display-focused JSX
-export function PostsRoute() {
-  const { t } = useTranslation("blog");
-  const posts = usePostsRoute();
-  const [selectedPostId, setSelectedPostId] = useState<string>();
-  const selectedPost = posts.rows.find((r) => r.id === selectedPostId) ?? posts.rows[0];
-  return (/* JSX built from `posts` + local UI state */);
-}
-```
-
-## Derive, don't sync
-
-Compute values from data during render instead of mirroring them into state
-with `useEffect`.
-
-```tsx
-// GOOD
-const selectedPost = rows.find((r) => r.id === selectedPostId) ?? rows[0];
-
-// BAD — effect that re-syncs state after every data change
-useEffect(() => {
-  if (!rows.some((r) => r.id === selectedPostId)) setSelectedPostId(rows[0]?.id);
-}, [rows, selectedPostId]);
-```
-
-## React 19 idioms
-
-- No `forwardRef` — pass `ref` as a regular prop.
-- No `defaultProps` — use parameter defaults.
-- Use `startTransition` / `useDeferredValue` for low-priority updates such as
-  search inputs that feed queries.
-
-## Required states
-
-Every data-driven view renders explicit loading (`Skeleton`), empty, and error
-states. Never return `null` while data is loading.
-
-## Subcomponents
-
-Presentational subcomponents receive everything via props — no data fetching,
-no feature hooks inside them. Co-locate them under
-`modules/<feature>/components/` (or in-file when tiny).
-
-## Text
-
-All user-facing strings go through `useTranslation` — no hardcoded copy. See
-the frontend i18n guide.
+---
+globs: apps/**/webapp/src/**/*.tsx
+alwaysApply: false
+---
+
+# Frontend Component Style Guide
+
+Conventions for React components in the webapp. The stack is fixed: React 19,
+HeroUI v3, Tailwind CSS v4, react-router v7, nuqs, TanStack Query over tRPC,
+i18next. Do not introduce alternatives.
+
+## HeroUI before raw Tailwind
+
+When a HeroUI component exists for the element you are building, use it instead
+of hand-rolled HTML + Tailwind: `Button`, `Input`, `TextField`, `TextArea`,
+`Select`, `ListBox`, `Modal`, `Card`, `Chip`, `Skeleton`, `Form`, `Label`,
+`FieldError`, `toast`. Tailwind utilities are for layout, spacing, and visual
+styling on top of these primitives — not for rebuilding them.
+
+```tsx
+// GOOD
+<Button variant="primary" isPending={isSaving} onPress={openCreate}>...</Button>
+
+// BAD — hand-rolled button
+<div className="cursor-pointer rounded bg-blue-600 px-4 py-2" onClick={...}>
+```
+
+## Components stay readable, logic lives in hooks
+
+The measure is readability, not dogma: someone editing the JSX should not have
+to scroll through business logic to find it. Data fetching, mutations, URL
+state, and effect chains belong in custom hooks (see the frontend hook guide).
+
+Allowed directly in a component:
+
+- `useTranslation` and small formatting helpers (dates, reading time).
+- `useId` for accessibility wiring.
+- Ephemeral UI state that never leaves the component: modal open/closed,
+  selected row, hover/expanded toggles.
+- A few small hooks that comfortably fit before the returned JSX.
+
+Not allowed directly in feature/route components:
+
+- `useQuery` / `useMutation` clusters, `queryClient` calls, tRPC wiring.
+- `useEffect` chains that synchronize state.
+- nuqs URL-state definitions for filters/pagination/tabs.
+
+```tsx
+// GOOD — one feature hook, ephemeral UI state local, display-focused JSX
+export function PostsRoute() {
+  const { t } = useTranslation("blog");
+  const posts = usePostsRoute();
+  const [selectedPostId, setSelectedPostId] = useState<string>();
+  const selectedPost = posts.rows.find((r) => r.id === selectedPostId) ?? posts.rows[0];
+  return (/* JSX built from `posts` + local UI state */);
+}
+```
+
+## Derive, don't sync
+
+Compute values from data during render instead of mirroring them into state
+with `useEffect`.
+
+```tsx
+// GOOD
+const selectedPost = rows.find((r) => r.id === selectedPostId) ?? rows[0];
+
+// BAD — effect that re-syncs state after every data change
+useEffect(() => {
+  if (!rows.some((r) => r.id === selectedPostId)) setSelectedPostId(rows[0]?.id);
+}, [rows, selectedPostId]);
+```
+
+## React 19 idioms
+
+- No `forwardRef` — pass `ref` as a regular prop.
+- No `defaultProps` — use parameter defaults.
+- Use `startTransition` / `useDeferredValue` for low-priority updates such as
+  search inputs that feed queries.
+
+## Required states
+
+Every data-driven view renders explicit loading (`Skeleton`), empty, and error
+states. Never return `null` while data is loading.
+
+## Subcomponents
+
+Presentational subcomponents receive everything via props — no data fetching,
+no feature hooks inside them. Co-locate them under
+`modules/<feature>/components/` (or in-file when tiny).
+
+## Text
+
+All user-facing strings go through `useTranslation` — no hardcoded copy. See
+the frontend i18n guide.

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

@@ -1,103 +1,103 @@
----
-globs: apps/**/webapp/src/**/*.ts*
-alwaysApply: false
----
-
-# Frontend Data Fetching Style Guide
-
-All server communication goes through tRPC with the TanStack React Query
-integration. No `fetch`, no axios, no hand-written API clients.
-
-## Types come from the server — never hand-mirror them
-
-Row and payload types are **inferred from the router**, not redeclared:
-
-```ts
-import type { inferRouterOutputs } from "@trpc/server";
-import type { AppRouter } from "{{PACKAGE_SCOPE}}/server/types";
-
-type PostsListOutput = inferRouterOutputs<AppRouter>["posts"]["list"];
-export type PostRow = PostsListOutput["rows"][number];
-```
-
-Shared Zod schemas (`apps/shared`) are only for runtime needs — form
-validation, or schemas the server DTO also imports. Never write a shared
-schema that just mirrors a server response; it will drift (see the shared
-schema guide).
-
-## Queries
-
-Use `useTRPC()` and the generated `queryOptions`:
-
-```ts
-const trpc = useTRPC();
-const { data, isLoading, isFetching } = useQuery(
-  trpc.posts.list.queryOptions(listInput) as unknown as UseQueryOptions<PostsListOutput>
-);
-```
-
-- Search inputs that feed queries go through `useDeferredValue`, and URL-state
-  updates are wrapped in `startTransition`.
-
-## List endpoints speak the generic query contract
-
-Module list procedures accept `QueryInput` from
-`@m5kdev/commons/modules/schemas/query.schema` — `page`, `limit`, `sort`,
-`order`, `q` (global search), and `filters`. Do not invent per-module fields
-like `search` or `status` at the top level; they will be stripped by input
-validation and silently ignored.
-
-```ts
-const listInput = useMemo<QueryInput>(
-  () => ({
-    page,
-    limit: PAGE_SIZE,
-    q: deferredSearch || undefined,
-    filters:
-      status === "all"
-        ? undefined
-        : [{ columnId: "status", type: "enum", method: "equals", value: status }],
-    sort: "updatedAt",
-    order: "desc",
-  }),
-  [deferredSearch, page, status]
-);
-```
-
-## Mutations
-
-Use `mutationOptions` with success/error handling declared where the mutation
-is created (inside a custom hook):
-
-```ts
-const createMutation = useMutation(
-  trpc.posts.create.mutationOptions({
-    onSuccess: async () => {
-      toast.success(t("posts.toast.created"));
-      await queryClient.invalidateQueries(trpc.posts.list.queryFilter());
-    },
-    onError: (error) => toast.error(error.message),
-  })
-);
-```
-
-Mutation input shapes are enforced by the router's inferred types — no
-`satisfies SomeSchema` casts needed for simple `{ id }` payloads.
-
-## Invalidation discipline
-
-- Invalidate intentionally with the matching `queryFilter()` after mutations.
-- Never call `queryClient.clear()` or invalidate everything.
-- Background Workflow completions: invalidate from a `ServerEventProvider` handler. The trigger mutation only returns `jobId`. See `.cursor/rules/server-event-emit.mdc`.
-
-## Pending state
-
-- Screen-level: `mutation.isPending`.
-- Row-level (a list where one item is being deleted):
-  `mutation.isPending && mutation.variables?.id === row.id`, exposed from the
-  hook as `deletingId` / `publishingId`.
-
-## Placement
-
-Queries and mutations live in custom hooks under
-`modules/<feature>/hooks/`, not in components — see the frontend hook guide.
+---
+globs: apps/**/webapp/src/**/*.ts*
+alwaysApply: false
+---
+
+# Frontend Data Fetching Style Guide
+
+All server communication goes through tRPC with the TanStack React Query
+integration. No `fetch`, no axios, no hand-written API clients.
+
+## Types come from the server — never hand-mirror them
+
+Row and payload types are **inferred from the router**, not redeclared:
+
+```ts
+import type { inferRouterOutputs } from "@trpc/server";
+import type { AppRouter } from "{{PACKAGE_SCOPE}}/server/types";
+
+type PostsListOutput = inferRouterOutputs<AppRouter>["posts"]["list"];
+export type PostRow = PostsListOutput["rows"][number];
+```
+
+Shared Zod schemas (`apps/shared`) are only for runtime needs — form
+validation, or schemas the server DTO also imports. Never write a shared
+schema that just mirrors a server response; it will drift (see the shared
+schema guide).
+
+## Queries
+
+Use `useTRPC()` and the generated `queryOptions`:
+
+```ts
+const trpc = useTRPC();
+const { data, isLoading, isFetching } = useQuery(
+  trpc.posts.list.queryOptions(listInput) as unknown as UseQueryOptions<PostsListOutput>
+);
+```
+
+- Search inputs that feed queries go through `useDeferredValue`, and URL-state
+  updates are wrapped in `startTransition`.
+
+## List endpoints speak the generic query contract
+
+Module list procedures accept `QueryInput` from
+`@m5kdev/commons/modules/schemas/query.schema` — `page`, `limit`, `sort`,
+`order`, `q` (global search), and `filters`. Do not invent per-module fields
+like `search` or `status` at the top level; they will be stripped by input
+validation and silently ignored.
+
+```ts
+const listInput = useMemo<QueryInput>(
+  () => ({
+    page,
+    limit: PAGE_SIZE,
+    q: deferredSearch || undefined,
+    filters:
+      status === "all"
+        ? undefined
+        : [{ columnId: "status", type: "enum", method: "equals", value: status }],
+    sort: "updatedAt",
+    order: "desc",
+  }),
+  [deferredSearch, page, status]
+);
+```
+
+## Mutations
+
+Use `mutationOptions` with success/error handling declared where the mutation
+is created (inside a custom hook):
+
+```ts
+const createMutation = useMutation(
+  trpc.posts.create.mutationOptions({
+    onSuccess: async () => {
+      toast.success(t("posts.toast.created"));
+      await queryClient.invalidateQueries(trpc.posts.list.queryFilter());
+    },
+    onError: (error) => toast.error(error.message),
+  })
+);
+```
+
+Mutation input shapes are enforced by the router's inferred types — no
+`satisfies SomeSchema` casts needed for simple `{ id }` payloads.
+
+## Invalidation discipline
+
+- Invalidate intentionally with the matching `queryFilter()` after mutations.
+- Never call `queryClient.clear()` or invalidate everything.
+- Background Workflow completions: invalidate from a `ServerEventProvider` handler. The trigger mutation only returns `jobId`. See `.cursor/rules/server-event-emit.mdc`.
+
+## Pending state
+
+- Screen-level: `mutation.isPending`.
+- Row-level (a list where one item is being deleted):
+  `mutation.isPending && mutation.variables?.id === row.id`, exposed from the
+  hook as `deletingId` / `publishingId`.
+
+## Placement
+
+Queries and mutations live in custom hooks under
+`modules/<feature>/hooks/`, not in components — see the frontend hook guide.

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

@@ -1,80 +1,80 @@
----
-globs: apps/**/webapp/src/**/*.tsx
-alwaysApply: false
----
-
-# Frontend Form Style Guide
-
-Forms are uncontrolled HeroUI v3 forms with native HTML validation. The server
-already validates every input through tRPC + Zod — the client only needs the
-built-in validators, which HeroUI renders nicely.
-
-## Never use form libraries
-
-Do not add react-hook-form, formik, react-final-form, or any controlled-form
-state manager. No `useState` per field, no `onChange` mirroring.
-
-## The pattern
-
-`Form` + `TextField`/`TextArea` with `name`, `defaultValue`, and `isRequired` /
-`type` / `minLength` for validation; `FieldError` renders the native message.
-Read values from `FormData` on submit.
-
-```tsx
-export function PostEditorForm({ post, isSaving, onSave, onClose }: Props) {
-  const { t } = useTranslation("blog");
-
-  const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    const formData = new FormData(event.currentTarget);
-    const payload = {
-      title: String(formData.get("title") ?? "").trim(),
-      content: String(formData.get("content") ?? "").trim(),
-    };
-    if (await onSave(payload, post?.id)) onClose();
-  };
-
-  return (
-    // key remounts the form so defaultValue updates when editing another row
-    <Form key={post?.id ?? "new"} onSubmit={onSubmit}>
-      <TextField isRequired name="title" defaultValue={post?.title ?? ""}>
-        <Label>{t("posts.editor.fields.title")}</Label>
-        <Input />
-        <FieldError />
-      </TextField>
-      <TextField isRequired name="content" defaultValue={post?.content ?? ""}>
-        <Label>{t("posts.editor.fields.content")}</Label>
-        <TextArea rows={10} />
-        <FieldError />
-      </TextField>
-      <Button type="submit" variant="primary" isPending={isSaving}>
-        {t("posts.editor.save")}
-      </Button>
-    </Form>
-  );
-}
-```
-
-The HeroUI `Form` blocks submission and shows `FieldError` messages until
-native constraints pass — no validation code needed for required fields,
-email formats, or lengths.
-
-## Extra validation on submit only
-
-When a rule cannot be expressed with native HTML validation (for example,
-password and confirm-password matching), check it inside the submit handler
-after reading `FormData`, and surface the failure with a toast or field-level
-message. Do not reach for a validation library for this.
-
-```tsx
-if (formData.get("password") !== formData.get("confirmPassword")) {
-  toast.error(t("auth.errors.passwordMismatch"));
-  return;
-}
-```
-
-## Submission state
-
-- The submit `Button` gets `isPending` from the mutation's pending flag.
-- The mutation itself (and its success/error toasts) lives in a custom hook;
-  the form component only parses `FormData` and calls the action.
+---
+globs: apps/**/webapp/src/**/*.tsx
+alwaysApply: false
+---
+
+# Frontend Form Style Guide
+
+Forms are uncontrolled HeroUI v3 forms with native HTML validation. The server
+already validates every input through tRPC + Zod — the client only needs the
+built-in validators, which HeroUI renders nicely.
+
+## Never use form libraries
+
+Do not add react-hook-form, formik, react-final-form, or any controlled-form
+state manager. No `useState` per field, no `onChange` mirroring.
+
+## The pattern
+
+`Form` + `TextField`/`TextArea` with `name`, `defaultValue`, and `isRequired` /
+`type` / `minLength` for validation; `FieldError` renders the native message.
+Read values from `FormData` on submit.
+
+```tsx
+export function PostEditorForm({ post, isSaving, onSave, onClose }: Props) {
+  const { t } = useTranslation("blog");
+
+  const onSubmit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const formData = new FormData(event.currentTarget);
+    const payload = {
+      title: String(formData.get("title") ?? "").trim(),
+      content: String(formData.get("content") ?? "").trim(),
+    };
+    if (await onSave(payload, post?.id)) onClose();
+  };
+
+  return (
+    // key remounts the form so defaultValue updates when editing another row
+    <Form key={post?.id ?? "new"} onSubmit={onSubmit}>
+      <TextField isRequired name="title" defaultValue={post?.title ?? ""}>
+        <Label>{t("posts.editor.fields.title")}</Label>
+        <Input />
+        <FieldError />
+      </TextField>
+      <TextField isRequired name="content" defaultValue={post?.content ?? ""}>
+        <Label>{t("posts.editor.fields.content")}</Label>
+        <TextArea rows={10} />
+        <FieldError />
+      </TextField>
+      <Button type="submit" variant="primary" isPending={isSaving}>
+        {t("posts.editor.save")}
+      </Button>
+    </Form>
+  );
+}
+```
+
+The HeroUI `Form` blocks submission and shows `FieldError` messages until
+native constraints pass — no validation code needed for required fields,
+email formats, or lengths.
+
+## Extra validation on submit only
+
+When a rule cannot be expressed with native HTML validation (for example,
+password and confirm-password matching), check it inside the submit handler
+after reading `FormData`, and surface the failure with a toast or field-level
+message. Do not reach for a validation library for this.
+
+```tsx
+if (formData.get("password") !== formData.get("confirmPassword")) {
+  toast.error(t("auth.errors.passwordMismatch"));
+  return;
+}
+```
+
+## Submission state
+
+- The submit `Button` gets `isPending` from the mutation's pending flag.
+- The mutation itself (and its success/error toasts) lives in a custom hook;
+  the form component only parses `FormData` and calls the action.