create-m5kdev 0.25.1 → 0.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-m5kdev",
-  "version": "0.25.1",
+  "version": "0.25.2",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

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

@@ -0,0 +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.

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

@@ -0,0 +1,59 @@
+---
+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.
+
+## 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<PostsListOutputSchema>
+);
+```
+
+- Input and output types come from the shared Zod schemas in `apps/shared` —
+  never redeclare them locally.
+- Search inputs that feed queries go through `useDeferredValue`, and URL-state
+  updates are wrapped in `startTransition`.
+
+## 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),
+  })
+);
+```
+
+## Invalidation discipline
+
+- Invalidate intentionally with the matching `queryFilter()` after mutations.
+- Never call `queryClient.clear()` or invalidate everything.
+
+## 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

@@ -0,0 +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.

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

@@ -0,0 +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).

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

@@ -0,0 +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.

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.db.ts
+globs: apps/**/server/src/modules/**/*.db.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.grants.ts
+globs: apps/**/server/src/modules/**/*.grants.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.module.ts
+globs: apps/**/server/src/modules/**/*.module.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.repository.ts
+globs: apps/**/server/src/modules/**/*.repository.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/shared/src/modules/**/*.schema.ts
+globs: apps/**/shared/src/modules/**/*.schema.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.service.ts
+globs: apps/**/server/src/modules/**/*.service.ts
 alwaysApply: false
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-globs: apps/*/server/src/modules/**/*.trpc.ts
+globs: apps/**/server/src/modules/**/*.trpc.ts
 alwaysApply: false
 ---
 

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

@@ -32,3 +32,10 @@
 - For upgrading existing apps, see the docs site guide `apps/docs/docs/guides/custom-app-roles-migration.md`.
 - Use `nuqs` for URL state, React Router for routing, HeroUI for UI primitives, and Tailwind v4 for styling.
 - Prefer shared framework utilities from `@m5kdev/frontend` and `@m5kdev/web-ui` before adding local duplicates.
+- React 19 idioms: no `forwardRef` (pass `ref` as a prop), no `defaultProps`, use `startTransition`/`useDeferredValue` for low-priority updates.
+- Prefer HeroUI v3 components over hand-rolled HTML + Tailwind whenever an equivalent exists; Tailwind is for layout and styling on top of them.
+- Keep components display-focused: data fetching, mutations, URL state, and effect chains live in custom hooks under `modules/<feature>/hooks/` (small focused hooks composed into one screen-level hook, e.g. `usePostsRoute`). Ephemeral UI state (modal open, selected row) may stay in the component. Extract reusable tRPC actions (delete, publish) into their own hooks.
+- Fetch all server data with TanStack Query over tRPC (`useTRPC()` + `queryOptions`/`mutationOptions`); invalidate with the matching `queryFilter()` after mutations. No `fetch`/axios.
+- Forms are uncontrolled HeroUI `Form` + `TextField`/`TextArea` with native HTML validation (`isRequired`, `type`, `minLength`) and `FieldError`; read values from `FormData` on submit. Never add form libraries (react-hook-form, formik). Validation that HTML cannot express (e.g. confirm-password) happens in the submit handler.
+- All user-facing copy goes through i18next (`useTranslation`); keys live in `apps/webapp/translations/`.
+- The `posts` feature (`apps/webapp/src/modules/posts/`) is the reference implementation for these conventions; see `.cursor/rules/frontend-*.mdc` for the detailed guides.

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

@@ -10,14 +10,14 @@
     "email:dev": "react-email dev --dir src/emails"
   },
   "dependencies": {
-    "@m5kdev/commons": "workspace:*",
-    "@m5kdev/email": "workspace:*",
+    "@m5kdev/commons": "catalog:",
+    "@m5kdev/email": "catalog:",
     "@react-email/components": "catalog:",
     "react": "catalog:",
     "react-dom": "catalog:"
   },
   "devDependencies": {
-    "@m5kdev/backend": "workspace:*",
+    "@m5kdev/backend": "catalog:",
     "@m5kdev/config": "catalog:",
     "@types/node": "catalog:",
     "@types/react": "catalog:",

package/templates/minimal-app/apps/webapp/AGENTS.md.tpl

@@ -1,18 +1,24 @@
-# AGENTS.md
-
-## Frontend Stack
-
-- React + TypeScript
-- React Router v7
-- HeroUI
-- Tailwind CSS v4
-- `nuqs` for URL state
-- TanStack Query + tRPC
-
-## Conventions
-
-- Keep providers centralized in `src/Providers.tsx`.
-- Keep routing in `src/Router.tsx`.
-- Keep feature code grouped under `src/modules/<feature>/`.
-- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
-- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
+# AGENTS.md
+
+## Frontend Stack
+
+- React 19 + TypeScript
+- React Router v7
+- HeroUI v3
+- Tailwind CSS v4
+- `nuqs` for URL state
+- TanStack Query + tRPC
+- i18next for all user-facing copy
+
+## Conventions
+
+- Keep providers centralized in `src/Providers.tsx`.
+- Keep routing in `src/Router.tsx`.
+- Keep feature code grouped under `src/modules/<feature>/` with `components/` and `hooks/` subfolders.
+- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
+- Components stay display-focused: queries, mutations, URL state, and effects live in custom hooks (`hooks/use<Feature>Route.ts` composed from smaller hooks); ephemeral UI state (modal open, selected row) may stay in the component. Reusable tRPC actions (delete, publish) get their own hook.
+- Derive values during render instead of syncing state with `useEffect`.
+- Forms are uncontrolled: HeroUI `Form` + `TextField` with native HTML validation and `FieldError`, values read from `FormData` on submit. No form libraries. Extra checks that HTML validation cannot express happen in the submit handler.
+- Fetch through `useTRPC()` + `queryOptions`/`mutationOptions` only; invalidate with `queryFilter()` after mutations.
+- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
+- The `posts` module is the reference implementation; detailed guides live in `.cursor/rules/frontend-*.mdc`.

package/templates/minimal-app/apps/webapp/public/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="App logo">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#b45309"/>
+  <path d="M20 18h18a6 6 0 0 1 6 6v22a2 2 0 0 1-3.2 1.6L36 44H20a4 4 0 0 1-4-4V22a4 4 0 0 1 4-4z" fill="#fffbeb"/>
+  <line x1="23" y1="27" x2="39" y2="27" stroke="#b45309" stroke-width="3" stroke-linecap="round"/>
+  <line x1="23" y1="34" x2="39" y2="34" stroke="#d97706" stroke-width="3" stroke-linecap="round"/>
+</svg>