gemi 0.59.0 → 0.60.0

package/skills/gemi-react-best-practices/rules/client-form-vs-mutation-hooks.md

@@ -0,0 +1,57 @@
+---
+title: Reach for Form First, Mutation Hooks When You Need Control
+impact: MEDIUM
+impactDescription: CSRF, FormData and field errors for free
+tags: client, forms, mutations, validation
+---
+
+## Reach for Form First, Mutation Hooks When You Need Control
+
+`<Form>` wraps a native form and handles what is otherwise hand-written every time:
+collecting fields into `FormData`, attaching the CSRF token, tracking pending state,
+and exposing the server's per-field `validation_error` messages through context.
+
+**Incorrect (re-implementing all of it, and losing field errors):**
+
+```tsx
+const { trigger, loading } = usePost("/admin/user");
+const [name, setName] = useState("");
+const [errors, setErrors] = useState({});
+
+async function onSubmit(e) {
+  e.preventDefault();
+  const res = await trigger({ name });
+  if (res?.error?.kind === "validation_error") setErrors(res.error.messages);
+}
+```
+
+**Correct:**
+
+```tsx
+import { Form, ValidationErrors } from "gemi/client";
+
+<Form action="/admin/user" method="POST"
+      onSuccess={(_data, form) => { form.reset(); push("/admin/users"); }}>
+  <input name="name" />
+  <ValidationErrors name="name" />
+  <FormError />
+  <button type="submit">Create</button>
+</Form>;
+```
+
+Inside a `Form`, three hooks read its context: `useFormStatus()`
+(`{ isPending, validationErrors, formError }`), `useMutationStatus()`
+(`{ isPending }`), and `useFormData()` for live `FormData` as the user types. The
+form also carries a `data-loading` attribute for styling.
+
+**Use the mutation hooks (`usePost` / `usePut` / `usePatch` / `useDelete`) when the
+write is not a form submission** — a button that toggles a flag, an action in a menu,
+an optimistic list operation. Pair them with `useMutate` to update the reading
+query's cache rather than refetching.
+
+**File posts that need to be unit-testable use `usePost` with `FormData`.**
+`useUpload` is XHR-based, which is what gives it progress events and also what makes
+it uninterceptable by MSW under happy-dom — reach for it only when you need the
+progress bar.
+
+Reference: <https://nstfkc.github.io/gemi/forms.md>

package/skills/gemi-react-best-practices/rules/client-loading-error-exports.md

@@ -0,0 +1,54 @@
+---
+title: A Route Module's Loading and Error Exports Are Its Suspense Boundary
+impact: MEDIUM
+impactDescription: correct fallback placement, no full-page blanking
+tags: render, suspense, ssr, boundaries
+---
+
+## A Route Module's Loading and Error Exports Are Its Suspense Boundary
+
+A view module declares its own suspense boundary by exporting `Loading` and
+`Error` **alongside** its default export — there is no separate file convention for
+either. Since
+`useQuery` suspends by default (`query-suspense-default`), a route with no `Loading`
+export falls back to whatever boundary happens to be above it — often a bare
+`<Suspense fallback={null}>`, which blanks the surface.
+
+**Incorrect (no boundary of its own; suspending blanks whatever is above):**
+
+```tsx
+export default function Todos() {
+  const { data } = useQuery("/todos");
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+```
+
+**Correct:**
+
+```tsx
+export default function Todos() {
+  const { data } = useQuery("/todos");
+  return <ul>{data.map((t) => <li key={t.id}>{t.title}</li>)}</ul>;
+}
+
+export function Loading() {
+  return <TodosSkeleton />;
+}
+
+export function Error({ error, resetErrorBoundary }) {
+  return <button onClick={() => resetErrorBoundary()}>Retry</button>;
+}
+```
+
+**Place the boundary where the blank is acceptable.** A route-level `Loading` is
+right for the route's primary read. For a secondary widget, do not add a boundary —
+give that query `{ suspense: false }` and render its loading state in place, so the
+rest of the page keeps its content.
+
+**Do not hand-roll a navigation spinner.** gemi already commits navigations in a
+transition, keeping the previous page visible until the new page's queries resolve,
+and the production shell preloads the chunks in the current route's component chain.
+`Link` sets `data-pending` during navigation if you want to style the transition —
+reach for that before adding state.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/client-no-effect-data-flow.md

