gemi 0.59.0 → 0.60.0

package/skills/gemi-react-best-practices/rules/payload-prefetch-mirrors-usequery.md

@@ -0,0 +1,52 @@
+---
+title: A Prefetch Must Mirror Its useQuery Exactly
+impact: CRITICAL
+impactDescription: one saved round-trip per read, or zero
+tags: payload, prefetch, cache-key, ssr
+---
+
+## A Prefetch Must Mirror Its useQuery Exactly
+
+`Query.prefetch` primes the client cache, and the cache is keyed on **path + params
++ search**. A prefetch that differs in any of the three lands in a different cache
+slot: the SSR payload carries the bytes AND the client still fetches. That is worse
+than not prefetching at all, and nothing fails — the page just quietly costs a
+round-trip.
+
+This makes prefetch lists a maintenance obligation. Adding a `useQuery` to a surface
+without adding the matching prefetch silently costs a round-trip; leaving a prefetch
+pointed at a path the surface no longer reads silently costs a query.
+
+**Incorrect (search differs, so it primes a slot nothing reads):**
+
+```tsx
+// Controller
+Query.prefetch("/app/:orgId/lists-v2", { params: { orgId } });
+
+// View — the cache key includes `search`, so this misses the primed entry
+const { data } = useQuery("/app/:orgId/lists-v2", {
+  params: { orgId },
+  search: { limit: "100" },
+});
+```
+
+**Correct (path, params and search all match):**
+
+```tsx
+// Controller
+Query.prefetch("/app/:orgId/lists-v2", {
+  params: { orgId },
+  search: { limit: "100" },
+});
+
+// View
+const { data } = useQuery("/app/:orgId/lists-v2", {
+  params: { orgId },
+  search: { limit: "100" },
+});
+```
+
+In dev, gemi logs a hint for a query that starts late, with its delay and payload
+size — that hint is how you find a prefetch that stopped matching.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/query-debounce-search-variant.md

@@ -0,0 +1,52 @@
+---
+title: Debounce a Value Before It Becomes a Query Variant
+impact: MEDIUM-HIGH
+impactDescription: one request per pause instead of per keystroke
+tags: query, debounce, search, effects
+---
+
+## Debounce a Value Before It Becomes a Query Variant
+
+Every distinct `search` object is a distinct cache key, so feeding raw input state
+straight into `useQuery` fires a request per keystroke and fills the cache with
+entries nobody will read again.
+
+Debounce with a debounce hook — **not** a hand-rolled
+`useEffect` + `setTimeout`. The house rule in most gemi apps is that data flow does
+not go
+through effects: derive in `useMemo`, reset in the change handler, debounce with the
+hook (`rerender-no-effect-data-flow`).
+
+**Incorrect (a request per keystroke, and a hand-rolled timer to boot):**
+
+```tsx
+const [query, setQuery] = useState("");
+const [debounced, setDebounced] = useState("");
+
+useEffect(() => {
+  const id = setTimeout(() => setDebounced(query), 250);
+  return () => clearTimeout(id);
+}, [query]);
+```
+
+**Correct:**
+
+```tsx
+// A debounce hook — your own, or one from a library.
+import { useDebounceValue } from "@/app/hooks/useDebounceValue";
+
+const [query, setQuery] = useState("");
+const [debouncedQuery] = useDebounceValue(query.trim(), 250);
+
+const { data = [], loading } = useQuery(
+  "/app/:orgId/products/search",
+  { params: { orgId }, search: { q: debouncedQuery || null, limit } },
+  { suspense: false },
+);
+```
+
+Two details worth copying from the call sites above:
+
+- **`.trim()` before debouncing**, so trailing whitespace is not its own variant.
+- **`|| null` rather than `""`** — pick one empty representation and use it
+  everywhere, or the empty-search variant splits in two.

package/skills/gemi-react-best-practices/rules/query-keep-previous-data.md

