code-ai-installer 2.4.1 → 3.0.0

package/locales/en/.agents/skills/tanstack-beast-practices/SKILL.md

@@ -1,476 +0,0 @@
----
-name: tanstack-beast-practices
-description: TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked "how to do X correctly with TanStack".
----
-
-# Skill: TanStack Beast Practices
-
-Copy-paste patterns for predictable work with data, tables, and virtualization.
-
-> [!IMPORTANT]
-> **MCP priority:** If the `tanstack-docs` MCP server is available, **always use its tools first** (`tanstack_doc`, `tanstack_search_docs`, `listTanStackAddOns`, `getAddOnDetails`, `createTanStackApplication`) — they provide up-to-date documentation directly from official TanStack sources. Use the patterns in this skill as a fallback or as additional architectural context (fetcher/adapter/hook, queryKey factory, optimistic updates, virtualization) when the MCP is unavailable or does not contain the required information.
-
-**Sections:**
-1. [Query: fetcher/adapter architecture](#1-query-architecture)
-2. [Query: caching and staleTime](#2-query-cache)
-3. [Query: mutations and invalidation](#3-query-mutations)
-4. [Query: pagination and infinite scroll](#4-query-pagination)
-5. [Table: server pagination/sorting/filters](#5-table)
-6. [Virtual: large lists](#6-virtual)
-
----
-
-## 1. Query: Architecture
-
-### ✅ DO: separate fetcher → adapter → hook layers
-```ts
-// ─── 1. fetcher: pure HTTP, no business logic ───────────────────
-// src/api/users.api.ts
-export async function fetchUsersApi(params: UsersQueryParams): Promise<UsersApiResponse> {
-  const qs = new URLSearchParams(params as any).toString();
-  const res = await fetch(`/api/users?${qs}`);
-  if (!res.ok) throw new Error(`HTTP ${res.status}`);
-  return res.json();
-}
-
-// ─── 2. adapter: mapping API model → domain model ────────────────────
-// src/api/users.adapter.ts
-export function adaptUser(raw: UserApiModel): User {
-  return {
-    id:        raw.user_id,          // snake_case → camelCase
-    fullName:  `${raw.first_name} ${raw.last_name}`,
-    createdAt: new Date(raw.created_at),
-  };
-}
-
-// ─── 3. hook: queryKey + queryFn + transform ──────────────────────
-// src/hooks/useUsers.ts
-export function useUsers(params: UsersQueryParams) {
-  return useQuery({
-    queryKey: ["users", params],          // the key includes parameters
-    queryFn:  () => fetchUsersApi(params),
-    select:   data => data.items.map(adaptUser), // transform is here, not in the component
-  });
-}
-```
-
-### ✅ DO: queryKey factory — single source of truth for keys
-```ts
-// src/api/users.keys.ts
-export const userKeys = {
-  all:     ()          => ["users"]                    as const,
-  lists:   ()          => [...userKeys.all(), "list"]  as const,
-  list:    (p: Params) => [...userKeys.lists(), p]     as const,
-  details: ()          => [...userKeys.all(), "detail"] as const,
-  detail:  (id: string)=> [...userKeys.details(), id]  as const,
-};
-
-// Usage:
-useQuery({ queryKey: userKeys.list(params), queryFn: ... });
-
-// Invalidating all lists at once:
-qc.invalidateQueries({ queryKey: userKeys.lists() });
-
-// ❌ Bad: magic strings matched across components
-useQuery({ queryKey: ["users", "list", page], ... }); // duplication and typos
-```
-
----
-
-## 2. Query: Cache
-
-### ✅ DO: consciously set staleTime and gcTime
-```ts
-// src/lib/queryClient.ts
-export const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 60 * 1000,   // data is fresh for 1 minute — no extra fetches on navigation
-      gcTime:    5 * 60 * 1000, // garbage is collected after 5 minutes
-      retry: 2,
-      refetchOnWindowFocus: false, // disable if data is not real-time
-    },
-  },
-});
-
-// ✅ Override for a specific hook
-export function useUserProfile(id: string) {
-  return useQuery({
-    queryKey: userKeys.detail(id),
-    queryFn:  () => fetchUserProfile(id),
-    staleTime: 5 * 60 * 1000, // profile changes rarely — cache for 5 minutes
-  });
-}
-
-// ✅ Real-time data — no cache
-export function useLiveStats() {
-  return useQuery({
-    queryKey: ["live-stats"],
-    queryFn:  fetchLiveStats,
-    staleTime: 0,               // always stale
-    refetchInterval: 5000,      // polling every 5 seconds
-  });
-}
-```
-
-### ✅ DO: prefetch for preloading on hover
-```ts
-function UserLink({ userId }: { userId: string }) {
-  const qc = useQueryClient();
-
-  return (
-    <a
-      href={`/users/${userId}`}
-      onMouseEnter={() => {
-        // ✅ Preloading data before the click — the transition seems instantaneous
-        qc.prefetchQuery({
-          queryKey: userKeys.detail(userId),
-          queryFn:  () => fetchUserProfile(userId),
-          staleTime: 60 * 1000,
-        });
-      }}
-    >
-      View Profile
-    </a>
-  );
-}
-```
-
----
-
-## 3. Query: Mutations and Invalidation
-
-### ✅ DO: optimistic update + rollback
-```ts
-export function useUpdateUser() {
-  const qc = useQueryClient();
-
-  return useMutation({
-    mutationFn: (data: UpdateUserDto) =>
-      fetch(`/api/users/${data.id}`, {
-        method: "PATCH",
-        body: JSON.stringify(data),
-        headers: { "Content-Type": "application/json" },
-      }).then(r => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); }),
-
-    // ✅ Optimistically update the cache BEFORE the server response
-    onMutate: async (data) => {
-      await qc.cancelQueries({ queryKey: userKeys.detail(data.id) });
-
-      const previous = qc.getQueryData<User>(userKeys.detail(data.id));
-      qc.setQueryData(userKeys.detail(data.id), (old: User) => ({ ...old, ...data }));
-
-      return { previous }; // context for rollback
-    },
-
-    // ✅ Rollback on error
-    onError: (_err, data, ctx) => {
-      if (ctx?.previous) {
-        qc.setQueryData(userKeys.detail(data.id), ctx.previous);
-      }
-    },
-
-    // ✅ Synchronization with the server in any case
-    onSettled: (_data, _err, data) => {
-      qc.invalidateQueries({ queryKey: userKeys.detail(data.id) });
-    },
-  });
-}
-```
-
-### ✅ DO: invalidate multiple keys after mutation
-```ts
-export function useDeleteUser() {
-  const qc = useQueryClient();
-
-  return useMutation({
-    mutationFn: (id: string) =>
-      fetch(`/api/users/${id}`, { method: "DELETE" }).then(r => {
-        if (!r.ok) throw new Error(`HTTP ${r.status}`);
-      }),
-
-    onSuccess: (_data, id) => {
-      // ✅ Invalidating the list AND the detail page
-      qc.invalidateQueries({ queryKey: userKeys.lists() });
-      qc.removeQueries({ queryKey: userKeys.detail(id) }); // completely removing from cache
-    },
-  });
-}
-```
-
----
-
-## 4. Query: Pagination and Infinite Scroll
-
-### ✅ DO: server-side pagination via keepPreviousData
-```ts
-export function useUsersList(page: number, pageSize = 20) {
-  return useQuery({
-    queryKey: userKeys.list({ page, pageSize }),
-    queryFn:  () => fetchUsersApi({ page, pageSize }),
-    placeholderData: keepPreviousData, // ✅ no "flickering" when changing the page
-    staleTime: 30 * 1000,
-  });
-}
-
-// Usage in the component
-function UsersTable() {
-  const [page, setPage] = useState(1);
-  const { data, isFetching } = useUsersList(page);
-
-  return (
-    <>
-      {isFetching && <Spinner size="sm" />} {/* indicator without blocking the UI */}
-      <Table rows={data?.items ?? []} />
-      <Pagination
-        current={page}
-        total={data?.meta.total ?? 0}
-        onChange={setPage}
-      />
-    </>
-  );
-}
-```
-
-### ✅ DO: infinite scroll via useInfiniteQuery
-```ts
-export function useInfiniteUsers(search: string) {
-  return useInfiniteQuery({
-    queryKey:     userKeys.list({ search }),
-    queryFn:      ({ pageParam }) => fetchUsersApi({ search, cursor: pageParam }),
-    initialPageParam: undefined as string | undefined,
-    getNextPageParam: last => last.meta.nextCursor ?? undefined,
-    staleTime: 60 * 1000,
-  });
-}
-
-function InfiniteUsersList() {
-  const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteUsers("");
-  const ref = useRef<HTMLDivElement>(null);
-
-  // ✅ IntersectionObserver — loading the next page when reaching the end
-  useEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    const obs = new IntersectionObserver(
-      ([entry]) => { if (entry.isIntersecting && hasNextPage) fetchNextPage(); },
-      { threshold: 0.1 }
-    );
-    obs.observe(el);
-    return () => obs.disconnect();
-  }, [fetchNextPage, hasNextPage]);
-
-  const users = data?.pages.flatMap(p => p.items) ?? [];
-
-  return (
-    <ul>
-      {users.map(u => <li key={u.id}>{u.fullName}</li>)}
-      <div ref={ref}>
-        {isFetchingNextPage && <Spinner />}
-      </div>
-    </ul>
-  );
-}
-```
-
----
-
-## 5. Table
-
-### ✅ DO: server pagination + sorting + filters
-```ts
-// ─── State: URL as the source of truth for filters/pagination ─────────
-function useTableState() {
-  const [sorting,    setSorting]    = useState<SortingState>([]);
-  const [pagination, setPagination] = useState<PaginationState>({ pageIndex: 0, pageSize: 20 });
-  const [columnFilters, setColumnFilters] = useState<ColumnFiltersState>([]);
-
-  return { sorting, setSorting, pagination, setPagination, columnFilters, setColumnFilters };
-}
-
-// ─── Query parameters from the table state ────────────────────────
-function tableStateToQueryParams(
-  sorting: SortingState,
-  pagination: PaginationState,
-  columnFilters: ColumnFiltersState
-): UsersQueryParams {
-  return {
-    page:     pagination.pageIndex + 1,
-    pageSize: pagination.pageSize,
-    sortBy:   sorting[0]?.id,
-    sortDir:  sorting[0]?.desc ? "desc" : "asc",
-    ...Object.fromEntries(columnFilters.map(f => [f.id, f.value])),
-  };
-}
-
-// ─── Table ───────────────────────────────────────────────────────
-const columns: ColumnDef<User>[] = [
-  { accessorKey: "fullName", header: "Name", enableSorting: true },
-  { accessorKey: "email",    header: "Email", enableColumnFilter: true },
-  {
-    accessorKey: "createdAt",
-    header: "Created",
-    cell: ({ getValue }) => getValue<Date>().toLocaleDateString("ru-RU"),
-  },
-];
-
-function UsersDataTable() {
-  const ts = useTableState();
-  const params = tableStateToQueryParams(ts.sorting, ts.pagination, ts.columnFilters);
-  const { data, isFetching } = useUsersList(params);
-
-  const table = useReactTable({
-    data:        data?.items ?? [],
-    columns,
-    rowCount:    data?.meta.total ?? 0,
-    state:       { sorting: ts.sorting, pagination: ts.pagination, columnFilters: ts.columnFilters },
-    manualSorting:    true, // ✅ server sorting
-    manualPagination: true, // ✅ server pagination
-    manualFiltering:  true, // ✅ server filtration
-    onSortingChange:       ts.setSorting,
-    onPaginationChange:    ts.setPagination,
-    onColumnFiltersChange: ts.setColumnFilters,
-    getCoreRowModel:       getCoreRowModel(),
-  });
-
-  return (
-    <div>
-      {isFetching && <div className="loading-bar" />}
-      <table>
-        <thead>
-          {table.getHeaderGroups().map(hg => (
-            <tr key={hg.id}>
-              {hg.headers.map(h => (
-                <th key={h.id} onClick={h.column.getToggleSortingHandler()}>
-                  {flexRender(h.column.columnDef.header, h.getContext())}
-                  {h.column.getIsSorted() === "asc" ? " ↑" : h.column.getIsSorted() === "desc" ? " ↓" : ""}
-                </th>
-              ))}
-            </tr>
-          ))}
-        </thead>
-        <tbody>
-          {table.getRowModel().rows.map(row => (
-            <tr key={row.id}>
-              {row.getVisibleCells().map(cell => (
-                <td key={cell.id}>
-                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
-                </td>
-              ))}
-            </tr>
-          ))}
-        </tbody>
-      </table>
-      <div>
-        <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>←</button>
-        <span>Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}</span>
-        <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>→</button>
-      </div>
-    </div>
-  );
-}
-```
-
-### ❌ DON'T: client sorting/pagination on large data
-```ts
-// ❌ Bad: loading everything, then sorting in the browser
-useQuery({ queryFn: () => fetchAllUsers() }); // 10k+ records in browser memory
-// ✅ manualSorting + manualPagination + server query with parameters
-```
-
----
-
-## 6. Virtual
-
-### ✅ DO: useVirtualizer for long lists
-```tsx
-import { useVirtualizer } from "@tanstack/react-virtual";
-
-function VirtualUsersList({ users }: { users: User[] }) {
-  const parentRef = useRef<HTMLDivElement>(null);
-
-  const virtualizer = useVirtualizer({
-    count:            users.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize:     () => 56,   // approximate row height in px
-    overscan:         5,          // rendering 5 rows outside the screen (smoothness)
-  });
-
-  return (
-    <div ref={parentRef} style={{ height: "600px", overflowY: "auto" }}>
-      {/* full height container — the browser draws the correct scrollbar */}
-      <div style={{ height: virtualizer.getTotalSize(), position: "relative" }}>
-        {virtualizer.getVirtualItems().map(vRow => (
-          <div
-            key={vRow.index}
-            style={{
-              position:  "absolute",
-              top:       vRow.start,
-              width:     "100%",
-              height:    vRow.size,
-            }}
-          >
-            <UserRow user={users[vRow.index]} />
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-### ✅ DO: dynamic row heights via measureElement
-```tsx
-const virtualizer = useVirtualizer({
-  count:            items.length,
-  getScrollElement: () => parentRef.current,
-  estimateSize:     () => 80,
-  measureElement:   el => el.getBoundingClientRect().height, // ✅ real height
-});
-
-// In row render:
-<div ref={virtualizer.measureElement} data-index={vRow.index}>
-  <VariableHeightRow item={items[vRow.index]} />
-</div>
-```
-
-### ✅ DO: table virtualization (combo Table + Virtual)
-```tsx
-// ✅ Getting rows from TanStack Table, virtualizing via Virtual
-const rows = table.getRowModel().rows;
-
-const rowVirtualizer = useVirtualizer({
-  count:            rows.length,
-  getScrollElement: () => tableContainerRef.current,
-  estimateSize:     () => 40,
-  overscan:         10,
-});
-
-// Rendering only visible rows:
-{rowVirtualizer.getVirtualItems().map(vRow => {
-  const row = rows[vRow.index];
-  return (
-    <tr key={row.id} style={{ height: vRow.size, transform: `translateY(${vRow.start}px)` }}>
-      {row.getVisibleCells().map(cell => (
-        <td key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</td>
-      ))}
-    </tr>
-  );
-})}
-```
-
-### Selection rule: pagination vs virtualization
-| Scenario | Solution |
-|---|---|
-| Table with navigation, SEO, page bookmarks | Server pagination |
-| Feed/list without a clear concept of "page" | Infinite scroll |
-| Dropdown with search, 1000+ options | Virtualization |
-| Table with 10k+ rows without pagination | Virtualization |
-| Mixed UX: table + scrolling to the end | Table + Virtual |
-
----
-
-## See also
-- `react-beast-practices` → virtualization (basic example)
-- `typescript-beast-practices` → typing generic queries
-- `dev-reference-snippets` → section 6 (basic useQuery/useMutation examples)

package/locales/en/.agents/skills/tanstack-beast-practices/agents/claude.json

@@ -1,18 +0,0 @@
-{
-  "name": "tanstack-beast-practices",
-  "display_name": "TanStack Beast Practices",
-  "description": "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked \"how to do X correctly with TanStack\".",
-  "default_prompt": "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill.",
-  "triggers": [
-    "tanstack-beast-practices",
-    "tanstack beast practices",
-    "TanStack (Query v5, Table v8, Virtual v3)"
-  ],
-  "capabilities": [
-    "tanstack",
-    "beast",
-    "practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/tanstack-beast-practices/agents/copilot.json

@@ -1,18 +0,0 @@
-{
-  "name": "tanstack-beast-practices",
-  "display_name": "TanStack Beast Practices",
-  "description": "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked \"how to do X correctly with TanStack\".",
-  "default_prompt": "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill.",
-  "triggers": [
-    "tanstack-beast-practices",
-    "tanstack beast practices",
-    "TanStack (Query v5, Table v8, Virtual v3)"
-  ],
-  "capabilities": [
-    "tanstack",
-    "beast",
-    "practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/tanstack-beast-practices/agents/gemini.json

@@ -1,18 +0,0 @@
-{
-  "name": "tanstack-beast-practices",
-  "display_name": "TanStack Beast Practices",
-  "description": "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked \"how to do X correctly with TanStack\".",
-  "default_prompt": "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill.",
-  "triggers": [
-    "tanstack-beast-practices",
-    "tanstack beast practices",
-    "TanStack (Query v5, Table v8, Virtual v3)"
-  ],
-  "capabilities": [
-    "tanstack",
-    "beast",
-    "practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/tanstack-beast-practices/agents/openai.yaml

@@ -1,8 +0,0 @@
-interface:
-  display_name: "TanStack Beast Practices"
-  short_description: "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll,…"
-  default_prompt: "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill."
-dependencies:
-  tools: []
-policy:
-  allow_implicit_invocation: true

package/locales/en/.agents/skills/tanstack-beast-practices/agents/qwen.json

@@ -1,18 +0,0 @@
-{
-  "name": "tanstack-beast-practices",
-  "display_name": "TanStack Beast Practices",
-  "description": "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked \"how to do X correctly with TanStack\".",
-  "default_prompt": "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill.",
-  "triggers": [
-    "tanstack-beast-practices",
-    "tanstack beast practices",
-    "TanStack (Query v5, Table v8, Virtual v3)"
-  ],
-  "capabilities": [
-    "tanstack",
-    "beast",
-    "practices"
-  ],
-  "tools": [],
-  "implicit_invocation": true
-}

package/locales/en/.agents/skills/tanstack-beast-practices/agents/skill.yaml

@@ -1,22 +0,0 @@
-version: 1
-name: "tanstack-beast-practices"
-display_name: "TanStack Beast Practices"
-description: "TanStack (Query v5, Table v8, Virtual v3): caching, invalidation, pagination, infinite scroll, server-side filters/sorting, virtualization of large lists. Use this skill for any work with TanStack Query, TanStack Table or TanStack Virtual — when writing the fetcher layer, configuring the cache, building tables with server-side pagination, virtual lists, and when asked \"how to do X correctly with TanStack\"."
-default_prompt: "Use $tanstack-beast-practices when the task matches the \"TanStack Beast Practices\" skill."
-triggers:
-  - "tanstack-beast-practices"
-  - "tanstack beast practices"
-  - "TanStack (Query v5, Table v8, Virtual v3)"
-capabilities:
-  - "tanstack"
-  - "beast"
-  - "practices"
-tools: []
-invocation:
-  explicit: true
-  implicit: true
-localization:
-  default_locale: "en"
-  available_locales:
-    - "ru"
-    - "en"