@@ -0,0 +1,68 @@
+---
+title: Do Not Route Data Flow Through useEffect
+impact: MEDIUM
+impactDescription: removes a render pass and a class of stale-state bugs
+tags: rerender, effects, derived-state, house-style
+---
+
+## Do Not Route Data Flow Through useEffect
+
+An effect that computes state runs *after* a render commits, so it costs an extra
+render pass and opens a window where the UI shows a stale value. This is a standing
+house rule in most gemi apps, not a preference. Three replacements cover almost
+every
+case:
+
+| Instead of an effect that… | Do this |
+|---|---|
+| resets state when a prop or selection changes | reset in the `onChange` handler — it is event-driven |
+| computes a value from other state | derive it in `useMemo` from the source |
+| debounces a value | a debounce hook, applied to the value before it is used |
+
+**Incorrect (three effects doing data flow):**
+
+```tsx
+const [selected, setSelected] = useState(null);
+const [query, setQuery] = useState("");
+const [debounced, setDebounced] = useState("");
+const [options, setOptions] = useState([]);
+
+useEffect(() => { setQuery(""); }, [selected]);            // reset
+useEffect(() => { setOptions(items.filter(fn)); }, [items]); // derive
+useEffect(() => {                                            // debounce
+  const id = setTimeout(() => setDebounced(query), 250);
+  return () => clearTimeout(id);
+}, [query]);
+```
+
+**Correct:**
+
+```tsx
+// gemi ships no debounce hook — this is your own, or one from a library.
+import { useDebounced } from "@/app/hooks/useDebounced";
+
+const [selected, setSelected] = useState(null);
+const [query, setQuery] = useState("");
+const [debouncedQuery] = useDebounced(query.trim(), 250);
+
+const options = useMemo(() => items.filter(fn), [items]);
+
+function onSelect(next) {
+  setSelected(next);
+  setQuery(""); // reset where the event happens
+}
+```
+
+**Whether the memoization here is load-bearing depends on your build.** If your
+`gemi.config.ts` enables the React plugin's `compiler` option — the default in
+projects scaffolded from the gemi template, unless `GEMI_REACT_COMPILER=off` is set —
+the React Compiler memoizes the client build for you, and a hand-written `useMemo` on a derived value is mostly redundant. Without it,
+`useMemo` / `useCallback` on a value that feeds a query variant, an effect dependency,
+or a memoized child is doing real work, not decoration. Check the config before you
+add or remove one.
+
+Either way the *shape* above is the point: derive in `useMemo`, do not compute state
+in an effect. The compiler removes the boilerplate, not the extra render pass.
+
+Effects remain correct for actual synchronization with the outside world:
+subscriptions, event listeners, imperative DOM measurement, timers you own.

package/skills/gemi-react-best-practices/rules/client-typed-links.md

@@ -0,0 +1,51 @@
+---
+title: Navigate With a Typed Link, Not an Interpolated Path String
+impact: MEDIUM-HIGH
+impactDescription: a renamed route breaks the build, not production
+tags: client, navigation, links, types
+---
+
+## Navigate With a Typed Link, Not an Interpolated Path String
+
+`Link` and `useNavigate` take the **route pattern** plus `params`, both typed against
+the routers. Build a URL by hand and the type layer cannot see it: renaming a route
+leaves a template literal that compiles fine and 404s at runtime.
+
+**Incorrect (a string the compiler cannot check):**
+
+```tsx
+<a href={`/app/${orgId}/products/${product.publicId}`}>{product.name}</a>
+<Link href={`/app/${orgId}/chat`}>Chat</Link>
+```
+
+**Correct:**
+
+```tsx
+import { Link, useNavigate } from "gemi/client";
+
+<Link href="/app/:orgId/products/:productId"
+      params={{ orgId, productId: product.publicId }}>
+  {product.name}
+</Link>;
+
+const { push } = useNavigate();
+push("/app/:orgId/chat", { params: { orgId } });
+```
+
+- **`params` are inherited from the current route if omitted**, so a link within the
+  same org needs only the params that change.
+- **`search` and `hash`** are typed props, not string concatenation.
+- **`Link` sets `data-active`** when it matches the current URL and `data-pending`
+  during navigation — style those instead of tracking active state yourself.
+- **`prefetch`** warms the target route (`hover`, `intent`, `viewport`, `render`).
+  A prefetch request carries a `Purpose: prefetch` header, so a handler with side
+  effects must check it before recording a visit.
+- **`useSearchParams`** mutates and then navigates: `searchParams.set("page", next)`
+  then `searchParams.push()`.
+- **`push(..., { shallow: true })`** updates the URL without re-running data loaders.
+
+Prefer a typed `<Link>` over a shared route-string map for new navigation. Some
+existing surfaces read templates from a constants module; match that when editing
+them, but do not extend the pattern.
+
+Reference: <https://nstfkc.github.io/gemi/navigation.md>