@@ -0,0 +1,40 @@
+---
+title: Keep the Previous Page Rendered While the Next Variant Loads
+impact: MEDIUM-HIGH
+impactDescription: removes layout collapse on every filter keystroke
+tags: query, pagination, ux, keepPreviousData
+---
+
+## Keep the Previous Page Rendered While the Next Variant Loads
+
+Changing `params` or `search` changes the cache key, so the query has no data for
+the new variant. `keepPreviousData` (default `true`) holds the old variant's data on
+screen until the new one arrives, which is what keeps a paginated table from
+collapsing to a skeleton on every page click.
+
+Because it is the default, the rule is mostly about **not breaking it**: setting
+`keepPreviousData: false`, or remounting the component on variant change (a changing
+`key`), throws the behaviour away.
+
+**Incorrect (a changing key remounts, discarding the previous data):**
+
+```tsx
+<ProductTable key={page} page={page} />
+```
+
+**Correct (same instance, variant changes, previous page stays visible):**
+
+```tsx
+const { data, loading } = useQuery(
+  "/app/:orgId/products",
+  { params: { orgId }, search: { page: String(page), limit: "25" } },
+  { keepPreviousData: true },
+);
+
+// `loading` is true while the next page is in flight; `data` is still the
+// previous page. Dim the table rather than replacing it.
+<Table className={loading ? "opacity-60" : undefined} rows={data} />
+```
+
+Pair it with `query-debounce-search-variant`: without a debounce, every keystroke
+is a new variant and `keepPreviousData` is doing far more work than it should.

package/skills/gemi-react-best-practices/rules/query-lazy-vs-mount-gate.md

@@ -0,0 +1,54 @@
+---
+title: A Lazy Query Does Not Refetch When Its Variant Changes
+impact: HIGH
+impactDescription: prevents silently dead search and pagination
+tags: query, lazy, correctness, mounting
+---
+
+## A Lazy Query Does Not Refetch When Its Variant Changes
+
+`{ lazy: true }` defers a query until `trigger()` or `refetch()` is called. It is the
+right tool for a read that fires on an explicit user action with **fixed** inputs.
+
+It is the wrong tool for a read whose key changes — search text, page size, filters.
+A lazy query does not refetch when its variant changes, so search and "load more"
+keep rendering the first triggered result and appear to be broken. Nothing errors.
+
+When a read is both expensive and variant-keyed, **gate it by mounting instead**.
+Mounting is a real gate: an unmounted component runs no query, and remounting
+re-establishes the subscription with the current variant.
+
+**Incorrect (lazy on a variant-keyed read — search silently stops working):**
+
+```tsx
+const { data, trigger } = useQuery(
+  "/app/:orgId/products/search",
+  { params: { orgId }, search: { q: debouncedQuery, limit } },
+  { lazy: true },
+);
+
+useEffect(() => { trigger(); }, [debouncedQuery, limit]); // fights the design
+```
+
+**Correct (move the read into the subtree that only mounts when opened):**
+
+```tsx
+// Radix unmounts PopoverContent while the popover is closed, so this query
+// does not exist until the user opens the picker — and it re-keys normally
+// on `debouncedQuery` and `limit` once it does.
+<PopoverContent>
+  <CatalogSearchPanel orgId={orgId} />
+</PopoverContent>
+```
+
+**Also correct — lazy for a fixed-input, action-triggered read:**
+
+```tsx
+const { data, trigger, loading } = useQuery(
+  "/app/:orgId/export/preview",
+  { params: { orgId } },
+  { lazy: true },
+);
+
+<Button onClick={() => trigger()}>Preview export</Button>
+```

package/skills/gemi-react-best-practices/rules/query-mutate-over-refetch.md

@@ -0,0 +1,55 @@
+---
+title: Write the Cache With mutate Instead of Refetching
+impact: MEDIUM-HIGH
+impactDescription: removes a round-trip from every write
+tags: query, mutations, cache, optimistic
+---
+
+## Write the Cache With mutate Instead of Refetching
+
+After a successful mutation the UI needs to reflect the new state. Refetching the
+list costs a round-trip the client can often skip: `mutate` writes the cache
+immediately, then reconciles with the server on its own.
+
+- **`mutate(fn)`** from a `useQuery` — updates that component's variant.
+- **`useMutate()`** — updates **any** variant by path, from outside the component
+  that owns it. This is the one to reach for after a mutation, since the writer is
+  rarely the reader.
+
+The callback must return the complete next value — merge existing data yourself.
+After the optimistic write, gemi refetches to reconcile, so a wrong guess
+self-corrects rather than sticking.
+
+**Incorrect (blank, then a full round-trip, before the row disappears):**
+
+```tsx
+const { trigger } = useDelete("/app/:orgId/products/:id");
+
+await trigger();
+await refetch(); // user waits for the list again
+```
+
+**Correct (row disappears immediately; reconciliation happens behind it):**
+
+```tsx
+import { useMutate, useDelete } from "gemi/client";
+
+const mutate = useMutate();
+const { trigger } = useDelete("/app/:orgId/products/:id");
+
+await trigger();
+mutate(
+  { path: "/app/:orgId/products", params: { orgId } },
+  (products) => products.filter((p) => p.publicId !== id),
+);
+```
+
+**Refetch, don't guess, when the server derives the value.** If a write changes
+counts, totals, credit balances or anything else computed server-side, call
+`mutate()` with no callback — it refetches without an optimistic write, which is
+still cheaper than remounting the surface.
+
+Note the target must name the same variant as the reader (`query-share-cache-key`):
+`mutate({ path, params, search })` misses if the search object differs.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/query-no-hand-rolled-fetch.md

@@ -0,0 +1,60 @@
+---
+title: Read Server Data With useQuery, Never a Raw fetch
+impact: CRITICAL
+impactDescription: dedup, caching, SSR priming, types — all lost otherwise
+tags: query, data-fetching, types
+---
+
+## Read Server Data With useQuery, Never a Raw fetch
+
+A hand-rolled `fetch` in an effect opts out of everything gemi's network layer
+provides: SSR priming from `Query.prefetch`, cross-component deduplication, the
+cache, revalidation, suspense integration, and end-to-end types generated into
+`.gemi/gemi.d.ts`. It also reintroduces the classic effect bugs — races on fast
+navigation, no cancellation, a setState after unmount.
+
+**Incorrect (no dedup, no cache, no priming, no types):**
+
+```tsx
+function Products() {
+  const [products, setProducts] = useState([]);
+  useEffect(() => {
+    fetch(`/api/app/${orgId}/products`)
+      .then((r) => r.json())
+      .then(setProducts);
+  }, [orgId]);
+}
+```
+
+**Correct:**
+
+```tsx
+import { useQuery } from "gemi/client";
+
+function Products() {
+  const { data: products } = useQuery("/app/:orgId/products", {
+    params: { orgId },
+  });
+}
+```
+
+**Writes go through the mutation hooks or `<Form>`, for the same reason:**
+
+```tsx
+import { usePost } from "gemi/client";
+
+const { trigger, loading, error } = usePost("/app/:orgId/products");
+await trigger({ name });
+```
+
+Mutation errors arrive as tagged objects — `validation_error` (with per-field
+`messages`), `form_error`, `server_error`, `not_authorized`,
+`insufficient_permissions` — so a controller should `throw new ValidationError(...)`
+rather than inventing a per-endpoint error shape.
+
+**The one documented exception is file upload.** `useUpload` is XHR-based (it needs
+progress events). That is also why it cannot be intercepted by MSW under happy-dom:
+a client file post that needs to be unit-testable should use `usePost` with
+`FormData` instead.
+
+Reference: <https://nstfkc.github.io/gemi/data-fetching.md>

package/skills/gemi-react-best-practices/rules/query-revalidate-on-focus.md