package/skills/gemi-react-best-practices/rules/controller-authorize-every-tenant-read.md

@@ -0,0 +1,65 @@
+---
+title: Scope Every Tenant Read, in Middleware or a Policy
+impact: HIGH
+impactDescription: the difference between a bug and a data leak
+tags: controller, authorization, tenancy, security, orm
+---
+
+## Scope Every Tenant Read, in Middleware or a Policy
+
+A route carrying `:orgId` is not authorized by having the parameter — it is
+authorized by checking the signed-in user belongs to that organization. Three layers
+do this, and they compose:
+
+1. **Middleware**, for the coarse gate on the whole router (`"auth"`, `"admin"`,
+   `"org"`, `"role:owner"`). This is where a whole surface is fenced off.
+2. **`Auth.guard(predicate)`** in a controller, for a per-action decision. It throws
+   `InsufficientPermissionsError` on a falsy result; `Auth.guardSafe` returns a
+   boolean instead.
+3. **An ORM policy** on the model — a `scope` that narrows every query, including
+   nested `include`s.
+
+**Incorrect (the parameter is trusted; any signed-in user reads any org):**
+
+```ts
+class OrgRouter extends ApiRouter {
+  middlewares = ["auth"];              // authenticated, but not scoped
+  routes = { "/:orgId/products": this.get(ProductController, "list") };
+}
+
+async list(req: HttpRequest) {
+  return Product.findMany({ where: { organizationId: req.params.orgId } });
+}
+```
+
+**Correct (a membership gate on the router):**
+
+```ts
+class OrgRouter extends ApiRouter {
+  middlewares = ["auth", "org"];      // OrganizationMiddleware checks membership
+  routes = { "/:orgId/products": this.get(ProductController, "list") };
+}
+```
+
+**A policy is the strongest version**, because it reaches reads the controller did
+not write — the `accounts` inside a `User.findMany({ include: { accounts: true } })`
+are scoped too, and relation filters and counts only see scoped rows, so
+"unscoped existence" cannot leak:
+
+```ts
+export class Account extends AccountModel {
+  static $policies: AccountPolicy[] = [
+    {
+      scope: (ctx) => ({ organizationId: ctx.user.organizationId }),
+      onCreate: (ctx, data) => ({ ...data, organizationId: ctx.user.organizationId }),
+    },
+  ];
+}
+```
+
+A policy only applies to a model **registered on `Kernel.models`** via the
+`app/models` barrel — that registration is what makes it apply inside nested
+`include`s. Policies concatenate base-first, so a subclass can narrow an inherited
+policy but never widen it.
+
+Reference: <https://nstfkc.github.io/gemi/authorization.md>

package/skills/gemi-react-best-practices/rules/controller-parse-request-at-the-boundary.md