@@ -0,0 +1,44 @@
+---
+title: revalidateOnFocus Is Opt-In, For Cross-Tab-Mutable Data Only
+impact: MEDIUM
+impactDescription: freshness without a request storm
+tags: query, revalidation, focus, staleness
+---
+
+## revalidateOnFocus Is Opt-In, For Cross-Tab-Mutable Data Only
+
+`revalidateOnFocus` defaults to `false` in gemi. Turn it on only for a value that can
+change **without this tab doing anything** — a balance a webhook can credit, a status
+another tab can flip, a quota a background job can consume. For everything else, the
+5s `staleTime` and the mutation-driven cache writes are enough.
+
+When you do turn it on, two defaults keep it from becoming a request storm:
+`staleTime` (5000ms) suppresses revalidation for data that is still fresh, and
+`focusThrottleInterval` (5000ms) sets a floor between focus-triggered revalidations.
+A tab return that fires both `focus` and `visibilitychange` collapses to one request.
+
+**Incorrect (a long-lived widget goes stale for the whole session):**
+
+```tsx
+// Mounted in the nav for the entire session. A purchase made in another tab,
+// or a renewal landing via webhook, leaves this balance wrong until reload.
+const { data: credits } = useQuery("/app/:orgId/ai-credits", { params: { orgId } });
+```
+
+**Correct:**
+
+```tsx
+const { data: credits, loading } = useQuery(
+  "/app/:orgId/ai-credits",
+  { params: { orgId } },
+  { revalidateOnFocus: true },
+);
+```
+
+**Do not reach for `refreshInterval` where focus revalidation would do.** Polling
+runs while nobody is looking; focus revalidation runs when someone starts looking.
+Reserve `refreshInterval` for genuinely live data (a job that is running now), and
+stop polling when the surface unmounts or the work completes.
+
+Remember `query-share-cache-key`: turning this on for a shared variant turns it on
+for every reader of that variant.

package/skills/gemi-react-best-practices/rules/query-share-cache-key.md

@@ -0,0 +1,51 @@
+---
+title: Identical Query Variants Dedupe For Free
+impact: HIGH
+impactDescription: N components, 1 request
+tags: query, deduplication, cache
+---
+
+## Identical Query Variants Dedupe For Free
+
+gemi's query cache is keyed on path + params + search. Two components reading the
+same variant share one request, one cache entry, and one revalidation — there is no
+caching library to add and no context to thread. Deduplication is the default, not
+something you opt into.
+
+The corollary is the useful part: **do not lift a query into a parent and prop-drill
+it just to avoid a "duplicate" request.** There is no duplicate request. Reading it
+where it is used keeps the component self-contained, and a mutation that refreshes
+the variant refreshes every reader at once.
+
+**Incorrect (prop-drilling to dedupe something already deduped):**
+
+```tsx
+function Settings() {
+  const { data: credits } = useQuery("/app/:orgId/ai-credits", { params });
+  return (
+    <>
+      <CreditsPanel credits={credits} />
+      <Composer credits={credits} />
+      <NavBadge credits={credits} />
+    </>
+  );
+}
+```
+
+**Correct (each reads it; one request serves all three):**
+
+```tsx
+function CreditsPanel() {
+  const { data: credits } = useQuery("/app/:orgId/ai-credits", { params });
+  // …
+}
+```
+
+Two things follow from the key being exact:
+
+- **A cosmetic difference in `search` splits the cache.** `{ limit: 25 }` and
+  `{ limit: "25" }` are different variants; so are `{ q: "" }` and `{ q: null }`.
+  Normalize at one place — usually a shared constant — so readers agree.
+- **Sharing a variant means sharing its config's effects.** A `revalidateOnFocus`
+  set by one reader refreshes the value every reader sees. That is usually what you
+  want; know that it is happening.

package/skills/gemi-react-best-practices/rules/query-suspense-default.md