@@ -0,0 +1,54 @@
+---
+title: Parse the Request at the Boundary, Keep Utils Framework-Free
+impact: MEDIUM
+impactDescription: testable helpers, no framework in the value layer
+tags: controller, utils, structure, testing
+---
+
+## Parse the Request at the Boundary, Keep Utils Framework-Free
+
+**Never pass an `HttpRequest` (or any framework object) into a util.** Read the raw
+value in the controller, parse and clamp it there, and hand the util a plain value.
+A util that takes a request cannot be unit-tested without constructing a request, and
+it quietly becomes controller logic living in the wrong directory.
+
+**Incorrect (the util now depends on the framework):**
+
+```ts
+// app/utils/productFilters.ts
+export function buildProductFilter(req: HttpRequest) {
+  const limit = Number(req.search.get("limit") ?? 25);
+  return { take: Math.min(limit, 100) };
+}
+```
+
+**Correct (controller parses; util stays pure):**
+
+```ts
+// controller
+const { take, skip } = paginate({
+  page: req.search.get("page"),
+  perPage: req.search.get("perPage"),
+});
+const status = optionalNumber(req.search.get("status"));
+
+// app/utils/productFilters.ts — plain values in, plain values out
+export function buildProductFilter(status?: number) {
+  return status === undefined ? {} : { where: { status } };
+}
+```
+
+Where a helper belongs:
+
+- **`app/utils`** — web-only, gemi-adjacent helpers (`optionalNumber`,
+  `safeParseInt`).
+- **A shared workspace package** (`@acme/utils`) — value logic another app **also**
+  needs. Make it the single source of truth; reach for it before writing a local
+  copy, and add a new cross-app rule there rather than duplicating. A local
+  `app/utils/*` module may still exist as a thin facade that adds web-only
+  write-side validation.
+- **A service** (`app/services`) — anything with I/O, a client, or state.
+
+`req.search.get()` returns a string **or `string[]`** for a repeated key, which is
+one more reason the parsing belongs at the boundary where you can decide what a
+repeat means.

package/skills/gemi-react-best-practices/rules/controller-redirect-facade-throws.md

@@ -0,0 +1,68 @@
+---
+title: Never Wrap the Redirect Facade in try/catch
+impact: HIGH
+impactDescription: silently breaks the redirect
+tags: controller, redirect, facades, gotcha
+---
+
+## Never Wrap the Redirect Facade in try/catch
+
+`Redirect` from `gemi/facades` works by **throwing** a special error that the
+framework catches higher up to perform the redirect. A `try/catch` around it — or a
+broad `catch` anywhere up the call stack — swallows that throw, and the redirect
+silently does nothing. Nothing logs; the handler just continues.
+
+Code after a `Redirect.to()` call is unreachable.
+
+**Incorrect (the catch eats the redirect):**
+
+```ts
+async view(req: HttpRequest) {
+  try {
+    const store = await Store.findUnique({ where: { slug } });
+    if (!store) {
+      Redirect.to("/stores");     // throws…
+    }
+    return { store };
+  } catch (error) {                // …and this swallows it
+    Log.error("store view failed", { error });
+    return { store: null };
+  }
+}
+```
+
+**Correct (redirect outside the guarded region):**
+
+```ts
+async view(req: HttpRequest) {
+  let store = null;
+  try {
+    store = await Store.findUnique({ where: { slug } });
+  } catch (error) {
+    Log.error("store lookup failed", { error });
+  }
+
+  if (!store) {
+    Redirect.to("/stores");
+  }
+
+  return { store };
+}
+```
+
+**Two Redirects, and they are not interchangeable:**
+
+- **Facade** (`gemi/facades`) — server-side, in a handler or middleware, *before*
+  rendering. `Redirect.to(path, { params, search })` for internal routes,
+  `Redirect.external(url, status)` for absolute ones.
+- **Component** (`gemi/client`) — client-side, redirects on mount from client state:
+  `if (!user) return <Redirect href="/auth/sign-in" action="replace" />;`
+
+Prefer the facade when the decision is knowable on the server: the component ships
+and renders a page first, then navigates.
+
+`Auth.user()` throws `AuthenticationError` the same way, so the same rule applies to
+it — do not bury an auth check inside a `try/catch`.
+
+Reference: `app/utils/storefrontRedirect.ts`
+<https://nstfkc.github.io/gemi/navigation.md>

package/skills/gemi-react-best-practices/rules/controller-request-schema.md