@@ -0,0 +1,52 @@
+---
+title: suspense Is On By Default and Throws to the Nearest Boundary
+impact: CRITICAL
+impactDescription: prevents whole-surface blanking
+tags: query, suspense, loading, ux
+---
+
+## suspense Is On By Default and Throws to the Nearest Boundary
+
+`useQuery` defaults to `suspense: true`. Two consequences that surprise people:
+
+1. **A fresh fetch suspends the component**, which blanks everything up to the
+   nearest boundary — not just the widget doing the read. A query added deep inside
+   an interactive surface can blank the whole route behind it.
+2. **A failed fetch throws**, so `loading` and `error` are not what that path
+   returns. Under suspense, `data` is non-nullable and the loading/error states are
+   the boundary's job.
+
+Keep the default for a route's primary read — that is what the route's `Loading` /
+`Error` exports are for (`render-loading-error-exports`). Pass `{ suspense: false }`
+for a secondary read that should render its own inline loading state in place.
+
+**Incorrect (opening a picker blanks the chat behind it):**
+
+```tsx
+// Inside a popover nested in the composer. The nearest boundary is the ROUTE's
+// <Suspense fallback={null}>, so this suspends the entire surface.
+const { data: products } = useQuery("/app/:orgId/products/search", {
+  params: { orgId },
+  search: { q: debouncedQuery },
+});
+```
+
+**Correct (the panel owns its loading state, nothing above it blanks):**
+
+```tsx
+const { data: products = [], loading } = useQuery(
+  "/app/:orgId/products/search",
+  { params: { orgId }, search: { q: debouncedQuery || null, limit } },
+  { suspense: false },
+);
+
+if (loading) return <PanelSkeleton />;
+```
+
+Note the third-argument position: options like `suspense`, `keepPreviousData`,
+`staleTime` and `refreshInterval` are the **third** argument; `params` and `search`
+are the second.
+
+**When writing tests for this:** a non-lazy query suspends while its first page is
+in flight and throws when it fails, so seed `<Page>`'s `fallback` and
+`errorFallback` and assert those — `loading`/`error` are not what that path returns.

package/skills/gemi-react-best-practices/rules/routing-cache-policy-constants.md

@@ -0,0 +1,53 @@
+---
+title: Name Cache Policies Once, Reuse the Constant
+impact: MEDIUM-HIGH
+impactDescription: prevents a private page shipping a public cache header
+tags: routing, caching, middleware, correctness
+---
+
+## Name Cache Policies Once, Reuse the Constant
+
+`cache:` compiles to a `Cache-Control` header, so the difference between
+`cache:public` and `cache:private,0,no-store` is the difference between a CDN
+serving one customer's page to another and not. Spelling the policy inline at each
+router invites a typo that is invisible in review and catastrophic in production.
+
+This app hoists the policies it uses to named constants and reuses them.
+
+**Incorrect (four routers, four hand-typed policies, one of them wrong):**
+
+```ts
+class CustomerRouter extends ViewRouter {
+  middlewares = ["cache:private,0,no-store", "auth"];
+}
+class CustomerAuthRouter extends ViewRouter {
+  middlewares = ["cache:public"]; // signed-out, but now CDN-cacheable per-visitor
+}
+```
+
+**Correct (one named policy per audience):**
+
+```ts
+const ANONYMOUS_VIEW_CACHE = "cache:private,0,no-store";
+const LANDING_VIEW_CACHE = "cache:private,12840,must-revalidate";
+
+class CustomerAuthRouter extends ViewRouter {
+  middlewares = [ANONYMOUS_VIEW_CACHE];
+}
+```
+
+What the DSL expands to:
+
+| DSL | `Cache-Control` |
+|---|---|
+| `cache` / `cache:public` | `public, max-age=864000, stale-while-revalidate=300, stale-if-error=600` |
+| `cache:private` | `private, max-age=0, stale-while-revalidate=300, stale-if-error=600` |
+| `cache:private,0,no-store` | `private, max-age=0, no-store` |
+
+The arguments are `scope`, `maxAge`, then directives, and the middleware only sets
+headers on **GET** responses.
+
+**Default to `no-store` for anything behind `auth`.** A per-user page that is
+cacheable at all is a decision worth making explicitly, with a constant that says so.
+
+Reference: `app/http/routes/view.ts`

package/skills/gemi-react-best-practices/rules/routing-middleware-dsl.md

@@ -0,0 +1,60 @@
+---
+title: Middleware Is a String DSL, Applied at Router or Route Level
+impact: HIGH
+impactDescription: the app's actual auth boundary
+tags: routing, middleware, auth, security
+---
+
+## Middleware Is a String DSL, Applied at Router or Route Level
+
+Middleware attaches as strings — `"auth"`, `"admin"`, `"role:owner"`,
+`"rate-limit:10,30"`, `"cache:private,0,no-store"` — resolved through the aliases in
+`app/config/middleware.ts`. Everything after the colon is a comma-separated argument
+list passed to the middleware's `run(...)`.
+
+Declare it **router-level** (`middlewares = [...]`, inherited by nested routers) or
+**per-route** (`.middleware([...])`, which stacks on top).
+
+**Incorrect (hand-rolling an auth check that middleware already expresses):**
+
+```ts
+export class ReportController extends Controller {
+  async index(req: HttpRequest) {
+    const user = await Auth.user();
+    if (!user || Number(user.globalRole) >= 10) {
+      throw new InsufficientPermissionsError();
+    }
+    // …
+  }
+}
+```
+
+**Correct (the boundary is declared where the route is):**
+
+```ts
+class AdminRouter extends ApiRouter {
+  middlewares = ["cache:private,0,no-store", "auth", "admin"];
+  routes = {
+    "/reports": this.get(ReportController, "index"),
+  };
+}
+```
+
+**Cancel an inherited middleware with `-name`.** The framework keeps a de-duplicated
+map keyed by alias, so a sign-in page inside an authenticated router opts out
+explicitly rather than being moved:
+
+```ts
+class AdminAuthViewRouter extends ViewRouter {
+  middlewares = [ANONYMOUS_VIEW_CACHE, "-auth", "-admin"];
+  routes = { "/sign-in": this.view("auth/SignIn") };
+}
+```
+
+**Rate-limit buckets are per client IP *and* route path**, so `/api/search` and
+`/api/upload` hold separate budgets — a shared limit needs a configured `key`
+function, and a budget outside a route uses the `RateLimiter` facade
+(`RateLimiter.consume(key, { limit, window })`).
+
+Reference: `app/config/middleware.ts`, `app/http/routes/view.ts`
+<https://nstfkc.github.io/gemi/middleware.md>

package/skills/gemi-react-best-practices/rules/routing-resource-routes.md

@@ -0,0 +1,59 @@
+---
+title: Use resource() for Standard REST, With Per-Method Middleware
+impact: MEDIUM
+impactDescription: five routes, one line, no drift
+tags: routing, rest, controllers, middleware
+---
+
+## Use resource() for Standard REST, With Per-Method Middleware
+
+`this.resource(Controller)` binds a `ResourceController`'s five methods to the
+conventional REST shape in one line. The route key **must end with the item's id
+parameter**; gemi splits it into the collection path and the item path itself.
+
+| Method | Verb | Path |
+|---|---|---|
+| `list` | GET | collection |
+| `store` | POST | collection |
+| `show` | GET | item |
+| `update` | PUT | item |
+| `delete` | DELETE | item |
+
+**Incorrect (five hand-wired routes that will drift apart):**
+
+```ts
+routes = {
+  "/products": this.get(ProductsController, "list"),
+  "/products/new": this.post(ProductsController, "store"),
+  "/products/:productId": this.get(ProductsController, "show"),
+  "/product/:productId": this.put(ProductsController, "update"),
+  "/products/:productId/delete": this.delete(ProductsController, "delete"),
+};
+```
+
+**Correct:**
+
+```ts
+routes = {
+  "/:orgId/products/:productId": this.resource(ProductsController).middleware({
+    store: ["auth"],
+    update: ["auth"],
+    delete: ["auth"],
+  }),
+};
+```
+
+**`.middleware({})` takes a per-method map**, which is how a resource exposes public
+reads and authenticated writes without splitting into two routers.
+
+**Reach for the explicit verbs when the shape is not REST.** A path that needs two
+verbs bound to non-standard methods takes an object of lowercase method keys:
+
+```ts
+"/conversations/:id": {
+  get: this.get(ConversationController, "restoreV2"),
+  delete: this.delete(ConversationController, "deleteV2"),
+},
+```
+
+Reference: `app/http/routes/api.ts`; <https://nstfkc.github.io/gemi/routing.md>