@@ -0,0 +1,61 @@
+---
+title: Validate With a Request Schema, Not Inline Checks
+impact: HIGH
+impactDescription: one boundary, localized messages, typed body
+tags: controller, validation, requests
+---
+
+## Validate With a Request Schema, Not Inline Checks
+
+Subclass `HttpRequest`, declare a `schema`, and type the controller method against
+it. The framework validates before the method body runs and produces the standard
+`validation_error` response that `<Form>` and the mutation hooks already know how to
+render per field.
+
+Built-in rules: `required`, `string`, `email`, `number`, `password`, `min:N`,
+`max:N`, `file`, `fileType`, `fileSize`. Custom logic goes in a `refine()` override.
+**A field with no value and no `required` rule is skipped**, so optional fields need
+no special handling.
+
+**Incorrect (hand-rolled, unlocalized, and it will drift from the client):**
+
+```ts
+async store(req: HttpRequest<{ name: string }>) {
+  const input = await req.input();
+  const name = input.get("name");
+  if (!name) return { error: "Name is required" };  // wrong shape entirely
+  if (name.length > 120) return { error: "Too long" };
+}
+```
+
+**Correct:**
+
+```ts
+class CreateCustomerRequest extends HttpRequest<{ name: string; email?: string }> {
+  schema = {
+    name: { required: "Name is required", "max:120": "Too long" },
+    email: { email: "Email is invalid", "max:160": "Too long" },
+  };
+}
+
+export class CustomerController extends ResourceController {
+  async store(req: CreateCustomerRequest) {
+    const { name, email } = (await req.input()).toJSON();
+  }
+}
+```
+
+**Localize the messages** rather than hardcoding English — `Dictionary.text({...})`
+from `gemi/i18n` translates an inline string without needing a client dictionary,
+which is exactly what a schema message is:
+
+```ts
+schema = { name: { required: Dictionary.text({ "en-US": "Name is required", "tr-TR": "Ad gerekli" }) } };
+```
+
+**Use `refine()` for a cross-field or lookup rule** — the one place a guard covers
+every path into an endpoint. `req.safeInput()` returns `{ isValid, errors, input }`
+when you need to branch instead of throw.
+
+Reference: `app/http/requests/SignUpRequest.ts` (a `refine()` guard covering every
+sign-up path); <https://nstfkc.github.io/gemi/controllers.md>

package/skills/gemi-react-best-practices/rules/controller-throw-framework-errors.md

@@ -0,0 +1,57 @@
+---
+title: Throw the Framework's Errors, Do Not Invent a Response Shape
+impact: HIGH
+impactDescription: clients already handle these; a custom shape they do not
+tags: controller, errors, validation, client-contract
+---
+
+## Throw the Framework's Errors, Do Not Invent a Response Shape
+
+The client's mutation hooks and `<Form>` branch on a tagged error object —
+`validation_error`, `form_error`, `server_error`, `not_authorized`,
+`insufficient_permissions`. Returning an ad-hoc `{ error: "…" }` from a controller
+produces a **200 with a body the client reads as success**, so the UI shows nothing
+and the failure disappears.
+
+| Throw | Meaning |
+|---|---|
+| `ValidationError({ field: ["msg"] })` | 400, per-field messages `<ValidationErrors>` renders |
+| `AuthenticationError` | 401 — no identity (views redirect to sign-in) |
+| `AuthorizationError("msg")` | 401 — known identity, refused this action |
+| `InsufficientPermissionsError` | 401 — missing a role or permission |
+
+**Incorrect (a 200 that the client cannot distinguish from success):**
+
+```ts
+async update(req: HttpRequest) {
+  const post = await Post.findUniqueOrThrow({ where: { publicId } });
+  if (post.authorId !== user.id) {
+    return { error: "You cannot edit this post", status: 403 };
+  }
+}
+```
+
+**Correct:**
+
+```ts
+import { AuthorizationError, ValidationError } from "gemi/http";
+
+async update(req: HttpRequest) {
+  const post = await Post.findUniqueOrThrow({ where: { publicId } });
+  if (post.authorId !== user.id) {
+    throw new AuthorizationError("You cannot edit this post");
+  }
+  if (!slug) {
+    throw new ValidationError({ slug: ["Slug is required"] });
+  }
+}
+```
+
+**`ValidationError` already yields the right status and body** — do not wrap it, and
+do not build a parallel error convention per endpoint.
+
+**Do not construct a `Response` by hand** to set a status, header or redirect. The
+facades cover it: `Redirect.to(...)`, `Cookie.set(...)`, `Meta.title(...)`. A handler
+returns plain data and the framework serializes it.
+
+Reference: <https://nstfkc.github.io/gemi/controllers.md>

package/skills/gemi-react-best-practices/rules/i18n-define-dictionary-inline.md

@@ -0,0 +1,58 @@
+---
+title: The defineDictionary Literal Must Be Inline
+impact: MEDIUM
+impactDescription: passes tests, fails the build
+tags: i18n, build, vite, gotcha
+---
+
+## The defineDictionary Literal Must Be Inline
+
+New i18n work uses `defineDictionary` (gemi 0.54): a `<Component>.i18n.ts` beside the
+component, read with `useDictionary(theDict)`. gemi's Vite plugin **rewrites the call
+at build time** and needs the object to be statically analyzable.
+
+A helper call, variable, spread or template literal **fails the BUILD** — while
+still resolving fine under test. That asymmetry is the trap: the refactor looks
+green locally and breaks CI at the build step.
+
+**Incorrect (factored behind a helper — resolves in tests, fails the build):**
+
+```ts
+const copy = (en: string, tr: string) => ({ "en-US": en, "tr-TR": tr });
+
+export const dict = defineDictionary({
+  title: copy("Products", "Ürünler"),
+  ...sharedKeys,
+});
+```
+
+**Correct (inline literal, `en-US` first in every key):**
+
+```ts
+export const dict = defineDictionary({
+  title: {
+    "en-US": "Products",
+    "tr-TR": "Ürünler",
+    "de-DE": "Produkte",
+    // …
+  },
+});
+```
+
+Rules that come with it:
+
+- **Write `en-US` first in every key.** The first locale is the source language and
+  the fallback when another locale is missing a key; if keys disagree on ordering,
+  the build stops.
+- **No name string, no `app/i18n/index.ts` entry, no prefetch map, no `gemi.d.ts`
+  declaration.** Keys and `{{param}}` types are inferred from the literal.
+- **Name a key after the copy it holds**, not its call site — `new`, not `button`.
+  A key named for where it is used drifts the moment the copy moves.
+- Untransformed it holds every locale and resolves **synchronously**, so a component
+  test asserts the real copy with nothing seeded. Assert `en-US` only.
+- **A missing translation degrades silently** (it falls back to the source locale)
+  rather than failing — completeness across locales wants one i18n-level check, not
+  an assertion in every component test.
+
+The legacy `Dictionary.create` system is still the bulk of the app and both coexist.
+Migrate per component when you touch it; there is no sweep planned.

package/skills/gemi-react-best-practices/rules/orm-analytics-connection.md

@@ -0,0 +1,53 @@
+---
+title: Heavy Aggregations Run on a Separate Connection
+impact: HIGH
+impactDescription: keeps the request-path pool available
+tags: orm, connections, pooling, admin, cron
+---
+
+## Heavy Aggregations Run on a Separate Connection
+
+Every connection your app declares counts against the database server's connection
+budget, and a long admin scan or cron aggregation on the same pool that serves
+requests starves the every-request auth path. This is a common production incident
+shape, not a hypothetical.
+
+If your app declares a second connection for that work — the usual name is
+`analytics` — route heavy reads to it. **Selection is per query, never per model:**
+
+```ts
+await AuditLog.on("analytics").count({ where });
+await DB.connection("analytics").query(sql`…`);
+```
+
+**Incorrect (a full-table admin scan competing with request traffic):**
+
+```ts
+const rows = await AuditLog.findMany({
+  where: { createdAt: { gte: monthStart } },
+});
+```
+
+**Correct:**
+
+```ts
+const rows = await AuditLog.on("analytics").findMany({
+  where: { createdAt: { gte: monthStart } },
+});
+```
+
+`Model.on(name)` and `DB.connection(name)` both take a connection your app has
+declared in its database config. There is no framework-provided `analytics` pool —
+check what your app actually declares before reaching for a name.
+
+**Bound a batch's concurrency to the pool that serves it.** An unbounded
+`Promise.all` over a three-connection pool is a queue, not parallelism, and it is a
+queue that blocks anything else needing that pool. Cap the in-flight count at the
+pool size rather than fanning out over the whole collection.
+
+**Do not hardcode a pool size at a call site.** Read it from the same config that
+declares the pool, so shrinking the pool cannot leave a batch fanning out wider than
+it can serve.
+
+Remember `orm-transaction-sequential`: a transaction cannot span connections, so
+work inside `Model.transaction` stays on the connection that opened it.